@shipfox/client-workflows 0.2.0

package/src/core/entities/step.ts

@@ -0,0 +1,105 @@
+import type {
+  AgentConfigIssueDto,
+  StepErrorCategoryDto,
+  StepErrorReasonDto,
+  StepSourceLocationDto,
+  WorkflowRunStepDetailDto,
+} from '@shipfox/api-workflows-dto';
+import {type StepAttempt, toStepAttempt} from './step-attempt.js';
+
+export type StepErrorReason = StepErrorReasonDto;
+export type AgentConfigIssue = AgentConfigIssueDto;
+export type StepErrorCategory = StepErrorCategoryDto;
+
+export interface StepSourceLocation {
+  startLine: number;
+  endLine: number;
+}
+
+export interface StepError {
+  message: string;
+  exitCode: number | null;
+  signal: string | undefined;
+  reason: StepErrorReason | undefined;
+  agentConfigIssue: AgentConfigIssue | undefined;
+  category: StepErrorCategory | undefined;
+}
+
+export interface AgentStepConfig {
+  provider: string | null;
+  model: string | null;
+  thinking: string | null;
+}
+
+export interface Step {
+  id: string;
+  jobExecutionId: string;
+  key: string | null;
+  name: string;
+  sourceLocation: StepSourceLocation | null;
+  status: string;
+  type: string;
+  config: Record<string, unknown>;
+  agentConfig: AgentStepConfig | null;
+  error: StepError | null;
+  position: number;
+  currentAttempt: number;
+  createdAt: string;
+  updatedAt: string;
+  attempts: StepAttempt[];
+}
+
+export function toStep(dto: WorkflowRunStepDetailDto): Step {
+  return {
+    id: dto.id,
+    jobExecutionId: dto.job_execution_id,
+    key: dto.key,
+    name: dto.name,
+    sourceLocation: dto.source_location ? toStepSourceLocation(dto.source_location) : null,
+    status: dto.status,
+    type: dto.type,
+    config: dto.config,
+    agentConfig: toAgentStepConfig(dto),
+    error: dto.error ? toStepError(dto.error) : null,
+    position: dto.position,
+    currentAttempt: dto.current_attempt,
+    createdAt: dto.created_at,
+    updatedAt: dto.updated_at,
+    attempts: dto.attempts.map((attempt) => toStepAttempt(attempt, dto.job_execution_id)),
+  };
+}
+
+function toStepSourceLocation(dto: StepSourceLocationDto): StepSourceLocation {
+  return {
+    startLine: dto.start_line,
+    endLine: dto.end_line,
+  };
+}
+
+function toStepError(dto: NonNullable<WorkflowRunStepDetailDto['error']>): StepError {
+  return {
+    message: dto.message,
+    exitCode: dto.exit_code ?? null,
+    signal: dto.signal,
+    reason: dto.reason,
+    agentConfigIssue: dto.agent_config_issue,
+    category: dto.category,
+  };
+}
+
+function toAgentStepConfig(dto: WorkflowRunStepDetailDto): AgentStepConfig | null {
+  if (dto.type !== 'agent') return null;
+
+  return {
+    provider: stringConfigValue(dto.config.provider),
+    model: stringConfigValue(dto.config.model),
+    thinking: stringConfigValue(dto.config.thinking),
+  };
+}
+
+function stringConfigValue(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+
+  const trimmedValue = value.trim();
+  return trimmedValue ? trimmedValue : null;
+}

package/src/core/entities/workflow-run-attempt.ts

