@shipfox/api-integration-slack 4.0.0

package/drizzle/0000_calm_fantastic_four.sql

@@ -0,0 +1,16 @@
+CREATE TABLE "integrations_slack_installations" (
+	"id" uuid PRIMARY KEY DEFAULT uuidv7() NOT NULL,
+	"connection_id" uuid NOT NULL,
+	"team_id" text NOT NULL,
+	"team_name" text NOT NULL,
+	"app_id" text NOT NULL,
+	"bot_user_id" text NOT NULL,
+	"scopes" jsonb NOT NULL,
+	"status" text NOT NULL,
+	"token_expires_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX "integrations_slack_installations_connection_unique" ON "integrations_slack_installations" USING btree ("connection_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "integrations_slack_installations_team_unique" ON "integrations_slack_installations" USING btree ("team_id");

package/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,132 @@
+{
+  "id": "62801d4c-2399-4306-8d37-9773d10cbb02",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.integrations_slack_installations": {
+      "name": "integrations_slack_installations",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "uuidv7()"
+        },
+        "connection_id": {
+          "name": "connection_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "team_id": {
+          "name": "team_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "team_name": {
+          "name": "team_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "app_id": {
+          "name": "app_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "bot_user_id": {
+          "name": "bot_user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "scopes": {
+          "name": "scopes",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_expires_at": {
+          "name": "token_expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "integrations_slack_installations_connection_unique": {
+          "name": "integrations_slack_installations_connection_unique",
+          "columns": [
+            {
+              "expression": "connection_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "integrations_slack_installations_team_unique": {
+          "name": "integrations_slack_installations_team_unique",
+          "columns": [
+            {
+              "expression": "team_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1784372558063,
+      "tag": "0000_calm_fantastic_four",
+      "breakpoints": true
+    }
+  ]
+}

package/drizzle.config.ts

@@ -0,0 +1,7 @@
+import {defineConfig} from 'drizzle-kit';
+
+export default defineConfig({
+  schema: './src/db/schema/*.ts',
+  out: './drizzle',
+  dialect: 'postgresql',
+});

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@shipfox/api-integration-slack",
+  "license": "MIT",
+  "version": "4.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
+    "directory": "libs/api/integration/slack"
+  },
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "imports": {
+    "#test/*": "./test/*",
+    "#*": {
+      "workspace-source": "./src/*",
+      "development": "./src/*",
+      "default": "./dist/*"
+    }
+  },
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.2",
+    "ky": "^2.0.0",
+    "zod": "^4.4.3",
+    "@shipfox/api-auth-context": "3.0.0",
+    "@shipfox/api-integration-core-dto": "3.0.0",
+    "@shipfox/config": "1.2.1",
+    "@shipfox/api-integration-slack-dto": "4.0.0",
+    "@shipfox/api-workspaces": "4.0.0",
+    "@shipfox/node-drizzle": "0.3.0",
+    "@shipfox/node-fastify": "0.2.2",
+    "@shipfox/node-opentelemetry": "0.5.1",
+    "@shipfox/node-postgres": "0.4.1"
+  },
+  "peerDependencies": {
+    "@shipfox/api-secrets": "4.0.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.15.5",
+    "drizzle-kit": "^0.31.10",
+    "fastify": "^5.3.3",
+    "fishery": "^2.4.0",
+    "@shipfox/swc": "1.2.5",
+    "@shipfox/biome": "1.8.1",
+    "@shipfox/ts-config": "1.3.8",
+    "@shipfox/typescript": "1.1.6",
+    "@shipfox/vitest": "1.2.2"
+  },
+  "scripts": {
+    "build": "shipfox-swc",
+    "check": "shipfox-biome-check",
+    "check:fix": "shipfox-biome-check --write",
+    "test": "shipfox-vitest-run",
+    "test:watch": "shipfox-vitest-watch",
+    "type": "shipfox-tsc-check",
+    "type:emit": "shipfox-tsc-emit"
+  }
+}

package/src/api/client.test.ts

