@shipfox/api-integration-core 4.0.0 → 6.0.0

package/src/providers/jira.ts

@@ -1,22 +1,163 @@
+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(): Promise<IntegrationModuleParts> {
+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');
 
-  return {
-    provider: createJiraIntegrationProvider(),
-    database: {
-      db: jiraDb,
-      migrationsPath,
-      migrationsTableName: JIRA_MIGRATIONS_TABLE,
+  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,
+        ...(options.requireActiveWorkspaceMembership
+          ? {requireActiveWorkspaceMembership: options.requireActiveWorkspaceMembership}
+          : {}),
+      },
+    }),
+    database: {db: jiraDb, migrationsPath, migrationsTableName: JIRA_MIGRATIONS_TABLE},
   };
 }
 
@@ -25,3 +166,10 @@ export const jiraProviderModule: IntegrationProviderModule = {
   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);
+}

package/src/providers/linear.test.ts

@@ -0,0 +1,136 @@
+import {
+  getLinearInstallationByConnectionId,
+  upsertLinearInstallation,
+} from '@shipfox/api-integration-linear';
+import {runMigrations} from '@shipfox/node-drizzle';
+import {getIntegrationConnectionById, upsertIntegrationConnection} from '#db/connections.js';
+import {db} from '#db/db.js';
+import {linearProviderModule} from '#providers/linear.js';
+import {createTestApp, useIntegrationRouteTest} from '#test/route-utils.js';
+
+describe('linearProviderModule', () => {
+  const context = useIntegrationRouteTest();
+
+  it('deletes the installation and tokens through the generic route before allowing a reinstall', async () => {
+    const deleteSecrets = vi.fn(() => Promise.resolve(2));
+    const scopedSecrets = {
+      getSecret: vi.fn(() => Promise.resolve(null)),
+      setSecrets: vi.fn(() => Promise.resolve()),
+      deleteSecrets,
+    };
+    const linearPart = await linearProviderModule.load({
+      secrets: {linear: scopedSecrets, deleteSecrets},
+    });
+    if (!linearPart.database) throw new Error('Linear provider database is not configured');
+    const organizationId = crypto.randomUUID();
+
+    await runMigrations(
+      linearPart.database.db(),
+      linearPart.database.migrationsPath,
+      linearPart.database.migrationsTableName,
+    );
+    const app = await createTestApp([linearPart.provider]);
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'linear',
+      externalAccountId: organizationId,
+      slug: 'linear_acme',
+      displayName: 'Linear Acme',
+    });
+    await upsertLinearInstallation({
+      connectionId: connection.id,
+      organizationId,
+      organizationUrlKey: 'acme',
+      appUserId: 'user-1',
+      scopes: ['read'],
+      status: 'installed',
+      tokenExpiresAt: null,
+    });
+
+    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();
+    await expect(getLinearInstallationByConnectionId(connection.id)).resolves.toBeUndefined();
+    expect(deleteSecrets).toHaveBeenCalledWith({
+      workspaceId: context.workspaceId,
+      namespace: connection.id,
+    });
+
+    const replacement = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'linear',
+      externalAccountId: organizationId,
+      slug: 'linear_acme_again',
+      displayName: 'Linear Acme',
+    });
+    await upsertLinearInstallation({
+      connectionId: replacement.id,
+      organizationId,
+      organizationUrlKey: 'acme',
+      appUserId: 'user-1',
+      scopes: ['read'],
+      status: 'installed',
+      tokenExpiresAt: null,
+    });
+
+    await expect(getLinearInstallationByConnectionId(replacement.id)).resolves.toMatchObject({
+      organizationId,
+    });
+  });
+
+  it('rolls back provider record cleanup when its transaction fails', async () => {
+    const deleteSecrets = vi.fn(() => Promise.resolve(2));
+    const scopedSecrets = {
+      getSecret: vi.fn(() => Promise.resolve(null)),
+      setSecrets: vi.fn(() => Promise.resolve()),
+      deleteSecrets,
+    };
+    const linearPart = await linearProviderModule.load({
+      secrets: {linear: scopedSecrets, deleteSecrets},
+    });
+    if (!linearPart.database) throw new Error('Linear provider database is not configured');
+    const organizationId = crypto.randomUUID();
+
+    await runMigrations(
+      linearPart.database.db(),
+      linearPart.database.migrationsPath,
+      linearPart.database.migrationsTableName,
+    );
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'linear',
+      externalAccountId: organizationId,
+      slug: 'linear_acme',
+      displayName: 'Linear Acme',
+    });
+    await upsertLinearInstallation({
+      connectionId: connection.id,
+      organizationId,
+      organizationUrlKey: 'acme',
+      appUserId: 'user-1',
+      scopes: ['read'],
+      status: 'installed',
+      tokenExpiresAt: null,
+    });
+
+    await expect(
+      db().transaction(async (tx) => {
+        await linearPart.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(getLinearInstallationByConnectionId(connection.id)).resolves.toMatchObject({
+      connectionId: connection.id,
+    });
+    expect(deleteSecrets).not.toHaveBeenCalled();
+  });
+});

