@frontera-sdk/workflow 1.50.62-next.0

package/src/workflow-client.ts

@@ -0,0 +1,355 @@
+import type { FronteraClient } from '@frontera-sdk/core/client'
+import { FronteraError } from '@frontera-sdk/core/errors'
+import type { RequestOptions } from '@frontera-sdk/core/transport'
+
+import type { WorkflowDefinition } from './definition'
+import {
+  isTerminalRunStatus,
+  type AgentBinding,
+  type BindAgentInput,
+  type CancelResult,
+  type CreateWorkflowInput,
+  type DeletedResult,
+  type EnabledResult,
+  type LayoutResult,
+  type NodeOutput,
+  type NodeTestResult,
+  type PromoteResult,
+  type PushResult,
+  type RenameResult,
+  type RunListFilters,
+  type RunMetrics,
+  type RunMetricsQuery,
+  type RunRequest,
+  type RunResult,
+  type RunSummary,
+  type RunTree,
+  type StepTest,
+  type VersionLineage,
+  type VersionSummary,
+  type WaitForRunOptions,
+  type WebhookTestWindow,
+  type Workflow,
+  type WorkflowBinding,
+  type WorkflowDeleteResult,
+  type WorkflowDraft,
+  type WorkflowLayout,
+  type WorkflowSummary,
+  type WorkflowVersion,
+  type WorkspaceRunListFilters,
+} from './types'
+
+const ORG_KEY_MESSAGE =
+  'Workflows are closed to organization keys. Use a workspace key (sk-ws-…) for @frontera-sdk/workflow; no capability on an organization key opens this route.'
+
+/**
+ * Typed client for `/v1/workflows`.
+ *
+ * Every method is workspace-scoped by the credential on the underlying
+ * `FronteraClient`. Organization keys are refused by the service for this
+ * whole route family, and that refusal is reworded here because the generic
+ * "Insufficient permissions" sends a caller to look for a grant that does not
+ * exist.
+ */
+export class WorkflowClient {
+  constructor(private readonly client: FronteraClient) {}
+
+  private async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    try {
+      return await this.client.request<T>(path, options)
+    } catch (err) {
+      if (
+        err instanceof FronteraError &&
+        (err.details as { detail?: string } | undefined)?.detail === 'org-key-route-closed'
+      ) {
+        throw new FronteraError(ORG_KEY_MESSAGE, { code: 'FORBIDDEN', status: 403, details: err.details })
+      }
+      throw err
+    }
+  }
+
+  list(): Promise<WorkflowSummary[]> {
+    return this.request<WorkflowSummary[]>('/v1/workflows')
+  }
+
+  get(slug: string): Promise<WorkflowSummary> {
+    return this.request<WorkflowSummary>(`/v1/workflows/${encodeURIComponent(slug)}`)
+  }
+
+  /** An empty workflow with the slug you choose and no version yet. */
+  create(input: CreateWorkflowInput): Promise<Workflow> {
+    return this.request<Workflow>('/v1/workflows', { method: 'POST', body: input })
+  }
+
+  /**
+   * A workflow named the way a person would name it, with an empty draft
+   * already on it. The slug is derived from the name and stays put afterwards.
+   */
+  createDraft(displayName: string): Promise<WorkflowDraft> {
+    return this.request<WorkflowDraft>('/v1/workflows/drafts', { method: 'POST', body: { displayName } })
+  }
+
+  /**
+   * The kill switch. It stops cron and the production webhook URL; manual,
+   * agent and test runs go on ignoring it.
+   */
+  setEnabled(slug: string, enabled: boolean): Promise<EnabledResult> {
+    return this.request<EnabledResult>(`/v1/workflows/${encodeURIComponent(slug)}`, {
+      method: 'PATCH',
+      body: { enabled },
+    })
+  }
+
+  rename(slug: string, displayName: string): Promise<RenameResult> {
+    return this.request<RenameResult>(`/v1/workflows/${encodeURIComponent(slug)}/name`, {
+      method: 'PATCH',
+      body: { displayName },
+    })
+  }
+
+  /** Refused while any agent is bound or any run is still going. */
+  remove(slug: string): Promise<WorkflowDeleteResult> {
+    return this.request<WorkflowDeleteResult>(`/v1/workflows/${encodeURIComponent(slug)}`, { method: 'DELETE' })
+  }
+
+  /**
+   * The version list, narrowed to listing fields. The route answers with whole
+   * version rows, definition included, for every version; `version(slug, n)`
+   * reads one in full.
+   */
+  async versions(slug: string): Promise<VersionSummary[]> {
+    const rows = await this.request<WorkflowVersion[]>(`/v1/workflows/${encodeURIComponent(slug)}/versions`)
+    return rows.map((v) => ({
+      id: v.id,
+      number: v.number,
+      status: v.status,
+      createdAt: v.createdAt,
+      createdVia: v.createdVia ?? null,
+    }))
+  }
+
+  version(slug: string, number: number): Promise<WorkflowVersion> {
+    return this.request<WorkflowVersion>(
+      `/v1/workflows/${encodeURIComponent(slug)}/versions/${number}`,
+    )
+  }
+
+  /**
+   * Push a definition as a new draft, or with `dryRun` validate it and write
+   * nothing. The definition is the raw body; there is no `{ definition }`
+   * wrapper.
+   */
+  push(
+    slug: string,
+    definition: WorkflowDefinition,
+    opts: { dryRun?: boolean } = {},
+  ): Promise<PushResult> {
+    return this.request<PushResult>(`/v1/workflows/${encodeURIComponent(slug)}/versions`, {
+      method: 'PUT',
+      body: definition,
+      query: opts.dryRun ? { dryRun: true } : undefined,
+    })
+  }
+
+  /**
+   * Rewrite a draft in place rather than adding a version. Same body as
+   * `push`, and the same refusal: only a draft can be overwritten.
+   */
+  overwriteDraft(
+    slug: string,
+    number: number,
+    definition: WorkflowDefinition,
+  ): Promise<PushResult> {
+    return this.request<PushResult>(`/v1/workflows/${encodeURIComponent(slug)}/versions/${number}`, {
+      method: 'PUT',
+      body: definition,
+    })
+  }
+
+  deleteVersion(slug: string, number: number): Promise<DeletedResult> {
+    return this.request<DeletedResult>(`/v1/workflows/${encodeURIComponent(slug)}/versions/${number}`, {
+      method: 'DELETE',
+    })
+  }
+
+  /** A new draft carrying that version's definition and its arrangement. */
+  copyVersion(slug: string, number: number): Promise<PushResult> {
+    return this.request<PushResult>(`/v1/workflows/${encodeURIComponent(slug)}/versions/${number}/copy`, {
+      method: 'POST',
+    })
+  }
+
+  /** Where the cards sit, and only that. No version is written. */
+  saveLayout(slug: string, number: number, layout: WorkflowLayout): Promise<LayoutResult> {
+    return this.request<LayoutResult>(`/v1/workflows/${encodeURIComponent(slug)}/versions/${number}/layout`, {
+      method: 'PATCH',
+      body: { layout },
+    })
+  }
+
+  /** Run ONE step of a draft against its newest test data, synchronously. */
+  testNode(slug: string, number: number, nodeId: string): Promise<NodeTestResult> {
+    return this.request<NodeTestResult>(
+      `/v1/workflows/${encodeURIComponent(slug)}/versions/${number}/nodes/${encodeURIComponent(nodeId)}/test`,
+      { method: 'POST' },
+    )
+  }
+
+  stepTests(slug: string, number: number): Promise<StepTest[]> {
+    return this.request<StepTest[]>(`/v1/workflows/${encodeURIComponent(slug)}/versions/${number}/step-tests`)
+  }
+
+  /** Arm the draft's test webhook URL for one delivery. Calling again re-arms it. */
+  listenForWebhookTest(slug: string, number: number): Promise<WebhookTestWindow> {
+    return this.request<WebhookTestWindow>(
+      `/v1/workflows/${encodeURIComponent(slug)}/versions/${number}/listen`,
+      { method: 'POST' },
+    )
+  }
+
+  promote(slug: string, number: number): Promise<PromoteResult> {
+    return this.request<PromoteResult>(
+      `/v1/workflows/${encodeURIComponent(slug)}/versions/${number}/promote`,
+      { method: 'POST' },
+    )
+  }
+
+  lineage(slug: string, number: number): Promise<VersionLineage> {
+    return this.request<VersionLineage>(
+      `/v1/workflows/${encodeURIComponent(slug)}/versions/${number}/lineage`,
+    )
+  }
+
+  /** A `File` in `request.input` makes this multipart; see `runBody`. */
+  run(slug: string, request: RunRequest = {}): Promise<RunResult> {
+    return this.request<RunResult>(`/v1/workflows/${encodeURIComponent(slug)}/run`, {
+      method: 'POST',
+      body: runBody(request),
+    })
+  }
+
+  runs(slug: string, filters: RunListFilters = {}): Promise<RunSummary[]> {
+    return this.request<RunSummary[]>(`/v1/workflows/${encodeURIComponent(slug)}/runs`, {
+      query: filters,
+    })
+  }
+
+  /** Every run in the workspace, or one workflow's with `filters.workflow`. */
+  workspaceRuns(filters: WorkspaceRunListFilters = {}): Promise<RunSummary[]> {
+    return this.request<RunSummary[]>('/v1/workflows/runs', { query: filters })
+  }
+
+  runMetrics(query: RunMetricsQuery = {}): Promise<RunMetrics> {
+    return this.request<RunMetrics>('/v1/workflows/runs/metrics', { query })
+  }
+
+  /** A step output the interpreter stored by reference, rather than inline. */
+  nodeOutput(nodeCallId: string): Promise<NodeOutput> {
+    return this.request<NodeOutput>(`/v1/workflows/runs/nodes/${encodeURIComponent(nodeCallId)}/output`)
+  }
+
+  /** Every agent that may see or run this workflow. */
+  bindings(slug: string): Promise<WorkflowBinding[]> {
+    return this.request<WorkflowBinding[]>(`/v1/workflows/${encodeURIComponent(slug)}/bindings`)
+  }
+
+  /** Create or update one binding. Omitted fields keep what the row holds. */
+  bindAgent(slug: string, agentSlug: string, input: BindAgentInput = {}): Promise<WorkflowBinding> {
+    return this.request<WorkflowBinding>(
+      `/v1/workflows/${encodeURIComponent(slug)}/bindings/${encodeURIComponent(agentSlug)}`,
+      { method: 'PUT', body: input },
+    )
+  }
+
+  unbindAgent(slug: string, agentSlug: string): Promise<DeletedResult> {
+    return this.request<DeletedResult>(
+      `/v1/workflows/${encodeURIComponent(slug)}/bindings/${encodeURIComponent(agentSlug)}`,
+      { method: 'DELETE' },
+    )
+  }
+
+  /** The other direction: every workflow one agent may see or run. */
+  agentBindings(agentSlug: string): Promise<AgentBinding[]> {
+    return this.request<AgentBinding[]>(`/v1/workflows/agent-bindings/${encodeURIComponent(agentSlug)}`)
+  }
+
+  /** One run and, with `depth: 'all'`, the child runs and effects beneath it. */
+  runById(id: string, depth: 'run' | 'all' = 'run'): Promise<RunTree> {
+    return this.request<RunTree>(`/v1/workflows/runs/${encodeURIComponent(id)}`, { query: { depth } })
+  }
+
+  cancel(id: string): Promise<CancelResult> {
+    return this.request<CancelResult>(`/v1/workflows/runs/${encodeURIComponent(id)}/cancel`, {
+      method: 'POST',
+    })
+  }
+
+  /**
+   * Poll until the run reaches a terminal status and return that tree. On
+   * timeout the run is left as it is; cancelling is the caller's decision.
+   */
+  async waitForRun(id: string, options: WaitForRunOptions = {}): Promise<RunTree> {
+    const { intervalMs = 1500, timeoutMs = 10 * 60_000, signal, depth = 'run', onPoll } = options
+    const deadline = Date.now() + timeoutMs
+    for (;;) {
+      throwIfAborted(signal)
+      const run = await this.runById(id, depth)
+      onPoll?.(run)
+      if (isTerminalRunStatus(run.status)) return run
+      if (Date.now() >= deadline) {
+        throw new FronteraError(
+          `Workflow run ${id} did not settle within ${timeoutMs} ms (last status: ${run.status})`,
+          { code: 'RUN_WAIT_TIMEOUT', details: { runId: id, lastStatus: run.status } },
+        )
+      }
+      await sleep(Math.min(intervalMs, deadline - Date.now()), signal)
+    }
+  }
+}
+
+/**
+ * The run body, JSON unless a `file` input carries an actual `File`.
+ *
+ * A `file` input cannot travel as JSON, so one turns the whole request
+ * multipart: the non-file fields go in an `input` part as JSON and each file
+ * gets a part named after its field, which is the shape the service's
+ * `readMultipartRun` expects. `subject` and `version` are serialised because a
+ * multipart part is text — the route parses both back. The content type is
+ * left alone deliberately: only `FormData` can generate the boundary, and
+ * naming the type here would lose it.
+ */
+function runBody(request: RunRequest): RunRequest | FormData {
+  const input = request.input ?? {}
+  const files = Object.entries(input).filter((entry): entry is [string, File] => entry[1] instanceof File)
+  if (files.length === 0) return request
+
+  const form = new FormData()
+  const rest = Object.fromEntries(Object.entries(input).filter(([, value]) => !(value instanceof File)))
+  form.append('input', JSON.stringify(rest))
+  for (const [field, file] of files) form.append(field, file)
+  if (request.subject) form.append('subject', JSON.stringify(request.subject))
+  if (request.version !== undefined) form.append('version', String(request.version))
+  if (request.source) form.append('source', request.source)
+  return form
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw new FronteraError('Workflow run wait was aborted', { code: 'ABORTED', details: { reason: signal.reason } })
+  }
+}
+
+/** Resolves after `ms`, or as soon as `signal` aborts. */
+function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    function onAbort() {
+      clearTimeout(timer)
+      resolve()
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}