fix(integrations): backfill integration templates (NangoHQ#1833)

## Describe your changes

- Backfill all sync & action integration templates with all their
necessary properties.
- Removed redundant text; Details: full sync, doesn't track deletes,
metadata is not required. and replaced it with actual `nango.yaml`
properties where appropriate; `sync_type`, `track_deletes` and
`metadata` since defaults are false.
- Fix integration docs files
- Added missing provider flows

docs-v2/integrations/all/ashby.mdx

@@ -29,4 +29,4 @@ API configuration: [`ashby`](https://nango.dev/providers.yaml)
 - Ashby gives you only an `API Key` but uses Basic auth for the API. Pass the `API Key` as the username to Nango and leave the password blank.
 
 
-<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/gong.mdx)</Note>
+<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/ashby.mdx)</Note>

docs-v2/integrations/all/freshdesk.mdx

@@ -48,4 +48,4 @@ For more details, see the [docs here](/integrate/guides/authorize-an-api#apis-re
 - For Basic Auth, Freshdesk uses API key as a username and dummy characters as a password.
 - API calls are directed to your subdomain of Freshdesk.
 
-<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/freshservice.mdx)</Note>
+<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/freshdesk.mdx)</Note>

docs-v2/integrations/all/greenhouse.mdx

@@ -33,4 +33,4 @@ Greenhouse offers both `Basic` and `OAuth` as authentication and Nango implement
 - For `Basic` auth pass Greenhouse API token as username and the password should be blank.
 - If you need to use the proxy, it is important to provide the resource that you will be calling in the config (as green house has many forms for API resource). Please see [here](https://developers.greenhouse.io/) for different types of resources. Once confirmed, you have to add `resource` as a config.
 
-<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/gorgias.mdx)</Note>
+<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/greenhouse.mdx)</Note>

docs-v2/integrations/all/guru.mdx

@@ -29,4 +29,4 @@ API configuration: [`guru`](https://nango.dev/providers.yaml)
 - For Basic Auth, Guru uses USER or COLLECTION ID as the username and either User token Collection token as the password.
 
 
-<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/getguru.mdx)</Note>
+<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/guru.mdx)</Note>

docs-v2/integrations/all/intercom.mdx

@@ -32,4 +32,4 @@ API configuration: [`intercom`](https://nango.dev/providers.yaml)
 -   Intercom access tokens do not expire. Logically, Intercom doesn't return a refresh token along with the access token.
 -   You do not need to pass API scopes/permissions during the authorization request. Permissions are only set in the Intercom Developer Portal.
 
-<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/instagram.mdx)</Note>
+<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/intercom.mdx)</Note>

docs-v2/integrations/all/servicenow.mdx

@@ -29,4 +29,4 @@ API configuration: [`servicenow`](https://nango.dev/providers.yaml)
 
 -   For security purposes, access tokens will expire after 30 minutes by default, when this happens you can use `nango.getConnection()` to generate a new set of tokens.
 
-<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/okta.mdx)</Note>
+<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/servicenow.mdx)</Note>

docs-v2/integrations/all/stripe-app.mdx

