@shipfox/api-agent-access-dto 20.2.0 → 21.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-agent-access-dto",
   "license": "MIT",
-  "version": "20.2.0",
+  "version": "21.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -11,25 +11,35 @@
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "imports": {
+    "#test/*": "./test/*",
+    "#*": {
+      "workspace-source": "./src/*",
+      "default": "./dist/*"
+    }
+  },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "workspace-source": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
     }
   },
   "dependencies": {
     "zod": "^4.4.3"
   },
-  "imports": {
-    "#*": "./dist/*"
-  },
-  "shipfox": {
-    "architecture": {
-      "schema": 1,
-      "realm": "source-available",
-      "kind": "dto",
-      "context": "agent-access"
-    }
+  "devDependencies": {
+    "@shipfox/biome": "1.10.1",
+    "@shipfox/depcruise": "1.0.5",
+    "@shipfox/swc": "1.2.8",
+    "@shipfox/ts-config": "1.3.9",
+    "@shipfox/typescript": "1.1.10",
+    "@shipfox/vitest": "1.2.6"
   },
   "scripts": {
     "build": "shipfox-swc",

package/src/index.ts

@@ -1,3 +1,22 @@
+export {
+  AGENT_ACCESS_FACET_MAX_ITEMS,
+  AGENT_ACCESS_FACET_VALUE_MAX_BYTES,
+  AGENT_ACCESS_SERIALIZED_JSON_MAX_BYTES,
+  AGENT_ACCESS_TRIGGER_DECISION_MAX_ITEMS,
+  AGENT_ACCESS_TRIGGER_REPLAY_MAX_ITEMS,
+  type GetTriggerEventFacetsInputDto,
+  type GetTriggerEventFacetsResultDto,
+  type GetTriggerEventInputDto,
+  type GetTriggerEventResultDto,
+  getTriggerEventFacetsInputJsonSchema,
+  getTriggerEventFacetsInputSchema,
+  getTriggerEventFacetsResultJsonSchema,
+  getTriggerEventFacetsResultSchema,
+  getTriggerEventInputJsonSchema,
+  getTriggerEventInputSchema,
+  getTriggerEventResultJsonSchema,
+  getTriggerEventResultSchema,
+} from './schemas/diagnostic-tools.js';
 export {
   AGENT_ACCESS_ERROR_CODE_MAX_LENGTH,
   AGENT_ACCESS_ERROR_MESSAGE_MAX_LENGTH,
@@ -10,3 +29,45 @@ export {
   agentAccessErrorSchema,
   agentAccessOutputSchema,
 } from './schemas/envelope.js';
+export {
+  AGENT_ACCESS_ANNOTATION_BODY_MAX_BYTES,
+  AGENT_ACCESS_CONNECTION_NAME_MAX_BYTES,
+  AGENT_ACCESS_DEFAULT_PAGE_LIMIT,
+  AGENT_ACCESS_DIAGNOSTIC_CODE_MAX_BYTES,
+  AGENT_ACCESS_DIAGNOSTIC_MAX_ITEMS,
+  AGENT_ACCESS_DIAGNOSTIC_MESSAGE_MAX_BYTES,
+  AGENT_ACCESS_DIAGNOSTIC_PATH_MAX_BYTES,
+  AGENT_ACCESS_PAGE_LIMIT_MAX,
+  AGENT_ACCESS_RESPONSE_MAX_BYTES,
+  AGENT_ACCESS_TEXT_MAX_BYTES,
+  type GetRunAnnotationsInputDto,
+  type GetRunAnnotationsResultDto,
+  getRunAnnotationsInputJsonSchema,
+  getRunAnnotationsInputSchema,
+  getRunAnnotationsResultJsonSchema,
+  getRunAnnotationsResultSchema,
+  type ListProjectsInputDto,
+  type ListProjectsResultDto,
+  type ListTriggerEventsInputDto,
+  type ListTriggerEventsResultDto,
+  type ListWorkflowDefinitionsInputDto,
+  type ListWorkflowDefinitionsResultDto,
+  type ListWorkflowRunsInputDto,
+  type ListWorkflowRunsResultDto,
+  listProjectsInputJsonSchema,
+  listProjectsInputSchema,
+  listProjectsResultJsonSchema,
+  listProjectsResultSchema,
+  listTriggerEventsInputJsonSchema,
+  listTriggerEventsInputSchema,
+  listTriggerEventsResultJsonSchema,
+  listTriggerEventsResultSchema,
+  listWorkflowDefinitionsInputJsonSchema,
+  listWorkflowDefinitionsInputSchema,
+  listWorkflowDefinitionsResultJsonSchema,
+  listWorkflowDefinitionsResultSchema,
+  listWorkflowRunsInputJsonSchema,
+  listWorkflowRunsInputSchema,
+  listWorkflowRunsResultJsonSchema,
+  listWorkflowRunsResultSchema,
+} from './schemas/paged-tools.js';

package/src/schemas/diagnostic-tools.ts

@@ -0,0 +1,266 @@
+import {z} from 'zod';
+import type {AgentAccessObjectSchema} from './envelope.js';
+import {
+  AGENT_ACCESS_CONNECTION_NAME_MAX_BYTES,
+  AGENT_ACCESS_TEXT_MAX_BYTES,
+} from './paged-tools.js';
+
+export const AGENT_ACCESS_SERIALIZED_JSON_MAX_BYTES = 16 * 1024;
+export const AGENT_ACCESS_TRIGGER_DECISION_MAX_ITEMS = 50;
+export const AGENT_ACCESS_TRIGGER_REPLAY_MAX_ITEMS = 20;
+export const AGENT_ACCESS_FACET_MAX_ITEMS = 50;
+export const AGENT_ACCESS_FACET_VALUE_MAX_BYTES = 256;
+
+const idSchema = z.string().uuid();
+const dateTimeSchema = z.string().datetime();
+const utf8Encoder = new TextEncoder();
+
+const utf8CappedString = (maxBytes: number) =>
+  z
+    .string()
+    .max(maxBytes)
+    .refine((value) => utf8Encoder.encode(value).byteLength <= maxBytes, {
+      message: `String must contain at most ${maxBytes} UTF-8 bytes`,
+    });
+
+const textSchema = utf8CappedString(AGENT_ACCESS_TEXT_MAX_BYTES);
+const shortTextSchema = utf8CappedString(AGENT_ACCESS_CONNECTION_NAME_MAX_BYTES);
+const serializedJsonSchema = utf8CappedString(AGENT_ACCESS_SERIALIZED_JSON_MAX_BYTES).refine(
+  isSerializedJson,
+  {message: 'String must contain valid serialized JSON'},
+);
+
+export const getTriggerEventInputSchema = z.object({event_id: idSchema}).strict();
+
+export const getTriggerEventFacetsInputSchema = z.object({}).strict();
+
+export type GetTriggerEventInputDto = z.infer<typeof getTriggerEventInputSchema>;
+export type GetTriggerEventFacetsInputDto = z.infer<typeof getTriggerEventFacetsInputSchema>;
+
+const triggerOriginSchema = z.enum(['integration', 'manual', 'cron', 'dev']);
+const triggerOutcomeSchema = z.enum(['received', 'routed', 'discarded', 'failed', 'errored']);
+const triggerDecisionOutcomeSchema = z.enum(['triggered', 'filter-error', 'dispatch-error']);
+const triggerDecisionSchema = z
+  .object({
+    id: idSchema,
+    subscription_kind: z.enum(['trigger', 'listener', 'dev']),
+    outcome: triggerDecisionOutcomeSchema,
+    reason: textSchema.nullable(),
+    workflow_definition_id: idSchema.nullable(),
+    project_id: idSchema.nullable(),
+    workflow_run_id: idSchema.nullable(),
+    job_id: idSchema.nullable(),
+  })
+  .strict();
+
+const triggerReplaySchema = z
+  .object({
+    id: idSchema,
+    workflow_run_id: idSchema.nullable(),
+    created_at: dateTimeSchema,
+  })
+  .strict();
+
+export const getTriggerEventResultSchema = z
+  .object({
+    id: idSchema,
+    origin: triggerOriginSchema,
+    provider: textSchema.nullable(),
+    source: textSchema,
+    event: textSchema,
+    outcome: triggerOutcomeSchema,
+    matched_count: z.number().int().nonnegative(),
+    connection_id: idSchema.nullable(),
+    connection_name: shortTextSchema.nullable(),
+    replay_of_event_id: idSchema.nullable(),
+    received_at: dateTimeSchema,
+    processed_at: dateTimeSchema.nullable(),
+    payload_preview: serializedJsonSchema,
+    payload_preview_truncated: z.literal(true).optional(),
+    payload_preview_total_bytes: z.number().int().nonnegative().optional(),
+    decisions: z.array(triggerDecisionSchema).max(AGENT_ACCESS_TRIGGER_DECISION_MAX_ITEMS),
+    decisions_truncated: z.literal(true).optional(),
+    decisions_total_count: z.number().int().nonnegative(),
+    replays: z.array(triggerReplaySchema).max(AGENT_ACCESS_TRIGGER_REPLAY_MAX_ITEMS),
+    replays_truncated: z.literal(true).optional(),
+    replays_total_count: z.number().int().nonnegative(),
+  })
+  .strict();
+
+const facetSchema = z
+  .object({
+    value: utf8CappedString(AGENT_ACCESS_FACET_VALUE_MAX_BYTES),
+    count: z.number().int().nonnegative(),
+  })
+  .strict();
+
+export const getTriggerEventFacetsResultSchema = z
+  .object({
+    sources: z.array(facetSchema).max(AGENT_ACCESS_FACET_MAX_ITEMS),
+    events: z.array(facetSchema).max(AGENT_ACCESS_FACET_MAX_ITEMS),
+    origins: z.array(facetSchema).max(AGENT_ACCESS_FACET_MAX_ITEMS),
+  })
+  .strict();
+
+export type GetTriggerEventResultDto = z.infer<typeof getTriggerEventResultSchema>;
+export type GetTriggerEventFacetsResultDto = z.infer<typeof getTriggerEventFacetsResultSchema>;
+
+const uuid = {type: 'string', format: 'uuid'} as const;
+const dateTime = {type: 'string', format: 'date-time'} as const;
+const text = {type: 'string', maxLength: AGENT_ACCESS_TEXT_MAX_BYTES} as const;
+const shortText = {
+  type: 'string',
+  maxLength: AGENT_ACCESS_CONNECTION_NAME_MAX_BYTES,
+} as const;
+const serializedJson = {
+  type: 'string',
+  maxLength: AGENT_ACCESS_SERIALIZED_JSON_MAX_BYTES,
+  contentMediaType: 'application/json',
+} as const;
+const nullable = (schema: Record<string, unknown>) => ({anyOf: [schema, {type: 'null'}]}) as const;
+
+export const getTriggerEventInputJsonSchema = {
+  type: 'object',
+  properties: {event_id: uuid},
+  required: ['event_id'],
+  additionalProperties: false,
+} as const satisfies AgentAccessObjectSchema;
+
+function isSerializedJson(value: string): boolean {
+  try {
+    JSON.parse(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export const getTriggerEventFacetsInputJsonSchema = {
+  type: 'object',
+  properties: {},
+  additionalProperties: false,
+} as const satisfies AgentAccessObjectSchema;
+
+const triggerDecisionJsonSchema = {
+  type: 'object',
+  properties: {
+    id: uuid,
+    subscription_kind: {type: 'string', enum: ['trigger', 'listener', 'dev']},
+    outcome: {type: 'string', enum: ['triggered', 'filter-error', 'dispatch-error']},
+    reason: nullable(text),
+    workflow_definition_id: nullable(uuid),
+    project_id: nullable(uuid),
+    workflow_run_id: nullable(uuid),
+    job_id: nullable(uuid),
+  },
+  required: [
+    'id',
+    'subscription_kind',
+    'outcome',
+    'reason',
+    'workflow_definition_id',
+    'project_id',
+    'workflow_run_id',
+    'job_id',
+  ],
+  additionalProperties: false,
+} as const;
+
+const triggerReplayJsonSchema = {
+  type: 'object',
+  properties: {
+    id: uuid,
+    workflow_run_id: nullable(uuid),
+    created_at: dateTime,
+  },
+  required: ['id', 'workflow_run_id', 'created_at'],
+  additionalProperties: false,
+} as const;
+
+export const getTriggerEventResultJsonSchema = {
+  type: 'object',
+  properties: {
+    id: uuid,
+    origin: {type: 'string', enum: ['integration', 'manual', 'cron', 'dev']},
+    provider: nullable(text),
+    source: text,
+    event: text,
+    outcome: {type: 'string', enum: ['received', 'routed', 'discarded', 'failed', 'errored']},
+    matched_count: {type: 'integer', minimum: 0},
+    connection_id: nullable(uuid),
+    connection_name: nullable(shortText),
+    replay_of_event_id: nullable(uuid),
+    received_at: dateTime,
+    processed_at: nullable(dateTime),
+    payload_preview: serializedJson,
+    payload_preview_truncated: {const: true},
+    payload_preview_total_bytes: {type: 'integer', minimum: 0},
+    decisions: {
+      type: 'array',
+      maxItems: AGENT_ACCESS_TRIGGER_DECISION_MAX_ITEMS,
+      items: triggerDecisionJsonSchema,
+    },
+    decisions_truncated: {const: true},
+    decisions_total_count: {type: 'integer', minimum: 0},
+    replays: {
+      type: 'array',
+      maxItems: AGENT_ACCESS_TRIGGER_REPLAY_MAX_ITEMS,
+      items: triggerReplayJsonSchema,
+    },
+    replays_truncated: {const: true},
+    replays_total_count: {type: 'integer', minimum: 0},
+  },
+  required: [
+    'id',
+    'origin',
+    'provider',
+    'source',
+    'event',
+    'outcome',
+    'matched_count',
+    'connection_id',
+    'connection_name',
+    'replay_of_event_id',
+    'received_at',
+    'processed_at',
+    'payload_preview',
+    'decisions',
+    'decisions_total_count',
+    'replays',
+    'replays_total_count',
+  ],
+  additionalProperties: false,
+} as const satisfies AgentAccessObjectSchema;
+
+const facetJsonSchema = {
+  type: 'object',
+  properties: {
+    value: {type: 'string', maxLength: AGENT_ACCESS_FACET_VALUE_MAX_BYTES},
+    count: {type: 'integer', minimum: 0},
+  },
+  required: ['value', 'count'],
+  additionalProperties: false,
+} as const;
+
+export const getTriggerEventFacetsResultJsonSchema = {
+  type: 'object',
+  properties: {
+    sources: {
+      type: 'array',
+      maxItems: AGENT_ACCESS_FACET_MAX_ITEMS,
+      items: facetJsonSchema,
+    },
+    events: {
+      type: 'array',
+      maxItems: AGENT_ACCESS_FACET_MAX_ITEMS,
+      items: facetJsonSchema,
+    },
+    origins: {
+      type: 'array',
+      maxItems: AGENT_ACCESS_FACET_MAX_ITEMS,
+      items: facetJsonSchema,
+    },
+  },
+  required: ['sources', 'events', 'origins'],
+  additionalProperties: false,
+} as const satisfies AgentAccessObjectSchema;

package/src/schemas/paged-tools.test.ts

@@ -0,0 +1,106 @@
+import {
+  AGENT_ACCESS_DEFAULT_PAGE_LIMIT,
+  getRunAnnotationsInputSchema,
+  getRunAnnotationsResultSchema,
+  listProjectsInputSchema,
+  listProjectsResultJsonSchema,
+  listProjectsResultSchema,
+  listTriggerEventsInputSchema,
+  listWorkflowDefinitionsResultSchema,
+  listWorkflowRunsInputSchema,
+} from './paged-tools.js';
+
+const projectId = '00000000-0000-4000-8000-000000000001';
+
+describe('paged agent-access schemas', () => {
+  test('defaults page size and rejects gateway-owned workspace arguments', () => {
+    expect(listProjectsInputSchema.parse({})).toEqual({limit: AGENT_ACCESS_DEFAULT_PAGE_LIMIT});
+    expect(listProjectsInputSchema.safeParse({workspace_id: projectId}).success).toBe(false);
+  });
+
+  test('validates date windows and strict list filters', () => {
+    expect(
+      listWorkflowRunsInputSchema.safeParse({
+        project_id: projectId,
+        created_from: '2026-08-02T00:00:00.000Z',
+        created_to: '2026-08-01T00:00:00.000Z',
+      }).success,
+    ).toBe(false);
+    expect(listTriggerEventsInputSchema.safeParse({source: ['push'], extra: true}).success).toBe(
+      false,
+    );
+  });
+
+  test('keeps output schemas as one strict object envelope result', () => {
+    expect(listProjectsResultJsonSchema).not.toHaveProperty('oneOf');
+    expect(listProjectsResultJsonSchema.properties.projects).toBeDefined();
+    expect(listProjectsResultSchema.safeParse({projects: [], next_cursor: null}).success).toBe(
+      true,
+    );
+    expect(
+      listProjectsResultSchema.safeParse({projects: [], next_cursor: null, workspace_id: projectId})
+        .success,
+    ).toBe(false);
+  });
+
+  test('requires annotation body truncation metadata to remain a boolean marker and byte count', () => {
+    const valid = {
+      id: projectId,
+      origin_step_id: '00000000-0000-4000-8000-000000000002',
+      origin_step_attempt: 1,
+      job_execution_id: '00000000-0000-4000-8000-000000000003',
+      sequence: 1,
+      created_at: '2026-08-01T00:00:00.000Z',
+      body: 'body',
+    };
+    expect(
+      getRunAnnotationsResultSchema.safeParse({annotations: [valid], next_cursor: null}).success,
+    ).toBe(true);
+    const truncated = {...valid, body_truncated: true, body_total_bytes: 8_192};
+    expect(
+      getRunAnnotationsResultSchema.safeParse({
+        annotations: [truncated],
+        next_cursor: null,
+      }).success,
+    ).toBe(true);
+    expect(
+      getRunAnnotationsResultSchema.safeParse({
+        annotations: [{...truncated, body_truncated: false}],
+        next_cursor: null,
+      }).success,
+    ).toBe(false);
+    expect(
+      getRunAnnotationsResultSchema.safeParse({
+        annotations: [{...truncated, body_total_bytes: '8192'}],
+        next_cursor: null,
+      }).success,
+    ).toBe(false);
+    expect(getRunAnnotationsInputSchema.safeParse({run_id: projectId, attempt: 0}).success).toBe(
+      false,
+    );
+  });
+
+  test('keeps definition sync error codes aligned with the producer enum', () => {
+    const sync = {
+      ref: null,
+      status: 'failed' as const,
+      last_sync_at: '2026-08-01T00:00:00.000Z',
+      started_at: null,
+      finished_at: '2026-08-01T00:00:00.000Z',
+      last_error_code: 'provider-timeout',
+      last_error_message: 'timed out',
+      diagnostics: {error_count: 0, warning_count: 0, items: []},
+    };
+    expect(
+      listWorkflowDefinitionsResultSchema.safeParse({definitions: [], sync, next_cursor: null})
+        .success,
+    ).toBe(true);
+    expect(
+      listWorkflowDefinitionsResultSchema.safeParse({
+        definitions: [],
+        sync: {...sync, last_error_code: 'untrusted-instruction'},
+        next_cursor: null,
+      }).success,
+    ).toBe(false);
+  });
+});