@shipfox/api-integration-slack 4.0.0

package/src/core/webhook.test.ts

@@ -0,0 +1,269 @@
+import {randomUUID} from 'node:crypto';
+import type {
+  GetIntegrationConnectionByIdFn,
+  IntegrationConnection,
+} from '@shipfox/api-integration-core-dto';
+import {db} from '#db/db.js';
+import {upsertSlackInstallation} from '#db/installations.js';
+import {slackInstallations} from '#db/schema/installations.js';
+import {handleSlackCommand, handleSlackEvent} from './webhook.js';
+
+function fakeConnection(overrides: Partial<IntegrationConnection> = {}): IntegrationConnection {
+  return {
+    id: randomUUID(),
+    workspaceId: randomUUID(),
+    provider: 'slack',
+    externalAccountId: 'T1',
+    slug: 'slack_acme',
+    displayName: 'Slack Acme',
+    lifecycleStatus: 'active',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+function eventEnvelope(overrides: Record<string, unknown> = {}) {
+  return {
+    type: 'event_callback' as const,
+    team_id: 'T1',
+    api_app_id: 'A1',
+    event: {type: 'app_mention', channel: 'C1', user: 'U1', text: 'hello', ts: '1.0'},
+    event_id: 'Ev1',
+    event_time: 1_721_300_000,
+    ...overrides,
+  };
+}
+
+function command(overrides: Record<string, unknown> = {}) {
+  return {
+    token: 'shared-verification-token',
+    command: '/deploy',
+    team_id: 'T1',
+    channel_id: 'C1',
+    user_id: 'U1',
+    response_url: 'https://hooks.slack.com/commands/1',
+    trigger_id: '1337.42',
+    text: '',
+    ...overrides,
+  };
+}
+
+async function seedInstallation(
+  connection: IntegrationConnection,
+  status: 'installed' | 'revoked' = 'installed',
+) {
+  await upsertSlackInstallation({
+    connectionId: connection.id,
+    teamId: 'T1',
+    teamName: 'Acme',
+    appId: 'A1',
+    botUserId: 'UBOT',
+    scopes: [],
+    status,
+  });
+}
+
+function handlers(connection = fakeConnection()) {
+  return {
+    connection,
+    publishIntegrationEventReceived: vi.fn(() => Promise.resolve({published: true})),
+    recordDeliveryOnly: vi.fn(() => Promise.resolve()),
+    getIntegrationConnectionById: vi.fn<GetIntegrationConnectionByIdFn>(() =>
+      Promise.resolve(connection),
+    ),
+  };
+}
+
+describe('Slack webhook handlers', () => {
+  beforeEach(async () => {
+    await db().delete(slackInstallations);
+  });
+
+  it('publishes a supported event with a flattened payload', async () => {
+    const deps = handlers();
+    await seedInstallation(deps.connection);
+
+    const result = await handleSlackEvent({
+      tx: db(),
+      deliveryId: 'Ev1',
+      envelope: eventEnvelope(),
+      ...deps,
+    });
+
+    expect(result.outcome).toBe('published');
+    expect(deps.publishIntegrationEventReceived).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event: expect.objectContaining({
+          event: 'app_mention',
+          deliveryId: 'Ev1',
+          payload: expect.objectContaining({
+            type: 'app_mention',
+            channel: 'C1',
+            team_id: 'T1',
+            event_id: 'Ev1',
+          }),
+        }),
+      }),
+    );
+  });
+
+  it('reports a duplicate for a repeated Slack event delivery id', async () => {
+    const deps = handlers();
+    deps.publishIntegrationEventReceived.mockResolvedValue({published: false});
+    await seedInstallation(deps.connection);
+
+    const result = await handleSlackEvent({
+      tx: db(),
+      deliveryId: 'Ev-replayed',
+      envelope: eventEnvelope({event_id: 'Ev-replayed'}),
+      ...deps,
+    });
+
+    expect(result.outcome).toBe('duplicate');
+    expect(deps.publishIntegrationEventReceived).toHaveBeenCalledWith(
+      expect.objectContaining({event: expect.objectContaining({deliveryId: 'Ev-replayed'})}),
+    );
+  });
+
+  it.each([
+    ['a bot-authored event', {event: {type: 'message', bot_id: 'B1'}}],
+    ['an event from this installation bot', {event: {type: 'reaction_added', user: 'UBOT'}}],
+    [
+      'a nested edited bot message',
+      {event: {type: 'message', subtype: 'message_changed', message: {bot_id: 'B1'}}},
+    ],
+  ])('records and drops %s', async (_description, override) => {
+    const deps = handlers();
+    await seedInstallation(deps.connection);
+
+    const result = await handleSlackEvent({
+      tx: db(),
+      deliveryId: randomUUID(),
+      envelope: eventEnvelope(override),
+      ...deps,
+    });
+
+    expect(result.outcome).toBe('self-message');
+    expect(deps.publishIntegrationEventReceived).not.toHaveBeenCalled();
+    expect(deps.recordDeliveryOnly).toHaveBeenCalledTimes(1);
+  });
+
+  it('records an unknown team without resolving a connection', async () => {
+    const deps = handlers();
+
+    const result = await handleSlackEvent({
+      tx: db(),
+      deliveryId: 'Ev-missing',
+      envelope: eventEnvelope({team_id: 'T-missing'}),
+      ...deps,
+    });
+
+    expect(result.outcome).toBe('unknown-team');
+    expect(deps.getIntegrationConnectionById).not.toHaveBeenCalled();
+    expect(deps.recordDeliveryOnly).toHaveBeenCalledWith(
+      expect.objectContaining({provider: 'slack', deliveryId: 'Ev-missing'}),
+    );
+  });
+
+  it('records an inactive connection', async () => {
+    const deps = handlers(fakeConnection({lifecycleStatus: 'disabled'}));
+    await seedInstallation(deps.connection);
+
+    const result = await handleSlackEvent({
+      tx: db(),
+      deliveryId: 'Ev-disabled',
+      envelope: eventEnvelope(),
+      ...deps,
+    });
+
+    expect(result.outcome).toBe('inactive-connection');
+    expect(deps.publishIntegrationEventReceived).not.toHaveBeenCalled();
+    expect(deps.recordDeliveryOnly).toHaveBeenCalledTimes(1);
+  });
+
+  it('records a revoked installation without resolving a connection', async () => {
+    const deps = handlers();
+    await seedInstallation(deps.connection, 'revoked');
+
+    const result = await handleSlackEvent({
+      tx: db(),
+      deliveryId: 'Ev-revoked',
+      envelope: eventEnvelope(),
+      ...deps,
+    });
+
+    expect(result.outcome).toBe('revoked-installation');
+    expect(deps.getIntegrationConnectionById).not.toHaveBeenCalled();
+    expect(deps.recordDeliveryOnly).toHaveBeenCalledTimes(1);
+  });
+
+  it('records an installation whose connection is missing', async () => {
+    const deps = handlers();
+    deps.getIntegrationConnectionById.mockResolvedValue(undefined);
+    await seedInstallation(deps.connection);
+
+    const result = await handleSlackEvent({
+      tx: db(),
+      deliveryId: 'Ev-missing-connection',
+      envelope: eventEnvelope(),
+      ...deps,
+    });
+
+    expect(result.outcome).toBe('missing-connection');
+    expect(deps.recordDeliveryOnly).toHaveBeenCalledTimes(1);
+  });
+
+  it('drops unsupported event types after resolving the installation', async () => {
+    const deps = handlers();
+    await seedInstallation(deps.connection);
+
+    const result = await handleSlackEvent({
+      tx: db(),
+      deliveryId: 'Ev-unsupported',
+      envelope: eventEnvelope({event: {type: 'channel_created'}}),
+      ...deps,
+    });
+
+    expect(result.outcome).toBe('unsupported-event');
+    expect(deps.publishIntegrationEventReceived).not.toHaveBeenCalled();
+    expect(deps.recordDeliveryOnly).toHaveBeenCalledTimes(1);
+  });
+
+  it('publishes a command without its verification token', async () => {
+    const deps = handlers();
+    await seedInstallation(deps.connection);
+
+    const result = await handleSlackCommand({
+      tx: db(),
+      deliveryId: '1337.42',
+      command: command(),
+      ...deps,
+    });
+
+    expect(result.outcome).toBe('published');
+    expect(deps.publishIntegrationEventReceived).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event: expect.objectContaining({
+          event: 'slash_command',
+          payload: expect.not.objectContaining({token: expect.anything()}),
+        }),
+      }),
+    );
+  });
+
+  it('reports a duplicate slash command delivery', async () => {
+    const deps = handlers();
+    deps.publishIntegrationEventReceived.mockResolvedValue({published: false});
+    await seedInstallation(deps.connection);
+
+    const result = await handleSlackCommand({
+      tx: db(),
+      deliveryId: '1337.42',
+      command: command(),
+      ...deps,
+    });
+
+    expect(result.outcome).toBe('duplicate');
+  });
+});