package/src/providers/linear.ts

@@ -32,9 +32,11 @@ async function loadLinearModuleParts(
     createLinearE2eRoutes,
     createLinearIntegrationProvider,
     config: linearConfig,
+    deleteLinearInstallationByConnectionId,
     disconnectLinearInstallation: disconnectLinearInstallationRecords,
     getLinearInstallationByOrganizationId,
     db: linearDb,
+    linearSecretsNamespace,
     migrationsPath: linearMigrationsPath,
     upsertLinearInstallation,
   } = await import('@shipfox/api-integration-linear');
@@ -134,20 +136,38 @@ async function loadLinearModuleParts(
     secrets,
   });
 
-  return {
-    provider: createLinearIntegrationProvider({
-      agentTools: {tokenStore, endpoint: linearConfig.LINEAR_MCP_ENDPOINT},
-      routes: {
-        tokenStore,
-        getExistingLinearConnection,
-        connectLinearInstallation,
-        disconnectLinearInstallation,
-        publishIntegrationEventReceived,
-        recordDeliveryOnly,
-        getIntegrationConnectionById,
-        coreDb: db,
+  const integrationProvider = createLinearIntegrationProvider({
+    agentTools: {tokenStore, endpoint: linearConfig.LINEAR_MCP_ENDPOINT},
+    cleanup: {
+      deleteConnectionRecords: async (connection, {tx}) => {
+        await deleteLinearInstallationByConnectionId(connection.id, {tx});
+      },
+      deleteConnectionSecrets: async (connection) => {
+        // Scoped secrets accept the provider-local suffix, after this helper validates its prefix.
+        await (options.secrets?.linear?.deleteSecrets({
+          workspaceId: connection.workspaceId,
+          namespace: linearNamespaceSuffix(linearSecretsNamespace(connection.id)),
+        }) ?? Promise.resolve());
       },
-    }),
+    },
+    routes: {
+      tokenStore,
+      getExistingLinearConnection,
+      connectLinearInstallation,
+      disconnectLinearInstallation,
+      publishIntegrationEventReceived,
+      recordDeliveryOnly,
+      getIntegrationConnectionById,
+      coreDb: db,
+      ...(options.requireActiveWorkspaceMembership
+        ? {requireActiveWorkspaceMembership: options.requireActiveWorkspaceMembership}
+        : {}),
+    },
+  });
+
+  return {
+    provider: integrationProvider,
+    webhookProcessors: integrationProvider.webhookProcessors,
     e2eRoutes: [
       createLinearE2eRoutes({
         tokenStore,

package/src/providers/sentry.ts

@@ -84,19 +84,22 @@ async function loadSentryModuleParts(): Promise<IntegrationModuleParts> {
     );
   }
 
+  const integrationProvider = createSentryIntegrationProvider({
+    getSentryInstallation: ({installationUuid}) =>
+      getSentryInstallationByInstallationUuid(installationUuid),
+    getConnectionById,
+    connectSentryInstallation,
+    persistVerifiedUnclaimedInstallation,
+    coreDb: db,
+    publishIntegrationEventReceived,
+    recordDeliveryOnly,
+    getIntegrationConnectionById,
+    updateConnectionLifecycleStatus: updateIntegrationConnectionLifecycleStatus,
+  });
+
   return {
-    provider: createSentryIntegrationProvider({
-      getSentryInstallation: ({installationUuid}) =>
-        getSentryInstallationByInstallationUuid(installationUuid),
-      getConnectionById,
-      connectSentryInstallation,
-      persistVerifiedUnclaimedInstallation,
-      coreDb: db,
-      publishIntegrationEventReceived,
-      recordDeliveryOnly,
-      getIntegrationConnectionById,
-      updateConnectionLifecycleStatus: updateIntegrationConnectionLifecycleStatus,
-    }),
+    provider: integrationProvider,
+    webhookProcessors: integrationProvider.webhookProcessors,
     database: {
       db: sentryDb,
       migrationsPath: sentryMigrationsPath,

package/src/providers/slack.test.ts

@@ -4,8 +4,12 @@ import {
 } from '@shipfox/api-integration-slack';
 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('slackProviderModule', () => {
+  const context = useIntegrationRouteTest();
+
   afterEach(() => {
     vi.unstubAllEnvs();
     vi.resetModules();
@@ -54,4 +58,139 @@ describe('slackProviderModule', () => {
       teamId,
     });
   });
+
+  it('deletes the installation and token through the generic route before allowing a reinstall', async () => {
+    vi.stubEnv('INTEGRATIONS_ENABLE_SLACK_PROVIDER', 'true');
+    vi.resetModules();
+    const deleteSecrets = vi.fn(() => Promise.resolve(1));
+    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: {slack: scopedSecrets, deleteSecrets},
+    });
+    const slackPart = parts.find((part) => part.provider.provider === 'slack');
+    if (!slackPart?.database) throw new Error('Slack provider database is not configured');
+    const teamId = `T${crypto.randomUUID()}`;
+
+    await runMigrations(
+      slackPart.database.db(),
+      slackPart.database.migrationsPath,
+      slackPart.database.migrationsTableName,
+    );
+    const app = await createTestApp([slackPart.provider]);
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'slack',
+      externalAccountId: teamId,
+      slug: `slack_${teamId}`,
+      displayName: 'Slack Acme',
+    });
+    await upsertSlackInstallation({
+      connectionId: connection.id,
+      teamId,
+      teamName: 'Acme',
+      appId: 'A123',
+      botUserId: 'U123',
+      scopes: ['app_mentions:read'],
+      status: 'installed',
+    });
+
+    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();
+    await expect(getSlackInstallationByConnectionId(connection.id)).resolves.toBeUndefined();
+    expect(deleteSecrets).toHaveBeenCalledWith({
+      workspaceId: context.workspaceId,
+      namespace: connection.id,
+    });
+
+    const replacement = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'slack',
+      externalAccountId: teamId,
+      slug: `slack_${teamId}_again`,
+      displayName: 'Slack Acme',
+    });
+    await upsertSlackInstallation({
+      connectionId: replacement.id,
+      teamId,
+      teamName: 'Acme',
+      appId: 'A123',
+      botUserId: 'U123',
+      scopes: ['app_mentions:read'],
+      status: 'installed',
+    });
+
+    await expect(getSlackInstallationByConnectionId(replacement.id)).resolves.toMatchObject({
+      teamId,
+    });
+  });
+
+  it('rolls back provider record cleanup when its transaction fails', async () => {
+    vi.stubEnv('INTEGRATIONS_ENABLE_SLACK_PROVIDER', 'true');
+    vi.resetModules();
+    const deleteSecrets = vi.fn(() => Promise.resolve(1));
+    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: {slack: scopedSecrets, deleteSecrets},
+    });
+    const slackPart = parts.find((part) => part.provider.provider === 'slack');
+    if (!slackPart?.database) throw new Error('Slack provider database is not configured');
+    const teamId = `T${crypto.randomUUID()}`;
+
+    await runMigrations(
+      slackPart.database.db(),
+      slackPart.database.migrationsPath,
+      slackPart.database.migrationsTableName,
+    );
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'slack',
+      externalAccountId: teamId,
+      slug: `slack_${teamId}`,
+      displayName: 'Slack Acme',
+    });
+    await upsertSlackInstallation({
+      connectionId: connection.id,
+      teamId,
+      teamName: 'Acme',
+      appId: 'A123',
+      botUserId: 'U123',
+      scopes: ['app_mentions:read'],
+      status: 'installed',
+    });
+
+    await expect(
+      db().transaction(async (tx) => {
+        await slackPart.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(getSlackInstallationByConnectionId(connection.id)).resolves.toMatchObject({
+      connectionId: connection.id,
+    });
+    expect(deleteSecrets).not.toHaveBeenCalled();
+  });
 });

