@shipfox/api-integration-core-dto 12.0.0 → 14.0.0

package/dist/webhooks.d.ts

@@ -6,14 +6,14 @@ export declare const WEBHOOK_MAX_HEADER_BYTES: number;
 export declare const WEBHOOK_MAX_RAW_QUERY_STRING_LENGTH: number;
 export declare const webhookRouteIds: readonly ["github", "gitea", "linear", "sentry", "slack.event", "slack.command", "webhook.connection", "jira"];
 export declare const webhookRouteIdSchema: z.ZodEnum<{
-    github: "github";
     gitea: "gitea";
+    github: "github";
+    jira: "jira";
     linear: "linear";
     sentry: "sentry";
-    "slack.event": "slack.event";
     "slack.command": "slack.command";
+    "slack.event": "slack.event";
     "webhook.connection": "webhook.connection";
-    jira: "jira";
 }>;
 export type WebhookRouteId = z.infer<typeof webhookRouteIdSchema>;
 declare const webhookBodySchema: z.ZodObject<{
@@ -32,12 +32,12 @@ export declare const storedWebhookRequestSchema: z.ZodDiscriminatedUnion<[z.ZodO
         data: z.ZodString;
     }, z.core.$strict>;
     route_id: z.ZodEnum<{
-        github: "github";
         gitea: "gitea";
+        github: "github";
         linear: "linear";
         sentry: "sentry";
-        "slack.event": "slack.event";
         "slack.command": "slack.command";
+        "slack.event": "slack.event";
     }>;
     path_parameters: z.ZodObject<{}, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
@@ -82,12 +82,12 @@ export declare const webhookProcessingResultSchema: z.ZodDiscriminatedUnion<[z.Z
 }, z.core.$strict>, z.ZodObject<{
     outcome: z.ZodLiteral<"discarded">;
     reason: z.ZodEnum<{
-        missing_required_input: "missing_required_input";
+        connection_unavailable: "connection_unavailable";
         invalid_signature: "invalid_signature";
-        stale_at_receipt: "stale_at_receipt";
         malformed_payload: "malformed_payload";
+        missing_required_input: "missing_required_input";
+        stale_at_receipt: "stale_at_receipt";
         unsupported_event: "unsupported_event";
-        connection_unavailable: "connection_unavailable";
     }>;
     deliveryId: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>], "outcome">;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-core-dto",
   "license": "MIT",
-  "version": "12.0.0",
+  "version": "14.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",

package/src/events.test.ts

@@ -1,13 +1,23 @@
 import {
+  INTEGRATION_CONNECTION_AVAILABLE,
   INTEGRATION_EVENT_RECEIVED,
   INTEGRATION_SOURCE_COMMIT_PUSHED,
   INTEGRATION_SOURCE_REPOSITORY_UPDATED,
+  integrationConnectionAvailableSchema,
   integrationEventReceivedSchema,
   integrationSourceCommitPushedSchema,
   integrationSourceRepositoryUpdatedSchema,
   integrationsEventSchemas,
 } from './events.js';
 
+const validConnectionAvailable = {
+  provider: 'linear',
+  workspaceId: 'ws-1',
+  connectionId: 'conn-1',
+  slug: 'linear_shipfox',
+  capabilities: ['agent_tools'],
+};
+
 const validEventReceived = {
   provider: 'github',
   source: 'github',
@@ -49,6 +59,65 @@ const validRepositoryUpdated = {
   },
 };
 
+describe('integrationConnectionAvailableSchema', () => {
+  it('parses a valid connection-available payload unchanged', () => {
+    expect(integrationConnectionAvailableSchema.parse(validConnectionAvailable)).toEqual(
+      validConnectionAvailable,
+    );
+  });
+
+  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;
+
+    expect(() => integrationConnectionAvailableSchema.parse(withoutSlug)).toThrow();
+  });
+});
+
 describe('integrationSourceCommitPushedSchema', () => {
   it('parses a valid commit-pushed payload unchanged', () => {
     const result = integrationSourceCommitPushedSchema.parse(validCommitPushed);
@@ -136,6 +205,7 @@ describe('integrationsEventSchemas', () => {
 
     expect(registeredTypes).toEqual(
       [
+        INTEGRATION_CONNECTION_AVAILABLE,
         INTEGRATION_EVENT_RECEIVED,
         INTEGRATION_SOURCE_COMMIT_PUSHED,
         INTEGRATION_SOURCE_REPOSITORY_UPDATED,

package/src/events.ts

@@ -1,6 +1,8 @@
 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;
 
 const nonEmptyStringSchema = z.string().nonempty();
 const isoDateTimeSchema = z.string().datetime();
@@ -22,6 +24,21 @@ export const integrationEventReceivedSchema = z.object({
 });
 export type IntegrationEventReceivedEvent = z.infer<typeof integrationEventReceivedSchema>;
 
+export const integrationConnectionAvailableSchema = z.object({
+  provider: nonEmptyStringSchema,
+  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
+>;
+
 // A source-control push, normalized by the producing provider and carried by
 // `INTEGRATION_SOURCE_COMMIT_PUSHED` for domain consumers.
 export const sourcePushSchema = z.object({
@@ -107,12 +124,14 @@ export const SENTRY_ISSUE_ACTIONS = [
 export type SentryIssueAction = (typeof SENTRY_ISSUE_ACTIONS)[number];
 
 export interface IntegrationsEventMap {
+  [INTEGRATION_CONNECTION_AVAILABLE]: IntegrationConnectionAvailableEvent;
   [INTEGRATION_EVENT_RECEIVED]: IntegrationEventReceivedEvent;
   [INTEGRATION_SOURCE_COMMIT_PUSHED]: IntegrationSourceCommitPushedEvent;
   [INTEGRATION_SOURCE_REPOSITORY_UPDATED]: IntegrationSourceRepositoryUpdatedEvent;
 }
 
 export const integrationsEventSchemas = {
+  [INTEGRATION_CONNECTION_AVAILABLE]: integrationConnectionAvailableSchema,
   [INTEGRATION_EVENT_RECEIVED]: integrationEventReceivedSchema,
   [INTEGRATION_SOURCE_COMMIT_PUSHED]: integrationSourceCommitPushedSchema,
   [INTEGRATION_SOURCE_REPOSITORY_UPDATED]: integrationSourceRepositoryUpdatedSchema,

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

@@ -4,6 +4,7 @@ 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 +37,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 +61,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 +147,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,
@@ -142,4 +156,11 @@ export const integrationsInterModuleContract = defineInterModuleContract({
   },
 });
 
+function isSafeRefInput(value: string): boolean {
+  return [...value].every((character) => {
+    const code = character.codePointAt(0) ?? 0;
+    return !(code < 0x20 || (code >= 0x7f && code <= 0x9f) || code === 0x2028 || code === 0x2029);
+  });
+}
+
 export type IntegrationsModuleClient = InterModuleClient<typeof integrationsInterModuleContract>;

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)