@shipfox/api-integration-webhook 2.0.0

package/src/presentation/routes/connections.ts

@@ -0,0 +1,184 @@
+import {AUTH_USER, requireWorkspaceAccess} from '@shipfox/api-auth-context';
+import {
+  ConnectionSlugConflictError,
+  type CreateIntegrationConnectionFn,
+  type DeleteIntegrationConnectionFn,
+  type GetIntegrationConnectionByIdFn,
+  type IntegrationConnection,
+  type UpdateIntegrationConnectionLifecycleStatusFn,
+} from '@shipfox/api-integration-core-dto';
+import {
+  createWebhookConnectionBodySchema,
+  listWebhookConnectionsQuerySchema,
+  listWebhookConnectionsResponseSchema,
+  updateWebhookConnectionBodySchema,
+  WEBHOOK_PROVIDER,
+  webhookConnectionDtoSchema,
+} from '@shipfox/api-integration-webhook-dto';
+import {ClientError, defineRoute, type RouteGroup} from '@shipfox/node-fastify';
+import type {FastifyRequest} from 'fastify';
+import {z} from 'zod';
+import {toWebhookConnectionDto} from '#presentation/dto/connections.js';
+
+export interface CreateWebhookConnectionRoutesOptions {
+  baseUrl: string;
+  createIntegrationConnection: CreateIntegrationConnectionFn;
+  listIntegrationConnections: (params: {workspaceId: string}) => Promise<IntegrationConnection[]>;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+  updateIntegrationConnectionLifecycleStatus: UpdateIntegrationConnectionLifecycleStatusFn;
+  deleteIntegrationConnection: DeleteIntegrationConnectionFn;
+}
+
+const connectionParamsSchema = z.object({
+  connectionId: z.string().uuid(),
+});
+
+function isConnectionAlreadyExistsError(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    ((error as {name?: unknown}).name === 'IntegrationConnectionAlreadyExistsError' ||
+      error instanceof ConnectionSlugConflictError)
+  );
+}
+
+async function requireWebhookConnection(params: {
+  request: FastifyRequest;
+  connectionId: string;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+}): Promise<IntegrationConnection> {
+  const connection = await params.getIntegrationConnectionById(params.connectionId);
+  if (!connection || connection.provider !== WEBHOOK_PROVIDER) {
+    throw new ClientError('Webhook connection not found', 'not-found', {status: 404});
+  }
+
+  requireWorkspaceAccess({request: params.request, workspaceId: connection.workspaceId});
+  return connection;
+}
+
+export function createWebhookConnectionRoutes(
+  options: CreateWebhookConnectionRoutesOptions,
+): RouteGroup {
+  const createConnectionRoute = defineRoute({
+    method: 'POST',
+    path: '/connections',
+    auth: AUTH_USER,
+    description: 'Create a generic webhook connection.',
+    schema: {
+      body: createWebhookConnectionBodySchema,
+      response: {
+        201: webhookConnectionDtoSchema,
+      },
+    },
+    errorHandler: (error) => {
+      if (isConnectionAlreadyExistsError(error)) {
+        throw new ClientError('Webhook slug already exists', 'slug-already-exists', {status: 409});
+      }
+      throw error;
+    },
+    handler: async (request, reply) => {
+      const {workspace_id: workspaceId, name, slug} = request.body;
+
+      requireWorkspaceAccess({request, workspaceId});
+      const connection = await options.createIntegrationConnection({
+        workspaceId,
+        provider: WEBHOOK_PROVIDER,
+        // The generic webhook provider uses the human slug as its provider-side account id.
+        externalAccountId: slug,
+        slug,
+        displayName: name,
+      });
+
+      reply.status(201);
+      return toWebhookConnectionDto(connection, options.baseUrl);
+    },
+  });
+
+  const listConnectionsRoute = defineRoute({
+    method: 'GET',
+    path: '/connections',
+    auth: AUTH_USER,
+    description: 'List generic webhook connections for a workspace.',
+    schema: {
+      querystring: listWebhookConnectionsQuerySchema,
+      response: {
+        200: listWebhookConnectionsResponseSchema,
+      },
+    },
+    handler: async (request) => {
+      const {workspace_id: workspaceId} = request.query;
+
+      requireWorkspaceAccess({request, workspaceId});
+      const connections = (await options.listIntegrationConnections({workspaceId})).filter(
+        (connection) => connection.provider === WEBHOOK_PROVIDER,
+      );
+      return {
+        connections: connections.map((connection) =>
+          toWebhookConnectionDto(connection, options.baseUrl),
+        ),
+      };
+    },
+  });
+
+  const updateConnectionRoute = defineRoute({
+    method: 'PATCH',
+    path: '/connections/:connectionId',
+    auth: AUTH_USER,
+    description: 'Update a generic webhook connection.',
+    schema: {
+      params: connectionParamsSchema,
+      body: updateWebhookConnectionBodySchema,
+      response: {
+        200: webhookConnectionDtoSchema,
+      },
+    },
+    handler: async (request) => {
+      const connection = await requireWebhookConnection({
+        request,
+        connectionId: request.params.connectionId,
+        getIntegrationConnectionById: options.getIntegrationConnectionById,
+      });
+      const updated = await options.updateIntegrationConnectionLifecycleStatus({
+        id: connection.id,
+        lifecycleStatus: request.body.lifecycle_status,
+      });
+      if (!updated) {
+        throw new ClientError('Webhook connection not found', 'not-found', {status: 404});
+      }
+      return toWebhookConnectionDto(updated, options.baseUrl);
+    },
+  });
+
+  const deleteConnectionRoute = defineRoute({
+    method: 'DELETE',
+    path: '/connections/:connectionId',
+    auth: AUTH_USER,
+    description: 'Delete a generic webhook connection.',
+    schema: {
+      params: connectionParamsSchema,
+      response: {
+        204: z.void(),
+      },
+    },
+    handler: async (request, reply) => {
+      const connection = await requireWebhookConnection({
+        request,
+        connectionId: request.params.connectionId,
+        getIntegrationConnectionById: options.getIntegrationConnectionById,
+      });
+
+      await options.deleteIntegrationConnection({id: connection.id});
+      reply.code(204);
+    },
+  });
+
+  return {
+    prefix: '/integrations/webhook',
+    routes: [
+      createConnectionRoute,
+      listConnectionsRoute,
+      updateConnectionRoute,
+      deleteConnectionRoute,
+    ],
+  };
+}

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

