@shipfox/api-integration-slack 4.0.0

package/src/api/client.ts

@@ -0,0 +1,243 @@
+import {logger} from '@shipfox/node-opentelemetry';
+import ky, {HTTPError, TimeoutError} from 'ky';
+import {config} from '#config.js';
+import {
+  SlackEnterpriseInstallUnsupportedError,
+  SlackIntegrationProviderError,
+  SlackTokenRotationUnsupportedError,
+} from '#core/errors.js';
+
+const SLACK_API_TIMEOUT_MS = 10_000;
+
+export interface SlackAuthorization {
+  accessToken: string;
+  botUserId: string;
+  appId: string;
+  teamId: string;
+  teamName: string;
+  scopes: string[];
+}
+
+export interface SlackWebApiResponse {
+  ok: boolean;
+  error?: string | undefined;
+  [key: string]: unknown;
+}
+
+export interface SlackApiClient {
+  exchangeAuthorizationCode(input: {code: string}): Promise<SlackAuthorization>;
+  revokeToken(input: {token: string}): Promise<void>;
+  callMethod(input: {
+    method: string;
+    token: string;
+    arguments: Record<string, unknown>;
+  }): Promise<SlackWebApiResponse>;
+}
+
+interface SlackOAuthAccessResponse {
+  ok?: unknown;
+  error?: unknown;
+  access_token?: unknown;
+  bot_user_id?: unknown;
+  app_id?: unknown;
+  team?: {id?: unknown; name?: unknown} | null | undefined;
+  scope?: unknown;
+  is_enterprise_install?: unknown;
+  expires_in?: unknown;
+  refresh_token?: unknown;
+}
+
+export function createSlackApiClient(): SlackApiClient {
+  return {
+    async exchangeAuthorizationCode(input) {
+      const body = await mapSlackError('exchange-authorization-code', () =>
+        ky
+          .post(slackApiUrl('oauth.v2.access'), {
+            body: new URLSearchParams({
+              client_id: config.SLACK_OAUTH_CLIENT_ID,
+              client_secret: config.SLACK_OAUTH_CLIENT_SECRET,
+              code: input.code,
+              redirect_uri: config.SLACK_OAUTH_REDIRECT_URL,
+            }),
+            timeout: SLACK_API_TIMEOUT_MS,
+          })
+          .json<SlackOAuthAccessResponse>(),
+      );
+      return parseOAuthAccess(body);
+    },
+
+    async revokeToken(input) {
+      await mapSlackError('revoke-token', async () => {
+        await ky.post(slackApiUrl('auth.revoke'), {
+          headers: {authorization: `Bearer ${input.token}`},
+          timeout: SLACK_API_TIMEOUT_MS,
+        });
+      });
+    },
+
+    async callMethod(input) {
+      return await mapSlackWebApiError(input.method, () =>
+        ky
+          .post(slackApiUrl(input.method), {
+            headers: {authorization: `Bearer ${input.token}`},
+            body: slackMethodArguments(input.arguments),
+            timeout: SLACK_API_TIMEOUT_MS,
+          })
+          .json<SlackWebApiResponse>(),
+      );
+    },
+  };
+}
+
+function parseOAuthAccess(body: SlackOAuthAccessResponse): SlackAuthorization {
+  if (body.ok !== true) {
+    throw new SlackIntegrationProviderError(
+      slackOAuthErrorReason(body.error),
+      'Slack authorization request failed',
+    );
+  }
+  if (body.is_enterprise_install === true || body.team == null) {
+    throw new SlackEnterpriseInstallUnsupportedError();
+  }
+  // The bot-token store has no refresh path, so a rotating (expiring) token must never be persisted.
+  // Slack omits both fields when rotation is off, so presence of either signals rotation.
+  // The rejected token self-expires, matching the Enterprise Grid rejection path.
+  if (body.expires_in !== undefined || body.refresh_token !== undefined) {
+    throw new SlackTokenRotationUnsupportedError();
+  }
+  const {access_token: accessToken, bot_user_id: botUserId, app_id: appId, team, scope} = body;
+  if (
+    typeof accessToken !== 'string' ||
+    typeof botUserId !== 'string' ||
+    typeof appId !== 'string' ||
+    typeof team.id !== 'string' ||
+    typeof team.name !== 'string' ||
+    typeof scope !== 'string'
+  ) {
+    throw new SlackIntegrationProviderError(
+      'malformed-provider-response',
+      'Slack authorization response did not include the required installation details',
+    );
+  }
+  return {
+    accessToken,
+    botUserId,
+    appId,
+    teamId: team.id,
+    teamName: team.name,
+    scopes: scope
+      .split(',')
+      .map((value) => value.trim())
+      .filter(Boolean),
+  };
+}
+
+function slackOAuthErrorReason(error: unknown) {
+  if (error === 'service_unavailable' || error === 'internal_error') return 'provider-unavailable';
+  if (error === 'ratelimited') return 'rate-limited';
+  return 'access-denied';
+}
+
+async function mapSlackError<T>(operation: string, request: () => Promise<T>): Promise<T> {
+  try {
+    return await request();
+  } catch (error) {
+    if (error instanceof SlackIntegrationProviderError) throw error;
+    if (error instanceof HTTPError) {
+      const {status, statusText, headers} = error.response;
+      logger().warn({operation, status, statusText}, 'Slack API request rejected');
+      if (status === 429) {
+        throw new SlackIntegrationProviderError(
+          'rate-limited',
+          'Slack request was rate limited',
+          retryAfterSeconds(headers),
+        );
+      }
+      if (status >= 500) {
+        throw new SlackIntegrationProviderError('provider-unavailable', 'Slack request failed');
+      }
+      throw new SlackIntegrationProviderError('access-denied', 'Slack request was rejected');
+    }
+    if (error instanceof TimeoutError) {
+      logger().warn({operation}, 'Slack API request timed out');
+      throw new SlackIntegrationProviderError('timeout', 'Slack request timed out');
+    }
+    logger().warn(
+      {operation, errName: error instanceof Error ? error.name : typeof error},
+      'Slack API request failed',
+    );
+    throw new SlackIntegrationProviderError('provider-unavailable', 'Slack request failed');
+  }
+}
+
+async function mapSlackWebApiError<T>(method: string, request: () => Promise<T>): Promise<T> {
+  try {
+    return await request();
+  } catch (error) {
+    if (error instanceof SlackIntegrationProviderError) throw error;
+    if (error instanceof HTTPError) {
+      const {status, statusText, headers} = error.response;
+      logger().warn(
+        {operation: 'call-method', method, status, statusText},
+        'Slack API request rejected',
+      );
+      if (status === 429) {
+        throw new SlackIntegrationProviderError(
+          'rate-limited',
+          'Slack request was rate limited',
+          retryAfterSeconds(headers),
+        );
+      }
+      if (status === 413) {
+        throw new SlackIntegrationProviderError(
+          'content-too-large',
+          'Slack request content was too large',
+        );
+      }
+      if (status >= 500) {
+        throw new SlackIntegrationProviderError('provider-unavailable', 'Slack request failed');
+      }
+      throw new SlackIntegrationProviderError(
+        'malformed-provider-response',
+        'Slack request was rejected',
+      );
+    }
+    if (error instanceof TimeoutError) {
+      logger().warn({operation: 'call-method', method}, 'Slack API request timed out');
+      throw new SlackIntegrationProviderError('timeout', 'Slack request timed out');
+    }
+    logger().warn(
+      {
+        operation: 'call-method',
+        method,
+        errName: error instanceof Error ? error.name : typeof error,
+      },
+      'Slack API request failed',
+    );
+    throw new SlackIntegrationProviderError('provider-unavailable', 'Slack request failed');
+  }
+}
+
+function slackMethodArguments(input: Record<string, unknown>): URLSearchParams {
+  const body = new URLSearchParams();
+  for (const [key, value] of Object.entries(input)) {
+    if (value === null || value === undefined) continue;
+    const serialized =
+      typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+        ? String(value)
+        : JSON.stringify(value);
+    if (serialized !== undefined) body.set(key, serialized);
+  }
+  return body;
+}
+
+function slackApiUrl(path: string): string {
+  return new URL(path, `${config.SLACK_API_BASE_URL}/`).toString();
+}
+
+function retryAfterSeconds(headers: Headers): number | undefined {
+  const retryAfter = headers.get('retry-after');
+  if (!retryAfter) return undefined;
+  const parsed = Number.parseInt(retryAfter, 10);
+  return Number.isNaN(parsed) ? undefined : parsed;
+}

