@shipfox/api-integration-core 3.0.0 → 4.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-core",
   "license": "MIT",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -40,17 +40,19 @@
     "@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-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.2.1",
+    "@shipfox/node-drizzle": "0.3.0",
     "@shipfox/node-fastify": "0.2.2",
-    "@shipfox/node-module": "0.3.0",
+    "@shipfox/node-module": "0.3.1",
     "@shipfox/node-opentelemetry": "0.5.1",
-    "@shipfox/node-outbox": "0.2.1",
+    "@shipfox/node-outbox": "0.2.2",
     "@shipfox/node-postgres": "0.4.1",
     "@shipfox/node-temporal": "0.3.0",
     "@shipfox/regex": "0.2.1",

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/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,27 @@
+import {config} from '#config.js';
+import type {IntegrationModuleParts, IntegrationProviderModule} from '#providers/types.js';
+
+const JIRA_MIGRATIONS_TABLE = '__drizzle_migrations_integrations_jira';
+
+async function loadJiraModuleParts(): Promise<IntegrationModuleParts> {
+  const {
+    createJiraIntegrationProvider,
+    db: jiraDb,
+    migrationsPath,
+  } = await import('@shipfox/api-integration-jira');
+
+  return {
+    provider: createJiraIntegrationProvider(),
+    database: {
+      db: jiraDb,
+      migrationsPath,
+      migrationsTableName: JIRA_MIGRATIONS_TABLE,
+    },
+  };
+}
+
+export const jiraProviderModule: IntegrationProviderModule = {
+  id: 'jira',
+  enabled: config.INTEGRATIONS_ENABLE_JIRA_PROVIDER,
+  load: loadJiraModuleParts,
+};

package/src/providers/modules.test.ts

@@ -37,4 +37,30 @@ describe('loadEnabledProviderModules', () => {
       adapters: {},
     });
   });
+
+  it('loads Slack when the provider is enabled', async () => {
+    vi.stubEnv('INTEGRATIONS_ENABLE_SLACK_PROVIDER', 'true');
+    vi.resetModules();
+
+    const {loadEnabledProviderModules} = await import('#providers/modules.js');
+    const parts = await loadEnabledProviderModules();
+
+    expect(parts.map((part) => part.provider.provider)).toEqual(['slack', 'cron', 'webhook']);
+    expect(parts[0]?.provider).toMatchObject({
+      provider: 'slack',
+      displayName: 'Slack',
+    });
+    expect(parts[0]?.provider.adapters?.agent_tools).toBeDefined();
+  });
+
+  it('loads Jira when the provider is enabled', async () => {
+    vi.stubEnv('INTEGRATIONS_ENABLE_JIRA_PROVIDER', 'true');
+    vi.resetModules();
+
+    const {loadEnabledProviderModules} = await import('#providers/modules.js');
+    const parts = await loadEnabledProviderModules();
+
+    expect(parts.map((part) => part.provider.provider)).toEqual(['jira', 'cron', 'webhook']);
+    expect(parts[0]?.provider).toMatchObject({provider: 'jira', displayName: 'Jira'});
+  });
 });

package/src/providers/modules.ts

@@ -1,8 +1,10 @@
 import {cronProviderModule} from '#providers/cron.js';
 import {giteaProviderModule} from '#providers/gitea.js';
 import {githubProviderModule} from '#providers/github.js';
+import {jiraProviderModule} from '#providers/jira.js';
 import {linearProviderModule} from '#providers/linear.js';
 import {sentryProviderModule} from '#providers/sentry.js';
