Functions SDK

ExamplesCopy Anchor Link

import { createSync } from 'nango';

const githubIssueDemoSchema = z.object({ ... });
type GithubIssueDemo = z.infer<typeof githubIssueDemoSchema>;

export default createSync({
  description: `Fetches the Github issues from all a user's repositories.`,
  version: '1.0.0',
  frequency: 'every hour',
  autoStart: true,
  metadata: z.void(),
  models: {
    GithubIssueDemo: githubIssueDemoSchema
  },

  exec: async (nango) => {
    // Mark the start of deletion tracking
    await nango.trackDeletesStart('GithubIssueDemo');

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

    // Detect and mark deleted records
    await nango.trackDeletesEnd('GithubIssueDemo');
  },
});

Read more about integration functions to understand what role they play in Tenklo.

ConfigurationCopy Anchor Link

createSyncCopy Anchor Link

frequency: 'every 1 minute',
frequency: 'every hour',
frequency: 'every 2 days'
frequency: 'every 3 week'

models: {
    GithubIssue: z.object({
        id: z.string(),
    }),
},

checkpoint: z.object({
    cursor: z.string(),
}),

metadata: z.object({
    userId: z.string(),
});

scopes: ['read:user', 'write:user'],

webhookSubscriptions: ['*'],

createActionCopy Anchor Link

input: z.object({
    title: z.string(),
});

output: z.object({
    issueId: z.string(),
});

metadata: z.object({
    userId: z.string(),
});

scopes: ['read:user', 'write:user'],

createOnEventCopy Anchor Link

metadata: z.object({
    userId: z.string(),
});

HTTP requestsCopy Anchor Link

Makes an HTTP request inside an integration function:

import type { ProxyConfiguration } from 'nango';

const config: ProxyConfiguration = { 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
    }

HTTP request retriesCopy Anchor Link

Configure behavior with two optional fields on your HTTP request config: retries and retryOn.

When a failed request is retriedCopy Anchor Link

Tenklo retries only when the failure looks transient. Exact rules depend on the integration:

If nothing in the table applies, the error is not retried.

BackoffCopy Anchor Link

Between retry attempts Tenklo waits with exponential backoff: first wait 3000ms, then each wait doubles, capped at 10 minutes.

Uncontrolled fetchCopy Anchor Link

nango.uncontrolledFetch() sends a request without injecting the connection's credentials and without retries. Use it for a host that is not the current integration.

const response = await nango.uncontrolledFetch({
    url: new URL('https://sandbox.example.com/upload'),
    method: 'POST',
    headers: { 'content-type': 'application/octet-stream' },
    body: fileContents,
    redirect: 'error'
});

Parameters

The response is a Fetch Response.

LoggingCopy Anchor Link

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

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

Collect logs in integration functions as follows:

await nango.log("This is a log."); // default log level is 'info'
await nango.log("This is an info log", { level: 'info' });
await nango.log("This is a warning", { level: 'warn' });
await nango.log("This is an error", { level: 'error' });

Log LevelsCopy Anchor Link

Tenklo supports the following log levels (from most to least verbose): debug, info, warn, error, off.

Only logs with a level greater than or equal to the configured logger level will surfaced in the Tenklo UI Logs tab. For example, if the logger level is set to warn, only warn and error logs will be shown.

Default log levels:

• All cloud environments: warn (only warnings and errors are logged by default)
• CLI dry-run: debug (all logs are shown in the console)

Configuring Log LevelCopy Anchor Link

You can override the default log level in two ways:

1. Environment variable: Set NANGO_LOGGER_LEVEL in your environment settings (values: debug, info, warn, error, off). It will apply to all your functions running in this environment and can be overridden in functions by using nango.setLogger(...)

2. In your function code:

nango.setLogger({ level: 'debug' }); // All logs will show in your cloud environments. It will apply to all `nango.log()` following this statement.
nango.setLogger({ level: 'off' }); // No logs will show

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

You can monitor your usage of custom logs in the billing tab of your Tenklo dashboard.

Environment variablesCopy Anchor Link

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

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

await nango.getEnvironmentVariables();

Parameters

No parameters.

Response

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

Trigger actionCopy Anchor Link

You can call action functions from other integration functions with:

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

Parameters

Response

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

Paginate through API responsesCopy Anchor Link

Tenklo provides a helper to automatically paginate endpoint responses.

Similar to HTTP requests, the nango.paginate() method takes in a ProxyConfiguration parameter.

Use the paginate field to of the ProxyConfiguration to specify how the endpoint's pagination work. Here's an example for a Jira endpoint:

const config: ProxyConfiguration = {
    // https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-search-get
    endpoint: `/ex/jira/${cloud.cloudId}/rest/api/3/project/search`,
    params: {
        properties: properties
    },
    paginate: {
        type: 'offset',
        offset_name_in_request: 'startAt',
        response_path: 'values',
        limit_name_in_request: 'maxResults',
        limit: 50,
        on_page: async ({ nextPageParam, response }) => {
            await nango.log(`Next offset value = ${nextPageParam}`);
            await nango.log(`Fetched ${response.data.total} records`);
        },
    },
    headers: {
        'X-Atlassian-Token': 'no-check'
    },
    retries: 10
};

for await (const projects of nango.paginate<JiraProjectResponse>(config)) {
    const projectsToSave = toProjects(projects, cloud.baseUrl);
    await nango.batchSave(projectsToSave, 'Project');
}