package/src/config.test.ts

@@ -0,0 +1,32 @@
+const slackEnvNames = [
+  'SLACK_OAUTH_CLIENT_ID',
+  'SLACK_OAUTH_CLIENT_SECRET',
+  'SLACK_SIGNING_SECRET',
+  'SLACK_OAUTH_REDIRECT_URL',
+] as const;
+
+describe('slack config', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it('exports validated Slack config from the package root', async () => {
+    vi.stubEnv('SLACK_API_BASE_URL', undefined);
+    vi.resetModules();
+
+    const {config} = await import('#index.js');
+
+    for (const name of slackEnvNames) expect(config[name]).toBe(process.env[name]);
+    expect(config.SLACK_API_BASE_URL).toBe('https://slack.com/api');
+  });
+
+  it('accepts a compatible Slack API base URL override', async () => {
+    vi.stubEnv('SLACK_API_BASE_URL', 'https://slack-api.example.test');
+    vi.resetModules();
+
+    const {config} = await import('#index.js');
+
+    expect(config.SLACK_API_BASE_URL).toBe('https://slack-api.example.test');
+  });
+});

package/src/config.ts

@@ -0,0 +1,20 @@
+import {createConfig, str, url} from '@shipfox/config';
+
+export const config = createConfig({
+  SLACK_OAUTH_CLIENT_ID: str({
+    desc: 'OAuth client ID of the Slack app, used to start and complete the Slack connect flow. Required.',
+  }),
+  SLACK_OAUTH_CLIENT_SECRET: str({
+    desc: 'OAuth client secret of the Slack app, used to exchange authorization codes for workspace bot tokens. Required.',
+  }),
+  SLACK_SIGNING_SECRET: str({
+    desc: 'Secret used to verify incoming Slack events and commands. It must match the signing secret configured on the Slack app. Required.',
+  }),
+  SLACK_OAUTH_REDIRECT_URL: url({
+    desc: 'Public client callback URL Slack redirects to after OAuth authorization, such as https://shipfox.example.com/integrations/slack/callback. Required.',
+  }),
+  SLACK_API_BASE_URL: url({
+    desc: 'Slack Web API base URL. Override this only when routing Slack API requests through a proxy or test server.',
+    default: 'https://slack.com/api',
+  }),
+});

