@shipfox/api-integration-webhook 2.0.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@shipfox/api-integration-webhook",
+  "license": "MIT",
+  "version": "2.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
+    "directory": "libs/api/integration/webhook"
+  },
+  "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": {
+    "@fastify/formbody": "^8.0.2",
+    "fastify-plugin": "^5.1.0",
+    "zod": "^4.4.3",
+    "@shipfox/api-auth-context": "2.0.0",
+    "@shipfox/api-integration-core-dto": "2.0.0",
+    "@shipfox/node-fastify": "0.2.1",
+    "@shipfox/config": "1.2.1",
+    "@shipfox/api-integration-webhook-dto": "2.0.0"
+  },
+  "devDependencies": {
+    "fastify": "^5.3.3",
+    "fastify-type-provider-zod": "^6.0.0",
+    "@shipfox/biome": "1.8.1",
+    "@shipfox/ts-config": "1.3.8",
+    "@shipfox/vitest": "1.2.2",
+    "@shipfox/swc": "1.2.5",
+    "@shipfox/typescript": "1.1.6"
+  },
+  "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/config.ts

@@ -0,0 +1,8 @@
+import {createConfig, url} from '@shipfox/config';
+
+export const config = createConfig({
+  WEBHOOK_PUBLIC_URL: url({
+    desc: 'Public origin of the API used to build webhook inbound URLs returned to users. Set it to the externally reachable API URL, including the scheme.',
+    default: 'http://localhost:3000',
+  }),
+});

package/src/constants.test.ts

@@ -0,0 +1,23 @@
+import {redactHeaders} from './constants.js';
+
+describe('redactHeaders', () => {
+  it('keeps allowlisted headers and redacts every other value', () => {
+    const result = redactHeaders({
+      'content-type': 'application/json',
+      'user-agent': 'test-agent',
+      'x-delivery-id': 'delivery-1',
+      authorization: 'Bearer secret',
+      cookie: 'sid=secret',
+      'x-custom-secret': ['one', 'two'],
+    });
+
+    expect(result).toEqual({
+      'content-type': 'application/json',
+      'user-agent': 'test-agent',
+      'x-delivery-id': 'delivery-1',
+      authorization: '[redacted]',
+      cookie: '[redacted]',
+      'x-custom-secret': '[redacted]',
+    });
+  });
+});

package/src/constants.ts

