@shipfox/api-integration-core-dto 12.2.0 → 15.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-core-dto",
   "license": "MIT",
-  "version": "12.2.0",
+  "version": "15.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -23,7 +23,8 @@
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@shipfox/inter-module": "0.2.3"
+    "@shipfox/inter-module": "0.2.3",
+    "@shipfox/regex": "0.3.0"
   },
   "imports": {
     "#*": "./dist/*"

package/src/events.test.ts

@@ -15,6 +15,7 @@ const validConnectionAvailable = {
   workspaceId: 'ws-1',
   connectionId: 'conn-1',
   slug: 'linear_shipfox',
+  capabilities: ['agent_tools'],
 };
 
 const validEventReceived = {
@@ -65,6 +66,51 @@ describe('integrationConnectionAvailableSchema', () => {
     );
   });
 
+  it('carries both capabilities for a source-control and tool provider', () => {
+    const input = {...validConnectionAvailable, capabilities: ['source_control', 'agent_tools']};
+
+    expect(integrationConnectionAvailableSchema.parse(input)).toEqual(input);
+  });
+
+  it('carries an empty capabilities array for a connection without adapters', () => {
+    const input = {...validConnectionAvailable, capabilities: []};
+
+    expect(integrationConnectionAvailableSchema.parse(input)).toEqual(input);
+  });
+
+  it('defaults capabilities for an event written before the field existed', () => {
+    const {capabilities: _capabilities, ...withoutCapabilities} = validConnectionAvailable;
+
+    expect(integrationConnectionAvailableSchema.parse(withoutCapabilities)).toEqual({
+      ...withoutCapabilities,
+      capabilities: [],
+    });
+  });
+
+  it('rejects unknown or empty capability values', () => {
+    expect(() =>
+      integrationConnectionAvailableSchema.parse({
+        ...validConnectionAvailable,
+        capabilities: [''],
+      }),
+    ).toThrow();
+    expect(() =>
+      integrationConnectionAvailableSchema.parse({
+        ...validConnectionAvailable,
+        capabilities: ['agent-tools'],
+      }),
+    ).toThrow();
+  });
+
+  it('rejects capability arrays above the contract bound', () => {
+    expect(() =>
+      integrationConnectionAvailableSchema.parse({
+        ...validConnectionAvailable,
+        capabilities: Array.from({length: 17}, () => 'agent_tools'),
+      }),
+    ).toThrow();
+  });
+
   it('rejects a payload without a connection slug', () => {
     const {slug: _slug, ...withoutSlug} = validConnectionAvailable;
 

package/src/events.ts

@@ -1,4 +1,5 @@
 import {z} from 'zod';
+import {integrationCapabilitySchema} from './schemas/integrations.js';
 
 export const INTEGRATION_EVENT_RECEIVED = 'integrations.event.received' as const;
 export const INTEGRATION_CONNECTION_AVAILABLE = 'integrations.connection.available' as const;
@@ -28,6 +29,11 @@ export const integrationConnectionAvailableSchema = z.object({
   workspaceId: nonEmptyStringSchema,
   connectionId: nonEmptyStringSchema,
   slug: nonEmptyStringSchema,
+  // Provider registry capabilities, so subscribers can tell a tool connection
+  // from a source-control connection without their own provider table.
+  // Defaulting keeps availability events written before this field existed
+  // deliverable while every new event is still constrained to known capabilities.
+  capabilities: z.array(integrationCapabilitySchema).max(16).default([]),
 });
 export type IntegrationConnectionAvailableEvent = z.infer<
   typeof integrationConnectionAvailableSchema

package/src/inter-module.test.ts

@@ -65,6 +65,37 @@ describe('integrationsInterModuleContract', () => {
     expect(integrationsInterModuleContract.methods.resolveConnection.output.parse(null)).toBeNull();
   });
 
+  test('accepts a resolved source ref through the producer contract', () => {
+    const result = integrationsInterModuleContract.methods.resolveSourceRef.output.parse({
+      ref: 'refs/heads/fix-triage-prompt',
+      commit: 'a'.repeat(40),
+    });
+
+    expect(result).toEqual({ref: 'refs/heads/fix-triage-prompt', commit: 'a'.repeat(40)});
+  });
+
+  test('parses a ref-bearing input through the producer contract', () => {
+    const input = integrationsInterModuleContract.methods.resolveSourceRef.input.parse({
+      workspaceId: '00000000-0000-4000-8000-000000000001',
+      connectionId: '00000000-0000-4000-8000-000000000002',
+      externalRepositoryId: 'github:42',
+      ref: 'refs/heads/main',
+    });
+
+    expect(input.ref).toBe('refs/heads/main');
+  });
+
+  test('rejects control characters in a ref-bearing input', () => {
+    expect(() =>
+      integrationsInterModuleContract.methods.resolveSourceRef.input.parse({
+        workspaceId: '00000000-0000-4000-8000-000000000001',
+        connectionId: '00000000-0000-4000-8000-000000000002',
+        externalRepositoryId: 'github:42',
+        ref: 'refs/heads/unsafe\nname',
+      }),
+    ).toThrow();
+  });
+
   test.each([
     ['connection-not-found', {connectionId: '00000000-0000-4000-8000-000000000001'}],
     ['provider-unavailable', {provider: 'github'}],
@@ -77,4 +108,49 @@ describe('integrationsInterModuleContract', () => {
 
     expect(schema.parse(details)).toEqual(details);
   });
+
+  test.each([
+    ['ref-not-found', {ref: 'refs/heads/missing'}],
+    ['ref-invalid', {ref: 'a'.repeat(40)}],
+  ] as const)('defines the %s ref failure', (code, details) => {
+    const schema =
+      integrationsInterModuleContract.methods.resolveSourceRef.errors[
+        code as keyof typeof integrationsInterModuleContract.methods.resolveSourceRef.errors
+      ];
+
+    expect(schema.parse(details)).toEqual(details);
+  });
+
+  test('accepts provider event catalogs and fixed event providers on the validation context', () => {
+    const output = integrationsInterModuleContract.methods.getAgentToolsContext.output.parse({
+      selectionCatalogs: [],
+      catalogs: [],
+      workspaceConnections: [],
+      eventCatalogs: [
+        {provider: 'github', events: ['push']},
+        {provider: 'webhook', events: ['received']},
+      ],
+      fixedEventProviders: ['webhook'],
+      defaultConnection: null,
+    });
+
+    expect(output.eventCatalogs).toEqual([
+      {provider: 'github', events: ['push']},
+      {provider: 'webhook', events: ['received']},
+    ]);
+    expect(output.fixedEventProviders).toEqual(['webhook']);
+  });
+
+  test('rejects empty fixed event provider identifiers', () => {
+    expect(() =>
+      integrationsInterModuleContract.methods.getAgentToolsContext.output.parse({
+        selectionCatalogs: [],
+        catalogs: [],
+        workspaceConnections: [],
+        eventCatalogs: [],
+        fixedEventProviders: [''],
+        defaultConnection: null,
+      }),
+    ).toThrow();
+  });
 });

package/src/inter-module.ts

@@ -1,9 +1,11 @@
 import {defineInterModuleContract, type InterModuleClient} from '@shipfox/inter-module';
+import {isSafeRefInput} from '@shipfox/regex';
 import {z} from 'zod';
 
 const id = z.string().uuid();
 const provider = z.string().min(1);
 const capability = z.enum(['source_control', 'agent_tools']);
+const safeRef = z.string().refine(isSafeRefInput, 'Ref contains a control character');
 const connection = z.object({id, provider, slug: z.string().min(1)});
 const repository = z.object({
   externalRepositoryId: z.string(),
@@ -36,6 +38,12 @@ const sourceErrors = {
   'provider-failure': providerError,
 };
 
+const refErrors = {
+  ...sourceErrors,
+  'ref-not-found': z.object({ref: safeRef}),
+  'ref-invalid': z.object({ref: safeRef}),
+};
+
 /** Producer-owned synchronous operations for the Integrations bounded context. */
 export const integrationsInterModuleContract = defineInterModuleContract({
   module: 'integrations',
@@ -54,6 +62,11 @@ export const integrationsInterModuleContract = defineInterModuleContract({
       output: triggerReference.nullable(),
       errors: sourceErrors,
     },
+    resolveSourceRef: {
+      input: sourceInput.extend({ref: safeRef}),
+      output: z.object({ref: z.string(), commit: z.string()}),
+      errors: refErrors,
+    },
     listSourceFiles: {
       input: sourceInput.extend({
         ref: z.string(),
@@ -135,6 +148,8 @@ export const integrationsInterModuleContract = defineInterModuleContract({
         workspaceConnections: z.array(
           z.object({slug: z.string(), id, provider, capabilities: z.array(capability)}),
         ),
+        eventCatalogs: z.array(z.object({provider, events: z.array(z.string())})),
+        fixedEventProviders: z.array(provider),
         defaultConnection: z.object({id, slug: z.string(), provider}).nullable(),
       }),
       errors: sourceErrors,

package/src/schemas/index.ts

@@ -25,6 +25,7 @@ export {
   listRepositoriesParamsSchema,
   listRepositoriesQuerySchema,
   listRepositoriesResponseSchema,
+  RESERVED_CONNECTION_SLUGS,
   type RepositoryDto,
   type RepositoryVisibilityDto,
   repositoryDtoSchema,

package/src/schemas/integrations.ts

@@ -2,6 +2,13 @@ import {z} from 'zod';
 
 export const CONNECTION_SLUG_MAX_LENGTH = 100;
 
+/**
+ * Slugs sync classifies by literal: a source equal to one of these names is a
+ * built-in trigger source, never a connection. No provider may allocate a
+ * connection holding one of them.
+ */
+export const RESERVED_CONNECTION_SLUGS = ['manual', 'cron'] as const;
+
 export const connectionSlugSchema = z
   .string()
   .min(1)