feat(endpoint-docs): [nan-2076] fix endpoint lint warnings (#102)

## Describe your changes ## Issue ticket number and link ## Checklist before requesting a review (skip if just adding/editing APIs & templates) - [x] I added tests, otherwise the reason is: - [x] External API requests have `retries` - [x] Pagination is used where appropriate - [ ] The built in `nango.paginate` call is used instead of a `while (true)` loop - [ ] Third party requests are NOT parallelized (this can cause issues with rate limits) - [ ] If a sync requires metadata the `nango.yaml` has `auto_start: false` - [ ] If the sync is a `full` sync then `track_deletes: true` is set - [ ] I followed the best practices and guidelines from the [Writing Integration Scripts](/NangoHQ/integration-templates/blob/main/WRITING_INTEGRATION_SCRIPTS.md) doc
NangoHQ · Nov 13, 2024 · 69da126 · 69da126
1 parent 1d44fff
commit 69da126
Show file tree

Hide file tree

Showing 119 changed files with 681 additions and 747 deletions.
diff --git a/.eslintrc b/.eslintrc
@@ -8,14 +8,14 @@
     ],
     "rules": {
         "@nangohq/custom-integrations-linting/no-console-log": "error",
-        "@nangohq/custom-integrations-linting/no-object-casting": "warn",
+        "@nangohq/custom-integrations-linting/no-object-casting": "error",
         "@nangohq/custom-integrations-linting/no-value-modification": "warn",
         "@nangohq/custom-integrations-linting/no-while-true": "warn",
         "@nangohq/custom-integrations-linting/proxy-call-retries": "error",
         //"@nangohq/custom-integrations-linting/type-external-api-responses": "warn",
         "@nangohq/custom-integrations-linting/enforce-proxy-configuration-type": "error",
         "@nangohq/custom-integrations-linting/no-try-catch-unless-explicitly-allowed": "warn",
         "@nangohq/custom-integrations-linting/query-params-in-params-object": "error",
-        "@nangohq/custom-integrations-linting/include-docs-for-endpoints": "warn",
+        "@nangohq/custom-integrations-linting/include-docs-for-endpoints": "error",
     }
 }