@@ -38,3 +38,5 @@ nango.auth('stripe-app-sandbox', '<CONNECTION-ID>', {params: {appDomain: '<strip
 ## API gotchas
 
 - Stripe app does not return an `expire_at` or `expire_in` value during the exchange of a code for an access token. However, according to the [docs](https://docs.stripe.com/stripe-apps/api-authentication/oauth#refresh-access-token), access tokens expire in one hour, while refresh tokens expire in one year
+
+<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/stripe-app.mdx)</Note>

docs-v2/integrations/all/stripe-express.mdx

@@ -27,4 +27,4 @@ API configuration: [`stripe-express`](https://nango.dev/providers.yaml)
 
 ## API gotchas
 
-<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/stripe.mdx)</Note>
+<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/stripe-express.mdx)</Note>

docs-v2/integrations/all/teamwork.mdx

@@ -27,7 +27,7 @@ API configuration: [`teamwork`](https://nango.dev/providers.yaml)
 ## API gotchas
 
 -   There are no scopes needed in the authorization, hence, you can keep the scope field empty.
--   Teamwork uses [different domain extensions](https://apidocs.teamwork.com/docs/teamwork/df5a63302d729-getting-started-with-the-teamwork-com-api#getting-your-url) for different regions, i.e `eu` for EU Hosted Customers. For US based clients leave `extension` blank but for EU based customers add `.eu` as your `extension`.
--   Also, provide your `yourSiteName` as your connection `subdomain`. If you're using a custom domain, you can override the set `base_url` using `baseUrlOverride`.
+-   Teamwork utilizes [distinct subdomain extensions and site names](https://apidocs.teamwork.com/guides/teamwork/getting-started-with-the-teamwork-com-api#getting-your-url) tailored to different regions. For instance, European customers are assigned a subdomain with the `.eu` extension, such as `yourSiteName.eu`, whereas US-based clients are provided with a subdomain without any additional extension, like `yourSiteName`. Remember to use the appropriate subdomain for your specific region.
+-   If you're using a custom domain, you can override the set `base_url` using `baseUrlOverride`.
 
 <Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/teamwork.mdx)</Note>

docs-v2/integrations/all/tiktok-ads.mdx

@@ -28,4 +28,4 @@ API configuration: [`tiktok-ads`](https://nango.dev/providers.yaml)
 
 ## API gotchas
 
-<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/tiktok-accounts.mdx)</Note>
+<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/tiktok-ads.mdx)</Note>

docs-v2/integrations/all/workable.mdx

@@ -55,4 +55,4 @@ nango.auth('workable', '<CONNECTION-ID>', {
 
 - The API base URL in Nango is set to `https://{subdomain}.workable.com` for future forward compatability. To call endpoints of the V3 API, prefix the endpoint with `/spi/v3/`, e.g. `/spi/v3/candidates`.
 
-<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/gong.mdx)</Note>
+<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/workable.mdx)</Note>

docs-v2/integrations/all/zoho-inventory.mdx

@@ -28,7 +28,7 @@ API configuration: [`zoho-inventory`](https://nango.dev/providers.yaml)
 
 ## Connection configuration in Nango
 
-Zoho uses [different domain extensions](https://www.zoho.com/crm/developer/docs/api/v3/multi-dc.html) for different regions. 
+Zoho uses [different domain extensions](https://www.zoho.com/crm/developer/docs/api/v3/multi-dc.html) for different regions.
 
 You need to pass the domain extension to use to Nango in the `nango.auth()` call:
 
@@ -41,4 +41,4 @@ For more details, see the [docs here](/integrate/guides/authorize-an-api#apis-re
 ## API gotchas
 - You can make your OAuth app cross-data-centers with [these instructions](https://www.zoho.com/crm/developer/docs/api/v3/multi-dc.html). This means that a single OAuth app will be able to query the Zoho API for Zoho accounts from the US, EU, etc.
 
-<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/zoho-books.mdx)</Note>
+<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/zoho-inventory.mdx)</Note>

integration-templates/asana/nango.yaml

@@ -4,14 +4,12 @@ integrations:
       asana-tasks:
         runs: every 30min
         description: |
-          Continuously fetches Asana tasks. This is just a trivial example:
-          it will only get tasks from the first project of the first workspace.
-          Details: full refresh, doesn't support deletes, sync goes to all time,
-          metadata is not required.
-        scopes: default
+          Fetches a list of tasks from Asana, retrieving tasks from only the first project of the first workspace
+        scopes:
+          - default
         output: AsanaTask
         sync_type: full
-        endpoint: /asana/asana-tasks
+        endpoint: /asana/tasks
 models:
   AsanaTask:
     id: string

integration-templates/ashby/ashby-create-application.ts

@@ -1,13 +1,4 @@
-import type { NangoAction, AshbyCreateApplicationResponse } from './models';
-
-interface AshbyCreateCandidateInput {
-    candidateId: string;
-    jobId: string;
-    interviewPlanId?: string;
-    interviewStageId?: string;
-    sourceId?: string;
-    creditedToUserId?: string;
-}
+import type { NangoAction, AshbyCreateApplicationResponse, AshbyCreateCandidateInput } from './models';
 
 export default async function runAction(nango: NangoAction, input: AshbyCreateCandidateInput): Promise<AshbyCreateApplicationResponse> {
     if (!input.candidateId) {
@@ -67,6 +58,8 @@ export default async function runAction(nango: NangoAction, input: AshbyCreateCa
             appliedViaJobPostingId
         };
     } catch (error: any) {
-        throw new Error(`Error in runAction: ${error.message}`);
+        throw new nango.ActionError({
+            message: `Error in runAction: ${error.message}`
+        });
     }
 }

integration-templates/ashby/ashby-create-note.ts

@@ -1,23 +1,13 @@
-import type { NangoAction, AshbyCreateNoteResponse } from './models';
-
-interface AshbyCreateNoteInput {
-    candidateId: string;
-    note: string | NoteObject;
-    sendNotifications?: boolean;
-}
-
-interface NoteObject {
-    value: string;
-    type: string;
-}
+import type { NangoAction, AshbyCreateNoteResponse, AshbyCreateNoteInput, NoteObject } from './models';
 
 export default async function runAction(nango: NangoAction, input: AshbyCreateNoteInput): Promise<AshbyCreateNoteResponse> {
+    //input validation
     if (!input.candidateId) {
         throw new nango.ActionError({
             message: 'candidateId is a required field'
         });
     } else if (typeof input.note === 'object') {
-        const noteObject = input.note;
+        const noteObject: NoteObject = input.note;
         if (!noteObject.value || !noteObject.type) {
             throw new nango.ActionError({
                 message: 'When note is an object, it must have "value" and "type" properties, both of which are required'
@@ -45,6 +35,8 @@ export default async function runAction(nango: NangoAction, input: AshbyCreateNo
 
         return { id, createdAt, content, author };
     } catch (error: any) {
-        throw new Error(`Error in runAction: ${error.message}`);
+        throw new nango.ActionError({
+            message: `Error in runAction: ${error.message}`
+        });
     }
 }

integration-templates/ashby/ashby-jobs.ts

@@ -41,8 +41,8 @@ async function saveAllJobs(nango: NangoSync, jobslastsyncToken: string) {
         const metadata = (await nango.getMetadata()) || {};
         metadata['jobslastsyncToken'] = jobslastsyncToken;
         await nango.setMetadata(metadata);
-    } catch (error) {
-        console.error('Error occurred while fetching and saving jobs:', error);
+    } catch (error: any) {
+        throw new Error(`Error in saveAllJobs: ${error.message}`);
     }
 }
 

integration-templates/ashby/nango.yaml

@@ -1,29 +1,41 @@
 integrations:
   ashby:
-    ashby-candidates:
-      runs: every hour
-      returns:
-        - AshbyCandidate
-      description: |
-        Fetch a list of all candidates from your ashby account.
-        Details: Increamental sync, doesn't track deletes, metadata is required.
-    ashby-jobs:
-      runs: every hour
-      returns:
-        - AshbyJob
-      description: |
-        Fetch a list of all jobs from your ashby account.
-        Details: Increamental sync, doesn't track deletes, metadata is required.
-    ashby-create-application:
-      type: action
-      returns: AshbyCreateApplicationResponse
-      description: |
-        Action to consider a candidate for a job.
-    ashby-create-note:
-      type: action
-      returns: AshbyCreateNoteResponse
-      description: |
-        Action to create a note on a candidate.
+    syncs:
+      ashby-candidates:
+        runs: every hour
+        output: AshbyCandidate
+        description: |
+          Fetches a list of all candidates from your ashby account
+        metadata:
+          description: |
+            We need to save a candidatelastsyncToken to track and update candidates' synchronizations
+          scopes: candidatelastsyncToken
+        sync_type: incremental
+        endpoint: /ashby/candidates
+      ashby-jobs:
+        runs: every hour
+        output: AshbyJob
+        description: |
+          Fetches a list of all jobs from your ashby account
+        metadata:
+          description: |
+            We need to save a jobslastsyncToken to track and update jobs' synchronizations
+          scopes: jobslastsyncToken
+        sync_type: incremental
+        endpoint: /ashby/jobs
+    actions:
+      ashby-create-application:
+        output: AshbyCreateApplicationResponse
+        input: AshbyCreateCandidateInput
+        description: |
+          Action to consider a candidate for a job
+        endpoint: POST /ashby/create-application
+      ashby-create-note:
+        output: AshbyCreateNoteResponse
+        input: AshbyCreateNoteInput
+        description: |
+          Action to create a note on a candidate.
+        endpoint: POST /ashby/create-note
 models:
   AshbyCandidate:
     id: string
@@ -154,3 +166,17 @@ models:
       firstName: string
       lastName: string
       email: string
+  AshbyCreateCandidateInput:
+    candidateId: string
+    jobId: string
+    interviewPlanId: string | undefined
+    interviewStageId: string | undefined
+    sourceId: string | undefined
+    creditedToUserId: string | undefined
+  AshbyCreateNoteInput:
+    candidateId: string
+    note: string | NoteObject
+    sendNotifications: boolean | undefined
+  NoteObject:
+    value: string
+    type: string

integration-templates/bamboohr-basic/bamboohr-create-employee.ts

@@ -53,6 +53,8 @@ export default async function runAction(nango: NangoAction, input: BamboohrEmplo
             status: response.statusText
         };
     } catch (error: any) {
-        throw new Error(`Error in runAction: ${error.message}`);
+        throw new nango.ActionError({
+            message: `Error in runAction: ${error.message}`
+        });
     }
 }

integration-templates/bamboohr-basic/nango.yaml

@@ -4,19 +4,17 @@ integrations:
       bamboohr-employees:
         runs: every 6 hours
         description: |
-          Fetches employees from bamboohr.
-          Details: full sync, doesn't track deletes, metadata is not required.
+          Fetches a list of current employees from bamboohr
         output: BamboohrEmployee
         sync_type: incremental
         endpoint: /bamboohr/employees
-        scopes:
-          - default
     actions:
       bamboohr-create-employee:
         description: |
-          Action to create a new employee.
+          Action to create a new employee
         output: BamboohrCreateEmployeeResponse
-        endpoint: /bamboohr/create-employee
+        input: BamboohrEmployee
+        endpoint: POST /bamboohr/create-employee
 models:
   BamboohrEmployee:
     id: string

integration-templates/clari-copilot/nango.yaml

@@ -1,12 +1,13 @@
 integrations:
   clari-copilot:
-    clari-copilot-call:
-      runs: every hour
-      returns:
-        - ClariCopilotCall
-      description: |
-        Fetches calls from your account. For the first sync, it will go back to the past one year.
-        Details: incremental sync, doesn't track deletes, metadata is not required.
+    syncs:
+      clari-copilot-call:
+        runs: every hour
+        output: ClariCopilotCall
+        description: |
+          Fetches a list of calls from your account. For the first sync, it will go back to the past one year
+        sync_type: incremental
+        endpoint: /clari-copilot/call
 models:
   ClariCopilotCall:
     id: string

integration-templates/confluence/confluence-pages.ts

@@ -9,7 +9,7 @@ export default async function fetchData(nango: NangoSync) {
         baseUrlOverride: `https://api.atlassian.com/ex/confluence/${cloudId}`,
         endpoint: `/wiki/api/v2/pages`,
         paginate: {
-            limit: 250
+            limit: 100
         }
     };
     for await (const pageBatch of nango.paginate(proxyConfig)) {

integration-templates/confluence/confluence-spaces.ts

@@ -18,7 +18,7 @@ export default async function fetchData(nango: NangoSync) {
         endpoint: `/wiki/api/v2/spaces`,
         retries: 10,
         paginate: {
-            limit: 250
+            limit: 100
         }
     };
     for await (const spaceBatch of nango.paginate(proxyConfig)) {

integration-templates/confluence/nango.yaml

@@ -4,11 +4,15 @@ integrations:
       confluence-spaces:
         runs: every 4 hours
         output: ConfluenceSpace
+        description: |
+          Fetches a list of spaces from confluence
         sync_type: full
         endpoint: /confluence/spaces
       confluence-pages:
         runs: every 4 hours
         output: ConfluencePage
+        description: |
+          Fetches a list of pages from confluence
         sync_type: full
         endpoint: /confluence/pages
 models:

integration-templates/evaluagent/nango.yaml

@@ -4,16 +4,22 @@ integrations:
       evaluagent-users:
         runs: every day
         output: EvaluAgentUser
+        description: |
+          Fetches a list of users from evaluagent
         sync_type: full
         endpoint: /evaluagent/users
       evaluagent-groups:
         runs: every day
         output: EvaluAgentGroup
+        description: |
+          Fetches a list of groups from evaluagent
         sync_type: full
         endpoint: /evaluagent/groups
       evaluagent-roles:
         runs: every day
         output: EvaluAgentRole
+        description: |
+          Fetches a list of roles from evaluagent
         sync_type: full
         endpoint: /evaluagent/roles
 models:

integration-templates/github/github-write-file.ts

@@ -1,21 +1,6 @@
-import type { NangoSync } from './models';
+import type { NangoSync, GithubWriteFileInput, GithubWriteFileActionResult } from './models';
 
-interface FileActionInput {
-    owner: string; // Owner of the repository
-    repo: string; // Name of the repository
-    path: string; // File path including the name, e.g. 'README.md'
-    message: string; // Commit message
-    content: string; // Content to be saved, should be Base64 encoded
-    sha?: string; // SHA of the file to update, required if updating
-}
-
-interface GithubWriteFileActionResult {
-    url: string; // URL of the file
-    status: string; // 'success' or 'failure'
-    sha: string; // SHA of the file to update, required if updating
-}
-
-export default async function runAction(nango: NangoSync, input: FileActionInput): Promise<GithubWriteFileActionResult> {
+export default async function runAction(nango: NangoSync, input: GithubWriteFileInput): Promise<GithubWriteFileActionResult> {
     const endpoint = `/repos/${input.owner}/${input.repo}/contents/${input.path}`;
 
     let fileSha: string | undefined = undefined;