@@ -0,0 +1,239 @@
+import {HTTPError, TimeoutError} from 'ky';
+import {
+  SlackEnterpriseInstallUnsupportedError,
+  SlackIntegrationProviderError,
+  SlackTokenRotationUnsupportedError,
+} from '#core/errors.js';
+import {createSlackApiClient} from './client.js';
+
+const mocks = vi.hoisted(() => ({post: vi.fn(), warn: vi.fn()}));
+
+vi.mock('@shipfox/node-opentelemetry', () => ({logger: () => ({warn: mocks.warn})}));
+vi.mock('ky', () => {
+  class HTTPError extends Error {
+    constructor(public response: {status: number; statusText?: string; headers: Headers}) {
+      super('http');
+      this.name = 'HTTPError';
+    }
+  }
+  class TimeoutError extends Error {
+    constructor() {
+      super('timeout');
+      this.name = 'TimeoutError';
+    }
+  }
+  return {default: {post: mocks.post}, HTTPError, TimeoutError};
+});
+
+function resolves(data: unknown) {
+  return {json: () => Promise.resolve(data)};
+}
+
+function rejects(error: unknown) {
+  return {json: () => Promise.reject(error)};
+}
+
+function httpError(status: number, headers: Record<string, string> = {}): HTTPError {
+  return new HTTPError(
+    {status, statusText: 'Rejected', headers: new Headers(headers)} as never,
+    {} as never,
+    {} as never,
+  );
+}
+
+function oauthSuccess(overrides: Record<string, unknown> = {}) {
+  return {
+    ok: true,
+    access_token: 'xoxb-token',
+    bot_user_id: 'U123',
+    app_id: 'A123',
+    team: {id: 'T123', name: 'Acme'},
+    scope: 'app_mentions:read,chat:write',
+    ...overrides,
+  };
+}
+
+describe('createSlackApiClient', () => {
+  beforeEach(() => {
+    mocks.post.mockReset();
+    mocks.warn.mockReset();
+  });
+
+  it('posts a form-encoded OAuth exchange and parses the Slack installation', async () => {
+    mocks.post.mockReturnValue(resolves(oauthSuccess()));
+
+    const result = await createSlackApiClient().exchangeAuthorizationCode({code: 'oauth-code'});
+
+    const [url, options] = mocks.post.mock.calls[0] as [string, {body: URLSearchParams}];
+    expect(url).toBe('http://127.0.0.1:0/oauth.v2.access');
+    expect(options.body).toEqual(
+      new URLSearchParams({
+        client_id: 'test-client-id',
+        client_secret: 'test-client-secret',
+        code: 'oauth-code',
+        redirect_uri: 'https://shipfox.example.com/integrations/slack/callback',
+      }),
+    );
+    expect(result).toEqual({
+      accessToken: 'xoxb-token',
+      botUserId: 'U123',
+      appId: 'A123',
+      teamId: 'T123',
+      teamName: 'Acme',
+      scopes: ['app_mentions:read', 'chat:write'],
+    });
+  });
+
+  it.each([
+    ['invalid_code', 'access-denied'],
+    ['service_unavailable', 'provider-unavailable'],
+    ['ratelimited', 'rate-limited'],
+  ])('maps Slack application error %s to %s', async (error, reason) => {
+    mocks.post.mockReturnValue(resolves({ok: false, error}));
+
+    const result = createSlackApiClient().exchangeAuthorizationCode({code: 'oauth-code'});
+
+    await expect(result).rejects.toMatchObject({reason});
+  });
+
+  it.each([
+    oauthSuccess({is_enterprise_install: true}),
+    oauthSuccess({team: null}),
+  ])('rejects unsupported Enterprise Grid installs', async (body) => {
+    mocks.post.mockReturnValue(resolves(body));
+
+    const result = createSlackApiClient().exchangeAuthorizationCode({code: 'oauth-code'});
+
+    await expect(result).rejects.toBeInstanceOf(SlackEnterpriseInstallUnsupportedError);
+  });
+
+  it.each([
+    oauthSuccess({expires_in: 43_200}),
+    oauthSuccess({refresh_token: 'xoxe-1-refresh'}),
+  ])('rejects rotation-enabled OAuth responses', async (body) => {
+    mocks.post.mockReturnValue(resolves(body));
+
+    const result = createSlackApiClient().exchangeAuthorizationCode({code: 'oauth-code'});
+
+    await expect(result).rejects.toBeInstanceOf(SlackTokenRotationUnsupportedError);
+  });
+
+  it('never embeds a rotating token value in the thrown error', async () => {
+    mocks.post.mockReturnValue(resolves(oauthSuccess({refresh_token: 'xoxe-secret-refresh'})));
+
+    const error = await createSlackApiClient()
+      .exchangeAuthorizationCode({code: 'oauth-code'})
+      .catch((thrown: unknown) => thrown);
+
+    expect(error).toBeInstanceOf(SlackTokenRotationUnsupportedError);
+    expect((error as Error).message).toBe('Slack token rotation is not supported');
+    expect(String(error)).not.toContain('xoxe-secret-refresh');
+  });
+
+  it.each([
+    [rejects(httpError(503)), 'provider-unavailable'],
+    [rejects(httpError(403)), 'access-denied'],
+    [rejects(new TimeoutError({} as never)), 'timeout'],
+  ])('maps transport failures without leaking OAuth secrets', async (response, reason) => {
+    mocks.post.mockReturnValue(response);
+
+    const error = await createSlackApiClient()
+      .exchangeAuthorizationCode({code: 'super-secret-code'})
+      .catch((thrown: unknown) => thrown);
+
+    expect(error).toMatchObject({reason});
+    expect(JSON.stringify([error, mocks.warn.mock.calls])).not.toContain('super-secret-code');
+    expect(JSON.stringify([error, mocks.warn.mock.calls])).not.toContain('test-client-secret');
+  });
+
+  it('rejects malformed success payloads', async () => {
+    mocks.post.mockReturnValue(resolves(oauthSuccess({access_token: undefined})));
+
+    const result = createSlackApiClient().exchangeAuthorizationCode({code: 'oauth-code'});
+
+    await expect(result).rejects.toBeInstanceOf(SlackIntegrationProviderError);
+    await expect(result).rejects.toMatchObject({reason: 'malformed-provider-response'});
+  });
+
+  it('revokes with a bearer token and never logs it', async () => {
+    mocks.post.mockResolvedValue(undefined);
+
+    await createSlackApiClient().revokeToken({token: 'secret-token'});
+
+    expect(mocks.post).toHaveBeenCalledWith('http://127.0.0.1:0/auth.revoke', {
+      headers: {authorization: 'Bearer secret-token'},
+      timeout: 10_000,
+    });
+    expect(JSON.stringify(mocks.warn.mock.calls)).not.toContain('secret-token');
+  });
+
+  it.each([
+    {ok: true, channel: {id: 'C123'}},
+    {ok: false, error: 'channel_not_found'},
+  ])('passes through Slack Web API response %o', async (body) => {
+    mocks.post.mockReturnValue(resolves(body));
+
+    const result = await createSlackApiClient().callMethod({
+      method: 'conversations.history',
+      token: 'xoxb-secret',
+      arguments: {channel: 'C123'},
+    });
+
+    const [url, options] = mocks.post.mock.calls[0] as [
+      string,
+      {headers: {authorization: string}; body: URLSearchParams},
+    ];
+    expect(url).toBe('http://127.0.0.1:0/conversations.history');
+    expect(options.headers).toEqual({authorization: 'Bearer xoxb-secret'});
+    expect(options.body).toEqual(new URLSearchParams({channel: 'C123'}));
+    expect(result).toEqual(body);
+  });
+
+  it('serializes Slack method arguments as form values and omits nullish values', async () => {
+    mocks.post.mockReturnValue(resolves({ok: true}));
+    const blocks = [{type: 'section', text: {type: 'plain_text', text: 'Hello'}}];
+
+    await createSlackApiClient().callMethod({
+      method: 'chat.postMessage',
+      token: 'xoxb-secret',
+      arguments: {
+        blocks,
+        limit: 30,
+        inclusive: false,
+        types: 'public_channel,private_channel',
+        oldest: null,
+        latest: undefined,
+      },
+    });
+
+    const [, options] = mocks.post.mock.calls[0] as [string, {body: URLSearchParams}];
+    expect(Object.fromEntries(options.body)).toEqual({
+      blocks: JSON.stringify(blocks),
+      limit: '30',
+      inclusive: 'false',
+      types: 'public_channel,private_channel',
+    });
+    expect(options.body.has('oldest')).toBe(false);
+    expect(options.body.has('latest')).toBe(false);
+  });
+
+  it.each([
+    [httpError(429, {'retry-after': '17'}), 'rate-limited', 17],
+    [httpError(413), 'content-too-large', undefined],
+    [httpError(404), 'malformed-provider-response', undefined],
+  ])('maps Web API HTTP failures to %s', async (transportError, reason, retryAfterSeconds) => {
+    mocks.post.mockReturnValue(rejects(transportError));
+
+    const error = await createSlackApiClient()
+      .callMethod({
+        method: 'chat.postMessage',
+        token: 'xoxb-super-secret',
+        arguments: {channel: 'C123', text: 'sensitive body'},
+      })
+      .catch((thrown: unknown) => thrown);
+
+    expect(error).toMatchObject({reason, retryAfterSeconds});
+    expect(JSON.stringify(mocks.warn.mock.calls)).not.toContain('xoxb-super-secret');
+    expect(JSON.stringify(mocks.warn.mock.calls)).not.toContain('sensitive body');
+  });
+});