@shipfox/api-integration-slack 4.0.0

package/src/db/installations.ts

@@ -0,0 +1,141 @@
+import {isUniqueViolation} from '@shipfox/node-drizzle';
+import {eq} from 'drizzle-orm';
+import {
+  SlackConnectionAlreadyLinkedError,
+  SlackInstallationAlreadyLinkedError,
+} from '#core/errors.js';
+import {db} from './db.js';
+import {slackInstallations, toSlackInstallation} from './schema/installations.js';
+
+export type SlackInstallationStatus = 'installed' | 'revoked';
+
+export interface SlackInstallation {
+  id: string;
+  connectionId: string;
+  teamId: string;
+  teamName: string;
+  appId: string;
+  botUserId: string;
+  scopes: string[];
+  status: SlackInstallationStatus;
+  tokenExpiresAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface UpsertSlackInstallationParams {
+  connectionId: string;
+  teamId: string;
+  teamName: string;
+  appId: string;
+  botUserId: string;
+  scopes: string[];
+  status: SlackInstallationStatus;
+  tokenExpiresAt?: Date | null | undefined;
+}
+
+type SlackDb = ReturnType<typeof db>;
+type SlackTx = Parameters<Parameters<SlackDb['transaction']>[0]>[0];
+
+export async function upsertSlackInstallation(
+  params: UpsertSlackInstallationParams,
+  options: {tx?: unknown} = {},
+): Promise<SlackInstallation> {
+  const executor = (options.tx ?? db()) as SlackDb | SlackTx;
+  const now = new Date();
+  let row: typeof slackInstallations.$inferSelect | undefined;
+
+  try {
+    [row] = await executor
+      .insert(slackInstallations)
+      .values({
+        connectionId: params.connectionId,
+        teamId: params.teamId,
+        teamName: params.teamName,
+        appId: params.appId,
+        botUserId: params.botUserId,
+        scopes: params.scopes,
+        status: params.status,
+        tokenExpiresAt: params.tokenExpiresAt ?? null,
+      })
+      .onConflictDoUpdate({
+        target: slackInstallations.teamId,
+        setWhere: eq(slackInstallations.connectionId, params.connectionId),
+        set: {
+          connectionId: params.connectionId,
+          teamId: params.teamId,
+          teamName: params.teamName,
+          appId: params.appId,
+          botUserId: params.botUserId,
+          scopes: params.scopes,
+          status: params.status,
+          tokenExpiresAt: params.tokenExpiresAt ?? null,
+          updatedAt: now,
+        },
+      })
+      .returning();
+  } catch (error) {
+    if (isUniqueViolation(error, 'integrations_slack_installations_connection_unique')) {
+      throw new SlackConnectionAlreadyLinkedError(params.connectionId);
+    }
+    throw error;
+  }
+
+  if (!row) throw new SlackInstallationAlreadyLinkedError(params.teamId);
+  return toSlackInstallation(row);
+}
+
+export async function getSlackInstallationByTeamId(
+  teamId: string,
+  options: {tx?: unknown} = {},
+): Promise<SlackInstallation | undefined> {
+  const executor = (options.tx ?? db()) as SlackDb | SlackTx;
+  const rows = await executor
+    .select()
+    .from(slackInstallations)
+    .where(eq(slackInstallations.teamId, teamId))
+    .limit(1);
+  const row = rows[0];
+  if (!row) return undefined;
+  return toSlackInstallation(row);
+}
+
+export async function getSlackInstallationByConnectionId(
+  connectionId: string,
+  options: {tx?: unknown} = {},
+): Promise<SlackInstallation | undefined> {
+  const executor = (options.tx ?? db()) as SlackDb | SlackTx;
+  const rows = await executor
+    .select()
+    .from(slackInstallations)
+    .where(eq(slackInstallations.connectionId, connectionId))
+    .limit(1);
+  const row = rows[0];
+  if (!row) return undefined;
+  return toSlackInstallation(row);
+}
+
+export async function deleteSlackInstallationByConnectionId(
+  connectionId: string,
+  options: {tx?: unknown} = {},
+): Promise<boolean> {
+  const executor = (options.tx ?? db()) as SlackDb | SlackTx;
+  const result = await executor
+    .delete(slackInstallations)
+    .where(eq(slackInstallations.connectionId, connectionId));
+  return (result.rowCount ?? 0) > 0;
+}
+
+export async function markSlackInstallationRevoked(
+  connectionId: string,
+  options: {tx?: unknown} = {},
+): Promise<SlackInstallation | undefined> {
+  const executor = (options.tx ?? db()) as SlackDb | SlackTx;
+  const [row] = await executor
+    .update(slackInstallations)
+    .set({status: 'revoked', updatedAt: new Date()})
+    .where(eq(slackInstallations.connectionId, connectionId))
+    .returning();
+  if (!row) return undefined;
+  return toSlackInstallation(row);
+}

package/src/db/migrations.ts

@@ -0,0 +1,4 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+export const migrationsPath = resolve(dirname(fileURLToPath(import.meta.url)), '../../drizzle');

package/src/db/schema/common.ts

@@ -0,0 +1,3 @@
+import {pgTableCreator} from 'drizzle-orm/pg-core';
+
+export const pgTable = pgTableCreator((name) => `integrations_slack_${name}`);

package/src/db/schema/installations.ts

@@ -0,0 +1,44 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {jsonb, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import type {SlackInstallation} from '#db/installations.js';
+import {pgTable} from './common.js';
+
+export const slackInstallations = pgTable(
+  'installations',
+  {
+    id: uuidv7PrimaryKey(),
+    connectionId: uuid('connection_id').notNull(),
+    teamId: text('team_id').notNull(),
+    teamName: text('team_name').notNull(),
+    appId: text('app_id').notNull(),
+    botUserId: text('bot_user_id').notNull(),
+    scopes: jsonb('scopes').notNull().$type<string[]>(),
+    status: text('status').notNull().$type<SlackInstallation['status']>(),
+    tokenExpiresAt: timestamp('token_expires_at', {withTimezone: true}),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('integrations_slack_installations_connection_unique').on(table.connectionId),
+    uniqueIndex('integrations_slack_installations_team_unique').on(table.teamId),
+  ],
+);
+
+export type SlackInstallationDb = typeof slackInstallations.$inferSelect;
+export type SlackInstallationCreateDb = typeof slackInstallations.$inferInsert;
+
+export function toSlackInstallation(row: SlackInstallationDb): SlackInstallation {
+  return {
+    id: row.id,
+    connectionId: row.connectionId,
+    teamId: row.teamId,
+    teamName: row.teamName,
+    appId: row.appId,
+    botUserId: row.botUserId,
+    scopes: row.scopes,
+    status: row.status,
+    tokenExpiresAt: row.tokenExpiresAt,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}

package/src/index.test.ts

@@ -0,0 +1,25 @@
+import {createSlackIntegrationProvider, slackAgentToolCatalog} from '#index.js';
+
+describe('createSlackIntegrationProvider', () => {
+  it('does not mount webhook routes without route options', () => {
+    const provider = createSlackIntegrationProvider();
+
+    expect(provider.routes).toEqual([]);
+  });
+
+  it('rejects incomplete webhook route options', () => {
+    expect(() => createSlackIntegrationProvider({routes: {}})).toThrow(
+      'Slack webhook routes require every core persistence dependency',
+    );
+  });
+
+  it('exposes the Slack agent-tools adapter when token access is configured', () => {
+    const provider = createSlackIntegrationProvider({
+      agentTools: {tokenStore: {getAccessToken: async () => 'xoxb-token'}},
+    });
+
+    const catalog = provider.adapters.agent_tools?.catalog();
+
+    expect(catalog).toBe(slackAgentToolCatalog);
+  });
+});

package/src/index.ts

@@ -0,0 +1,196 @@
+import {SLACK_PROVIDER} from '@shipfox/api-integration-slack-dto';
+import type {RouteGroup} from '@shipfox/node-fastify';
+import {createSlackApiClient, type SlackApiClient} from '#api/client.js';
+import {config} from '#config.js';
+import {SlackAgentToolsProvider} from '#core/agent-tools-provider.js';
+import type {SlackTokenStore} from '#core/tokens.js';
+import {closeDb, db} from '#db/db.js';
+import {getSlackInstallationByConnectionId} from '#db/installations.js';
+import {migrationsPath} from '#db/migrations.js';
+import {
+  type CreateSlackIntegrationRoutesOptions,
+  createSlackIntegrationRoutes,
+} from '#presentation/routes/install.js';
+import {
+  type CreateSlackWebhookRoutesOptions,
+  createSlackWebhookRoutes,
+} from '#presentation/routes/webhooks.js';
+
+type SlackInstallationRouteOptions = Omit<
+  CreateSlackIntegrationRoutesOptions,
+  'slack' | 'connectionCapabilities'
+>;
+type SlackRouteOptions = Partial<SlackInstallationRouteOptions> &
+  Partial<CreateSlackWebhookRoutesOptions>;
+
+export type {SlackProvider} from '@shipfox/api-integration-slack-dto';
+export type {SlackApiClient, SlackAuthorization, SlackWebApiResponse} from '#api/client.js';
+export {createSlackApiClient} from '#api/client.js';
+export type {
+  SlackAgentToolCatalogEntry,
+  SlackAgentToolId,
+  SlackAgentToolRequiredScope,
+} from '#core/agent-tools.js';
+export {
+  SLACK_TOOL_METHODS,
+  slackAgentToolCatalog,
+  slackAgentToolSelectionCatalog,
+} from '#core/agent-tools.js';
+export type {
+  SlackAgentToolsProviderOptions,
+  SlackToolCallResult,
+} from '#core/agent-tools-provider.js';
+export {SlackAgentToolsProvider} from '#core/agent-tools-provider.js';
+export {
+  type DisconnectSlackInstallationParams,
+  disconnectSlackInstallation,
+} from '#core/disconnect.js';
+export {
+  SlackAccessTokenUnavailableError,
+  type SlackAccessTokenUnavailableReason,
+  SlackAuthorizationScopeMismatchError,
+  SlackBotTokenMissingError,
+  SlackConnectionAlreadyLinkedError,
+  SlackConnectionNotFoundError,
+  SlackEnterpriseInstallUnsupportedError,
+  SlackInstallationAlreadyLinkedError,
+  SlackInstallStateActorMismatchError,
+  SlackInstallStateError,
+  SlackIntegrationProviderError,
+  SlackOAuthCallbackError,
+} from '#core/errors.js';
+export type {ConnectSlackInstallationInput, HandleSlackCallbackParams} from '#core/install.js';
+export {handleSlackCallback, handleSlackOAuthCallbackError} from '#core/install.js';
+export {
+  assertSlackAuthorizationScopes,
+  formatSlackBotScopes,
+  SLACK_BOT_SCOPES,
+} from '#core/scopes.js';
+export type {VerifySlackSignatureParams} from '#core/signature.js';
+export {verifySlackSignature} from '#core/signature.js';
+export type {SlackInstallStateClaims} from '#core/state.js';
+export {signSlackInstallState, verifySlackInstallState} from '#core/state.js';
+export type {
+  CreateSlackTokenStoreParams,
+  GetSlackAccessTokenParams,
+  SlackConnectionResolverResult,
+  SlackSecretsStore,
+  SlackTokenStore,
+  StoreSlackTokensParams,
+} from '#core/tokens.js';
+export {createSlackTokenStore, slackSecretsNamespace} from '#core/tokens.js';
+export type {
+  HandleSlackCommandParams,
+  HandleSlackEventParams,
+  SlackWebhookOutcome,
+} from '#core/webhook.js';
+export {handleSlackCommand, handleSlackEvent, isSelfAuthoredSlackEvent} from '#core/webhook.js';
+export type {
+  SlackInstallation,
+  SlackInstallationStatus,
+  UpsertSlackInstallationParams,
+} from '#db/installations.js';
+export {
+  deleteSlackInstallationByConnectionId,
+  getSlackInstallationByConnectionId,
+  getSlackInstallationByTeamId,
+  markSlackInstallationRevoked,
+  upsertSlackInstallation,
+} from '#db/installations.js';
+export {
+  type CreateSlackE2eRoutesOptions,
+  createSlackE2eRoutes,
+} from '#presentation/e2eRoutes/index.js';
+export {
+  type CreateSlackWebhookRoutesOptions,
+  createSlackWebhookRoutes,
+  SLACK_WEBHOOK_BODY_LIMIT,
+  SLASH_COMMAND_ACK,
+} from '#presentation/routes/webhooks.js';
+export {closeDb, config, db, migrationsPath};
+
+export interface CreateSlackIntegrationProviderOptions {
+  slack?: SlackApiClient | undefined;
+  agentTools?: {tokenStore: Pick<SlackTokenStore, 'getAccessToken'>} | undefined;
+  getSlackInstallationByConnectionId?: typeof getSlackInstallationByConnectionId | undefined;
+  routes?: SlackRouteOptions | undefined;
+}
+
+export function createSlackIntegrationProvider(
+  options: CreateSlackIntegrationProviderOptions = {},
+) {
+  const slack = options.slack ?? createSlackApiClient();
+  const getInstallationByConnectionId =
+    options.getSlackInstallationByConnectionId ?? getSlackInstallationByConnectionId;
+  const adapters = options.agentTools
+    ? {
+        agent_tools: new SlackAgentToolsProvider({
+          slack,
+          tokenStore: options.agentTools.tokenStore,
+        }),
+      }
+    : {};
+  if (
+    options.routes &&
+    !hasSlackInstallationRoutesOptions(options.routes) &&
+    !hasSlackWebhookRoutesOptions(options.routes)
+  ) {
+    throw new Error('Slack webhook routes require every core persistence dependency');
+  }
+  const routes: RouteGroup[] = [];
+  if (options.routes && hasSlackInstallationRoutesOptions(options.routes)) {
+    const {
+      tokenStore,
+      getExistingSlackConnection,
+      connectSlackInstallation,
+      disconnectSlackInstallation,
+    } = options.routes;
+    routes.push(
+      createSlackIntegrationRoutes({
+        slack,
+        connectionCapabilities: adapters.agent_tools ? ['agent_tools'] : [],
+        tokenStore,
+        getExistingSlackConnection,
+        connectSlackInstallation,
+        disconnectSlackInstallation,
+      }),
+    );
+  }
+  if (options.routes && hasSlackWebhookRoutesOptions(options.routes)) {
+    routes.push(...createSlackWebhookRoutes(options.routes));
+  }
+
+  return {
+    provider: SLACK_PROVIDER,
+    displayName: 'Slack',
+    adapters,
+    async connectionExternalUrl(connection: {id: string}): Promise<string | undefined> {
+      const installation = await getInstallationByConnectionId(connection.id);
+      if (!installation) return undefined;
+      return `https://app.slack.com/client/${encodeURIComponent(installation.teamId)}`;
+    },
+    routes,
+  };
+}
+
+function hasSlackInstallationRoutesOptions(
+  routes: SlackRouteOptions,
+): routes is SlackInstallationRouteOptions {
+  return (
+    routes.tokenStore !== undefined &&
+    routes.getExistingSlackConnection !== undefined &&
+    routes.connectSlackInstallation !== undefined &&
+    routes.disconnectSlackInstallation !== undefined
+  );
+}
+
+function hasSlackWebhookRoutesOptions(
+  routes: SlackRouteOptions,
+): routes is CreateSlackWebhookRoutesOptions {
+  return (
+    routes.coreDb !== undefined &&
+    routes.publishIntegrationEventReceived !== undefined &&
+    routes.recordDeliveryOnly !== undefined &&
+    routes.getIntegrationConnectionById !== undefined
+  );
+}

package/src/presentation/dto/integrations.ts

@@ -0,0 +1 @@
+export {toIntegrationConnectionDto} from '@shipfox/api-integration-core-dto';

package/src/presentation/e2eRoutes/create-connection.ts

@@ -0,0 +1,82 @@
+import type {IntegrationCapability, IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {
+  createE2eSlackConnectionBodySchema,
+  createE2eSlackConnectionResponseSchema,
+} from '@shipfox/api-integration-slack-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {logger} from '@shipfox/node-opentelemetry';
+import type {ConnectSlackInstallationInput} from '#core/install.js';
+import type {SlackTokenStore} from '#core/tokens.js';
+import {toIntegrationConnectionDto} from '#presentation/dto/integrations.js';
+
+export interface CreateE2eSlackConnectionRouteOptions {
+  tokenStore: Pick<SlackTokenStore, 'storeTokens'>;
+  getExistingSlackConnection: (input: {
+    teamId: string;
+  }) => Promise<IntegrationConnection<'slack'> | undefined>;
+  connectSlackInstallation: (
+    input: ConnectSlackInstallationInput,
+  ) => Promise<IntegrationConnection<'slack'>>;
+  disconnectSlackInstallation: (input: {connectionId: string}) => Promise<void>;
+  connectionCapabilities: IntegrationCapability[];
+}
+
+export function createE2eSlackConnectionRoute(options: CreateE2eSlackConnectionRouteOptions) {
+  return defineRoute({
+    method: 'POST',
+    path: '/slack-connections',
+    description: 'Create a synthetic Slack connection for E2E tests.',
+    schema: {
+      body: createE2eSlackConnectionBodySchema,
+      response: {201: createE2eSlackConnectionResponseSchema},
+    },
+    handler: async (request, reply) => {
+      const body = request.body;
+      const existing = await options.getExistingSlackConnection({teamId: body.team_id});
+      if (existing && existing.workspaceId !== body.workspace_id) {
+        throw new ClientError(
+          'Slack team is already connected to another workspace',
+          'slack-connection-workspace-mismatch',
+          {status: 409},
+        );
+      }
+      const connection =
+        existing ??
+        (await options.connectSlackInstallation({
+          workspaceId: body.workspace_id,
+          teamId: body.team_id,
+          teamName: body.team_name,
+          appId: body.app_id,
+          botUserId: body.bot_user_id,
+          scopes: body.scopes,
+          tokenExpiresAt: null,
+          displayName: `Slack ${body.team_name}`,
+        }));
+      try {
+        await options.tokenStore.storeTokens({
+          connectionId: connection.id,
+          botToken: body.bot_token,
+        });
+      } catch (error) {
+        if (!existing) await bestEffortDisconnectSlackInstallation(options, connection.id);
+        throw error;
+      }
+      reply.code(201);
+      return toIntegrationConnectionDto(connection, {capabilities: options.connectionCapabilities});
+    },
+  });
+}
+
+async function bestEffortDisconnectSlackInstallation(
+  options: CreateE2eSlackConnectionRouteOptions,
+  connectionId: string,
+): Promise<void> {
+  try {
+    await options.disconnectSlackInstallation({connectionId});
+  } catch (error) {
+    logger().warn(
+      {err: error, connectionId},
+      'Slack E2E connection compensation failed after token storage rejection',
+    );
+  }
+}

package/src/presentation/e2eRoutes/index.test.ts

@@ -0,0 +1,96 @@
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {closeApp, createApp} from '@shipfox/node-fastify';
+import {createSlackE2eRoutes} from './index.js';
+
+function connection(overrides: Partial<IntegrationConnection<'slack'>> = {}) {
+  return {
+    id: '00000000-0000-4000-8000-000000000001',
+    workspaceId: '00000000-0000-4000-8000-000000000002',
+    provider: 'slack',
+    externalAccountId: 'T123',
+    slug: 'slack_acme',
+    displayName: 'Slack Acme',
+    lifecycleStatus: 'active',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  } satisfies IntegrationConnection<'slack'>;
+}
+
+describe('Slack E2E routes', () => {
+  afterEach(async () => {
+    await closeApp();
+  });
+
+  it('creates a connection and stores its bot token without returning it', async () => {
+    const tokenStore = {storeTokens: vi.fn(() => Promise.resolve())};
+    const app = await createApp({
+      routes: [
+        createSlackE2eRoutes({
+          tokenStore,
+          getExistingSlackConnection: vi.fn(() => Promise.resolve(undefined)),
+          connectSlackInstallation: vi.fn(() => Promise.resolve(connection())),
+          disconnectSlackInstallation: vi.fn(() => Promise.resolve()),
+          connectionCapabilities: [],
+        }),
+      ],
+      swagger: false,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/slack-connections',
+      payload: {
+        workspace_id: '00000000-0000-4000-8000-000000000002',
+        team_id: 'T123',
+        team_name: 'Acme',
+        app_id: 'A123',
+        bot_user_id: 'U123',
+        bot_token: 'xoxb-e2e-token',
+      },
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toMatchObject({provider: 'slack', capabilities: []});
+    expect(res.body).not.toContain('xoxb-e2e-token');
+    expect(tokenStore.storeTokens).toHaveBeenCalledWith({
+      connectionId: '00000000-0000-4000-8000-000000000001',
+      botToken: 'xoxb-e2e-token',
+    });
+  });
+
+  it('rejects a Slack team connected to another workspace', async () => {
+    const connectSlackInstallation = vi.fn(() => Promise.resolve(connection()));
+    const app = await createApp({
+      routes: [
+        createSlackE2eRoutes({
+          tokenStore: {storeTokens: vi.fn(() => Promise.resolve())},
+          getExistingSlackConnection: vi.fn(() =>
+            Promise.resolve(connection({workspaceId: '00000000-0000-4000-8000-000000000003'})),
+          ),
+          connectSlackInstallation,
+          disconnectSlackInstallation: vi.fn(() => Promise.resolve()),
+          connectionCapabilities: [],
+        }),
+      ],
+      swagger: false,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/slack-connections',
+      payload: {
+        workspace_id: '00000000-0000-4000-8000-000000000002',
+        team_id: 'T123',
+        team_name: 'Acme',
+        app_id: 'A123',
+        bot_user_id: 'U123',
+        bot_token: 'xoxb-e2e-token',
+      },
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json()).toMatchObject({code: 'slack-connection-workspace-mismatch'});
+    expect(connectSlackInstallation).not.toHaveBeenCalled();
+  });
+});

package/src/presentation/e2eRoutes/index.ts

@@ -0,0 +1,11 @@
+import type {RouteGroup} from '@shipfox/node-fastify';
+import {
+  type CreateE2eSlackConnectionRouteOptions,
+  createE2eSlackConnectionRoute,
+} from './create-connection.js';
+
+export type CreateSlackE2eRoutesOptions = CreateE2eSlackConnectionRouteOptions;
+
+export function createSlackE2eRoutes(options: CreateSlackE2eRoutesOptions): RouteGroup {
+  return {prefix: '/integrations', routes: [createE2eSlackConnectionRoute(options)]};
+}

package/src/presentation/routes/errors.ts

@@ -0,0 +1,68 @@
+import {
+  ConnectionSlugConflictError,
+  type IntegrationProviderErrorReason,
+} from '@shipfox/api-integration-core-dto';
+import {ClientError} from '@shipfox/node-fastify';
+import {
+  SlackAuthorizationScopeMismatchError,
+  SlackConnectionAlreadyLinkedError,
+  SlackEnterpriseInstallUnsupportedError,
+  SlackInstallationAlreadyLinkedError,
+  SlackInstallStateActorMismatchError,
+  SlackInstallStateError,
+  SlackIntegrationProviderError,
+  SlackOAuthCallbackError,
+  SlackTokenRotationUnsupportedError,
+} from '#core/errors.js';
+
+function providerStatus(reason: IntegrationProviderErrorReason): number {
+  if (reason === 'rate-limited') return 429;
+  if (reason === 'timeout' || reason === 'provider-unavailable') return 503;
+  return 422;
+}
+
+export function slackRouteErrorHandler(error: unknown): never {
+  if (error instanceof SlackInstallStateError) {
+    throw new ClientError(error.message, 'invalid-slack-install-state', {status: 400});
+  }
+  if (error instanceof SlackInstallStateActorMismatchError) {
+    throw new ClientError(error.message, 'slack-install-state-actor-mismatch', {status: 403});
+  }
+  if (error instanceof SlackInstallationAlreadyLinkedError) {
+    throw new ClientError(error.message, 'slack-installation-already-linked', {status: 409});
+  }
+  if (error instanceof SlackConnectionAlreadyLinkedError) {
+    throw new ClientError(error.message, 'slack-connection-already-linked', {status: 409});
+  }
+  if (error instanceof SlackAuthorizationScopeMismatchError) {
+    throw new ClientError(error.message, 'slack-authorization-scope-mismatch', {
+      status: 422,
+      details: {missing_scopes: error.missingScopes},
+    });
+  }
+  if (error instanceof SlackEnterpriseInstallUnsupportedError) {
+    throw new ClientError(error.message, 'slack-enterprise-install-unsupported', {status: 422});
+  }
+  if (error instanceof SlackTokenRotationUnsupportedError) {
+    throw new ClientError(error.message, 'slack-token-rotation-unsupported', {status: 422});
+  }
+  if (error instanceof SlackOAuthCallbackError) {
+    throw new ClientError(error.message, 'slack-oauth-callback-error', {
+      status: 422,
+      details: {
+        error: error.providerError,
+        ...(error.providerDescription ? {error_description: error.providerDescription} : {}),
+      },
+    });
+  }
+  if (error instanceof ConnectionSlugConflictError) {
+    throw new ClientError(error.message, 'slug-conflict', {status: 409});
+  }
+  if (error instanceof SlackIntegrationProviderError) {
+    throw new ClientError(error.message, error.reason, {
+      details: {retry_after_seconds: error.retryAfterSeconds},
+      status: providerStatus(error.reason),
+    });
+  }
+  throw error;
+}