From 79461aaf98d7b362e230f6a6086cf6713f34d1d0 Mon Sep 17 00:00:00 2001 From: Bastien Beurier Date: Mon, 18 Mar 2024 17:14:34 +0100 Subject: [PATCH] Add scripts reference --- .../reference/integration-configuration.mdx | 3 +- docs-v2/reference/scripts.mdx | 201 +++++++++++++++++- docs-v2/reference/sdks/node.mdx | 4 +- 3 files changed, 202 insertions(+), 6 deletions(-) diff --git a/docs-v2/reference/integration-configuration.mdx b/docs-v2/reference/integration-configuration.mdx index c34b79a511..5214f9dc5c 100644 --- a/docs-v2/reference/integration-configuration.mdx +++ b/docs-v2/reference/integration-configuration.mdx @@ -4,7 +4,8 @@ sidebarTitle: 'Integration config (nango.yaml)' icon: 'arrow-right-arrow-left' --- -Example of an integration configuration: +# Example + ```yaml nango.yaml integrations: asana: # Integration ID. diff --git a/docs-v2/reference/scripts.mdx b/docs-v2/reference/scripts.mdx index 0f8f90455c..6a2d21ac3e 100644 --- a/docs-v2/reference/scripts.mdx +++ b/docs-v2/reference/scripts.mdx @@ -4,6 +4,201 @@ sidebarTitle: 'Scripts' icon: 'code' --- - -The docs recently underwent a makeover, leaving this page empty. We are working hard to fill in all the missing pages within the next two weeks. Meanwhile, ask any questions on the [community](https://nango.dev/slack). - \ No newline at end of file +# Examples + + + + +```ts +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'); +} +``` + + + +```ts +import type { NangoAction, GithubCreateIssueInput, GithubCreateIssueResult } from './models'; + +export default async function runAction(nango: NangoAction, input: GithubCreateIssueInput): Promise { + // Create a GitHub issue. + const res = await nango.post({ + endpoint: '/repos/NangoHQ/interactive-demo/issues', + data: { + title: `[demo] ${input.title}`, + body: `The body of the issue.`, + labels: ['automatic'] + } + }); + + // Send response. + return { url: res.data.html_url, status: res.status }; +} +``` + + + + +Read more about [scripts](/understand/concepts/scripts) to understand what role they play in Nango. + +Scripts expose a helper object (`NangoSync` for sync scripts, `NangoAction` for action scripts), which allows to interact with external APIs & Nango more easily. + + +The script helper object shares some methods, but not all, with the [Node backend SDK](/reference/sdks/node), which is why this reference will link to the Node SDK reference a lot. + + +# Common helper methods + +### HTTP requests + +HTTP requests in scripts are made with the proxy ([concept]((/understand/concepts/proxy)) / [step-by-step guide](/integrate/guides/proxy-requests-to-an-api) / [reference](/reference/sdks/node#proxy)). + + + +There is one simplification to using the proxy in scripts. Because scripts always execute in the context of a specific integration & connection, you do not need to specify the `providerConfigKey` & `connectionId` parameters when calling the proxy from script. + +Instead of writing: +```ts +const res = await nango.get({ + endpoint: '/external-endpoint', + providerConfigKey: '', + connectionId: '' +}); +``` + +You can write: + +```ts +const res = await nango.get({ endpoint: '/external-endpoint' }); +``` + + +### Logging + +You can collect logs in scripts. This is particularly useful when: +- developing, to debug your scripts +- in production, to collect information about script executions & understand issues + +Collect logs in scripts as follows: +```ts +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 + +Scripts sometimes need to access sensitive variables that should not be revealed directly in the script 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 scripts ([reference](/reference/sdks/node#get-environment-variables)). + +### Trigger action + +Scripts currently do not support importing files, which limits the ability to share code between scripts. + +As a temporary workaround, you can call action scripts from other scripts ([reference](/reference/sdks/node#trigger-an-action)). + +### Paginate through API responses + +Follow the pagination [step-by-step guides](/customize/guides/advanced/paginate-api-responses) to learn how to easily paginate through API responses. + +### Manage connection metadata + +[Retrieve](/reference/sdks/node#get-connection-metadata), [edit](/reference/sdks/node#edit-connection-metadata) or [override](/reference/sdks/node#set-connection-metadata) the connection metadata. + +### Get connection + +Get the connection details, including the API credentials ([reference](/reference/sdks/node#get-a-connection-with-credentials)). + +# Sync-specific helper methods + +Sync scripts persist data updates to the Nango cache, which your app later fetches (cf. [step-by-step guide](/integrate/guides/sync-data-from-an-api)). + +### 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. + +```js +const githubIssues: GitHubIssue[] = ...; // Fetch issues from GitHub API. + +await nango.batchSave(githubIssues, 'GitHubIssue'); +``` + +**Parameters** + + + + The list of records to persist. + + + + 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. + +```js +const githubIssuesToDelete: { id: string }[] = ...; // Fetch issues to delete from GitHub API. + +await nango.batchDelete(githubIssuesToDelete, 'GitHubIssue'); +``` + +**Parameters** + + + + The list of records to delete. + + + + 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: +```ts + +export default async function runAction(nango: NangoAction): Promise { + // Something went wrong... + + throw new ActionError({ any_key: 'any_value' }); +} + +``` + +In this case, the response to the trigger action call will be: +```json +{ + "error_type": "action_script_failure", + "payload": { + "any_key": "any_value" + } +} +``` + + +**Questions, problems, feedback?** Please reach out in the [Slack community](https://nango.dev/slack). + \ No newline at end of file diff --git a/docs-v2/reference/sdks/node.mdx b/docs-v2/reference/sdks/node.mdx index 4cdc5115a5..a726448e15 100644 --- a/docs-v2/reference/sdks/node.mdx +++ b/docs-v2/reference/sdks/node.mdx @@ -335,9 +335,9 @@ If you do not want to deal with collecting & injecting credentials in requests f -Every time you fetch the connection with this API endpoint, Nango will check if the access token has expired. If it has, it will refresh it. +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 you always fetch the token just before you use it to make sure it is fresh!** +We recommend not caching tokens for longer than 5 minutes to ensure they are fresh. **Parameters**