package/src/connection-external-url.test.ts

@@ -0,0 +1,25 @@
+import type {SlackInstallation} from '#db/installations.js';
+import {createSlackIntegrationProvider} from '#index.js';
+
+describe('Slack connectionExternalUrl', () => {
+  it('resolves the Slack team URL from the installation row', async () => {
+    const provider = createSlackIntegrationProvider({
+      getSlackInstallationByConnectionId: () =>
+        Promise.resolve({teamId: 'T 123'} as SlackInstallation),
+    });
+
+    const result = await provider.connectionExternalUrl({id: crypto.randomUUID()});
+
+    expect(result).toBe('https://app.slack.com/client/T%20123');
+  });
+
+  it('returns undefined when the installation is missing', async () => {
+    const provider = createSlackIntegrationProvider({
+      getSlackInstallationByConnectionId: () => Promise.resolve(undefined),
+    });
+
+    const result = await provider.connectionExternalUrl({id: crypto.randomUUID()});
+
+    expect(result).toBeUndefined();
+  });
+});

package/src/core/agent-tools-provider.test.ts

@@ -0,0 +1,256 @@
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import type {SlackWebApiResponse} from '#api/client.js';
+import {slackAgentToolCatalog, slackAgentToolSelectionCatalog} from '#core/agent-tools.js';
+import {SlackAgentToolsProvider} from '#core/agent-tools-provider.js';
+import {SlackBotTokenMissingError, SlackIntegrationProviderError} from '#core/errors.js';
+
+const mocks = vi.hoisted(() => ({warn: vi.fn()}));
+
+vi.mock('@shipfox/node-opentelemetry', () => ({logger: () => ({warn: mocks.warn})}));
+
+function slackConnection(
+  overrides: Partial<IntegrationConnection<'slack'>> = {},
+): IntegrationConnection<'slack'> {
+  const now = new Date();
+  return {
+    id: 'slack-connection-1',
+    workspaceId: 'workspace-1',
+    provider: 'slack',
+    externalAccountId: 'T123',
+    slug: 'slack-acme',
+    displayName: 'Slack Acme',
+    lifecycleStatus: 'active',
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  };
+}
+
+function catalogTool(id: string) {
+  const tool = slackAgentToolCatalog.find((candidate) => candidate.id === id);
+  if (!tool) throw new Error(`Unknown test tool: ${id}`);
+  return tool;
+}
+
+function providerOptions(
+  callMethod: (input: {
+    method: string;
+    token: string;
+    arguments: Record<string, unknown>;
+  }) => Promise<SlackWebApiResponse>,
+) {
+  return {
+    slack: {callMethod: vi.fn(callMethod)},
+    tokenStore: {getAccessToken: vi.fn().mockResolvedValue('xoxb-token')},
+  };
+}
+
+async function openSession(
+  options: ReturnType<typeof providerOptions>,
+  toolIds: string[],
+  connection = slackConnection(),
+) {
+  const provider = new SlackAgentToolsProvider(options);
+  return await provider.openSession({
+    connection,
+    tools: toolIds.map(catalogTool),
+    scope: {provider: 'slack'},
+  });
+}
+
+describe('SlackAgentToolsProvider', () => {
+  beforeEach(() => {
+    mocks.warn.mockReset();
+  });
+
+  it('returns the Slack agent tools catalogs', () => {
+    const options = providerOptions(async () => ({ok: true}));
+    const provider = new SlackAgentToolsProvider(options);
+
+    const catalog = provider.catalog();
+    const selectionCatalog = provider.selectionCatalog();
+
+    expect(catalog).toBe(slackAgentToolCatalog);
+    expect(selectionCatalog).toBe(slackAgentToolSelectionCatalog);
+  });
+
+  it('reads the stored bot token for the connection before opening a session', async () => {
+    const options = providerOptions(async () => ({ok: true}));
+    const provider = new SlackAgentToolsProvider(options);
+
+    await provider.openSession({
+      connection: slackConnection({id: 'slack-connection-7'}),
+      tools: [],
+      scope: {provider: 'slack'},
+    });
+
+    expect(options.tokenStore.getAccessToken).toHaveBeenCalledWith({
+      connectionId: 'slack-connection-7',
+    });
+  });
+
+  it('dispatches a read method and returns the Slack response as structured content', async () => {
+    const body = {ok: true, messages: [{text: 'Hello'}]};
+    const options = providerOptions(async () => body);
+    const session = await openSession(options, ['conversations_history']);
+
+    const result = await session.call({
+      toolId: 'conversations_history',
+      arguments: {channel: 'C123', limit: 10},
+    });
+
+    expect(options.slack.callMethod).toHaveBeenCalledWith({
+      method: 'conversations.history',
+      token: 'xoxb-token',
+      arguments: {channel: 'C123', limit: 10},
+    });
+    expect(result).toEqual({
+      content: [{type: 'text', text: JSON.stringify(body)}],
+      structuredContent: body,
+    });
+  });
+
+  it('passes a thread timestamp through to the message-posting method', async () => {
+    const options = providerOptions(async () => ({ok: true, ts: '456.000'}));
+    const session = await openSession(options, ['chat_postMessage']);
+
+    await session.call({
+      toolId: 'chat_postMessage',
+      arguments: {channel: 'C123', text: 'Reply', thread_ts: '123.000'},
+    });
+
+    expect(options.slack.callMethod).toHaveBeenCalledWith({
+      method: 'chat.postMessage',
+      token: 'xoxb-token',
+      arguments: {channel: 'C123', text: 'Reply', thread_ts: '123.000'},
+    });
+  });
+
+  it('rejects a tool that was not selected for the session', async () => {
+    const options = providerOptions(async () => ({ok: true}));
+    const session = await openSession(options, ['conversations_history']);
+
+    const result = await session.call({toolId: 'users_info', arguments: {user: 'U123'}});
+
+    expect(result).toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'Unknown Slack tool: users_info'}],
+    });
+    expect(options.slack.callMethod).not.toHaveBeenCalled();
+  });
+
+  it('rejects a call missing a required parameter', async () => {
+    const options = providerOptions(async () => ({ok: true}));
+    const session = await openSession(options, ['conversations_replies']);
+
+    const result = await session.call({
+      toolId: 'conversations_replies',
+      arguments: {channel: 'C123'},
+    });
+
+    expect(result).toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'Missing required parameter: ts'}],
+    });
+    expect(options.slack.callMethod).not.toHaveBeenCalled();
+  });
+
+  it('returns a Slack application error to the agent', async () => {
+    const options = providerOptions(async () => ({ok: false, error: 'channel_not_found'}));
+    const session = await openSession(options, ['conversations_history']);
+
+    const result = await session.call({
+      toolId: 'conversations_history',
+      arguments: {channel: 'C123'},
+    });
+
+    expect(result).toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'channel_not_found'}],
+    });
+  });
+
+  it('returns auth failures with a stable access-denied code and logs only metadata', async () => {
+    const options = providerOptions(async () => ({ok: false, error: 'invalid_auth'}));
+    const session = await openSession(options, ['conversations_history']);
+
+    const result = await session.call({
+      toolId: 'conversations_history',
+      arguments: {channel: 'C123'},
+    });
+
+    expect(result).toMatchObject({
+      isError: true,
+      content: [{type: 'text', text: 'invalid_auth'}],
+      structuredContent: {code: 'access-denied'},
+    });
+    expect(mocks.warn).toHaveBeenCalledWith(
+      {connectionId: 'slack-connection-1', slackError: 'invalid_auth'},
+      'Slack API rejected integration credentials',
+    );
+    expect(JSON.stringify(mocks.warn.mock.calls)).not.toContain('xoxb-token');
+  });
+
+  it('returns an HTTP-200 rate-limit response with a stable code', async () => {
+    const options = providerOptions(async () => ({ok: false, error: 'ratelimited'}));
+    const session = await openSession(options, ['conversations_list']);
+
+    const result = await session.call({toolId: 'conversations_list', arguments: {}});
+
+    expect(result).toMatchObject({
+      isError: true,
+      structuredContent: {code: 'rate-limited'},
+    });
+  });
+
+  it('preserves retry details from a transport-level rate limit', async () => {
+    const options = providerOptions(() =>
+      Promise.reject(new SlackIntegrationProviderError('rate-limited', 'Try again later', 19)),
+    );
+    const session = await openSession(options, ['conversations_list']);
+
+    const result = await session.call({toolId: 'conversations_list', arguments: {}});
+
+    expect(result).toMatchObject({
+      isError: true,
+      content: [{type: 'text', text: 'Try again later'}],
+      structuredContent: {code: 'rate-limited', retryAfterSeconds: 19},
+    });
+  });
+
+  it('preserves content-too-large from a rejected Slack request', async () => {
+    const options = providerOptions(() =>
+      Promise.reject(
+        new SlackIntegrationProviderError('content-too-large', 'Slack content was too large'),
+      ),
+    );
+    const session = await openSession(options, ['chat_postMessage']);
+
+    const result = await session.call({
+      toolId: 'chat_postMessage',
+      arguments: {channel: 'C123', blocks: []},
+    });
+
+    expect(result).toMatchObject({
+      isError: true,
+      structuredContent: {code: 'content-too-large'},
+    });
+  });
+
+  it('does not call Slack when the bot token is missing', async () => {
+    const options = providerOptions(async () => ({ok: true}));
+    options.tokenStore.getAccessToken.mockRejectedValue(
+      new SlackBotTokenMissingError('slack-connection-1'),
+    );
+    const provider = new SlackAgentToolsProvider(options);
+
+    const result = provider.openSession({
+      connection: slackConnection(),
+      tools: [catalogTool('conversations_list')],
+      scope: {provider: 'slack'},
+    });
+
+    await expect(result).rejects.toBeInstanceOf(SlackBotTokenMissingError);
+    expect(options.slack.callMethod).not.toHaveBeenCalled();
+  });
+});