As shown in the example above, use a for loop to iterate through the paginated results.

The pagination helper supports 3 types of pagination: cursor, link or offset with the following settings:

Get IntegrationCopy Anchor Link

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 metadataCopy Anchor Link

Get connection metadataCopy Anchor Link

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 metadataCopy Anchor Link

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

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

Parameters

Response

Empty response.

Edit connection metadataCopy Anchor Link

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 credentialsCopy Anchor Link

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 methodsCopy Anchor Link

Sync functions persist data updates to the Tenklo cache, which your app later fetches. See the sync functions section.

CheckpointsCopy Anchor Link

Checkpoints allow syncs to save their progress and resume from where they left off. This is useful for:

• Resuming after failures without re-fetching all data
• Tracking pagination state across sync runs
• Storing custom cursor/offset values

To use checkpoints, define a checkpoint schema in your sync configuration (see Configuration). For a complete guide on implementing incremental syncs with checkpoints, see the checkpoints guide. If you are migrating from nango.lastSyncDate, see the migration guide.

getCheckpoint()Copy Anchor Link

Retrieves the current checkpoint. Returns null on first run or after a reset.

const checkpoint = await nango.getCheckpoint();
if (checkpoint) {
    // Resume from checkpoint
    startCursor = checkpoint.cursor;
}

Response

Returns the checkpoint object matching your schema, or null if no checkpoint exists.

saveCheckpoint()Copy Anchor Link

Saves the current progress. Call this after processing each batch of data to enable resumption if the sync fails.

await nango.saveCheckpoint({ cursor: nextCursor });

Parameters

clearCheckpoint()Copy Anchor Link

Clears the checkpoint. Use at the end of a full sync so the next run starts from the first page. Checkpoints are also automatically cleared when triggering a sync with reset: true.

await nango.clearCheckpoint();

Save recordsCopy Anchor Link

Upserts records to the Tenklo 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 recordsCopy Anchor Link

Marks records as deleted in the Tenklo 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).

To implement deletion detection in your syncs, follow this guide.

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

Detect deletions automaticallyCopy Anchor Link

Automatically detects and marks records as deleted by comparing what existed before trackDeletesStart with what was saved between trackDeletesStart and trackDeletesEnd.

await nango.trackDeletesStart('ModelName');

// ... fetch and save all records ...

await nango.trackDeletesEnd('ModelName');

Call trackDeletesStart at the beginning of your sync execution, before fetching any data. Call trackDeletesEnd after all records have been saved with batchSave. Tenklo will compare the records that existed before trackDeletesStart with those saved in the window and mark any missing records as deleted.

Parameters (both functions)

Important considerations:

• Only use within syncs that fetch the complete dataset between trackDeletesStart and trackDeletesEnd
• If your sync fails or doesn't fetch the complete dataset, avoid calling trackDeletesEnd as it may cause false deletions
• Records are soft deleted (marked with _metadata.deleted = true) and remain in the cache

For more details on deletion detection strategies, see the detecting deletes guide.

Update recordsCopy Anchor Link

Updates records in the Tenklo cache by merging the given data into the existing record. The id field is required in each record and used to determine what existing record to merge into.

batchUpdate is primarily useful in webhook sync functions, where you receive partial updates from a webhook and want to merge them into the existing records.

The merge algorithm used is a deep merge. Nested objects are merged recursively, while arrays always use the new value for the array. Any fields not present in the update record are left unchanged.

// Create partial GitHub Issue update records with only id and state.
const githubIssues: Pick<GitHubIssue, "id" | "state">[] = ...;

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

Take special care when using batchUpdate with records containing arrays. The merge algorithm does not attempt to merge arrays, but rather always uses the value of the new array.

// given a an existing record:
// { id: '1', tags: [{id: 12, name: 'Dev'}, {id: 13, name: "QA"}] }
const updates: Pick<Issue, "id" | "tags">[] = [
    { id: '1', tags: [{id: 14, name: 'UX'}] }
];

// after the update, the record will be:
// { id: '1', tags: [{id: 14, name: "UX"}] }
await nango.batchUpdate(updates, 'Issue');

Parameters

Get recordsCopy Anchor Link

Fetches records from the Tenklo cache by ID. Returns a Map where the keys are the requested IDs, and the values are the corresponding records. Any records that are not found will simply be absent from the map.

Example usage:

const records = await nango.getRecordsById<string, Issue>(['1', '2', '3'], 'Issue');

if (records.has('1')) {
    const record = records.get('1');
    await nango.log(record.title);
} else {
    await nango.log('Record with id 1 not found.');
}

VariantCopy Anchor Link

If you are using sync variants, you can access the current variant name via the nango.variant property.

export default createSync({
  exec: async (nango) => {
    await nango.log(`Running sync with variant: ${nango.variant}`);

    // Customize sync behavior based on variant
    const res = await nango.get({
        endpoint: `/spreadsheet/${nango.variant}`
    });

    // Rest of sync implementation...
  },
});

Action-specific helper methodsCopy Anchor Link

ActionErrorCopy Anchor Link

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

export default createAction({
  exec: async (nango) => {
    // 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 functionsCopy Anchor Link

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

import { issueMapper } from '../mappers/issue-mappper';

export default createSync({
  exec: async (nango) => {
    // 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 DependenciesCopy Anchor Link

Some libraries are pre-included for usage in functions:

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

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