@shipfox/api-workflows-dto 12.6.0 → 13.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workflows-dto",
   "license": "MIT",
-  "version": "12.6.0",
+  "version": "13.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",

package/src/events.test.ts

@@ -1,7 +1,8 @@
 import {
   WORKFLOWS_JOB_ACTIVATED,
   WORKFLOWS_JOB_EVENT_DELIVERED,
-  WORKFLOWS_JOB_EXECUTION_TIMED_OUT,
+  WORKFLOWS_JOB_EXECUTION_QUEUED,
+  WORKFLOWS_JOB_EXECUTION_TERMINATED,
   WORKFLOWS_JOB_STEPS_SETTLED,
   WORKFLOWS_JOB_TERMINATED,
   WORKFLOWS_STEP_ATTEMPT_TERMINATED,
@@ -12,7 +13,8 @@ import {
   workflowsEventSchemas,
   workflowsJobActivatedSchema,
   workflowsJobEventDeliveredSchema,
-  workflowsJobExecutionTimedOutSchema,
+  workflowsJobExecutionQueuedSchema,
+  workflowsJobExecutionTerminatedSchema,
   workflowsJobStepsSettledSchema,
   workflowsJobTerminatedSchema,
   workflowsStepAttemptTerminatedSchema,
@@ -52,10 +54,25 @@ const validRunCancelled = {
   projectId: 'proj-1',
 };
 
-const validJobExecutionTimedOut = {
+const validJobExecutionQueued = {
   jobId: 'job-1',
   jobExecutionId: 'execution-1',
+  workflowRunId: 'run-1',
+  workflowRunAttemptId: 'attempt-1',
+  workspaceId: 'ws-1',
+  projectId: 'project-1',
+  requiredLabels: ['linux'],
+  queuedAt: '2026-08-11T08:00:00.000Z',
+};
+
+const validJobExecutionTerminated = {
+  jobId: 'job-1',
+  jobExecutionId: 'execution-1',
+  workflowRunId: 'run-1',
   workflowRunAttemptId: 'attempt-1',
+  status: 'cancelled',
+  statusReason: 'run_cancelled',
+  statusReasonMessage: null,
 };
 
 const validJobActivated = {
@@ -187,6 +204,24 @@ describe('workflowsJobTerminatedSchema', () => {
   });
 });
 
+describe('workflowsJobExecutionTerminatedSchema', () => {
+  it('parses a terminal job-execution fact', () => {
+    const result = workflowsJobExecutionTerminatedSchema.parse(validJobExecutionTerminated);
+
+    expect(result).toEqual(validJobExecutionTerminated);
+  });
+
+  it('rejects a non-terminal status', () => {
+    const parse = () =>
+      workflowsJobExecutionTerminatedSchema.parse({
+        ...validJobExecutionTerminated,
+        status: 'running',
+      });
+
+    expect(parse).toThrow();
+  });
+});
+
 describe('workflowsWorkflowRunTerminatedSchema', () => {
   it('parses a valid run-terminated payload unchanged', () => {
     const result = workflowsWorkflowRunTerminatedSchema.parse(validRunTerminated);
@@ -322,9 +357,9 @@ describe.each([
     'projectId',
   ],
   [
-    'workflowsJobExecutionTimedOutSchema',
-    workflowsJobExecutionTimedOutSchema,
-    validJobExecutionTimedOut,
+    'workflowsJobExecutionQueuedSchema',
+    workflowsJobExecutionQueuedSchema,
+    validJobExecutionQueued,
     'jobId',
   ],
   ['workflowsJobActivatedSchema', workflowsJobActivatedSchema, validJobActivated, 'mode'],
@@ -379,7 +414,8 @@ describe('workflowsEventSchemas', () => {
         WORKFLOWS_WORKFLOW_RUN_ATTEMPT_CREATED,
         WORKFLOWS_WORKFLOW_RUN_TERMINATED,
         WORKFLOWS_WORKFLOW_RUN_CANCELLED,
-        WORKFLOWS_JOB_EXECUTION_TIMED_OUT,
+        WORKFLOWS_JOB_EXECUTION_QUEUED,
+        WORKFLOWS_JOB_EXECUTION_TERMINATED,
         WORKFLOWS_JOB_ACTIVATED,
         WORKFLOWS_JOB_EVENT_DELIVERED,
         WORKFLOWS_JOB_TERMINATED,

package/src/events.ts

@@ -11,7 +11,11 @@ export const WORKFLOWS_WORKFLOW_RUN_ATTEMPT_CREATED =
 export const WORKFLOWS_WORKFLOW_RUN_TERMINATED = 'workflows.workflow_run.terminated' as const;
 // Intent fact for cooperative run cancellation. Consumers use this to stop orchestration.
 export const WORKFLOWS_WORKFLOW_RUN_CANCELLED = 'workflows.workflow_run.cancelled' as const;
-export const WORKFLOWS_JOB_EXECUTION_TIMED_OUT = 'workflows.job_execution.timed_out' as const;
+// Terminal fact for a job execution, written in the same transaction as every
+// transition to succeeded, failed, or cancelled.
+export const WORKFLOWS_JOB_EXECUTION_TERMINATED = 'workflows.job_execution.terminated' as const;
+// Scheduling fact for a job execution, written when workflows first records it as queued.
+export const WORKFLOWS_JOB_EXECUTION_QUEUED = 'workflows.job_execution.queued' as const;
 export const WORKFLOWS_JOB_ACTIVATED = 'workflows.job.activated' as const;
 export const WORKFLOWS_JOB_EVENT_DELIVERED = 'workflows.job_event.delivered' as const;
 // Terminal fact for a job: the single reliable "this job is over" signal, written in
@@ -65,13 +69,29 @@ export type WorkflowsWorkflowRunCancelledEventDto = z.infer<
   typeof workflowsWorkflowRunCancelledSchema
 >;
 
-export const workflowsJobExecutionTimedOutSchema = z.object({
+export const workflowsJobExecutionQueuedSchema = z.object({
   jobId: nonEmptyStringSchema,
   jobExecutionId: nonEmptyStringSchema,
+  workflowRunId: nonEmptyStringSchema,
+  workflowRunAttemptId: nonEmptyStringSchema,
+  workspaceId: nonEmptyStringSchema,
+  projectId: nonEmptyStringSchema,
+  requiredLabels: z.array(nonEmptyStringSchema).min(1),
+  queuedAt: z.string().datetime(),
+});
+export type WorkflowsJobExecutionQueuedEventDto = z.infer<typeof workflowsJobExecutionQueuedSchema>;
+
+export const workflowsJobExecutionTerminatedSchema = z.object({
+  jobId: nonEmptyStringSchema,
+  jobExecutionId: nonEmptyStringSchema,
+  workflowRunId: nonEmptyStringSchema,
   workflowRunAttemptId: nonEmptyStringSchema,
+  status: workflowRunTerminalStatusSchema,
+  statusReason: jobStatusReasonSchema.nullable(),
+  statusReasonMessage: z.string().nullable().optional(),
 });
-export type WorkflowsJobExecutionTimedOutEventDto = z.infer<
-  typeof workflowsJobExecutionTimedOutSchema
+export type WorkflowsJobExecutionTerminatedEventDto = z.infer<
+  typeof workflowsJobExecutionTerminatedSchema
 >;
 
 const workflowsJobActivatedBaseSchema = z.object({
@@ -196,7 +216,8 @@ export interface WorkflowsEventMapDto {
   [WORKFLOWS_WORKFLOW_RUN_ATTEMPT_CREATED]: WorkflowsWorkflowRunAttemptCreatedEventDto;
   [WORKFLOWS_WORKFLOW_RUN_TERMINATED]: WorkflowsWorkflowRunTerminatedEventDto;
   [WORKFLOWS_WORKFLOW_RUN_CANCELLED]: WorkflowsWorkflowRunCancelledEventDto;
-  [WORKFLOWS_JOB_EXECUTION_TIMED_OUT]: WorkflowsJobExecutionTimedOutEventDto;
+  [WORKFLOWS_JOB_EXECUTION_QUEUED]: WorkflowsJobExecutionQueuedEventDto;
+  [WORKFLOWS_JOB_EXECUTION_TERMINATED]: WorkflowsJobExecutionTerminatedEventDto;
   [WORKFLOWS_JOB_ACTIVATED]: WorkflowsJobActivatedEventDto;
   [WORKFLOWS_JOB_EVENT_DELIVERED]: WorkflowsJobEventDeliveredEventDto;
   [WORKFLOWS_JOB_TERMINATED]: WorkflowsJobTerminatedEventDto;
@@ -209,7 +230,8 @@ export const workflowsEventSchemas = {
   [WORKFLOWS_WORKFLOW_RUN_ATTEMPT_CREATED]: workflowsWorkflowRunAttemptCreatedSchema,
   [WORKFLOWS_WORKFLOW_RUN_TERMINATED]: workflowsWorkflowRunTerminatedSchema,
   [WORKFLOWS_WORKFLOW_RUN_CANCELLED]: workflowsWorkflowRunCancelledSchema,
-  [WORKFLOWS_JOB_EXECUTION_TIMED_OUT]: workflowsJobExecutionTimedOutSchema,
+  [WORKFLOWS_JOB_EXECUTION_QUEUED]: workflowsJobExecutionQueuedSchema,
+  [WORKFLOWS_JOB_EXECUTION_TERMINATED]: workflowsJobExecutionTerminatedSchema,
   [WORKFLOWS_JOB_ACTIVATED]: workflowsJobActivatedSchema,
   [WORKFLOWS_JOB_EVENT_DELIVERED]: workflowsJobEventDeliveredSchema,
   [WORKFLOWS_JOB_TERMINATED]: workflowsJobTerminatedSchema,

package/src/index.ts

@@ -128,7 +128,8 @@ export {
   terminalStatusSchema,
   WORKFLOWS_JOB_ACTIVATED,
   WORKFLOWS_JOB_EVENT_DELIVERED,
-  WORKFLOWS_JOB_EXECUTION_TIMED_OUT,
+  WORKFLOWS_JOB_EXECUTION_QUEUED,
+  WORKFLOWS_JOB_EXECUTION_TERMINATED,
   WORKFLOWS_JOB_STEPS_SETTLED,
   WORKFLOWS_JOB_TERMINATED,
   WORKFLOWS_STEP_ATTEMPT_TERMINATED,
@@ -139,7 +140,8 @@ export {
   type WorkflowsEventMapDto,
   type WorkflowsJobActivatedEventDto,
   type WorkflowsJobEventDeliveredEventDto,
-  type WorkflowsJobExecutionTimedOutEventDto,
+  type WorkflowsJobExecutionQueuedEventDto,
+  type WorkflowsJobExecutionTerminatedEventDto,
   type WorkflowsJobStepsSettledEventDto,
   type WorkflowsJobTerminatedEventDto,
   type WorkflowsStepAttemptTerminatedEventDto,
@@ -151,7 +153,8 @@ export {
   workflowsEventSchemas,
   workflowsJobActivatedSchema,
   workflowsJobEventDeliveredSchema,
-  workflowsJobExecutionTimedOutSchema,
+  workflowsJobExecutionQueuedSchema,
+  workflowsJobExecutionTerminatedSchema,
   workflowsJobStepsSettledSchema,
   workflowsJobTerminatedSchema,
   workflowsStepAttemptTerminatedSchema,

package/src/schemas/workflow-run-detail.ts

@@ -72,6 +72,14 @@ export type WorkflowRunJobDetailDto = z.infer<typeof workflowRunJobDetailDtoSche
 export const workflowRunDetailResponseSchema = workflowRunResponseSchema.extend({
   run_attempt: workflowRunAttemptDtoSchema,
   jobs: z.array(workflowRunJobDetailDtoSchema),
+  /**
+   * Whether any job execution of this attempt reached its runner. Redundant with the executions
+   * below, and deliberately so: the server decides it once for both this response and the run
+   * list, which is what keeps the two surfaces from reaching different answers.
+   *
+   * Defaults to started for the same rollout reason as the list item's copy.
+   */
+  has_started_job_execution: z.boolean().optional().default(true),
 });
 
 export type WorkflowRunDetailResponseDto = z.infer<typeof workflowRunDetailResponseSchema>;

package/src/schemas/workflow-run.test.ts

@@ -120,6 +120,7 @@ describe('workflow run list item schema', () => {
       source_snapshot: null,
       jobs: [jobDto(0)],
       job_status_counts: [{status: 'succeeded', count: 1}],
+      has_started_job_execution: true,
     });
 
     expect(result.jobs).toHaveLength(1);
@@ -185,6 +186,7 @@ describe('workflow run list item schema', () => {
         {status: 'succeeded', count: 40},
         {status: 'failed', count: 2},
       ],
+      has_started_job_execution: true,
     });
 
     expect(result.job_status_counts).toHaveLength(2);
@@ -196,6 +198,7 @@ describe('workflow run list item schema', () => {
       source_snapshot: null,
       jobs: Array.from({length: WORKFLOW_RUN_JOB_PREVIEW_LIMIT + 1}, (_, index) => jobDto(index)),
       job_status_counts: [],
+      has_started_job_execution: false,
     });
 
     expect(result.success).toBe(false);

package/src/schemas/workflow-run.ts

@@ -201,6 +201,14 @@ export const workflowRunListItemSchema = workflowRunResponseSchema.extend({
    * Optional so a new web client can consume an older API response during rollout.
    */
   job_display_status_counts: z.array(workflowRunJobDisplayStatusCountDtoSchema).optional(),
+  /**
+   * Whether any job execution in the attempt reached its runner. A `cancelled` job does not say
+   * this on its own, so the counts above cannot answer it.
+   *
+   * Defaults to started, so an older API response during a rollout keeps the reading a run had
+   * before this field existed rather than claiming work that ran never began.
+   */
+  has_started_job_execution: z.boolean().optional().default(true),
 });
 
 export type WorkflowRunListItemDto = z.input<typeof workflowRunListItemSchema>;