@shipfox/api-integration-sentry 2.0.0

package/src/presentation/routes/webhooks.ts

@@ -0,0 +1,59 @@
+import {
+  ClientError,
+  defineRoute,
+  type RouteGroup,
+  rawBodyPlugin,
+  WEBHOOK_BODY_LIMIT,
+} from '@shipfox/node-fastify';
+import {logger} from '@shipfox/node-opentelemetry';
+import {config} from '#config.js';
+import {verifySentrySignature} from '#core/signature.js';
+import {handleInstallationResource} from './installation-handler.js';
+import {handleIssueResource} from './issue-handler.js';
+import type {SentryWebhookContext} from './webhook-context.js';
+import {recordAndDrop} from './webhook-delivery.js';
+import {parseSentryWebhookRequest} from './webhook-request.js';
+
+const ISSUE_RESOURCE = 'issue';
+const INSTALLATION_RESOURCE = 'installation';
+
+export type {SentryWebhookContext} from './webhook-context.js';
+
+export function createSentryWebhookRoutes(context: SentryWebhookContext): RouteGroup {
+  const webhookRoute = defineRoute({
+    method: 'POST',
+    path: '/',
+    auth: [],
+    description: 'Sentry integration webhook receiver.',
+    options: {bodyLimit: WEBHOOK_BODY_LIMIT},
+    handler: (request, reply) => {
+      const {deliveryId, resource, signature, signatureHeaderName, rawBody} =
+        parseSentryWebhookRequest(request);
+
+      if (!verifySentrySignature({rawBody, signature, secret: config.SENTRY_APP_CLIENT_SECRET})) {
+        throw new ClientError('invalid signature', 'invalid-signature', {status: 401});
+      }
+      logger().debug(
+        {deliveryId, signatureHeader: signatureHeaderName},
+        'sentry webhook: signature verified',
+      );
+
+      if (resource === ISSUE_RESOURCE) {
+        return handleIssueResource({context, reply, deliveryId, rawBody});
+      }
+      if (resource === INSTALLATION_RESOURCE) {
+        return handleInstallationResource({context, reply, deliveryId, rawBody});
+      }
+
+      // Unsupported resources are acknowledged so Sentry does not retry or disable the app.
+      return recordAndDrop({context, reply, deliveryId});
+    },
+  });
+
+  return {
+    prefix: '/webhooks/integrations/sentry',
+    auth: [],
+    plugins: [rawBodyPlugin],
+    routes: [webhookRoute],
+  };
+}

package/src/temporal/activities/index.ts

@@ -0,0 +1,7 @@
+import {pruneUnclaimedSentryInstallationsActivity} from './prune-unclaimed-installations.js';
+
+export function createSentryMaintenanceActivities() {
+  return {
+    pruneUnclaimedSentryInstallationsActivity,
+  };
+}

package/src/temporal/activities/prune-unclaimed-installations.test.ts