@@ -0,0 +1,210 @@
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {closeApp, createApp} from '@shipfox/node-fastify';
+import type {FastifyInstance} from 'fastify';
+import {createWebhookInboundRoutes} from './inbound.js';
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+function fakeConnection(overrides: Partial<IntegrationConnection> = {}): IntegrationConnection {
+  const now = new Date();
+  return {
+    id: crypto.randomUUID(),
+    workspaceId: crypto.randomUUID(),
+    provider: 'webhook',
+    externalAccountId: 'stripe-prod',
+    slug: 'stripe_prod',
+    displayName: 'Stripe Production',
+    lifecycleStatus: 'active',
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  };
+}
+
+async function createTestApp(
+  options: {connection?: IntegrationConnection | undefined} = {},
+): Promise<{
+  app: FastifyInstance;
+  publishIntegrationEventReceived: ReturnType<typeof vi.fn>;
+  getIntegrationConnectionById: ReturnType<typeof vi.fn>;
+}> {
+  const connection = options.connection ?? fakeConnection();
+  const publishIntegrationEventReceived = vi.fn(() => Promise.resolve({published: true}));
+  const getIntegrationConnectionById = vi.fn((id: string) =>
+    Promise.resolve(id === connection.id ? connection : undefined),
+  );
+  const routes = createWebhookInboundRoutes({
+    coreDb: () => ({transaction: (callback) => callback({})}),
+    getIntegrationConnectionById,
+    publishIntegrationEventReceived,
+  });
+  const app = await createApp({routes: [routes], swagger: false});
+  await app.ready();
+  return {app, publishIntegrationEventReceived, getIntegrationConnectionById};
+}
+
+describe('webhook inbound route', () => {
+  beforeEach(async () => {
+    await closeApp();
+  });
+
+  afterEach(async () => {
+    await closeApp();
+  });
+
+  it('publishes a JSON delivery envelope', async () => {
+    const connection = fakeConnection();
+    const {app, publishIntegrationEventReceived} = await createTestApp({connection});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: `/webhook/${connection.id}?mode=test`,
+      headers: {
+        'content-type': 'application/json',
+        'x-delivery-id': 'evt-1',
+        authorization: 'Bearer secret',
+      },
+      payload: {ok: true},
+    });
+
+    expect(res.statusCode).toBe(202);
+    expect(res.json().delivery_id).toBe('evt-1');
+    expect(publishIntegrationEventReceived).toHaveBeenCalledTimes(1);
+    expect(publishIntegrationEventReceived.mock.calls[0]?.[0].event).toMatchObject({
+      provider: 'webhook',
+      source: 'stripe_prod',
+      event: 'received',
+      workspaceId: connection.workspaceId,
+      connectionId: connection.id,
+      connectionName: 'Stripe Production',
+      deliveryId: 'evt-1',
+      payload: {
+        method: 'POST',
+        query: {mode: 'test'},
+        body: {ok: true},
+        headers: {
+          'content-type': 'application/json',
+          'x-delivery-id': 'evt-1',
+          authorization: '[redacted]',
+        },
+      },
+    });
+  });
+
+  it('publishes a form delivery envelope', async () => {
+    const connection = fakeConnection();
+    const {app, publishIntegrationEventReceived} = await createTestApp({connection});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: `/webhook/${connection.id}`,
+      headers: {'content-type': 'application/x-www-form-urlencoded'},
+      payload: 'status=paid&amount=1200',
+    });
+
+    expect(res.statusCode).toBe(202);
+    expect(publishIntegrationEventReceived.mock.calls[0]?.[0].event.payload.body).toEqual({
+      status: 'paid',
+      amount: '1200',
+    });
+  });
+
+  it('publishes a text delivery envelope', async () => {
+    const connection = fakeConnection();
+    const {app, publishIntegrationEventReceived} = await createTestApp({connection});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: `/webhook/${connection.id}`,
+      headers: {'content-type': 'text/plain'},
+      payload: 'hello',
+    });
+
+    expect(res.statusCode).toBe(202);
+    expect(publishIntegrationEventReceived.mock.calls[0]?.[0].event.payload.body).toBe('hello');
+  });
+
+  it('rejects unsupported content types without publishing', async () => {
+    const connection = fakeConnection();
+    const {app, publishIntegrationEventReceived} = await createTestApp({connection});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: `/webhook/${connection.id}`,
+      headers: {'content-type': 'application/xml'},
+      payload: '<ok />',
+    });
+
+    expect(res.statusCode).toBe(415);
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+  });
+
+  it('rejects malformed JSON without publishing', async () => {
+    const connection = fakeConnection();
+    const {app, publishIntegrationEventReceived} = await createTestApp({connection});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: `/webhook/${connection.id}`,
+      headers: {'content-type': 'application/json'},
+      payload: '{"ok":',
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    {connection: undefined, description: 'unknown connection'},
+    {connection: fakeConnection({lifecycleStatus: 'disabled'}), description: 'disabled connection'},
+    {connection: fakeConnection({provider: 'github'}), description: 'wrong provider'},
+  ])('returns 404 for $description without publishing', async ({connection}) => {
+    const activeConnection = connection ?? fakeConnection();
+    const {app, publishIntegrationEventReceived} = await createTestApp({connection});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: `/webhook/${activeConnection.id}`,
+      headers: {'content-type': 'application/json'},
+      payload: {ok: true},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+  });
+
+  it('uses a random delivery ID when no header is present', async () => {
+    const connection = fakeConnection();
+    const {app, publishIntegrationEventReceived} = await createTestApp({connection});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: `/webhook/${connection.id}`,
+      headers: {'content-type': 'application/json'},
+      payload: {ok: true},
+    });
+
+    expect(res.statusCode).toBe(202);
+    const deliveryId = publishIntegrationEventReceived.mock.calls[0]?.[0].event.deliveryId;
+    expect(deliveryId).toMatch(UUID_RE);
+  });
+
+  it('rejects an overlong delivery ID header without publishing', async () => {
+    const connection = fakeConnection();
+    const {app, publishIntegrationEventReceived} = await createTestApp({connection});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: `/webhook/${connection.id}`,
+      headers: {
+        'content-type': 'application/json',
+        'x-delivery-id': 'x'.repeat(201),
+      },
+      payload: {ok: true},
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().code).toBe('delivery-id-too-long');
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+  });
+});