@@ -0,0 +1,87 @@
+import type {WorkflowRunAttemptDto} from '@shipfox/api-workflows-dto';
+import {type Duration, intervalToDuration} from 'date-fns';
+import type {WorkflowRunStatus} from './workflow-run.js';
+
+export type WorkflowRunAttemptDisplayDuration =
+  | {state: 'fixed'; elapsed: Duration}
+  | {state: 'live'; fromIso: string};
+
+interface WorkflowRunAttemptSummaryFields {
+  workflowRunId: string;
+  attempt: number;
+  status: WorkflowRunStatus;
+  createdAt: string;
+  startedAt: string | null;
+  finishedAt: string | null;
+}
+
+interface WorkflowRunAttemptFields extends WorkflowRunAttemptSummaryFields {
+  id: string;
+  rerunMode: 'all' | 'failed' | null;
+}
+
+export class WorkflowRunAttemptSummary {
+  workflowRunId!: string;
+  attempt!: number;
+  status!: WorkflowRunStatus;
+  createdAt!: string;
+  startedAt!: string | null;
+  finishedAt!: string | null;
+
+  constructor(fields: WorkflowRunAttemptSummaryFields) {
+    Object.assign(this, fields);
+  }
+
+  get displayDuration(): WorkflowRunAttemptDisplayDuration | null {
+    return workflowRunAttemptDisplayDurationFromTimestamps(this);
+  }
+}
+
+export class WorkflowRunAttempt extends WorkflowRunAttemptSummary {
+  id!: string;
+  rerunMode!: 'all' | 'failed' | null;
+
+  constructor(fields: WorkflowRunAttemptFields) {
+    super(fields);
+    this.id = fields.id;
+    this.rerunMode = fields.rerunMode;
+  }
+}
+
+export function toWorkflowRunAttempt(dto: WorkflowRunAttemptDto): WorkflowRunAttempt {
+  return new WorkflowRunAttempt({
+    id: dto.id,
+    workflowRunId: dto.workflow_run_id,
+    attempt: dto.attempt,
+    status: dto.status,
+    createdAt: dto.created_at,
+    startedAt: dto.started_at ?? null,
+    finishedAt: dto.finished_at ?? null,
+    rerunMode: dto.rerun_mode,
+  });
+}
+
+export function workflowRunAttemptDisplayDurationFromTimestamps({
+  startedAt,
+  finishedAt,
+}: {
+  startedAt: string | null;
+  finishedAt: string | null;
+}): WorkflowRunAttemptDisplayDuration | null {
+  if (startedAt === null) return null;
+  if (finishedAt === null) return {state: 'live', fromIso: startedAt};
+
+  const elapsed = durationBetween(startedAt, finishedAt);
+  return elapsed === null ? null : {state: 'fixed', elapsed};
+}
+
+function durationBetween(from: string, to: string): Duration | null {
+  const start = new Date(from);
+  const end = new Date(to);
+  if (!Number.isFinite(start.getTime()) || !Number.isFinite(end.getTime())) return null;
+
+  return intervalToDuration({
+    start,
+    end: end < start ? start : end,
+  });
+}

package/src/core/entities/workflow-run.ts

