@slates/provider 1.0.0-rc.29 → 1.0.0-rc.31

package/dist/index.cjs

@@ -52,6 +52,7 @@ __export(index_exports, {
   SlatePublicTool: () => SlatePublicTool,
   SlateSpecification: () => SlateSpecification,
   SlateTool: () => SlateTool,
+  SlateToolCategory: () => SlateToolCategory,
   SlateTrigger: () => SlateTrigger,
   SlateTriggerGroup: () => SlateTriggerGroup,
   SlateTriggerGroupBuilder: () => SlateTriggerGroupBuilder,
@@ -112,6 +113,7 @@ __export(index_exports, {
   spec: () => spec,
   statusLabelForApiError: () => statusLabelForApiError,
   tool: () => tool,
+  toolCategory: () => toolCategory,
   trigger: () => trigger,
   triggerGroup: () => triggerGroup,
   truncateApiErrorMessage: () => truncateApiErrorMessage,
@@ -2178,6 +2180,33 @@ var SlatePublicTool = class {
 };
 var publicTool = (spec2, params) => SlatePublicTool.create(spec2, params);
 
+// src/action/toolCategory.ts
+var SlateToolCategory = class _SlateToolCategory {
+  constructor(_params) {
+    this._params = _params;
+  }
+  _params;
+  static create(params) {
+    return new _SlateToolCategory(params);
+  }
+  get key() {
+    return this._params.key;
+  }
+  get name() {
+    return this._params.name;
+  }
+  get description() {
+    return this._params.description;
+  }
+  get imageUrl() {
+    return this._params.imageUrl;
+  }
+  get tools() {
+    return this._params.tools;
+  }
+};
+var toolCategory = (params) => SlateToolCategory.create(params);
+
 // src/action/trigger.ts
 var SlateTrigger = class _SlateTrigger extends SlateAction {
   #triggerGroup;
@@ -3201,16 +3230,20 @@ var setIfDefined = (target, key, value) => {
 
 // src/specification/slate.ts
 var Slate = class _Slate {
-  constructor(_spec, _actions, _adapters, _triggerGroups) {
+  constructor(_spec, _actions, _adapters, _triggerGroups, _toolCategories, _toolCategoryKeysByActionKey) {
     this._spec = _spec;
     this._actions = _actions;
     this._adapters = _adapters;
     this._triggerGroups = _triggerGroups;
+    this._toolCategories = _toolCategories;
+    this._toolCategoryKeysByActionKey = _toolCategoryKeysByActionKey;
   }
   _spec;
   _actions;
   _adapters;
   _triggerGroups;
+  _toolCategories;
+  _toolCategoryKeysByActionKey;
   static create(params) {
     let adapters = params.adapters ?? [];
     let actions = [...params.triggers, ...params.tools];
@@ -3254,7 +3287,16 @@ var Slate = class _Slate {
         `Only one trigger group may use manual webhook registration, but found: ${manualWebhookTriggerGroups.map((group) => group.key).join(", ")}`
       );
     }
-    return new _Slate(params.spec, actions, adapters, triggerGroups);
+    let toolCategories = params.toolCategories ?? [];
+    let toolCategoryKeysByActionKey = resolveToolCategoryMembership(toolCategories, actions);
+    return new _Slate(
+      params.spec,
+      actions,
+      adapters,
+      triggerGroups,
+      toolCategories,
+      toolCategoryKeysByActionKey
+    );
   }
   get spec() {
     return this._spec;
@@ -3268,6 +3310,79 @@ var Slate = class _Slate {
   get triggerGroups() {
     return this._triggerGroups ?? [];
   }
+  get toolCategories() {
+    return this._toolCategories ?? [];
+  }
+  // Keys of the tool categories an action belongs to, in declared category order.
+  getToolCategoryKeys(actionKey) {
+    return [...this._toolCategoryKeysByActionKey?.get(actionKey) ?? []];
+  }
+};
+var TOOL_CATEGORY_KEY_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+var isHttpUrl = (value) => {
+  try {
+    let url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:";
+  } catch {
+    return false;
+  }
+};
+var resolveToolCategoryMembership = (toolCategories, actions) => {
+  let effectiveActions = /* @__PURE__ */ new Map();
+  for (let action of actions) {
+    if (!effectiveActions.has(action.key)) effectiveActions.set(action.key, action);
+  }
+  let registeredActions = new Set(actions);
+  let membersByCategoryKey = /* @__PURE__ */ new Map();
+  for (let category of toolCategories) {
+    if (!TOOL_CATEGORY_KEY_PATTERN.test(category.key)) {
+      throw new SlateDeclarationError(
+        `Tool category key "${category.key}" must match ${TOOL_CATEGORY_KEY_PATTERN}`
+      );
+    }
+    if (membersByCategoryKey.has(category.key)) {
+      throw new SlateDeclarationError(
+        `Tool category "${category.key}" is registered more than once`
+      );
+    }
+    if (!category.name?.trim()) {
+      throw new SlateDeclarationError(`Tool category "${category.key}" must have a name`);
+    }
+    if (category.imageUrl !== void 0 && !isHttpUrl(category.imageUrl)) {
+      throw new SlateDeclarationError(
+        `Tool category "${category.key}" imageUrl must be an absolute http(s) URL`
+      );
+    }
+    if (!category.tools?.length) {
+      throw new SlateDeclarationError(
+        `Tool category "${category.key}" must list at least one tool`
+      );
+    }
+    let members = /* @__PURE__ */ new Set();
+    for (let tool2 of category.tools) {
+      if (!registeredActions.has(tool2)) {
+        throw new SlateDeclarationError(
+          `Tool category "${category.key}" lists tool "${tool2.key}", which is not registered in this slate`
+        );
+      }
+      if (tool2.type !== "tool") {
+        throw new SlateDeclarationError(
+          `Tool category "${category.key}" lists trigger "${tool2.key}", but only tools can belong to a tool category`
+        );
+      }
+      if (effectiveActions.get(tool2.key) === tool2) members.add(tool2.key);
+    }
+    membersByCategoryKey.set(category.key, members);
+  }
+  let keysByActionKey = /* @__PURE__ */ new Map();
+  for (let category of toolCategories) {
+    for (let actionKey of membersByCategoryKey.get(category.key) ?? []) {
+      let keys = keysByActionKey.get(actionKey) ?? [];
+      keys.push(category.key);
+      keysByActionKey.set(actionKey, keys);
+    }
+  }
+  return keysByActionKey;
 };
 
 // src/specification/specification.ts
@@ -3397,6 +3512,7 @@ var skipWebhook = (reason, response) => ({
   SlatePublicTool,
   SlateSpecification,
   SlateTool,
+  SlateToolCategory,
   SlateTrigger,
   SlateTriggerGroup,
   SlateTriggerGroupBuilder,
@@ -3457,6 +3573,7 @@ var skipWebhook = (reason, response) => ({
   spec,
   statusLabelForApiError,
   tool,
+  toolCategory,
   trigger,
   triggerGroup,
   truncateApiErrorMessage,

package/dist/index.d.cts

@@ -147,6 +147,35 @@ type SlateActionDocsReference = SlateTypedDocsReference<'docs.action.general'>;
 type SlateAuthDocsReference = SlateTypedDocsReference<'docs.auth.oauth' | 'docs.auth.oauth_scopes' | 'docs.auth.token' | 'docs.auth.service_account' | 'docs.auth.custom'>;
 
 type SlateAuthCallbackConfig = Record<string, any>;
+type SlateOauthAuthorizationUrlContext<InputType> = {
+    redirectUri: string;
+    state: string;
+    input: InputType;
+    clientId: string;
+    clientSecret: string;
+    scopes: string[];
+    config?: SlateAuthCallbackConfig;
+};
+type SlateOauthAuthorizationUrlResult<InputType> = {
+    url: string;
+    input?: InputType;
+    callbackState?: Record<string, any>;
+};
+type SlateOauthCallbackContext<InputType> = {
+    code: string;
+    state: string;
+    redirectUri: string;
+    input: InputType;
+    clientId: string;
+    clientSecret: string;
+    scopes: string[];
+    callbackParams?: Record<string, string>;
+    callbackState: Record<string, any>;
+    config?: SlateAuthCallbackConfig;
+};
+type SlateOauthAdminCallbackContext<InputType> = Omit<SlateOauthCallbackContext<InputType>, 'code'> & {
+    code?: string;
+};
 type SlateAuthWithOauth<InputType extends {}, OutputType extends {
     token: string;
     refreshToken?: string;
@@ -162,6 +191,12 @@ type SlateAuthWithOauth<InputType extends {}, OutputType extends {
     }[];
     adapters?: string[];
     syncTokensAcrossConnections?: boolean;
+    adminSetup?: {
+        getAuthorizationUrl?: (ctx: SlateOauthAuthorizationUrlContext<InputType>) => Promise<SlateOauthAuthorizationUrlResult<InputType>>;
+        handleCallback?: (ctx: SlateOauthAdminCallbackContext<InputType>) => Promise<{
+            instructions?: string;
+        }>;
+    };
     docs?: SlateAuthDocsReference[];
     inputSchema?: z.ZodType<InputType>;
     onInputChanged?: (params: {
@@ -171,31 +206,8 @@ type SlateAuthWithOauth<InputType extends {}, OutputType extends {
         input?: InputType;
     } | undefined>;
     getDefaultInput?: () => Promise<InputType>;
-    getAuthorizationUrl: (ctx: {
-        redirectUri: string;
-        state: string;
-        input: InputType;
-        clientId: string;
-        clientSecret: string;
-        scopes: string[];
-        config?: SlateAuthCallbackConfig;
-    }) => Promise<{
-        url: string;
-        input?: InputType;
-        callbackState?: Record<string, any>;
-    }>;
-    handleCallback: (ctx: {
-        code: string;
-        state: string;
-        redirectUri: string;
-        input: InputType;
-        clientId: string;
-        clientSecret: string;
-        scopes: string[];
-        callbackParams?: Record<string, string>;
-        callbackState: Record<string, any>;
-        config?: SlateAuthCallbackConfig;
-    }) => Promise<{
+    getAuthorizationUrl: (ctx: SlateOauthAuthorizationUrlContext<InputType>) => Promise<SlateOauthAuthorizationUrlResult<InputType>>;
+    handleCallback: (ctx: SlateOauthCallbackContext<InputType>) => Promise<{
         output: OutputType;
         input?: InputType;
         scopes?: string[];
@@ -857,6 +869,25 @@ declare let allOf: (...inputs: SlateActionScopesInput[]) => SlateActionScopes;
 declare let mergeScopes: (...inputs: Array<SlateActionScopes | null | undefined | false>) => SlateActionScopes | undefined;
 declare let validateScopes: (scopes: SlateActionScopes) => SlateActionScopes;
 
+interface SlateToolCategoryParameters {
+    key: string;
+    name: string;
+    description?: string;
+    imageUrl?: string;
+    tools: SlateTool<any, any, any, any>[];
+}
+declare class SlateToolCategory {
+    private readonly _params;
+    private constructor();
+    static create(params: SlateToolCategoryParameters): SlateToolCategory;
+    get key(): string;
+    get name(): string;
+    get description(): string | undefined;
+    get imageUrl(): string | undefined;
+    get tools(): SlateTool<any, any, any, any>[];
+}
+declare let toolCategory: (params: SlateToolCategoryParameters) => SlateToolCategory;
+
 interface SlateTriggerParameters<ConfigType extends {}, AuthType extends {}, InputType extends {}, OutputType extends {
     type: string;
 }> extends SlateActionParameters {
@@ -1123,6 +1154,8 @@ declare class Slate<ConfigType extends {}, AuthType extends {}> {
     private readonly _actions;
     private readonly _adapters;
     private readonly _triggerGroups;
+    private readonly _toolCategories;
+    private readonly _toolCategoryKeysByActionKey;
     private constructor();
     static create<ConfigType extends {}, AuthType extends {}>(params: {
         spec: SlateSpecification<ConfigType, AuthType>;
@@ -1130,11 +1163,14 @@ declare class Slate<ConfigType extends {}, AuthType extends {}> {
         tools: SlateTool<ConfigType, AuthType, any, any>[];
         adapters?: SlateAdapter<ConfigType, AuthType>[];
         triggerGroups?: SlateTriggerGroup<ConfigType, AuthType>[];
+        toolCategories?: SlateToolCategory[];
     }): Slate<ConfigType, AuthType>;
     get spec(): SlateSpecification<ConfigType, AuthType>;
     get actions(): (SlateTrigger<ConfigType, AuthType, any, any> | SlateTool<ConfigType, AuthType, any, any>)[];
     get adapters(): SlateAdapter<ConfigType, AuthType>[];
     get triggerGroups(): SlateTriggerGroup<ConfigType, AuthType, Record<string, unknown>>[];
+    get toolCategories(): SlateToolCategory[];
+    getToolCategoryKeys(actionKey: string): string[];
 }
 
 declare const graphWebhookHttp: {
@@ -1168,4 +1204,4 @@ declare let skipWebhook: (reason: string, response?: Response | SlateWebhookHttp
     response: Response | SlateWebhookHttpResponseInit;
 };
 
-export { API_ERROR_MAX_DETAILS, API_ERROR_MAX_MESSAGE_LENGTH, API_ERROR_TRUNCATED_PLACEHOLDER, AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX, type ApiErrorBuildHelpers, type ApiErrorDetailOptions, type ApiErrorResponse, type ApiErrorStatus, type ApiErrorTextOptions, type ApiServiceError, type AuthConfigSecretFilter, AuthConfigSecretRedactor, type BoundedApiErrorDetailOptions, type BuildApiServiceErrorOptions, type CreateHmacSignatureOptions, type DecodeApiErrorBodyOptions, GET_FILE_URL_TOOL_ID, type GetFileUrlHandler, type GetFileUrlToolInput, type GetFileUrlToolOutput, type NormalizeOAuthTokenResponseOptions, type OAuthExpiresAtOptions, type OAuthRefreshTokenFallbackMode, type OAuthTokenResponse, Slate, SlateAction, SlateActionBuilder, type SlateActionCreateParameters, type SlateActionDocsReference, type SlateActionParameters, type SlateActionParametersAny, type SlateActionParametersTool, type SlateActionParametersTrigger, type SlateActionScopeClause, type SlateActionScopeClauseInput, type SlateActionScopeValue, type SlateActionScopes, type SlateActionScopesInput, type SlateActionType, SlateAdapter, type SlateAdapterCapability, SlateAdapterSpec, type SlateAdapterSpecParameters, type SlateAddAttachmentContent, type SlateAddAttachmentInput, type SlateAttachment, type SlateAttachmentInlineContent, type SlateAttachmentUploadReferenceContent, type SlateAttachmentUrlContent, SlateAuth, type SlateAuthDocsReference, type SlateAuthType, type SlateAuthWithCustomData, type SlateAuthWithNone, type SlateAuthWithOauth, type SlateAuthWithServiceAccount, type SlateAuthWithToken, type SlateAuthenticatedAxiosDefaults, type SlateAxiosDefaults, type SlateAxiosErrorAdapter, type SlateAxiosErrorOptions, SlateConfig, type SlateConfigDocsReference, SlateContext, SlateDeclarationError, SlateDefaultPollingIntervalSeconds, type SlateDirectUploadInput, type SlateDocsReference, SlateError, type SlateErrorInput, type SlateErrorIssue, type SlateErrorKind, type SlateErrorProviderInfo, type SlateErrorResponse, type SlateErrorUpstreamInfo, type SlateGatewayEvent, type SlateLiveInvocationInfo, type SlateLogEntry, type SlateLogFields, type SlateLogListener, type SlateLogMessageInput, type SlateLogType, SlateLogger, type SlateProviderDocsReference, SlatePublicContext, SlatePublicTool, type SlatePublicToolInvocationHandler, type SlatePublicToolParameters, type SlateServiceErrorData, SlateSpecification, type SlateSpecificationCreateParameters, type SlateSpecificationParameters, SlateTool, type SlateToolInvocationHandler, type SlateToolParameters, SlateTrigger, SlateTriggerGroup, SlateTriggerGroupBuilder, type SlateTriggerGroupCreateParameters, type SlateTriggerGroupGatewayConnectHandler, type SlateTriggerGroupGatewayParameters, type SlateTriggerGroupGatewayReceiveHandler, type SlateTriggerGroupParameters, type SlateTriggerGroupPollHandler, type SlateTriggerGroupPollingParameters, type SlateTriggerGroupRoutingMatchersHandler, type SlateTriggerGroupWebhookAutoRegistrationParameters, type SlateTriggerGroupWebhookManualRegistrationParameters, type SlateTriggerGroupWebhookParameters, type SlateTriggerMappingHandler, type SlateTriggerMatchesHandler, type SlateTriggerParameters, type SlateTriggerRoutingMatcher, type SlateTypedDocsReference, type SlateWebhookHttpResponseInit, type SlateWebhookManualFinishHandler, type SlateWebhookManualSetupHandler, type SlateWebhookProcessHandler, type SlateWebhookRegisterHandler, type SlateWebhookSkipped, type SlateWebhookTarget, type SlateWebhookTargetListHandler, type SlateWebhookTargetOwnership, type SlateWebhookUnregisterHandler, type VerifyHmacSignatureOptions, adapterSpec, allOf, anyOf, auth, axios, buildApiServiceError, collectApiErrorDetails, config, createApiServiceError, createAuthenticatedAxios, createAxios, createBase64Attachment, createHmacSignature, createSlateError, createTextAttachment, createUrlAttachment, decodeApiErrorBody, extractApiErrorMessage, getApiErrorResponse, getApiErrorResponseWithBody, getApiErrorStatus, getBase64ByteLength, getCurrentContext, getFileUrlTool, getFileUrlToolInputSchema, getFileUrlToolOutputSchema, getGraphWebhookValidationResponse, getMetaWebhookVerificationResponse, getOAuthExpiresAtFromExpiresIn, getResponseHeaderValue, getServiceErrorData, graphWebhookHttp, inferSlateErrorFromAxios, isApiErrorRecord, isAxiosErrorLike, isServiceErrorData, isUrlEmbeddedCredential, looksLikeHtmlErrorBody, mapServiceErrorCode, mapServiceErrorToSlateErrorInput, mergeScopes, metaWebhookHttp, normalizeOAuthTokenResponse, pickDefined, publicTool, pushBoundedApiErrorDetail, readApiErrorText, redactUrlAttachmentSecrets, requestAxios, requestAxiosData, runWithContext, scopeClause, setIfDefined, skipWebhook, spec, statusLabelForApiError, tool, trigger, triggerGroup, truncateApiErrorMessage, uploadAttachmentDirect, validateScopes, verifyHmacSignature };
+export { API_ERROR_MAX_DETAILS, API_ERROR_MAX_MESSAGE_LENGTH, API_ERROR_TRUNCATED_PLACEHOLDER, AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX, type ApiErrorBuildHelpers, type ApiErrorDetailOptions, type ApiErrorResponse, type ApiErrorStatus, type ApiErrorTextOptions, type ApiServiceError, type AuthConfigSecretFilter, AuthConfigSecretRedactor, type BoundedApiErrorDetailOptions, type BuildApiServiceErrorOptions, type CreateHmacSignatureOptions, type DecodeApiErrorBodyOptions, GET_FILE_URL_TOOL_ID, type GetFileUrlHandler, type GetFileUrlToolInput, type GetFileUrlToolOutput, type NormalizeOAuthTokenResponseOptions, type OAuthExpiresAtOptions, type OAuthRefreshTokenFallbackMode, type OAuthTokenResponse, Slate, SlateAction, SlateActionBuilder, type SlateActionCreateParameters, type SlateActionDocsReference, type SlateActionParameters, type SlateActionParametersAny, type SlateActionParametersTool, type SlateActionParametersTrigger, type SlateActionScopeClause, type SlateActionScopeClauseInput, type SlateActionScopeValue, type SlateActionScopes, type SlateActionScopesInput, type SlateActionType, SlateAdapter, type SlateAdapterCapability, SlateAdapterSpec, type SlateAdapterSpecParameters, type SlateAddAttachmentContent, type SlateAddAttachmentInput, type SlateAttachment, type SlateAttachmentInlineContent, type SlateAttachmentUploadReferenceContent, type SlateAttachmentUrlContent, SlateAuth, type SlateAuthDocsReference, type SlateAuthType, type SlateAuthWithCustomData, type SlateAuthWithNone, type SlateAuthWithOauth, type SlateAuthWithServiceAccount, type SlateAuthWithToken, type SlateAuthenticatedAxiosDefaults, type SlateAxiosDefaults, type SlateAxiosErrorAdapter, type SlateAxiosErrorOptions, SlateConfig, type SlateConfigDocsReference, SlateContext, SlateDeclarationError, SlateDefaultPollingIntervalSeconds, type SlateDirectUploadInput, type SlateDocsReference, SlateError, type SlateErrorInput, type SlateErrorIssue, type SlateErrorKind, type SlateErrorProviderInfo, type SlateErrorResponse, type SlateErrorUpstreamInfo, type SlateGatewayEvent, type SlateLiveInvocationInfo, type SlateLogEntry, type SlateLogFields, type SlateLogListener, type SlateLogMessageInput, type SlateLogType, SlateLogger, type SlateProviderDocsReference, SlatePublicContext, SlatePublicTool, type SlatePublicToolInvocationHandler, type SlatePublicToolParameters, type SlateServiceErrorData, SlateSpecification, type SlateSpecificationCreateParameters, type SlateSpecificationParameters, SlateTool, SlateToolCategory, type SlateToolCategoryParameters, type SlateToolInvocationHandler, type SlateToolParameters, SlateTrigger, SlateTriggerGroup, SlateTriggerGroupBuilder, type SlateTriggerGroupCreateParameters, type SlateTriggerGroupGatewayConnectHandler, type SlateTriggerGroupGatewayParameters, type SlateTriggerGroupGatewayReceiveHandler, type SlateTriggerGroupParameters, type SlateTriggerGroupPollHandler, type SlateTriggerGroupPollingParameters, type SlateTriggerGroupRoutingMatchersHandler, type SlateTriggerGroupWebhookAutoRegistrationParameters, type SlateTriggerGroupWebhookManualRegistrationParameters, type SlateTriggerGroupWebhookParameters, type SlateTriggerMappingHandler, type SlateTriggerMatchesHandler, type SlateTriggerParameters, type SlateTriggerRoutingMatcher, type SlateTypedDocsReference, type SlateWebhookHttpResponseInit, type SlateWebhookManualFinishHandler, type SlateWebhookManualSetupHandler, type SlateWebhookProcessHandler, type SlateWebhookRegisterHandler, type SlateWebhookSkipped, type SlateWebhookTarget, type SlateWebhookTargetListHandler, type SlateWebhookTargetOwnership, type SlateWebhookUnregisterHandler, type VerifyHmacSignatureOptions, adapterSpec, allOf, anyOf, auth, axios, buildApiServiceError, collectApiErrorDetails, config, createApiServiceError, createAuthenticatedAxios, createAxios, createBase64Attachment, createHmacSignature, createSlateError, createTextAttachment, createUrlAttachment, decodeApiErrorBody, extractApiErrorMessage, getApiErrorResponse, getApiErrorResponseWithBody, getApiErrorStatus, getBase64ByteLength, getCurrentContext, getFileUrlTool, getFileUrlToolInputSchema, getFileUrlToolOutputSchema, getGraphWebhookValidationResponse, getMetaWebhookVerificationResponse, getOAuthExpiresAtFromExpiresIn, getResponseHeaderValue, getServiceErrorData, graphWebhookHttp, inferSlateErrorFromAxios, isApiErrorRecord, isAxiosErrorLike, isServiceErrorData, isUrlEmbeddedCredential, looksLikeHtmlErrorBody, mapServiceErrorCode, mapServiceErrorToSlateErrorInput, mergeScopes, metaWebhookHttp, normalizeOAuthTokenResponse, pickDefined, publicTool, pushBoundedApiErrorDetail, readApiErrorText, redactUrlAttachmentSecrets, requestAxios, requestAxiosData, runWithContext, scopeClause, setIfDefined, skipWebhook, spec, statusLabelForApiError, tool, toolCategory, trigger, triggerGroup, truncateApiErrorMessage, uploadAttachmentDirect, validateScopes, verifyHmacSignature };

package/dist/index.d.ts

@@ -147,6 +147,35 @@ type SlateActionDocsReference = SlateTypedDocsReference<'docs.action.general'>;
 type SlateAuthDocsReference = SlateTypedDocsReference<'docs.auth.oauth' | 'docs.auth.oauth_scopes' | 'docs.auth.token' | 'docs.auth.service_account' | 'docs.auth.custom'>;
 
 type SlateAuthCallbackConfig = Record<string, any>;
+type SlateOauthAuthorizationUrlContext<InputType> = {
+    redirectUri: string;
+    state: string;
+    input: InputType;
+    clientId: string;
+    clientSecret: string;
+    scopes: string[];
+    config?: SlateAuthCallbackConfig;
+};
+type SlateOauthAuthorizationUrlResult<InputType> = {
+    url: string;
+    input?: InputType;
+    callbackState?: Record<string, any>;
+};
+type SlateOauthCallbackContext<InputType> = {
+    code: string;
+    state: string;
+    redirectUri: string;
+    input: InputType;
+    clientId: string;
+    clientSecret: string;
+    scopes: string[];
+    callbackParams?: Record<string, string>;
+    callbackState: Record<string, any>;
+    config?: SlateAuthCallbackConfig;
+};
+type SlateOauthAdminCallbackContext<InputType> = Omit<SlateOauthCallbackContext<InputType>, 'code'> & {
+    code?: string;
+};
 type SlateAuthWithOauth<InputType extends {}, OutputType extends {
     token: string;
     refreshToken?: string;
@@ -162,6 +191,12 @@ type SlateAuthWithOauth<InputType extends {}, OutputType extends {
     }[];
     adapters?: string[];
     syncTokensAcrossConnections?: boolean;
+    adminSetup?: {
+        getAuthorizationUrl?: (ctx: SlateOauthAuthorizationUrlContext<InputType>) => Promise<SlateOauthAuthorizationUrlResult<InputType>>;
+        handleCallback?: (ctx: SlateOauthAdminCallbackContext<InputType>) => Promise<{
+            instructions?: string;
+        }>;
+    };
     docs?: SlateAuthDocsReference[];
     inputSchema?: z.ZodType<InputType>;
     onInputChanged?: (params: {
@@ -171,31 +206,8 @@ type SlateAuthWithOauth<InputType extends {}, OutputType extends {
         input?: InputType;
     } | undefined>;
     getDefaultInput?: () => Promise<InputType>;
-    getAuthorizationUrl: (ctx: {
-        redirectUri: string;
-        state: string;
-        input: InputType;
-        clientId: string;
-        clientSecret: string;
-        scopes: string[];
-        config?: SlateAuthCallbackConfig;
-    }) => Promise<{
-        url: string;
-        input?: InputType;
-        callbackState?: Record<string, any>;
-    }>;
-    handleCallback: (ctx: {
-        code: string;
-        state: string;
-        redirectUri: string;
-        input: InputType;
-        clientId: string;
-        clientSecret: string;
-        scopes: string[];
-        callbackParams?: Record<string, string>;
-        callbackState: Record<string, any>;
-        config?: SlateAuthCallbackConfig;
-    }) => Promise<{
+    getAuthorizationUrl: (ctx: SlateOauthAuthorizationUrlContext<InputType>) => Promise<SlateOauthAuthorizationUrlResult<InputType>>;
+    handleCallback: (ctx: SlateOauthCallbackContext<InputType>) => Promise<{
         output: OutputType;
         input?: InputType;
         scopes?: string[];
@@ -857,6 +869,25 @@ declare let allOf: (...inputs: SlateActionScopesInput[]) => SlateActionScopes;
 declare let mergeScopes: (...inputs: Array<SlateActionScopes | null | undefined | false>) => SlateActionScopes | undefined;
 declare let validateScopes: (scopes: SlateActionScopes) => SlateActionScopes;
 
+interface SlateToolCategoryParameters {
+    key: string;
+    name: string;
+    description?: string;
+    imageUrl?: string;
+    tools: SlateTool<any, any, any, any>[];
+}
+declare class SlateToolCategory {
+    private readonly _params;
+    private constructor();
+    static create(params: SlateToolCategoryParameters): SlateToolCategory;
+    get key(): string;
+    get name(): string;
+    get description(): string | undefined;
+    get imageUrl(): string | undefined;
+    get tools(): SlateTool<any, any, any, any>[];
+}
+declare let toolCategory: (params: SlateToolCategoryParameters) => SlateToolCategory;
+
 interface SlateTriggerParameters<ConfigType extends {}, AuthType extends {}, InputType extends {}, OutputType extends {
     type: string;
 }> extends SlateActionParameters {
@@ -1123,6 +1154,8 @@ declare class Slate<ConfigType extends {}, AuthType extends {}> {
     private readonly _actions;
     private readonly _adapters;
     private readonly _triggerGroups;
+    private readonly _toolCategories;
+    private readonly _toolCategoryKeysByActionKey;
     private constructor();
     static create<ConfigType extends {}, AuthType extends {}>(params: {
         spec: SlateSpecification<ConfigType, AuthType>;
@@ -1130,11 +1163,14 @@ declare class Slate<ConfigType extends {}, AuthType extends {}> {
         tools: SlateTool<ConfigType, AuthType, any, any>[];
         adapters?: SlateAdapter<ConfigType, AuthType>[];
         triggerGroups?: SlateTriggerGroup<ConfigType, AuthType>[];
+        toolCategories?: SlateToolCategory[];
     }): Slate<ConfigType, AuthType>;
     get spec(): SlateSpecification<ConfigType, AuthType>;
     get actions(): (SlateTrigger<ConfigType, AuthType, any, any> | SlateTool<ConfigType, AuthType, any, any>)[];
     get adapters(): SlateAdapter<ConfigType, AuthType>[];
     get triggerGroups(): SlateTriggerGroup<ConfigType, AuthType, Record<string, unknown>>[];
+    get toolCategories(): SlateToolCategory[];
+    getToolCategoryKeys(actionKey: string): string[];
 }
 
 declare const graphWebhookHttp: {
@@ -1168,4 +1204,4 @@ declare let skipWebhook: (reason: string, response?: Response | SlateWebhookHttp
     response: Response | SlateWebhookHttpResponseInit;
 };
 
-export { API_ERROR_MAX_DETAILS, API_ERROR_MAX_MESSAGE_LENGTH, API_ERROR_TRUNCATED_PLACEHOLDER, AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX, type ApiErrorBuildHelpers, type ApiErrorDetailOptions, type ApiErrorResponse, type ApiErrorStatus, type ApiErrorTextOptions, type ApiServiceError, type AuthConfigSecretFilter, AuthConfigSecretRedactor, type BoundedApiErrorDetailOptions, type BuildApiServiceErrorOptions, type CreateHmacSignatureOptions, type DecodeApiErrorBodyOptions, GET_FILE_URL_TOOL_ID, type GetFileUrlHandler, type GetFileUrlToolInput, type GetFileUrlToolOutput, type NormalizeOAuthTokenResponseOptions, type OAuthExpiresAtOptions, type OAuthRefreshTokenFallbackMode, type OAuthTokenResponse, Slate, SlateAction, SlateActionBuilder, type SlateActionCreateParameters, type SlateActionDocsReference, type SlateActionParameters, type SlateActionParametersAny, type SlateActionParametersTool, type SlateActionParametersTrigger, type SlateActionScopeClause, type SlateActionScopeClauseInput, type SlateActionScopeValue, type SlateActionScopes, type SlateActionScopesInput, type SlateActionType, SlateAdapter, type SlateAdapterCapability, SlateAdapterSpec, type SlateAdapterSpecParameters, type SlateAddAttachmentContent, type SlateAddAttachmentInput, type SlateAttachment, type SlateAttachmentInlineContent, type SlateAttachmentUploadReferenceContent, type SlateAttachmentUrlContent, SlateAuth, type SlateAuthDocsReference, type SlateAuthType, type SlateAuthWithCustomData, type SlateAuthWithNone, type SlateAuthWithOauth, type SlateAuthWithServiceAccount, type SlateAuthWithToken, type SlateAuthenticatedAxiosDefaults, type SlateAxiosDefaults, type SlateAxiosErrorAdapter, type SlateAxiosErrorOptions, SlateConfig, type SlateConfigDocsReference, SlateContext, SlateDeclarationError, SlateDefaultPollingIntervalSeconds, type SlateDirectUploadInput, type SlateDocsReference, SlateError, type SlateErrorInput, type SlateErrorIssue, type SlateErrorKind, type SlateErrorProviderInfo, type SlateErrorResponse, type SlateErrorUpstreamInfo, type SlateGatewayEvent, type SlateLiveInvocationInfo, type SlateLogEntry, type SlateLogFields, type SlateLogListener, type SlateLogMessageInput, type SlateLogType, SlateLogger, type SlateProviderDocsReference, SlatePublicContext, SlatePublicTool, type SlatePublicToolInvocationHandler, type SlatePublicToolParameters, type SlateServiceErrorData, SlateSpecification, type SlateSpecificationCreateParameters, type SlateSpecificationParameters, SlateTool, type SlateToolInvocationHandler, type SlateToolParameters, SlateTrigger, SlateTriggerGroup, SlateTriggerGroupBuilder, type SlateTriggerGroupCreateParameters, type SlateTriggerGroupGatewayConnectHandler, type SlateTriggerGroupGatewayParameters, type SlateTriggerGroupGatewayReceiveHandler, type SlateTriggerGroupParameters, type SlateTriggerGroupPollHandler, type SlateTriggerGroupPollingParameters, type SlateTriggerGroupRoutingMatchersHandler, type SlateTriggerGroupWebhookAutoRegistrationParameters, type SlateTriggerGroupWebhookManualRegistrationParameters, type SlateTriggerGroupWebhookParameters, type SlateTriggerMappingHandler, type SlateTriggerMatchesHandler, type SlateTriggerParameters, type SlateTriggerRoutingMatcher, type SlateTypedDocsReference, type SlateWebhookHttpResponseInit, type SlateWebhookManualFinishHandler, type SlateWebhookManualSetupHandler, type SlateWebhookProcessHandler, type SlateWebhookRegisterHandler, type SlateWebhookSkipped, type SlateWebhookTarget, type SlateWebhookTargetListHandler, type SlateWebhookTargetOwnership, type SlateWebhookUnregisterHandler, type VerifyHmacSignatureOptions, adapterSpec, allOf, anyOf, auth, axios, buildApiServiceError, collectApiErrorDetails, config, createApiServiceError, createAuthenticatedAxios, createAxios, createBase64Attachment, createHmacSignature, createSlateError, createTextAttachment, createUrlAttachment, decodeApiErrorBody, extractApiErrorMessage, getApiErrorResponse, getApiErrorResponseWithBody, getApiErrorStatus, getBase64ByteLength, getCurrentContext, getFileUrlTool, getFileUrlToolInputSchema, getFileUrlToolOutputSchema, getGraphWebhookValidationResponse, getMetaWebhookVerificationResponse, getOAuthExpiresAtFromExpiresIn, getResponseHeaderValue, getServiceErrorData, graphWebhookHttp, inferSlateErrorFromAxios, isApiErrorRecord, isAxiosErrorLike, isServiceErrorData, isUrlEmbeddedCredential, looksLikeHtmlErrorBody, mapServiceErrorCode, mapServiceErrorToSlateErrorInput, mergeScopes, metaWebhookHttp, normalizeOAuthTokenResponse, pickDefined, publicTool, pushBoundedApiErrorDetail, readApiErrorText, redactUrlAttachmentSecrets, requestAxios, requestAxiosData, runWithContext, scopeClause, setIfDefined, skipWebhook, spec, statusLabelForApiError, tool, trigger, triggerGroup, truncateApiErrorMessage, uploadAttachmentDirect, validateScopes, verifyHmacSignature };
+export { API_ERROR_MAX_DETAILS, API_ERROR_MAX_MESSAGE_LENGTH, API_ERROR_TRUNCATED_PLACEHOLDER, AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX, type ApiErrorBuildHelpers, type ApiErrorDetailOptions, type ApiErrorResponse, type ApiErrorStatus, type ApiErrorTextOptions, type ApiServiceError, type AuthConfigSecretFilter, AuthConfigSecretRedactor, type BoundedApiErrorDetailOptions, type BuildApiServiceErrorOptions, type CreateHmacSignatureOptions, type DecodeApiErrorBodyOptions, GET_FILE_URL_TOOL_ID, type GetFileUrlHandler, type GetFileUrlToolInput, type GetFileUrlToolOutput, type NormalizeOAuthTokenResponseOptions, type OAuthExpiresAtOptions, type OAuthRefreshTokenFallbackMode, type OAuthTokenResponse, Slate, SlateAction, SlateActionBuilder, type SlateActionCreateParameters, type SlateActionDocsReference, type SlateActionParameters, type SlateActionParametersAny, type SlateActionParametersTool, type SlateActionParametersTrigger, type SlateActionScopeClause, type SlateActionScopeClauseInput, type SlateActionScopeValue, type SlateActionScopes, type SlateActionScopesInput, type SlateActionType, SlateAdapter, type SlateAdapterCapability, SlateAdapterSpec, type SlateAdapterSpecParameters, type SlateAddAttachmentContent, type SlateAddAttachmentInput, type SlateAttachment, type SlateAttachmentInlineContent, type SlateAttachmentUploadReferenceContent, type SlateAttachmentUrlContent, SlateAuth, type SlateAuthDocsReference, type SlateAuthType, type SlateAuthWithCustomData, type SlateAuthWithNone, type SlateAuthWithOauth, type SlateAuthWithServiceAccount, type SlateAuthWithToken, type SlateAuthenticatedAxiosDefaults, type SlateAxiosDefaults, type SlateAxiosErrorAdapter, type SlateAxiosErrorOptions, SlateConfig, type SlateConfigDocsReference, SlateContext, SlateDeclarationError, SlateDefaultPollingIntervalSeconds, type SlateDirectUploadInput, type SlateDocsReference, SlateError, type SlateErrorInput, type SlateErrorIssue, type SlateErrorKind, type SlateErrorProviderInfo, type SlateErrorResponse, type SlateErrorUpstreamInfo, type SlateGatewayEvent, type SlateLiveInvocationInfo, type SlateLogEntry, type SlateLogFields, type SlateLogListener, type SlateLogMessageInput, type SlateLogType, SlateLogger, type SlateProviderDocsReference, SlatePublicContext, SlatePublicTool, type SlatePublicToolInvocationHandler, type SlatePublicToolParameters, type SlateServiceErrorData, SlateSpecification, type SlateSpecificationCreateParameters, type SlateSpecificationParameters, SlateTool, SlateToolCategory, type SlateToolCategoryParameters, type SlateToolInvocationHandler, type SlateToolParameters, SlateTrigger, SlateTriggerGroup, SlateTriggerGroupBuilder, type SlateTriggerGroupCreateParameters, type SlateTriggerGroupGatewayConnectHandler, type SlateTriggerGroupGatewayParameters, type SlateTriggerGroupGatewayReceiveHandler, type SlateTriggerGroupParameters, type SlateTriggerGroupPollHandler, type SlateTriggerGroupPollingParameters, type SlateTriggerGroupRoutingMatchersHandler, type SlateTriggerGroupWebhookAutoRegistrationParameters, type SlateTriggerGroupWebhookManualRegistrationParameters, type SlateTriggerGroupWebhookParameters, type SlateTriggerMappingHandler, type SlateTriggerMatchesHandler, type SlateTriggerParameters, type SlateTriggerRoutingMatcher, type SlateTypedDocsReference, type SlateWebhookHttpResponseInit, type SlateWebhookManualFinishHandler, type SlateWebhookManualSetupHandler, type SlateWebhookProcessHandler, type SlateWebhookRegisterHandler, type SlateWebhookSkipped, type SlateWebhookTarget, type SlateWebhookTargetListHandler, type SlateWebhookTargetOwnership, type SlateWebhookUnregisterHandler, type VerifyHmacSignatureOptions, adapterSpec, allOf, anyOf, auth, axios, buildApiServiceError, collectApiErrorDetails, config, createApiServiceError, createAuthenticatedAxios, createAxios, createBase64Attachment, createHmacSignature, createSlateError, createTextAttachment, createUrlAttachment, decodeApiErrorBody, extractApiErrorMessage, getApiErrorResponse, getApiErrorResponseWithBody, getApiErrorStatus, getBase64ByteLength, getCurrentContext, getFileUrlTool, getFileUrlToolInputSchema, getFileUrlToolOutputSchema, getGraphWebhookValidationResponse, getMetaWebhookVerificationResponse, getOAuthExpiresAtFromExpiresIn, getResponseHeaderValue, getServiceErrorData, graphWebhookHttp, inferSlateErrorFromAxios, isApiErrorRecord, isAxiosErrorLike, isServiceErrorData, isUrlEmbeddedCredential, looksLikeHtmlErrorBody, mapServiceErrorCode, mapServiceErrorToSlateErrorInput, mergeScopes, metaWebhookHttp, normalizeOAuthTokenResponse, pickDefined, publicTool, pushBoundedApiErrorDetail, readApiErrorText, redactUrlAttachmentSecrets, requestAxios, requestAxiosData, runWithContext, scopeClause, setIfDefined, skipWebhook, spec, statusLabelForApiError, tool, toolCategory, trigger, triggerGroup, truncateApiErrorMessage, uploadAttachmentDirect, validateScopes, verifyHmacSignature };

package/dist/index.module.js

@@ -2055,6 +2055,33 @@ var SlatePublicTool = class {
 };
 var publicTool = (spec2, params) => SlatePublicTool.create(spec2, params);
 
+// src/action/toolCategory.ts
+var SlateToolCategory = class _SlateToolCategory {
+  constructor(_params) {
+    this._params = _params;
+  }
+  _params;
+  static create(params) {
+    return new _SlateToolCategory(params);
+  }
+  get key() {
+    return this._params.key;
+  }
+  get name() {
+    return this._params.name;
+  }
+  get description() {
+    return this._params.description;
+  }
+  get imageUrl() {
+    return this._params.imageUrl;
+  }
+  get tools() {
+    return this._params.tools;
+  }
+};
+var toolCategory = (params) => SlateToolCategory.create(params);
+
 // src/action/trigger.ts
 var SlateTrigger = class _SlateTrigger extends SlateAction {
   #triggerGroup;
@@ -3078,16 +3105,20 @@ var setIfDefined = (target, key, value) => {
 
 // src/specification/slate.ts
 var Slate = class _Slate {
-  constructor(_spec, _actions, _adapters, _triggerGroups) {
+  constructor(_spec, _actions, _adapters, _triggerGroups, _toolCategories, _toolCategoryKeysByActionKey) {
     this._spec = _spec;
     this._actions = _actions;
     this._adapters = _adapters;
     this._triggerGroups = _triggerGroups;
+    this._toolCategories = _toolCategories;
+    this._toolCategoryKeysByActionKey = _toolCategoryKeysByActionKey;
   }
   _spec;
   _actions;
   _adapters;
   _triggerGroups;
+  _toolCategories;
+  _toolCategoryKeysByActionKey;
   static create(params) {
     let adapters = params.adapters ?? [];
     let actions = [...params.triggers, ...params.tools];
@@ -3131,7 +3162,16 @@ var Slate = class _Slate {
         `Only one trigger group may use manual webhook registration, but found: ${manualWebhookTriggerGroups.map((group) => group.key).join(", ")}`
       );
     }
-    return new _Slate(params.spec, actions, adapters, triggerGroups);
+    let toolCategories = params.toolCategories ?? [];
+    let toolCategoryKeysByActionKey = resolveToolCategoryMembership(toolCategories, actions);
+    return new _Slate(
+      params.spec,
+      actions,
+      adapters,
+      triggerGroups,
+      toolCategories,
+      toolCategoryKeysByActionKey
+    );
   }
   get spec() {
     return this._spec;
@@ -3145,6 +3185,79 @@ var Slate = class _Slate {
   get triggerGroups() {
     return this._triggerGroups ?? [];
   }
+  get toolCategories() {
+    return this._toolCategories ?? [];
+  }
+  // Keys of the tool categories an action belongs to, in declared category order.
+  getToolCategoryKeys(actionKey) {
+    return [...this._toolCategoryKeysByActionKey?.get(actionKey) ?? []];
+  }
+};
+var TOOL_CATEGORY_KEY_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+var isHttpUrl = (value) => {
+  try {
+    let url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:";
+  } catch {
+    return false;
+  }
+};
+var resolveToolCategoryMembership = (toolCategories, actions) => {
+  let effectiveActions = /* @__PURE__ */ new Map();
+  for (let action of actions) {
+    if (!effectiveActions.has(action.key)) effectiveActions.set(action.key, action);
+  }
+  let registeredActions = new Set(actions);
+  let membersByCategoryKey = /* @__PURE__ */ new Map();
+  for (let category of toolCategories) {
+    if (!TOOL_CATEGORY_KEY_PATTERN.test(category.key)) {
+      throw new SlateDeclarationError(
+        `Tool category key "${category.key}" must match ${TOOL_CATEGORY_KEY_PATTERN}`
+      );
+    }
+    if (membersByCategoryKey.has(category.key)) {
+      throw new SlateDeclarationError(
+        `Tool category "${category.key}" is registered more than once`
+      );
+    }
+    if (!category.name?.trim()) {
+      throw new SlateDeclarationError(`Tool category "${category.key}" must have a name`);
+    }
+    if (category.imageUrl !== void 0 && !isHttpUrl(category.imageUrl)) {
+      throw new SlateDeclarationError(
+        `Tool category "${category.key}" imageUrl must be an absolute http(s) URL`
+      );
+    }
+    if (!category.tools?.length) {
+      throw new SlateDeclarationError(
+        `Tool category "${category.key}" must list at least one tool`
+      );
+    }
+    let members = /* @__PURE__ */ new Set();
+    for (let tool2 of category.tools) {
+      if (!registeredActions.has(tool2)) {
+        throw new SlateDeclarationError(
+          `Tool category "${category.key}" lists tool "${tool2.key}", which is not registered in this slate`
+        );
+      }
+      if (tool2.type !== "tool") {
+        throw new SlateDeclarationError(
+          `Tool category "${category.key}" lists trigger "${tool2.key}", but only tools can belong to a tool category`
+        );
+      }
+      if (effectiveActions.get(tool2.key) === tool2) members.add(tool2.key);
+    }
+    membersByCategoryKey.set(category.key, members);
+  }
+  let keysByActionKey = /* @__PURE__ */ new Map();
+  for (let category of toolCategories) {
+    for (let actionKey of membersByCategoryKey.get(category.key) ?? []) {
+      let keys = keysByActionKey.get(actionKey) ?? [];
+      keys.push(category.key);
+      keysByActionKey.set(actionKey, keys);
+    }
+  }
+  return keysByActionKey;
 };
 
 // src/specification/specification.ts
@@ -3273,6 +3386,7 @@ export {
   SlatePublicTool,
   SlateSpecification,
   SlateTool,
+  SlateToolCategory,
   SlateTrigger,
   SlateTriggerGroup,
   SlateTriggerGroupBuilder,
@@ -3333,6 +3447,7 @@ export {
   spec,
   statusLabelForApiError,
   tool,
+  toolCategory,
   trigger,
   triggerGroup,
   truncateApiErrorMessage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slates/provider",
-  "version": "1.0.0-rc.29",
+  "version": "1.0.0-rc.31",
   "publishConfig": {
     "access": "public"
   },

package/src/action/index.ts

@@ -4,5 +4,6 @@ export * from './getFileUrlTool';
 export * from './publicTool';
 export * from './scopes';
 export * from './tool';
+export * from './toolCategory';
 export * from './trigger';
 export * from './triggerGroup';

package/src/action/toolCategory.ts

@@ -0,0 +1,40 @@
+import type { SlateTool } from './tool';
+
+export interface SlateToolCategoryParameters {
+  key: string;
+  name: string;
+  description?: string;
+  imageUrl?: string;
+  tools: SlateTool<any, any, any, any>[];
+}
+
+export class SlateToolCategory {
+  private constructor(private readonly _params: SlateToolCategoryParameters) {}
+
+  static create(params: SlateToolCategoryParameters) {
+    return new SlateToolCategory(params);
+  }
+
+  get key() {
+    return this._params.key;
+  }
+
+  get name() {
+    return this._params.name;
+  }
+
+  get description() {
+    return this._params.description;
+  }
+
+  get imageUrl() {
+    return this._params.imageUrl;
+  }
+
+  get tools() {
+    return this._params.tools;
+  }
+}
+
+export let toolCategory = (params: SlateToolCategoryParameters) =>
+  SlateToolCategory.create(params);

package/src/auth/types.ts

@@ -3,6 +3,42 @@ import type { SlateAuthDocsReference } from '../docs';
 
 type SlateAuthCallbackConfig = Record<string, any>;
 
+type SlateOauthAuthorizationUrlContext<InputType> = {
+  redirectUri: string;
+  state: string;
+  input: InputType;
+  clientId: string;
+  clientSecret: string;
+  scopes: string[];
+  config?: SlateAuthCallbackConfig;
+};
+
+type SlateOauthAuthorizationUrlResult<InputType> = {
+  url: string;
+  input?: InputType;
+  callbackState?: Record<string, any>;
+};
+
+type SlateOauthCallbackContext<InputType> = {
+  code: string;
+  state: string;
+  redirectUri: string;
+  input: InputType;
+  clientId: string;
+  clientSecret: string;
+  scopes: string[];
+  callbackParams?: Record<string, string>;
+  callbackState: Record<string, any>;
+  config?: SlateAuthCallbackConfig;
+};
+
+type SlateOauthAdminCallbackContext<InputType> = Omit<
+  SlateOauthCallbackContext<InputType>,
+  'code'
+> & {
+  code?: string;
+};
+
 export type SlateAuthWithOauth<
   InputType extends {},
   OutputType extends {
@@ -28,6 +64,18 @@ export type SlateAuthWithOauth<
   // connection of one installation, so a refresh must update all of them.
   syncTokensAcrossConnections?: boolean;
 
+  // Missing hooks fall back to the regular flow (callback output discarded).
+  // Returned instructions are markdown shown to the admin.
+  adminSetup?: {
+    getAuthorizationUrl?: (
+      ctx: SlateOauthAuthorizationUrlContext<InputType>
+    ) => Promise<SlateOauthAuthorizationUrlResult<InputType>>;
+
+    handleCallback?: (
+      ctx: SlateOauthAdminCallbackContext<InputType>
+    ) => Promise<{ instructions?: string }>;
+  };
+
   docs?: SlateAuthDocsReference[];
 
   inputSchema?: z.ZodType<InputType>;
@@ -39,32 +87,11 @@ export type SlateAuthWithOauth<
 
   getDefaultInput?: () => Promise<InputType>;
 
-  getAuthorizationUrl: (ctx: {
-    redirectUri: string;
-    state: string;
-    input: InputType;
-    clientId: string;
-    clientSecret: string;
-    scopes: string[];
-    config?: SlateAuthCallbackConfig;
-  }) => Promise<{
-    url: string;
-    input?: InputType;
-    callbackState?: Record<string, any>;
-  }>;
+  getAuthorizationUrl: (
+    ctx: SlateOauthAuthorizationUrlContext<InputType>
+  ) => Promise<SlateOauthAuthorizationUrlResult<InputType>>;
 
-  handleCallback: (ctx: {
-    code: string;
-    state: string;
-    redirectUri: string;
-    input: InputType;
-    clientId: string;
-    clientSecret: string;
-    scopes: string[];
-    callbackParams?: Record<string, string>;
-    callbackState: Record<string, any>;
-    config?: SlateAuthCallbackConfig;
-  }) => Promise<{
+  handleCallback: (ctx: SlateOauthCallbackContext<InputType>) => Promise<{
     output: OutputType;
     input?: InputType;
     scopes?: string[];

package/src/specification/slate.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { z } from 'zod';
-import { SlateTrigger, SlateTriggerGroup } from '../action';
+import { SlateTool, SlateTrigger, SlateTriggerGroup, toolCategory } from '../action';
 import { SlateAuth } from '../auth';
 import { SlateConfig } from '../config';
 import { Slate } from './slate';
@@ -117,3 +117,155 @@ describe('Slate.create', () => {
     expect(slate.triggerGroups).toEqual([]);
   });
 });
+
+let createTestTool = (spec: ReturnType<typeof createTestSpec>, key: string) =>
+  SlateTool.create(spec, { key, name: key })
+    .input(z.object({}))
+    .output(z.object({}))
+    .handleInvocation(async () => ({ output: {}, message: 'ok' }))
+    .build();
+
+describe('Slate.create tool categories', () => {
+  it('resolves membership in declared category order', () => {
+    let spec = createTestSpec();
+    let records = createTestTool(spec, 'records');
+    let report = createTestTool(spec, 'report');
+    let other = createTestTool(spec, 'other');
+
+    let slate = Slate.create({
+      spec,
+      tools: [records, report, other],
+      triggers: [],
+      toolCategories: [
+        toolCategory({ key: 'crm', name: 'CRM', tools: [records, report] }),
+        toolCategory({ key: 'reporting', name: 'Reporting', tools: [report] })
+      ]
+    });
+
+    expect(slate.toolCategories.map(category => category.key)).toEqual(['crm', 'reporting']);
+    expect(slate.getToolCategoryKeys('records')).toEqual(['crm']);
+    expect(slate.getToolCategoryKeys('report')).toEqual(['crm', 'reporting']);
+    expect(slate.getToolCategoryKeys('other')).toEqual([]);
+  });
+
+  it('ignores a shadowed duplicate tool listed in a category', () => {
+    let spec = createTestSpec();
+    let writer = createTestTool(spec, 'dup');
+    let reader = createTestTool(spec, 'dup');
+
+    let slate = Slate.create({
+      spec,
+      tools: [writer, reader],
+      triggers: [],
+      toolCategories: [toolCategory({ key: 'read', name: 'Read', tools: [reader] })]
+    });
+
+    expect(slate.getToolCategoryKeys('dup')).toEqual([]);
+  });
+
+  it('returns a copy of the membership list', () => {
+    let spec = createTestSpec();
+    let tool = createTestTool(spec, 'a');
+    let slate = Slate.create({
+      spec,
+      tools: [tool],
+      triggers: [],
+      toolCategories: [toolCategory({ key: 'crm', name: 'CRM', tools: [tool] })]
+    });
+
+    slate.getToolCategoryKeys('a').push('mutated');
+    expect(slate.getToolCategoryKeys('a')).toEqual(['crm']);
+  });
+
+  it('defaults to no categories', () => {
+    let spec = createTestSpec();
+    let slate = Slate.create({ spec, tools: [createTestTool(spec, 'a')], triggers: [] });
+
+    expect(slate.toolCategories).toEqual([]);
+    expect(slate.getToolCategoryKeys('a')).toEqual([]);
+  });
+
+  it('rejects duplicate and malformed category keys', () => {
+    let spec = createTestSpec();
+    let tool = createTestTool(spec, 'a');
+
+    expect(() =>
+      Slate.create({
+        spec,
+        tools: [tool],
+        triggers: [],
+        toolCategories: [
+          toolCategory({ key: 'crm', name: 'CRM', tools: [tool] }),
+          toolCategory({ key: 'crm', name: 'CRM again', tools: [tool] })
+        ]
+      })
+    ).toThrow('Tool category "crm" is registered more than once');
+
+    expect(() =>
+      Slate.create({
+        spec,
+        tools: [tool],
+        triggers: [],
+        toolCategories: [toolCategory({ key: 'Zoho CRM', name: 'CRM', tools: [tool] })]
+      })
+    ).toThrow('Tool category key "Zoho CRM" must match');
+  });
+
+  it('accepts http(s) category images and rejects anything else', () => {
+    let spec = createTestSpec();
+    let tool = createTestTool(spec, 'a');
+    let slate = Slate.create({
+      spec,
+      tools: [tool],
+      triggers: [],
+      toolCategories: [
+        toolCategory({
+          key: 'crm',
+          name: 'CRM',
+          imageUrl: 'https://cdn.test/crm.svg',
+          tools: [tool]
+        })
+      ]
+    });
+    expect(slate.toolCategories[0]?.imageUrl).toBe('https://cdn.test/crm.svg');
+
+    expect(() =>
+      Slate.create({
+        spec,
+        tools: [tool],
+        triggers: [],
+        toolCategories: [
+          toolCategory({ key: 'crm', name: 'CRM', imageUrl: 'crm.svg', tools: [tool] })
+        ]
+      })
+    ).toThrow('Tool category "crm" imageUrl must be an absolute http(s) URL');
+  });
+
+  it('rejects a category without tools', () => {
+    let spec = createTestSpec();
+
+    expect(() =>
+      Slate.create({
+        spec,
+        tools: [createTestTool(spec, 'a')],
+        triggers: [],
+        toolCategories: [toolCategory({ key: 'crm', name: 'CRM', tools: [] })]
+      })
+    ).toThrow('Tool category "crm" must list at least one tool');
+  });
+
+  it('rejects unregistered member tools', () => {
+    let spec = createTestSpec();
+
+    expect(() =>
+      Slate.create({
+        spec,
+        tools: [],
+        triggers: [],
+        toolCategories: [
+          toolCategory({ key: 'crm', name: 'CRM', tools: [createTestTool(spec, 'stray')] })
+        ]
+      })
+    ).toThrow('Tool category "crm" lists tool "stray", which is not registered in this slate');
+  });
+});

package/src/specification/slate.ts

@@ -1,4 +1,4 @@
-import type { SlateTool, SlateTrigger, SlateTriggerGroup } from '../action';
+import type { SlateTool, SlateToolCategory, SlateTrigger, SlateTriggerGroup } from '../action';
 import type { SlateAdapter } from '../adapter';
 import { SlateDeclarationError } from '../error';
 import type { SlateSpecification } from './specification';
@@ -11,7 +11,9 @@ export class Slate<ConfigType extends {}, AuthType extends {}> {
       | SlateTool<ConfigType, AuthType, any, any>
     )[],
     private readonly _adapters: SlateAdapter<ConfigType, AuthType>[],
-    private readonly _triggerGroups: SlateTriggerGroup<ConfigType, AuthType>[]
+    private readonly _triggerGroups: SlateTriggerGroup<ConfigType, AuthType>[],
+    private readonly _toolCategories: SlateToolCategory[],
+    private readonly _toolCategoryKeysByActionKey: Map<string, string[]>
   ) {}
 
   static create<ConfigType extends {}, AuthType extends {}>(params: {
@@ -20,6 +22,7 @@ export class Slate<ConfigType extends {}, AuthType extends {}> {
     tools: SlateTool<ConfigType, AuthType, any, any>[];
     adapters?: SlateAdapter<ConfigType, AuthType>[];
     triggerGroups?: SlateTriggerGroup<ConfigType, AuthType>[];
+    toolCategories?: SlateToolCategory[];
   }) {
     let adapters = params.adapters ?? [];
     let actions = [...params.triggers, ...params.tools];
@@ -71,7 +74,17 @@ export class Slate<ConfigType extends {}, AuthType extends {}> {
       );
     }
 
-    return new Slate(params.spec, actions, adapters, triggerGroups);
+    let toolCategories = params.toolCategories ?? [];
+    let toolCategoryKeysByActionKey = resolveToolCategoryMembership(toolCategories, actions);
+
+    return new Slate(
+      params.spec,
+      actions,
+      adapters,
+      triggerGroups,
+      toolCategories,
+      toolCategoryKeysByActionKey
+    );
   }
 
   get spec() {
@@ -89,4 +102,93 @@ export class Slate<ConfigType extends {}, AuthType extends {}> {
   get triggerGroups() {
     return this._triggerGroups ?? [];
   }
+
+  get toolCategories() {
+    return this._toolCategories ?? [];
+  }
+
+  // Keys of the tool categories an action belongs to, in declared category order.
+  getToolCategoryKeys(actionKey: string) {
+    return [...(this._toolCategoryKeysByActionKey?.get(actionKey) ?? [])];
+  }
 }
+
+let TOOL_CATEGORY_KEY_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+let isHttpUrl = (value: string) => {
+  try {
+    let url = new URL(value);
+    return url.protocol === 'https:' || url.protocol === 'http:';
+  } catch {
+    return false;
+  }
+};
+
+type SlateActionAny = SlateTool<any, any, any, any> | SlateTrigger<any, any, any, any>;
+
+let resolveToolCategoryMembership = (
+  toolCategories: SlateToolCategory[],
+  actions: SlateActionAny[]
+) => {
+  // Actions resolve by key and the first registered one wins, so a shadowed duplicate must
+  // not lend its categories to the action that actually runs.
+  let effectiveActions = new Map<string, SlateActionAny>();
+  for (let action of actions) {
+    if (!effectiveActions.has(action.key)) effectiveActions.set(action.key, action);
+  }
+  let registeredActions = new Set(actions);
+  let membersByCategoryKey = new Map<string, Set<string>>();
+
+  for (let category of toolCategories) {
+    if (!TOOL_CATEGORY_KEY_PATTERN.test(category.key)) {
+      throw new SlateDeclarationError(
+        `Tool category key "${category.key}" must match ${TOOL_CATEGORY_KEY_PATTERN}`
+      );
+    }
+    if (membersByCategoryKey.has(category.key)) {
+      throw new SlateDeclarationError(
+        `Tool category "${category.key}" is registered more than once`
+      );
+    }
+    if (!category.name?.trim()) {
+      throw new SlateDeclarationError(`Tool category "${category.key}" must have a name`);
+    }
+    if (category.imageUrl !== undefined && !isHttpUrl(category.imageUrl)) {
+      throw new SlateDeclarationError(
+        `Tool category "${category.key}" imageUrl must be an absolute http(s) URL`
+      );
+    }
+    if (!category.tools?.length) {
+      throw new SlateDeclarationError(
+        `Tool category "${category.key}" must list at least one tool`
+      );
+    }
+
+    let members = new Set<string>();
+    for (let tool of category.tools) {
+      if (!registeredActions.has(tool)) {
+        throw new SlateDeclarationError(
+          `Tool category "${category.key}" lists tool "${tool.key}", which is not registered in this slate`
+        );
+      }
+      if (tool.type !== 'tool') {
+        throw new SlateDeclarationError(
+          `Tool category "${category.key}" lists trigger "${tool.key}", but only tools can belong to a tool category`
+        );
+      }
+      if (effectiveActions.get(tool.key) === tool) members.add(tool.key);
+    }
+    membersByCategoryKey.set(category.key, members);
+  }
+
+  let keysByActionKey = new Map<string, string[]>();
+  for (let category of toolCategories) {
+    for (let actionKey of membersByCategoryKey.get(category.key) ?? []) {
+      let keys = keysByActionKey.get(actionKey) ?? [];
+      keys.push(category.key);
+      keysByActionKey.set(actionKey, keys);
+    }
+  }
+
+  return keysByActionKey;
+};