@shipfox/api-integration-core-dto 5.0.0 → 8.0.0

package/dist/webhooks.d.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+export declare const WEBHOOK_REQUEST_SCHEMA_VERSION: 1;
+export declare const WEBHOOK_MAX_RAW_BODY_BYTES: number;
+export declare const WEBHOOK_MAX_SERIALIZED_REQUEST_BYTES: number;
+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"];
+export declare const webhookRouteIdSchema: z.ZodEnum<{
+    github: "github";
+    gitea: "gitea";
+    linear: "linear";
+    sentry: "sentry";
+    "slack.event": "slack.event";
+    "slack.command": "slack.command";
+    "webhook.connection": "webhook.connection";
+}>;
+export type WebhookRouteId = z.infer<typeof webhookRouteIdSchema>;
+declare const webhookBodySchema: z.ZodObject<{
+    encoding: z.ZodLiteral<"base64">;
+    data: z.ZodString;
+}, z.core.$strict>;
+export declare const storedWebhookRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    request_id: z.ZodString;
+    received_at: z.ZodString;
+    method: z.ZodLiteral<"POST">;
+    raw_query_string: z.ZodString;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    body: z.ZodObject<{
+        encoding: z.ZodLiteral<"base64">;
+        data: z.ZodString;
+    }, z.core.$strict>;
+    route_id: z.ZodEnum<{
+        github: "github";
+        gitea: "gitea";
+        linear: "linear";
+        sentry: "sentry";
+        "slack.event": "slack.event";
+        "slack.command": "slack.command";
+    }>;
+    path_parameters: z.ZodObject<{}, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    request_id: z.ZodString;
+    received_at: z.ZodString;
+    method: z.ZodLiteral<"POST">;
+    raw_query_string: z.ZodString;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    body: z.ZodObject<{
+        encoding: z.ZodLiteral<"base64">;
+        data: z.ZodString;
+    }, z.core.$strict>;
+    route_id: z.ZodLiteral<"webhook.connection">;
+    path_parameters: z.ZodObject<{
+        connection_id: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>], "route_id">;
+export type StoredWebhookRequest = z.infer<typeof storedWebhookRequestSchema>;
+export declare const webhookProcessingResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    outcome: z.ZodLiteral<"processed">;
+    deliveryId: z.ZodOptional<z.ZodString>;
+    challenge: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    outcome: z.ZodLiteral<"duplicate">;
+    deliveryId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    outcome: z.ZodLiteral<"discarded">;
+    reason: z.ZodEnum<{
+        missing_required_input: "missing_required_input";
+        invalid_signature: "invalid_signature";
+        stale_at_receipt: "stale_at_receipt";
+        malformed_payload: "malformed_payload";
+        unsupported_event: "unsupported_event";
+        connection_unavailable: "connection_unavailable";
+    }>;
+    deliveryId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "outcome">;
+export type WebhookProcessingResult = z.infer<typeof webhookProcessingResultSchema>;
+/** Processes one provider-neutral inbound webhook request. */
+export interface WebhookRequestProcessor {
+    process(request: StoredWebhookRequest): Promise<WebhookProcessingResult>;
+}
+export interface CreateStoredWebhookRequestInput {
+    requestId: string;
+    routeId: WebhookRouteId;
+    receivedAt: string;
+    rawQueryString: string;
+    headers: Record<string, string>;
+    body: Uint8Array;
+    connectionId?: string | undefined;
+}
+export declare function encodeWebhookBody(body: Uint8Array): string;
+export declare function decodeWebhookBody(body: z.infer<typeof webhookBodySchema>): Uint8Array;
+export declare function createStoredWebhookRequest(input: CreateStoredWebhookRequestInput): StoredWebhookRequest;
+export declare function createMaximumSizeStoredWebhookRequestFixture(): StoredWebhookRequest;
+export {};
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,eAAO,MAAM,8BAA8B,EAAG,CAAU,CAAC;AACzD,eAAO,MAAM,0BAA0B,QAAa,CAAC;AACrD,eAAO,MAAM,oCAAoC,QAAc,CAAC;AAChE,eAAO,MAAM,wBAAwB,QAAY,CAAC;AAClD,eAAO,MAAM,mCAAmC,QAAW,CAAC;AAW5D,eAAO,MAAM,eAAe,wGAA8D,CAAC;AAE3F,eAAO,MAAM,oBAAoB;;;;;;;;EAA0B,CAAC;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AA4BlE,QAAA,MAAM,iBAAiB;;;kBAYpB,CAAC;AA6BJ,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAGrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;+BAuBxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF,8DAA8D;AAC9D,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC1E;AAED,MAAM,WAAW,+BAA+B;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,cAAc,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CA0B1D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,GAAG,UAAU,CAyBrF;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,+BAA+B,GACrC,oBAAoB,CAetB;AAED,wBAAgB,4CAA4C,IAAI,oBAAoB,CAiBnF"}

