Node.js SDK

import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: '<SECRET-KEY>' });

try {
    const res = await nango.listIntegrations();
} catch (err) {
    if (err.response.status === 429) {
        const retryAfter = err.response.headers['retry-after'];
        // wait retryAfter seconds, then retry
    }
}

const providers = await nango.listProviders(queries);

const provider = await nango.getProvider({ provider: 'github' });

const { configs } = await nango.listIntegrations();

const integration = await nango.getIntegration(
    { uniqueKey: 'my-github-integration' },
    { include: ['webhook'] } // optional
);

const integration = await nango.createIntegration({
    provider: 'github',
    unique_key: 'my-github-integration',
    display_name: 'GitHub',
    credentials: {
        oauth_client_id: '<CLIENT-ID>',
        oauth_client_secret: '<CLIENT-SECRET>'
    }
});

await nango.updateIntegration(
    { uniqueKey: 'my-github-integration' },
    { display_name: 'GitHub (Production)' }
);

await nango.deleteIntegration('my-github-integration');

const { data } = await nango.createConnectSession({
    tags: {
        end_user_id: 'user-123',
        end_user_email: '[email protected]',
        organization_id: 'org-456'
    },
    allowed_integrations: ['github', 'slack'],
    integrations_config_defaults: {
        github: {
            connection_config: {
                repo: 'my-repo'
            }
        }
    }
});

const { token, connect_link, expires_at } = data;

const { data } = await nango.createReconnectSession({
    connection_id: 'user-123-github',
    integration_id: 'my-github-integration',
    tags: {
        end_user_id: 'user-123'
    }
});

const result = await nango.listConnections({
    connectionId: 'user-123',
    integrationId: 'my-github-integration',
    limit: 100,
    tags: { end_user_id: 'user-123' }
});

const connection = await nango.getConnection(
    'my-github-integration', // providerConfigKey
    'user-123',              // connectionId
    false,                   // forceRefresh (optional)
    false                    // refreshToken (optional)
);

await nango.deleteConnection('my-github-integration', 'user-123');

const connection = await nango.waitForConnection(
    'my-github-integration', // integrationKey
    'user-123'               // userId (end_user_id tag value)
);

await nango.patchConnection(
    { connectionId: 'user-123', provider_config_key: 'my-github-integration' },
    { tags: { plan: 'pro' } }
);

const metadata = await nango.getMetadata('my-github-integration', 'user-123');

// With typed return value:
interface MyMetadata {
    repo: string;
    plan: string;
}
const typed = await nango.getMetadata<MyMetadata>('my-github-integration', 'user-123');

// Single connection
await nango.setMetadata('my-github-integration', 'user-123', {
    repo: 'my-repo',
    plan: 'pro'
});

// Multiple connections at once
await nango.setMetadata('my-github-integration', ['user-123', 'user-456'], {
    plan: 'enterprise'
});

await nango.updateMetadata('my-github-integration', 'user-123', {
    plan: 'enterprise'
});

const config = {
    endpoint: '/repos/octocat/hello-world',
    providerConfigKey: 'my-github-integration',
    connectionId: 'user-123'
};

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

const response = await nango.post({
    endpoint: '/issues',
    providerConfigKey: 'my-github-integration',
    connectionId: 'user-123',
    headers: {
        'Accept': 'application/vnd.github+json'
    },
    data: {
        title: 'Bug report',
        body: 'Something is broken.'
    }
});

console.log(response.data); // GitHub API response

import type { GithubIssue } from './nango-integrations/models';

const result = await nango.listRecords<GithubIssue>({
    providerConfigKey: 'my-github-integration',
    connectionId: 'user-123',
    model: 'GithubIssue',
    limit: 100,
    filter: 'added,updated'
});

const { records, next_cursor } = result;

// Trigger a single sync
await nango.triggerSync('my-github-integration', ['github-issues'], 'user-123');

// Full resync from scratch
await nango.triggerSync('my-github-integration', ['github-issues'], 'user-123', {
    reset: true,
    emptyCache: true
});

// Using sync variants
await nango.triggerSync('my-github-integration', [
    { name: 'github-issues', variant: 'enterprise' },
    'github-repos'
], 'user-123');

await nango.startSync('my-github-integration', ['github-issues'], 'user-123');

await nango.pauseSync('my-github-integration', ['github-issues'], 'user-123');

// Specific syncs
const status = await nango.syncStatus('my-github-integration', ['github-issues'], 'user-123');

// All syncs for a connection
const allStatus = await nango.syncStatus('my-github-integration', '*', 'user-123');

// Override to every hour
await nango.updateSyncConnectionFrequency(
    'my-github-integration',
    'github-issues',
    'user-123',
    'every hour'
);

// Revert to default frequency
await nango.updateSyncConnectionFrequency(
    'my-github-integration',
    'github-issues',
    'user-123',
    null
);

const result = await nango.pruneRecords({
    providerConfigKey: 'my-github-integration',
    connectionId: 'user-123',
    model: 'GithubIssue',
    untilCursor: 'MjAyNC0wMi0yNlQw...'
});

console.log(`Pruned ${result.count} records. More available: ${result.has_more}`);

const result = await nango.triggerAction(
    'my-github-integration',  // providerConfigKey
    'user-123',               // connectionId
    'create-issue',           // actionName
    {                         // input (optional)
        title: 'New bug',
        body: 'Description here'
    }
);

const { id, statusUrl } = await nango.triggerActionAsync(
    'my-github-integration',
    'user-123',
    'export-data',
    { format: 'csv' }
);

// Later, poll for the result:
const result = await nango.getAsyncActionResult({ id });

// By action ID
const result = await nango.getAsyncActionResult({ id: 'action_123456' });

// By status URL
const result = await nango.getAsyncActionResult({ statusUrl: '/action/action_123456' });

app.post('/webhook', (req, res) => {
    const isValid = nango.verifyIncomingWebhookRequest(
        req.body,    // raw body as a string
        req.headers  // request headers
    );

    if (!isValid) {
        return res.status(401).send('Invalid signature');
    }

    // handle the webhook
});

// Nango format (default)
const config = await nango.getScriptsConfig();

// OpenAI function-calling format
const openaiConfig = await nango.getScriptsConfig('openai');