@shipfox/api-integration-linear 2.0.0

package/src/core/webhook.test.ts

@@ -0,0 +1,318 @@
+import {randomUUID} from 'node:crypto';
+import type {
+  GetIntegrationConnectionByIdFn,
+  IntegrationConnection,
+  PublishIntegrationEventReceivedFn,
+  RecordDeliveryOnlyFn,
+} from '@shipfox/api-integration-core-dto';
+import type {LinearWebhookBaseEnvelopeDto} from '@shipfox/api-integration-linear-dto';
+import {db} from '#db/db.js';
+import {upsertLinearInstallation} from '#db/installations.js';
+import {linearInstallations} from '#db/schema/installations.js';
+import {handleLinearWebhook} from './webhook.js';
+
+function fakeConnection(overrides: Partial<IntegrationConnection> = {}): IntegrationConnection {
+  return {
+    id: randomUUID(),
+    workspaceId: randomUUID(),
+    provider: 'linear',
+    externalAccountId: 'org-1',
+    slug: 'Linear_Acme',
+    displayName: 'Linear Acme',
+    lifecycleStatus: 'active',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+function payload(overrides: Record<string, unknown> = {}) {
+  return {
+    action: 'create',
+    type: 'Issue',
+    organizationId: `org-${randomUUID()}`,
+    webhookTimestamp: Date.now(),
+    data: {id: 'issue-1'},
+    ...overrides,
+  };
+}
+
+function agentSessionPayload(
+  overrides: Record<string, unknown> = {},
+): LinearWebhookBaseEnvelopeDto {
+  return {
+    action: 'created',
+    type: 'AgentSessionEvent',
+    organizationId: `org-${randomUUID()}`,
+    appUserId: 'app-user-1',
+    webhookTimestamp: Date.now(),
+    agentSession: {id: 'session-1'},
+    ...overrides,
+  };
+}
+
+function deps(
+  options: {
+    connection?: IntegrationConnection | undefined;
+    publishIntegrationEventReceivedResult?: {published: boolean};
+  } = {},
+) {
+  return {
+    publishIntegrationEventReceived: vi.fn<PublishIntegrationEventReceivedFn>(() =>
+      Promise.resolve(options.publishIntegrationEventReceivedResult ?? {published: true}),
+    ),
+    recordDeliveryOnly: vi.fn<RecordDeliveryOnlyFn>(() => Promise.resolve()),
+    getIntegrationConnectionById: vi.fn<GetIntegrationConnectionByIdFn>(() =>
+      Promise.resolve(options.connection ?? fakeConnection()),
+    ),
+  };
+}
+
+function firstPublishIntegrationEventReceivedCall(publishIntegrationEventReceived: {
+  mock: {calls: Array<Parameters<PublishIntegrationEventReceivedFn>>};
+}): Parameters<PublishIntegrationEventReceivedFn>[0] {
+  const [call] = publishIntegrationEventReceived.mock.calls;
+  if (!call) throw new Error('Expected publishIntegrationEventReceived to be called');
+  return call[0];
+}
+
+function firstRecordDeliveryOnlyCall(recordDeliveryOnly: {
+  mock: {calls: Array<Parameters<RecordDeliveryOnlyFn>>};
+}): Parameters<RecordDeliveryOnlyFn>[0] {
+  const [call] = recordDeliveryOnly.mock.calls;
+  if (!call) throw new Error('Expected recordDeliveryOnly to be called');
+  return call[0];
+}
+
+async function seedInstallation(input: {
+  connectionId: string;
+  organizationId: string;
+  status?: 'installed' | 'revoked' | undefined;
+}): Promise<void> {
+  await upsertLinearInstallation({
+    connectionId: input.connectionId,
+    organizationId: input.organizationId,
+    organizationUrlKey: 'acme',
+    appUserId: 'app-user-1',
+    scopes: ['read', 'write'],
+    status: input.status ?? 'installed',
+  });
+}
+
+describe('handleLinearWebhook', () => {
+  beforeEach(async () => {
+    await db().delete(linearInstallations);
+  });
+
+  it('publishes a supported Linear data event for an active connection', async () => {
+    const connection = fakeConnection();
+    const deliveryId = randomUUID();
+    const rawPayload = payload({organizationId: 'org-active'});
+    await seedInstallation({connectionId: connection.id, organizationId: 'org-active'});
+    const handlers = deps({connection});
+
+    const result = await handleLinearWebhook({
+      tx: db(),
+      deliveryId,
+      payload: rawPayload,
+      rawPayload,
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('published');
+    expect(handlers.recordDeliveryOnly).not.toHaveBeenCalled();
+    expect(
+      firstPublishIntegrationEventReceivedCall(handlers.publishIntegrationEventReceived),
+    ).toMatchObject({
+      event: {
+        provider: 'linear',
+        source: connection.slug,
+        event: 'Issue.create',
+        workspaceId: connection.workspaceId,
+        connectionId: connection.id,
+        connectionName: connection.displayName,
+        deliveryId,
+        payload: rawPayload,
+      },
+    });
+  });
+
+  it('returns duplicate when the delivery was already published', async () => {
+    const connection = fakeConnection();
+    const rawPayload = payload({organizationId: 'org-duplicate'});
+    await seedInstallation({connectionId: connection.id, organizationId: 'org-duplicate'});
+    const handlers = deps({
+      connection,
+      publishIntegrationEventReceivedResult: {published: false},
+    });
+
+    const result = await handleLinearWebhook({
+      tx: db(),
+      deliveryId: randomUUID(),
+      payload: rawPayload,
+      rawPayload,
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('duplicate');
+    expect(handlers.publishIntegrationEventReceived).toHaveBeenCalledTimes(1);
+    expect(handlers.recordDeliveryOnly).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['created', 'agentSession.created'],
+    ['prompted', 'agentSession.prompted'],
+  ] as const)('publishes AgentSessionEvent %s as %s', async (action, event) => {
+    const connection = fakeConnection();
+    const rawPayload = agentSessionPayload({
+      action,
+      organizationId: `org-${action}`,
+      promptContext: '<issue identifier="ENG-879">Route the complete payload</issue>',
+    });
+    await seedInstallation({connectionId: connection.id, organizationId: `org-${action}`});
+    const handlers = deps({connection});
+
+    const result = await handleLinearWebhook({
+      tx: db(),
+      deliveryId: randomUUID(),
+      payload: rawPayload,
+      rawPayload,
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('published');
+    const published = firstPublishIntegrationEventReceivedCall(
+      handlers.publishIntegrationEventReceived,
+    );
+    expect(published.event.event).toBe(event);
+    expect(published.event.payload).toEqual(rawPayload);
+  });
+
+  it('records the delivery only for an unknown organization', async () => {
+    const handlers = deps();
+    const deliveryId = randomUUID();
+
+    const result = await handleLinearWebhook({
+      tx: db(),
+      deliveryId,
+      payload: payload({organizationId: 'org-missing'}),
+      rawPayload: payload({organizationId: 'org-missing'}),
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('unknown-organization');
+    expect(handlers.getIntegrationConnectionById).not.toHaveBeenCalled();
+    expect(handlers.publishIntegrationEventReceived).not.toHaveBeenCalled();
+    expect(firstRecordDeliveryOnlyCall(handlers.recordDeliveryOnly)).toMatchObject({
+      provider: 'linear',
+      deliveryId,
+    });
+  });
+
+  it('records the delivery only for a revoked installation', async () => {
+    const connection = fakeConnection();
+    const rawPayload = payload({organizationId: 'org-revoked'});
+    await seedInstallation({
+      connectionId: connection.id,
+      organizationId: 'org-revoked',
+      status: 'revoked',
+    });
+    const handlers = deps({connection});
+
+    const result = await handleLinearWebhook({
+      tx: db(),
+      deliveryId: randomUUID(),
+      payload: rawPayload,
+      rawPayload,
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('revoked-installation');
+    expect(handlers.getIntegrationConnectionById).not.toHaveBeenCalled();
+    expect(handlers.publishIntegrationEventReceived).not.toHaveBeenCalled();
+    expect(handlers.recordDeliveryOnly).toHaveBeenCalledTimes(1);
+  });
+
+  it('records the delivery only when the installation has no connection', async () => {
+    const connection = fakeConnection();
+    const rawPayload = payload({organizationId: 'org-dangling'});
+    await seedInstallation({connectionId: connection.id, organizationId: 'org-dangling'});
+    const handlers = deps({connection});
+    handlers.getIntegrationConnectionById.mockResolvedValue(undefined);
+
+    const result = await handleLinearWebhook({
+      tx: db(),
+      deliveryId: randomUUID(),
+      payload: rawPayload,
+      rawPayload,
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('missing-connection');
+    expect(handlers.publishIntegrationEventReceived).not.toHaveBeenCalled();
+    expect(handlers.recordDeliveryOnly).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    'disabled',
+    'error',
+  ] as const)('records the delivery only when the connection is %s', async (lifecycleStatus) => {
+    const connection = fakeConnection({lifecycleStatus});
+    const rawPayload = payload({organizationId: `org-${lifecycleStatus}`});
+    await seedInstallation({
+      connectionId: connection.id,
+      organizationId: `org-${lifecycleStatus}`,
+    });
+    const handlers = deps({connection});
+
+    const result = await handleLinearWebhook({
+      tx: db(),
+      deliveryId: randomUUID(),
+      payload: rawPayload,
+      rawPayload,
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('inactive-connection');
+    expect(handlers.publishIntegrationEventReceived).not.toHaveBeenCalled();
+    expect(handlers.recordDeliveryOnly).toHaveBeenCalledTimes(1);
+  });
+
+  it('records the delivery only for unsupported resources', async () => {
+    const connection = fakeConnection();
+    const rawPayload = payload({organizationId: 'org-reaction', type: 'Reaction'});
+    await seedInstallation({connectionId: connection.id, organizationId: 'org-reaction'});
+    const handlers = deps({connection});
+
+    const result = await handleLinearWebhook({
+      tx: db(),
+      deliveryId: randomUUID(),
+      payload: rawPayload,
+      rawPayload,
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('unsupported-event');
+    expect(handlers.publishIntegrationEventReceived).not.toHaveBeenCalled();
+    expect(handlers.recordDeliveryOnly).toHaveBeenCalledTimes(1);
+  });
+
+  it('records and drops an unsupported AgentSessionEvent action', async () => {
+    const connection = fakeConnection();
+    const rawPayload = agentSessionPayload({action: 'resolved', organizationId: 'org-resolved'});
+    await seedInstallation({connectionId: connection.id, organizationId: 'org-resolved'});
+    const handlers = deps({connection});
+
+    const result = await handleLinearWebhook({
+      tx: db(),
+      deliveryId: randomUUID(),
+      payload: rawPayload,
+      rawPayload,
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('unsupported-event');
+    expect(handlers.publishIntegrationEventReceived).not.toHaveBeenCalled();
+    expect(handlers.recordDeliveryOnly).toHaveBeenCalledTimes(1);
+  });
+});

package/src/core/webhook.ts

@@ -0,0 +1,146 @@
+import type {
+  GetIntegrationConnectionByIdFn,
+  IntegrationTx,
+  PublishIntegrationEventReceivedFn,
+  RecordDeliveryOnlyFn,
+} from '@shipfox/api-integration-core-dto';
+import {
+  LINEAR_PROVIDER,
+  type LinearWebhookBaseEnvelopeDto,
+  type LinearWebhookEnvelopeDto,
+  type LinearWebhookEventName,
+  linearWebhookEnvelopeSchema,
+} from '@shipfox/api-integration-linear-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import {getLinearInstallationByOrganizationId} from '#db/installations.js';
+
+export interface HandleLinearWebhookParams {
+  tx: IntegrationTx;
+  deliveryId: string;
+  payload: LinearWebhookBaseEnvelopeDto;
+  rawPayload: unknown;
+  publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+}
+
+export type HandleLinearWebhookOutcome =
+  | 'published'
+  | 'duplicate'
+  | 'unknown-organization'
+  | 'revoked-installation'
+  | 'missing-connection'
+  | 'inactive-connection'
+  | 'unsupported-event';
+
+export async function handleLinearWebhook(
+  params: HandleLinearWebhookParams,
+): Promise<{outcome: HandleLinearWebhookOutcome}> {
+  const installation = await getLinearInstallationByOrganizationId(params.payload.organizationId, {
+    tx: params.tx,
+  });
+  if (!installation) {
+    logger().warn(
+      {deliveryId: params.deliveryId, organizationId: params.payload.organizationId},
+      'linear webhook: unknown organization, dropping',
+    );
+    await recordDeliveryOnly(params);
+    return {outcome: 'unknown-organization'};
+  }
+
+  if (installation.status !== 'installed') {
+    logger().info(
+      {
+        deliveryId: params.deliveryId,
+        organizationId: params.payload.organizationId,
+        connectionId: installation.connectionId,
+        status: installation.status,
+      },
+      'linear webhook: installation is not installed, dropping',
+    );
+    await recordDeliveryOnly(params);
+    return {outcome: 'revoked-installation'};
+  }
+
+  const connection = await params.getIntegrationConnectionById(installation.connectionId, {
+    tx: params.tx,
+  });
+  if (!connection) {
+    logger().warn(
+      {
+        deliveryId: params.deliveryId,
+        organizationId: params.payload.organizationId,
+        connectionId: installation.connectionId,
+      },
+      'linear webhook: installation has no connection, dropping',
+    );
+    await recordDeliveryOnly(params);
+    return {outcome: 'missing-connection'};
+  }
+
+  if (connection.lifecycleStatus !== 'active') {
+    const logContext = {
+      deliveryId: params.deliveryId,
+      organizationId: params.payload.organizationId,
+      connectionId: connection.id,
+      workspaceId: connection.workspaceId,
+      lifecycleStatus: connection.lifecycleStatus,
+    };
+    if (connection.lifecycleStatus === 'error') {
+      logger().warn(logContext, 'linear webhook: connection in error state, dropping');
+    } else {
+      logger().info(logContext, 'linear webhook: connection disabled, dropping');
+    }
+    await recordDeliveryOnly(params);
+    return {outcome: 'inactive-connection'};
+  }
+
+  const supported = linearWebhookEnvelopeSchema.safeParse(params.payload);
+  if (!supported.success) {
+    logger().info(
+      {
+        deliveryId: params.deliveryId,
+        organizationId: params.payload.organizationId,
+        type: params.payload.type,
+        action: params.payload.action,
+      },
+      'linear webhook: unsupported event, dropping',
+    );
+    await recordDeliveryOnly(params);
+    return {outcome: 'unsupported-event'};
+  }
+
+  const result = await params.publishIntegrationEventReceived({
+    tx: params.tx,
+    event: {
+      provider: LINEAR_PROVIDER,
+      source: connection.slug,
+      event: linearWebhookEventName(supported.data),
+      workspaceId: connection.workspaceId,
+      connectionId: connection.id,
+      connectionName: connection.displayName,
+      deliveryId: params.deliveryId,
+      receivedAt: new Date().toISOString(),
+      payload: params.rawPayload,
+    },
+  });
+
+  return {outcome: result.published ? 'published' : 'duplicate'};
+}
+
+function linearWebhookEventName(payload: LinearWebhookEnvelopeDto): LinearWebhookEventName {
+  if (payload.type === 'AgentSessionEvent') return `agentSession.${payload.action}`;
+  return `${payload.type}.${payload.action}`;
+}
+
+async function recordDeliveryOnly(params: {
+  tx: IntegrationTx;
+  deliveryId: string;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+}): Promise<void> {
+  await params.recordDeliveryOnly({
+    tx: params.tx,
+    provider: LINEAR_PROVIDER,
+    deliveryId: params.deliveryId,
+  });
+}

package/src/db/db.ts

@@ -0,0 +1,18 @@
+import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
+import {pgClient} from '@shipfox/node-postgres';
+import {linearInstallations} from './schema/installations.js';
+
+export const schema = {
+  linearInstallations,
+};
+
+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/installations.test.ts

@@ -0,0 +1,182 @@
+import {
+  LinearConnectionAlreadyLinkedError,
+  LinearInstallationAlreadyLinkedError,
+} from '#core/errors.js';
+import {
+  getLinearInstallationByConnectionId,
+  getLinearInstallationByOrganizationId,
+  markLinearInstallationRevoked,
+  upsertLinearInstallation,
+  withLinearRefreshLock,
+} from './installations.js';
+
+describe('linear installations', () => {
+  it('upserts and reads an installation by connection id', async () => {
+    const connectionId = crypto.randomUUID();
+    const organizationId = `org-${crypto.randomUUID()}`;
+    const tokenExpiresAt = new Date('2026-08-01T00:00:00.000Z');
+
+    const installation = await upsertLinearInstallation({
+      connectionId,
+      organizationId,
+      organizationUrlKey: 'acme',
+      appUserId: 'app-user-1',
+      scopes: ['read', 'write'],
+      tokenExpiresAt,
+      status: 'installed',
+    });
+
+    const result = await getLinearInstallationByConnectionId(connectionId);
+    expect(result).toEqual(installation);
+  });
+
+  it('updates mutable metadata for an existing connection id', async () => {
+    const connectionId = crypto.randomUUID();
+    const organizationId = `org-${crypto.randomUUID()}`;
+    await upsertLinearInstallation({
+      connectionId,
+      organizationId,
+      organizationUrlKey: 'old',
+      appUserId: 'app-user-2',
+      scopes: ['read'],
+      status: 'installed',
+    });
+
+    const result = await upsertLinearInstallation({
+      connectionId,
+      organizationId,
+      organizationUrlKey: 'new',
+      appUserId: 'app-user-3',
+      scopes: ['read', 'write', 'app:assignable'],
+      tokenExpiresAt: null,
+      status: 'installed',
+    });
+
+    expect(result.organizationUrlKey).toBe('new');
+    expect(result.appUserId).toBe('app-user-3');
+    expect(result.scopes).toEqual(['read', 'write', 'app:assignable']);
+  });
+
+  it('refuses to claim an organization already linked to another connection', async () => {
+    const organizationId = `org-${crypto.randomUUID()}`;
+    const firstConnectionId = crypto.randomUUID();
+    const secondConnectionId = crypto.randomUUID();
+    await upsertLinearInstallation({
+      connectionId: firstConnectionId,
+      organizationId,
+      organizationUrlKey: 'claimed',
+      appUserId: 'app-user-claimed',
+      scopes: ['read'],
+      status: 'installed',
+    });
+
+    let error: unknown;
+    try {
+      await upsertLinearInstallation({
+        connectionId: secondConnectionId,
+        organizationId,
+        organizationUrlKey: 'claimed',
+        appUserId: 'app-user-claimed',
+        scopes: ['read', 'write'],
+        status: 'installed',
+      });
+    } catch (caught) {
+      error = caught;
+    }
+
+    const installation = await getLinearInstallationByOrganizationId(organizationId);
+
+    expect(error).toBeInstanceOf(LinearInstallationAlreadyLinkedError);
+    expect(installation?.connectionId).toBe(firstConnectionId);
+  });
+
+  it('refuses to repoint an existing connection to another organization', async () => {
+    const connectionId = crypto.randomUUID();
+    const firstOrganizationId = `org-${crypto.randomUUID()}`;
+    const secondOrganizationId = `org-${crypto.randomUUID()}`;
+    await upsertLinearInstallation({
+      connectionId,
+      organizationId: firstOrganizationId,
+      organizationUrlKey: 'first',
+      appUserId: 'app-user-first',
+      scopes: ['read'],
+      status: 'installed',
+    });
+
+    let error: unknown;
+    try {
+      await upsertLinearInstallation({
+        connectionId,
+        organizationId: secondOrganizationId,
+        organizationUrlKey: 'second',
+        appUserId: 'app-user-second',
+        scopes: ['read', 'write'],
+        status: 'installed',
+      });
+    } catch (caught) {
+      error = caught;
+    }
+
+    const installation = await getLinearInstallationByConnectionId(connectionId);
+
+    expect(error).toBeInstanceOf(LinearConnectionAlreadyLinkedError);
+    expect(installation?.organizationId).toBe(firstOrganizationId);
+  });
+
+  it('reads an installation by organization id', async () => {
+    const connectionId = crypto.randomUUID();
+    const organizationId = `org-${crypto.randomUUID()}`;
+    await upsertLinearInstallation({
+      connectionId,
+      organizationId,
+      organizationUrlKey: 'lookup',
+      appUserId: 'app-user-lookup',
+      scopes: ['read'],
+      status: 'installed',
+    });
+
+    const result = await getLinearInstallationByOrganizationId(organizationId);
+
+    expect(result?.connectionId).toBe(connectionId);
+  });
+
+  it('marks an installation revoked by connection id', async () => {
+    const connectionId = crypto.randomUUID();
+    await upsertLinearInstallation({
+      connectionId,
+      organizationId: `org-${crypto.randomUUID()}`,
+      organizationUrlKey: 'revoked',
+      appUserId: 'app-user-revoked',
+      scopes: ['read'],
+      status: 'installed',
+    });
+
+    const result = await markLinearInstallationRevoked(connectionId);
+
+    expect(result?.status).toBe('revoked');
+  });
+
+  it('allows one refresh lock holder per connection and fails contenders fast', async () => {
+    const connectionId = crypto.randomUUID();
+    let releaseLock: () => void = () => {
+      throw new Error('releaseLock was not initialized');
+    };
+    const holder = withLinearRefreshLock(
+      connectionId,
+      () =>
+        new Promise<string>((resolve) => {
+          releaseLock = () => resolve('holder');
+        }),
+    );
+
+    await new Promise((resolve) => setTimeout(resolve, 25));
+    const contender = await withLinearRefreshLock(connectionId, async () => 'contender');
+    const different = await withLinearRefreshLock(crypto.randomUUID(), async () => 'different');
+    releaseLock();
+    const held = await holder;
+
+    expect(contender).toEqual({acquired: false});
+    expect(different).toEqual({acquired: true, value: 'different'});
+    expect(held).toEqual({acquired: true, value: 'holder'});
+  });
+});