@shipfox/api-integration-core 4.0.0 → 6.0.0

package/src/presentation/inter-module.ts

@@ -0,0 +1,155 @@
+import {integrationsInterModuleContract} from '@shipfox/api-integration-core-dto';
+import {
+  createInterModuleKnownError,
+  defineInterModulePresentation,
+  type InterModuleMethodContract,
+  type InterModulePresentation,
+} from '@shipfox/inter-module';
+import {
+  buildAgentToolCatalogs,
+  buildAgentToolSelectionCatalogs,
+  createWorkspaceConnectionSnapshotLoader,
+} from '#core/agent-tool-selection.js';
+import {
+  IntegrationCapabilityUnavailableError,
+  IntegrationCheckoutUnsupportedError,
+  IntegrationConnectionInactiveError,
+  IntegrationConnectionNotFoundError,
+  IntegrationConnectionWorkspaceMismatchError,
+  IntegrationProviderError,
+  IntegrationProviderUnavailableError,
+} from '#core/errors.js';
+import type {IntegrationProviderRegistry} from '#core/providers/registry.js';
+import type {IntegrationSourceControlService} from '#core/source-control-service.js';
+import {getIntegrationConnectionById} from '#db/connections.js';
+
+export function createIntegrationsInterModulePresentation(params: {
+  registry: IntegrationProviderRegistry;
+  sourceControl: IntegrationSourceControlService;
+}): InterModulePresentation<typeof integrationsInterModuleContract> {
+  const contract = integrationsInterModuleContract;
+  return defineInterModulePresentation(contract, {
+    resolveSourceRepository: async (input) =>
+      await known(contract.methods.resolveSourceRepository, input, async () => {
+        const resolved = await params.sourceControl.resolveRepository(input);
+        return {
+          connection: {
+            id: resolved.connection.id,
+            provider: resolved.connection.provider,
+            slug: resolved.connection.slug,
+          },
+          repository: resolved.repository,
+        };
+      }),
+    listSourceFiles: async (input) =>
+      await known(
+        contract.methods.listSourceFiles,
+        input,
+        async () => await params.sourceControl.listFiles(input),
+      ),
+    fetchSourceFile: async (input) =>
+      await known(
+        contract.methods.fetchSourceFile,
+        input,
+        async () => await params.sourceControl.fetchFile(input),
+      ),
+    createCheckoutSpec: async (input) =>
+      await known(contract.methods.createCheckoutSpec, input, async () => {
+        const spec = await params.sourceControl.createCheckoutSpec(input);
+        return {
+          repositoryUrl: spec.repositoryUrl,
+          ref: spec.ref,
+          ...(spec.credentials
+            ? {
+                credentials: {
+                  ...spec.credentials,
+                  expiresAt: spec.credentials.expiresAt.toISOString(),
+                },
+              }
+            : {}),
+          ...(spec.gitAuthor === undefined ? {} : {gitAuthor: spec.gitAuthor}),
+        };
+      }),
+    getAgentToolsContext: async (input) =>
+      await known(contract.methods.getAgentToolsContext, input, async () => {
+        const [selectionCatalogs, catalogs, snapshot, defaultConnection] = await Promise.all([
+          buildAgentToolSelectionCatalogs(params.registry),
+          buildAgentToolCatalogs(params.registry),
+          createWorkspaceConnectionSnapshotLoader(params.registry)(input.workspaceId),
+          getIntegrationConnectionById(input.defaultConnectionId),
+        ]);
+        return {
+          selectionCatalogs: [...selectionCatalogs].map(([provider, value]) => ({
+            provider,
+            selectors: value.selectors.map((selector) => ({...selector})),
+          })),
+          catalogs: [...catalogs].map(([provider, tools]) => ({
+            provider,
+            tools: tools.map(({methods, ...tool}) => ({
+              ...tool,
+              ...(methods === undefined ? {} : {methods: methods.map((method) => ({...method}))}),
+            })),
+          })),
+          workspaceConnections: [...snapshot].map(([slug, value]) => ({
+            slug,
+            ...value,
+            capabilities: [...value.capabilities],
+          })),
+          defaultConnection: defaultConnection
+            ? {
+                id: defaultConnection.id,
+                slug: defaultConnection.slug,
+                provider: defaultConnection.provider,
+              }
+            : null,
+        };
+      }),
+  });
+}
+
+async function known<Output>(
+  method: InterModuleMethodContract,
+  input: {connectionId?: string; defaultConnectionId?: string},
+  operation: () => Promise<Output>,
+): Promise<Output> {
+  try {
+    return await operation();
+  } catch (error) {
+    throw mapError(method, input, error);
+  }
+}
+function mapError(
+  method: InterModuleMethodContract,
+  input: {connectionId?: string; defaultConnectionId?: string},
+  error: unknown,
+): unknown {
+  if (error instanceof IntegrationConnectionNotFoundError)
+    return createInterModuleKnownError(method, 'connection-not-found', {
+      connectionId: input.connectionId ?? input.defaultConnectionId,
+    });
+  if (error instanceof IntegrationConnectionInactiveError)
+    return createInterModuleKnownError(method, 'connection-inactive', {
+      connectionId: input.connectionId,
+    });
+  if (error instanceof IntegrationConnectionWorkspaceMismatchError)
+    return createInterModuleKnownError(method, 'connection-workspace-mismatch', {
+      connectionId: input.connectionId,
+    });
+  if (error instanceof IntegrationProviderUnavailableError)
+    return createInterModuleKnownError(method, 'provider-unavailable', {provider: error.provider});
+  if (error instanceof IntegrationCapabilityUnavailableError)
+    return createInterModuleKnownError(method, 'capability-unavailable', {
+      provider: error.provider,
+      capability: error.capability,
+    });
+  if (error instanceof IntegrationCheckoutUnsupportedError)
+    return createInterModuleKnownError(method, 'checkout-unsupported', {provider: error.provider});
+  if (error instanceof IntegrationProviderError)
+    return createInterModuleKnownError(method, 'provider-failure', {
+      reason: error.reason,
+      ...(error.retryAfterSeconds === undefined
+        ? {}
+        : {retryAfterSeconds: error.retryAfterSeconds}),
+    });
+  return error;
+}