@@ -0,0 +1,183 @@
+import type {
+  WorkflowRunDetailResponseDto,
+  WorkflowRunListResponseDto,
+  WorkflowRunResponseDto,
+  WorkflowRunStatusDto,
+} from '@shipfox/api-workflows-dto';
+import {type Job, toJob, WORKFLOW_JOB_STATUSES} from './job.js';
+import {
+  toWorkflowRunAttempt,
+  type WorkflowRunAttempt,
+  WorkflowRunAttemptSummary,
+} from './workflow-run-attempt.js';
+
+export type WorkflowRunStatus = WorkflowRunStatusDto;
+export type WorkflowStatus = WorkflowRunStatus | (typeof WORKFLOW_JOB_STATUSES)[number];
+
+export const WORKFLOW_RUN_STATUSES = [
+  'pending',
+  'running',
+  'succeeded',
+  'failed',
+  'cancelled',
+] as const satisfies readonly WorkflowRunStatus[];
+
+export const TERMINAL_WORKFLOW_RUN_STATUSES = [
+  'succeeded',
+  'failed',
+  'cancelled',
+] as const satisfies readonly WorkflowRunStatus[];
+
+const WORKFLOW_STATUSES = new Set<WorkflowStatus>([
+  ...WORKFLOW_RUN_STATUSES,
+  ...WORKFLOW_JOB_STATUSES,
+]);
+const TERMINAL_WORKFLOW_RUN_STATUS_SET = new Set<WorkflowRunStatus>(TERMINAL_WORKFLOW_RUN_STATUSES);
+
+export interface WorkflowSourceSnapshot {
+  content: string;
+  format: 'yaml';
+}
+
+export interface WorkflowRun {
+  id: string;
+  projectId: string;
+  definitionId: string;
+  name: string;
+  currentAttempt: number;
+  triggerProvider: string | null;
+  triggerSource: string;
+  triggerEvent: string;
+  triggerDisplayLabel: string;
+  triggerLabel: string;
+  triggerPayload: Record<string, unknown>;
+  inputs: Record<string, unknown> | null;
+  sourceSnapshot: WorkflowSourceSnapshot | null;
+  createdAt: string;
+  updatedAt: string;
+  shortId: string;
+  isTemporary: boolean;
+}
+
+export interface WorkflowRunListItem extends WorkflowRun {
+  status: WorkflowRunStatus;
+  latestAttempt: number;
+  runAttempt: WorkflowRunAttemptSummary;
+}
+
+export interface WorkflowRunDetail extends WorkflowRun {
+  latestAttempt: number;
+  runAttempt: WorkflowRunAttempt;
+  jobs: Job[];
+}
+
+export interface WorkflowRunListPage {
+  runs: WorkflowRunListItem[];
+  nextCursor: string | null;
+  filteredTotalCount: number | null;
+}
+
+export function workflowRunShortId(id: string): string {
+  return id.length <= 8 ? id : id.slice(0, 8);
+}
+
+export function workflowRunTriggerLabel({
+  triggerSource,
+  triggerEvent,
+}: {
+  triggerSource: string;
+  triggerEvent: string;
+}): string {
+  return [triggerSource, triggerEvent].filter(Boolean).join(' · ');
+}
+
+export function workflowRunTriggerDisplayLabel({
+  triggerSource,
+  triggerEvent,
+}: {
+  triggerSource: string;
+  triggerEvent: string;
+}): string {
+  return triggerEvent || triggerSource;
+}
+
+export function isWorkflowRunTerminal(status: WorkflowRunStatus): boolean {
+  return TERMINAL_WORKFLOW_RUN_STATUS_SET.has(status);
+}
+
+export function isWorkflowStatus(status: string): status is WorkflowStatus {
+  return WORKFLOW_STATUSES.has(status as WorkflowStatus);
+}
+
+export function toWorkflowRun(dto: WorkflowRunResponseDto): WorkflowRun {
+  const triggerLabel = workflowRunTriggerLabel({
+    triggerSource: dto.trigger_source,
+    triggerEvent: dto.trigger_event,
+  });
+  const triggerDisplayLabel = workflowRunTriggerDisplayLabel({
+    triggerSource: dto.trigger_source,
+    triggerEvent: dto.trigger_event,
+  });
+
+  return {
+    id: dto.id,
+    projectId: dto.project_id,
+    definitionId: dto.definition_id,
+    name: dto.name,
+    currentAttempt: dto.current_attempt,
+    triggerProvider: dto.trigger_provider,
+    triggerSource: dto.trigger_source,
+    triggerEvent: dto.trigger_event,
+    triggerDisplayLabel,
+    triggerLabel,
+    triggerPayload: dto.trigger_payload,
+    inputs: dto.inputs ?? null,
+    sourceSnapshot: dto.source_snapshot ? toWorkflowSourceSnapshot(dto.source_snapshot) : null,
+    createdAt: dto.created_at,
+    updatedAt: dto.updated_at,
+    shortId: workflowRunShortId(dto.id),
+    isTemporary: dto.id.startsWith('temp-'),
+  };
+}
+
+export function toWorkflowRunListItem(dto: WorkflowRunResponseDto): WorkflowRunListItem {
+  return {
+    ...toWorkflowRun(dto),
+    status: dto.status,
+    latestAttempt: dto.latest_attempt,
+    runAttempt: new WorkflowRunAttemptSummary({
+      workflowRunId: dto.id,
+      attempt: dto.current_attempt,
+      status: dto.status,
+      createdAt: dto.created_at,
+      startedAt: dto.started_at ?? null,
+      finishedAt: dto.finished_at ?? null,
+    }),
+  };
+}
+
+export function toWorkflowRunDetail(dto: WorkflowRunDetailResponseDto): WorkflowRunDetail {
+  return {
+    ...toWorkflowRun(dto),
+    latestAttempt: dto.latest_attempt,
+    runAttempt: toWorkflowRunAttempt(dto.run_attempt),
+    jobs: dto.jobs.map(toJob),
+  };
+}
+
+export function toWorkflowRunListPage(dto: WorkflowRunListResponseDto): WorkflowRunListPage {
+  return {
+    runs: dto.runs.map(toWorkflowRunListItem),
+    nextCursor: dto.next_cursor,
+    filteredTotalCount: dto.filtered_total_count,
+  };
+}
+
+function toWorkflowSourceSnapshot(
+  dto: NonNullable<WorkflowRunResponseDto['source_snapshot']>,
+): WorkflowSourceSnapshot {
+  return {
+    content: dto.content,
+    format: dto.format,
+  };
+}

