diff --git a/docs-v2/reference/scripts.mdx b/docs-v2/reference/scripts.mdx
index 77115c14cd..aa363d8d2f 100644
--- a/docs-v2/reference/scripts.mdx
+++ b/docs-v2/reference/scripts.mdx
@@ -56,37 +56,78 @@ Read more about [integration scripts](/understand/concepts/scripts) to understan
Integration 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
-HTTP requests in integration 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)).
+Makes an HTTP request inside an integration script:
+```js
+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
+```
-There is one simplification to using the proxy in integration scripts. Because integration 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 integration script.
+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.
+
-Instead of writing:
-```ts
-const res = await nango.get({
- endpoint: '/external-endpoint',
- providerConfigKey: '',
- connectionId: ''
-});
-```
+**Parameters**
-You can write:
+
+
+
+
+ The endpoint of the request.
+
+
+ The headers of the request.
+
+
+ The query parameters of the request.
+
+
+ The body of the request.
+
+
+ The number of retries in case of failure (with exponential back-off). Optional, default 0.
+
+
+ Array of additional status codes to retry a request in addition to the 5xx, 429, ECONNRESET, ETIMEDOUT, and ECONNABORTED
+
+
+ The API base URL. Can be ommitted if the base URL is configured for this API in the [providers.yaml](https://nango.dev/providers.yaml).
+
+
+ Override the decompress option when making requests. Optional, defaults to false
+
+
+ The type of the response.
+
+
+
+
-```ts
-const res = await nango.get({ endpoint: '/external-endpoint' });
+**Response**
+
+
+```json
+ {
+ 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](https://axios-http.com/docs/res_schema).
+
-### Logging
+# Logging
You can collect logs in integration scripts. This is particularly useful when:
- developing, to debug your integration scripts
@@ -99,29 +140,205 @@ 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
+# Environment variables
+
+Integration scripts sometimes need to access sensitive variables that should not be revealed directly in the code.
-Integration scripts sometimes need to access sensitive variables that should not be revealed directly in the integration 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 integration scripts with:
-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 ([reference](/reference/sdks/node#get-environment-variables)).
+```js
+await nango.getEnvironmentVariables();
+```
+
+**Parameters**
+
+No parameters.
+
+**Response**
+
+
+```json
+[
+ {
+ "name": "MY_SECRET_KEY",
+ "value": "SK_373892NSHFNCOWFO..."
+ }
+]
+```
+
-### Trigger action
+# 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 ([reference](/reference/sdks/node#trigger-an-action)).
+As a temporary workaround, you can call action scripts from other integration scripts with:
+
+```js
+await nango.triggerAction('', { 'custom_key1': 'custom_value1' });
+```
+
+**Parameters**
+
+
+
+ The name of the action to trigger.
+
+
+ The necessary input for your action's `runAction` function.
+
+
+
+**Response**
+
+
+```json
+{
+ "your-properties": "The data returned by the action"
+}
+```
+
+
+# Paginate through API responses
-### Paginate through API responses
+Follow the pagination [step-by-step guides](/customize/guides/advanced/paginate-api-responses) to learn how to paginate through API responses easily.
-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
-### Manage connection metadata
+### Get 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.
+Returns the connection's metadata.
-### Get connection
+```js
+await nango.getMetadata();
+```
+
+Better, you can specify the type of the metadata;
+
+```ts
+interface CustomMetadata {
+ anyKey: Record;
+}
+const myTypedMetadata = await nango.getMetadata();
+```
+
+**Parameters**
-Get the connection details, including the API credentials ([reference](/reference/sdks/node#get-a-connection-with-credentials)).
+No parameters.
+
+**Example Response**
+
+
+```json
+{
+ "custom_key1": "custom_value1"
+}
+```
+
+
+### Set connection metadata
+
+Set custom metadata for the connection (overrides existing metadata).
+
+```js
+await nango.setMetadata({ 'CUSTOM_KEY1': 'CUSTOM_VALUE1' });
+```
+
+**Parameters**
+
+
+
+ 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.
+
+```js
+await nango.updateMetadata({ 'CUSTOM_KEY1': 'CUSTOM_VALUE1' });
+```
+
+**Parameters**
+
+
+
+ The custom metadata to store in the connection.
+
+
+
+**Response**
+
+Empty response.
+
+# Get the connection credentials
+
+Returns a specific connection with credentials.
+
+```js
+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**
+
+
+
+ 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.
+
+
+ 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**
+
+
+```json
+{
+ "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
diff --git a/docs-v2/reference/sdks/node.mdx b/docs-v2/reference/sdks/node.mdx
index 48224c9c65..31918e26db 100644
--- a/docs-v2/reference/sdks/node.mdx
+++ b/docs-v2/reference/sdks/node.mdx
@@ -325,11 +325,11 @@ await nango.listConnections();
Returns a specific connection with credentials.
```js
-await nango.getConnection();
+await nango.getConnection(, );
```
-The response content depends on the API authentication type (OAuth 2, OAuth 1, API key, Basic auth).
+The response content depends on the API authentication type (OAuth 2, OAuth 1, API key, Basic auth, etc.).
If you do not want to deal with collecting & injecting credentials in requests for multiple authentication types, use the Proxy ([step-by-step guide](/integrate/guides/proxy-requests-to-an-api)).
@@ -346,16 +346,13 @@ We recommend not caching tokens for longer than 5 minutes to ensure they are fre
The integration ID.
-
The connection ID.
-
-
+
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.
-
-
+
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.
@@ -1013,17 +1010,20 @@ await nango.triggerAction('', '', ''
# Proxy
-### Proxy - GET requests
-
-Triggers an action for a connection.
+Makes an HTTP request using the [proxy](/understand/concepts/proxy):
```js
-const res = await nango.get({
- endpoint: '/endpoint',
+const config = {
+ endpoint: '/some-endpoint',
providerConfigKey: '',
- connectionId: '',
- baseUrlOverride: 'https://base-url.com'
-});
+ connectionId: ''
+};
+
+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**
@@ -1078,262 +1078,6 @@ The response from the external API is passed back to you exactly as Nango gets i
-### Proxy - POST requests
-
-Triggers an action for a connection.
-
-```js
-const res = await nango.post({
- endpoint: '/endpoint',
- providerConfigKey: '',
- connectionId: '',
- baseUrlOverride: 'https://base-url.com'
-});
-```
-
-**Parameters**
-
-
-
-
-
- The endpoint of the request.
-
-
- The integration ID (for credential injection).
-
-
- The connection ID (for credential injection).
-
-
- The headers of the request.
-
-
- The query parameters of the request.
-
-
- The body of the request.
-
-
- The number of retries in case of failure (with exponential back-off). Optional, default 0.
-
-
- Array of additional status codes to retry a request in addition to the 5xx, 429, ECONNRESET, ETIMEDOUT, and ECONNABORTED
-
-
- The API base URL. Can be ommitted if the base URL is configured for this API in the [providers.yaml](https://nango.dev/providers.yaml).
-
-
- Override the decompress option when making requests. Optional, defaults to false
-
-
- The type of the response.
-
-
-
-
-
-**Response**
-
-
-The response from the external API is passed back to you exactly as Nango gets it:
-- response code
-- response headers
-- response body
-
-
-### Proxy - PUT requests
-
-Triggers an action for a connection.
-
-```js
-const res = await nango.put({
- endpoint: '/endpoint',
- providerConfigKey: '',
- connectionId: '',
- baseUrlOverride: 'https://base-url.com'
-});
-```
-
-**Parameters**
-
-
-
-
-
- The endpoint of the request.
-
-
- The integration ID (for credential injection).
-
-
- The connection ID (for credential injection).
-
-
- The headers of the request.
-
-
- The query parameters of the request.
-
-
- The body of the request.
-
-
- The number of retries in case of failure (with exponential back-off). Optional, default 0.
-
-
- Array of additional status codes to retry a request in addition to the 5xx, 429, ECONNRESET, ETIMEDOUT, and ECONNABORTED
-
-
- The API base URL. Can be ommitted if the base URL is configured for this API in the [providers.yaml](https://nango.dev/providers.yaml).
-
-
- Override the decompress option when making requests. Optional, defaults to false
-
-
- The type of the response.
-
-
-
-
-
-**Response**
-
-
-The response from the external API is passed back to you exactly as Nango gets it:
-- response code
-- response headers
-- response body
-
-
-### Proxy - PATCH requests
-
-Triggers an action for a connection.
-
-```js
-const res = await nango.patch({
- endpoint: '/endpoint',
- providerConfigKey: '',
- connectionId: '',
- baseUrlOverride: 'https://base-url.com'
-});
-```
-
-**Parameters**
-
-
-
-
-
- The endpoint of the request.
-
-
- The integration ID (for credential injection).
-
-
- The connection ID (for credential injection).
-
-
- The headers of the request.
-
-
- The query parameters of the request.
-
-
- The body of the request.
-
-
- The number of retries in case of failure (with exponential back-off). Optional, default 0.
-
-
- Array of additional status codes to retry a request in addition to the 5xx, 429, ECONNRESET, ETIMEDOUT, and ECONNABORTED
-
-
- The API base URL. Can be ommitted if the base URL is configured for this API in the [providers.yaml](https://nango.dev/providers.yaml).
-
-
- Override the decompress option when making requests. Optional, defaults to false
-
-
- The type of the response.
-
-
-
-
-
-**Response**
-
-
-The response from the external API is passed back to you exactly as Nango gets it:
-- response code
-- response headers
-- response body
-
-
-### Proxy - DELETE requests
-
-Triggers an action for a connection.
-
-```js
-const res = await nango.delete({
- endpoint: '/endpoint',
- providerConfigKey: '',
- connectionId: '',
- baseUrlOverride: 'https://base-url.com'
-});
-```
-
-**Parameters**
-
-
-
-
-
- The endpoint of the request.
-
-
- The integration ID (for credential injection).
-
-
- The connection ID (for credential injection).
-
-
- The headers of the request.
-
-
- The query parameters of the request.
-
-
- The body of the request.
-
-
- The number of retries in case of failure (with exponential back-off). Optional, default 0.
-
-
- Array of additional status codes to retry a request in addition to the 5xx, 429, ECONNRESET, ETIMEDOUT, and ECONNABORTED
-
-
- The API base URL. Can be ommitted if the base URL is configured for this API in the [providers.yaml](https://nango.dev/providers.yaml).
-
-
- Override the decompress option when making requests. Optional, defaults to false
-
-
- The type of the response.
-
-
-
-
-
-**Response**
-
-
-The response from the external API is passed back to you exactly as Nango gets it:
-- response code
-- response headers
-- response body
-
-
**Questions, problems, feedback?** Please reach out in the [Slack community](https://nango.dev/slack).
\ No newline at end of file