@shipfox/api-integration-core 3.0.0 → 5.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-core",
   "license": "MIT",
-  "version": "3.0.0",
+  "version": "5.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -13,22 +13,12 @@
   "types": "dist/index.d.ts",
   "imports": {
     "#test/*": "./test/*",
-    "#*": {
-      "workspace-source": "./src/*",
-      "development": "./src/*",
-      "default": "./dist/*"
-    }
+    "#*": "./dist/*"
   },
   "exports": {
     ".": {
-      "development": {
-        "types": "./src/index.ts",
-        "default": "./src/index.ts"
-      },
-      "default": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "dependencies": {
@@ -37,24 +27,26 @@
     "ajv": "^8.20.0",
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
-    "@shipfox/api-agent-dto": "3.0.0",
-    "@shipfox/api-auth-context": "3.0.0",
-    "@shipfox/api-integration-core-dto": "3.0.0",
-    "@shipfox/api-integration-gitea": "3.0.0",
-    "@shipfox/api-integration-github": "3.0.0",
-    "@shipfox/api-integration-linear": "3.0.0",
-    "@shipfox/api-integration-sentry": "3.0.0",
-    "@shipfox/api-integration-webhook": "3.0.0",
-    "@shipfox/config": "1.2.1",
-    "@shipfox/node-drizzle": "0.2.1",
-    "@shipfox/node-fastify": "0.2.2",
-    "@shipfox/node-module": "0.3.0",
-    "@shipfox/node-opentelemetry": "0.5.1",
-    "@shipfox/node-outbox": "0.2.1",
-    "@shipfox/node-postgres": "0.4.1",
-    "@shipfox/node-temporal": "0.3.0",
-    "@shipfox/regex": "0.2.1",
-    "@shipfox/redact": "0.2.1"
+    "@shipfox/api-agent-dto": "5.0.0",
+    "@shipfox/api-auth-context": "5.0.0",
+    "@shipfox/api-integration-core-dto": "5.0.0",
+    "@shipfox/api-integration-gitea": "5.0.0",
+    "@shipfox/api-integration-github": "5.0.0",
+    "@shipfox/api-integration-jira": "5.0.0",
+    "@shipfox/api-integration-linear": "5.0.0",
+    "@shipfox/api-integration-sentry": "5.0.0",
+    "@shipfox/api-integration-slack": "5.0.0",
+    "@shipfox/api-integration-webhook": "5.0.0",
+    "@shipfox/config": "1.2.2",
+    "@shipfox/node-drizzle": "0.3.1",
+    "@shipfox/node-fastify": "0.2.3",
+    "@shipfox/node-module": "0.3.2",
+    "@shipfox/node-opentelemetry": "0.5.2",
+    "@shipfox/node-outbox": "0.2.3",
+    "@shipfox/node-postgres": "0.4.2",
+    "@shipfox/node-temporal": "0.3.1",
+    "@shipfox/regex": "0.2.2",
+    "@shipfox/redact": "0.2.2"
   },
   "devDependencies": {
     "@temporalio/activity": "1.18.1",
@@ -67,11 +59,11 @@
     "fastify": "^5.3.3",
     "fastify-type-provider-zod": "^6.0.0",
     "fishery": "^2.4.0",
-    "@shipfox/biome": "1.8.1",
-    "@shipfox/swc": "1.2.5",
+    "@shipfox/biome": "1.8.2",
+    "@shipfox/swc": "1.2.6",
     "@shipfox/ts-config": "1.3.8",
-    "@shipfox/typescript": "1.1.6",
-    "@shipfox/vitest": "1.2.2"
+    "@shipfox/typescript": "1.1.7",
+    "@shipfox/vitest": "1.2.3"
   },
   "scripts": {
     "build": "shipfox-swc && shipfox-temporal-bundle dist/temporal/workflows/index.js",

package/src/config.ts

@@ -13,6 +13,10 @@ export const config = createConfig({
     desc: 'Enables the GitHub integration provider so users can connect GitHub.',
     default: false,
   }),
+  INTEGRATIONS_ENABLE_JIRA_PROVIDER: bool({
+    desc: 'Enables the Jira integration provider so users can connect Jira sites.',
+    default: false,
+  }),
   INTEGRATIONS_ENABLE_LINEAR_PROVIDER: bool({
     desc: 'Enables the Linear integration provider so users can connect Linear workspaces.',
     default: false,
@@ -21,6 +25,10 @@ export const config = createConfig({
     desc: 'Enables the Sentry integration provider so users can connect Sentry.',
     default: false,
   }),
+  INTEGRATIONS_ENABLE_SLACK_PROVIDER: bool({
+    desc: 'Enables the Slack integration provider so users can connect Slack workspaces.',
+    default: false,
+  }),
   INTEGRATIONS_ENABLE_WEBHOOK_PROVIDER: bool({
     desc: 'Enables the generic webhook integration provider so users can create inbound webhook URLs. It is enabled by default because it does not require provider setup.',
     default: true,

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

@@ -9,6 +9,7 @@ import {db} from './db.js';
 import {integrationsOutbox} from './schema/outbox.js';
 import {integrationsWebhookDeliveries} from './schema/webhook-deliveries.js';
 import {
+  claimWebhookDelivery,
   publishIntegrationEventReceived,
   publishSourceCommitPushed,
   publishSourcePush,
@@ -165,6 +166,16 @@ describe('integration webhook delivery persistence', () => {
 
     expect(await deliveriesFor('github', deliveryId)).toHaveLength(1);
   });
+
+  it('reports whether it claimed a delivery', async () => {
+    const deliveryId = crypto.randomUUID();
+
+    const first = await claimWebhookDelivery({tx: db(), provider: 'github', deliveryId});
+    const duplicate = await claimWebhookDelivery({tx: db(), provider: 'github', deliveryId});
+
+    expect(first.claimed).toBe(true);
+    expect(duplicate.claimed).toBe(false);
+  });
 });
 
 describe('publishSourcePush', () => {

package/src/db/webhook-deliveries.ts

@@ -171,8 +171,10 @@ export interface RecordDeliveryOnlyParams {
   deliveryId: string;
 }
 
-export async function recordDeliveryOnly(params: RecordDeliveryOnlyParams): Promise<void> {
-  await params.tx
+export async function claimWebhookDelivery(
+  params: RecordDeliveryOnlyParams,
+): Promise<{claimed: boolean}> {
+  const inserted = await params.tx
     .insert(integrationsWebhookDeliveries)
     .values({
       provider: params.provider,
@@ -185,7 +187,13 @@ export async function recordDeliveryOnly(params: RecordDeliveryOnlyParams): Prom
         integrationsWebhookDeliveries.dedupScope,
         integrationsWebhookDeliveries.deliveryId,
       ],
-    });
+    })
+    .returning({deliveryId: integrationsWebhookDeliveries.deliveryId});
+  return {claimed: inserted.length > 0};
+}
+
+export async function recordDeliveryOnly(params: RecordDeliveryOnlyParams): Promise<void> {
+  await claimWebhookDelivery(params);
 }
 
 export interface PruneWebhookDeliveriesParams {
@@ -204,4 +212,5 @@ export async function pruneWebhookDeliveries(
 export type PublishIntegrationEventReceivedFn = typeof publishIntegrationEventReceived;
 export type PublishSourcePushFn = typeof publishSourcePush;
 export type PublishSourceCommitPushedFn = typeof publishSourceCommitPushed;
+export type ClaimWebhookDeliveryFn = typeof claimWebhookDelivery;
 export type RecordDeliveryOnlyFn = typeof recordDeliveryOnly;

package/src/index.ts

@@ -98,6 +98,7 @@ export {createSourceControlIntegrationService} from '#core/source-control-servic
 export type {GetIntegrationConnectionByIdFn} from '#db/connections.js';
 export {getIntegrationConnectionById} from '#db/connections.js';
 export type {
+  ClaimWebhookDeliveryFn,
   PublishIntegrationEventReceivedFn,
   PublishIntegrationEventReceivedParams,
   PublishIntegrationEventReceivedResult,
@@ -106,7 +107,7 @@ export type {
   RecordDeliveryOnlyFn,
   RecordDeliveryOnlyParams,
 } from '#db/webhook-deliveries.js';
-export {pruneWebhookDeliveries} from '#db/webhook-deliveries.js';
+export {claimWebhookDelivery, pruneWebhookDeliveries} from '#db/webhook-deliveries.js';
 export {integrationRouteErrorHandler} from '#presentation/routes/errors.js';
 
 export interface CreateIntegrationsModuleOptions {

package/src/presentation/routes/index.ts

@@ -45,7 +45,7 @@ export function createIntegrationRoutes(
     createListIntegrationProvidersRoute(registry),
     createListIntegrationConnectionsRoute(registry),
     createUpdateIntegrationConnectionRoute(registry),
-    createDeleteIntegrationConnectionRoute(),
+    createDeleteIntegrationConnectionRoute(registry),
     createListRepositoriesRoute(sourceControl),
     ...agentToolsRoutes,
     ...providerRoutes,

package/src/presentation/routes/manage-connections.test.ts

@@ -110,6 +110,119 @@ describe('DELETE /integration-connections/:connectionId', () => {
     expect(reloaded).toBeUndefined();
   });
 
+  it('runs provider cleanup hooks while retaining ownership of the core row', async () => {
+    const deleteConnectionRecords = vi.fn(() => Promise.resolve());
+    const deleteConnectionSecrets = vi.fn(() => Promise.resolve());
+    const app = await createTestApp([
+      sourceProvider({
+        provider: 'slack',
+        displayName: 'Slack',
+        adapters: {},
+        deleteConnectionRecords,
+        deleteConnectionSecrets,
+      }),
+    ]);
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'slack',
+      externalAccountId: 'T123',
+      slug: 'slack_acme',
+      displayName: 'Slack Acme',
+    });
+
+    const res = await app.inject({
+      method: 'DELETE',
+      url: `/integration-connections/${connection.id}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(204);
+    expect(deleteConnectionRecords).toHaveBeenCalledWith(connection, {
+      tx: expect.anything(),
+    });
+    expect(deleteConnectionSecrets).toHaveBeenCalledWith(connection);
+    await expect(getIntegrationConnectionById(connection.id)).resolves.toBeUndefined();
+  });
+
+  it('keeps the connection when provider record cleanup fails', async () => {
+    const deleteConnectionSecrets = vi.fn(() => Promise.resolve());
+    const app = await createTestApp([
+      sourceProvider({
+        provider: 'slack',
+        displayName: 'Slack',
+        adapters: {},
+        deleteConnectionRecords: () => Promise.reject(new Error('record cleanup failed')),
+        deleteConnectionSecrets,
+      }),
+    ]);
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'slack',
+      externalAccountId: 'T123',
+      slug: 'slack_acme',
+      displayName: 'Slack Acme',
+    });
+
+    const res = await app.inject({
+      method: 'DELETE',
+      url: `/integration-connections/${connection.id}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(500);
+    await expect(getIntegrationConnectionById(connection.id)).resolves.toMatchObject({
+      id: connection.id,
+    });
+    expect(deleteConnectionSecrets).not.toHaveBeenCalled();
+  });
+
+  it('deletes the connection when provider secret cleanup fails after commit', async () => {
+    const app = await createTestApp([
+      sourceProvider({
+        provider: 'slack',
+        displayName: 'Slack',
+        adapters: {},
+        deleteConnectionSecrets: () => Promise.reject(new Error('secret cleanup failed')),
+      }),
+    ]);
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'slack',
+      externalAccountId: 'T123',
+      slug: 'slack_acme',
+      displayName: 'Slack Acme',
+    });
+
+    const res = await app.inject({
+      method: 'DELETE',
+      url: `/integration-connections/${connection.id}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(204);
+    await expect(getIntegrationConnectionById(connection.id)).resolves.toBeUndefined();
+  });
+
+  it('deletes an unregistered provider connection without provider cleanup', async () => {
+    const app = await createTestApp([]);
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'slack',
+      externalAccountId: 'T123',
+      slug: 'slack_acme',
+      displayName: 'Slack Acme',
+    });
+
+    const res = await app.inject({
+      method: 'DELETE',
+      url: `/integration-connections/${connection.id}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(204);
+    await expect(getIntegrationConnectionById(connection.id)).resolves.toBeUndefined();
+  });
+
   it('returns not-found for a missing connection', async () => {
     const app = await createTestApp([sourceProvider()]);
 

package/src/presentation/routes/manage-connections.ts

@@ -11,6 +11,7 @@ import {
   getIntegrationConnectionById,
   updateIntegrationConnectionLifecycleStatus,
 } from '#db/connections.js';
+import {db} from '#db/db.js';
 import {toIntegrationConnectionDto} from '#presentation/dto/integrations.js';
 
 const connectionParamsSchema = z.object({
@@ -51,7 +52,7 @@ export function createUpdateIntegrationConnectionRoute(registry: IntegrationProv
   });
 }
 
-export function createDeleteIntegrationConnectionRoute() {
+export function createDeleteIntegrationConnectionRoute(registry: IntegrationProviderRegistry) {
   return defineRoute({
     method: 'DELETE',
     path: '/integration-connections/:connectionId',
@@ -70,7 +71,30 @@ export function createDeleteIntegrationConnectionRoute() {
       }
 
       requireWorkspaceAccess({request, workspaceId: connection.workspaceId});
-      await deleteIntegrationConnection({id: connection.id});
+      const provider = registry
+        .list()
+        .find((candidate) => candidate.provider === connection.provider);
+      const hasCleanupHooks =
+        provider?.deleteConnectionRecords !== undefined ||
+        provider?.deleteConnectionSecrets !== undefined;
+      if (!hasCleanupHooks) {
+        request.log.warn(
+          {connectionId: connection.id, provider: connection.provider},
+          'Deleting integration connection without provider cleanup',
+        );
+      }
+      await db().transaction(async (tx) => {
+        await provider?.deleteConnectionRecords?.(connection, {tx});
+        await deleteIntegrationConnection({id: connection.id}, {tx});
+      });
+      try {
+        await provider?.deleteConnectionSecrets?.(connection);
+      } catch (error) {
+        request.log.error(
+          {connectionId: connection.id, provider: connection.provider, err: error},
+          'Integration connection secret cleanup failed after connection deletion',
+        );
+      }
       reply.status(204);
     },
   });

package/src/providers/jira.test.ts

@@ -0,0 +1,57 @@
+import {
+  getJiraInstallationByConnectionId,
+  upsertJiraInstallation,
+} from '@shipfox/api-integration-jira';
+import {runMigrations} from '@shipfox/node-drizzle';
+import {getIntegrationConnectionById, upsertIntegrationConnection} from '#db/connections.js';
+
+describe('jiraProviderModule', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it('loads its database descriptor and persists a core connection with its Jira installation', async () => {
+    vi.stubEnv('INTEGRATIONS_ENABLE_JIRA_PROVIDER', 'true');
+    vi.resetModules();
+    const {createPostgresClient} = await import('@shipfox/node-postgres');
+    createPostgresClient();
+    const {loadEnabledProviderModules} = await import('#providers/modules.js');
+    const parts = await loadEnabledProviderModules();
+    const jiraPart = parts.find((part) => part.provider.provider === 'jira');
+    if (!jiraPart?.database) throw new Error('Jira provider database is not configured');
+    const workspaceId = crypto.randomUUID();
+    const cloudId = crypto.randomUUID();
+
+    await runMigrations(
+      jiraPart.database.db(),
+      jiraPart.database.migrationsPath,
+      jiraPart.database.migrationsTableName,
+    );
+    const connection = await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'jira',
+      externalAccountId: cloudId,
+      slug: `jira_${cloudId}`,
+      displayName: 'Jira Acme',
+    });
+    await upsertJiraInstallation({
+      connectionId: connection.id,
+      cloudId,
+      siteUrl: 'https://acme.atlassian.net',
+      siteName: 'Acme',
+      authorizingAccountId: crypto.randomUUID(),
+      scopes: ['read:jira-work'],
+      status: 'installed',
+    });
+
+    await expect(getIntegrationConnectionById(connection.id)).resolves.toMatchObject({
+      id: connection.id,
+      provider: 'jira',
+    });
+    await expect(getJiraInstallationByConnectionId(connection.id)).resolves.toMatchObject({
+      connectionId: connection.id,
+      cloudId,
+    });
+  });
+});

package/src/providers/jira.ts

@@ -0,0 +1,172 @@
+import {
+  type IntegrationConnection as CoreIntegrationConnection,
+  slugifyConnectionSlug,
+} from '@shipfox/api-integration-core-dto';
+import type {
+  ConnectJiraInstallationInput,
+  JiraPendingSelectionSecretsStore,
+  JiraSecretsStore,
+} from '@shipfox/api-integration-jira';
+import {config} from '#config.js';
+import {
+  deleteIntegrationConnection,
+  getIntegrationConnectionById,
+  resolveUniqueConnectionSlug,
+  updateIntegrationConnectionLifecycleStatus,
+  upsertIntegrationConnection,
+} from '#db/connections.js';
+import {db} from '#db/db.js';
+import {retryConnectionSlugCollision} from '#providers/connection-slug.js';
+import type {IntegrationModuleParts, IntegrationProviderModule} from '#providers/types.js';
+
+const JIRA_MIGRATIONS_TABLE = '__drizzle_migrations_integrations_jira';
+const JIRA_SECRETS_NAMESPACE_PREFIX = 'system/integrations/jira/';
+type IntegrationDb = ReturnType<typeof db>;
+type IntegrationTx = Parameters<Parameters<IntegrationDb['transaction']>[0]>[0];
+
+async function loadJiraModuleParts(
+  options: Parameters<IntegrationProviderModule['load']>[0] = {},
+): Promise<IntegrationModuleParts> {
+  const {
+    createJiraIntegrationProvider,
+    createJiraPendingSelectionStore,
+    createJiraTokenStore,
+    db: jiraDb,
+    disconnectJiraInstallation: disconnectJiraInstallationRecords,
+    getJiraInstallationByCloudId,
+    migrationsPath,
+    upsertJiraInstallation,
+  } = await import('@shipfox/api-integration-jira');
+
+  async function getExistingJiraConnection(input: {
+    cloudId: string;
+  }): Promise<CoreIntegrationConnection<'jira'> | undefined> {
+    const installation = await getJiraInstallationByCloudId(input.cloudId);
+    if (!installation) return undefined;
+    return (await getIntegrationConnectionById(installation.connectionId)) as
+      | CoreIntegrationConnection<'jira'>
+      | undefined;
+  }
+
+  function connectJiraInstallation(
+    input: ConnectJiraInstallationInput,
+  ): Promise<CoreIntegrationConnection<'jira'>> {
+    return retryConnectionSlugCollision(() =>
+      db().transaction(async (tx) => {
+        const slug = await resolveUniqueConnectionSlug(
+          {
+            workspaceId: input.workspaceId,
+            provider: 'jira',
+            externalAccountId: input.cloudId,
+            baseSlug: slugifyConnectionSlug(`jira_${input.siteName || input.cloudId}`, {
+              fallback: 'jira',
+            }),
+          },
+          {tx},
+        );
+        const connection = await upsertIntegrationConnection(
+          {
+            workspaceId: input.workspaceId,
+            provider: 'jira',
+            externalAccountId: input.cloudId,
+            slug,
+            displayName: input.displayName,
+            lifecycleStatus: 'active',
+          },
+          {tx},
+        );
+        await upsertJiraInstallation(
+          {
+            connectionId: connection.id,
+            cloudId: input.cloudId,
+            siteUrl: input.siteUrl,
+            siteName: input.siteName,
+            authorizingAccountId: input.authorizingAccountId,
+            scopes: input.scopes,
+            status: 'installed',
+            tokenExpiresAt: input.tokenExpiresAt,
+          },
+          {tx},
+        );
+        return connection as CoreIntegrationConnection<'jira'>;
+      }),
+    );
+  }
+
+  async function disconnectJiraInstallation(input: {connectionId: string}): Promise<void> {
+    await disconnectJiraInstallationRecords<IntegrationTx>({
+      connectionId: input.connectionId,
+      getConnection: getIntegrationConnectionById,
+      deleteSecrets: (params) =>
+        options.secrets?.jira?.deleteSecrets({
+          ...params,
+          namespace: jiraNamespaceSuffix(params.namespace),
+        }) ?? Promise.resolve(0),
+      transaction: (fn) => db().transaction((tx) => fn(tx)),
+      deleteConnection: (params, transactionOptions) =>
+        deleteIntegrationConnection({id: params.connectionId}, transactionOptions),
+    });
+  }
+
+  const fallbackSecrets: JiraSecretsStore & JiraPendingSelectionSecretsStore = {
+    getSecret: () => Promise.resolve(null),
+    setSecrets: () => Promise.reject(new Error('Jira token storage is not configured')),
+    deleteSecrets: () => Promise.resolve(0),
+  };
+  const secrets: JiraSecretsStore & JiraPendingSelectionSecretsStore = options.secrets?.jira
+    ? {
+        getSecret: (params) =>
+          options.secrets?.jira?.getSecret({
+            ...params,
+            namespace: jiraNamespaceSuffix(params.namespace),
+          }) ?? Promise.resolve(null),
+        setSecrets: (params) =>
+          options.secrets?.jira?.setSecrets({
+            ...params,
+            namespace: jiraNamespaceSuffix(params.namespace),
+          }) ?? Promise.resolve(),
+        deleteSecrets: (params) =>
+          options.secrets?.jira?.deleteSecrets({
+            ...params,
+            namespace: jiraNamespaceSuffix(params.namespace),
+          }) ?? Promise.resolve(0),
+      }
+    : fallbackSecrets;
+  const tokenStore = createJiraTokenStore({
+    resolveConnection: getIntegrationConnectionById,
+    secrets,
+    markConnectionError: async ({connectionId}) => {
+      await updateIntegrationConnectionLifecycleStatus({
+        id: connectionId,
+        lifecycleStatus: 'error',
+      });
+    },
+  });
+  const pendingStore = createJiraPendingSelectionStore({secrets});
+
+  return {
+    provider: createJiraIntegrationProvider({
+      routes: {
+        tokenStore,
+        pendingStore,
+        getExistingJiraConnection,
+        connectJiraInstallation,
+        disconnectJiraInstallation,
+      },
+    }),
+    database: {db: jiraDb, migrationsPath, migrationsTableName: JIRA_MIGRATIONS_TABLE},
+  };
+}
+
+export const jiraProviderModule: IntegrationProviderModule = {
+  id: 'jira',
+  enabled: config.INTEGRATIONS_ENABLE_JIRA_PROVIDER,
+  load: loadJiraModuleParts,
+};
+
+function jiraNamespaceSuffix(namespace: string): string {
+  if (!namespace.startsWith(JIRA_SECRETS_NAMESPACE_PREFIX)) {
+    throw new Error('Jira provider attempted to access an unscoped secret namespace');
+  }
+  return namespace.slice(JIRA_SECRETS_NAMESPACE_PREFIX.length);
+}