@shipfox/api-integration-core 2.0.0

package/src/db/connections.ts

@@ -0,0 +1,262 @@
+import {
+  CONNECTION_SLUG_MAX_LENGTH,
+  ConnectionSlugConflictError,
+} from '@shipfox/api-integration-core-dto';
+import {and, eq} from 'drizzle-orm';
+import type {
+  IntegrationConnection,
+  IntegrationConnectionLifecycleStatus,
+} from '#core/entities/connection.js';
+import type {IntegrationProviderKind} from '#core/entities/provider.js';
+import {IntegrationConnectionAlreadyExistsError} from '#core/errors.js';
+import {db} from './db.js';
+import {integrationConnections, toIntegrationConnection} from './schema/connections.js';
+
+type IntegrationDb = ReturnType<typeof db>;
+type IntegrationTx = Parameters<Parameters<IntegrationDb['transaction']>[0]>[0];
+
+export interface UpsertIntegrationConnectionParams {
+  workspaceId: string;
+  provider: IntegrationProviderKind;
+  externalAccountId: string;
+  slug: string;
+  displayName: string;
+  lifecycleStatus?: IntegrationConnectionLifecycleStatus | undefined;
+}
+
+export async function upsertIntegrationConnection(
+  params: UpsertIntegrationConnectionParams,
+  options: {tx?: IntegrationDb | IntegrationTx | undefined} = {},
+): Promise<IntegrationConnection> {
+  const executor = options.tx ?? db();
+  const now = new Date();
+  const [row] = await executor
+    .insert(integrationConnections)
+    .values({
+      workspaceId: params.workspaceId,
+      provider: params.provider,
+      externalAccountId: params.externalAccountId,
+      slug: params.slug,
+      displayName: params.displayName,
+      lifecycleStatus: params.lifecycleStatus ?? 'active',
+    })
+    .onConflictDoUpdate({
+      target: [
+        integrationConnections.workspaceId,
+        integrationConnections.provider,
+        integrationConnections.externalAccountId,
+      ],
+      set: {
+        displayName: params.displayName,
+        lifecycleStatus: params.lifecycleStatus ?? 'active',
+        updatedAt: now,
+      },
+    })
+    .returning();
+
+  if (!row) throw new Error('Integration connection upsert returned no rows');
+  return toIntegrationConnection(row);
+}
+
+export interface CreateIntegrationConnectionParams {
+  workspaceId: string;
+  provider: IntegrationProviderKind;
+  externalAccountId: string;
+  slug: string;
+  displayName: string;
+  lifecycleStatus?: IntegrationConnectionLifecycleStatus | undefined;
+}
+
+const INTEGRATION_CONNECTION_EXTERNAL_UNIQUE_CONSTRAINT =
+  'integrations_connections_workspace_external_unique';
+const INTEGRATION_CONNECTION_SLUG_UNIQUE_CONSTRAINT =
+  'integrations_connections_workspace_slug_unique';
+
+export function isIntegrationConnectionUniqueViolation(error: unknown): boolean {
+  let current: unknown = error;
+  for (let depth = 0; depth < 5 && current != null; depth += 1) {
+    if (typeof current !== 'object') return false;
+    const {code, constraint} = current as {code?: unknown; constraint?: unknown};
+    if (code === '23505' && constraint === INTEGRATION_CONNECTION_EXTERNAL_UNIQUE_CONSTRAINT) {
+      return true;
+    }
+    current = (current as {cause?: unknown}).cause;
+  }
+  return false;
+}
+
+export function isIntegrationConnectionSlugUniqueViolation(error: unknown): boolean {
+  let current: unknown = error;
+  for (let depth = 0; depth < 5 && current != null; depth += 1) {
+    if (typeof current !== 'object') return false;
+    const {code, constraint} = current as {code?: unknown; constraint?: unknown};
+    if (code === '23505' && constraint === INTEGRATION_CONNECTION_SLUG_UNIQUE_CONSTRAINT) {
+      return true;
+    }
+    current = (current as {cause?: unknown}).cause;
+  }
+  return false;
+}
+
+export async function createIntegrationConnection(
+  params: CreateIntegrationConnectionParams,
+  options: {tx?: IntegrationDb | IntegrationTx | undefined} = {},
+): Promise<IntegrationConnection> {
+  const executor = options.tx ?? db();
+  let rows: (typeof integrationConnections.$inferSelect)[];
+  try {
+    rows = await executor
+      .insert(integrationConnections)
+      .values({
+        workspaceId: params.workspaceId,
+        provider: params.provider,
+        externalAccountId: params.externalAccountId,
+        slug: params.slug,
+        displayName: params.displayName,
+        lifecycleStatus: params.lifecycleStatus ?? 'active',
+      })
+      .returning();
+  } catch (error) {
+    if (isIntegrationConnectionUniqueViolation(error)) {
+      throw new IntegrationConnectionAlreadyExistsError(
+        params.workspaceId,
+        params.provider,
+        params.externalAccountId,
+      );
+    }
+    if (isIntegrationConnectionSlugUniqueViolation(error)) {
+      throw new ConnectionSlugConflictError(error);
+    }
+    throw error;
+  }
+
+  const row = rows[0];
+  if (!row) throw new Error('Integration connection insert returned no rows');
+  return toIntegrationConnection(row);
+}
+
+export interface ResolveUniqueConnectionSlugParams {
+  workspaceId: string;
+  provider: IntegrationProviderKind;
+  externalAccountId: string;
+  baseSlug: string;
+}
+
+export async function resolveUniqueConnectionSlug(
+  params: ResolveUniqueConnectionSlugParams,
+  options: {tx?: IntegrationDb | IntegrationTx | undefined} = {},
+): Promise<string> {
+  const executor = options.tx ?? db();
+  const [existing] = await executor
+    .select({slug: integrationConnections.slug})
+    .from(integrationConnections)
+    .where(
+      and(
+        eq(integrationConnections.workspaceId, params.workspaceId),
+        eq(integrationConnections.provider, params.provider),
+        eq(integrationConnections.externalAccountId, params.externalAccountId),
+      ),
+    )
+    .limit(1);
+  if (existing) return existing.slug;
+
+  const workspaceSlugs = await executor
+    .select({slug: integrationConnections.slug})
+    .from(integrationConnections)
+    .where(eq(integrationConnections.workspaceId, params.workspaceId));
+  const used = new Set(workspaceSlugs.map((row) => row.slug));
+
+  for (let suffixNumber = 1; ; suffixNumber += 1) {
+    const suffix = suffixNumber === 1 ? '' : `_${suffixNumber}`;
+    const baseBudget = CONNECTION_SLUG_MAX_LENGTH - suffix.length;
+    const candidate = `${params.baseSlug.slice(0, baseBudget).replaceAll(/[_-]+$/g, '')}${suffix}`;
+    if (!used.has(candidate)) return candidate;
+  }
+}
+
+export type CreateIntegrationConnectionFn = typeof createIntegrationConnection;
+
+export async function getIntegrationConnectionById(
+  id: string,
+  options: {tx?: IntegrationDb | IntegrationTx | undefined} = {},
+): Promise<IntegrationConnection | undefined> {
+  const executor = options.tx ?? db();
+  const rows = await executor
+    .select()
+    .from(integrationConnections)
+    .where(eq(integrationConnections.id, id))
+    .limit(1);
+  const row = rows[0];
+  if (!row) return undefined;
+  return toIntegrationConnection(row);
+}
+
+export type GetIntegrationConnectionByIdFn = typeof getIntegrationConnectionById;
+
+export interface UpdateIntegrationConnectionLifecycleStatusParams {
+  id: string;
+  lifecycleStatus: IntegrationConnectionLifecycleStatus;
+}
+
+export async function updateIntegrationConnectionLifecycleStatus(
+  params: UpdateIntegrationConnectionLifecycleStatusParams,
+  options: {tx?: IntegrationDb | IntegrationTx | undefined} = {},
+): Promise<IntegrationConnection | undefined> {
+  const executor = options.tx ?? db();
+  const [row] = await executor
+    .update(integrationConnections)
+    .set({lifecycleStatus: params.lifecycleStatus, updatedAt: new Date()})
+    .where(eq(integrationConnections.id, params.id))
+    .returning();
+  if (!row) return undefined;
+  return toIntegrationConnection(row);
+}
+
+export type UpdateIntegrationConnectionLifecycleStatusFn =
+  typeof updateIntegrationConnectionLifecycleStatus;
+
+export async function deleteIntegrationConnection(
+  params: {id: string},
+  options: {tx?: IntegrationDb | IntegrationTx | undefined} = {},
+): Promise<boolean> {
+  const executor = options.tx ?? db();
+  const result = await executor
+    .delete(integrationConnections)
+    .where(eq(integrationConnections.id, params.id));
+  return (result.rowCount ?? 0) > 0;
+}
+
+export type DeleteIntegrationConnectionFn = typeof deleteIntegrationConnection;
+
+export interface ListIntegrationConnectionsParams {
+  workspaceId: string;
+}
+
+export async function listIntegrationConnections(
+  params: ListIntegrationConnectionsParams,
+): Promise<IntegrationConnection[]> {
+  const rows = await db()
+    .select()
+    .from(integrationConnections)
+    .where(eq(integrationConnections.workspaceId, params.workspaceId))
+    .orderBy(integrationConnections.createdAt, integrationConnections.id);
+
+  const connections = rows.map(toIntegrationConnection);
+  return connections;
+}
+
+export interface ListIntegrationConnectionsByProviderParams {
+  provider: IntegrationProviderKind;
+}
+
+export async function listIntegrationConnectionsByProvider(
+  params: ListIntegrationConnectionsByProviderParams,
+): Promise<IntegrationConnection[]> {
+  const rows = await db()
+    .select()
+    .from(integrationConnections)
+    .where(eq(integrationConnections.provider, params.provider))
+    .orderBy(integrationConnections.createdAt, integrationConnections.id);
+
+  return rows.map(toIntegrationConnection);
+}

