Integration scripts

Examples

Sync script

import type { GithubIssueDemo, NangoSync } from './models';

export default async function fetchData(nango: NangoSync) {
    // Fetch issues from GitHub.
    const res = await nango.get({
        endpoint: '/repos/NangoHQ/interactive-demo/issues?labels=demo&sort=created&direction=asc'
    });

    // Map issues to your preferred schema.
    const issues: GithubIssueDemo[] = res.data.map(({ id, title, html_url }: any) => {
        return { id, title, url: html_url };
    });

    // Persist issues to the Nango cache.
    await nango.batchSave(issues, 'GithubIssueDemo');
}

Read more about integration scripts to understand what role they play in Nango.

Integration scripts expose a helper object (NangoSync for sync scripts, NangoAction for action scripts), which allows to interact with external APIs & Nango more easily.

HTTP requests

Makes an HTTP request inside an integration script:

const config = { endpoint: '/some-endpoint' };

await nango.get(config); // GET request
await nango.post(config); // POST request
await nango.put(config); // PUT request
await nango.patch(config); // PATCH request
await nango.delete(config); // DELETE request

Note that all HTTP requests benefit from automatic credential injection. Because scripts are executed in the context of a specific integration & connection, Nango can automatically retrieve & refresh the relevant API credentials.

Parameters

Show child attributes

config · object · required

Hide config

endpoint · string · required

The endpoint of the request.

headers · Record<string, string>

The headers of the request.

params · Record<string, string | number>

The query parameters of the request.

data · unknown

The body of the request.

retries · number

The number of retries in case of failure (with exponential back-off). Optional, default 0.

retryOn · number[]

Array of additional status codes to retry a request in addition to the 5xx, 429, ECONNRESET, ETIMEDOUT, and ECONNABORTED

baseUrlOverride · string

The API base URL. Can be ommitted if the base URL is configured for this API in the providers.yaml.

decompress · boolean

Override the decompress option when making requests. Optional, defaults to false

responseType · 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream'

The type of the response.

Response

Show child attributes

    {
        data: {}, // the response provided by the server
        status: 200, // the HTTP status code
        headers: {}, // the HTTP headers
        config: {}, // the config provided for the request
        request: {} // the request that generated this response
    }

The response object is an Axios response.

Logging

You can collect logs in integration scripts. This is particularly useful when:

• developing, to debug your integration scripts
• in production, to collect information about integration script executions & understand issues

Collect logs in integration scripts as follows:

await nango.log("This is a log.");

Logs can be viewed & searched in the Nango UI. We plan to make them exportable in the future as well.

Environment variables

Integration scripts sometimes need to access sensitive variables that should not be revealed directly in the code.

For this, you can define environment variables in the Nango UI, in the Environment Settings tab. Then you can retrieve these environment variables from integration scripts with:

await nango.getEnvironmentVariables();

Parameters

No parameters.

Response

Show child attributes

[
    {
        "name": "MY_SECRET_KEY",
        "value": "SK_373892NSHFNCOWFO..."
    }
]

Trigger action

Integration scripts currently do not support importing files, which limits the ability to share code between integration scripts.

As a temporary workaround, you can call action scripts from other integration scripts with:

await nango.triggerAction('<ACTION-NAME>', { 'custom_key1': 'custom_value1' });

Parameters

Show child attributes

actionName · string · required

The name of the action to trigger.

input · unkown · required

The necessary input for your action’s runAction function.

Response

Show child attributes

{
    "your-properties": "The data returned by the action"
}

Paginate through API responses

Follow the pagination step-by-step guides to learn how to paginate through API responses easily.

Manage connection metadata

Get connection metadata

Returns the connection’s metadata.

await nango.getMetadata();

Better, you can specify the type of the metadata;

interface CustomMetadata {
    anyKey: Record<string, string>;
}
const myTypedMetadata = await nango.getMetadata<CustomMetadata>();

Parameters

No parameters.

Example Response

Show child attributes

{
    "custom_key1": "custom_value1"
}

Set connection metadata

