Refactor arguments and type tests for admin.functions.* APIs.

packages/web-api/src/methods.ts

@@ -270,6 +270,7 @@ import type { AdminAuthPolicyAssignEntitiesArguments, AdminAuthPolicyGetEntities
 import type { AdminBarriersCreateArguments, AdminBarriersDeleteArguments, AdminBarriersListArguments, AdminBarriersUpdateArguments } from './types/request/admin/barriers';
 import type { AdminConversationsArchiveArguments, AdminConversationsBulkArchiveArguments, AdminConversationsBulkDeleteArguments, AdminConversationsBulkMoveArguments, AdminConversationsConvertToPrivateArguments, AdminConversationsConvertToPublicArguments, AdminConversationsCreateArguments, AdminConversationsDeleteArguments, AdminConversationsDisconnectSharedArguments, AdminConversationsEKMListOriginalConnectedChannelInfoArguments, AdminConversationsGetConversationPrefsArguments, AdminConversationsGetCustomRetentionArguments, AdminConversationsGetTeamsArguments, AdminConversationsInviteArguments, AdminConversationsLookupArguments, AdminConversationsRemoveCustomRetentionArguments, AdminConversationsRenameArguments, AdminConversationsRestrictAccessAddGroupArguments, AdminConversationsRestrictAccessListGroupsArguments, AdminConversationsRestrictAccessRemoveGroupArguments, AdminConversationsSearchArguments, AdminConversationsSetConversationPrefsArguments, AdminConversationsSetCustomRetentionArguments, AdminConversationsSetTeamsArguments, AdminConversationsUnarchiveArguments } from './types/request/admin/conversations';
 import type { AdminEmojiAddArguments, AdminEmojiAddAliasArguments, AdminEmojiListArguments, AdminEmojiRemoveArguments, AdminEmojiRenameArguments } from './types/request/admin/emoji';
+import type { AdminFunctionsListArguments, AdminFunctionsPermissionsLookupArguments, AdminFunctionsPermissionsSetArguments } from './types/request/admin/functions';
 
 /**
  * Generic method definition
@@ -654,9 +655,23 @@ export abstract class Methods extends EventEmitter<WebClientEvent> {
       rename: bindApiCall<AdminEmojiRenameArguments, AdminEmojiRenameResponse>(this, 'admin.emoji.rename'),
     },
     functions: {
+      /**
+       * @description Look up functions by a set of apps.
+       * @see {@link https://api.slack.com/methods/admin.functions.list `admin.functions.list` API reference}.
+       */
       list: bindApiCall<AdminFunctionsListArguments, AdminFunctionsListResponse>(this, 'admin.functions.list'),
       permissions: {
+        /**
+         * @description Lookup the visibility of multiple Slack functions and include the users if
+         * it is limited to particular named entities.
+         * @see {@link https://api.slack.com/methods/admin.functions.permissions.lookup `admin.functions.permissions.lookup` API reference}.
+         */
         lookup: bindApiCall<AdminFunctionsPermissionsLookupArguments, AdminFunctionsPermissionsLookupResponse>(this, 'admin.functions.permissions.lookup'),
+        /**
+         * @description Set the visibility of a Slack function and define the users or workspaces if
+         * it is set to named_entities.
+         * @see {@link https://api.slack.com/methods/admin.functions.permissions.set `admin.functions.permissions.set` API reference}.
+         */
         set: bindApiCall<AdminFunctionsPermissionsSetArguments, AdminFunctionsPermissionsSetResponse>(this, 'admin.functions.permissions.set'),
       },
     },
@@ -1685,22 +1700,6 @@ export abstract class Methods extends EventEmitter<WebClientEvent> {
     updateStep: bindApiCall<WorkflowsUpdateStepArguments, WorkflowsUpdateStepResponse>(this, 'workflows.updateStep'),
   };
 }
-// https://api.slack.com/methods/admin.functions.list
-export interface AdminFunctionsListArguments extends TokenOverridable, CursorPaginationEnabled {
-  app_ids: string[];
-  team_id?: string;
-}
-// https://api.slack.com/methods/admin.functions.permissions.lookup
-export interface AdminFunctionsPermissionsLookupArguments
-  extends TokenOverridable {
-  function_ids: string[];
-}
-// https://api.slack.com/methods/admin.functions.permissions.set
-export interface AdminFunctionsPermissionsSetArguments extends TokenOverridable {
-  function_id: string;
-  visibility: string;
-  user_ids?: string[];
-}
 // https://api.slack.com/methods/admin.inviteRequests.approve
 export interface AdminInviteRequestsApproveArguments
   extends TokenOverridable {

packages/web-api/src/types/request/admin/functions.ts

@@ -0,0 +1,26 @@
+import type { CursorPaginationEnabled, TokenOverridable } from '../common';
+
+// https://api.slack.com/methods/admin.functions.list
+export interface AdminFunctionsListArguments extends TokenOverridable, CursorPaginationEnabled {
+  /** @description Array of app IDs to get functions for; max 50. */
+  app_ids: string[];
+  /** @description The team context to retrieve functions from. */
+  team_id?: string;
+}
+
+// https://api.slack.com/methods/admin.functions.permissions.lookup
+export interface AdminFunctionsPermissionsLookupArguments
+  extends TokenOverridable {
+  /** @description An array of function IDs to get permissions for. */
+  function_ids: [string, ...string[]];
+}
+
+// https://api.slack.com/methods/admin.functions.permissions.set
+export interface AdminFunctionsPermissionsSetArguments extends TokenOverridable {
+  /** @description The function ID to set permissions for. */
+  function_id: string;
+  /** @description The function visibility. */
+  visibility: 'everyone' | 'app_collaborators' | 'named_entities' | 'no_one';
+  /** @description List of user IDs to allow for `named_entities` visibility. */
+  user_ids?: string[];
+}

packages/web-api/test/types/methods/admin.functions.test-d.ts

@@ -0,0 +1,41 @@
+import { expectAssignable, expectError } from 'tsd';
+import { WebClient } from '../../../src/WebClient';
+
+const web = new WebClient('TOKEN');
+
+// admin.functions.list
+// -- sad path
+expectError(web.admin.functions.list()); // lacking argument
+expectError(web.admin.functions.list({})); // empty argument
+// -- happy path
+expectAssignable<Parameters<typeof web.admin.functions.list>>([{
+  app_ids: [],
+}]);
+
+// admin.functions.permissions.lookup
+// -- sad path
+expectError(web.admin.functions.permissions.lookup()); // lacking argument
+expectError(web.admin.functions.permissions.lookup({})); // empty argument
+expectError(web.admin.functions.permissions.lookup({
+  function_ids: [], // must provide at least 1
+}));
+// -- happy path
+expectAssignable<Parameters<typeof web.admin.functions.permissions.lookup>>([{
+  function_ids: ['F1234'],
+}]);
+
+// admin.functions.permissions.set
+// -- sad path
+expectError(web.admin.functions.permissions.set()); // lacking argument
+expectError(web.admin.functions.permissions.set({})); // empty argument
+expectError(web.admin.functions.permissions.set({
+  function_id: 'F1234', // missing visibility
+}));
+expectError(web.admin.functions.permissions.set({
+  visibility: 'named_entities', // missing function_id
+}));
+// -- happy path
+expectAssignable<Parameters<typeof web.admin.functions.permissions.set>>([{
+  function_id: 'F1234',
+  visibility: 'named_entities',
+}]);