​

Examples

• Sync script
• Action 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

Parameters

Response

    {
        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
    }

​

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

[
    {
        "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

Response

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

​

Paginate through API responses

TbD

​

Get Integration

Returns the current integration information

await nango.getIntegration();

With credentials

await nango.getIntegration({ include: ['credentials'] });

Parameters

See GET /integrations/{uniqueKey} query parameters: documentation

Response

See GET /integrations/{uniqueKey} response: documentation

​

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

{
    "custom_key1": "custom_value1"
}

​

Set connection metadata

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

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

Parameters

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

Response

Empty response.

​

Get the connection credentials

Returns a specific connection with credentials.

await nango.getConnection();

Parameters

Example Response

{
    "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

​

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

​

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"
  }
}

​

Relative imports in scripts

You can import relative files into your scripts to allow for code abstraction and to maintain DRY (Don’t Repeat Yourself) principles. This means you can reuse code across different scripts by importing it. The imported file must live in the nango-integrations directory and can be imported in the following way:

import type { GithubIssueDemo, NangoSync } from '../../models';
import { issueMapper } from '../mappers/issue-mappper';

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'
    });

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

Note that you cannot import third-party modules at this time. Additionally, if there is a compilation error in an imported file, the entry point file will also fail to compile.

​

Pre-included Dependencies

Some libraries are pre-included for usage in scripts:

• zod
• crypto / node:crypto
• url / node:url

Please reach out in the community if you would like to request additional ones.