@shipfox/api-integration-core 13.0.0 → 14.0.0

package/src/db/connections.ts

@@ -2,6 +2,7 @@ import {
   CONNECTION_SLUG_MAX_LENGTH,
   INTEGRATION_CONNECTION_AVAILABLE,
   type IntegrationsEventMap,
+  RESERVED_CONNECTION_SLUGS,
 } from '@shipfox/api-integration-core-dto';
 import {ConnectionSlugConflictError} from '@shipfox/api-integration-spi';
 import {writeOutboxEvent} from '@shipfox/node-outbox';
@@ -10,7 +11,7 @@ import type {
   IntegrationConnection,
   IntegrationConnectionLifecycleStatus,
 } from '#core/entities/connection.js';
-import type {IntegrationProviderKind} from '#core/entities/provider.js';
+import type {IntegrationCapability, IntegrationProviderKind} from '#core/entities/provider.js';
 import {IntegrationConnectionAlreadyExistsError} from '#core/errors.js';
 import {db} from './db.js';
 import {integrationConnections, toIntegrationConnection} from './schema/connections.js';
@@ -26,12 +27,14 @@ export interface UpsertIntegrationConnectionParams {
   slug: string;
   displayName: string;
   lifecycleStatus?: IntegrationConnectionLifecycleStatus | undefined;
+  capabilities?: IntegrationCapability[] | undefined;
 }
 
 export async function upsertIntegrationConnection(
   params: UpsertIntegrationConnectionParams,
   options: {tx?: IntegrationDb | IntegrationTx | undefined} = {},
 ): Promise<IntegrationConnection> {
+  assertConnectionSlugIsNotReserved(params.slug);
   if (options.tx === undefined) {
     return await db().transaction((tx) => upsertIntegrationConnection(params, {tx}));
   }
@@ -91,7 +94,7 @@ export async function upsertIntegrationConnection(
   if (!row) throw new Error('Integration connection upsert returned no rows');
   const connection = toIntegrationConnection(row);
   if (becameAvailable) {
-    await writeConnectionAvailableEvent(executor, connection);
+    await writeConnectionAvailableEvent(executor, connection, params.capabilities);
   }
   return connection;
 }
@@ -103,6 +106,7 @@ export interface CreateIntegrationConnectionParams {
   slug: string;
   displayName: string;
   lifecycleStatus?: IntegrationConnectionLifecycleStatus | undefined;
+  capabilities?: IntegrationCapability[] | undefined;
 }
 
 const INTEGRATION_CONNECTION_EXTERNAL_UNIQUE_CONSTRAINT =
@@ -140,6 +144,7 @@ export async function createIntegrationConnection(
   params: CreateIntegrationConnectionParams,
   options: {tx?: IntegrationDb | IntegrationTx | undefined} = {},
 ): Promise<IntegrationConnection> {
+  assertConnectionSlugIsNotReserved(params.slug);
   if (options.tx === undefined) {
     return await db().transaction((tx) => createIntegrationConnection(params, {tx}));
   }
@@ -176,7 +181,7 @@ export async function createIntegrationConnection(
   if (!row) throw new Error('Integration connection insert returned no rows');
   const connection = toIntegrationConnection(row);
   if (connection.lifecycleStatus === 'active') {
-    await writeConnectionAvailableEvent(executor, connection);
+    await writeConnectionAvailableEvent(executor, connection, params.capabilities);
   }
   return connection;
 }
@@ -192,6 +197,7 @@ export async function resolveUniqueConnectionSlug(
   params: ResolveUniqueConnectionSlugParams,
   options: {tx?: IntegrationDb | IntegrationTx | undefined} = {},
 ): Promise<string> {
+  assertConnectionSlugIsNotReserved(params.baseSlug);
   const executor = options.tx ?? db();
   const [existing] = await executor
     .select({slug: integrationConnections.slug})
@@ -220,6 +226,14 @@ export async function resolveUniqueConnectionSlug(
   }
 }
 
+function assertConnectionSlugIsNotReserved(slug: string): void {
+  const normalizedSlug = slug.toLowerCase().replaceAll(/[_-]+$/g, '');
+  if (!(RESERVED_CONNECTION_SLUGS as readonly string[]).includes(normalizedSlug)) return;
+  throw new ConnectionSlugConflictError(
+    new Error(`Slug "${slug}" is reserved for a built-in trigger source`),
+  );
+}
+
 export type CreateIntegrationConnectionFn = typeof createIntegrationConnection;
 
 export async function getIntegrationConnectionById(
@@ -267,6 +281,7 @@ export type GetIntegrationConnectionBySlugFn = typeof getIntegrationConnectionBy
 export interface UpdateIntegrationConnectionLifecycleStatusParams {
   id: string;
   lifecycleStatus: IntegrationConnectionLifecycleStatus;
+  capabilities?: IntegrationCapability[] | undefined;
 }
 
 export async function updateIntegrationConnectionLifecycleStatus(
@@ -294,7 +309,7 @@ export async function updateIntegrationConnectionLifecycleStatus(
   if (!row) return undefined;
   const connection = toIntegrationConnection(row);
   if (existing.lifecycleStatus !== 'active' && connection.lifecycleStatus === 'active') {
-    await writeConnectionAvailableEvent(executor, connection);
+    await writeConnectionAvailableEvent(executor, connection, params.capabilities);
   }
   return connection;
 }
@@ -305,6 +320,7 @@ export type UpdateIntegrationConnectionLifecycleStatusFn =
 async function writeConnectionAvailableEvent(
   executor: IntegrationDb | IntegrationTx,
   connection: IntegrationConnection,
+  capabilities: IntegrationCapability[] | undefined,
 ): Promise<void> {
   await writeOutboxEvent<IntegrationsEventMap>(executor, integrationsOutbox, {
     type: INTEGRATION_CONNECTION_AVAILABLE,
@@ -313,6 +329,7 @@ async function writeConnectionAvailableEvent(
       workspaceId: connection.workspaceId,
       connectionId: connection.id,
       slug: connection.slug,
+      capabilities: capabilities ?? [],
     },
   });
 }

package/src/db/secret-cleanups.test.ts

@@ -107,6 +107,7 @@ async function createCleanupConnection(overrides: {externalAccountId?: string} =
     externalAccountId: overrides.externalAccountId ?? crypto.randomUUID(),
     slug: `slack_${crypto.randomUUID()}`,
     displayName: 'Slack',
+    capabilities: ['agent_tools'],
   });
   await enqueueIntegrationSecretCleanup({connection});
   return connection;

package/src/index.ts

@@ -112,6 +112,8 @@ export type {
   RepositoryPage,
   RepositorySnapshot,
   RepositoryVisibility,
+  ResolvedRef,
+  ResolveRefInput,
   ResolveRepositoryInput,
   SourceControlProvider,
   TriggerReference,

package/src/metrics/instance.ts

@@ -26,6 +26,8 @@ const integrationAgentToolCallErrorCodes = new Set<string>([
   'repository-not-found',
   'installation-not-found',
   'file-not-found',
+  'ref-not-found',
+  'ref-invalid',
   'access-denied',
   'rate-limited',
   'timeout',

package/src/presentation/inter-module.test.ts

@@ -0,0 +1,219 @@
+import {integrationsInterModuleContract} from '@shipfox/api-integration-core-dto/inter-module';
+import {isInterModuleKnownError} from '@shipfox/inter-module';
+import {createInMemoryInterModuleTransport} from '@shipfox/node-module/inter-module';
+import {IntegrationProviderError} from '#core/errors.js';
+import {createIntegrationProviderRegistry} from '#core/providers/registry.js';
+import type {SourceControlProvider} from '#core/providers/source-control.js';
+import {createSourceControlIntegrationService} from '#core/source-control-service.js';
+import {createIntegrationsInterModulePresentation} from './inter-module.js';
+
+const workspaceId = crypto.randomUUID();
+const connectionId = crypto.randomUUID();
+
+function createClient(
+  resolveRef: (input: {ref: string}) => Promise<{ref: string; commit: string}>,
+  resolveRepository: SourceControlProvider['resolveRepository'] = () => {
+    throw new Error('not used');
+  },
+) {
+  const transport = createInMemoryInterModuleTransport();
+  const client = transport.createClient(integrationsInterModuleContract);
+
+  const sourceControl = createSourceControlIntegrationService({
+    registry: createIntegrationProviderRegistry([
+      {
+        provider: 'gitea',
+        displayName: 'Gitea',
+        adapters: {
+          source_control: {
+            listRepositories: vi.fn(),
+            resolveRepository: vi.fn(resolveRepository),
+            listFiles: vi.fn(),
+            fetchFile: vi.fn(),
+            resolveTriggerReference: () => null,
+            resolveRef: async (input) => await resolveRef(input),
+          },
+        },
+      },
+    ]),
+    getIntegrationConnectionById: async (id) => {
+      await Promise.resolve();
+      return id === connectionId
+        ? {
+            id: connectionId,
+            workspaceId,
+            provider: 'gitea',
+            externalAccountId: 'gitea-owner',
+            slug: 'gitea_owner',
+            displayName: 'Gitea',
+            lifecycleStatus: 'active' as const,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+          }
+        : undefined;
+    },
+  });
+
+  transport.register(
+    createIntegrationsInterModulePresentation({
+      registry: createIntegrationProviderRegistry([]),
+      sourceControl,
+    }),
+  );
+  transport.seal();
+  return client;
+}
+
+describe('integrations inter-module presentation', () => {
+  const input = {
+    workspaceId,
+    connectionId,
+    externalRepositoryId: 'gitea:gitea-owner/platform',
+  };
+
+  it('resolves a source ref through the transport', async () => {
+    const client = createClient(async (input) => ({
+      ref: input.ref,
+      commit: 'a'.repeat(40),
+    }));
+
+    const result = await client.resolveSourceRef({...input, ref: 'refs/heads/main'});
+
+    expect(result).toEqual({ref: 'refs/heads/main', commit: 'a'.repeat(40)});
+  });
+
+  it('maps a missing ref to the ref-not-found known error', async () => {
+    const client = createClient(() => {
+      throw new IntegrationProviderError('ref-not-found', 'Ref not found');
+    });
+
+    const error = await client
+      .resolveSourceRef({...input, ref: 'refs/heads/missing'})
+      .catch((caught: unknown) => caught);
+
+    expect(
+      isInterModuleKnownError(integrationsInterModuleContract.methods.resolveSourceRef, error),
+    ).toBe(true);
+    if (isInterModuleKnownError(integrationsInterModuleContract.methods.resolveSourceRef, error)) {
+      expect(error.code).toBe('ref-not-found');
+      expect(error.details).toEqual({ref: 'refs/heads/missing'});
+    }
+  });
+
+  it('maps an invalid ref to the ref-invalid known error', async () => {
+    const client = createClient(() => {
+      throw new IntegrationProviderError('ref-invalid', 'Ref is not a branch or tag name');
+    });
+
+    const error = await client
+      .resolveSourceRef({...input, ref: 'a'.repeat(40)})
+      .catch((caught: unknown) => caught);
+
+    if (isInterModuleKnownError(integrationsInterModuleContract.methods.resolveSourceRef, error)) {
+      expect(error.code).toBe('ref-invalid');
+      expect(error.details).toEqual({ref: 'a'.repeat(40)});
+    } else {
+      throw error;
+    }
+  });
+
+  it('keeps other provider failures as provider-failure known errors', async () => {
+    const client = createClient(() => {
+      throw new IntegrationProviderError('rate-limited', 'Rate limited', 60);
+    });
+
+    const error = await client
+      .resolveSourceRef({...input, ref: 'refs/heads/main'})
+      .catch((caught: unknown) => caught);
+
+    if (isInterModuleKnownError(integrationsInterModuleContract.methods.resolveSourceRef, error)) {
+      expect(error.code).toBe('provider-failure');
+      expect(error.details).toEqual({reason: 'rate-limited', retryAfterSeconds: 60});
+    } else {
+      throw error;
+    }
+  });
+
+  it('keeps ref reasons generic for methods that do not declare ref errors', async () => {
+    const client = createClient(
+      async (input) => ({ref: input.ref, commit: 'a'.repeat(40)}),
+      () => {
+        throw new IntegrationProviderError('ref-not-found', 'Ref not found');
+      },
+    );
+
+    const error = await client.resolveSourceRepository(input).catch((caught: unknown) => caught);
+
+    if (
+      isInterModuleKnownError(
+        integrationsInterModuleContract.methods.resolveSourceRepository,
+        error,
+      )
+    ) {
+      expect(error.code).toBe('provider-failure');
+      expect(error.details).toEqual({reason: 'ref-not-found'});
+    } else {
+      throw error;
+    }
+  });
+
+  it('serves provider event catalogs and fixed event providers on the validation context', async () => {
+    const transport = createInMemoryInterModuleTransport();
+    const client = transport.createClient(integrationsInterModuleContract);
+
+    const sourceControl = createSourceControlIntegrationService({
+      registry: createIntegrationProviderRegistry([]),
+      getIntegrationConnectionById: async () => undefined,
+    });
+    transport.register(
+      createIntegrationsInterModulePresentation({
+        registry: createIntegrationProviderRegistry([
+          {
+            provider: 'github',
+            displayName: 'GitHub',
+            eventCatalog: {
+              provider: 'GitHub',
+              events: [
+                {
+                  name: 'push',
+                  summary: 'A push.',
+                  emittedWhen: 'GitHub sends a push webhook.',
+                  payloadKind: 'raw-provider',
+                },
+              ],
+            },
+          },
+          {
+            provider: 'webhook',
+            displayName: 'Webhook',
+            eventCatalog: {
+              provider: 'Custom webhook',
+              events: [
+                {
+                  name: 'received',
+                  summary: 'A webhook request is accepted.',
+                  emittedWhen: 'Shipfox accepts a request.',
+                  payloadKind: 'shipfox-normalized',
+                },
+              ],
+            },
+          },
+          {provider: 'gitea', displayName: 'Gitea'},
+        ]),
+        sourceControl,
+      }),
+    );
+    transport.seal();
+
+    const context = await client.getAgentToolsContext({
+      workspaceId,
+      defaultConnectionId: connectionId,
+    });
+
+    expect(context.eventCatalogs).toEqual([
+      {provider: 'github', events: ['push']},
+      {provider: 'webhook', events: ['received']},
+    ]);
+    expect(context.fixedEventProviders).toEqual(['webhook']);
+  });
+});

package/src/presentation/inter-module.ts

@@ -19,6 +19,7 @@ import {
   IntegrationProviderError,
   IntegrationProviderUnavailableError,
 } from '#core/errors.js';
+import {buildFixedEventProviders, buildProviderEventCatalogs} from '#core/event-catalogs.js';
 import type {IntegrationProviderRegistry} from '#core/providers/registry.js';
 import type {IntegrationSourceControlService} from '#core/source-control-service.js';
 import {getIntegrationConnectionById, getIntegrationConnectionBySlug} from '#db/connections.js';
@@ -51,6 +52,12 @@ export function createIntegrationsInterModulePresentation(params: {
         input,
         async () => await params.sourceControl.resolveTriggerReference(input),
       ),
+    resolveSourceRef: async (input) =>
+      await known(
+        contract.methods.resolveSourceRef,
+        input,
+        async () => await params.sourceControl.resolveSourceRef(input),
+      ),
     listSourceFiles: async (input) =>
       await known(
         contract.methods.listSourceFiles,
@@ -105,6 +112,8 @@ export function createIntegrationsInterModulePresentation(params: {
             ...value,
             capabilities: [...value.capabilities],
           })),
+          eventCatalogs: buildProviderEventCatalogs(params.registry),
+          fixedEventProviders: buildFixedEventProviders(params.registry),
           defaultConnection: defaultConnection
             ? {
                 id: defaultConnection.id,
@@ -119,7 +128,7 @@ export function createIntegrationsInterModulePresentation(params: {
 
 async function known<Output>(
   method: InterModuleMethodContract,
-  input: {connectionId?: string; defaultConnectionId?: string},
+  input: {connectionId?: string; defaultConnectionId?: string; ref?: string | undefined},
   operation: () => Promise<Output>,
 ): Promise<Output> {
   try {
@@ -130,7 +139,7 @@ async function known<Output>(
 }
 function mapError(
   method: InterModuleMethodContract,
-  input: {connectionId?: string; defaultConnectionId?: string},
+  input: {connectionId?: string; defaultConnectionId?: string; ref?: string | undefined},
   error: unknown,
 ): unknown {
   if (error instanceof IntegrationConnectionNotFoundError)
@@ -154,12 +163,28 @@ function mapError(
     });
   if (error instanceof IntegrationCheckoutUnsupportedError)
     return createInterModuleKnownError(method, 'checkout-unsupported', {provider: error.provider});
-  if (error instanceof IntegrationProviderError)
+  if (error instanceof IntegrationProviderError) {
+    // Only methods that resolve refs declare these codes; other methods keep
+    // seeing the failure as a generic provider failure.
+    if (error.reason === 'ref-not-found' && 'ref-not-found' in method.errors) {
+      return createInterModuleKnownError(method, 'ref-not-found', refDetails(input));
+    }
+    if (error.reason === 'ref-invalid' && 'ref-invalid' in method.errors) {
+      return createInterModuleKnownError(method, 'ref-invalid', refDetails(input));
+    }
     return createInterModuleKnownError(method, 'provider-failure', {
       reason: error.reason,
       ...(error.retryAfterSeconds === undefined
         ? {}
         : {retryAfterSeconds: error.retryAfterSeconds}),
     });
+  }
   return error;
 }
+
+function refDetails(input: {ref?: string | undefined}): {ref: string} {
+  if (input.ref === undefined) {
+    throw new Error('Ref error mapping requires a ref input');
+  }
+  return {ref: input.ref};
+}

package/src/presentation/routes/errors.ts

@@ -23,7 +23,10 @@ function isProviderError(error: unknown): error is IntegrationProviderError {
       'reason' in error &&
       typeof error.reason === 'string' &&
       (error.reason === 'repository-not-found' ||
+        error.reason === 'installation-not-found' ||
         error.reason === 'file-not-found' ||
+        error.reason === 'ref-not-found' ||
+        error.reason === 'ref-invalid' ||
         error.reason === 'access-denied' ||
         error.reason === 'rate-limited' ||
         error.reason === 'timeout' ||

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

@@ -13,6 +13,7 @@ describe('GET /integration-connections', () => {
       externalAccountId: 'debug-active',
       slug: 'debug_active',
       displayName: 'Gitea',
+      capabilities: ['source_control'],
     });
     await upsertIntegrationConnection({
       workspaceId: context.workspaceId,
@@ -20,6 +21,7 @@ describe('GET /integration-connections', () => {
       externalAccountId: 'debug-error',
       slug: 'debug_error',
       displayName: 'Gitea',
+      capabilities: ['source_control'],
       lifecycleStatus: 'error',
     });
 
@@ -38,13 +40,17 @@ describe('GET /integration-connections', () => {
   });
 
   it('drops connections whose provider misses the capability filter', async () => {
-    const app = await createTestApp([sourceProvider()]);
+    const app = await createTestApp([
+      sourceProvider(),
+      {provider: 'github', displayName: 'GitHub', adapters: {}},
+    ]);
     await upsertIntegrationConnection({
       workspaceId: context.workspaceId,
       provider: 'gitea',
       externalAccountId: 'gitea-owner',
       slug: 'gitea_owner',
       displayName: 'Gitea',
+      capabilities: ['source_control'],
     });
     await upsertIntegrationConnection({
       workspaceId: context.workspaceId,
@@ -52,6 +58,7 @@ describe('GET /integration-connections', () => {
       externalAccountId: 'team-1',
       slug: 'github_team_1',
       displayName: 'GitHub',
+      capabilities: ['source_control', 'agent_tools'],
     });
 
     const res = await app.inject({
@@ -94,6 +101,7 @@ describe('GET /integration-connections', () => {
       externalAccountId: 'team-1',
       slug: 'github_team_1',
       displayName: 'GitHub',
+      capabilities: ['source_control', 'agent_tools'],
     });
 
     const res = await app.inject({
@@ -119,6 +127,7 @@ describe('GET /integration-connections', () => {
       externalAccountId: 'org-1',
       slug: 'linear_org_1',
       displayName: 'Linear Org',
+      capabilities: ['agent_tools'],
     });
 
     const res = await app.inject({
@@ -145,6 +154,7 @@ describe('GET /integration-connections', () => {
       externalAccountId: 'org-1',
       slug: 'linear_org_1',
       displayName: 'Linear Org',
+      capabilities: ['agent_tools'],
     });
 
     const res = await app.inject({
@@ -174,6 +184,7 @@ describe('GET /integration-connections', () => {
       externalAccountId: 'gitea-owner',
       slug: 'gitea_owner',
       displayName: 'Gitea',
+      capabilities: ['source_control'],
     });
 
     const res = await app.inject({
@@ -198,6 +209,7 @@ describe('GET /integration-connections', () => {
       externalAccountId: 'gitea-owner',
       slug: 'gitea_owner',
       displayName: 'Gitea',
+      capabilities: ['source_control'],
     });
 
     const res = await app.inject({

package/src/presentation/routes/list-repositories.test.ts

@@ -13,6 +13,7 @@ describe('GET /integration-connections/:connectionId/repositories', () => {
       externalAccountId: 'gitea-owner',
       slug: 'gitea_owner',
       displayName: 'Gitea',
+      capabilities: ['source_control'],
     });
 
     const res = await app.inject({
@@ -46,6 +47,7 @@ describe('GET /integration-connections/:connectionId/repositories', () => {
       externalAccountId: 'gitea-owner',
       slug: 'gitea_owner',
       displayName: 'Gitea',
+      capabilities: ['source_control'],
       lifecycleStatus: 'disabled',
     });
 
@@ -73,6 +75,7 @@ describe('GET /integration-connections/:connectionId/repositories', () => {
       externalAccountId: 'team-1',
       slug: 'github_team_1',
       displayName: 'GitHub',
+      capabilities: ['source_control', 'agent_tools'],
     });
 
     const res = await app.inject({
@@ -93,6 +96,7 @@ describe('GET /integration-connections/:connectionId/repositories', () => {
       externalAccountId: 'installation-1',
       slug: 'github_installation_1',
       displayName: 'GitHub',
+      capabilities: ['source_control', 'agent_tools'],
     });
 
     const res = await app.inject({
@@ -127,6 +131,10 @@ describe('GET /integration-connections/:connectionId/repositories', () => {
               throw new Error('not used');
             },
             resolveTriggerReference: () => null,
+            resolveRef: async () => {
+              await Promise.resolve();
+              throw new Error('not used');
+            },
           },
         },
       }),
@@ -137,6 +145,7 @@ describe('GET /integration-connections/:connectionId/repositories', () => {
       externalAccountId: 'gitea-owner',
       slug: 'gitea_owner',
       displayName: 'Gitea',
+      capabilities: ['source_control'],
     });
 
     const res = await app.inject({