@@ -0,0 +1,21 @@
+export const WEBHOOK_INBOUND_BODY_LIMIT = 1 * 1024 * 1024;
+
+export const WEBHOOK_FORWARDED_HEADERS = [
+  'content-type',
+  'user-agent',
+  'x-delivery-id',
+  'x-request-id',
+] as const;
+
+const forwardedHeaderSet = new Set<string>(WEBHOOK_FORWARDED_HEADERS);
+
+export function redactHeaders(
+  headers: Record<string, string | string[] | undefined>,
+): Record<string, string | string[]> {
+  const redacted: Record<string, string | string[]> = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (value === undefined) continue;
+    redacted[name] = forwardedHeaderSet.has(name.toLowerCase()) ? value : '[redacted]';
+  }
+  return redacted;
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+import type {
+  CreateIntegrationConnectionFn,
+  DeleteIntegrationConnectionFn,
+  GetIntegrationConnectionByIdFn,
+  IntegrationConnection,
+  IntegrationTx,
+  PublishIntegrationEventReceivedFn,
+  UpdateIntegrationConnectionLifecycleStatusFn,
+} from '@shipfox/api-integration-core-dto';
+import {WEBHOOK_PROVIDER} from '@shipfox/api-integration-webhook-dto';
+import {config} from '#config.js';
+import {createWebhookConnectionRoutes} from '#presentation/routes/connections.js';
+import {createWebhookInboundRoutes} from '#presentation/routes/inbound.js';
+
+export {redactHeaders, WEBHOOK_FORWARDED_HEADERS, WEBHOOK_INBOUND_BODY_LIMIT} from '#constants.js';
+
+export interface CreateWebhookIntegrationProviderOptions {
+  coreDb: () => {
+    transaction<T>(callback: (tx: IntegrationTx) => Promise<T>): Promise<T>;
+  };
+  createIntegrationConnection: CreateIntegrationConnectionFn;
+  listIntegrationConnections: (params: {workspaceId: string}) => Promise<IntegrationConnection[]>;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+  updateIntegrationConnectionLifecycleStatus: UpdateIntegrationConnectionLifecycleStatusFn;
+  deleteIntegrationConnection: DeleteIntegrationConnectionFn;
+  publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+  baseUrl?: string | undefined;
+}
+
+export function createWebhookIntegrationProvider(options: CreateWebhookIntegrationProviderOptions) {
+  const baseUrl = options.baseUrl ?? config.WEBHOOK_PUBLIC_URL;
+  return {
+    provider: WEBHOOK_PROVIDER,
+    displayName: 'Webhook',
+    routes: [
+      createWebhookConnectionRoutes({
+        baseUrl,
+        createIntegrationConnection: options.createIntegrationConnection,
+        listIntegrationConnections: options.listIntegrationConnections,
+        getIntegrationConnectionById: options.getIntegrationConnectionById,
+        updateIntegrationConnectionLifecycleStatus:
+          options.updateIntegrationConnectionLifecycleStatus,
+        deleteIntegrationConnection: options.deleteIntegrationConnection,
+      }),
+      createWebhookInboundRoutes({
+        coreDb: options.coreDb,
+        getIntegrationConnectionById: options.getIntegrationConnectionById,
+        publishIntegrationEventReceived: options.publishIntegrationEventReceived,
+      }),
+    ],
+  };
+}

package/src/presentation/dto/connections.ts

@@ -0,0 +1,20 @@
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import type {WebhookConnectionDto} from '@shipfox/api-integration-webhook-dto';
+
+const TRAILING_SLASHES_RE = /\/+$/;
+
+export function toWebhookConnectionDto(
+  connection: IntegrationConnection,
+  baseUrl: string,
+): WebhookConnectionDto {
+  return {
+    id: connection.id,
+    workspace_id: connection.workspaceId,
+    name: connection.displayName,
+    slug: connection.slug,
+    lifecycle_status: connection.lifecycleStatus,
+    inbound_url: `${baseUrl.replace(TRAILING_SLASHES_RE, '')}/webhook/${connection.id}`,
+    created_at: connection.createdAt.toISOString(),
+    updated_at: connection.updatedAt.toISOString(),
+  };
+}

package/src/presentation/routes/connections.test.ts

