@shipfox/api-integration-sentry 2.0.0

package/src/db/installations.ts

@@ -0,0 +1,207 @@
+import {and, eq, isNull, lt, sql} from 'drizzle-orm';
+import {SentryInstallationAlreadyLinkedError} from '#core/errors.js';
+import {db} from './db.js';
+import {sentryInstallations, toSentryInstallation} from './schema/installations.js';
+
+export type SentryInstallationStatus = 'installed' | 'deleted';
+
+export interface SentryInstallation {
+  id: string;
+  connectionId: string | null;
+  installationUuid: string;
+  orgSlug: string;
+  status: string;
+  codeHash: string | null;
+  installerUserId: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface UpsertSentryInstallationParams {
+  connectionId: string;
+  installationUuid: string;
+  orgSlug: string;
+  status: SentryInstallationStatus;
+  codeHash?: string | null | undefined;
+  installerUserId?: string | null | undefined;
+}
+
+export interface PersistVerifiedUnclaimedInstallationParams {
+  installationUuid: string;
+  orgSlug: string;
+  codeHash: string;
+}
+
+type SentryDb = ReturnType<typeof db>;
+type SentryTx = Parameters<Parameters<SentryDb['transaction']>[0]>[0];
+
+export async function upsertSentryInstallation(
+  params: UpsertSentryInstallationParams,
+  options: {tx?: unknown} = {},
+): Promise<SentryInstallation> {
+  const executor = (options.tx ?? db()) as SentryDb | SentryTx;
+  const now = new Date();
+  const [row] = await executor
+    .insert(sentryInstallations)
+    .values({
+      connectionId: params.connectionId,
+      installationUuid: params.installationUuid,
+      orgSlug: params.orgSlug,
+      status: params.status,
+      codeHash: params.codeHash ?? null,
+      installerUserId: params.installerUserId ?? null,
+    })
+    .onConflictDoUpdate({
+      target: sentryInstallations.installationUuid,
+      // TOCTOU guard: allow the update only when this installation is unclaimed
+      // (connection_id IS NULL, the first claim of a verified-unclaimed row) or
+      // already owned by this same connection (idempotent reconnect). A concurrent
+      // claim of the same installation to a different workspace commits its own
+      // connection_id first; this losing transaction then sees a different non-null
+      // connection_id, the predicate is false, Postgres updates nothing, and the
+      // empty RETURNING below rolls it back instead of silently repointing the
+      // installation (cross-tenant event misroute).
+      setWhere: sql`${sentryInstallations.connectionId} is null or ${sentryInstallations.connectionId} = ${params.connectionId}`,
+      set: {
+        connectionId: params.connectionId,
+        orgSlug: params.orgSlug,
+        status: params.status,
+        codeHash: params.codeHash ?? null,
+        installerUserId: params.installerUserId ?? null,
+        updatedAt: now,
+      },
+    })
+    .returning();
+
+  if (!row) throw new SentryInstallationAlreadyLinkedError(params.installationUuid);
+  return toSentryInstallation(row);
+}
+
+/**
+ * Inserts the verified-but-unclaimed install half (`connection_id = NULL`,
+ * `status = 'installed'`) after a successful code exchange. Idempotent on the
+ * installation uuid: a conflicting row refreshes only `code_hash`/`org_slug`/
+ * `updated_at`, so a webhook that lands after a claim never clobbers the
+ * `connection_id` it set nor downgrades a `deleted` tombstone back to installed.
+ */
+export async function persistVerifiedUnclaimedInstallation(
+  params: PersistVerifiedUnclaimedInstallationParams,
+  options: {tx?: unknown} = {},
+): Promise<SentryInstallation> {
+  const executor = (options.tx ?? db()) as SentryDb | SentryTx;
+  const now = new Date();
+  const [row] = await executor
+    .insert(sentryInstallations)
+    .values({
+      connectionId: null,
+      installationUuid: params.installationUuid,
+      orgSlug: params.orgSlug,
+      status: 'installed',
+      codeHash: params.codeHash,
+    })
+    .onConflictDoUpdate({
+      target: sentryInstallations.installationUuid,
+      set: {
+        orgSlug: params.orgSlug,
+        codeHash: params.codeHash,
+        updatedAt: now,
+      },
+    })
+    .returning();
+
+  if (!row) throw new Error('Sentry installation persist returned no rows');
+  return toSentryInstallation(row);
+}
+
+/**
+ * Verified installs no user has claimed yet (`connection_id IS NULL`,
+ * `status='installed'`). Tombstoned rows are excluded so the TTL cron stays
+ * idempotent and the unclaimed metric stays accurate. Pass `olderThan` to scope
+ * to stale rows for the cron.
+ */
+export async function listUnclaimedSentryInstallations(
+  params: {olderThan?: Date} = {},
+  options: {tx?: unknown} = {},
+): Promise<SentryInstallation[]> {
+  const executor = (options.tx ?? db()) as SentryDb | SentryTx;
+  const conditions = [
+    isNull(sentryInstallations.connectionId),
+    eq(sentryInstallations.status, 'installed'),
+  ];
+  if (params.olderThan) {
+    conditions.push(lt(sentryInstallations.createdAt, params.olderThan));
+  }
+  const rows = await executor
+    .select()
+    .from(sentryInstallations)
+    .where(and(...conditions));
+  return rows.map(toSentryInstallation);
+}
+
+export async function getSentryInstallationByInstallationUuid(
+  installationUuid: string,
+  options: {tx?: unknown} = {},
+): Promise<SentryInstallation | undefined> {
+  const executor = (options.tx ?? db()) as SentryDb | SentryTx;
+  const rows = await executor
+    .select()
+    .from(sentryInstallations)
+    .where(eq(sentryInstallations.installationUuid, installationUuid))
+    .limit(1);
+  const row = rows[0];
+  if (!row) return undefined;
+  return toSentryInstallation(row);
+}
+
+export async function getSentryInstallationByConnectionId(
+  connectionId: string,
+  options: {tx?: unknown} = {},
+): Promise<SentryInstallation | undefined> {
+  const executor = (options.tx ?? db()) as SentryDb | SentryTx;
+  const rows = await executor
+    .select()
+    .from(sentryInstallations)
+    .where(eq(sentryInstallations.connectionId, connectionId))
+    .limit(1);
+  const row = rows[0];
+  if (!row) return undefined;
+  return toSentryInstallation(row);
+}
+
+/**
+ * Tombstones verified-unclaimed installs older than `olderThan` (the TTL cleanup
+ * cron). Bounds a never-claimed install rather than leaving it pending forever.
+ * Returns how many rows were tombstoned. We hold no Sentry token for these rows
+ * (tokens are never persisted), so the Sentry-side uninstall is out of scope here.
+ */
+export async function pruneUnclaimedSentryInstallations(
+  params: {olderThan: Date},
+  options: {tx?: unknown} = {},
+): Promise<{tombstoned: number}> {
+  const executor = (options.tx ?? db()) as SentryDb | SentryTx;
+  const result = await executor
+    .update(sentryInstallations)
+    .set({status: 'deleted', updatedAt: new Date()})
+    .where(
+      and(
+        isNull(sentryInstallations.connectionId),
+        eq(sentryInstallations.status, 'installed'),
+        lt(sentryInstallations.createdAt, params.olderThan),
+      ),
+    );
+  return {tombstoned: result.rowCount ?? 0};
+}
+
+export async function markSentryInstallationDeleted(
+  params: {installationUuid: string},
+  options: {tx?: unknown} = {},
+): Promise<SentryInstallation | undefined> {
+  const executor = (options.tx ?? db()) as SentryDb | SentryTx;
+  const [row] = await executor
+    .update(sentryInstallations)
+    .set({status: 'deleted', updatedAt: new Date()})
+    .where(eq(sentryInstallations.installationUuid, params.installationUuid))
+    .returning();
+  if (!row) return undefined;
+  return toSentryInstallation(row);
+}

package/src/db/migrations.ts

@@ -0,0 +1,4 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+export const migrationsPath = resolve(dirname(fileURLToPath(import.meta.url)), '../../drizzle');

package/src/db/schema/common.ts

@@ -0,0 +1,3 @@
+import {pgTableCreator} from 'drizzle-orm/pg-core';
+
+export const pgTable = pgTableCreator((name) => `integrations_sentry_${name}`);

package/src/db/schema/installations.ts

@@ -0,0 +1,46 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import type {SentryInstallation} from '#db/installations.js';
+import {pgTable} from './common.js';
+
+export const sentryInstallations = pgTable(
+  'installations',
+  {
+    id: uuidv7PrimaryKey(),
+    // Null until a logged-in user claims the verified install into a workspace.
+    // An unclaimed install (`connection_id IS NULL`, `status='installed'`) is
+    // persisted by the authoritative webhook before any browser claim arrives.
+    connectionId: uuid('connection_id'),
+    installationUuid: text('installation_uuid').notNull(),
+    orgSlug: text('org_slug').notNull(),
+    status: text('status').notNull(),
+    // sha256(authorization code) of the exchange that verified this install.
+    // The claim presents the code and we match the hash, so a bare uuid alone
+    // cannot bind the install (IDOR guard) without storing a live credential.
+    codeHash: text('code_hash'),
+    installerUserId: uuid('installer_user_id'),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('integrations_sentry_installations_connection_unique').on(table.connectionId),
+    uniqueIndex('integrations_sentry_installations_installation_unique').on(table.installationUuid),
+  ],
+);
+
+export type SentryInstallationDb = typeof sentryInstallations.$inferSelect;
+export type SentryInstallationCreateDb = typeof sentryInstallations.$inferInsert;
+
+export function toSentryInstallation(row: SentryInstallationDb): SentryInstallation {
+  return {
+    id: row.id,
+    connectionId: row.connectionId,
+    installationUuid: row.installationUuid,
+    orgSlug: row.orgSlug,
+    status: row.status,
+    codeHash: row.codeHash,
+    installerUserId: row.installerUserId,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}

package/src/index.test.ts

@@ -0,0 +1,18 @@
+import {createSentryMaintenanceWorker} from './index.js';
+
+describe('createSentryMaintenanceWorker', () => {
+  test('describes the sentry maintenance worker', () => {
+    const worker = createSentryMaintenanceWorker();
+
+    expect(worker.taskQueue).toBe('integrations-sentry-maintenance');
+    expect(worker.workflowsPath.endsWith('dist/temporal/workflows/index.js')).toBe(true);
+    expect(Object.keys(worker.activities())).toContain('pruneUnclaimedSentryInstallationsActivity');
+    expect(worker.workflows).toEqual([
+      {
+        name: 'pruneUnclaimedSentryInstallationsCron',
+        id: 'sentry-prune-unclaimed-installations',
+        cronSchedule: '0 4 * * *',
+      },
+    ]);
+  });
+});

package/src/index.ts

@@ -0,0 +1,127 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import type {
+  GetIntegrationConnectionByIdFn,
+  PublishIntegrationEventReceivedFn,
+  RecordDeliveryOnlyFn,
+  UpdateIntegrationConnectionLifecycleStatusFn,
+} from '@shipfox/api-integration-core-dto';
+import type {ModuleWorker} from '@shipfox/node-module';
+import type {NodePgDatabase} from 'drizzle-orm/node-postgres';
+import {createSentryApiClient, type SentryApiClient} from '#api/client.js';
+import {closeDb, db} from '#db/db.js';
+import {
+  getSentryInstallationByConnectionId,
+  persistVerifiedUnclaimedInstallation,
+} from '#db/installations.js';
+import {migrationsPath} from '#db/migrations.js';
+import {
+  type CreateSentryIntegrationRoutesOptions,
+  createSentryIntegrationRoutes,
+} from '#presentation/routes/install.js';
+import {createSentryWebhookRoutes} from '#presentation/routes/webhooks.js';
+import {createSentryMaintenanceActivities} from '#temporal/activities/index.js';
+import {SENTRY_MAINTENANCE_TASK_QUEUE} from '#temporal/constants.js';
+
+export type {SentryApiClient} from '#api/client.js';
+export {
+  SentryClaimProofMismatchError,
+  SentryInstallationAlreadyLinkedError,
+  SentryInstallationDeletedError,
+  SentryIntegrationProviderError,
+  SentryVerificationInProgressError,
+} from '#core/errors.js';
+export type {
+  ConnectSentryInstallationInput,
+  VerifyAndPersistUnclaimedInstallationParams,
+} from '#core/install.js';
+export {
+  handleSentryConnect,
+  hashAuthorizationCode,
+  verifyAndPersistUnclaimedInstallation,
+} from '#core/install.js';
+export {
+  handleSentryInstallationCreated,
+  handleSentryInstallationDeleted,
+  handleSentryIssueEvent,
+} from '#core/webhook.js';
+export type {
+  PersistVerifiedUnclaimedInstallationParams,
+  SentryInstallation,
+  SentryInstallationStatus,
+  UpsertSentryInstallationParams,
+} from '#db/installations.js';
+export {
+  getSentryInstallationByInstallationUuid,
+  persistVerifiedUnclaimedInstallation,
+  upsertSentryInstallation,
+} from '#db/installations.js';
+export {closeDb, db, migrationsPath};
+
+export interface CreateSentryIntegrationProviderOptions
+  extends Omit<
+    CreateSentryIntegrationRoutesOptions,
+    'sentry' | 'persistVerifiedUnclaimedInstallation'
+  > {
+  sentry?: SentryApiClient | undefined;
+  coreDb: () => NodePgDatabase<Record<string, unknown>>;
+  publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+  updateConnectionLifecycleStatus: UpdateIntegrationConnectionLifecycleStatusFn;
+  getSentryInstallationByConnectionId?: typeof getSentryInstallationByConnectionId | undefined;
+  persistVerifiedUnclaimedInstallation?: typeof persistVerifiedUnclaimedInstallation | undefined;
+}
+
+export function createSentryIntegrationProvider(options: CreateSentryIntegrationProviderOptions) {
+  const sentry = options.sentry ?? createSentryApiClient();
+  const getInstallationByConnectionId =
+    options.getSentryInstallationByConnectionId ?? getSentryInstallationByConnectionId;
+  const persistUnclaimed =
+    options.persistVerifiedUnclaimedInstallation ?? persistVerifiedUnclaimedInstallation;
+
+  return {
+    provider: 'sentry' as const,
+    displayName: 'Sentry',
+    async connectionExternalUrl(connection: {id: string}): Promise<string | undefined> {
+      const installation = await getInstallationByConnectionId(connection.id);
+      if (!installation?.orgSlug) return undefined;
+      return `https://sentry.io/organizations/${encodeURIComponent(installation.orgSlug)}/`;
+    },
+    routes: [
+      createSentryIntegrationRoutes({
+        sentry,
+        getSentryInstallation: options.getSentryInstallation,
+        getConnectionById: options.getConnectionById,
+        connectSentryInstallation: options.connectSentryInstallation,
+        persistVerifiedUnclaimedInstallation: persistUnclaimed,
+      }),
+      createSentryWebhookRoutes({
+        sentry,
+        coreDb: options.coreDb,
+        publishIntegrationEventReceived: options.publishIntegrationEventReceived,
+        recordDeliveryOnly: options.recordDeliveryOnly,
+        getIntegrationConnectionById: options.getIntegrationConnectionById,
+        updateConnectionLifecycleStatus: options.updateConnectionLifecycleStatus,
+      }),
+    ],
+  };
+}
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const maintenanceWorkflowsPath = resolve(packageRoot, 'dist/temporal/workflows/index.js');
+
+export function createSentryMaintenanceWorker(): ModuleWorker {
+  return {
+    taskQueue: SENTRY_MAINTENANCE_TASK_QUEUE,
+    workflowsPath: maintenanceWorkflowsPath,
+    activities: createSentryMaintenanceActivities,
+    workflows: [
+      {
+        name: 'pruneUnclaimedSentryInstallationsCron',
+        id: 'sentry-prune-unclaimed-installations',
+        cronSchedule: '0 4 * * *',
+      },
+    ],
+  };
+}

package/src/presentation/dto/integrations.ts

@@ -0,0 +1,9 @@
+import {
+  type IntegrationConnection,
+  toIntegrationConnectionDto as toCoreIntegrationConnectionDto,
+} from '@shipfox/api-integration-core-dto';
+
+// Sentry exposes no adapters, so its connections carry no capabilities.
+export function toIntegrationConnectionDto(connection: IntegrationConnection<'sentry'>) {
+  return toCoreIntegrationConnectionDto(connection, {capabilities: []});
+}

package/src/presentation/routes/errors.ts

@@ -0,0 +1,48 @@
+import {
+  ConnectionSlugConflictError,
+  type IntegrationProviderErrorReason,
+} from '@shipfox/api-integration-core-dto';
+import {ClientError} from '@shipfox/node-fastify';
+import {
+  SentryClaimProofMismatchError,
+  SentryInstallationAlreadyLinkedError,
+  SentryInstallationDeletedError,
+  SentryIntegrationProviderError,
+  SentryVerificationInProgressError,
+} from '#core/errors.js';
+
+function providerStatus(reason: IntegrationProviderErrorReason): number {
+  if (reason === 'rate-limited') return 429;
+  if (reason === 'timeout' || reason === 'provider-unavailable') return 503;
+  return 422;
+}
+
+export function sentryRouteErrorHandler(error: unknown): never {
+  if (error instanceof SentryInstallationAlreadyLinkedError) {
+    throw new ClientError(error.message, 'sentry-installation-already-linked', {status: 409});
+  }
+  if (error instanceof SentryInstallationDeletedError) {
+    throw new ClientError(error.message, 'sentry-installation-deleted', {status: 409});
+  }
+  if (error instanceof SentryClaimProofMismatchError) {
+    throw new ClientError(error.message, 'sentry-claim-proof-mismatch', {status: 403});
+  }
+  if (error instanceof ConnectionSlugConflictError) {
+    throw new ClientError(error.message, 'slug-conflict', {status: 409});
+  }
+  if (error instanceof SentryVerificationInProgressError) {
+    // Retryable: a concurrent webhook is mid-exchange. 503 + retry_after lands in
+    // the client backoff that already treats >= 500 as retryable.
+    throw new ClientError(error.message, 'sentry-verification-in-progress', {
+      status: 503,
+      details: {retry_after_seconds: error.retryAfterSeconds},
+    });
+  }
+  if (error instanceof SentryIntegrationProviderError) {
+    throw new ClientError(error.message, error.reason, {
+      details: {retry_after_seconds: error.retryAfterSeconds},
+      status: providerStatus(error.reason),
+    });
+  }
+  throw error;
+}