diff --git a/integrations/ashby/syncs/candidates.ts b/integrations/ashby/syncs/candidates.ts
@@ -15,6 +15,7 @@ async function saveAllCandidates(nango: NangoSync, candidatelastsyncToken: strin
     // eslint-disable-next-line @nangohq/custom-integrations-linting/no-while-true
     while (true) {
         const payload: ProxyConfiguration = {
+            // https://developers.ashbyhq.com/reference/candidatelist
             endpoint: '/candidate.list',
             data: {
                 ...(candidatelastsyncToken && { syncToken: candidatelastsyncToken }),

diff --git a/integrations/ashby/syncs/jobs.ts b/integrations/ashby/syncs/jobs.ts
@@ -15,6 +15,7 @@ async function saveAllJobs(nango: NangoSync, jobslastsyncToken: string) {
     // eslint-disable-next-line @nangohq/custom-integrations-linting/no-while-true
     while (true) {
         const payload: ProxyConfiguration = {
+            // https://developers.ashbyhq.com/reference/joblist
             endpoint: '/job.list',
             data: {
                 ...(jobslastsyncToken && { syncToken: jobslastsyncToken }),

diff --git a/integrations/aws-iam/actions/create-user.ts b/integrations/aws-iam/actions/create-user.ts
@@ -62,13 +62,13 @@ export default async function runAction(nango: NangoAction, input: AWSCreateUser
     );
 
     const config: ProxyConfiguration = {
+        // https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateUser.html
         endpoint: awsIAMParams.path,
         params: paramsObject,
         retries: 10
     };
 
     // Make the Create User request
-    // https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateUser.html
     const resp = await nango.post({
         ...config,
         headers: {

diff --git a/integrations/aws-iam/actions/delete-user.ts b/integrations/aws-iam/actions/delete-user.ts
@@ -27,13 +27,12 @@ export default async function runAction(nango: NangoAction, input: UserNamEntity
     const { authorizationHeader, date } = await getAWSAuthHeader(nango, awsIAMParams.method, awsIAMParams.service, awsIAMParams.path, querystring);
 
     const config: ProxyConfiguration = {
+        // https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteUser.html
         endpoint: awsIAMParams.path,
         params: awsIAMParams.params,
         retries: 10
     };
 
-    // Make the delete user request
-    // https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteUser.html
     await nango.get({
         ...config,
         headers: {

diff --git a/integrations/aws-iam/syncs/users.ts b/integrations/aws-iam/syncs/users.ts
@@ -74,6 +74,7 @@ async function* paginate<T>(nango: NangoSync, requestParams: AWSIAMRequestParams
         // Authorization header setup
         const { authorizationHeader, date } = await getAWSAuthHeader(nango, method, service, path, querystring);
         const config: ProxyConfiguration = {
+            // see docs in calling functions
             endpoint: '/',
             params: queryParams,
             headers: {
@@ -92,6 +93,7 @@ async function* paginate<T>(nango: NangoSync, requestParams: AWSIAMRequestParams
         if (response.data.ListUsersResponse?.ListUsersResult) {
             const listUsersResult = response.data.ListUsersResponse.ListUsersResult;
             const users = listUsersResult.Users;
+            // eslint-disable-next-line @nangohq/custom-integrations-linting/no-object-casting
             yield users as T[];
             nextMarker = listUsersResult.IsTruncated ? listUsersResult.Marker : undefined;
         }
@@ -100,6 +102,7 @@ async function* paginate<T>(nango: NangoSync, requestParams: AWSIAMRequestParams
         if (response.data.ListUserTagsResponse?.ListUserTagsResult) {
             const listUserTagsResult = response.data.ListUserTagsResponse.ListUserTagsResult;
             const tags = listUserTagsResult.Tags;
+            // eslint-disable-next-line @nangohq/custom-integrations-linting/no-object-casting
             yield tags as T[];
             nextMarker = listUserTagsResult.IsTruncated ? listUserTagsResult.Marker : undefined;
         }

diff --git a/integrations/checkr-partner-staging/syncs/account.ts b/integrations/checkr-partner-staging/syncs/account.ts
@@ -11,6 +11,7 @@ export default async function fetchData(nango: NangoSync): Promise<void> {
         });
     }
     const config: ProxyConfiguration = {
+        // https://docs.checkr.com/#operation/account
         endpoint: '/v1/account',
         headers: {
             Authorization: 'Basic ' + Buffer.from(access_token + ':').toString('base64')

diff --git a/integrations/checkr-partner/helpers/construct-request.ts b/integrations/checkr-partner/helpers/construct-request.ts
@@ -39,6 +39,7 @@ export async function constructRequestWithConnectionConfig(
     }
 
     const config: ProxyConfiguration = {
+        // https://docs.checkr.com/
         endpoint,
         headers: {
             Authorization: 'Basic ' + Buffer.from(access_token + ':').toString('base64')

diff --git a/integrations/clari-copilot/syncs/calls.ts b/integrations/clari-copilot/syncs/calls.ts
@@ -27,6 +27,7 @@ async function getAllCalls(nango: NangoSync) {
     const queryDate = lastSyncDate ? lastSyncDate.toISOString() : new Date(new Date().setFullYear(new Date().getFullYear() - 1)).toISOString();
 
     const config: ProxyConfiguration = {
+        // https://api-doc.copilot.clari.com/#tag/call/paths/~1calls/get
         endpoint: '/calls',
         params: { filterTimeGt: queryDate }, // filter calls after lastSyncDate
         paginate: {

diff --git a/integrations/confluence/syncs/pages.ts b/integrations/confluence/syncs/pages.ts
@@ -7,6 +7,7 @@ export default async function fetchData(nango: NangoSync) {
     const proxyConfig: ProxyConfiguration = {
         // The base URL is specific for user because of the cloud ID path param
         baseUrlOverride: `https://api.atlassian.com/ex/confluence/${cloudId}`,
+        // https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-page/#api-pages-get
         endpoint: `/wiki/api/v2/pages`,
         paginate: {
             limit: 100

diff --git a/integrations/confluence/syncs/spaces.ts b/integrations/confluence/syncs/spaces.ts
@@ -15,6 +15,7 @@ export default async function fetchData(nango: NangoSync) {
 
     const proxyConfig: ProxyConfiguration = {
         baseUrlOverride: `https://api.atlassian.com/ex/confluence/${cloudId}`, // The base URL is specific for user because of the cloud ID path param
+        // https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-space/#api-spaces-get
         endpoint: `/wiki/api/v2/spaces`,
         retries: 10,
         paginate: {

diff --git a/integrations/discourse/actions/create-category.ts b/integrations/discourse/actions/create-category.ts
@@ -8,6 +8,7 @@ export default async function runAction(nango: NangoAction, input: CreateCategor
     }
 
     const config: ProxyConfiguration = {
+        // https://docs.discourse.org/#tag/Categories/operation/createCategory
         endpoint: '/categories',
         retries: 10,
         data: input

diff --git a/integrations/discourse/actions/create-topic.ts b/integrations/discourse/actions/create-topic.ts
@@ -9,6 +9,7 @@ export default async function runAction(nango: NangoAction, input: CreateTopic):
     }
 
     const config: ProxyConfiguration = {
+        // https://docs.discourse.org/#tag/Posts/operation/createTopicPostPM
         endpoint: '/posts',
         retries: 10,
         data: input

diff --git a/integrations/discourse/actions/update-topic-status.ts b/integrations/discourse/actions/update-topic-status.ts
@@ -22,6 +22,7 @@ export default async function runAction(nango: NangoAction, input: TopicStatus):
     const { id, ...rest } = input;
 
     const config: ProxyConfiguration = {
+        // https://docs.discourse.org/#tag/Topics/operation/updateTopicStatus
         endpoint: `/t/${input.id}/status`,
         retries: 10,
         data: rest

diff --git a/integrations/discourse/helpers/paginate.ts b/integrations/discourse/helpers/paginate.ts
diff --git a/integrations/discourse/syncs/active-users.ts b/integrations/discourse/syncs/active-users.ts
@@ -1,7 +1,5 @@
-import type { NangoSync, User } from '../../models';
+import type { NangoSync, ProxyConfiguration, User } from '../../models';
 import type { DiscourseUser } from '../types';
-import paginate from '../helpers/paginate.js';
-import type { PaginationParams } from '../helpers/paginate';
 import { toUser } from '../mappers/toUser.js';
 
 /**
@@ -17,16 +15,23 @@ import { toUser } from '../mappers/toUser.js';
  * @returns A promise that resolves when the data has been successfully fetched and saved.
  */
 export default async function fetchData(nango: NangoSync): Promise<void> {
-    const config: PaginationParams = {
+    const config: ProxyConfiguration = {
+        // https://docs.discourse.org/#tag/Users/operation/adminListUsers
         endpoint: '/admin/users/list/active',
         params: {
             order: 'created',
             asc: 'true',
-            stats: true // Additional parameters for the API request can be added in here
+            stats: 'true'
+        },
+        paginate: {
+            type: 'offset',
+            offset_name_in_request: 'page',
+            offset_calculation_method: 'per-page',
+            response_path: ''
         }
     };
 
-    for await (const users of paginate<DiscourseUser>(nango, config)) {
+    for await (const users of nango.paginate<DiscourseUser>(config)) {
         await nango.batchSave<User>(users.map(toUser), 'User');
     }
 }
diff --git a/integrations/discourse/syncs/categories.ts b/integrations/discourse/syncs/categories.ts
@@ -4,6 +4,7 @@ import type { CategoryResponse } from '../types';
 export default async function fetchData(nango: NangoSync): Promise<void> {
     const config: ProxyConfiguration = {
         retries: 10,
+        // https://docs.discourse.org/#tag/Categories/operation/listCategories
         endpoint: '/categories'
     };
 

diff --git a/integrations/docusign/actions/create-user.ts b/integrations/docusign/actions/create-user.ts
@@ -30,8 +30,8 @@ export default async function runAction(nango: NangoAction, input: DocuSignCreat
     ];
 
     const config: ProxyConfiguration = {
-        // https://developers.docusign.com/docs/esign-rest-api/reference/users/users/create/
         baseUrlOverride: baseUri,
+        // https://developers.docusign.com/docs/esign-rest-api/reference/users/users/create/
         endpoint: `/restapi/v2.1/accounts/${accountId}/users`,
         data: {
             newUsers

diff --git a/integrations/docusign/actions/delete-user.ts b/integrations/docusign/actions/delete-user.ts
@@ -18,8 +18,8 @@ export default async function runAction(nango: NangoAction, input: IdEntity): Pr
     const { baseUri, accountId } = await getRequestInfo(nango);
 
     const config: ProxyConfiguration = {
-        // https://developers.docusign.com/docs/esign-rest-api/reference/users/users/delete/
         baseUrlOverride: baseUri,
+        // https://developers.docusign.com/docs/esign-rest-api/reference/users/users/delete/
         endpoint: `/restapi/v2.1/accounts/${accountId}/users`,
         data: {
             users: [{ userId: parsedInput.data.id }]

diff --git a/integrations/evaluagent/syncs/groups.ts b/integrations/evaluagent/syncs/groups.ts
@@ -12,6 +12,7 @@ interface EvaluAgentGroupResponse {
 
 export default async function fetchData(nango: NangoSync) {
     const payload: ProxyConfiguration = {
+        // https://docs.evaluagent.com/#operation/fetchGroups
         endpoint: '/v1/org/groups',
         retries: 10
     };

diff --git a/integrations/evaluagent/syncs/roles.ts b/integrations/evaluagent/syncs/roles.ts
@@ -7,6 +7,7 @@ interface EvaluAgentRoleResponse {
 
 export default async function fetchData(nango: NangoSync) {
     const payload: ProxyConfiguration = {
+        // https://docs.evaluagent.com/#operation/fetchRoles
         endpoint: '/v1/org/roles',
         retries: 10
     };

diff --git a/integrations/evaluagent/syncs/users.ts b/integrations/evaluagent/syncs/users.ts
@@ -11,6 +11,7 @@ interface EvaluAgentUserResponse {
 
 export default async function fetchData(nango: NangoSync) {
     const payload: ProxyConfiguration = {
+        // https://docs.evaluagent.com/#operation/fetchUsers
         endpoint: '/v1/org/users',
         retries: 10
     };

diff --git a/integrations/expensify/syncs/users.ts b/integrations/expensify/syncs/users.ts
@@ -10,6 +10,7 @@ export default async function fetchData(nango: NangoSync): Promise<void> {
     const { id: adminPolicyId } = policy;
 
     const config: ProxyConfiguration = {
+        // https://integrations.expensify.com/Integration-Server/doc/#policy-getter
         endpoint: `/ExpensifyIntegrations`,
         data:
             'requestJobDescription=' +

diff --git a/integrations/freshdesk/actions/create-contact.ts b/integrations/freshdesk/actions/create-contact.ts
@@ -35,6 +35,7 @@ export default async function runAction(nango: NangoAction, input: CreateContact
     }
 
     const config: ProxyConfiguration = {
+        // https://developer.freshdesk.com/api/#create_contact
         endpoint: `/api/v2/contacts`,
         data: parsedInput.data,
         retries: 10

diff --git a/integrations/freshdesk/actions/delete-contact.ts b/integrations/freshdesk/actions/delete-contact.ts
@@ -21,6 +21,7 @@ export default async function runAction(nango: NangoAction, input: IdEntity): Pr
     }
 
     const config: ProxyConfiguration = {
+        // https://developer.freshdesk.com/api/#soft_delete_contact
         endpoint: `/api/v2/contacts/${parsedInput.data.id}`,
         retries: 10
     };

diff --git a/integrations/freshdesk/syncs/articles.ts b/integrations/freshdesk/syncs/articles.ts
@@ -11,11 +11,11 @@ import { toArticle } from '../mappers/to-article.js';
  * @returns Promise that resolves when all articles are fetched and saved.
  */
 export default async function fetchData(nango: NangoSync): Promise<void> {
-    const categoriesEndpoint = '/api/v2/solutions/categories';
     const foldersEndpoint = (categoryId: number) => `/api/v2/solutions/categories/${categoryId}/folders`;
 
     const categoriesConfig: ProxyConfiguration = {
-        endpoint: categoriesEndpoint,
+        // https://developers.freshdesk.com/api/#solutions
+        endpoint: '/api/v2/solutions/categories',
         retries: 10
     };
     //https://developers.freshdesk.com/api/#solution_category_attributes
@@ -24,6 +24,7 @@ export default async function fetchData(nango: NangoSync): Promise<void> {
 
     for (const category of categories) {
         const folderConfig: ProxyConfiguration = {
+            // https://developers.freshdesk.com/api/#solutions
             endpoint: foldersEndpoint(category.id),
             retries: 10,
             paginate: {
@@ -57,6 +58,7 @@ async function fetchArticlesAndSubfolders(nango: NangoSync, folderId: number): P
 
     // Fetch subfolders.
     // Some user accounts do not support subfolders. Handling that edge case here.
+    // @allowTryCatch
     try {
         subfolders = await fetchSubfolders(nango, folderId);
     } catch (e: any) {
@@ -86,6 +88,7 @@ async function fetchArticlesAndSubfolders(nango: NangoSync, folderId: number): P
 async function fetchArticlesFromFolder(nango: NangoSync, folderId: number): Promise<void> {
     const articlesEndpoint = (folderId: number) => `/api/v2/solutions/folders/${folderId}/articles`;
     const articlesConfig: ProxyConfiguration = {
+        // https://developers.freshdesk.com/api/#solutions
         endpoint: articlesEndpoint(folderId),
         retries: 10,
         paginate: {
@@ -116,6 +119,7 @@ async function fetchArticlesFromFolder(nango: NangoSync, folderId: number): Prom
 async function fetchSubfolders(nango: NangoSync, folderId: number): Promise<FreshdeskFolder[]> {
     const subfoldersEndpoint = `/api/v2/solutions/folders/${folderId}/subfolders`;
     const subfoldersConfig: ProxyConfiguration = {
+        // https://developers.freshdesk.com/api/#solutions
         endpoint: subfoldersEndpoint,
         retries: 10,
         paginate: {

diff --git a/integrations/front/syncs/list-conversations.ts b/integrations/front/syncs/list-conversations.ts
@@ -4,6 +4,7 @@ import type { FrontConversation } from '../types';
 
 export default async function fetchData(nango: NangoSync): Promise<void> {
     const config: ProxyConfiguration = {
+        // https://dev.frontapp.com/reference/list-conversations
         endpoint: '/conversations',
         paginate: {
             type: 'link',
@@ -14,7 +15,6 @@ export default async function fetchData(nango: NangoSync): Promise<void> {
         },
         retries: 10
     };
-    // https://dev.frontapp.com/reference/list-conversations
     for await (const conversations of nango.paginate<FrontConversation>(config)) {
         const mappedConversations = conversations.map((conversation: FrontConversation) => toConversation(conversation));
         await nango.batchSave<Conversation>(mappedConversations, 'Conversation');

diff --git a/integrations/github/actions/list-repos.ts b/integrations/github/actions/list-repos.ts
@@ -36,6 +36,7 @@ async function getAll(nango: NangoSync, endpoint: string) {
     const records: any[] = [];
 
     const proxyConfig: ProxyConfiguration = {
+        // eslint-disable-next-line @nangohq/custom-integrations-linting/include-docs-for-endpoints
         endpoint,
         paginate: {
             limit: LIMIT

diff --git a/integrations/github/syncs/issues.ts b/integrations/github/syncs/issues.ts
@@ -40,6 +40,7 @@ export default async function fetchData(nango: NangoSync) {
 async function getAllRepositories(nango: NangoSync) {
     const records: any[] = [];
     const proxyConfig: ProxyConfiguration = {
+        // https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#list-repositories-for-the-authenticated-user
         endpoint: '/user/repos',
         paginate: {
             limit: LIMIT