### Example Build and Start Script Source: https://docs.pandium.com/getting-started/pandium-integration-tutorial/pokemon-of-the-day-part-1/write-the-integration-in-typescript/add-the-pokemonsync-flow Command to build the project and start the Pokemon of the Day integration. This will trigger the logic to fetch and post a new Pokemon. ```bash npm run build && npm run start ``` -------------------------------- ### Example Build and Run Logs Source: https://docs.pandium.com/getting-started/pandium-integration-tutorial/pokemon-of-the-day-part-2/add-dynamic-configs Expected output format when running the build and start scripts, showing the standard out object containing Slack user options. ```text > pokemon-of-the-day@1.0.0 start > node build/src/ This run is in mode: init ------------------------CONFIG------------------------ Config {} ------------------------CONTEXT------------------------ Context { run_mode: 'init', last_successful_run_std_out: '{"last_pokemon_id":247}' } ------------------------INIT SYNC------------------------ {"slack_users":[{"const":"UCEGPFQRX","title":"Jeff"},{"const":"UCEMD4QCX","title":"Juanita"},... other Slack users fetched from your Slack workspace.]} ``` -------------------------------- ### Example output of the Pokémon client execution Source: https://docs.pandium.com/getting-started/pandium-integration-tutorial/pokemon-of-the-day-part-1/write-the-integration-in-typescript/add-the-pokemon-client Shows the expected console output after running the build and start commands, including the fetched Pokémon object. ```text > pokemon-of-the-day@1.0.0 start > node build/src/ This run is in mode: normal ------------------------CONFIG------------------------ Config {} ------------------------CONTEXT------------------------ Context { run_mode: 'normal' } { abilities: [ { ability: [Object], is_hidden: false, slot: 1 }, { ability: [Object], is_hidden: true, slot: 3 } ], ... further properties of the Pokémon Tyranitar } ``` -------------------------------- ### Import ShipBob Client Source: https://docs.pandium.com/getting-started/pandium-integration-development-kit-idk/pandium-clients Example of importing the ShipBob client. Ensure the '@pandium/shipbob-client' package is installed. ```javascript import ShipbobClient from '@pandium/shipbob-client' ``` -------------------------------- ### Expected Build and Start Logs Source: https://docs.pandium.com/getting-started/pandium-integration-tutorial/pokemon-of-the-day-part-1/write-the-integration-in-typescript/add-the-pokemonsync-flow Sample output from running the build and start commands, showing the integration's operational status and the Pokemon synchronization details. ```log > pokemon-of-the-day@1.0.0 start > node build/src/ This run is in mode: normal ------------------------CONFIG------------------------ Config {} ------------------------CONTEXT------------------------ Context { run_mode: 'normal', last_successful_run_std_out: '{"last_pokemon_id":247}' } ------------------------POKEMON SYNC------------------------ {"last_pokemon_id":248} ``` -------------------------------- ### Run Trigger JSON Examples Source: https://docs.pandium.com/getting-started/anatomy-of-an-integration/run-triggers Example JSON structures for different trigger modes available in the integration context. ```json { "id": "4731234254284123", "source": "webhook", "payload": { "file": "sample/test_file.txt", "headers": { "User-Agent": "PostmanRuntime/7.29.0" } }, "created_date": "2023-01-27T23:27:07Z", "mode": "webhook" } ``` ```json { "id": "12345678", "source": "api", "payload": { "file": "sample/test_file.txt", "headers": { "User-Agent": "PostmanRuntime/7.29.0" } }, "created_date": "2023-06-06T10:11:50-04:00", "mode": "normal" } ``` ```json { "id": "12345678", "source": "manual", "created_date": "2023-06-06T10:11:50-04:00", "mode": "init" } ``` ```json { "id": "example_id", "source": "cron", "created_date": "2023-06-06T10:11:50-04:00", "mode": "normal" } ``` -------------------------------- ### Auth Installation URL Source: https://docs.pandium.com/marketplaces/listing-in-external-marketplaces/bigcommerce-marketplace The Auth Installation URL initiates the OAuth connection flow when users install your app from the BigCommerce marketplace. Replace `` and `` with your specific values. ```APIDOC ## Auth Installation URL ### Description Initiates the OAuth connection flow for app installation. ### Method GET ### Endpoint **Sandbox Environment:** `https://exmart.sandbox.pandium.com/v1/bigcommerce/auth//` **Production Environment:** `https://exmart.pandium.io/v1/bigcommerce/auth//` ### Parameters #### Path Parameters - **account_name** (string) - Required - The name of your Pandium account. - **integration_name** (string) - Required - The name of your integration. ``` -------------------------------- ### Pandium CLI Installation Source: https://docs.pandium.com/getting-started/pandium-integration-development-kit-idk/pandium-cli Instructions on how to install the Pandium CLI. The installation command is available through the Pandium Admin Dashboard. ```APIDOC ## Pandium CLI Installation To install the Pandium CLI, follow these steps: 1. Log into the Pandium Admin Dashboard. 2. Navigate to **Settings > Developer Resources**. 3. Copy the command for your system (e.g., MacOS aarch64 (Apple Silicon)). 4. Paste the command into your terminal and press Enter. *Note: If a command for your platform is not listed, please contact support.* ``` -------------------------------- ### Example .env file structure Source: https://docs.pandium.com/getting-started/pandium-integration-tutorial/pokemon-of-the-day-part-1/write-the-integration-in-typescript/add-the-.env A .env file should be placed in the root folder of your integration project. ```text ├── build ├── node_modules ├── src │ ├── index.ts │ └── lib.ts ├── .env ├── package.json ├── PANDIUM.yaml └── tsconfig.json ``` -------------------------------- ### Verify .env configuration with npm start Source: https://docs.pandium.com/getting-started/pandium-integration-tutorial/pokemon-of-the-day-part-1/write-the-integration-in-typescript/add-the-.env After building and starting your integration, check the console output to confirm that environment variables from your .env file, such as the Slack token and run mode, are being read correctly. This output shows the structure of the logged data. ```bash > pokemon-of-the-day@1.0.0 start > node build/src/ This run is in mode: normal ------------------------CONFIG------------------------ Config {} ------------------------SECRET------------------------ Secret { slack_oauth_access_token: 'xoxb-...' } ------------------------CONTEXT------------------------ Context { run_mode: 'normal' } ------------------------ENV---------------------------- {...} ``` -------------------------------- ### Slack User List Output Example Source: https://docs.pandium.com/getting-started/pandium-integration-tutorial/pokemon-of-the-day-part-1/write-the-integration-in-typescript/add-the-slack-client This is an example of the output you can expect when fetching a list of users from your Slack workspace using the `users.list` method. The actual output will contain users specific to your workspace. ```json [ { id: 'USLACKBOT', team_id: 'TCF1SSXMJ', name: 'slackbot', deleted: false, color: '757575', real_name: 'Slackbot', tz: 'America/Los_Angeles', tz_label: 'Pacific Standard Time', tz_offset: -28800, profile: { title: '', phone: '', skype: '', real_name: 'Slackbot', real_name_normalized: 'Slackbot', display_name: 'Slackbot', display_name_normalized: 'Slackbot', fields: {}, status_text: '', status_emoji: '', status_emoji_display_info: [], status_expiration: 0, avatar_hash: 'sv41d8cd98f0', always_active: true, first_name: 'slackbot', last_name: '', image_24: 'https://a.slack-edge.com/80588/img/slackbot_24.png', image_32: 'https://a.slack-edge.com/80588/img/slackbot_32.png', image_48: 'https://a.slack-edge.com/80588/img/slackbot_48.png', image_72: 'https://a.slack-edge.com/80588/img/slackbot_72.png', image_192: 'https://a.slack-edge.com/80588/marketing/img/avatars/slackbot/avatar-slackbot.png', image_512: 'https://a.slack-edge.com/80588/img/slackbot_512.png', status_text_canonical: '', team: 'TCF1SSXMJ' }, is_admin: false, is_owner: false, is_primary_owner: false, is_restricted: false, is_ultra_restricted: false, is_bot: false, is_app_user: false, updated: 0, is_email_confirmed: false, who_can_share_contact_card: 'EVERYONE' }, ... ] ``` -------------------------------- ### OAuth Installation URL - Landing URL Query Parameter Source: https://docs.pandium.com/marketplaces/listing-in-external-marketplaces/klaviyo-marketplace Include the 'landing_url' parameter to specify the user's redirection destination after installation. Pandium will append additional parameters for tenant linking. ```bash ?landing_url= ``` -------------------------------- ### BigCommerce Auth Installation URL (Production) Source: https://docs.pandium.com/marketplaces/listing-in-external-marketplaces/bigcommerce-marketplace Use this URL to initiate the OAuth connection flow when users install your app from the BigCommerce marketplace in a production environment. Replace and with your specific values. ```url https://exmart.pandium.io/v1/bigcommerce/auth// ``` -------------------------------- ### Define Parent Selector Options Source: https://docs.pandium.com/getting-started/anatomy-of-an-integration/pandium.yaml-spec/dependent-selector-configurations Example outputs for parent selector options in an init sync. ```python food_type_options = [ {'const': 1, 'title': 'Fruits'}, {'const': 2, 'title': 'Veggies'}, ] ``` ```python food_type_options = [ {'const': 3, 'title': 'Sweet'}, {'const': 4, 'title': 'Savory'}, ] ``` -------------------------------- ### BigCommerce Auth Installation URL (Sandbox) Source: https://docs.pandium.com/marketplaces/listing-in-external-marketplaces/bigcommerce-marketplace Use this URL to initiate the OAuth connection flow when users install your app from the BigCommerce marketplace in a sandbox environment. Replace and with your specific values. ```url https://exmart.sandbox.pandium.com/v1/bigcommerce/auth// ``` -------------------------------- ### Configure App URL Source: https://docs.pandium.com/marketplaces/listing-in-external-marketplaces/wix-marketplace Used for the 'Install' page in the Wix Marketplace to initiate the OAuth flow. ```text https://exmart.pandium.io/v1/wix/auth// ``` -------------------------------- ### PANDIUM.yaml Configuration Example Source: https://docs.pandium.com/getting-started/anatomy-of-an-integration/pandium.yaml-spec This example demonstrates a PANDIUM.yaml file with static configurations for S3 bucket name, file name, and boolean flags for creating contacts and companies. It includes schema definitions for data types and UI schema for controlling display labels and types. ```yaml version: 0.4 base: python:3.7 # Node, Ruby, PHP, Java, GO build: pipenv install run: pipenv run python -m hubspot2s3 configs: schema: properties: s3_bucket_name: type: string s3_file_name: type: string make_contact: type: boolean default: true make_company: type: boolean type: object uischema: elements: - label: S3 Bucket Name scope: '#/properties/s3_bucket_name' type: Control - label: S3 File Name scope: '#/properties/s3_file_name' type: Control - label: Make Contact? scope: '#/properties/make_contact' type: Control admin: true - label: Make Company? scope: '#/properties/make_company' type: Control type: VerticalLayout ``` -------------------------------- ### Pandium CLI Usage - Help Source: https://docs.pandium.com/getting-started/pandium-integration-development-kit-idk/pandium-cli Get a list of all available commands or help for a specific command. ```APIDOC ## Usage - Help ### Get all available commands: ```bash pandium help ``` ### Get help for a specific command: ```bash pandium help [COMMAND] ``` **Example Output:** ``` Usage:pandium login [environment] pandium logout pandium get integrations [integration_id] pandium get tenants [OPTIONS] [tenant_id] pandium get help [COMMAND] pandium local build pandium local run [OPTIONS] pandium local help [COMMAND] pandium help [COMMAND] Options: -h, --help Print help -V, --version Print version pandium login: Log in to Pandium! Takes environment name as an option, defaults to sandbox -h, --help Print help [environment] [default: sandbox] [possible values: sandbox, sandbox-eu, demo] pandium logout: End your Pandium session -h, --help Print help pandium get: Get internal integrations or their tenants -h, --help Print help pandium get integrations: See a list of all your internal integrations -h, --help Print help [integration_id] pandium get tenants: See a list of tenant associated with the provided integration id -i, --integration-id --include-active-secrets -h, --help Print help [tenant_id] pandium get help: Print this message or the help of the given subcommand(s) pandium local: Execute commands from your local PANDIUM file (PANDIUM.yaml, PANDIUM.json, or PANDIUM.toml) -h, --help Print help pandium local build: Execute the 'build' command in your PANDIUM.yaml -h, --help Print help pandium local run: Run the integration found in the current folder using the env values from the provided tenant id. Local .env file will override any values saved in pandium -m, --mode Optionally specify a run mode. Defaults to 'normal' [default: normal] [possible values: init, normal] -h, --help Print help pandium local help: Print this message or the help of the given subcommand(s) pandium help: Print this message or the help of the given subcommand(s) [COMMAND]... Print help for the subcommand(s) ``` ``` -------------------------------- ### OAuth Installation URL - Production Environment Source: https://docs.pandium.com/marketplaces/listing-in-external-marketplaces/klaviyo-marketplace Use this base URL format for initiating the OAuth connection flow in a production environment. Replace placeholders with your specific account and integration names. ```bash https://exmart.pandium.io/v1/connect// ``` -------------------------------- ### JWT Payload Example Source: https://docs.pandium.com/marketplaces/integration-onboarding-experiences-overview/embedding-the-marketplace An example of the JSON payload structure containing user information and metadata. ```javascript { "iat": 1621521641, "jti": "1cfa7dbf-8110-4237-ad22-410608791b7d", "ti": { "udn": "Pandium Test", "ufn": "Important Person", "uem": "test@pandium.com", "ili": [ "new-id", "something-different" ], "aid": "", "adn": "", "xti": { "extraProp": "extra value", "extraList": [ "bla", "listVal" ] } }, "sub": "test-pandium-com" } ``` -------------------------------- ### OAuth Installation URL - Sandbox Environment Source: https://docs.pandium.com/marketplaces/listing-in-external-marketplaces/klaviyo-marketplace Use this base URL format for initiating the OAuth connection flow in a sandbox environment. Replace placeholders with your specific account and integration names. ```bash https://exmart.sandbox.pandium.io/v1/connect// ``` -------------------------------- ### Example stdout output for dynamic configs Source: https://docs.pandium.com/getting-started/anatomy-of-an-integration/pandium.yaml-spec/dynamic-configurations The expected format for the final line of stdout printed during an init sync to populate the UI. ```log [OUT] {"audiences":["Friends","Family","Acquaintances"],"lists":[{"title":"Prospective Customers","const":1},{"title":"One Time Customers","const":2},{"title":"Loyal Customers","const":3}]} ``` -------------------------------- ### Complete JWT Example Source: https://docs.pandium.com/marketplaces/customizing-the-jwt A full example of a JWT, showing the encoded header, payload, and signature separated by dots. ```APIDOC ## Complete JWT Example ### Description A full example of a JWT, showing the encoded header, payload, and signature separated by dots. ### Response Example ``` eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 .eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ .SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c ``` ``` -------------------------------- ### Define Dynamic Configuration Options with oneOf Source: https://docs.pandium.com/getting-started/anatomy-of-an-integration/pandium.yaml-spec/dynamic-configurations This example shows how to define dynamic configuration options using the 'oneOf' type in the schema definitions, with a placeholder for tenant-specific values fetched during an init sync. ```yaml properties: klaviyo_list: $ref: '#/definitions/lists default: INFO type: string definitions: lists: oneOf: - const: placeholder Title: Placeholder ``` -------------------------------- ### Get Pandium Integrations Source: https://docs.pandium.com/getting-started/pandium-integration-development-kit-idk/pandium-cli Retrieve a list of all your internal integrations. You can optionally specify an integration ID to get details for a specific integration. ```bash pandium get integrations [integration_id] ``` -------------------------------- ### Configure Shopify App Installation URLs Source: https://docs.pandium.com/marketplaces/listing-in-external-marketplaces/shopify-marketplace Use these base URLs in the Shopify Dev Portal to initiate the connection flow. Replace placeholders with your specific account and integration names. ```text https://exmart.sandbox.pandium.com/v1/shopify/auth// ``` ```text https://exmart.pandium.io/v1/shopify/auth// ``` -------------------------------- ### Populate dynamic configs via init sync Source: https://docs.pandium.com/getting-started/anatomy-of-an-integration/pandium.yaml-spec/dynamic-configurations Use this logic within your integration script to detect the 'init' run mode and output configuration options to stdout. ```javascript if (pandium.context.runMode === 'init') { const mcAudiences = await mcClient.getMany('audience'); const kLists = await kClient.getMany('audience'); const stdout = { // If a key in the standard out matches one of the PANDIUM.yaml's configs.schema.definitions its values will populate the dropdown for configs that reference that definition. 'audiences': mcAudiences.map(({ name }) => name) 'lists': kLists.map((list) => {const: list.id, title: list.name}) }; // Print json string to stdout and end the script. console.log(JSON.stringify(stdout)); return } ``` -------------------------------- ### Get Tenant Metadata OpenAPI Spec Source: https://docs.pandium.com/reference/pandium-api This OpenAPI specification defines the GET endpoint for retrieving metadata for a specific tenant. It includes parameters for tenant ID and responses for success, not found, and validation errors. ```json {"openapi":"3.1.0","info":{"title":"FastAPI","version":"0.1.0"},"paths":{"/v2/tenants/{tenant_id}/metadata":{"get":{"summary":"Get Metadata","description":"Get the metadata for a tenant.","operationId":"get_metadata_v2_tenants__tenant_id__metadata_get","parameters":[{"name":"tenant_id","in":"path","required":true,"schema":{"type":"integer","description":"Unique identifier for a tenant","title":"Tenant Id"},"description":"Unique identifier for a tenant"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantMetadata"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}},"description":"Not Found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"TenantMetadata":{"properties":{"tenant_id":{"type":"integer","title":"Tenant Id"},"data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Data","default":{}},"created_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created Date"},"modified_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Modified Date"}},"type":"object","required":["tenant_id"],"title":"TenantMetadata"},"ErrorMessage":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"ErrorMessage"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` -------------------------------- ### GET /v2/integrations Source: https://docs.pandium.com/reference/pandium-api Retrieves a list of all integrations. ```APIDOC ## GET /v2/integrations ### Description Retrieves a list of all integrations available in your Pandium account. ### Method GET ### Endpoint /v2/integrations ### Parameters #### Query Parameters - **limit** (integer) - Optional - The maximum number of integrations to return. - **offset** (integer) - Optional - The number of integrations to skip before starting to collect the result set. ### Request Example ``` curl -X GET \ 'https://api.pandium.io/v2/integrations?limit=10&offset=0' \ -H 'X-API-KEY: ' ``` ### Response #### Success Response (200) - **integrations** (array) - A list of integration objects. - **id** (string) - The unique identifier for the integration. - **name** (string) - The name of the integration. - **description** (string) - A description of the integration. #### Response Example ```json { "integrations": [ { "id": "integration_123", "name": "Salesforce Connector", "description": "Syncs data between Pandium and Salesforce." } ] } ``` ``` -------------------------------- ### Configuring Environment Variables Source: https://docs.pandium.com/getting-started/pandium-integration-tutorial/pokemon-of-the-day-part-1/write-the-integration-in-typescript/add-the-pokemonsync-flow Example of setting the standard output context variable in a .env file to track the last processed Pokémon ID. ```properties PAN_CTX_LAST_SUCCESSFUL_RUN_STD_OUT= '{"last_pokemon_id":247}' ``` -------------------------------- ### OAuth Installation URL - Connector Query Parameters Source: https://docs.pandium.com/marketplaces/listing-in-external-marketplaces/klaviyo-marketplace Append connector parameters to specify which services to link and in what order. Multiple 'connector' parameters enable sequential service connections. ```bash ?connector=magento&connector=Klaviyo ``` -------------------------------- ### GET /v2/tenants Source: https://docs.pandium.com/reference/pandium-api Retrieves a list of all tenants associated with the integration. ```APIDOC ## GET /v2/tenants ### Description Retrieves a list of all tenants associated with the integration. ### Method GET ### Endpoint /v2/tenants ``` -------------------------------- ### GET /v2/integrations/{integration_id} Source: https://docs.pandium.com/reference/pandium-api Retrieves details for a specific integration. ```APIDOC ## GET /v2/integrations/{integration_id} ### Description Retrieves detailed information about a specific integration using its ID. ### Method GET ### Endpoint /v2/integrations/{integration_id} ### Parameters #### Path Parameters - **integration_id** (string) - Required - The unique identifier of the integration. ### Request Example ``` curl -X GET \ 'https://api.pandium.io/v2/integrations/integration_123' \ -H 'X-API-KEY: ' ``` ### Response #### Success Response (200) - **id** (string) - The unique identifier for the integration. - **name** (string) - The name of the integration. - **description** (string) - A description of the integration. - **created_at** (string) - The timestamp when the integration was created. - **updated_at** (string) - The timestamp when the integration was last updated. #### Response Example ```json { "id": "integration_123", "name": "Salesforce Connector", "description": "Syncs data between Pandium and Salesforce.", "created_at": "2023-01-01T10:00:00Z", "updated_at": "2023-01-01T10:00:00Z" } ``` ``` -------------------------------- ### Display Pandium CLI Help Source: https://docs.pandium.com/getting-started/pandium-integration-development-kit-idk/pandium-cli Run this command to see a list of all available commands and their usage. ```bash pandium help ``` -------------------------------- ### Define Dynamic Configuration Options with Placeholder Source: https://docs.pandium.com/getting-started/anatomy-of-an-integration/pandium.yaml-spec/dynamic-configurations For dynamic configurations, specify a placeholder in the schema's definitions. The actual options will be fetched during an init sync and can differ per tenant. ```yaml properties: mailchimp_audience: $ref: '#/definitions/audiences' default: INFO type: string definitions: audiences: enum: - placeholder ``` -------------------------------- ### GET /v2/tenants/{tenant_id}/metadata Source: https://docs.pandium.com/reference/pandium-api Retrieves the metadata for a specific tenant. ```APIDOC ## GET /v2/tenants/{tenant_id}/metadata ### Description Get the metadata for a tenant. ### Method GET ### Endpoint /v2/tenants/{tenant_id}/metadata ### Parameters #### Path Parameters - **tenant_id** (integer) - Required - Unique identifier for a tenant ### Response #### Success Response (200) - **tenant_id** (integer) - Unique identifier for a tenant - **data** (object) - Metadata content - **created_date** (string) - Creation timestamp - **modified_date** (string) - Last modification timestamp #### Response Example { "tenant_id": 123, "data": {}, "created_date": "2023-01-01T00:00:00Z", "modified_date": "2023-01-01T00:00:00Z" } ``` -------------------------------- ### Settings URL - Explicit Tenant List Page Source: https://docs.pandium.com/marketplaces/listing-in-external-marketplaces/klaviyo-marketplace Use 'display=list' to explicitly navigate to the tenant list page for your integration. ```bash https://gwtech.io.pandium.com/integrations?integration_id=1121?display=list ```