Set custom metadata for the connection (overrides existing metadata).

await nango.setMetadata({ 'CUSTOM_KEY1': 'CUSTOM_VALUE1' });

Parameters

Show child attributes

metadata · Record<string, any> · required

The custom metadata to store in the connection.

Response

Empty response.

Edit connection metadata

Edit custom metadata for the connection. Only overrides & adds specified properties, not the entire metadata.

await nango.updateMetadata({ 'CUSTOM_KEY1': 'CUSTOM_VALUE1' });

Parameters

Show child attributes

metadata · Record<string, any> · required

The custom metadata to store in the connection.

Response

Empty response.

Get the connection credentials

Returns a specific connection with credentials.

await nango.getConnection();

The response content depends on the API authentication type (OAuth 2, OAuth 1, API key, Basic auth, etc.).

When you fetch the connection with this API endpoint, Nango will check if the access token has expired. If it has, it will refresh it.

We recommend not caching tokens for longer than 5 minutes to ensure they are fresh.

Parameters

Show child attributes

forceRefresh · boolean

Defaults to false. If false, the token will only be refreshed if it expires within 15 minutes. If true, a token refresh attempt will happen on each request. This is only useful for testing and should not be done at high traffic.

refreshToken · boolean

Defaults to false. If false, the refresh token is not included in the response, otherwise it is. In production, it is not advised to return the refresh token, for security reasons, since only the access token is needed to sign requests.

Example Response

Show child attributes

{
    "id": 18393,                                 
    "created_at": "2023-03-08T09:43:03.725Z",     
    "updated_at": "2023-03-08T09:43:03.725Z",     
    "provider_config_key": "github",              
    "connection_id": "1",                         
    "credentials": {
        "type": "OAUTH2",                         
        "access_token": "gho_tsXLG73f....",       
        "refresh_token": "gho_fjofu84u9....",     
        "expires_at": "2024-03-08T09:43:03.725Z", 
        "raw": { // Raw token response from the OAuth provider: Contents vary!
            "access_token": "gho_tsXLG73f....",
            "refresh_token": "gho_fjofu84u9....",
            "token_type": "bearer",
            "scope": "public_repo,user"
        }
    },
    "connection_config": {                       
        "subdomain": "myshop",
        "realmId": "XXXXX",
        "instance_id": "YYYYYYY"
    },                      
    "account_id": 0,                              
    "metadata": {                                 
        "myProperty": "yes",
        "filter": "closed=true"
    }
}                              

Sync-specific helper methods

Sync scripts persist data updates to the Nango cache, which your app later fetches (cf. step-by-step guide).

Save records

Upserts records to the Nango cache (i.e. create new records, update existing ones). Each record needs to contain a unique id field used to dedupe records.

const githubIssues: GitHubIssue[] = ...; // Fetch issues from GitHub API. 

await nango.batchSave(githubIssues, 'GitHubIssue');

Parameters

Show child attributes

recordList · Model[] · required

The list of records to persist.

modelType · string · required

The model type of the records to persist.

Delete records

Marks records as deleted in the Nango cache. Deleted records are still returned when you fetch them, but they are marked as deleted in the record’s metadata (i.e. soft delete).

The only field that needs to be present in each record when calling batchDelete is the unique id; the other fields are ignored.

const githubIssuesToDelete: { id: string }[] = ...; // Fetch issues to delete from GitHub API. 

await nango.batchDelete(githubIssuesToDelete, 'GitHubIssue');

Parameters

Show child attributes

recordList · { id: string }[] · required

The list of records to delete.

modelType · string · required

The model type of the records to delete.

Action-specific helper methods

ActionError

You can use ActionError in an action script to return a descriptive error to your app when needed:

export default async function runAction(nango: NangoAction): Promise<Response> {
    // Something went wrong...

    throw new ActionError({ any_key: 'any_value' });
}

In this case, the response to the trigger action call will be:

{
  "error_type": "action_script_failure",
  "payload": {
    "any_key": "any_value"
  }
}

Questions, problems, feedback? Please reach out in the Slack community.