package/src/presentation/routes/inbound.ts

@@ -0,0 +1,132 @@
+import type {Buffer} from 'node:buffer';
+import {randomUUID} from 'node:crypto';
+import formBodyPlugin from '@fastify/formbody';
+import type {
+  GetIntegrationConnectionByIdFn,
+  IntegrationTx,
+  PublishIntegrationEventReceivedFn,
+} from '@shipfox/api-integration-core-dto';
+import {WEBHOOK_PROVIDER, WEBHOOK_RECEIVED_EVENT} from '@shipfox/api-integration-webhook-dto';
+import {ClientError, defineRoute, type RouteGroup} from '@shipfox/node-fastify';
+import type {FastifyPluginAsync} from 'fastify';
+import fp from 'fastify-plugin';
+import {z} from 'zod';
+import {redactHeaders, WEBHOOK_INBOUND_BODY_LIMIT} from '#constants.js';
+
+const MAX_DELIVERY_ID_HEADER_LENGTH = 200;
+const acceptedContentTypes = new Set([
+  'application/json',
+  'application/x-www-form-urlencoded',
+  'text/plain',
+]);
+const FORM_URLENCODED_CONTENT_TYPE_RE = /^application\/x-www-form-urlencoded(?:;.*)?$/i;
+
+const formBodyRoutePlugin: FastifyPluginAsync = fp(async (app) => {
+  await app.register(formBodyPlugin, {bodyLimit: WEBHOOK_INBOUND_BODY_LIMIT});
+
+  app.addContentTypeParser(
+    FORM_URLENCODED_CONTENT_TYPE_RE,
+    {parseAs: 'buffer', bodyLimit: WEBHOOK_INBOUND_BODY_LIMIT},
+    (_request, body: Buffer, done) => {
+      done(null, Object.fromEntries(new URLSearchParams(body.toString('utf8'))));
+    },
+  );
+});
+
+export interface CreateWebhookInboundRoutesOptions {
+  coreDb: () => {
+    transaction<T>(callback: (tx: IntegrationTx) => Promise<T>): Promise<T>;
+  };
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+  publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+}
+
+const inboundParamsSchema = z.object({
+  connectionId: z.string().uuid(),
+});
+
+const inboundQuerySchema = z.record(z.string(), z.unknown());
+
+const inboundAcceptedResponseSchema = z.object({
+  delivery_id: z.string(),
+});
+
+function contentType(requestContentType: string | undefined): string | undefined {
+  return requestContentType?.split(';', 1)[0]?.trim().toLowerCase();
+}
+
+function deliveryIdFor(header: string | string[] | undefined): string {
+  const value = Array.isArray(header) ? header[0] : header;
+  if (!value) return randomUUID();
+  if (value.length > MAX_DELIVERY_ID_HEADER_LENGTH) {
+    throw new ClientError('Delivery ID header is too long', 'delivery-id-too-long', {status: 400});
+  }
+  return value;
+}
+
+export function createWebhookInboundRoutes(options: CreateWebhookInboundRoutesOptions): RouteGroup {
+  const inboundRoute = defineRoute({
+    method: 'POST',
+    path: '/:connectionId',
+    auth: [],
+    description: 'Generic webhook receiver.',
+    options: {bodyLimit: WEBHOOK_INBOUND_BODY_LIMIT},
+    schema: {
+      params: inboundParamsSchema,
+      querystring: inboundQuerySchema,
+      response: {
+        202: inboundAcceptedResponseSchema,
+      },
+    },
+    handler: async (request, reply) => {
+      const mediaType = contentType(request.headers['content-type']);
+      if (!mediaType || !acceptedContentTypes.has(mediaType)) {
+        throw new ClientError('Unsupported content type', 'unsupported-media-type', {status: 415});
+      }
+
+      const {connectionId} = request.params;
+      const connection = await options.getIntegrationConnectionById(connectionId);
+      if (
+        !connection ||
+        connection.provider !== WEBHOOK_PROVIDER ||
+        connection.lifecycleStatus !== 'active'
+      ) {
+        throw new ClientError('Webhook connection not found', 'not-found', {status: 404});
+      }
+
+      const deliveryId = deliveryIdFor(request.headers['x-delivery-id']);
+      const receivedAt = new Date().toISOString();
+      await options.coreDb().transaction(async (tx) => {
+        await options.publishIntegrationEventReceived({
+          tx,
+          event: {
+            provider: WEBHOOK_PROVIDER,
+            source: connection.slug,
+            event: WEBHOOK_RECEIVED_EVENT,
+            workspaceId: connection.workspaceId,
+            connectionId: connection.id,
+            connectionName: connection.displayName,
+            deliveryId,
+            receivedAt,
+            payload: {
+              method: request.method,
+              headers: redactHeaders(request.headers),
+              query: request.query,
+              body: request.body,
+            },
+          },
+        });
+      });
+
+      reply.code(202);
+      return {delivery_id: deliveryId};
+    },
+  });
+
+  return {
+    prefix: '/webhook',
+    auth: [],
+    plugins: [formBodyRoutePlugin],
+    routes: [inboundRoute],
+  };
+}

package/test/env.ts

@@ -0,0 +1,7 @@
+process.env.POSTGRES_HOST = 'localhost';
+process.env.POSTGRES_PORT = '5432';
+process.env.POSTGRES_USERNAME = 'shipfox';
+process.env.POSTGRES_PASSWORD = 'password';
+process.env.POSTGRES_DATABASE = 'api_test';
+process.env.POSTGRES_MAX_CONNECTIONS = '5';
+process.env.TZ = 'UTC';

package/test/globalSetup.ts

@@ -0,0 +1,5 @@
+import './env.js';
+
+export async function setup() {
+  await Promise.resolve();
+}

package/test/setup.ts

@@ -0,0 +1,6 @@
+import './env.js';
+import {afterEach, vi} from '@shipfox/vitest/vi';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@shipfox/ts-config/node",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["**/*.test.tsx", "**/*.test.ts"]
+}