@shipfox/api-integration-core 4.0.0 → 6.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-core",
   "license": "MIT",
-  "version": "4.0.0",
+  "version": "6.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,26 +27,29 @@
     "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": "4.0.0",
-    "@shipfox/api-integration-github": "4.0.0",
-    "@shipfox/api-integration-jira": "4.0.0",
-    "@shipfox/api-integration-linear": "4.0.0",
-    "@shipfox/api-integration-sentry": "4.0.0",
-    "@shipfox/api-integration-slack": "4.0.0",
-    "@shipfox/api-integration-webhook": "3.0.0",
-    "@shipfox/config": "1.2.1",
-    "@shipfox/node-drizzle": "0.3.0",
-    "@shipfox/node-fastify": "0.2.2",
-    "@shipfox/node-module": "0.3.1",
-    "@shipfox/node-opentelemetry": "0.5.1",
-    "@shipfox/node-outbox": "0.2.2",
-    "@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": "6.0.0",
+    "@shipfox/api-auth-context": "6.0.0",
+    "@shipfox/api-workflows-dto": "6.0.0",
+    "@shipfox/api-integration-core-dto": "6.0.0",
+    "@shipfox/api-workspaces-dto": "6.0.0",
+    "@shipfox/api-integration-gitea": "6.0.0",
+    "@shipfox/api-integration-github": "6.0.0",
+    "@shipfox/api-integration-jira": "6.0.0",
+    "@shipfox/api-integration-linear": "6.0.0",
+    "@shipfox/api-integration-sentry": "6.0.0",
+    "@shipfox/api-integration-slack": "6.0.0",
+    "@shipfox/api-integration-webhook": "6.0.0",
+    "@shipfox/config": "1.2.2",
+    "@shipfox/inter-module": "0.2.0",
+    "@shipfox/node-drizzle": "0.3.2",
+    "@shipfox/node-fastify": "0.2.4",
+    "@shipfox/node-module": "0.4.0",
+    "@shipfox/node-opentelemetry": "0.5.2",
+    "@shipfox/node-outbox": "0.2.4",
+    "@shipfox/node-postgres": "0.4.2",
+    "@shipfox/node-temporal": "0.3.2",
+    "@shipfox/regex": "0.2.2",
+    "@shipfox/redact": "0.2.3"
   },
   "devDependencies": {
     "@temporalio/activity": "1.18.1",
@@ -69,16 +62,18 @@
     "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/depcruise": "1.0.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",
     "check": "shipfox-biome-check",
     "check:fix": "shipfox-biome-check --write",
+    "depcruise": "shipfox-depcruise",
     "test": "shipfox-vitest-run",
     "test:watch": "shipfox-vitest-watch",
     "type": "shipfox-tsc-check",

package/src/core/entities/provider.ts

@@ -1,6 +1,8 @@
 import type {
   IntegrationProvider as CoreIntegrationProvider,
   RegisteredIntegrationProvider as CoreRegisteredIntegrationProvider,
+  WebhookRequestProcessor,
+  WebhookRouteId,
 } from '@shipfox/api-integration-core-dto';
 import type {RouteExport} from '@shipfox/node-fastify';
 
@@ -17,5 +19,9 @@ export type {
   OpenAgentToolsSessionInput,
 } from '@shipfox/api-integration-core-dto';
 
-export type IntegrationProvider = CoreIntegrationProvider<string, RouteExport>;
+export type IntegrationProvider = CoreIntegrationProvider<string, RouteExport> & {
+  webhookProcessors?:
+    | Array<{routeIds: readonly WebhookRouteId[]; processor: WebhookRequestProcessor}>
+    | undefined;
+};
 export type RegisteredIntegrationProvider = CoreRegisteredIntegrationProvider<string, RouteExport>;

package/src/core/errors.ts

@@ -35,7 +35,10 @@ export class IntegrationConnectionAlreadyExistsError extends Error {
 }
 
 export class IntegrationCapabilityUnavailableError extends Error {
-  constructor(capability: IntegrationCapability, provider: IntegrationProviderKind) {
+  constructor(
+    public readonly capability: IntegrationCapability,
+    public readonly provider: IntegrationProviderKind,
+  ) {
     super(`Integration provider ${provider} does not expose ${capability}`);
   }
 }
@@ -47,9 +50,16 @@ export class IntegrationCheckoutUnsupportedError extends Error {
 }
 
 export class IntegrationProviderUnavailableError extends Error {
-  constructor(provider: IntegrationProviderKind) {
+  constructor(public readonly provider: IntegrationProviderKind) {
     super(`No integration provider registered for ${provider}`);
   }
 }
 
+export class WebhookProcessorNotConfiguredError extends Error {
+  constructor(public readonly routeId: string) {
+    super(`No webhook processor is configured for ${routeId}`);
+    this.name = 'WebhookProcessorNotConfiguredError';
+  }
+}
+
 export {ConnectionSlugConflictError, IntegrationProviderError, type IntegrationProviderErrorReason};

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.test.ts

@@ -0,0 +1,112 @@
+import type {
+  StoredWebhookRequest,
+  WebhookRequestProcessor,
+} from '@shipfox/api-integration-core-dto';
+import {createOutboxRegistry, type ModuleService, startModuleServices} from '@shipfox/node-module';
+import {createIntegrationsContext, WebhookProcessorNotConfiguredError} from './index.js';
+
+const request = {
+  schema_version: 1,
+  request_id: 'a8a44e12-f4bd-4bd1-82d4-ccdba70a9f3e',
+  route_id: 'github',
+  received_at: '2026-07-20T12:00:00.000Z',
+  method: 'POST',
+  path_parameters: {},
+  raw_query_string: '',
+  headers: {},
+  body: {encoding: 'base64', data: ''},
+} as const satisfies StoredWebhookRequest;
+
+describe('createIntegrationsContext', () => {
+  it('binds the composed direct-route processor to an optional delivery source', async () => {
+    const directProcessor: WebhookRequestProcessor = {
+      process: vi.fn().mockResolvedValue({outcome: 'processed', deliveryId: 'delivery-1'}),
+    };
+    const stop = vi.fn().mockResolvedValue(undefined);
+    const service: ModuleService = {
+      name: 'queued-webhook-deliveries',
+      shutdownTimeoutMs: 1_000,
+      start: vi.fn().mockResolvedValue({finished: Promise.resolve(), stop}),
+    };
+    const deliverySource = {createService: vi.fn().mockReturnValue(service)};
+
+    const context = await createIntegrationsContext({
+      parts: [
+        {
+          provider: {provider: 'github', displayName: 'GitHub', adapters: {}},
+          webhookProcessors: [{routeIds: ['github'], processor: directProcessor}],
+        },
+      ],
+      webhookDeliverySource: deliverySource,
+    });
+
+    expect(context.module.services).toEqual([service]);
+    expect(deliverySource.createService).toHaveBeenCalledWith(context.webhookProcessor);
+
+    const result = await context.webhookProcessor.process(request);
+    const services = await startModuleServices({
+      services: context.module.services ?? [],
+      context: {outboxRegistry: createOutboxRegistry()},
+    });
+    await services.stop();
+
+    expect(result).toEqual({outcome: 'processed', deliveryId: 'delivery-1'});
+    expect(directProcessor.process).toHaveBeenCalledWith(request);
+    expect(stop).toHaveBeenCalledOnce();
+  });
+
+  it('does not register a service without a delivery source', async () => {
+    const context = await createIntegrationsContext({
+      parts: [{provider: {provider: 'github', displayName: 'GitHub', adapters: {}}}],
+    });
+
+    expect(context.module.services).toBeUndefined();
+  });
+
+  it('rejects a queued request with no registered processor', async () => {
+    const context = await createIntegrationsContext({
+      parts: [{provider: {provider: 'github', displayName: 'GitHub', adapters: {}}}],
+    });
+
+    const result = context.webhookProcessor.process(request);
+
+    await expect(result).rejects.toEqual(new WebhookProcessorNotConfiguredError('github'));
+  });
+
+  it('fails composition when more than one processor handles a route', async () => {
+    const processor: WebhookRequestProcessor = {
+      process: vi.fn().mockResolvedValue({outcome: 'processed', deliveryId: 'delivery-1'}),
+    };
+
+    const result = createIntegrationsContext({
+      parts: [
+        {
+          provider: {provider: 'github', displayName: 'GitHub', adapters: {}},
+          webhookProcessors: [
+            {routeIds: ['github'], processor},
+            {routeIds: ['github'], processor},
+          ],
+        },
+      ],
+    });
+
+    await expect(result).rejects.toThrow(
+      'Webhook processor is registered more than once for github',
+    );
+  });
+
+  it('fails composition when a configured delivery source is invalid', async () => {
+    const sourceError = new Error('WEBHOOK_QUEUE_URL is required');
+
+    const result = createIntegrationsContext({
+      parts: [{provider: {provider: 'github', displayName: 'GitHub', adapters: {}}}],
+      webhookDeliverySource: {
+        createService: () => {
+          throw sourceError;
+        },
+      },
+    });
+
+    await expect(result).rejects.toThrow(sourceError);
+  });
+});

package/src/index.ts

@@ -1,9 +1,18 @@
 import {dirname, resolve} from 'node:path';
 import {fileURLToPath} from 'node:url';
-import {integrationsEventSchemas} from '@shipfox/api-integration-core-dto';
-import type {ShipfoxModule} from '@shipfox/node-module';
+import {
+  integrationsEventSchemas,
+  type StoredWebhookRequest,
+  type WebhookProcessingResult,
+  type WebhookRequestProcessor,
+  type WebhookRouteId,
+} from '@shipfox/api-integration-core-dto';
+import type {WorkflowsModuleClient} from '@shipfox/api-workflows-dto/inter-module';
+import type {WorkspacesInterModuleClient} from '@shipfox/api-workspaces-dto/inter-module';
+import type {ModuleService, ShipfoxModule} from '@shipfox/node-module';
 import {logger} from '@shipfox/node-opentelemetry';
 import type {IntegrationProvider} from '#core/entities/provider.js';
+import {WebhookProcessorNotConfiguredError} from '#core/errors.js';
 import {
   createIntegrationProviderRegistry,
   type IntegrationProviderRegistry,
@@ -16,15 +25,26 @@ import {getIntegrationConnectionById} from '#db/connections.js';
 import {db} from '#db/db.js';
 import {migrationsPath} from '#db/migrations.js';
 import {integrationsOutbox} from '#db/schema/outbox.js';
-import {createIntegrationRoutes, type LeasedAgentStepLoader} from '#presentation/routes/index.js';
+import {createIntegrationsInterModulePresentation} from '#presentation/inter-module.js';
+import {createIntegrationRoutes} from '#presentation/routes/index.js';
 import {loadEnabledProviderModules} from '#providers/modules.js';
-import type {IntegrationModuleParts, IntegrationProviderSecrets} from '#providers/types.js';
+import type {
+  IntegrationModuleParts,
+  IntegrationProviderSecrets,
+  WebhookProcessorRegistration,
+} from '#providers/types.js';
 import {createIntegrationsMaintenanceActivities} from '#temporal/activities/index.js';
 import {INTEGRATIONS_MAINTENANCE_TASK_QUEUE} from '#temporal/constants.js';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const maintenanceWorkflowsPath = resolve(packageRoot, 'dist/temporal/workflows/index.js');
 
+export type {
+  StoredWebhookRequest,
+  WebhookProcessingResult,
+  WebhookRequestProcessor,
+  WebhookRouteId,
+} from '@shipfox/api-integration-core-dto';
 export {
   buildProviderRepositoryId,
   MAX_REPOSITORY_FILE_BYTES,
@@ -63,6 +83,7 @@ export {
   IntegrationConnectionWorkspaceMismatchError,
   IntegrationProviderError,
   IntegrationProviderUnavailableError,
+  WebhookProcessorNotConfiguredError,
 } from '#core/errors.js';
 export type {
   AgentToolCallInput,
@@ -98,6 +119,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 +128,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 {
@@ -118,11 +140,21 @@ export interface CreateIntegrationsModuleOptions {
    */
   parts?: IntegrationModuleParts[] | undefined;
   secrets?: IntegrationProviderSecrets | undefined;
+  workspaces?: WorkspacesInterModuleClient | undefined;
   agentTools?:
     | {
-        loadLeasedAgentStep: LeasedAgentStepLoader;
+        workflows: WorkflowsModuleClient;
       }
     | undefined;
+  webhookDeliverySource?: WebhookDeliverySource | undefined;
+}
+
+/**
+ * Hosted runtimes implement this port to receive stored webhook requests. The
+ * integration module starts its returned service after migrations complete.
+ */
+export interface WebhookDeliverySource {
+  createService(processor: WebhookRequestProcessor): ModuleService;
 }
 
 export interface IntegrationsContext {
@@ -132,6 +164,7 @@ export interface IntegrationsContext {
     sourceControl: IntegrationSourceControlService;
   };
   sourceControl: IntegrationSourceControlService;
+  webhookProcessor: WebhookRequestProcessor;
   /**
    * Runs every enabled provider's one-shot boot-time tasks, after modules are initialized
    * (migrations done). Failures are isolated and logged, never rethrown, so a provider task
@@ -149,17 +182,41 @@ export async function createIntegrationsModule(
 export async function createIntegrationsContext(
   options: CreateIntegrationsModuleOptions = {},
 ): Promise<IntegrationsContext> {
+  const workspaces = options.workspaces;
   const parts: IntegrationModuleParts[] =
     options.parts ??
     (options.providers
-      ? options.providers.map((provider) => ({provider}))
-      : await loadEnabledProviderModules({secrets: options.secrets}));
+      ? options.providers.map((provider) => ({
+          provider,
+          webhookProcessors: provider.webhookProcessors,
+        }))
+      : await loadEnabledProviderModules({
+          secrets: options.secrets,
+          ...(workspaces
+            ? {
+                requireActiveWorkspaceMembership: (input: {
+                  workspaceId: string;
+                  userId: string;
+                  memberships: ReadonlyArray<
+                    import('@shipfox/api-auth-context').UserContextMembership
+                  >;
+                }) =>
+                  workspaces.requireActiveMembership({
+                    ...input,
+                    memberships: [...input.memberships],
+                  }),
+              }
+            : {}),
+        }));
 
   const registry = createIntegrationProviderRegistry(parts.map((part) => part.provider));
   const sourceControl = createSourceControlIntegrationService({
     registry,
     getIntegrationConnectionById,
   });
+  const webhookProcessor = createComposedWebhookProcessor(
+    parts.flatMap((part) => part.webhookProcessors ?? []),
+  );
 
   async function runStartupTasks(): Promise<void> {
     for (const task of parts.flatMap((part) => part.startupTasks ?? [])) {
@@ -174,6 +231,9 @@ export async function createIntegrationsContext(
 
   const module: ShipfoxModule = {
     name: 'integrations',
+    interModulePresentations: [
+      createIntegrationsInterModulePresentation({registry, sourceControl}),
+    ],
     startupTasks: runStartupTasks,
     database: [
       {db, migrationsPath},
@@ -182,7 +242,7 @@ export async function createIntegrationsContext(
     routes: createIntegrationRoutes(registry, sourceControl, {
       agentTools: options.agentTools
         ? {
-            loadLeasedAgentStep: options.agentTools.loadLeasedAgentStep,
+            workflows: options.agentTools.workflows,
             getIntegrationConnectionById,
           }
         : undefined,
@@ -206,7 +266,41 @@ export async function createIntegrationsContext(
       },
       ...parts.flatMap((part) => part.workers ?? []),
     ],
+    ...(options.webhookDeliverySource
+      ? {services: [options.webhookDeliverySource.createService(webhookProcessor)]}
+      : {}),
   };
 
-  return {module, registry, capabilities: {sourceControl}, sourceControl, runStartupTasks};
+  return {
+    module,
+    registry,
+    capabilities: {sourceControl},
+    sourceControl,
+    webhookProcessor,
+    runStartupTasks,
+  };
+}
+
+function createComposedWebhookProcessor(
+  registrations: WebhookProcessorRegistration[],
+): WebhookRequestProcessor {
+  const processors = new Map<WebhookRouteId, WebhookRequestProcessor>();
+  for (const registration of registrations) {
+    for (const routeId of registration.routeIds) {
+      if (processors.has(routeId)) {
+        throw new Error(`Webhook processor is registered more than once for ${routeId}`);
+      }
+      processors.set(routeId, registration.processor);
+    }
+  }
+
+  return {
+    async process(request: StoredWebhookRequest): Promise<WebhookProcessingResult> {
+      const processor = processors.get(request.route_id);
+      if (!processor) {
+        throw new WebhookProcessorNotConfiguredError(request.route_id);
+      }
+      return await processor.process(request);
+    },
+  };
 }