package/src/core/workflow-run-url-state.ts

@@ -0,0 +1,61 @@
+export interface WorkflowRunSelectionInput {
+  jobId?: string | undefined;
+  jobExecutionId?: string | undefined;
+  stepId?: string | undefined;
+  stepAttemptId?: string | undefined;
+  runAttempt?: number | undefined;
+}
+
+const WORKFLOW_RUN_URL_SELECTION_KEYS = [
+  'job',
+  'jobExecution',
+  'step',
+  'stepAttempt',
+  'runAttempt',
+] as const;
+
+type WorkflowRunSearch = Record<string, unknown>;
+
+export function workflowRunSelectionFromSearch(
+  search: WorkflowRunSearch,
+): WorkflowRunSelectionInput {
+  return {
+    jobId: stringSearchParam(search.job),
+    jobExecutionId: stringSearchParam(search.jobExecution),
+    stepId: stringSearchParam(search.step),
+    stepAttemptId: stringSearchParam(search.stepAttempt),
+    runAttempt: positiveIntegerSearchParam(search.runAttempt),
+  };
+}
+
+export function withWorkflowRunSelectionSearch<TSearch extends WorkflowRunSearch>(
+  search: TSearch,
+  selection: WorkflowRunSelectionInput,
+): TSearch {
+  const nextSearch: WorkflowRunSearch = withoutWorkflowRunSelectionSearch(search);
+  if (selection.jobId) nextSearch.job = selection.jobId;
+  if (selection.jobExecutionId) nextSearch.jobExecution = selection.jobExecutionId;
+  if (selection.stepId) nextSearch.step = selection.stepId;
+  if (selection.stepAttemptId) nextSearch.stepAttempt = selection.stepAttemptId;
+  if (selection.runAttempt) nextSearch.runAttempt = String(selection.runAttempt);
+  return nextSearch as TSearch;
+}
+
+export function withoutWorkflowRunSelectionSearch<TSearch extends WorkflowRunSearch>(
+  search: TSearch,
+): TSearch {
+  const nextSearch: WorkflowRunSearch = {...search};
+  for (const key of WORKFLOW_RUN_URL_SELECTION_KEYS) {
+    delete nextSearch[key];
+  }
+  return nextSearch as TSearch;
+}
+
+function stringSearchParam(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function positiveIntegerSearchParam(value: unknown): number | undefined {
+  const raw = typeof value === 'string' ? Number(value) : value;
+  return typeof raw === 'number' && Number.isInteger(raw) && raw > 0 ? raw : undefined;
+}