@shipfox/api-integration-core 12.1.0 → 12.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-core",
   "license": "MIT",
-  "version": "12.1.0",
+  "version": "12.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -23,29 +23,29 @@
     "ajv": "^8.20.0",
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
-    "@shipfox/api-agent-dto": "12.0.0",
-    "@shipfox/api-auth-context": "12.0.0",
-    "@shipfox/api-workflows-dto": "12.1.0",
-    "@shipfox/api-integration-core-dto": "12.0.0",
-    "@shipfox/api-integration-spi": "1.0.0",
+    "@shipfox/api-agent-dto": "12.2.0",
+    "@shipfox/api-auth-context": "12.2.0",
+    "@shipfox/api-workflows-dto": "12.2.0",
+    "@shipfox/api-integration-core-dto": "12.2.0",
+    "@shipfox/api-integration-spi": "1.0.1",
     "@shipfox/api-workspaces-dto": "12.0.0",
-    "@shipfox/api-integration-gitea": "12.0.0",
-    "@shipfox/api-integration-github": "12.0.0",
-    "@shipfox/api-integration-jira": "12.1.0",
-    "@shipfox/api-integration-linear": "12.0.0",
-    "@shipfox/api-integration-sentry": "12.0.0",
-    "@shipfox/api-integration-slack": "12.0.0",
-    "@shipfox/api-integration-webhook": "12.0.0",
+    "@shipfox/api-integration-gitea": "12.2.0",
+    "@shipfox/api-integration-github": "12.2.0",
+    "@shipfox/api-integration-jira": "12.2.0",
+    "@shipfox/api-integration-linear": "12.2.0",
+    "@shipfox/api-integration-sentry": "12.2.0",
+    "@shipfox/api-integration-slack": "12.2.0",
+    "@shipfox/api-integration-webhook": "12.2.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.3",
     "@shipfox/node-drizzle": "0.3.5",
-    "@shipfox/node-fastify": "0.4.1",
-    "@shipfox/node-module": "1.0.5",
-    "@shipfox/node-opentelemetry": "0.6.3",
+    "@shipfox/node-fastify": "0.4.2",
+    "@shipfox/node-module": "1.0.6",
+    "@shipfox/node-opentelemetry": "0.6.4",
     "@shipfox/node-error-monitoring": "0.3.0",
     "@shipfox/node-outbox": "0.2.6",
     "@shipfox/node-postgres": "0.5.0",
-    "@shipfox/node-temporal": "0.4.4",
+    "@shipfox/node-temporal": "0.4.5",
     "@shipfox/regex": "0.2.4",
     "@shipfox/redact": "0.2.6"
   },

package/src/db/connections.test.ts

@@ -1,5 +1,7 @@
+import {INTEGRATION_CONNECTION_AVAILABLE} from '@shipfox/api-integration-core-dto';
 import {upsertGithubInstallation} from '@shipfox/api-integration-github';
 import {ConnectionSlugConflictError} from '@shipfox/api-integration-spi';