package/src/db/db.ts

@@ -0,0 +1,22 @@
+import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
+import {pgClient} from '@shipfox/node-postgres';
+import {integrationConnections} from './schema/connections.js';
+import {integrationsOutbox} from './schema/outbox.js';
+import {integrationsWebhookDeliveries} from './schema/webhook-deliveries.js';
+
+export const schema = {
+  integrationConnections,
+  integrationsOutbox,
+  integrationsWebhookDeliveries,
+};
+
+let _db: NodePgDatabase<typeof schema> | undefined;
+
+export function db() {
+  if (!_db) _db = drizzle(pgClient(), {schema});
+  return _db;
+}
+
+export function closeDb(): void {
+  _db = undefined;
+}

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_${name}`);

package/src/db/schema/connections.ts

@@ -0,0 +1,49 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {index, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import type {
+  IntegrationConnection,
+  IntegrationConnectionLifecycleStatus,
+} from '#core/entities/connection.js';
+import type {IntegrationProviderKind} from '#core/entities/provider.js';
+import {pgTable} from './common.js';
+
+export const integrationConnections = pgTable(
+  'connections',
+  {
+    id: uuidv7PrimaryKey(),
+    workspaceId: uuid('workspace_id').notNull(),
+    provider: text('provider').notNull(),
+    externalAccountId: text('external_account_id').notNull(),
+    slug: text('slug').notNull(),
+    displayName: text('display_name').notNull(),
+    lifecycleStatus: text('lifecycle_status').notNull().default('active'),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('integrations_connections_workspace_external_unique').on(
+      table.workspaceId,
+      table.provider,
+      table.externalAccountId,
+    ),
+    uniqueIndex('integrations_connections_workspace_slug_unique').on(table.workspaceId, table.slug),
+    index('integrations_connections_workspace_id_idx').on(table.workspaceId),
+  ],
+);
+
+export type IntegrationConnectionDb = typeof integrationConnections.$inferSelect;
+export type IntegrationConnectionCreateDb = typeof integrationConnections.$inferInsert;
+
+export function toIntegrationConnection(row: IntegrationConnectionDb): IntegrationConnection {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId,
+    provider: row.provider as IntegrationProviderKind,
+    externalAccountId: row.externalAccountId,
+    slug: row.slug,
+    displayName: row.displayName,
+    lifecycleStatus: row.lifecycleStatus as IntegrationConnectionLifecycleStatus,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}

package/src/db/schema/outbox.ts

@@ -0,0 +1,4 @@
+import {createOutboxTable} from '@shipfox/node-outbox';
+import {pgTable} from './common.js';
+
+export const integrationsOutbox = createOutboxTable(pgTable);

package/src/db/schema/webhook-deliveries.ts

@@ -0,0 +1,19 @@
+import {index, primaryKey, text, timestamp} from 'drizzle-orm/pg-core';
+import {pgTable} from './common.js';
+
+export const integrationsWebhookDeliveries = pgTable(
+  'webhook_deliveries',
+  {
+    provider: text('provider').notNull(),
+    dedupScope: text('dedup_scope').notNull(),
+    deliveryId: text('delivery_id').notNull(),
+    receivedAt: timestamp('received_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    primaryKey({
+      name: 'integrations_webhook_deliveries_dedup_pk',
+      columns: [table.provider, table.dedupScope, table.deliveryId],
+    }),
+    index('integrations_webhook_deliveries_received_at_idx').on(table.receivedAt),
+  ],
+);

package/src/db/webhook-deliveries.test.ts

@@ -0,0 +1,267 @@
+import {
+  INTEGRATION_EVENT_RECEIVED,
+  INTEGRATION_SOURCE_COMMIT_PUSHED,
+  type IntegrationEventReceivedEvent,
+  type SourcePushPayload,
+} from '@shipfox/api-integration-core-dto';
+import {and, eq, sql} from 'drizzle-orm';
+import {db} from './db.js';
+import {integrationsOutbox} from './schema/outbox.js';
+import {integrationsWebhookDeliveries} from './schema/webhook-deliveries.js';
+import {
+  publishIntegrationEventReceived,
+  publishSourceCommitPushed,
+  publishSourcePush,
+  recordDeliveryOnly,
+} from './webhook-deliveries.js';
+
+function buildEvent(
+  overrides: Partial<IntegrationEventReceivedEvent> = {},
+): IntegrationEventReceivedEvent {
+  return {
+    provider: 'github',
+    source: 'github_acme_production',
+    event: 'push',
+    workspaceId: crypto.randomUUID(),
+    connectionId: crypto.randomUUID(),
+    connectionName: 'Acme Production',
+    deliveryId: crypto.randomUUID(),
+    receivedAt: new Date().toISOString(),
+    payload: {
+      externalRepositoryId: 'github:42',
+      ref: 'main',
+      headCommitSha: 'abc123',
+      defaultBranch: 'main',
+      isDefaultBranch: true,
+    },
+    ...overrides,
+  };
+}
+
+function buildPush(overrides: Partial<SourcePushPayload> = {}): SourcePushPayload {
+  return {
+    externalRepositoryId: 'github:42',
+    ref: 'main',
+    headCommitSha: 'abc123',
+    defaultBranch: 'main',
+    isDefaultBranch: true,
+    ...overrides,
+  };
+}
+
+function buildSourcePushParams() {
+  const rawPayload = {
+    ref: 'refs/heads/main',
+    after: 'abc123',
+    repository: {id: 42, default_branch: 'main'},
+  };
+  return {
+    provider: 'github',
+    source: 'github_acme_production',
+    workspaceId: crypto.randomUUID(),
+    connectionId: crypto.randomUUID(),
+    connectionName: 'Acme Production',
+    deliveryId: crypto.randomUUID(),
+    receivedAt: new Date().toISOString(),
+    rawPayload,
+    push: buildPush(),
+  };
+}
+
+function deliveriesFor(provider: string, deliveryId: string) {
+  return db()
+    .select()
+    .from(integrationsWebhookDeliveries)
+    .where(
+      and(
+        eq(integrationsWebhookDeliveries.provider, provider),
+        eq(integrationsWebhookDeliveries.deliveryId, deliveryId),
+      ),
+    );
+}
+
+function outboxFor(deliveryId: string) {
+  return db()
+    .select()
+    .from(integrationsOutbox)
+    .where(sql`${integrationsOutbox.payload}->>'deliveryId' = ${deliveryId}`);
+}
+
+describe('integration webhook delivery persistence', () => {
+  it('writes a delivery row and an outbox event for a new delivery', async () => {
+    const event = buildEvent();
+
+    const result = await publishIntegrationEventReceived({tx: db(), event});
+
+    expect(result.published).toBe(true);
+    expect(await deliveriesFor(event.provider, event.deliveryId)).toHaveLength(1);
+    const outbox = await outboxFor(event.deliveryId);
+    expect(outbox).toHaveLength(1);
+    expect(outbox[0]?.eventType).toBe(INTEGRATION_EVENT_RECEIVED);
+    expect(outbox[0]?.payload).toMatchObject({
+      provider: 'github',
+      source: event.source,
+      event: 'push',
+      deliveryId: event.deliveryId,
+      payload: {externalRepositoryId: 'github:42', isDefaultBranch: true},
+    });
+  });
+
+  it('does not publish a duplicate delivery twice', async () => {
+    const event = buildEvent();
+
+    const first = await publishIntegrationEventReceived({tx: db(), event});
+    const second = await publishIntegrationEventReceived({tx: db(), event});
+
+    expect(first.published).toBe(true);
+    expect(second.published).toBe(false);
+    expect(await deliveriesFor(event.provider, event.deliveryId)).toHaveLength(1);
+    expect(await outboxFor(event.deliveryId)).toHaveLength(1);
+  });
+
+  it('deduplicates received events per connection', async () => {
+    const deliveryId = crypto.randomUUID();
+    const firstConnectionEvent = buildEvent({
+      provider: 'webhook',
+      source: 'stripe-prod',
+      event: 'received',
+      deliveryId,
+    });
+    const secondConnectionEvent = buildEvent({
+      provider: 'webhook',
+      source: 'stripe-dev',
+      event: 'received',
+      deliveryId,
+    });
+
+    const first = await publishIntegrationEventReceived({tx: db(), event: firstConnectionEvent});
+    const second = await publishIntegrationEventReceived({tx: db(), event: secondConnectionEvent});
+    const duplicate = await publishIntegrationEventReceived({
+      tx: db(),
+      event: firstConnectionEvent,
+    });
+
+    expect(first.published).toBe(true);
+    expect(second.published).toBe(true);
+    expect(duplicate.published).toBe(false);
+    expect(await deliveriesFor('webhook', deliveryId)).toHaveLength(2);
+    expect(await outboxFor(deliveryId)).toHaveLength(2);
+  });
+
+  it('records a delivery without writing an outbox event', async () => {
+    const deliveryId = crypto.randomUUID();
+
+    await recordDeliveryOnly({tx: db(), provider: 'github', deliveryId});
+
+    expect(await deliveriesFor('github', deliveryId)).toHaveLength(1);
+    expect(await outboxFor(deliveryId)).toHaveLength(0);
+  });
+
+  it('ignores a duplicate delivery record', async () => {
+    const deliveryId = crypto.randomUUID();
+
+    await recordDeliveryOnly({tx: db(), provider: 'github', deliveryId});
+    await recordDeliveryOnly({tx: db(), provider: 'github', deliveryId});
+
+    expect(await deliveriesFor('github', deliveryId)).toHaveLength(1);
+  });
+});
+
+describe('publishSourcePush', () => {
+  it('writes the delivery row plus both outbox events for a new delivery', async () => {
+    const params = buildSourcePushParams();
+
+    const result = await db().transaction((tx) => publishSourcePush({tx, ...params}));
+
+    expect(result.published).toBe(true);
+    expect(await deliveriesFor(params.provider, params.deliveryId)).toHaveLength(1);
+    const types = (await outboxFor(params.deliveryId)).map((row) => row.eventType).sort();
+    expect(types).toEqual([INTEGRATION_EVENT_RECEIVED, INTEGRATION_SOURCE_COMMIT_PUSHED].sort());
+  });
+
+  it('emits the generic envelope (for triggers) and the typed event (for projects)', async () => {
+    const params = buildSourcePushParams();
+
+    await db().transaction((tx) => publishSourcePush({tx, ...params}));
+
+    const outbox = await outboxFor(params.deliveryId);
+    const envelope = outbox.find((row) => row.eventType === INTEGRATION_EVENT_RECEIVED);
+    const typed = outbox.find((row) => row.eventType === INTEGRATION_SOURCE_COMMIT_PUSHED);
+    expect(envelope?.payload).toMatchObject({
+      provider: 'github',
+      source: params.source,
+      event: 'push',
+      deliveryId: params.deliveryId,
+      payload: params.rawPayload,
+    });
+    expect(typed?.payload).toMatchObject({
+      provider: 'github',
+      deliveryId: params.deliveryId,
+      push: {externalRepositoryId: 'github:42', ref: 'main', headCommitSha: 'abc123'},
+    });
+  });
+
+  it('writes nothing for a duplicate delivery', async () => {
+    const params = buildSourcePushParams();
+
+    const first = await db().transaction((tx) => publishSourcePush({tx, ...params}));
+    const second = await db().transaction((tx) => publishSourcePush({tx, ...params}));
+
+    expect(first.published).toBe(true);
+    expect(second.published).toBe(false);
+    expect(await deliveriesFor(params.provider, params.deliveryId)).toHaveLength(1);
+    expect(await outboxFor(params.deliveryId)).toHaveLength(2);
+  });
+
+  it('does not publish when the delivery was already recorded (record-only first)', async () => {
+    const params = buildSourcePushParams();
+    await recordDeliveryOnly({
+      tx: db(),
+      provider: params.provider,
+      deliveryId: params.deliveryId,
+    });
+
+    const result = await db().transaction((tx) => publishSourcePush({tx, ...params}));
+
+    expect(result.published).toBe(false);
+    expect(await deliveriesFor(params.provider, params.deliveryId)).toHaveLength(1);
+    expect(await outboxFor(params.deliveryId)).toHaveLength(0);
+  });
+});
+
+describe('publishSourceCommitPushed', () => {
+  function buildParams() {
+    return {
+      provider: 'gitea',
+      workspaceId: crypto.randomUUID(),
+      connectionId: crypto.randomUUID(),
+      deliveryId: crypto.randomUUID(),
+      receivedAt: new Date().toISOString(),
+      push: buildPush({externalRepositoryId: 'gitea:gitea-owner/platform'}),
+    };
+  }
+
+  it('writes only the typed event, never the generic envelope', async () => {
+    const params = buildParams();
+
+    await publishSourceCommitPushed(params);
+
+    const outbox = await outboxFor(params.deliveryId);
+    expect(outbox).toHaveLength(1);
+    expect(outbox[0]?.eventType).toBe(INTEGRATION_SOURCE_COMMIT_PUSHED);
+    expect(outbox.some((row) => row.eventType === INTEGRATION_EVENT_RECEIVED)).toBe(false);
+    expect(outbox[0]?.payload).toMatchObject({
+      provider: 'gitea',
+      deliveryId: params.deliveryId,
+      push: {externalRepositoryId: 'gitea:gitea-owner/platform', isDefaultBranch: true},
+    });
+  });
+
+  it('does not write a webhook-delivery dedup row', async () => {
+    const params = buildParams();
+
+    await publishSourceCommitPushed(params);
+
+    expect(await deliveriesFor(params.provider, params.deliveryId)).toHaveLength(0);
+  });
+});