package/src/core/webhook.ts

@@ -0,0 +1,223 @@
+import type {
+  GetIntegrationConnectionByIdFn,
+  IntegrationConnection,
+  IntegrationTx,
+  PublishIntegrationEventReceivedFn,
+  RecordDeliveryOnlyFn,
+} from '@shipfox/api-integration-core-dto';
+import {
+  SLACK_PROVIDER,
+  SLACK_SLASH_COMMAND_EVENT,
+  type SlackEventBaseEnvelopeDto,
+  type SlackSlashCommandDto,
+  slackEventEnvelopeSchema,
+} from '@shipfox/api-integration-slack-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import {z} from 'zod';
+import {getSlackInstallationByTeamId, type SlackInstallation} from '#db/installations.js';
+
+const slackSelfAuthoredEventSchema = z
+  .object({
+    bot_id: z.string().optional(),
+    user: z.string().optional(),
+    message: z
+      .object({
+        bot_id: z.string().optional(),
+        user: z.string().optional(),
+      })
+      .passthrough()
+      .optional(),
+  })
+  .passthrough();
+
+export type SlackWebhookOutcome =
+  | 'published'
+  | 'duplicate'
+  | 'unknown-team'
+  | 'revoked-installation'
+  | 'missing-connection'
+  | 'inactive-connection'
+  | 'unsupported-event'
+  | 'self-message';
+
+interface SlackWebhookParams {
+  tx: IntegrationTx;
+  deliveryId: string;
+  publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+}
+
+export interface HandleSlackEventParams extends SlackWebhookParams {
+  envelope: SlackEventBaseEnvelopeDto;
+}
+
+export interface HandleSlackCommandParams extends SlackWebhookParams {
+  command: SlackSlashCommandDto;
+}
+
+type SlackConnectionResolution =
+  | {kind: 'ok'; connection: IntegrationConnection; installation: SlackInstallation}
+  | {
+      kind: 'drop';
+      outcome: Exclude<
+        SlackWebhookOutcome,
+        'published' | 'duplicate' | 'unsupported-event' | 'self-message'
+      >;
+    };
+
+export async function handleSlackEvent(
+  params: HandleSlackEventParams,
+): Promise<{outcome: SlackWebhookOutcome}> {
+  const resolution = await resolveSlackConnection({
+    ...params,
+    teamId: params.envelope.team_id,
+  });
+  if (resolution.kind === 'drop') return resolution;
+
+  if (isSelfAuthoredSlackEvent(params.envelope.event, resolution.installation.botUserId)) {
+    await recordSlackDeliveryOnly(params);
+    return {outcome: 'self-message'};
+  }
+
+  const supported = slackEventEnvelopeSchema.safeParse(params.envelope);
+  if (!supported.success) {
+    logger().info(
+      {
+        deliveryId: params.deliveryId,
+        teamId: params.envelope.team_id,
+        type: params.envelope.event.type,
+      },
+      'slack webhook: unsupported event, dropping',
+    );
+    await recordSlackDeliveryOnly(params);
+    return {outcome: 'unsupported-event'};
+  }
+
+  const result = await params.publishIntegrationEventReceived({
+    tx: params.tx,
+    event: {
+      provider: SLACK_PROVIDER,
+      source: resolution.connection.slug,
+      event: supported.data.event.type,
+      workspaceId: resolution.connection.workspaceId,
+      connectionId: resolution.connection.id,
+      connectionName: resolution.connection.displayName,
+      deliveryId: params.deliveryId,
+      receivedAt: new Date().toISOString(),
+      payload: {
+        ...supported.data.event,
+        team_id: supported.data.team_id,
+        api_app_id: supported.data.api_app_id,
+        event_id: supported.data.event_id,
+        event_time: supported.data.event_time,
+      },
+    },
+  });
+
+  return {outcome: result.published ? 'published' : 'duplicate'};
+}
+
+export async function handleSlackCommand(
+  params: HandleSlackCommandParams,
+): Promise<{outcome: Exclude<SlackWebhookOutcome, 'unsupported-event' | 'self-message'>}> {
+  const resolution = await resolveSlackConnection({
+    ...params,
+    teamId: params.command.team_id,
+  });
+  if (resolution.kind === 'drop') return resolution;
+
+  const {token: _token, ...payload} = params.command;
+  const result = await params.publishIntegrationEventReceived({
+    tx: params.tx,
+    event: {
+      provider: SLACK_PROVIDER,
+      source: resolution.connection.slug,
+      event: SLACK_SLASH_COMMAND_EVENT,
+      workspaceId: resolution.connection.workspaceId,
+      connectionId: resolution.connection.id,
+      connectionName: resolution.connection.displayName,
+      deliveryId: params.deliveryId,
+      receivedAt: new Date().toISOString(),
+      payload,
+    },
+  });
+
+  return {outcome: result.published ? 'published' : 'duplicate'};
+}
+
+export function isSelfAuthoredSlackEvent(event: unknown, botUserId: string): boolean {
+  const parsed = slackSelfAuthoredEventSchema.safeParse(event);
+  if (!parsed.success) return false;
+  const nestedMessage = parsed.data.message;
+  return (
+    parsed.data.bot_id !== undefined ||
+    parsed.data.user === botUserId ||
+    nestedMessage?.bot_id !== undefined ||
+    nestedMessage?.user === botUserId
+  );
+}
+
+async function resolveSlackConnection(
+  params: SlackWebhookParams & {teamId: string},
+): Promise<SlackConnectionResolution> {
+  const installation = await getSlackInstallationByTeamId(params.teamId, {tx: params.tx});
+  if (!installation) {
+    logger().warn(
+      {deliveryId: params.deliveryId, teamId: params.teamId},
+      'slack webhook: unknown team, dropping',
+    );
+    await recordSlackDeliveryOnly(params);
+    return {kind: 'drop', outcome: 'unknown-team'};
+  }
+
+  if (installation.status !== 'installed') {
+    logger().info(
+      {
+        deliveryId: params.deliveryId,
+        teamId: params.teamId,
+        connectionId: installation.connectionId,
+      },
+      'slack webhook: installation is not installed, dropping',
+    );
+    await recordSlackDeliveryOnly(params);
+    return {kind: 'drop', outcome: 'revoked-installation'};
+  }
+
+  const connection = await params.getIntegrationConnectionById(installation.connectionId, {
+    tx: params.tx,
+  });
+  if (!connection) {
+    logger().warn(
+      {
+        deliveryId: params.deliveryId,
+        teamId: params.teamId,
+        connectionId: installation.connectionId,
+      },
+      'slack webhook: installation has no connection, dropping',
+    );
+    await recordSlackDeliveryOnly(params);
+    return {kind: 'drop', outcome: 'missing-connection'};
+  }
+
+  if (connection.lifecycleStatus !== 'active') {
+    logger().info(
+      {deliveryId: params.deliveryId, teamId: params.teamId, connectionId: connection.id},
+      'slack webhook: inactive connection, dropping',
+    );
+    await recordSlackDeliveryOnly(params);
+    return {kind: 'drop', outcome: 'inactive-connection'};
+  }
+
+  return {kind: 'ok', connection, installation};
+}
+
+async function recordSlackDeliveryOnly(
+  params: Pick<SlackWebhookParams, 'tx' | 'deliveryId' | 'recordDeliveryOnly'>,
+): Promise<void> {
+  await params.recordDeliveryOnly({
+    tx: params.tx,
+    provider: SLACK_PROVIDER,
+    deliveryId: params.deliveryId,
+  });
+}