package/dist/webhooks.js

@@ -0,0 +1,151 @@
+import { z } from 'zod';
+export const WEBHOOK_REQUEST_SCHEMA_VERSION = 1;
+export const WEBHOOK_MAX_RAW_BODY_BYTES = 512 * 1024;
+export const WEBHOOK_MAX_SERIALIZED_REQUEST_BYTES = 1024 * 1024;
+export const WEBHOOK_MAX_HEADER_BYTES = 64 * 1024;
+export const WEBHOOK_MAX_RAW_QUERY_STRING_LENGTH = 8 * 1024;
+const standardWebhookRouteIds = [
+    'github',
+    'gitea',
+    'linear',
+    'sentry',
+    'slack.event',
+    'slack.command'
+];
+export const webhookRouteIds = [
+    ...standardWebhookRouteIds,
+    'webhook.connection'
+];
+export const webhookRouteIdSchema = z.enum(webhookRouteIds);
+const base64Pattern = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+function decodedBase64Length(value) {
+    const paddingLength = value.endsWith('==') ? 2 : value.endsWith('=') ? 1 : 0;
+    return value.length / 4 * 3 - paddingLength;
+}
+function headersByteLength(headers) {
+    return new TextEncoder().encode(JSON.stringify(headers)).byteLength;
+}
+const webhookHeadersSchema = z.record(z.string(), z.string().max(8 * 1024)).refine((headers)=>Object.keys(headers).every((name)=>name === name.toLowerCase() && name.length > 0 && name.length <= 128), 'Webhook header names must be lowercase and at most 128 characters').refine((headers)=>headersByteLength(headers) <= WEBHOOK_MAX_HEADER_BYTES, `Webhook headers must serialize to at most ${WEBHOOK_MAX_HEADER_BYTES} bytes`);
+const webhookBodySchema = z.object({
+    encoding: z.literal('base64'),
+    data: z.string().max(Math.ceil(WEBHOOK_MAX_RAW_BODY_BYTES / 3) * 4).regex(base64Pattern)
+}).strict().refine((body)=>decodedBase64Length(body.data) <= WEBHOOK_MAX_RAW_BODY_BYTES, `Webhook bodies must decode to at most ${WEBHOOK_MAX_RAW_BODY_BYTES} bytes`);
+const storedWebhookRequestBaseSchema = z.object({
+    schema_version: z.literal(WEBHOOK_REQUEST_SCHEMA_VERSION),
+    request_id: z.string().uuid(),
+    received_at: z.string().datetime({
+        offset: true
+    }),
+    method: z.literal('POST'),
+    raw_query_string: z.string().max(WEBHOOK_MAX_RAW_QUERY_STRING_LENGTH),
+    headers: webhookHeadersSchema,
+    body: webhookBodySchema
+});
+const emptyPathParametersSchema = z.object({}).strict();
+const connectionPathParametersSchema = z.object({
+    connection_id: z.string().uuid()
+}).strict();
+const standardWebhookRouteRequestSchema = storedWebhookRequestBaseSchema.extend({
+    route_id: z.enum(standardWebhookRouteIds),
+    path_parameters: emptyPathParametersSchema
+}).strict();
+const genericWebhookRouteRequestSchema = storedWebhookRequestBaseSchema.extend({
+    route_id: z.literal('webhook.connection'),
+    path_parameters: connectionPathParametersSchema
+}).strict();
+export const storedWebhookRequestSchema = z.discriminatedUnion('route_id', [
+    standardWebhookRouteRequestSchema,
+    genericWebhookRouteRequestSchema
+]);
+export const webhookProcessingResultSchema = z.discriminatedUnion('outcome', [
+    z.object({
+        outcome: z.literal('processed'),
+        deliveryId: z.string().min(1).optional(),
+        challenge: z.string().min(1).optional()
+    }).strict(),
+    z.object({
+        outcome: z.literal('duplicate'),
+        deliveryId: z.string().min(1)
+    }).strict(),
+    z.object({
+        outcome: z.literal('discarded'),
+        reason: z.enum([
+            'missing_required_input',
+            'invalid_signature',
+            'stale_at_receipt',
+            'malformed_payload',
+            'unsupported_event',
+            'connection_unavailable'
+        ]),
+        deliveryId: z.string().min(1).optional()
+    }).strict()
+]);
+export function encodeWebhookBody(body) {
+    let encoded = '';
+    for(let index = 0; index < body.length; index += 3){
+        const first = body[index] ?? 0;
+        const second = body[index + 1];
+        const third = body[index + 2];
+        const combined = first << 16 | (second ?? 0) << 8 | (third ?? 0);
+        encoded += 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'[combined >> 18 & 63];
+        encoded += 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'[combined >> 12 & 63];
+        encoded += second === undefined ? '=' : 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'[combined >> 6 & 63];
+        encoded += third === undefined ? '=' : 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'[combined & 63];
+    }
+    return encoded;
+}
+export function decodeWebhookBody(body) {
+    const output = new Uint8Array(decodedBase64Length(body.data));
+    let outputIndex = 0;
+    for(let index = 0; index < body.data.length; index += 4){
+        const chunk = body.data.slice(index, index + 4);
+        const values = chunk.split('').map((character)=>character === '=' ? 0 : 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'.indexOf(character));
+        const first = values[0] ?? 0;
+        const second = values[1] ?? 0;
+        const third = values[2] ?? 0;
+        const fourth = values[3] ?? 0;
+        const combined = first << 18 | second << 12 | third << 6 | fourth;
+        output[outputIndex++] = combined >> 16 & 255;
+        if (chunk[2] !== '=') output[outputIndex++] = combined >> 8 & 255;
+        if (chunk[3] !== '=') output[outputIndex++] = combined & 255;
+    }
+    return output;
+}
+export function createStoredWebhookRequest(input) {
+    const pathParameters = input.routeId === 'webhook.connection' ? {
+        connection_id: input.connectionId
+    } : {};
+    return storedWebhookRequestSchema.parse({
+        schema_version: WEBHOOK_REQUEST_SCHEMA_VERSION,
+        request_id: input.requestId,
+        route_id: input.routeId,
+        received_at: input.receivedAt,
+        method: 'POST',
+        path_parameters: pathParameters,
+        raw_query_string: input.rawQueryString,
+        headers: input.headers,
+        body: {
+            encoding: 'base64',
+            data: encodeWebhookBody(input.body)
+        }
+    });
+}
+export function createMaximumSizeStoredWebhookRequestFixture() {
+    const headers = Object.fromEntries(Array.from({
+        length: 8
+    }, (_, index)=>[
+            `x-fixture-${index}`,
+            'a'.repeat(index === 7 ? 8_000 : 8 * 1024)
+        ]));
+    return createStoredWebhookRequest({
+        requestId: '9b11d65a-f7e7-40ea-b421-06af012a9be5',
+        routeId: 'webhook.connection',
+        receivedAt: '2026-07-20T10:30:00.123Z',
+        rawQueryString: 'q='.padEnd(WEBHOOK_MAX_RAW_QUERY_STRING_LENGTH, 'q'),
+        headers,
+        body: new Uint8Array(WEBHOOK_MAX_RAW_BODY_BYTES),
+        connectionId: 'c0a8012e-0b6d-4d8f-8d5c-6d74102602b0'
+    });
+}
+
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/webhooks.ts"],"sourcesContent":["import {z} from 'zod';\n\nexport const WEBHOOK_REQUEST_SCHEMA_VERSION = 1 as const;\nexport const WEBHOOK_MAX_RAW_BODY_BYTES = 512 * 1024;\nexport const WEBHOOK_MAX_SERIALIZED_REQUEST_BYTES = 1024 * 1024;\nexport const WEBHOOK_MAX_HEADER_BYTES = 64 * 1024;\nexport const WEBHOOK_MAX_RAW_QUERY_STRING_LENGTH = 8 * 1024;\n\nconst standardWebhookRouteIds = [\n  'github',\n  'gitea',\n  'linear',\n  'sentry',\n  'slack.event',\n  'slack.command',\n] as const;\n\nexport const webhookRouteIds = [...standardWebhookRouteIds, 'webhook.connection'] as const;\n\nexport const webhookRouteIdSchema = z.enum(webhookRouteIds);\nexport type WebhookRouteId = z.infer<typeof webhookRouteIdSchema>;\n\nconst base64Pattern = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;\n\nfunction decodedBase64Length(value: string): number {\n  const paddingLength = value.endsWith('==') ? 2 : value.endsWith('=') ? 1 : 0;\n\n  return (value.length / 4) * 3 - paddingLength;\n}\n\nfunction headersByteLength(headers: Record<string, string>): number {\n  return new TextEncoder().encode(JSON.stringify(headers)).byteLength;\n}\n\nconst webhookHeadersSchema = z\n  .record(z.string(), z.string().max(8 * 1024))\n  .refine(\n    (headers) =>\n      Object.keys(headers).every(\n        (name) => name === name.toLowerCase() && name.length > 0 && name.length <= 128,\n      ),\n    'Webhook header names must be lowercase and at most 128 characters',\n  )\n  .refine(\n    (headers) => headersByteLength(headers) <= WEBHOOK_MAX_HEADER_BYTES,\n    `Webhook headers must serialize to at most ${WEBHOOK_MAX_HEADER_BYTES} bytes`,\n  );\n\nconst webhookBodySchema = z\n  .object({\n    encoding: z.literal('base64'),\n    data: z\n      .string()\n      .max(Math.ceil(WEBHOOK_MAX_RAW_BODY_BYTES / 3) * 4)\n      .regex(base64Pattern),\n  })\n  .strict()\n  .refine(\n    (body) => decodedBase64Length(body.data) <= WEBHOOK_MAX_RAW_BODY_BYTES,\n    `Webhook bodies must decode to at most ${WEBHOOK_MAX_RAW_BODY_BYTES} bytes`,\n  );\n\nconst storedWebhookRequestBaseSchema = z.object({\n  schema_version: z.literal(WEBHOOK_REQUEST_SCHEMA_VERSION),\n  request_id: z.string().uuid(),\n  received_at: z.string().datetime({offset: true}),\n  method: z.literal('POST'),\n  raw_query_string: z.string().max(WEBHOOK_MAX_RAW_QUERY_STRING_LENGTH),\n  headers: webhookHeadersSchema,\n  body: webhookBodySchema,\n});\n\nconst emptyPathParametersSchema = z.object({}).strict();\nconst connectionPathParametersSchema = z.object({connection_id: z.string().uuid()}).strict();\n\nconst standardWebhookRouteRequestSchema = storedWebhookRequestBaseSchema\n  .extend({\n    route_id: z.enum(standardWebhookRouteIds),\n    path_parameters: emptyPathParametersSchema,\n  })\n  .strict();\n\nconst genericWebhookRouteRequestSchema = storedWebhookRequestBaseSchema\n  .extend({\n    route_id: z.literal('webhook.connection'),\n    path_parameters: connectionPathParametersSchema,\n  })\n  .strict();\n\nexport const storedWebhookRequestSchema = z.discriminatedUnion('route_id', [\n  standardWebhookRouteRequestSchema,\n  genericWebhookRouteRequestSchema,\n]);\nexport type StoredWebhookRequest = z.infer<typeof storedWebhookRequestSchema>;\n\nexport const webhookProcessingResultSchema = z.discriminatedUnion('outcome', [\n  z\n    .object({\n      outcome: z.literal('processed'),\n      deliveryId: z.string().min(1).optional(),\n      challenge: z.string().min(1).optional(),\n    })\n    .strict(),\n  z.object({outcome: z.literal('duplicate'), deliveryId: z.string().min(1)}).strict(),\n  z\n    .object({\n      outcome: z.literal('discarded'),\n      reason: z.enum([\n        'missing_required_input',\n        'invalid_signature',\n        'stale_at_receipt',\n        'malformed_payload',\n        'unsupported_event',\n        'connection_unavailable',\n      ]),\n      deliveryId: z.string().min(1).optional(),\n    })\n    .strict(),\n]);\nexport type WebhookProcessingResult = z.infer<typeof webhookProcessingResultSchema>;\n\n/** Processes one provider-neutral inbound webhook request. */\nexport interface WebhookRequestProcessor {\n  process(request: StoredWebhookRequest): Promise<WebhookProcessingResult>;\n}\n\nexport interface CreateStoredWebhookRequestInput {\n  requestId: string;\n  routeId: WebhookRouteId;\n  receivedAt: string;\n  rawQueryString: string;\n  headers: Record<string, string>;\n  body: Uint8Array;\n  connectionId?: string | undefined;\n}\n\nexport function encodeWebhookBody(body: Uint8Array): string {\n  let encoded = '';\n\n  for (let index = 0; index < body.length; index += 3) {\n    const first = body[index] ?? 0;\n    const second = body[index + 1];\n    const third = body[index + 2];\n    const combined = (first << 16) | ((second ?? 0) << 8) | (third ?? 0);\n\n    encoded += 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'[\n      (combined >> 18) & 63\n    ];\n    encoded += 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'[\n      (combined >> 12) & 63\n    ];\n    encoded +=\n      second === undefined\n        ? '='\n        : 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'[(combined >> 6) & 63];\n    encoded +=\n      third === undefined\n        ? '='\n        : 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'[combined & 63];\n  }\n\n  return encoded;\n}\n\nexport function decodeWebhookBody(body: z.infer<typeof webhookBodySchema>): Uint8Array {\n  const output = new Uint8Array(decodedBase64Length(body.data));\n  let outputIndex = 0;\n\n  for (let index = 0; index < body.data.length; index += 4) {\n    const chunk = body.data.slice(index, index + 4);\n    const values = chunk\n      .split('')\n      .map((character) =>\n        character === '='\n          ? 0\n          : 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'.indexOf(character),\n      );\n    const first = values[0] ?? 0;\n    const second = values[1] ?? 0;\n    const third = values[2] ?? 0;\n    const fourth = values[3] ?? 0;\n    const combined = (first << 18) | (second << 12) | (third << 6) | fourth;\n\n    output[outputIndex++] = (combined >> 16) & 255;\n    if (chunk[2] !== '=') output[outputIndex++] = (combined >> 8) & 255;\n    if (chunk[3] !== '=') output[outputIndex++] = combined & 255;\n  }\n\n  return output;\n}\n\nexport function createStoredWebhookRequest(\n  input: CreateStoredWebhookRequestInput,\n): StoredWebhookRequest {\n  const pathParameters =\n    input.routeId === 'webhook.connection' ? {connection_id: input.connectionId} : {};\n\n  return storedWebhookRequestSchema.parse({\n    schema_version: WEBHOOK_REQUEST_SCHEMA_VERSION,\n    request_id: input.requestId,\n    route_id: input.routeId,\n    received_at: input.receivedAt,\n    method: 'POST',\n    path_parameters: pathParameters,\n    raw_query_string: input.rawQueryString,\n    headers: input.headers,\n    body: {encoding: 'base64', data: encodeWebhookBody(input.body)},\n  });\n}\n\nexport function createMaximumSizeStoredWebhookRequestFixture(): StoredWebhookRequest {\n  const headers = Object.fromEntries(\n    Array.from({length: 8}, (_, index) => [\n      `x-fixture-${index}`,\n      'a'.repeat(index === 7 ? 8_000 : 8 * 1024),\n    ]),\n  );\n\n  return createStoredWebhookRequest({\n    requestId: '9b11d65a-f7e7-40ea-b421-06af012a9be5',\n    routeId: 'webhook.connection',\n    receivedAt: '2026-07-20T10:30:00.123Z',\n    rawQueryString: 'q='.padEnd(WEBHOOK_MAX_RAW_QUERY_STRING_LENGTH, 'q'),\n    headers,\n    body: new Uint8Array(WEBHOOK_MAX_RAW_BODY_BYTES),\n    connectionId: 'c0a8012e-0b6d-4d8f-8d5c-6d74102602b0',\n  });\n}\n"],"names":["z","WEBHOOK_REQUEST_SCHEMA_VERSION","WEBHOOK_MAX_RAW_BODY_BYTES","WEBHOOK_MAX_SERIALIZED_REQUEST_BYTES","WEBHOOK_MAX_HEADER_BYTES","WEBHOOK_MAX_RAW_QUERY_STRING_LENGTH","standardWebhookRouteIds","webhookRouteIds","webhookRouteIdSchema","enum","base64Pattern","decodedBase64Length","value","paddingLength","endsWith","length","headersByteLength","headers","TextEncoder","encode","JSON","stringify","byteLength","webhookHeadersSchema","record","string","max","refine","Object","keys","every","name","toLowerCase","webhookBodySchema","object","encoding","literal","data","Math","ceil","regex","strict","body","storedWebhookRequestBaseSchema","schema_version","request_id","uuid","received_at","datetime","offset","method","raw_query_string","emptyPathParametersSchema","connectionPathParametersSchema","connection_id","standardWebhookRouteRequestSchema","extend","route_id","path_parameters","genericWebhookRouteRequestSchema","storedWebhookRequestSchema","discriminatedUnion","webhookProcessingResultSchema","outcome","deliveryId","min","optional","challenge","reason","encodeWebhookBody","encoded","index","first","second","third","combined","undefined","decodeWebhookBody","output","Uint8Array","outputIndex","chunk","slice","values","split","map","character","indexOf","fourth","createStoredWebhookRequest","input","pathParameters","routeId","connectionId","parse","requestId","receivedAt","rawQueryString","createMaximumSizeStoredWebhookRequestFixture","fromEntries","Array","from","_","repeat","padEnd"],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-core-dto",
   "license": "MIT",
-  "version": "5.0.0",
+  "version": "8.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -19,18 +19,15 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./inter-module": {
+      "types": "./dist/inter-module.d.ts",
+      "default": "./dist/inter-module.js"
     }
   },
   "dependencies": {
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@shipfox/biome": "1.8.2",
-    "@shipfox/depcruise": "1.0.2",
-    "@shipfox/swc": "1.2.6",
-    "@shipfox/ts-config": "1.3.8",
-    "@shipfox/typescript": "1.1.7",
-    "@shipfox/vitest": "1.2.3"
+    "zod": "^4.4.3",
+    "@shipfox/inter-module": "0.2.0"
   },
   "scripts": {
     "build": "shipfox-swc",

package/src/index.ts

@@ -4,3 +4,4 @@ export * from '#events.js';
 export * from '#ports.js';
 export * from '#schemas/index.js';
 export * from '#slug.js';
+export * from '#webhooks.js';

package/src/inter-module.test.ts

@@ -0,0 +1,38 @@
+import {integrationsInterModuleContract} from './inter-module.js';
+
+describe('integrationsInterModuleContract', () => {
+  test('accepts a source repository lookup through the producer contract', () => {
+    const result = integrationsInterModuleContract.methods.resolveSourceRepository.output.parse({
+      connection: {
+        id: '00000000-0000-4000-8000-000000000001',
+        provider: 'github',
+        slug: 'github-main',
+      },
+      repository: {
+        externalRepositoryId: 'shipfox/project',
+        owner: 'shipfox',
+        name: 'project',
+        fullName: 'shipfox/project',
+        defaultBranch: 'main',
+        visibility: 'private',
+        cloneUrl: 'https://github.com/shipfox/project.git',
+        htmlUrl: 'https://github.com/shipfox/project',
+      },
+    });
+
+    expect(result.repository.fullName).toBe('shipfox/project');
+  });
+
+  test.each([
+    ['connection-not-found', {connectionId: '00000000-0000-4000-8000-000000000001'}],
+    ['provider-unavailable', {provider: 'github'}],
+    ['provider-failure', {reason: 'rate-limited', retryAfterSeconds: 30}],
+  ] as const)('defines the %s source failure', (code, details) => {
+    const schema =
+      integrationsInterModuleContract.methods.resolveSourceRepository.errors[
+        code as keyof typeof integrationsInterModuleContract.methods.resolveSourceRepository.errors
+      ];
+
+    expect(schema.parse(details)).toEqual(details);
+  });
+});

package/src/inter-module.ts

@@ -0,0 +1,129 @@
+import {defineInterModuleContract, type InterModuleClient} from '@shipfox/inter-module';
+import {z} from 'zod';
+
+const id = z.string().uuid();
+const provider = z.string().min(1);
+const capability = z.enum(['source_control', 'agent_tools']);
+const repository = z.object({
+  externalRepositoryId: z.string(),
+  owner: z.string(),
+  name: z.string(),
+  fullName: z.string(),
+  defaultBranch: z.string(),
+  visibility: z.enum(['public', 'private', 'internal', 'unknown']),
+  cloneUrl: z.string(),
+  htmlUrl: z.string(),
+});
+const sourceInput = z.object({workspaceId: id, connectionId: id, externalRepositoryId: z.string()});
+const providerError = z.object({
+  reason: z.string(),
+  retryAfterSeconds: z.number().int().positive().optional(),
+});
+const sourceErrors = {
+  'connection-not-found': z.object({connectionId: id}),
+  'connection-inactive': z.object({connectionId: id}),
+  'connection-workspace-mismatch': z.object({connectionId: id}),
+  'provider-unavailable': z.object({provider}),
+  'capability-unavailable': z.object({provider, capability}),
+  'checkout-unsupported': z.object({provider}),
+  'provider-failure': providerError,
+};
+
+/** Producer-owned synchronous operations for the Integrations bounded context. */
+export const integrationsInterModuleContract = defineInterModuleContract({
+  module: 'integrations',
+  methods: {
+    resolveSourceRepository: {
+      input: sourceInput,
+      output: z.object({connection: z.object({id, provider, slug: z.string()}), repository}),
+      errors: sourceErrors,
+    },
+    listSourceFiles: {
+      input: sourceInput.extend({
+        ref: z.string(),
+        prefix: z.string(),
+        limit: z.number().int().positive(),
+        cursor: z.string().optional(),
+      }),
+      output: z.object({
+        files: z.array(
+          z.object({path: z.string(), type: z.literal('file'), size: z.number().int().nullable()}),
+        ),
+        nextCursor: z.string().nullable(),
+      }),
+      errors: sourceErrors,
+    },
+    fetchSourceFile: {
+      input: sourceInput.extend({ref: z.string(), path: z.string()}),
+      output: z.object({path: z.string(), ref: z.string(), content: z.string()}),
+      errors: sourceErrors,
+    },
+    createCheckoutSpec: {
+      input: sourceInput.extend({
+        ref: z.string().optional(),
+        permissions: z.object({contents: z.enum(['read', 'write'])}).optional(),
+      }),
+      output: z.object({
+        repositoryUrl: z.string(),
+        ref: z.string(),
+        credentials: z
+          .object({username: z.string(), token: z.string(), expiresAt: z.string().datetime()})
+          .optional(),
+        gitAuthor: z.object({name: z.string(), email: z.string()}).optional(),
+      }),
+      errors: sourceErrors,
+    },
+    getAgentToolsContext: {
+      input: z.object({workspaceId: id, defaultConnectionId: id}),
+      output: z.object({
+        selectionCatalogs: z.array(
+          z.object({
+            provider,
+            selectors: z.array(
+              z.object({
+                token: z.string(),
+                kind: z.enum(['family', 'family_wildcard', 'method', 'standalone']),
+                sensitivity: z.enum(['read', 'write']),
+                sensitive: z.boolean(),
+              }),
+            ),
+          }),
+        ),
+        catalogs: z.array(
+          z.object({
+            provider,
+            tools: z.array(
+              z.object({
+                id: z.string(),
+                description: z.string(),
+                sensitivity: z.enum(['read', 'write']),
+                sensitive: z.boolean(),
+                requiredScope: z.unknown(),
+                inputSchema: z.record(z.string(), z.unknown()),
+                outputSchema: z.record(z.string(), z.unknown()).optional(),
+                methods: z
+                  .array(
+                    z.object({
+                      id: z.string(),
+                      description: z.string(),
+                      sensitivity: z.enum(['read', 'write']),
+                      sensitive: z.boolean(),
+                      requiredScope: z.unknown(),
+                    }),
+                  )
+                  .optional(),
+              }),
+            ),
+          }),
+        ),
+        workspaceConnections: z.array(
+          z.object({slug: z.string(), id, provider, capabilities: z.array(capability)}),
+        ),
+        defaultConnection: z.object({id, slug: z.string(), provider}).nullable(),
+      }),
+      errors: sourceErrors,
+    },
+  },
+});
+
+export type IntegrationsModuleClient = InterModuleClient<typeof integrationsInterModuleContract>;

package/src/webhooks.test.ts

@@ -0,0 +1,92 @@
+import {
+  createMaximumSizeStoredWebhookRequestFixture,
+  createStoredWebhookRequest,
+  decodeWebhookBody,
+  storedWebhookRequestSchema,
+  WEBHOOK_MAX_RAW_BODY_BYTES,
+  WEBHOOK_MAX_SERIALIZED_REQUEST_BYTES,
+  webhookProcessingResultSchema,
+} from './webhooks.js';
+
+const requestId = '9b11d65a-f7e7-40ea-b421-06af012a9be5';
+const receivedAt = '2026-07-20T10:30:00.123Z';
+
+describe('storedWebhookRequestSchema', () => {
+  it('round-trips exact body bytes from a direct adapter through the stored contract', () => {
+    const body = new Uint8Array([0, 255, 5, 128, 42]);
+    const directRequest = createStoredWebhookRequest({
+      requestId,
+      routeId: 'slack.command',
+      receivedAt,
+      rawQueryString: '',
+      headers: {'content-type': 'application/x-www-form-urlencoded'},
+      body,
+    });
+
+    const queuedRequest = storedWebhookRequestSchema.parse(
+      JSON.parse(JSON.stringify(directRequest)),
+    );
+
+    expect(queuedRequest.received_at).toBe(receivedAt);
+    expect(decodeWebhookBody(queuedRequest.body)).toEqual(body);
+  });
+
+  it('rejects unknown fields, routes, and schema versions', () => {
+    const request = createStoredWebhookRequest({
+      requestId,
+      routeId: 'github',
+      receivedAt,
+      rawQueryString: '',
+      headers: {'content-type': 'application/json'},
+      body: new Uint8Array(),
+    });
+
+    expect(storedWebhookRequestSchema.safeParse({...request, added_later: true}).success).toBe(
+      false,
+    );
+    expect(storedWebhookRequestSchema.safeParse({...request, schema_version: 2}).success).toBe(
+      false,
+    );
+    expect(storedWebhookRequestSchema.safeParse({...request, route_id: 'stripe'}).success).toBe(
+      false,
+    );
+  });
+
+  it('requires a generic connection identifier only for the generic route', () => {
+    const genericRequest = createStoredWebhookRequest({
+      requestId,
+      routeId: 'webhook.connection',
+      receivedAt,
+      rawQueryString: '',
+      headers: {'content-type': 'application/json'},
+      body: new Uint8Array(),
+      connectionId: 'c0a8012e-0b6d-4d8f-8d5c-6d74102602b0',
+    });
+
+    const withoutConnectionId = {
+      ...genericRequest,
+      path_parameters: {},
+    };
+
+    expect(storedWebhookRequestSchema.safeParse(withoutConnectionId).success).toBe(false);
+  });
+
+  it('keeps the maximum-size fixture below the SQS message limit', () => {
+    const fixture = createMaximumSizeStoredWebhookRequestFixture();
+    const serializedSize = new TextEncoder().encode(JSON.stringify(fixture)).byteLength;
+
+    expect(decodeWebhookBody(fixture.body)).toHaveLength(WEBHOOK_MAX_RAW_BODY_BYTES);
+    expect(serializedSize).toBeLessThan(WEBHOOK_MAX_SERIALIZED_REQUEST_BYTES);
+  });
+});
+
+describe('webhookProcessingResultSchema', () => {
+  it.each([
+    {outcome: 'processed'},
+    {outcome: 'processed', challenge: 'slack-url-verification'},
+    {outcome: 'duplicate', deliveryId: 'delivery-1'},
+    {outcome: 'discarded', reason: 'invalid_signature'},
+  ])('accepts the %s processing outcome', (result) => {
+    expect(webhookProcessingResultSchema.safeParse(result).success).toBe(true);
+  });
+});