@shipfox/api-integration-linear 2.0.0

package/src/db/installations.ts

@@ -0,0 +1,215 @@
+import {pgClient} from '@shipfox/node-postgres';
+import {eq} from 'drizzle-orm';
+import {
+  LinearConnectionAlreadyLinkedError,
+  LinearInstallationAlreadyLinkedError,
+} from '#core/errors.js';
+import {db} from './db.js';
+import {linearInstallations, toLinearInstallation} from './schema/installations.js';
+
+export type LinearInstallationStatus = 'installed' | 'revoked';
+
+export interface LinearInstallation {
+  id: string;
+  connectionId: string;
+  organizationId: string;
+  organizationUrlKey: string;
+  appUserId: string;
+  scopes: string[];
+  tokenExpiresAt: Date | null;
+  status: LinearInstallationStatus;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface UpsertLinearInstallationParams {
+  connectionId: string;
+  organizationId: string;
+  organizationUrlKey: string;
+  appUserId: string;
+  scopes: string[];
+  tokenExpiresAt?: Date | null | undefined;
+  status: LinearInstallationStatus;
+}
+
+export interface UpdateLinearInstallationTokenExpiryParams {
+  connectionId: string;
+  tokenExpiresAt: Date | null;
+  scopes?: string[] | undefined;
+}
+
+type LinearDb = ReturnType<typeof db>;
+type LinearTx = Parameters<Parameters<LinearDb['transaction']>[0]>[0];
+
+interface PostgresErrorFields {
+  code?: unknown;
+  constraint?: unknown;
+  cause?: unknown;
+}
+
+export async function upsertLinearInstallation(
+  params: UpsertLinearInstallationParams,
+  options: {tx?: unknown} = {},
+): Promise<LinearInstallation> {
+  const executor = (options.tx ?? db()) as LinearDb | LinearTx;
+  const now = new Date();
+  let row: typeof linearInstallations.$inferSelect | undefined;
+
+  try {
+    [row] = await executor
+      .insert(linearInstallations)
+      .values({
+        connectionId: params.connectionId,
+        organizationId: params.organizationId,
+        organizationUrlKey: params.organizationUrlKey,
+        appUserId: params.appUserId,
+        scopes: params.scopes,
+        tokenExpiresAt: params.tokenExpiresAt ?? null,
+        status: params.status,
+      })
+      .onConflictDoUpdate({
+        target: linearInstallations.organizationId,
+        setWhere: eq(linearInstallations.connectionId, params.connectionId),
+        set: {
+          connectionId: params.connectionId,
+          organizationId: params.organizationId,
+          organizationUrlKey: params.organizationUrlKey,
+          appUserId: params.appUserId,
+          scopes: params.scopes,
+          tokenExpiresAt: params.tokenExpiresAt ?? null,
+          status: params.status,
+          updatedAt: now,
+        },
+      })
+      .returning();
+  } catch (error) {
+    if (isUniqueViolation(error, 'integrations_linear_installations_connection_unique')) {
+      throw new LinearConnectionAlreadyLinkedError(params.connectionId);
+    }
+    throw error;
+  }
+
+  if (!row) throw new LinearInstallationAlreadyLinkedError(params.organizationId);
+  return toLinearInstallation(row);
+}
+
+function isUniqueViolation(error: unknown, constraint: string): boolean {
+  let current = error;
+  while (typeof current === 'object' && current !== null) {
+    const postgresError = current as PostgresErrorFields;
+    if (postgresError.code === '23505' && postgresError.constraint === constraint) {
+      return true;
+    }
+    current = postgresError.cause;
+  }
+  return false;
+}
+
+export async function getLinearInstallationByConnectionId(
+  connectionId: string,
+  options: {tx?: unknown} = {},
+): Promise<LinearInstallation | undefined> {
+  const executor = (options.tx ?? db()) as LinearDb | LinearTx;
+  const rows = await executor
+    .select()
+    .from(linearInstallations)
+    .where(eq(linearInstallations.connectionId, connectionId))
+    .limit(1);
+  const row = rows[0];
+  if (!row) return undefined;
+  return toLinearInstallation(row);
+}
+
+export async function getLinearInstallationByOrganizationId(
+  organizationId: string,
+  options: {tx?: unknown} = {},
+): Promise<LinearInstallation | undefined> {
+  const executor = (options.tx ?? db()) as LinearDb | LinearTx;
+  const rows = await executor
+    .select()
+    .from(linearInstallations)
+    .where(eq(linearInstallations.organizationId, organizationId))
+    .limit(1);
+  const row = rows[0];
+  if (!row) return undefined;
+  return toLinearInstallation(row);
+}
+
+export async function updateLinearInstallationTokenExpiry(
+  params: UpdateLinearInstallationTokenExpiryParams,
+  options: {tx?: unknown} = {},
+): Promise<LinearInstallation | undefined> {
+  const executor = (options.tx ?? db()) as LinearDb | LinearTx;
+  const [row] = await executor
+    .update(linearInstallations)
+    .set({
+      tokenExpiresAt: params.tokenExpiresAt,
+      ...(params.scopes === undefined ? {} : {scopes: params.scopes}),
+      updatedAt: new Date(),
+    })
+    .where(eq(linearInstallations.connectionId, params.connectionId))
+    .returning();
+  if (!row) return undefined;
+  return toLinearInstallation(row);
+}
+
+export async function markLinearInstallationRevoked(
+  connectionId: string,
+  options: {tx?: unknown} = {},
+): Promise<LinearInstallation | undefined> {
+  const executor = (options.tx ?? db()) as LinearDb | LinearTx;
+  const [row] = await executor
+    .update(linearInstallations)
+    .set({status: 'revoked', updatedAt: new Date()})
+    .where(eq(linearInstallations.connectionId, connectionId))
+    .returning();
+  if (!row) return undefined;
+  return toLinearInstallation(row);
+}
+
+export async function deleteLinearInstallationByConnectionId(
+  connectionId: string,
+  options: {tx?: unknown} = {},
+): Promise<boolean> {
+  const executor = (options.tx ?? db()) as LinearDb | LinearTx;
+  const result = await executor
+    .delete(linearInstallations)
+    .where(eq(linearInstallations.connectionId, connectionId));
+  return (result.rowCount ?? 0) > 0;
+}
+
+export type LinearRefreshLockResult<T> = {acquired: true; value: T} | {acquired: false};
+
+export function withLinearRefreshLock<T>(
+  connectionId: string,
+  fn: () => Promise<T>,
+): Promise<LinearRefreshLockResult<T>> {
+  return withLinearRefreshLockClient(connectionId, fn);
+}
+
+async function withLinearRefreshLockClient<T>(
+  connectionId: string,
+  fn: () => Promise<T>,
+): Promise<LinearRefreshLockResult<T>> {
+  const client = await pgClient().connect();
+  let acquired = false;
+  try {
+    const lock = await client.query<{acquired: boolean}>(
+      'SELECT pg_try_advisory_lock(hashtext($1)) AS acquired',
+      [connectionId],
+    );
+    acquired = lock.rows[0]?.acquired === true;
+    if (!acquired) return {acquired: false};
+
+    const value = await fn();
+    return {acquired: true, value};
+  } finally {
+    try {
+      if (acquired) {
+        await client.query('SELECT pg_advisory_unlock(hashtext($1))', [connectionId]);
+      }
+    } finally {
+      client.release();
+    }
+  }
+}

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

package/src/db/schema/installations.ts

@@ -0,0 +1,42 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {jsonb, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import type {LinearInstallation} from '#db/installations.js';
+import {pgTable} from './common.js';
+
+export const linearInstallations = pgTable(
+  'installations',
+  {
+    id: uuidv7PrimaryKey(),
+    connectionId: uuid('connection_id').notNull(),
+    organizationId: text('organization_id').notNull(),
+    organizationUrlKey: text('organization_url_key').notNull(),
+    appUserId: text('app_user_id').notNull(),
+    scopes: jsonb('scopes').notNull().$type<string[]>(),
+    tokenExpiresAt: timestamp('token_expires_at', {withTimezone: true}),
+    status: text('status').notNull().$type<LinearInstallation['status']>(),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('integrations_linear_installations_connection_unique').on(table.connectionId),
+    uniqueIndex('integrations_linear_installations_organization_unique').on(table.organizationId),
+  ],
+);
+
+export type LinearInstallationDb = typeof linearInstallations.$inferSelect;
+export type LinearInstallationCreateDb = typeof linearInstallations.$inferInsert;
+
+export function toLinearInstallation(row: LinearInstallationDb): LinearInstallation {
+  return {
+    id: row.id,
+    connectionId: row.connectionId,
+    organizationId: row.organizationId,
+    organizationUrlKey: row.organizationUrlKey,
+    appUserId: row.appUserId,
+    scopes: row.scopes,
+    tokenExpiresAt: row.tokenExpiresAt,
+    status: row.status,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}

package/src/index.test.ts

@@ -0,0 +1,20 @@
+import {linearAgentToolCatalog} from '#core/agent-tools.js';
+import {createLinearIntegrationProvider} from '#index.js';
+
+describe('createLinearIntegrationProvider', () => {
+  it('does not wire the Linear agent tools adapter without a token store', () => {
+    const provider = createLinearIntegrationProvider();
+
+    expect(provider.adapters.agent_tools).toBeUndefined();
+  });
+
+  it('wires the Linear agent tools adapter when a token store is provided', () => {
+    const provider = createLinearIntegrationProvider({
+      agentTools: {
+        tokenStore: {getAccessToken: async () => 'linear-token'},
+      },
+    });
+
+    expect(provider.adapters.agent_tools?.catalog()).toBe(linearAgentToolCatalog);
+  });
+});

package/src/index.ts

@@ -0,0 +1,153 @@
+import {LINEAR_PROVIDER} from '@shipfox/api-integration-linear-dto';
+import {createLinearApiClient, type LinearApiClient} from '#api/client.js';
+import {config} from '#config.js';
+import {LinearAgentToolsProvider} from '#core/agent-tools-provider.js';
+import type {LinearTokenStore} from '#core/tokens.js';
+import {closeDb, db} from '#db/db.js';
+import {getLinearInstallationByConnectionId} from '#db/installations.js';
+import {migrationsPath} from '#db/migrations.js';
+import {
+  type CreateLinearIntegrationRoutesOptions,
+  createLinearIntegrationRoutes,
+} from '#presentation/routes/install.js';
+import {
+  type CreateLinearWebhookRoutesOptions,
+  createLinearWebhookRoutes,
+} from '#presentation/routes/webhooks.js';
+
+export type {LinearProvider} from '@shipfox/api-integration-linear-dto';
+export type {LinearApiClient, LinearAuthorization, LinearIdentity} from '#api/client.js';
+export {createLinearApiClient} from '#api/client.js';
+export type {
+  LinearAgentToolCatalogEntry,
+  LinearAgentToolCategory,
+  LinearAgentToolId,
+  LinearAgentToolRequiredScope,
+} from '#core/agent-tools.js';
+export {
+  linearAgentToolCatalog,
+  linearAgentToolSelectionCatalog,
+} from '#core/agent-tools.js';
+export {
+  type DisconnectLinearInstallationParams,
+  disconnectLinearInstallation,
+} from '#core/disconnect.js';
+export {
+  LinearAccessTokenMissingError,
+  LinearAuthorizationScopeMismatchError,
+  LinearConnectionAlreadyLinkedError,
+  LinearConnectionNotFoundError,
+  LinearInstallationAlreadyLinkedError,
+  LinearInstallStateActorMismatchError,
+  LinearInstallStateError,
+  LinearIntegrationProviderError,
+  LinearOAuthCallbackError,
+  LinearTokenUnrefreshableError,
+} from '#core/errors.js';
+export type {ConnectLinearInstallationInput, HandleLinearCallbackParams} from '#core/install.js';
+export {handleLinearCallback, handleLinearOAuthCallbackError} from '#core/install.js';
+export {
+  assertLinearAuthorizationScopes,
+  formatLinearOAuthScopes,
+  LINEAR_OAUTH_SCOPES,
+} from '#core/scopes.js';
+export type {LinearInstallStateClaims} from '#core/state.js';
+export {signLinearInstallState, verifyLinearInstallState} from '#core/state.js';
+export type {
+  CreateLinearTokenStoreParams,
+  GetLinearAccessTokenParams,
+  LinearConnectionResolverResult,
+  LinearSecretsStore,
+  LinearTokenStore,
+  StoreLinearTokensParams,
+} from '#core/tokens.js';
+export {
+  createLinearTokenStore,
+  linearSecretsNamespace,
+} from '#core/tokens.js';
+export type {HandleLinearWebhookOutcome, HandleLinearWebhookParams} from '#core/webhook.js';
+export {handleLinearWebhook} from '#core/webhook.js';
+export type {
+  LinearInstallation,
+  LinearInstallationStatus,
+  UpdateLinearInstallationTokenExpiryParams,
+  UpsertLinearInstallationParams,
+} from '#db/installations.js';
+export {
+  getLinearInstallationByConnectionId,
+  getLinearInstallationByOrganizationId,
+  markLinearInstallationRevoked,
+  updateLinearInstallationTokenExpiry,
+  upsertLinearInstallation,
+  withLinearRefreshLock,
+} from '#db/installations.js';
+export {
+  type CreateLinearE2eRoutesOptions,
+  createLinearE2eRoutes,
+} from '#presentation/e2eRoutes/index.js';
+export {closeDb, config, db, migrationsPath};
+
+export interface CreateLinearIntegrationProviderOptions {
+  linear?: LinearApiClient | undefined;
+  agentTools?:
+    | {
+        tokenStore: Pick<LinearTokenStore, 'getAccessToken'>;
+        endpoint?: string | URL | undefined;
+        callTimeoutMs?: number | undefined;
+      }
+    | undefined;
+  getLinearInstallationByConnectionId?: typeof getLinearInstallationByConnectionId | undefined;
+  routes?:
+    | (Omit<CreateLinearIntegrationRoutesOptions, 'linear' | 'connectionCapabilities'> &
+        Partial<CreateLinearWebhookRoutesOptions>)
+    | undefined;
+}
+
+export function createLinearIntegrationProvider(
+  options: CreateLinearIntegrationProviderOptions = {},
+) {
+  const linear = options.linear ?? createLinearApiClient();
+  const getInstallationByConnectionId =
+    options.getLinearInstallationByConnectionId ?? getLinearInstallationByConnectionId;
+  const adapters = options.agentTools
+    ? {
+        agent_tools: new LinearAgentToolsProvider(options.agentTools),
+      }
+    : {};
+
+  const routes = options.routes
+    ? [
+        createLinearIntegrationRoutes({
+          linear,
+          connectionCapabilities: adapters.agent_tools ? ['agent_tools'] : [],
+          ...options.routes,
+        }),
+      ]
+    : [];
+  if (options.routes && hasLinearWebhookRoutesOptions(options.routes)) {
+    routes.push(createLinearWebhookRoutes(options.routes));
+  }
+
+  return {
+    provider: LINEAR_PROVIDER,
+    displayName: 'Linear',
+    adapters,
+    async connectionExternalUrl(connection: {id: string}): Promise<string | undefined> {
+      const installation = await getInstallationByConnectionId(connection.id);
+      if (!installation?.organizationUrlKey) return undefined;
+      return `https://linear.app/${encodeURIComponent(installation.organizationUrlKey)}/settings`;
+    },
+    routes,
+  };
+}
+
+function hasLinearWebhookRoutesOptions(
+  routes: Partial<CreateLinearWebhookRoutesOptions>,
+): routes is CreateLinearWebhookRoutesOptions {
+  return (
+    routes.coreDb !== undefined &&
+    routes.publishIntegrationEventReceived !== undefined &&
+    routes.recordDeliveryOnly !== undefined &&
+    routes.getIntegrationConnectionById !== undefined
+  );
+}

package/src/presentation/dto/integrations.ts

@@ -0,0 +1,9 @@
+import type {IntegrationCapability, IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {toIntegrationConnectionDto as toCoreIntegrationConnectionDto} from '@shipfox/api-integration-core-dto';
+
+export function toIntegrationConnectionDto(
+  connection: IntegrationConnection,
+  params: {capabilities: IntegrationCapability[]},
+) {
+  return toCoreIntegrationConnectionDto(connection, params);
+}

package/src/presentation/e2eRoutes/create-connection.ts

@@ -0,0 +1,85 @@
+import type {IntegrationCapability, IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {
+  createE2eLinearConnectionBodySchema,
+  createE2eLinearConnectionResponseSchema,
+} from '@shipfox/api-integration-linear-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {logger} from '@shipfox/node-opentelemetry';
+import type {ConnectLinearInstallationInput} from '#core/install.js';
+import type {LinearTokenStore} from '#core/tokens.js';
+import {toIntegrationConnectionDto} from '#presentation/dto/integrations.js';
+
+export interface CreateE2eLinearConnectionRouteOptions {
+  tokenStore: Pick<LinearTokenStore, 'storeTokens'>;
+  getExistingLinearConnection: (input: {
+    organizationId: string;
+  }) => Promise<IntegrationConnection<'linear'> | undefined>;
+  connectLinearInstallation: (
+    input: ConnectLinearInstallationInput,
+  ) => Promise<IntegrationConnection<'linear'>>;
+  disconnectLinearInstallation: (input: {connectionId: string}) => Promise<void>;
+  connectionCapabilities: IntegrationCapability[];
+}
+
+export function createE2eLinearConnectionRoute(options: CreateE2eLinearConnectionRouteOptions) {
+  return defineRoute({
+    method: 'POST',
+    path: '/linear-connections',
+    description: 'Create a synthetic Linear connection for E2E tests.',
+    schema: {
+      body: createE2eLinearConnectionBodySchema,
+      response: {201: createE2eLinearConnectionResponseSchema},
+    },
+    handler: async (request, reply) => {
+      const body = request.body;
+      const existing = await options.getExistingLinearConnection({
+        organizationId: body.organization_id,
+      });
+      if (existing && existing.workspaceId !== body.workspace_id) {
+        throw new ClientError(
+          'Linear organization is already connected to another workspace',
+          'linear-connection-workspace-mismatch',
+          {status: 409},
+        );
+      }
+      const connection =
+        existing ??
+        (await options.connectLinearInstallation({
+          workspaceId: body.workspace_id,
+          organizationId: body.organization_id,
+          organizationUrlKey: body.organization_url_key,
+          appUserId: body.app_user_id,
+          scopes: body.scopes,
+          tokenExpiresAt: null,
+          displayName: body.display_name,
+        }));
+
+      try {
+        await options.tokenStore.storeTokens({
+          connectionId: connection.id,
+          accessToken: body.access_token,
+        });
+      } catch (error) {
+        if (!existing) await bestEffortDisconnectLinearInstallation(options, connection.id);
+        throw error;
+      }
+
+      reply.code(201);
+      return toIntegrationConnectionDto(connection, {capabilities: options.connectionCapabilities});
+    },
+  });
+}
+
+async function bestEffortDisconnectLinearInstallation(
+  options: CreateE2eLinearConnectionRouteOptions,
+  connectionId: string,
+): Promise<void> {
+  try {
+    await options.disconnectLinearInstallation({connectionId});
+  } catch (error) {
+    logger().warn(
+      {err: error, connectionId},
+      'Linear E2E connection compensation failed after token storage rejection',
+    );
+  }
+}