package/src/db/db.ts

@@ -0,0 +1,16 @@
+import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
+import {pgClient} from '@shipfox/node-postgres';
+import {slackInstallations} from './schema/installations.js';
+
+export const schema = {slackInstallations};
+
+let database: NodePgDatabase<typeof schema> | undefined;
+
+export function db() {
+  if (!database) database = drizzle(pgClient(), {schema});
+  return database;
+}
+
+export function closeDb(): void {
+  database = undefined;
+}

package/src/db/installations.test.ts

@@ -0,0 +1,93 @@
+import {
+  SlackConnectionAlreadyLinkedError,
+  SlackInstallationAlreadyLinkedError,
+} from '#core/errors.js';
+import {
+  getSlackInstallationByConnectionId,
+  getSlackInstallationByTeamId,
+  markSlackInstallationRevoked,
+  upsertSlackInstallation,
+} from './installations.js';
+
+function createInstallationInput(
+  overrides: Partial<Parameters<typeof upsertSlackInstallation>[0]> = {},
+) {
+  return {
+    connectionId: crypto.randomUUID(),
+    teamId: `T${crypto.randomUUID()}`,
+    teamName: 'Acme',
+    appId: 'A123',
+    botUserId: 'U123',
+    scopes: ['app_mentions:read'],
+    status: 'installed' as const,
+    ...overrides,
+  };
+}
+
+describe('slack installations', () => {
+  it('upserts and reads an installation by connection and team id', async () => {
+    const input = createInstallationInput();
+
+    const installation = await upsertSlackInstallation(input);
+    const byConnection = await getSlackInstallationByConnectionId(input.connectionId);
+    const byTeam = await getSlackInstallationByTeamId(input.teamId);
+
+    expect(byConnection).toEqual(installation);
+    expect(byTeam).toEqual(installation);
+  });
+
+  it('updates mutable metadata for an existing installation', async () => {
+    const input = createInstallationInput();
+    await upsertSlackInstallation(input);
+
+    const result = await upsertSlackInstallation({
+      ...input,
+      teamName: 'Acme renamed',
+      appId: 'A456',
+      botUserId: 'U456',
+      scopes: ['app_mentions:read', 'chat:write'],
+    });
+
+    expect(result).toMatchObject({
+      teamName: 'Acme renamed',
+      appId: 'A456',
+      botUserId: 'U456',
+      scopes: ['app_mentions:read', 'chat:write'],
+    });
+  });
+
+  it('refuses to claim a team already linked to another connection', async () => {
+    const first = createInstallationInput();
+    await upsertSlackInstallation(first);
+    const second = createInstallationInput({teamId: first.teamId});
+
+    const result = upsertSlackInstallation(second);
+
+    await expect(result).rejects.toBeInstanceOf(SlackInstallationAlreadyLinkedError);
+    await expect(getSlackInstallationByTeamId(first.teamId)).resolves.toMatchObject({
+      connectionId: first.connectionId,
+    });
+  });
+
+  it('refuses to repoint an existing connection to another team', async () => {
+    const first = createInstallationInput();
+    await upsertSlackInstallation(first);
+    const second = createInstallationInput({connectionId: first.connectionId});
+
+    const result = upsertSlackInstallation(second);
+
+    await expect(result).rejects.toBeInstanceOf(SlackConnectionAlreadyLinkedError);
+    await expect(getSlackInstallationByConnectionId(first.connectionId)).resolves.toMatchObject({
+      teamId: first.teamId,
+    });
+  });
+
+  it('marks an installation revoked by connection id', async () => {
+    const input = createInstallationInput();
+    await upsertSlackInstallation(input);
+
+    const result = await markSlackInstallationRevoked(input.connectionId);
+
+    expect(result?.status).toBe('revoked');
+  });
+});