+import {sql} from 'drizzle-orm';
 import {IntegrationConnectionAlreadyExistsError} from '#core/errors.js';
 import {
   createIntegrationConnection,
@@ -13,6 +15,16 @@ import {
   upsertIntegrationConnection,
 } from './connections.js';
 import {db} from './db.js';
+import {integrationsOutbox} from './schema/outbox.js';
+
+function connectionEvents(connectionId: string) {
+  return db()
+    .select()
+    .from(integrationsOutbox)
+    .where(
+      sql`${integrationsOutbox.eventType} = ${INTEGRATION_CONNECTION_AVAILABLE} AND ${integrationsOutbox.payload}->>'connectionId' = ${connectionId}`,
+    );
+}
 
 describe('integration connection queries', () => {
   let workspaceId: string;
@@ -41,6 +53,31 @@ describe('integration connection queries', () => {
     expect(second.id).toBe(first.id);
     expect(second.displayName).toBe('Renamed Debug');
     expect(second.slug).toBe('gitea_owner');
+    expect(await connectionEvents(first.id)).toHaveLength(1);
+  });
+
+  it('publishes availability when an upsert activates an existing connection', async () => {
+    const connection = await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'linear',
+      externalAccountId: 'linear-acme',
+      slug: 'linear_acme',
+      displayName: 'Linear Acme',
+      lifecycleStatus: 'disabled',
+    });
+
+    expect(await connectionEvents(connection.id)).toHaveLength(0);
+
+    await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'linear',
+      externalAccountId: 'linear-acme',
+      slug: 'linear_acme',
+      displayName: 'Linear Acme',
+      lifecycleStatus: 'active',
+    });
+
+    expect(await connectionEvents(connection.id)).toHaveLength(1);
   });
 
   it('allows multiple same-provider connections when external account differs', async () => {
@@ -148,6 +185,7 @@ describe('integration connection queries', () => {
     expect(connections).toHaveLength(1);
     expect(connections[0]?.id).toBe(first.id);
     expect(connections[0]?.displayName).toBe('Stripe');
+    expect(await connectionEvents(first.id)).toHaveLength(1);
   });
 
   it('reports slug collisions separately from duplicate external accounts', async () => {
@@ -252,6 +290,51 @@ describe('integration connection queries', () => {
     expect(updated?.lifecycleStatus).toBe('disabled');
     const reloaded = await getIntegrationConnectionById(connection.id);
     expect(reloaded?.lifecycleStatus).toBe('disabled');
+    expect(await connectionEvents(connection.id)).toHaveLength(1);
+  });
+
+  it('publishes availability when a disabled connection becomes active', async () => {
+    const connection = await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'linear',
+      externalAccountId: 'linear-acme',
+      slug: 'linear_acme',
+      displayName: 'Linear Acme',
+      lifecycleStatus: 'disabled',
+    });
+
+    expect(await connectionEvents(connection.id)).toHaveLength(0);
+
+    await updateIntegrationConnectionLifecycleStatus({
+      id: connection.id,
+      lifecycleStatus: 'active',
+    });
+
+    const events = await connectionEvents(connection.id);
+    expect(events).toHaveLength(1);
+    expect(events[0]?.payload).toEqual({
+      provider: 'linear',
+      workspaceId,
+      connectionId: connection.id,
+      slug: 'linear_acme',
+    });
+  });
+
+  it('does not republish availability when an active connection stays active', async () => {
+    const connection = await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'linear',
+      externalAccountId: 'linear-acme',
+      slug: 'linear_acme',
+      displayName: 'Linear Acme',
+    });
+
+    await updateIntegrationConnectionLifecycleStatus({
+      id: connection.id,
+      lifecycleStatus: 'active',
+    });
+
+    expect(await connectionEvents(connection.id)).toHaveLength(1);
   });
 
   it('returns undefined when updating the lifecycle status of an unknown connection', async () => {
@@ -310,5 +393,12 @@ describe('integration connection queries', () => {
 
     const connections = await listIntegrationConnections({workspaceId});
     expect(connections).toHaveLength(0);
+    const events = await db()
+      .select()
+      .from(integrationsOutbox)
+      .where(
+        sql`${integrationsOutbox.eventType} = ${INTEGRATION_CONNECTION_AVAILABLE} AND ${integrationsOutbox.payload}->>'workspaceId' = ${workspaceId}`,
+      );
+    expect(events).toHaveLength(0);
   });
 });

package/src/db/connections.ts

@@ -1,5 +1,10 @@
-import {CONNECTION_SLUG_MAX_LENGTH} from '@shipfox/api-integration-core-dto';
+import {
+  CONNECTION_SLUG_MAX_LENGTH,
+  INTEGRATION_CONNECTION_AVAILABLE,
+  type IntegrationsEventMap,
+} from '@shipfox/api-integration-core-dto';
 import {ConnectionSlugConflictError} from '@shipfox/api-integration-spi';
