@frontera-sdk/workflow 1.50.62-next.0

package/src/types.ts

@@ -0,0 +1,483 @@
+import type { InputsSchema } from '@frontera-sdk/functions'
+
+export type WorkflowRunStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled'
+export type WorkflowNodeStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'skipped' | 'canceled'
+
+export const TERMINAL_RUN_STATUSES: ReadonlySet<WorkflowRunStatus> = new Set<WorkflowRunStatus>([
+  'succeeded',
+  'failed',
+  'canceled',
+])
+
+export function isTerminalRunStatus(status: string): boolean {
+  return TERMINAL_RUN_STATUSES.has(status as WorkflowRunStatus)
+}
+
+/** A row of `GET /v1/workflows`. */
+export interface WorkflowSummary {
+  id: string
+  slug: string
+  enabled: boolean
+  description: string | null
+  liveVersion: number | null
+  latestDraftNumber: number | null
+  versionCount: number
+  runCount: number
+  lastRunAt: string | null
+  lastRunStatus: WorkflowRunStatus | null
+  triggerKinds: string[]
+  cron: string | null
+  subjectApiName: string | null
+  subjectLabel: string | null
+  /** One per webhook trigger. Absent from a service that predates webhooks. */
+  webhooks?: WorkflowWebhook[]
+}
+
+export interface WorkflowWebhook {
+  methods: string[]
+  path: string
+  auth: string
+  respond: string
+  url: string
+  testUrl: string
+}
+
+/** The whole workflow row, which the two create routes answer with. */
+export interface Workflow {
+  id: string
+  orgId: string
+  workspaceId: string
+  slug: string
+  displayName: string | null
+  subjectObjectTypeId: string | null
+  enabled: boolean
+  liveVersionId: string | null
+  testHookVersionId: string | null
+  testHookUntil: string | null
+  createdBy: string
+  createdAt: string
+}
+
+export interface CreateWorkflowInput {
+  /** Lowercase, digits and hyphens; unique in the workspace. */
+  slug: string
+  /** A Blueprint object type id. Every run is then about one of its objects. */
+  subjectObjectTypeId?: string
+}
+
+/** `createDraft`: the workflow and the empty draft made with it, in one write. */
+export interface WorkflowDraft {
+  workflow: Workflow
+  version: { id: string; number: number; status: WorkflowVersionStatus }
+}
+
+/** What `rename` answers with. The slug does not move with the name. */
+export interface RenameResult {
+  id: string
+  slug: string
+  displayName: string
+}
+
+export interface EnabledResult {
+  id: string
+  enabled: boolean
+}
+
+export interface WorkflowDeleteResult {
+  deleted: boolean
+  runsDeleted: number
+}
+
+/** Answered by the two routes that remove a version or a binding. */
+export interface DeletedResult {
+  deleted: boolean
+}
+
+/** draft | live | draining | retired */
+export type WorkflowVersionStatus = 'draft' | 'live' | 'draining' | 'retired'
+
+/** A row of `GET /v1/workflows/:slug/versions`, narrowed to what a listing shows. */
+export interface VersionSummary {
+  id: string
+  number: number
+  status: WorkflowVersionStatus
+  createdAt: string
+  createdVia: string | null
+}
+
+/** The whole row `GET /v1/workflows/:slug/versions/:n` answers with. */
+export interface WorkflowVersion {
+  id: string
+  workflowId: string
+  number: number
+  status: WorkflowVersionStatus
+  definition: Record<string, unknown>
+  grants: string[]
+  lineage: LineageEdge[]
+  inputSchema: InputsSchema | null
+  /** Presentation only; null means none saved. */
+  layout?: WorkflowLayout | null
+  createdVia: string | null
+  createdBy: string
+  createdAt: string
+}
+
+/** Canvas card positions keyed by node id. Never read by the engine. */
+export type WorkflowLayout = Record<string, { x: number; y: number }>
+
+/** What `saveLayout` answers with. */
+export interface LayoutResult {
+  versionId: string
+  number: number
+  layout: WorkflowLayout | null
+}
+
+/**
+ * One step run on its own against the draft's newest test data.
+ *
+ * `ok: false` is the step failing, not the request failing — a 200 carries it.
+ * `preview` marks a kind that only reports what it would do, so its output is
+ * never what a real run would put in `$steps`.
+ */
+export type NodeTestResult =
+  | { ok: true; nodeId: string; kind: string; mocked: boolean; preview?: boolean; input: unknown; output: unknown }
+  | {
+      ok: false
+      nodeId: string
+      kind: string
+      mocked: boolean
+      preview?: boolean
+      input: unknown
+      error: Record<string, unknown>
+    }
+
+/** One step's newest stored step test, as `stepTests` lists them. */
+export interface StepTest {
+  nodeId: string
+  kind: string
+  status: 'succeeded' | 'failed'
+  mocked: boolean
+  preview: boolean
+  input: unknown
+  output: unknown
+  error: Record<string, unknown> | null
+  testedAt: string
+}
+
+/** How long the draft's test webhook URL stays armed, ISO. */
+export interface WebhookTestWindow {
+  until: string
+}
+
+/**
+ * What a push answers with.
+ *
+ * `ok: false` is a result, not a transport failure, and only on a dry run. A
+ * real push that fails validation comes back as a 400 whose
+ * `FronteraError.details.errors` lists the reasons.
+ */
+export interface PushResult {
+  ok: boolean
+  errors?: string[]
+  workflowId?: string
+  version?: { id: string; number: number; status: WorkflowVersionStatus }
+  grants?: string[]
+  lineage?: LineageEdge[]
+}
+
+export interface PromoteResult {
+  workflowId: string
+  versionId: string
+  /** True when the version was already live and nothing changed. */
+  alreadyLive: boolean
+}
+
+export interface LineageEdge {
+  kind: string
+  resourceKind: string
+  resourceId: string
+  label?: string | null
+  property?: string | null
+  nodeId?: string | null
+}
+
+export interface VersionLineage {
+  version: number
+  status: WorkflowVersionStatus
+  grants: string[]
+  lineage: LineageEdge[]
+}
+
+export interface RunRequest {
+  /**
+   * A `File` value here is sent as its own multipart part, named after the
+   * `file` input it fills; everything else travels as JSON.
+   */
+  input?: Record<string, unknown>
+  subject?: { pk: string }
+  /** A version number; without it the live version runs. */
+  version?: number
+  /** `test` is allowed only against a draft. */
+  source?: 'manual' | 'test'
+}
+
+export interface RunResult {
+  runId: string
+  versionNumber: number
+  /** True when an idempotency key matched a run that already existed. */
+  reused?: boolean
+}
+
+/** A row of `GET /v1/workflows/:slug/runs`. */
+export interface RunSummary {
+  id: string
+  orgId: string
+  workflowId: string
+  versionId: string
+  status: WorkflowRunStatus
+  triggerSource: string
+  triggerIndex: number | null
+  triggeredBy: string | null
+  subjectObjectTypeId: string | null
+  subjectPk: string | null
+  rootRunId: string | null
+  parentRunId: string | null
+  depth: number
+  input: Record<string, unknown>
+  output: unknown
+  error: Record<string, unknown> | null
+  nodeCalls: number
+  conversationId: string | null
+  idempotencyKey: string | null
+  invocationDepth: number
+  iteration: { nodePath: string; nodeId: string; index: number; item: unknown; outerSteps: Record<string, unknown> } | null
+  startedAt: string
+  endedAt: string | null
+  versionNumber: number
+  workflowSlug: string
+  workflowDisplayName: string | null
+  triggeredByName: string | null
+  triggeredByEmail: string | null
+  subjectLabel: string | null
+}
+
+export type RunListFilters = {
+  /** `live` hides test runs; `test` shows only them. */
+  source?: 'live' | 'test'
+  status?: WorkflowRunStatus
+  /** Default 50, maximum 200. */
+  limit?: number
+  /** Keyset cursor `<startedAt ISO>|<run id>`; see `runCursor`. */
+  before?: string
+  from?: string
+  to?: string
+}
+
+/**
+ * `workspaceRuns` filters: the per-workflow set plus the slug that narrows to
+ * one workflow. A `type`, not an `interface`, because it is passed as a query
+ * bag and only a type alias carries an implicit index signature.
+ */
+export type WorkspaceRunListFilters = RunListFilters & {
+  /** A workflow slug. Without it, every workflow in the workspace is included. */
+  workflow?: string
+}
+
+export type RunMetricsPeriod = '24h' | '7d' | '30d' | '90d'
+
+export type RunMetricsQuery = {
+  /** Default `7d`. */
+  period?: RunMetricsPeriod
+  /** A workflow slug; without it the whole workspace is counted. */
+  workflow?: string
+}
+
+/** Run counts over one window. Test runs and forEach children are excluded. */
+export interface RunMetricsTotals {
+  runs: number
+  succeeded: number
+  failed: number
+  canceled: number
+  running: number
+  /** Succeeded over finished. Null when nothing finished in the window. */
+  successRate: number | null
+  p50DurationMs: number | null
+  p95DurationMs: number | null
+  nodeCalls: number
+  lastRunAt: string | null
+}
+
+export interface RunMetricsByWorkflow extends RunMetricsTotals {
+  workflowId: string
+  workflowSlug: string
+}
+
+export interface RunVolumeBucket {
+  /** Bucket start, ISO. */
+  at: string
+  succeeded: number
+  failed: number
+}
+
+export interface RunMetrics {
+  period: RunMetricsPeriod
+  /** The current window, ISO; `to` is exclusive. `previous` is the span before it. */
+  range: { from: string; to: string }
+  granularity: 'hour' | 'day' | 'week' | 'month'
+  current: RunMetricsTotals
+  previous: RunMetricsTotals
+  buckets: RunVolumeBucket[]
+  byWorkflow: RunMetricsByWorkflow[]
+}
+
+/** A step output stored by reference, read back whole. */
+export interface NodeOutput {
+  id: string
+  runId: string
+  nodeId: string
+  output: unknown
+}
+
+/** `run` implies `read`; `read` grants the observation tools and no run tool. */
+export type BindingAccess = 'read' | 'run'
+
+/** One agent's standing permission on one workflow, from the workflow's side. */
+export interface WorkflowBinding {
+  agentId: string
+  agentSlug: string
+  agentName: string
+  enabled: boolean
+  access: BindingAccess
+  requiresApproval: boolean
+  waitSeconds: number
+  createdBy: string
+  createdAt: string
+}
+
+/**
+ * The same permission from the agent's side, plus whether it currently grants
+ * anything: a row can exist while nothing is promoted, or while the live
+ * version declares a redacted input an agent may not supply.
+ */
+export interface AgentBinding {
+  workflowId: string
+  workflowSlug: string
+  enabled: boolean
+  access: BindingAccess
+  requiresApproval: boolean
+  waitSeconds: number
+  runnable: boolean
+  /** Why not, when `runnable` is false. */
+  inertReason: 'no_live_version' | 'input_redacted' | 'disabled' | 'read_only' | null
+}
+
+/** Every field is optional: an omitted one keeps what the row already holds. */
+export interface BindAgentInput {
+  enabled?: boolean
+  /** Defaults to `run` on a binding that does not exist yet. */
+  access?: BindingAccess
+  requiresApproval?: boolean
+  /** 5 to 300; defaults to 90. */
+  waitSeconds?: number
+}
+
+/** The `before` cursor for the page after `run`, the last row of the current page. */
+export function runCursor(run: Pick<RunSummary, 'startedAt' | 'id'>): string {
+  return `${run.startedAt}|${run.id}`
+}
+
+export interface RunTreeNode {
+  id: string
+  nodePath: string
+  nodeId: string
+  kind: string
+  status: WorkflowNodeStatus
+  attempt: number
+  input: unknown
+  output: unknown
+  error: unknown
+  startedAt: string
+  endedAt: string | null
+  functionRunId: string | null
+  actionRequestId: string | null
+  conversationId: string | null
+  childRunId: string | null
+  /** Present with `depth: 'all'`. */
+  functionRun?: {
+    id: string
+    slug: string | null
+    status: string
+    startedAt: string
+    endedAt: string | null
+    result: unknown
+    errorMessage: string | null
+    steps: Array<{
+      id: string
+      seq: number
+      kind: string
+      label: string
+      status: string
+      durationMs: number | null
+      stepName: string | null
+    }>
+  } | null
+  /** Present with `depth: 'all'`. */
+  actionRequest?: {
+    id: string
+    lifecycle: string
+    createdAt: string
+    attempts: Array<{ id: string; createdAt: string }>
+    approvals: Array<{ id: string; decision: string; createdAt: string }>
+    outcomes: Array<{ id: string; certainty: string; businessOutcomeCode: string | null; createdAt: string }>
+  } | null
+  /** Present with `depth: 'all'`. */
+  conversation?: {
+    id: string
+    status: string | null
+    createdAt: string | null
+    messages: Array<{ id: string; role: string; createdAt: string | null }>
+  } | null
+  /** Present with `depth: 'all'`. */
+  childRun?: RunTree | null
+}
+
+export interface RunTree {
+  id: string
+  workflowId: string
+  slug: string
+  versionId: string
+  versionNumber: number | null
+  status: WorkflowRunStatus
+  triggerSource: string
+  triggeredBy: string | null
+  triggeredByName: string | null
+  subject: { objectTypeId: string; pk: string; apiName: string | null; label: string | null } | null
+  rootRunId: string | null
+  parentRunId: string | null
+  depth: number
+  input: Record<string, unknown>
+  output: unknown
+  error: unknown
+  nodeCalls: number
+  startedAt: string
+  endedAt: string | null
+  nodes: RunTreeNode[]
+  /** Only on the root of the tree, and only for a webhook delivery. */
+  triggerCapture?: unknown
+}
+
+export interface CancelResult {
+  runId: string
+  status: WorkflowRunStatus
+}
+
+export interface WaitForRunOptions {
+  /** Default 1500. */
+  intervalMs?: number
+  /** Default 10 minutes. The run is left running on timeout. */
+  timeoutMs?: number
+  signal?: AbortSignal
+  /** Default `'run'`. */
+  depth?: 'run' | 'all'
+  onPoll?: (run: RunTree) => void
+}