package/src/presentation/routes/agent-tools-gateway/index.ts

@@ -13,6 +13,7 @@ import {
 } from './resolve-authorized-tools.js';
 
 export type {LeasedAgentStepLoader} from './resolve-authorized-tools.js';
+export {createWorkflowsLeasedAgentStepLoader} from './resolve-authorized-tools.js';
 
 export interface CreateAgentToolsGatewayRoutesParams {
   loadLeasedAgentStep: LeasedAgentStepLoader;

package/src/presentation/routes/agent-tools-gateway/resolve-authorized-tools.test.ts

@@ -1,4 +1,6 @@
 import {setLeasedJobContext} from '@shipfox/api-auth-context';
+import {workflowsInterModuleContract} from '@shipfox/api-workflows-dto/inter-module';
+import {createInterModuleKnownError} from '@shipfox/inter-module';
 import {createIntegrationProviderRegistry} from '#core/providers/registry.js';
 import {
   agentStepConfig,
@@ -9,6 +11,7 @@ import {
   registryWithAgentTools,
 } from '#test/agent-tools-gateway-helpers.js';
 import {
+  createWorkflowsLeasedAgentStepLoader,
   mcpToolName,
   narrowMethodEnum,
   resolveAuthorizedIntegrationTools,
@@ -16,6 +19,39 @@ import {
 } from './resolve-authorized-tools.js';
 
 describe('resolveAuthorizedIntegrationTools', () => {
+  it.each([
+    ['lease-not-active', 404],
+    ['step-not-found', 404],
+    ['job-not-found', 404],
+    ['step-attempt-mismatch', 409],
+    ['step-not-running', 409],
+    ['leased-step-not-agent', 409],
+    ['agent-step-config-invalid', 409],
+  ] as const)('maps %s from Workflows to HTTP %i', async (code, status) => {
+    const request = {};
+    const lease = leaseContext();
+    setLeasedJobContext(request, lease);
+    const workflows = {
+      getLeasedAgentToolContext: () =>
+        Promise.reject(
+          createInterModuleKnownError(
+            workflowsInterModuleContract.methods.getLeasedAgentToolContext,
+            code,
+            {},
+          ),
+        ),
+    };
+    const loadLeasedAgentStep = createWorkflowsLeasedAgentStepLoader(workflows as never);
+
+    const error = await loadLeasedAgentStep({
+      request,
+      stepId: lease.currentStepId as string,
+      attempt: lease.currentStepAttempt as number,
+    }).catch((error: unknown) => error);
+
+    expect(error).toMatchObject({code, status});
+  });
+
   it('resolves namespaced tools with live descriptions and Anthropic-compatible method schemas', async () => {
     const request = {};
     const lease = leaseContext();

package/src/presentation/routes/agent-tools-gateway/resolve-authorized-tools.ts

@@ -4,6 +4,11 @@ import {
   materializedAgentStepConfigSchema,
 } from '@shipfox/api-agent-dto';
 import {requireLeasedJobContext} from '@shipfox/api-auth-context';
+import {
+  type WorkflowsModuleClient,
+  workflowsInterModuleContract,
+} from '@shipfox/api-workflows-dto/inter-module';
+import {isInterModuleKnownError} from '@shipfox/inter-module';
 import {ClientError} from '@shipfox/node-fastify';
 import type {IntegrationConnection} from '#core/entities/connection.js';
 import type {IntegrationProviderKind} from '#core/entities/provider.js';
@@ -16,10 +21,49 @@ export type LeasedAgentStepLoader = (params: {
   stepId: string;
   attempt: number;
 }) => Promise<{
-  step: {type: string; config: Record<string, unknown>};
   workspaceId: string;
+  integrations?: MaterializedAgentIntegrationConfigDto[];
+  step?: {type: string; config: Record<string, unknown>};
 }>;
 
+export function createWorkflowsLeasedAgentStepLoader(
+  workflows: WorkflowsModuleClient,
+): LeasedAgentStepLoader {
+  return async ({request, stepId, attempt}) => {
+    const leasedJob = requireLeasedJobContext(request);
+    try {
+      const context = await workflows.getLeasedAgentToolContext({
+        jobId: leasedJob.jobId,
+        jobExecutionId: leasedJob.jobExecutionId,
+        runnerSessionId: leasedJob.runnerSessionId,
+        stepId,
+        attempt,
+      });
+      return {
+        workspaceId: context.workspaceId,
+        integrations: context.integrations,
+      };
+    } catch (error) {
+      throw toLeasedAgentToolClientError(error);
+    }
+  };
+}
+
+function toLeasedAgentToolClientError(error: unknown): unknown {
+  const method = workflowsInterModuleContract.methods.getLeasedAgentToolContext;
+  if (!isInterModuleKnownError(method, error)) return error;
+
+  const status = [
+    'step-attempt-mismatch',
+    'step-not-running',
+    'leased-step-not-agent',
+    'agent-step-config-invalid',
+  ].includes(error.code)
+    ? 409
+    : 404;
+  return new ClientError(error.code.replaceAll('-', ' '), error.code, {status});
+}
+
 export interface AuthorizedIntegrationTool {
   mcpName: string;
   integration: MaterializedAgentIntegrationConfigDto;
@@ -49,18 +93,13 @@ export async function resolveAuthorizedIntegrationTools(
     });
   }
 
-  const {step, workspaceId} = await params.loadLeasedAgentStep({
+  const loaded = await params.loadLeasedAgentStep({
     request: params.request,
     stepId: leasedJob.currentStepId,
     attempt: leasedJob.currentStepAttempt,
   });
-  if (step.type !== 'agent') {
-    throw new ClientError('Current leased step is not an agent step', 'leased-step-not-agent', {
-      status: 409,
-    });
-  }
-
-  const integrations = parseAgentIntegrations(step.config);
+  const workspaceId = loaded.workspaceId;
+  const integrations = loaded.integrations ?? legacyIntegrations(loaded.step);
   const authorizedTools: AuthorizedIntegrationToolMap = new Map();
 
   for (const integration of integrations) {
@@ -102,6 +141,22 @@ export async function resolveAuthorizedIntegrationTools(
   return authorizedTools;
 }
 
+function legacyIntegrations(step: {type: string; config: Record<string, unknown>} | undefined) {
+  if (step?.type !== 'agent') {
+    throw new ClientError('Current leased step is not an agent step', 'leased-step-not-agent', {
+      status: 409,
+    });
+  }
+  try {
+    return materializedAgentStepConfigSchema.parse(step.config).integrations ?? [];
+  } catch (error) {
+    throw new ClientError('Agent step config is invalid', 'agent-step-config-invalid', {
+      status: 409,
+      cause: error,
+    });
+  }
+}
+
 export function sanitizeSlug(slug: string): string {
   return slug.replaceAll('-', '_');
 }
@@ -132,19 +187,6 @@ function toolInputSchema(tool: MaterializedAgentIntegrationToolConfigDto): Agent
   return narrowMethodEnum(tool.inputSchema, authorizedMethods);
 }
 
-function parseAgentIntegrations(
-  config: Record<string, unknown>,
-): MaterializedAgentIntegrationConfigDto[] {
-  try {
-    return materializedAgentStepConfigSchema.parse(config).integrations ?? [];
-  } catch (error) {
-    throw new ClientError('Agent step config is invalid', 'agent-step-config-invalid', {
-      status: 409,
-      cause: error,
-    });
-  }
-}
-
 async function loadAuthorizedConnection(params: {
   integration: MaterializedAgentIntegrationConfigDto;
   workspaceId: string;

package/src/presentation/routes/index.ts

@@ -1,10 +1,11 @@
+import type {WorkflowsModuleClient} from '@shipfox/api-workflows-dto/inter-module';
 import type {RouteExport} from '@shipfox/node-fastify';
 import type {IntegrationProviderRegistry} from '#core/providers/registry.js';
 import type {IntegrationSourceControlService} from '#core/source-control-service.js';
 import type {GetIntegrationConnectionByIdFn} from '#db/connections.js';
 import {
   createAgentToolsGatewayRoutes,
-  type LeasedAgentStepLoader,
+  createWorkflowsLeasedAgentStepLoader,
 } from './agent-tools-gateway/index.js';
 import {createListIntegrationConnectionsRoute} from './list-connections.js';
 import {createListIntegrationProvidersRoute} from './list-providers.js';
@@ -14,12 +15,10 @@ import {
   createUpdateIntegrationConnectionRoute,
 } from './manage-connections.js';
 
-export type {LeasedAgentStepLoader} from './agent-tools-gateway/index.js';
-
 export interface CreateIntegrationRoutesOptions {
   agentTools?:
     | {
-        loadLeasedAgentStep: LeasedAgentStepLoader;
+        workflows: WorkflowsModuleClient;
         getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
       }
     | undefined;
@@ -35,7 +34,7 @@ export function createIntegrationRoutes(
     ? [
         createAgentToolsGatewayRoutes({
           registry,
-          loadLeasedAgentStep: options.agentTools.loadLeasedAgentStep,
+          loadLeasedAgentStep: createWorkflowsLeasedAgentStepLoader(options.agentTools.workflows),
           getIntegrationConnectionById: options.agentTools.getIntegrationConnectionById,
         }),
       ]
@@ -45,7 +44,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/gitea.ts

@@ -79,15 +79,18 @@ async function loadGiteaModuleParts(): Promise<IntegrationModuleParts> {
     );
   }
 
+  const integrationProvider = createGiteaIntegrationProvider({
+    getExistingGiteaConnection,
+    connectGiteaConnection,
+    publishSourcePush,
+    recordDeliveryOnly,
+    getIntegrationConnectionById,
+    coreDb: db,
+  });
+
   return {
-    provider: createGiteaIntegrationProvider({
-      getExistingGiteaConnection,
-      connectGiteaConnection,
-      publishSourcePush,
-      recordDeliveryOnly,
-      getIntegrationConnectionById,
-      coreDb: db,
-    }),
+    provider: integrationProvider,
+    webhookProcessors: integrationProvider.webhookProcessors,
     database: {
       db: giteaDb,
       migrationsPath: giteaMigrationsPath,

package/src/providers/github.ts

@@ -116,18 +116,24 @@ async function loadGithubModuleParts(
     );
   }
 
+  const integrationProvider = createGithubIntegrationProvider({
+    getExistingGithubConnection,
+    connectGithubInstallation,
+    publishIntegrationEventReceived,
+    publishSourcePush,
+    recordDeliveryOnly,
+    getIntegrationConnectionById,
+    coreDb: db,
+    deleteSecrets: options.secrets?.deleteSecrets,
+    agentTools: {tokenProvider},
+    ...(options.requireActiveWorkspaceMembership
+      ? {requireActiveWorkspaceMembership: options.requireActiveWorkspaceMembership}
+      : {}),
+  });
+
   return {
-    provider: createGithubIntegrationProvider({
-      getExistingGithubConnection,
-      connectGithubInstallation,
-      publishIntegrationEventReceived,
-      publishSourcePush,
-      recordDeliveryOnly,
-      getIntegrationConnectionById,
-      coreDb: db,
-      deleteSecrets: options.secrets?.deleteSecrets,
-      agentTools: {tokenProvider},
-    }),
+    provider: integrationProvider,
+    webhookProcessors: integrationProvider.webhookProcessors,
     e2eRoutes: [
       createGithubE2eRoutes({
         getExistingGithubConnection,