+import {slackProviderModule} from '#providers/slack.js';
 import type {
   IntegrationModuleParts,
   IntegrationProviderModuleLoadOptions,
@@ -14,6 +16,8 @@ import {webhookProviderModule} from '#providers/webhook.js';
 const providerModules = [
   githubProviderModule,
   linearProviderModule,
+  slackProviderModule,
+  jiraProviderModule,
   sentryProviderModule,
   giteaProviderModule,
   cronProviderModule,

package/src/providers/slack.test.ts

@@ -0,0 +1,57 @@
+import {
+  getSlackInstallationByConnectionId,
+  upsertSlackInstallation,
+} from '@shipfox/api-integration-slack';
+import {runMigrations} from '@shipfox/node-drizzle';
+import {getIntegrationConnectionById, upsertIntegrationConnection} from '#db/connections.js';
+
+describe('slackProviderModule', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it('loads its database descriptor and persists a core connection with its Slack installation', async () => {
+    vi.stubEnv('INTEGRATIONS_ENABLE_SLACK_PROVIDER', 'true');
+    vi.resetModules();
+    const {createPostgresClient} = await import('@shipfox/node-postgres');
+    createPostgresClient();
+    const {loadEnabledProviderModules} = await import('#providers/modules.js');
+    const parts = await loadEnabledProviderModules();
+    const slackPart = parts.find((part) => part.provider.provider === 'slack');
+    if (!slackPart?.database) throw new Error('Slack provider database is not configured');
+    const workspaceId = crypto.randomUUID();
+    const teamId = `T${crypto.randomUUID()}`;
+
+    await runMigrations(
+      slackPart.database.db(),
+      slackPart.database.migrationsPath,
+      slackPart.database.migrationsTableName,
+    );
+    const connection = await upsertIntegrationConnection({
+      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(getIntegrationConnectionById(connection.id)).resolves.toMatchObject({
+      id: connection.id,
+      provider: 'slack',
+    });
+    await expect(getSlackInstallationByConnectionId(connection.id)).resolves.toMatchObject({
+      connectionId: connection.id,
+      teamId,
+    });
+  });
+});

package/src/providers/slack.ts

@@ -0,0 +1,177 @@
+import {
+  type IntegrationConnection as CoreIntegrationConnection,
+  slugifyConnectionSlug,
+} from '@shipfox/api-integration-core-dto';
+import type {
+  ConnectSlackInstallationInput,
+  SlackSecretsStore,
+} from '@shipfox/api-integration-slack';
+import {config} from '#config.js';
+import {
+  deleteIntegrationConnection,
+  getIntegrationConnectionById,
+  resolveUniqueConnectionSlug,
+  upsertIntegrationConnection,
+} from '#db/connections.js';
+import {db} from '#db/db.js';
+import {publishIntegrationEventReceived, recordDeliveryOnly} from '#db/webhook-deliveries.js';
+import {retryConnectionSlugCollision} from '#providers/connection-slug.js';
+import type {IntegrationModuleParts, IntegrationProviderModule} from '#providers/types.js';
+
+const SLACK_MIGRATIONS_TABLE = '__drizzle_migrations_integrations_slack';
+const SLACK_SECRETS_NAMESPACE_PREFIX = 'system/integrations/slack/';
+
+type IntegrationDb = ReturnType<typeof db>;
+type IntegrationTx = Parameters<Parameters<IntegrationDb['transaction']>[0]>[0];
+
+async function loadSlackModuleParts(
+  options: Parameters<IntegrationProviderModule['load']>[0] = {},
+): Promise<IntegrationModuleParts> {
+  const {
+    createSlackE2eRoutes,
+    createSlackIntegrationProvider,
+    createSlackTokenStore,
+    db: slackDb,
+    disconnectSlackInstallation: disconnectSlackInstallationRecords,
+    getSlackInstallationByTeamId,
+    migrationsPath: slackMigrationsPath,
+    upsertSlackInstallation,
+  } = await import('@shipfox/api-integration-slack');
+
+  async function getExistingSlackConnection(input: {
+    teamId: string;
+  }): Promise<CoreIntegrationConnection<'slack'> | undefined> {
+    const installation = await getSlackInstallationByTeamId(input.teamId);
+    if (!installation) return undefined;
+    const connection = await getIntegrationConnectionById(installation.connectionId);
+    if (!connection) return undefined;
+    return connection as CoreIntegrationConnection<'slack'>;
+  }
+
+  async function connectSlackInstallation(
+    input: ConnectSlackInstallationInput,
+  ): Promise<CoreIntegrationConnection<'slack'>> {
+    return await retryConnectionSlugCollision(() =>
+      db().transaction(async (tx) => {
+        const baseSlug = slugifyConnectionSlug(`slack_${input.teamName || input.teamId}`, {
+          fallback: 'slack',
+        });
+        const slug = await resolveUniqueConnectionSlug(
+          {
+            workspaceId: input.workspaceId,
+            provider: 'slack',
+            externalAccountId: input.teamId,
+            baseSlug,
+          },
+          {tx},
+        );
+        const connection = await upsertIntegrationConnection(
+          {
+            workspaceId: input.workspaceId,
+            provider: 'slack',
+            externalAccountId: input.teamId,
+            slug,
+            displayName: input.displayName,
+            lifecycleStatus: 'active',
+          },
+          {tx},
+        );
+        await upsertSlackInstallation(
+          {
+            connectionId: connection.id,
+            teamId: input.teamId,
+            teamName: input.teamName,
+            appId: input.appId,
+            botUserId: input.botUserId,
+            scopes: input.scopes,
+            tokenExpiresAt: input.tokenExpiresAt,
+            status: 'installed',
+          },
+          {tx},
+        );
+        return connection as CoreIntegrationConnection<'slack'>;
+      }),
+    );
+  }
+
+  async function disconnectSlackInstallation(input: {connectionId: string}): Promise<void> {
+    await disconnectSlackInstallationRecords<IntegrationTx>({
+      connectionId: input.connectionId,
+      getConnection: getIntegrationConnectionById,
+      deleteSecrets: (params) =>
+        options.secrets?.slack?.deleteSecrets({
+          ...params,
+          namespace: slackNamespaceSuffix(params.namespace),
+        }) ?? Promise.resolve(0),
+      transaction: (fn) => db().transaction((tx) => fn(tx)),
+      deleteConnection: (params, options) =>
+        deleteIntegrationConnection({id: params.connectionId}, options),
+    });
+  }
+
+  const fallbackSecrets: SlackSecretsStore = {
+    getSecret: () => Promise.resolve(null),
+    setSecrets: () => Promise.reject(new Error('Slack token storage is not configured')),
+  };
+  const secrets: SlackSecretsStore = options.secrets?.slack
+    ? {
+        getSecret: (params: Parameters<SlackSecretsStore['getSecret']>[0]) =>
+          options.secrets?.slack?.getSecret({
+            ...params,
+            namespace: slackNamespaceSuffix(params.namespace),
+          }) ?? Promise.resolve(null),
+        setSecrets: (params: Parameters<SlackSecretsStore['setSecrets']>[0]) =>
+          options.secrets?.slack?.setSecrets({
+            ...params,
+            namespace: slackNamespaceSuffix(params.namespace),
+          }) ?? Promise.resolve(),
+      }
+    : fallbackSecrets;
+  const tokenStore = createSlackTokenStore({
+    resolveConnection: async (connectionId) => getIntegrationConnectionById(connectionId),
+    secrets,
+  });
+
+  return {
+    provider: createSlackIntegrationProvider({
+      agentTools: {tokenStore},
+      routes: {
+        tokenStore,
+        getExistingSlackConnection,
+        connectSlackInstallation,
+        disconnectSlackInstallation,
+        coreDb: db,
+        publishIntegrationEventReceived,
+        recordDeliveryOnly,
+        getIntegrationConnectionById,
+      },
+    }),
+    e2eRoutes: [
+      createSlackE2eRoutes({
+        tokenStore,
+        getExistingSlackConnection,
+        connectSlackInstallation,
+        disconnectSlackInstallation,
+        connectionCapabilities: ['agent_tools'],
+      }),
+    ],
+    database: {
+      db: slackDb,
+      migrationsPath: slackMigrationsPath,
+      migrationsTableName: SLACK_MIGRATIONS_TABLE,
+    },
+  };
+}
+
+export const slackProviderModule: IntegrationProviderModule = {
+  id: 'slack',
+  enabled: config.INTEGRATIONS_ENABLE_SLACK_PROVIDER,
+  load: loadSlackModuleParts,
+};
+
+function slackNamespaceSuffix(namespace: string): string {
+  if (!namespace.startsWith(SLACK_SECRETS_NAMESPACE_PREFIX)) {
+    throw new Error('Slack provider attempted to access an unscoped secret namespace');
+  }
+  return namespace.slice(SLACK_SECRETS_NAMESPACE_PREFIX.length);
+}

package/src/providers/types.ts

@@ -36,7 +36,9 @@ export interface IntegrationProviderModuleLoadOptions {
 
 export interface IntegrationProviderSecrets {
   github?: IntegrationProviderScopedSecrets | undefined;
+  jira?: IntegrationProviderScopedSecrets | undefined;
   linear?: IntegrationProviderScopedSecrets | undefined;
+  slack?: IntegrationProviderScopedSecrets | undefined;
   deleteSecrets(params: {workspaceId: string; namespace: string}): Promise<number>;
 }
 

package/test/env.ts

@@ -12,11 +12,23 @@ process.env.GITHUB_APP_CLIENT_SECRET = 'test-client-secret';
 process.env.GITHUB_APP_WEBHOOK_SECRET = 'test-webhook-secret';
 process.env.GITHUB_APP_SLUG = 'shipfox-test';
 process.env.GITHUB_INSTALL_STATE_SECRET = 'test-install-state-secret';
+process.env.JIRA_OAUTH_CLIENT_ID = 'test-client-id';
+process.env.JIRA_OAUTH_CLIENT_SECRET = 'test-client-secret';
+process.env.JIRA_OAUTH_REDIRECT_URL = 'https://shipfox.example.com/integrations/jira/callback';
+process.env.JIRA_WEBHOOK_SIGNING_SECRET = 'test-webhook-secret';
+process.env.JIRA_WEBHOOK_BASE_URL = 'https://shipfox.example.com';
+process.env.JIRA_API_BASE_URL = 'https://jira.example.com/api';
+process.env.JIRA_AUTH_BASE_URL = 'https://jira.example.com/auth';
 process.env.LINEAR_OAUTH_CLIENT_ID = 'test-client-id';
 process.env.LINEAR_OAUTH_CLIENT_SECRET = 'test-client-secret';
 process.env.LINEAR_WEBHOOK_SIGNING_SECRET = 'test-webhook-secret';
 process.env.LINEAR_OAUTH_REDIRECT_URL = 'https://shipfox.example.com/integrations/linear/callback';
 process.env.LINEAR_MCP_ENDPOINT = 'https://mcp.linear.app/mcp';
+process.env.SLACK_OAUTH_CLIENT_ID = 'test-client-id';
+process.env.SLACK_OAUTH_CLIENT_SECRET = 'test-client-secret';
+process.env.SLACK_SIGNING_SECRET = 'test-signing-secret';
+process.env.SLACK_OAUTH_REDIRECT_URL = 'https://shipfox.example.com/integrations/slack/callback';
+process.env.SLACK_API_BASE_URL = 'https://slack.example.com/api';
 process.env.GITEA_BASE_URL = 'https://gitea.example.com';
 process.env.GITEA_SERVICE_USERNAME = 'shipfox-bot';
 process.env.GITEA_SERVICE_TOKEN = 'test-service-token';