@@ -0,0 +1,52 @@
+import {randomUUID} from 'node:crypto';
+import {db} from '#db/db.js';
+import {getSentryInstallationByInstallationUuid} from '#db/installations.js';
+import {sentryInstallations} from '#db/schema/installations.js';
+import {pruneUnclaimedSentryInstallationsActivity} from './prune-unclaimed-installations.js';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+// The activity derives its cutoff from SENTRY_UNCLAIMED_INSTALLATION_RETENTION_DAYS
+// (default 7), so rows are seeded with an explicit createdAt to straddle it; the
+// persist helpers always stamp createdAt=now and could not exercise the cutoff.
+describe('pruneUnclaimedSentryInstallationsActivity', () => {
+  beforeEach(async () => {
+    await db().delete(sentryInstallations);
+  });
+
+  test('tombstones unclaimed installs older than the retention window', async () => {
+    const staleUuid = randomUUID();
+    await db()
+      .insert(sentryInstallations)
+      .values({
+        connectionId: null,
+        installationUuid: staleUuid,
+        orgSlug: 'acme',
+        status: 'installed',
+        createdAt: new Date(Date.now() - 8 * DAY_MS),
+        updatedAt: new Date(Date.now() - 8 * DAY_MS),
+      });
+
+    const result = await pruneUnclaimedSentryInstallationsActivity();
+
+    expect(result.tombstoned).toBe(1);
+    expect((await getSentryInstallationByInstallationUuid(staleUuid))?.status).toBe('deleted');
+  });
+
+  test('leaves unclaimed installs within the retention window untouched', async () => {
+    const freshUuid = randomUUID();
+    await db().insert(sentryInstallations).values({
+      connectionId: null,
+      installationUuid: freshUuid,
+      orgSlug: 'acme',
+      status: 'installed',
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    const result = await pruneUnclaimedSentryInstallationsActivity();
+
+    expect(result.tombstoned).toBe(0);
+    expect((await getSentryInstallationByInstallationUuid(freshUuid))?.status).toBe('installed');
+  });
+});

package/src/temporal/activities/prune-unclaimed-installations.ts

@@ -0,0 +1,11 @@
+import {config} from '#config.js';
+import {pruneUnclaimedSentryInstallations} from '#db/installations.js';
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+export async function pruneUnclaimedSentryInstallationsActivity(): Promise<{tombstoned: number}> {
+  const olderThan = new Date(
+    Date.now() - config.SENTRY_UNCLAIMED_INSTALLATION_RETENTION_DAYS * MS_PER_DAY,
+  );
+  return await pruneUnclaimedSentryInstallations({olderThan});
+}

package/src/temporal/constants.ts

@@ -0,0 +1 @@
+export const SENTRY_MAINTENANCE_TASK_QUEUE = 'integrations-sentry-maintenance';

package/src/temporal/workflows/index.ts

@@ -0,0 +1 @@
+export {pruneUnclaimedSentryInstallationsCron} from './prune-unclaimed-installations-cron.js';

package/src/temporal/workflows/prune-unclaimed-installations-cron.ts

@@ -0,0 +1,15 @@
+import {log, proxyActivities} from '@temporalio/workflow';
+import type {createSentryMaintenanceActivities} from '../activities/index.js';
+
+const {pruneUnclaimedSentryInstallationsActivity} = proxyActivities<
+  ReturnType<typeof createSentryMaintenanceActivities>
+>({
+  startToCloseTimeout: '5 minutes',
+});
+
+export async function pruneUnclaimedSentryInstallationsCron(): Promise<void> {
+  const {tombstoned} = await pruneUnclaimedSentryInstallationsActivity();
+  if (tombstoned > 0) {
+    log.info('Tombstoned stale unclaimed Sentry installations', {tombstoned});
+  }
+}

package/test/env.ts

@@ -0,0 +1,11 @@
+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';
+process.env.SENTRY_APP_CLIENT_ID = 'test-client-id';
+process.env.SENTRY_APP_CLIENT_SECRET = 'test-client-secret';
+process.env.SENTRY_APP_SLUG = 'shipfox-test';
+process.env.SENTRY_APP_VERIFY_INSTALL = 'true';

package/test/factories/index.ts

@@ -0,0 +1,9 @@
+export {sentryInstallationFactory} from './sentry-installation.js';
+export {
+  type SentryInstallationWebhookPayload,
+  sentryInstallationWebhookFactory,
+} from './sentry-installation-webhook.js';
+export {
+  type SentryIssueWebhookPayload,
+  sentryIssueWebhookFactory,
+} from './sentry-issue-webhook.js';

package/test/factories/sentry-installation-webhook.ts

@@ -0,0 +1,35 @@
+import {Factory} from 'fishery';
+
+// Raw Sentry installation webhook payload, shaped exactly as Sentry delivers it
+// over the wire: the lifecycle data nests under `data.installation` and carries
+// the single-use authorization `code`. Tests serialize the built object to form a
+// signed request body; the route parses and validates it with the production Zod
+// schema. Build-only — the payload is never persisted, so there is no onCreate
+// handler.
+export interface SentryInstallationWebhookPayload {
+  action: string;
+  actor?: {type?: string; id?: string | number; name?: string};
+  data: {
+    installation: {
+      uuid: string;
+      status?: string;
+      code?: string;
+      organization?: {slug: string};
+    };
+  };
+}
+
+export const sentryInstallationWebhookFactory = Factory.define<SentryInstallationWebhookPayload>(
+  ({sequence}) => ({
+    action: 'created',
+    actor: {type: 'user', id: sequence, name: 'Installer'},
+    data: {
+      installation: {
+        uuid: `install-${sequence}`,
+        status: 'installed',
+        code: `grant-code-${sequence}`,
+        organization: {slug: 'acme'},
+      },
+    },
+  }),
+);

package/test/factories/sentry-installation.ts

@@ -0,0 +1,44 @@
+import {Factory} from 'fishery';
+import {
+  persistVerifiedUnclaimedInstallation,
+  type SentryInstallation,
+  type SentryInstallationStatus,
+  upsertSentryInstallation,
+} from '#db/installations.js';
+
+// Persists either a claimed install (default: `connectionId` set) or, when
+// `connectionId` is null, a verified-unclaimed install via the dedicated insert
+// so tests can exercise the webhook-authoritative pre-claim state.
+export const sentryInstallationFactory = Factory.define<SentryInstallation>(
+  ({sequence, onCreate}) => {
+    onCreate((installation) => {
+      if (installation.connectionId === null) {
+        return persistVerifiedUnclaimedInstallation({
+          installationUuid: installation.installationUuid,
+          orgSlug: installation.orgSlug,
+          codeHash: installation.codeHash ?? 'unclaimed-code-hash',
+        });
+      }
+      return upsertSentryInstallation({
+        connectionId: installation.connectionId,
+        installationUuid: installation.installationUuid,
+        orgSlug: installation.orgSlug,
+        status: installation.status as SentryInstallationStatus,
+        codeHash: installation.codeHash,
+        installerUserId: installation.installerUserId,
+      });
+    });
+
+    return {
+      id: crypto.randomUUID(),
+      connectionId: crypto.randomUUID(),
+      installationUuid: `install-${sequence + 1}`,
+      orgSlug: 'acme',
+      status: 'installed',
+      codeHash: null,
+      installerUserId: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+  },
+);

package/test/factories/sentry-issue-webhook.ts

@@ -0,0 +1,34 @@
+import {Factory} from 'fishery';
+
+// Raw Sentry issue webhook payload, shaped exactly as Sentry delivers it over
+// the wire. Tests serialize the built object to form a signed request body; the
+// route parses and validates it with the production Zod schema. Build-only — the
+// payload is never persisted, so there is no onCreate handler.
+export interface SentryIssueWebhookPayload {
+  action: string;
+  installation: {uuid: string};
+  data: {issue: Record<string, unknown>};
+}
+
+export const sentryIssueWebhookFactory = Factory.define<SentryIssueWebhookPayload>(
+  ({sequence}) => ({
+    action: 'created',
+    installation: {uuid: `install-${sequence}`},
+    data: {
+      issue: {
+        id: 'issue-123',
+        shortId: 'PROJ-1',
+        title: 'TypeError: boom',
+        culprit: 'app/main',
+        level: 'error',
+        status: 'unresolved',
+        platform: 'javascript',
+        web_url: 'https://sentry.io/organizations/acme/issues/123/',
+        url: 'https://sentry.io/api/0/issues/123/',
+        project_url: 'https://sentry.io/api/0/projects/acme/web/',
+        firstSeen: '2026-06-01T00:00:00Z',
+        lastSeen: '2026-06-10T00:00:00Z',
+      },
+    },
+  }),
+);

package/test/globalSetup.ts

@@ -0,0 +1,14 @@
+import './env.js';
+import {runMigrations} from '@shipfox/node-drizzle';
+import {closePostgresClient, createPostgresClient} from '@shipfox/node-postgres';
+import {closeDb, db} from '#db/db.js';
+import {migrationsPath} from '#db/migrations.js';
+
+export async function setup() {
+  createPostgresClient();
+
+  await runMigrations(db(), migrationsPath, '__drizzle_migrations_integrations_sentry');
+
+  closeDb();
+  await closePostgresClient();
+}

package/test/index.ts

@@ -0,0 +1,9 @@
+export {sentryInstallationFactory} from './factories/sentry-installation.js';
+export {
+  type SentryInstallationWebhookPayload,
+  sentryInstallationWebhookFactory,
+} from './factories/sentry-installation-webhook.js';
+export {
+  type SentryIssueWebhookPayload,
+  sentryIssueWebhookFactory,
+} from './factories/sentry-issue-webhook.js';

package/test/setup.ts

@@ -0,0 +1,17 @@
+import './env.js';
+import {closePostgresClient, createPostgresClient} from '@shipfox/node-postgres';
+import {afterAll, afterEach, beforeAll, vi} from '@shipfox/vitest/vi';
+import {closeDb} from '#db/db.js';
+
+beforeAll(() => {
+  createPostgresClient();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+afterAll(async () => {
+  closeDb();
+  await closePostgresClient();
+});

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"]
+}