@@ -0,0 +1,374 @@
+import {
+  AUTH_USER,
+  buildUserContext,
+  setUserContext,
+  type UserContextMembership,
+} from '@shipfox/api-auth-context';
+import {
+  ConnectionSlugConflictError,
+  type IntegrationConnection,
+} from '@shipfox/api-integration-core-dto';
+import {WEBHOOK_RESERVED_SLUGS} from '@shipfox/api-integration-webhook-dto';
+import {type AuthMethod, ClientError, closeApp, createApp} from '@shipfox/node-fastify';
+import type {FastifyInstance, FastifyRequest} from 'fastify';
+import type {CreateWebhookIntegrationProviderOptions} from '#index.js';
+import {createWebhookIntegrationProvider} from '#index.js';
+
+type CreateConnectionFn = CreateWebhookIntegrationProviderOptions['createIntegrationConnection'];
+type ListConnectionsFn = CreateWebhookIntegrationProviderOptions['listIntegrationConnections'];
+type GetConnectionFn = CreateWebhookIntegrationProviderOptions['getIntegrationConnectionById'];
+type UpdateConnectionFn =
+  CreateWebhookIntegrationProviderOptions['updateIntegrationConnectionLifecycleStatus'];
+type DeleteConnectionFn = CreateWebhookIntegrationProviderOptions['deleteIntegrationConnection'];
+
+const INBOUND_URL_RE = /^https:\/\/api\.example\.com\/webhook\//;
+
+let authenticatedMemberships: UserContextMembership[] = [];
+
+function authorizeWorkspace(workspaceId: string): void {
+  authenticatedMemberships = [{workspaceId, role: 'admin'}];
+}
+
+const fakeUserAuth: AuthMethod = {
+  name: AUTH_USER,
+  authenticate: (request: FastifyRequest) => {
+    if (request.headers.authorization !== 'Bearer user') {
+      throw new ClientError('Invalid user token', 'unauthorized', {status: 401});
+    }
+
+    setUserContext(
+      request,
+      buildUserContext({
+        userId: 'user-1',
+        email: 'user@example.com',
+        memberships: authenticatedMemberships,
+      }),
+    );
+    return Promise.resolve();
+  },
+};
+
+function duplicateSlugError(): Error {
+  const error = new Error('duplicate connection');
+  error.name = 'IntegrationConnectionAlreadyExistsError';
+  return error;
+}
+
+function connectionSlugConflictError(): Error {
+  return new ConnectionSlugConflictError(new Error('duplicate slug'));
+}
+
+function fakeConnection(overrides: Partial<IntegrationConnection> = {}): IntegrationConnection {
+  const now = new Date();
+  return {
+    id: crypto.randomUUID(),
+    workspaceId: crypto.randomUUID(),
+    provider: 'webhook',
+    externalAccountId: 'stripe',
+    slug: 'stripe',
+    displayName: 'Stripe',
+    lifecycleStatus: 'active',
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  };
+}
+
+function createStore() {
+  const byId = new Map<string, IntegrationConnection>();
+  const bySlug = new Map<string, string>();
+  const seed = (connection: IntegrationConnection) => {
+    byId.set(connection.id, connection);
+    bySlug.set(`${connection.workspaceId}:${connection.slug}`, connection.id);
+    return connection;
+  };
+
+  return {
+    seed,
+    createIntegrationConnection: vi.fn<CreateConnectionFn>((input) => {
+      const key = `${input.workspaceId}:${input.slug}`;
+      if (bySlug.has(key)) throw duplicateSlugError();
+      const connection = fakeConnection({
+        workspaceId: input.workspaceId,
+        provider: input.provider,
+        externalAccountId: input.externalAccountId,
+        slug: input.slug,
+        displayName: input.displayName,
+        lifecycleStatus: input.lifecycleStatus ?? 'active',
+      });
+      seed(connection);
+      return Promise.resolve(connection);
+    }),
+    listIntegrationConnections: vi.fn<ListConnectionsFn>(({workspaceId}) =>
+      Promise.resolve(
+        [...byId.values()].filter((connection) => connection.workspaceId === workspaceId),
+      ),
+    ),
+    getIntegrationConnectionById: vi.fn<GetConnectionFn>((id) => Promise.resolve(byId.get(id))),
+    updateIntegrationConnectionLifecycleStatus: vi.fn<UpdateConnectionFn>(
+      ({id, lifecycleStatus}) => {
+        const connection = byId.get(id);
+        if (!connection) return Promise.resolve(undefined);
+        const updated = {...connection, lifecycleStatus, updatedAt: new Date()};
+        byId.set(id, updated);
+        return Promise.resolve(updated);
+      },
+    ),
+    deleteIntegrationConnection: vi.fn<DeleteConnectionFn>(({id}) =>
+      Promise.resolve(byId.delete(id)),
+    ),
+  };
+}
+
+async function createTestApp(store = createStore()): Promise<{
+  app: FastifyInstance;
+  store: ReturnType<typeof createStore>;
+}> {
+  const provider = createWebhookIntegrationProvider({
+    baseUrl: 'https://api.example.com/',
+    coreDb: () => ({transaction: (callback) => callback({})}),
+    publishIntegrationEventReceived: vi.fn(() => Promise.resolve({published: true})),
+    ...store,
+  } satisfies CreateWebhookIntegrationProviderOptions);
+  const app = await createApp({
+    auth: [fakeUserAuth],
+    routes: provider.routes,
+    swagger: false,
+  });
+  await app.ready();
+  return {app, store};
+}
+
+describe('webhook connection routes', () => {
+  beforeEach(async () => {
+    authenticatedMemberships = [];
+    await closeApp();
+  });
+
+  afterEach(async () => {
+    await closeApp();
+  });
+
+  it('creates a webhook connection with its inbound URL', async () => {
+    const workspaceId = crypto.randomUUID();
+    authorizeWorkspace(workspaceId);
+    const {app} = await createTestApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/webhook/connections',
+      headers: {authorization: 'Bearer user'},
+      payload: {workspace_id: workspaceId, name: 'Stripe', slug: 'stripe-prod'},
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toMatchObject({
+      workspace_id: workspaceId,
+      name: 'Stripe',
+      slug: 'stripe-prod',
+      lifecycle_status: 'active',
+      inbound_url: expect.stringMatching(INBOUND_URL_RE),
+    });
+  });
+
+  it('returns 409 for a duplicate slug in the workspace', async () => {
+    const workspaceId = crypto.randomUUID();
+    authorizeWorkspace(workspaceId);
+    const {app} = await createTestApp();
+    const payload = {workspace_id: workspaceId, name: 'Stripe', slug: 'stripe-prod'};
+
+    const first = await app.inject({
+      method: 'POST',
+      url: '/integrations/webhook/connections',
+      headers: {authorization: 'Bearer user'},
+      payload,
+    });
+    const second = await app.inject({
+      method: 'POST',
+      url: '/integrations/webhook/connections',
+      headers: {authorization: 'Bearer user'},
+      payload,
+    });
+
+    expect(first.statusCode).toBe(201);
+    expect(second.statusCode).toBe(409);
+    expect(second.json().code).toBe('slug-already-exists');
+  });
+
+  it('returns 409 when the core connection create reports a slug conflict', async () => {
+    const workspaceId = crypto.randomUUID();
+    authorizeWorkspace(workspaceId);
+    const store = createStore();
+    store.createIntegrationConnection.mockRejectedValueOnce(connectionSlugConflictError());
+    const {app} = await createTestApp(store);
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/webhook/connections',
+      headers: {authorization: 'Bearer user'},
+      payload: {workspace_id: workspaceId, name: 'Stripe', slug: 'stripe-prod'},
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json().code).toBe('slug-already-exists');
+  });
+
+  it('lists only webhook connections for the workspace', async () => {
+    const workspaceId = crypto.randomUUID();
+    authorizeWorkspace(workspaceId);
+    const store = createStore();
+    const webhook = store.seed(fakeConnection({workspaceId, externalAccountId: 'stripe'}));
+    store.seed(fakeConnection({workspaceId, provider: 'github', externalAccountId: 'gh'}));
+    store.seed(fakeConnection({workspaceId: crypto.randomUUID(), externalAccountId: 'other'}));
+    const {app} = await createTestApp(store);
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integrations/webhook/connections?workspace_id=${workspaceId}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().connections).toEqual([
+      expect.objectContaining({id: webhook.id, slug: 'stripe'}),
+    ]);
+  });
+
+  it('updates a webhook connection lifecycle status', async () => {
+    const store = createStore();
+    const connection = store.seed(fakeConnection());
+    authorizeWorkspace(connection.workspaceId);
+    const {app} = await createTestApp(store);
+
+    const res = await app.inject({
+      method: 'PATCH',
+      url: `/integrations/webhook/connections/${connection.id}`,
+      headers: {authorization: 'Bearer user'},
+      payload: {lifecycle_status: 'disabled'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().lifecycle_status).toBe('disabled');
+  });
+
+  it.each([
+    {description: 'missing connection', connectionId: crypto.randomUUID()},
+    {
+      description: 'non-webhook connection',
+      connectionId: undefined,
+      seed: (store: ReturnType<typeof createStore>) =>
+        store.seed(fakeConnection({provider: 'github'})).id,
+    },
+  ])('returns 404 when patching a $description', async ({connectionId, seed}) => {
+    const store = createStore();
+    const id = seed ? seed(store) : connectionId;
+    if (seed && id) {
+      const connection = await store.getIntegrationConnectionById(id);
+      if (connection) authorizeWorkspace(connection.workspaceId);
+    }
+    const {app} = await createTestApp(store);
+
+    const res = await app.inject({
+      method: 'PATCH',
+      url: `/integrations/webhook/connections/${id}`,
+      headers: {authorization: 'Bearer user'},
+      payload: {lifecycle_status: 'disabled'},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('not-found');
+    expect(store.updateIntegrationConnectionLifecycleStatus).not.toHaveBeenCalled();
+  });
+
+  it('returns 404 when a webhook connection disappears during patch', async () => {
+    const store = createStore();
+    const connection = store.seed(fakeConnection());
+    authorizeWorkspace(connection.workspaceId);
+    store.updateIntegrationConnectionLifecycleStatus.mockResolvedValueOnce(undefined);
+    const {app} = await createTestApp(store);
+
+    const res = await app.inject({
+      method: 'PATCH',
+      url: `/integrations/webhook/connections/${connection.id}`,
+      headers: {authorization: 'Bearer user'},
+      payload: {lifecycle_status: 'disabled'},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('not-found');
+  });
+
+  it('deletes a webhook connection', async () => {
+    const store = createStore();
+    const connection = store.seed(fakeConnection());
+    authorizeWorkspace(connection.workspaceId);
+    const {app} = await createTestApp(store);
+
+    const res = await app.inject({
+      method: 'DELETE',
+      url: `/integrations/webhook/connections/${connection.id}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(204);
+    expect(store.deleteIntegrationConnection).toHaveBeenCalledWith({id: connection.id});
+  });
+
+  it.each([
+    {description: 'missing connection', connectionId: crypto.randomUUID()},
+    {
+      description: 'non-webhook connection',
+      connectionId: undefined,
+      seed: (store: ReturnType<typeof createStore>) =>
+        store.seed(fakeConnection({provider: 'github'})).id,
+    },
+  ])('returns 404 when deleting a $description', async ({connectionId, seed}) => {
+    const store = createStore();
+    const id = seed ? seed(store) : connectionId;
+    if (seed && id) {
+      const connection = await store.getIntegrationConnectionById(id);
+      if (connection) authorizeWorkspace(connection.workspaceId);
+    }
+    const {app} = await createTestApp(store);
+
+    const res = await app.inject({
+      method: 'DELETE',
+      url: `/integrations/webhook/connections/${id}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('not-found');
+    expect(store.deleteIntegrationConnection).not.toHaveBeenCalled();
+  });
+
+  it.each(WEBHOOK_RESERVED_SLUGS)('rejects reserved slug %s', async (slug) => {
+    const workspaceId = crypto.randomUUID();
+    authorizeWorkspace(workspaceId);
+    const {app} = await createTestApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/webhook/connections',
+      headers: {authorization: 'Bearer user'},
+      payload: {workspace_id: workspaceId, name: 'Reserved', slug},
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('rejects a malformed slug', async () => {
+    const workspaceId = crypto.randomUUID();
+    authorizeWorkspace(workspaceId);
+    const {app} = await createTestApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/webhook/connections',
+      headers: {authorization: 'Bearer user'},
+      payload: {workspace_id: workspaceId, name: 'Malformed', slug: 'Stripe_Prod'},
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+});