package/src/providers/slack.ts

@@ -14,7 +14,11 @@ import {
   upsertIntegrationConnection,
 } from '#db/connections.js';
 import {db} from '#db/db.js';
-import {publishIntegrationEventReceived, recordDeliveryOnly} from '#db/webhook-deliveries.js';
+import {
+  claimWebhookDelivery,
+  publishIntegrationEventReceived,
+  recordDeliveryOnly,
+} from '#db/webhook-deliveries.js';
 import {retryConnectionSlugCollision} from '#providers/connection-slug.js';
 import type {IntegrationModuleParts, IntegrationProviderModule} from '#providers/types.js';
 
@@ -32,9 +36,11 @@ async function loadSlackModuleParts(
     createSlackIntegrationProvider,
     createSlackTokenStore,
     db: slackDb,
+    deleteSlackInstallationByConnectionId,
     disconnectSlackInstallation: disconnectSlackInstallationRecords,
     getSlackInstallationByTeamId,
     migrationsPath: slackMigrationsPath,
+    slackSecretsNamespace,
     upsertSlackInstallation,
   } = await import('@shipfox/api-integration-slack');
 
@@ -132,20 +138,39 @@ async function loadSlackModuleParts(
     secrets,
   });
 
-  return {
-    provider: createSlackIntegrationProvider({
-      agentTools: {tokenStore},
-      routes: {
-        tokenStore,
-        getExistingSlackConnection,
-        connectSlackInstallation,
-        disconnectSlackInstallation,
-        coreDb: db,
-        publishIntegrationEventReceived,
-        recordDeliveryOnly,
-        getIntegrationConnectionById,
+  const integrationProvider = createSlackIntegrationProvider({
+    agentTools: {tokenStore},
+    cleanup: {
+      deleteConnectionRecords: async (connection, {tx}) => {
+        await deleteSlackInstallationByConnectionId(connection.id, {tx});
       },
-    }),
+      deleteConnectionSecrets: async (connection) => {
+        // Scoped secrets accept the provider-local suffix, after this helper validates its prefix.
+        await (options.secrets?.slack?.deleteSecrets({
+          workspaceId: connection.workspaceId,
+          namespace: slackNamespaceSuffix(slackSecretsNamespace(connection.id)),
+        }) ?? Promise.resolve());
+      },
+    },
+    routes: {
+      tokenStore,
+      getExistingSlackConnection,
+      connectSlackInstallation,
+      disconnectSlackInstallation,
+      coreDb: db,
+      claimWebhookDelivery,
+      publishIntegrationEventReceived,
+      recordDeliveryOnly,
+      getIntegrationConnectionById,
+      ...(options.requireActiveWorkspaceMembership
+        ? {requireActiveWorkspaceMembership: options.requireActiveWorkspaceMembership}
+        : {}),
+    },
+  });
+
+  return {
+    provider: integrationProvider,
+    webhookProcessors: integrationProvider.webhookProcessors,
     e2eRoutes: [
       createSlackE2eRoutes({
         tokenStore,

package/src/providers/types.ts

@@ -1,3 +1,5 @@
+import type {UserContextMembership} from '@shipfox/api-auth-context';
+import type {WebhookRequestProcessor, WebhookRouteId} from '@shipfox/api-integration-core-dto';
 import type {RouteExport} from '@shipfox/node-fastify';
 import type {ModuleDatabase, ModuleWorker} from '@shipfox/node-module';
 import type {IntegrationProvider} from '#core/entities/provider.js';
@@ -17,6 +19,12 @@ export interface IntegrationModuleParts {
   e2eRoutes?: RouteExport[] | undefined;
   workers?: ModuleWorker[] | undefined;
   startupTasks?: Array<() => Promise<void>> | undefined;
+  webhookProcessors?: WebhookProcessorRegistration[] | undefined;
+}
+
+export interface WebhookProcessorRegistration {
+  routeIds: readonly WebhookRouteId[];
+  processor: WebhookRequestProcessor;
 }
 
 /**
@@ -32,6 +40,13 @@ export interface IntegrationProviderModule {
 
 export interface IntegrationProviderModuleLoadOptions {
   secrets?: IntegrationProviderSecrets | undefined;
+  requireActiveWorkspaceMembership?:
+    | ((input: {
+        workspaceId: string;
+        userId: string;
+        memberships: ReadonlyArray<UserContextMembership>;
+      }) => Promise<unknown>)
+    | undefined;
 }
 
 export interface IntegrationProviderSecrets {