Skip to content

Commit

Permalink
feat(sdk): add new endpoints (#2747)
Browse files Browse the repository at this point in the history 
## Describe your changes

Fixes
https://linear.app/nango/issue/NAN-1753/document-new-endpoints-integrations-and-providers

- Add new endpoints to the SDK
There is only one method that was different enough, queries and output
that even with signature overload it wasn't possible to make it
non-breaking. Honestly, I didn't find anything compelling to deprecate
without either being ugly or breaking customers' scripts, so very open
to suggestions.

- Document new SDK method
- Add support for `include=webhook` in `GET /integrations/:key`
The SDK needs it, and some customers use it. It's a secret but not
credentials, so I didn't put a too vague name. If we need credentials at
some point, we can differentiate.
  • Loading branch information
@bodinsamuel
bodinsamuel authored Sep 20, 2024
1 parent 280be08 commit 53d383b
Show file tree
Hide file tree
Showing 17 changed files with 317 additions and 96 deletions.
4 changes: 2 additions & 2 deletions docs-v2/reference/api/integration/get.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ openapi: 'GET /integrations/{uniqueKey}'
---

<ResponseExample>
```json Example Response
```json Example Response
{
"data": {
"unique_key": "slack-nango-community",
Expand All @@ -14,5 +14,5 @@ openapi: 'GET /integrations/{uniqueKey}'
"updated_at": "2023-10-16T08:45:26.241Z",
}
}
```
```
</ResponseExample>
14 changes: 12 additions & 2 deletions docs-v2/reference/api/integration/list.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,18 @@ title: 'List all integrations'
openapi: 'GET /integrations'
---

<RequestExample>

```ts Node Client
const nango = new Nango({ secretKey });

const response = await nango.listIntegrations();
```

</RequestExample>

<ResponseExample>
```json Example Response
```json Example Response
{
"data": [
{
Expand All @@ -23,5 +33,5 @@ openapi: 'GET /integrations'
},
]
}
```
```
</ResponseExample>
171 changes: 116 additions & 55 deletions docs-v2/reference/sdks/node.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ const nango = new Nango({ secretKey: '<SECRET-KEY>' });
</ResponseField>

<ResponseField name="host" type="string">
Omitting the host points to Nango Cloud. For local development, use `http://localhost:3003`. Use your instance URL if self-hosting.
Omitting the host points to Nango Cloud. For local development, use `http://localhost:3003`. Use your instance URL if self-hosting.
</ResponseField>
</Expandable>
</ResponseField>
Expand Down Expand Up @@ -61,6 +61,63 @@ try {
}
```

# Providers

### List all providers

Returns a list of providers.

```js
await nango.listProviders()
```

**Example Response**

<Expandable>
```json
{
"data": [
{
"name": "posthog",
"categories": ["dev-tools"],
"auth_mode": "API_KEY",
"proxy": {
"base_url": "https://api.posthog.com",
},
"docs": "https://docs.nango.dev/integrations/all/posthog"
}
]
}
```
</Expandable>


### Get a provider

Returns a specific provider.

```js
await nango.getProvider({ provider: <NAME> })
```

**Example Response**

<Expandable>
```json
{
"data": {
"name": "posthog",
"categories": ["dev-tools"],
"auth_mode": "API_KEY",
"proxy": {
"base_url": "https://api.posthog.com",
},
"docs": "https://docs.nango.dev/integrations/all/posthog"
}
}
```
</Expandable>

# Integrations

### List all integrations
Expand All @@ -79,11 +136,17 @@ await nango.listIntegrations()
"configs": [
{
"unique_key": "slack-nango-community",
"provider": "slack"
"provider": "slack",
"logo": "http://localhost:3003/images/template-logos/slack.svg",
"created_at": "2023-10-16T08:45:26.241Z",
"updated_at": "2023-10-16T08:45:26.241Z",
},
{
"unique_key": "github-prod",
"provider": "github"
"provider": "github",
"logo": "http://localhost:3003/images/template-logos/github.svg",
"created_at": "2023-10-16T08:45:26.241Z",
"updated_at": "2023-10-16T08:45:26.241Z",
},
]
}
Expand All @@ -95,44 +158,42 @@ await nango.listIntegrations()
Returns a specific integration.

```js
await nango.getIntegration({ unique_key: <UNIQUE_KEY> });

// Deprecated
await nango.getIntegration(<INTEGRATION-ID>);
```

**Parameters**

<Expandable>
<ResponseField name="providerConfigKey" type="string" required>
<ResponseField name="unique_key" type="string" required>
The integration ID (`unique_key`)
</ResponseField>
<ResponseField name="include" type="array">
Include sensitive data. Allowed values: `webhook`
</ResponseField>

<ResponseField name="providerConfigKey" type="string" required deprecated>
The integration ID.
</ResponseField>

<ResponseField name="includeIntegrationCredentials" type="boolean">
Defaults to `false`.
</ResponseField>
<ResponseField name="includeIntegrationCredentials" type="boolean" deprecated>
Defaults to `false`.
</ResponseField>
</Expandable>

**Example Response**

<Expandable>
```json
{
"config": {
"data": {
"unique_key": "slack-nango-community",
"provider": "slack",
"syncs": [
{
"name": "slack-messages",
"created_at": "2023-10-16T08:45:26.241Z",
"updated_at": "2023-10-16T08:45:26.241Z",
"description": "Continuously fetch the latest Slack messages. Details: full refresh. Required scopes(s): channels:read, groups:read, mpim:read, im:read"
}
],
"actions": [
{
"name": "github-list-repos-action",
"created_at": "2023-10-17T17:28:03.839Z",
"updated_at": "2023-10-17T17:28:03.839Z"
}
]
"logo": "http://localhost:3003/images/template-logos/slack.svg",
"created_at": "2023-10-16T08:45:26.241Z",
"updated_at": "2023-10-16T08:45:26.241Z",
}
}
```
Expand All @@ -159,7 +220,7 @@ await nango.createIntegration(<PROVIDER-ID>, <INTEGRATION-ID>);

<ResponseField name="credentials" type="Record<string, string>">
The credentials to include depend on the specific integration that you want to create.
</ResponseField>
</ResponseField>

<ResponseField name="credentials" type="Record<string, string>">
<Expandable title="credentials" defaultOpen>
Expand Down Expand Up @@ -212,7 +273,7 @@ await nango.updateIntegration(<PROVIDER-ID>, <INTEGRATION-ID>);

<ResponseField name="credentials" type="Record<string, string>">
The credentials to include depend on the specific integration that you want to create.
</ResponseField>
</ResponseField>

<ResponseField name="credentials" type="Record<string, string>">
<Expandable title="credentials" defaultOpen>
Expand Down Expand Up @@ -244,7 +305,7 @@ await nango.updateIntegration(<PROVIDER-ID>, <INTEGRATION-ID>);
```
</Expandable>

### Delete an integration
### Delete an integration

Deletes a specific integration.

Expand Down Expand Up @@ -329,7 +390,7 @@ await nango.getConnection(<INTEGRATION-ID>, <CONNECTION-ID>);
```

<Info>
The response content depends on the API authentication type (OAuth 2, OAuth 1, API key, Basic auth, etc.).
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)).
</Info>
Expand Down Expand Up @@ -362,34 +423,34 @@ We recommend not caching tokens for longer than 5 minutes to ensure they are fre
<Expandable>
```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",
"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",
"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": {
"connection_config": {
"subdomain": "myshop",
"realmId": "XXXXX",
"instance_id": "YYYYYYY"
},
"account_id": 0,
"metadata": {
},
"account_id": 0,
"metadata": {
"myProperty": "yes",
"filter": "closed=true"
}
}
}
```
</Expandable>

Expand Down Expand Up @@ -729,8 +790,8 @@ Returns the synced data.
import type { ModelName } from '<path-to-nango-integrations>/models'

const records = await nango.listRecords<ModelName>({
providerConfigKey: '<INTEGRATION-ID>',
connectionId: '<CONNECTION-ID>',
providerConfigKey: '<INTEGRATION-ID>',
connectionId: '<CONNECTION-ID>',
model: '<MODEL-NAME>'
});
```
Expand Down Expand Up @@ -767,13 +828,13 @@ const records = await nango.listRecords<ModelName>({
</ResponseField>

<ResponseField name="limit" type="number">
The maximum number of records to return. Defaults to 100.
The maximum number of records to return. Defaults to 100.
</ResponseField>

<ResponseField name="filter" type="string">
Filter to only show results that have been added or updated or deleted.
Filter to only show results that have been added or updated or deleted.

Available options: added, updated, deleted
Available options: added, updated, deleted
</ResponseField>

<ResponseField name="modifiedAfter" type="string">
Expand Down Expand Up @@ -831,7 +892,7 @@ const records = await nango.triggerSync('<INTEGRATION-ID>', ['SYNC_NAME1', 'SYNC
The integration ID.
</ResponseField>
<ResponseField name="syncs" type="string[]" required>
The name of the syncs to trigger. If the array is empty, all syncs are triggered.
The name of the syncs to trigger. If the array is empty, all syncs are triggered.
</ResponseField>
<ResponseField name="connectionId" type="string">
The connection ID. If omitted, the sync will trigger for all relevant connections.
Expand All @@ -857,7 +918,7 @@ await nango.startSync('<INTEGRATION-ID>', ['SYNC_NAME1', 'SYNC_NAME2'], '<CONNEC
The integration ID.
</ResponseField>
<ResponseField name="syncs" type="string[]" required>
The name of the syncs that should be triggered.
The name of the syncs that should be triggered.
</ResponseField>
<ResponseField name="connectionId" type="string">
The connection ID. If ommitted, the sync will trigger for all relevant connections.
Expand All @@ -883,7 +944,7 @@ await nango.startSync('<INTEGRATION-ID>', ['SYNC_NAME1', 'SYNC_NAME2'], '<CONNEC
The integration ID.
</ResponseField>
<ResponseField name="syncs" type="string[]" required>
The name of the syncs that should be paused.
The name of the syncs that should be paused.
</ResponseField>
<ResponseField name="connectionId" type="string">
The connection ID. If ommitted, the sync will pause for all relevant connections.
Expand Down Expand Up @@ -955,7 +1016,7 @@ await nango.updateSyncConnectionFrequency('<INTEGRATION-ID>', 'SYNC_NAME', '<CON
The name of the sync.
</ResponseField>
<ResponseField name="connectionId" type="string" required>
The connection ID.
The connection ID.
</ResponseField>
<ResponseField name="frequency" type="string" required>
The frequency you want to set (ex: 'every hour'). Set to `null` to revert to the default frequency. Uses the https://github.com/vercel/ms notations. Min frequency: 5 minutes.
Expand Down Expand Up @@ -1014,7 +1075,7 @@ await nango.triggerAction('<INTEGRATION-ID>', '<CONNECTION_ID>', '<ACTION-NAME>'
The integration ID.
</ResponseField>
<ResponseField name="connectionId" type="string" required>
The connection ID.
The connection ID.
</ResponseField>
<ResponseField name="actionName" type="string" required>
The name of the action to trigger.
Expand All @@ -1039,7 +1100,7 @@ await nango.triggerAction('<INTEGRATION-ID>', '<CONNECTION_ID>', '<ACTION-NAME>'
Makes an HTTP request using the [proxy](/understand/concepts/proxy):

```js
const config = {
const config = {
endpoint: '/some-endpoint',
providerConfigKey: '<INTEGRATION-ID>',
connectionId: '<CONNECTION-ID>'
Expand All @@ -1064,7 +1125,7 @@ await nango.delete(config); // DELETE request
The integration ID (for credential injection).
</ResponseField>
<ResponseField name="connectionId" type="string" required>
The connection ID (for credential injection).
The connection ID (for credential injection).
</ResponseField>
<ResponseField name="headers" type="Record<string, string>">
The headers of the request.
Expand All @@ -1088,7 +1149,7 @@ await nango.delete(config); // DELETE request
Override the decompress option when making requests. Optional, defaults to false
</ResponseField>
<ResponseField name="responseType" type="'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream'">
The type of the response.
The type of the response.
</ResponseField>
</Expandable>
</ResponseField>
Expand All @@ -1106,4 +1167,4 @@ The response from the external API is passed back to you exactly as Nango gets i

<Tip>
**Questions, problems, feedback?** Please reach out in the [Slack community](https://nango.dev/slack).
</Tip>
</Tip>
Loading

0 comments on commit 53d383b

Please sign in to comment.