+import {writeOutboxEvent} from '@shipfox/node-outbox';
 import {and, eq} from 'drizzle-orm';
 import type {
   IntegrationConnection,
@@ -9,6 +14,7 @@ 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';
+import {integrationsOutbox} from './schema/outbox.js';
 
 type IntegrationDb = ReturnType<typeof db>;
 type IntegrationTx = Parameters<Parameters<IntegrationDb['transaction']>[0]>[0];
@@ -26,9 +32,13 @@ export async function upsertIntegrationConnection(
   params: UpsertIntegrationConnectionParams,
   options: {tx?: IntegrationDb | IntegrationTx | undefined} = {},
 ): Promise<IntegrationConnection> {
-  const executor = options.tx ?? db();
+  if (options.tx === undefined) {
+    return await db().transaction((tx) => upsertIntegrationConnection(params, {tx}));
+  }
+
+  const executor = options.tx;
   const now = new Date();
-  const [row] = await executor
+  let [row] = await executor
     .insert(integrationConnections)
     .values({
       workspaceId: params.workspaceId,
@@ -38,22 +48,52 @@ export async function upsertIntegrationConnection(
       displayName: params.displayName,
       lifecycleStatus: params.lifecycleStatus ?? 'active',
     })
-    .onConflictDoUpdate({
+    .onConflictDoNothing({
       target: [
         integrationConnections.workspaceId,
         integrationConnections.provider,
         integrationConnections.externalAccountId,
       ],
-      set: {
+    })
+    .returning();
+
+  let becameAvailable = row?.lifecycleStatus === 'active';
+  if (!row) {
+    const [existing] = await executor
+      .select({
+        id: integrationConnections.id,
+        lifecycleStatus: integrationConnections.lifecycleStatus,
+      })
+      .from(integrationConnections)
+      .where(
+        and(
+          eq(integrationConnections.workspaceId, params.workspaceId),
+          eq(integrationConnections.provider, params.provider),
+          eq(integrationConnections.externalAccountId, params.externalAccountId),
+        ),
+      )
+      .limit(1)
+      .for('update');
+    if (!existing) throw new Error('Integration connection upsert conflict row was not found');
+
+    [row] = await executor
+      .update(integrationConnections)
+      .set({
         displayName: params.displayName,
         lifecycleStatus: params.lifecycleStatus ?? 'active',
         updatedAt: now,
-      },
-    })
-    .returning();
+      })
+      .where(eq(integrationConnections.id, existing.id))
+      .returning();
+    becameAvailable = existing.lifecycleStatus !== 'active' && row?.lifecycleStatus === 'active';
+  }
 
   if (!row) throw new Error('Integration connection upsert returned no rows');
-  return toIntegrationConnection(row);
+  const connection = toIntegrationConnection(row);
+  if (becameAvailable) {
+    await writeConnectionAvailableEvent(executor, connection);
+  }
+  return connection;
 }
 
 export interface CreateIntegrationConnectionParams {
@@ -100,7 +140,11 @@ export async function createIntegrationConnection(
   params: CreateIntegrationConnectionParams,
   options: {tx?: IntegrationDb | IntegrationTx | undefined} = {},
 ): Promise<IntegrationConnection> {
-  const executor = options.tx ?? db();
+  if (options.tx === undefined) {
+    return await db().transaction((tx) => createIntegrationConnection(params, {tx}));
+  }
+
+  const executor = options.tx;
   let rows: (typeof integrationConnections.$inferSelect)[];
   try {
     rows = await executor
@@ -130,7 +174,11 @@ export async function createIntegrationConnection(
 
   const row = rows[0];
   if (!row) throw new Error('Integration connection insert returned no rows');
-  return toIntegrationConnection(row);
+  const connection = toIntegrationConnection(row);
+  if (connection.lifecycleStatus === 'active') {
+    await writeConnectionAvailableEvent(executor, connection);
+  }
+  return connection;
 }
 
 export interface ResolveUniqueConnectionSlugParams {
@@ -225,19 +273,50 @@ export async function updateIntegrationConnectionLifecycleStatus(
   params: UpdateIntegrationConnectionLifecycleStatusParams,
   options: {tx?: IntegrationDb | IntegrationTx | undefined} = {},
 ): Promise<IntegrationConnection | undefined> {
-  const executor = options.tx ?? db();
+  if (options.tx === undefined) {
+    return await db().transaction((tx) => updateIntegrationConnectionLifecycleStatus(params, {tx}));
+  }
+
+  const executor = options.tx;
+  const [existing] = await executor
+    .select({lifecycleStatus: integrationConnections.lifecycleStatus})
+    .from(integrationConnections)
+    .where(eq(integrationConnections.id, params.id))
+    .limit(1)
+    .for('update');
+  if (!existing) return undefined;
+
   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);
+  const connection = toIntegrationConnection(row);
+  if (existing.lifecycleStatus !== 'active' && connection.lifecycleStatus === 'active') {
+    await writeConnectionAvailableEvent(executor, connection);
+  }
+  return connection;
 }
 
 export type UpdateIntegrationConnectionLifecycleStatusFn =
   typeof updateIntegrationConnectionLifecycleStatus;
 
+async function writeConnectionAvailableEvent(
+  executor: IntegrationDb | IntegrationTx,
+  connection: IntegrationConnection,
+): Promise<void> {
+  await writeOutboxEvent<IntegrationsEventMap>(executor, integrationsOutbox, {
+    type: INTEGRATION_CONNECTION_AVAILABLE,
+    payload: {
+      provider: connection.provider,
+      workspaceId: connection.workspaceId,
+      connectionId: connection.id,
+      slug: connection.slug,
+    },
+  });
+}
+
 export async function deleteIntegrationConnection(
   params: {id: string},
   options: {tx?: IntegrationDb | IntegrationTx | undefined} = {},

package/src/providers/jira.test.ts

@@ -1,16 +1,65 @@
 import {
   getJiraInstallationByConnectionId,
   upsertJiraInstallation,
+  withJiraRefreshLock,
 } from '@shipfox/api-integration-jira';
 import {runMigrations} from '@shipfox/node-drizzle';
 import {getIntegrationConnectionById, upsertIntegrationConnection} from '#db/connections.js';
+import {db} from '#db/db.js';
+import {createTestApp, useIntegrationRouteTest} from '#test/route-utils.js';
 
 describe('jiraProviderModule', () => {
+  const context = useIntegrationRouteTest();
+
   afterEach(() => {
     vi.unstubAllEnvs();
     vi.resetModules();
   });
 
+  async function createJiraCleanupFixture() {
+    vi.stubEnv('INTEGRATIONS_ENABLE_JIRA_PROVIDER', 'true');
+    vi.resetModules();
+    const deleteSecrets = vi.fn(() => Promise.resolve(2));
+    const scopedSecrets = {
+      getSecret: vi.fn(() => Promise.resolve(null)),
+      setSecrets: vi.fn(() => Promise.resolve()),
+      deleteSecrets,
+    };
+    const {createPostgresClient} = await import('@shipfox/node-postgres');
+    createPostgresClient();
+    const {loadEnabledProviderModules} = await import('#providers/modules.js');
+    const parts = await loadEnabledProviderModules({
+      secrets: {jira: scopedSecrets, deleteSecrets},
+    });
+    const jiraPart = parts.find((part) => part.provider.provider === 'jira');
+    if (!jiraPart?.database) throw new Error('Jira provider database is not configured');
+    const cloudId = crypto.randomUUID();
+
+    await runMigrations(
+      jiraPart.database.db(),
+      jiraPart.database.migrationsPath,
+      `__drizzle_migrations_${jiraPart.database.databaseNamespace}`,
+    );
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'jira',
+      externalAccountId: cloudId,
+      slug: 'jira_acme',
+      displayName: 'Jira Acme',
+    });
+    await upsertJiraInstallation({
+      connectionId: connection.id,
+      cloudId,
+      siteUrl: 'https://acme.atlassian.net',
+      siteName: 'Acme',
+      authorizingAccountId: 'user-1',
+      scopes: ['read:jira-work'],
+      status: 'installed',
+    });
+
+    return {connection, deleteSecrets, jiraPart, cloudId};
+  }
+
   it('loads its database descriptor and persists a core connection with its Jira installation', async () => {
     vi.stubEnv('INTEGRATIONS_ENABLE_JIRA_PROVIDER', 'true');
     vi.resetModules();
@@ -59,4 +108,88 @@ describe('jiraProviderModule', () => {
       cloudId,
     });
   });
+
+  it('waits for refresh before deleting tokens and allowing a reinstall', async () => {
+    const {cloudId, connection, deleteSecrets, jiraPart} = await createJiraCleanupFixture();
+    const app = await createTestApp([jiraPart.provider]);
+
+    let releaseRefreshLock!: () => void;
+    let refreshLockEntered!: () => void;
+    const refreshLockReady = new Promise<void>((resolve) => {
+      refreshLockEntered = resolve;
+    });
+    const refreshLockReleased = new Promise<void>((resolve) => {
+      releaseRefreshLock = resolve;
+    });
+    const refreshLock = withJiraRefreshLock(connection.id, async () => {
+      refreshLockEntered();
+      await refreshLockReleased;
+    });
+    await refreshLockReady;
+
+    const deletion = app.inject({
+      method: 'DELETE',
+      url: `/integration-connections/${connection.id}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    await vi.waitFor(async () => {
+      await expect(getIntegrationConnectionById(connection.id)).resolves.toBeUndefined();
+    });
+    let res!: Awaited<ReturnType<typeof app.inject>>;
+    try {
+      expect(deleteSecrets).not.toHaveBeenCalled();
+    } finally {
+      releaseRefreshLock();
+      await expect(refreshLock).resolves.toMatchObject({acquired: true});
+      res = await deletion;
+    }
+
+    expect(res.statusCode).toBe(204);
+    await expect(getIntegrationConnectionById(connection.id)).resolves.toBeUndefined();
+    await expect(getJiraInstallationByConnectionId(connection.id)).resolves.toBeUndefined();
+    expect(deleteSecrets).toHaveBeenCalledWith({
+      workspaceId: context.workspaceId,
+      namespace: connection.id,
+    });
+
+    const replacement = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'jira',
+      externalAccountId: cloudId,
+      slug: 'jira_acme_again',
+      displayName: 'Jira Acme',
+    });
+    await upsertJiraInstallation({
+      connectionId: replacement.id,
+      cloudId,
+      siteUrl: 'https://acme.atlassian.net',
+      siteName: 'Acme',
+      authorizingAccountId: 'user-1',
+      scopes: ['read:jira-work'],
+      status: 'installed',
+    });
+
+    await expect(getJiraInstallationByConnectionId(replacement.id)).resolves.toMatchObject({
+      cloudId,
+    });
+  });
+
+  it('rolls back provider record cleanup when its transaction fails', async () => {
+    const {connection, jiraPart} = await createJiraCleanupFixture();
+
+    await expect(
+      db().transaction(async (tx) => {
+        await jiraPart.provider.deleteConnectionRecords?.(connection, {tx});
+        throw new Error('transaction failed');
+      }),
+    ).rejects.toThrow('transaction failed');
+
+    await expect(getIntegrationConnectionById(connection.id)).resolves.toMatchObject({
+      id: connection.id,
+    });
+    await expect(getJiraInstallationByConnectionId(connection.id)).resolves.toMatchObject({
+      connectionId: connection.id,
+    });
+  });
 });

package/src/providers/jira.ts

@@ -30,10 +30,13 @@ async function loadJiraModuleParts(
     createJiraPendingSelectionStore,
     createJiraTokenStore,
     db: jiraDb,
+    deleteJiraInstallationByConnectionId,
     disconnectJiraInstallation: disconnectJiraInstallationRecords,
     getJiraInstallationByCloudId,
+    jiraSecretsNamespace,
     migrationsPath,
     upsertJiraInstallation,
+    withJiraRefreshLockAndWait,
   } = await import('@shipfox/api-integration-jira');
 
   async function getExistingJiraConnection(input: {
@@ -144,6 +147,20 @@ async function loadJiraModuleParts(
 
   const integrationProvider = createJiraIntegrationProvider({
     agentTools: {tokenStore},
+    cleanup: {
+      deleteConnectionRecords: async (connection, {tx}) => {
+        await deleteJiraInstallationByConnectionId(connection.id, {tx});
+      },
+      deleteConnectionSecrets: async (connection) => {
+        await withJiraRefreshLockAndWait(connection.id, async () => {
+          // Scoped secrets accept the provider-local suffix, after this helper validates its prefix.
+          await (options.secrets?.jira?.deleteSecrets({
+            workspaceId: connection.workspaceId,
+            namespace: jiraNamespaceSuffix(jiraSecretsNamespace(connection.id)),
+          }) ?? Promise.resolve());
+        });
+      },
+    },
     routes: {
       tokenStore,
       pendingStore,