@proteos/sdk 0.18.1

package/src/workflow/types.ts

@@ -0,0 +1,658 @@
+/**
+ * Types for the Proteos Workflow Service API (engine v2).
+ *
+ * Hand-written mirror of the Go models in `go.proteos.ai/model/workflow`
+ * (`workflow.go`, `graph.go`, `node-type.go`, `execution.go`, `item.go` +
+ * `api/*-requests.go`). Field names match the snake_case wire format exactly,
+ * including enum values.
+ *
+ * A Workflow is an n8n-shaped automation definition keyed by an immutable
+ * kebab-case `key` ((org_id, key) PK). Its graph is catalog-driven: every node
+ * references a registered node type (a NodeDescriptor) by an open string type
+ * key plus a pinned `type_version`. A WorkflowExecution is one firing of a
+ * workflow; per-node results live in append-only NodeExecution rows.
+ */
+
+import type { AuditFields, ListOptions, UserRef } from '../types/common.js'
+
+// ---------------------------------------------------------------------------
+// Graph (v2)
+// ---------------------------------------------------------------------------
+
+export type WorkflowStatus = 'active' | 'paused' | 'archived'
+
+/**
+ * A node's registered type key — open string. Catalog types follow
+ * `<package>.<node>` (e.g. `proteos-nodes-core.http-request`); engine-native
+ * trigger types keep their legacy `trigger.<kind>` keys.
+ */
+export type NodeTypeKey = string
+
+export interface NodePosition {
+  x: number
+  y: number
+}
+
+/** How the interpreter routes a failed node run. */
+export type OnErrorPolicy = 'stop' | 'continue' | 'continue_error_output'
+
+/**
+ * Per-node activity retry policy. `max_attempts: 1` disables retries; zero
+ * values fall back to the descriptor's defaults, then the engine defaults.
+ */
+export interface NodeRetryPolicy {
+  max_attempts?: number
+  backoff_seconds?: number
+}
+
+/**
+ * One node in the graph. `parameters` holds the RAW parameter values for the
+ * node's descriptor properties (Liquid expressions unresolved — resolution
+ * happens at ExecuteNode time).
+ */
+export interface WorkflowNode {
+  id: string
+  type: NodeTypeKey
+  /** Pins one registered descriptor version of `type`. */
+  type_version?: number
+  name: string
+  parameters?: Record<string, unknown>
+  /** Credential-type slug → metadata variable key or id. */
+  credential_refs?: Record<string, string>
+  position?: NodePosition
+  is_disabled?: boolean
+  notes?: string
+  on_error?: OnErrorPolicy
+  retry?: NodeRetryPolicy
+}
+
+/** The single-port key used when a connection endpoint omits the port. */
+export const DEFAULT_PORT = 'main'
+
+/**
+ * The reserved output-port key the `on_error: continue_error_output` policy
+ * routes failed items to, when the node's descriptor declares it.
+ */
+export const ERROR_PORT = 'error'
+
+/**
+ * One side of a connection: a node by id and one of its ports by key.
+ * Connections are id-keyed (renaming a node never breaks the graph) and
+ * port-keyed (never index-keyed).
+ */
+export interface ConnectionEndpoint {
+  node_id: string
+  port: string
+}
+
+/** A directed edge from one node's output port to another node's input port. */
+export interface WorkflowConnection {
+  from: ConnectionEndpoint
+  to: ConnectionEndpoint
+}
+
+export interface WorkflowGraph {
+  nodes: WorkflowNode[]
+  connections: WorkflowConnection[]
+  /**
+   * Editor-only per-node pinned output items (keyed by node id) used for
+   * partial executions; the production interpreter ignores it unless a run
+   * explicitly opts in.
+   */
+  pin_data?: Record<string, Item[]>
+}
+
+// ---------------------------------------------------------------------------
+// Items
+// ---------------------------------------------------------------------------
+
+/** A storage-service file reference carried by an item (never inline bytes). */
+export interface BinaryRef {
+  file_id: string
+  mime_type?: string
+  file_name?: string
+  size_bytes?: number
+}
+
+/**
+ * Item lineage: which input item (and port) produced an output item. The wire
+ * shape also allows an int shorthand equivalent to `{ item: n }`.
+ */
+export interface PairedItem {
+  item: number
+  input?: string
+}
+
+/**
+ * The unit of data flowing between workflow nodes (n8n 1:1). Node input/output
+ * is a map of port key → `Item[]`.
+ */
+export interface Item {
+  json: Record<string, unknown>
+  binary?: Record<string, BinaryRef>
+  paired_item?: PairedItem | number
+}
+
+// ---------------------------------------------------------------------------
+// Node descriptors (catalog)
+// ---------------------------------------------------------------------------
+
+/**
+ * Which runtime executes a node type. `go` nodes are first-party, compiled
+ * into the node host; `wasm` nodes are user-defined sandboxed bundles;
+ * `intrinsic` types are executed by the interpreter / workflow-service itself.
+ */
+export type NodeRuntime = 'go' | 'wasm' | 'intrinsic'
+
+/** Coarse catalog grouping of a node type. */
+export type NodeGroup = 'trigger' | 'action' | 'transform' | 'flow'
+
+/** Control type of one descriptor property (n8n INodeProperties paradigm). */
+export type PropertyType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'options'
+  | 'multi_options'
+  | 'json'
+  | 'date_time'
+  | 'color'
+  | 'notice'
+  | 'hidden'
+  | 'collection'
+  | 'fixed_collection'
+  | 'credentials_select'
+  | 'button'
+  // Wave 2 (editor support lands with Phase 3):
+  | 'resource_locator'
+  | 'resource_mapper'
+  | 'filter'
+  | 'assignment_collection'
+
+/**
+ * One named input or output port. Port keys are stable identifiers referenced
+ * by connections (never indexes).
+ */
+export interface PortSpec {
+  key: string
+  display_name?: string
+  is_required?: boolean
+  max_connections?: number
+}
+
+/**
+ * Gates a property's visibility on sibling parameter values. The editor
+ * re-evaluates reactively; the backend applies the same rule during validation
+ * (hidden properties are ignored). `hide` wins over `show`.
+ */
+export interface DisplayOptions {
+  show?: Record<string, unknown[]>
+  hide?: Record<string, unknown[]>
+}
+
+/**
+ * One entry of an options/multi_options list, one repeatable sub-property
+ * group of a collection, or one named group of a fixed_collection (in which
+ * case `values` carries the group's fixed sub-fields).
+ */
+export interface PropertyOption {
+  name: string
+  value?: unknown
+  display_name?: string
+  description?: string
+  values?: NodeProperty[]
+}
+
+/**
+ * One parameter in a descriptor's schema. `name` is the verbatim key under
+ * `node.parameters` (never case-converted). Every value-bearing property
+ * accepts a Liquid expression unless `no_data_expression` is true.
+ */
+export interface NodeProperty {
+  display_name: string
+  name: string
+  type: PropertyType
+  default?: unknown
+  description?: string
+  placeholder?: string
+  hint?: string
+  is_required?: boolean
+  no_data_expression?: boolean
+  options?: PropertyOption[]
+  display_options?: DisplayOptions
+  /**
+   * v1 subset: `load_options_method`, `load_options_depends_on`,
+   * `multiple_values`, `multiple_value_button_text`, `rows`, `password`,
+   * `min_value`, `max_value`, `editor`.
+   */
+  type_options?: Record<string, unknown>
+}
+
+/** Declares that a node type uses a credential of the given type slug. */
+export interface CredentialSpec {
+  type: string
+  is_required?: boolean
+  display_options?: DisplayOptions
+}
+
+/**
+ * The full, self-describing contract of one node type: drives the editor's
+ * picker and parameter form, backend validation, and dispatch.
+ */
+export interface NodeDescriptor {
+  type: NodeTypeKey
+  display_name: string
+  description?: string
+  /** Lucide icon name, PascalCase. */
+  icon?: string
+  group: NodeGroup
+  version: number
+  runtime: NodeRuntime
+  task_queue?: string
+  inputs: PortSpec[]
+  outputs: PortSpec[]
+  properties: NodeProperty[]
+  credentials?: CredentialSpec[]
+  /** Dynamic methods the host answers, as `"<kind>:<method_name>"`. */
+  methods?: string[]
+  /** Declarative routing spec (Phase 4). */
+  routing?: unknown
+  documentation_url?: string
+  /** Liquid over parameters, shown on the canvas node card. */
+  subtitle?: string
+}
+
+/** Registry lifecycle of one (type, version) row. */
+export type NodeTypeStatus = 'active' | 'inactive'
+
+/**
+ * One node-type registry row: a registered (package, name, version) with its
+ * full descriptor. `org_id` is empty for platform-global types and set for
+ * org-installed (wasm) types.
+ */
+export interface WorkflowNodeType {
+  package: string
+  name: string
+  version: number
+  runtime: NodeRuntime
+  task_queue?: string
+  descriptor: NodeDescriptor
+  status: NodeTypeStatus
+  org_id?: string
+  created_at: string
+  updated_at: string
+}
+
+// ---------------------------------------------------------------------------
+// Node-type API shapes
+// ---------------------------------------------------------------------------
+
+export interface GetNodeTypesResponse {
+  data: WorkflowNodeType[]
+}
+
+/**
+ * An editor dynamic-method call (load_options / list_search /
+ * resource_mapper_fields / credential_test) proxied to the node host.
+ * `parameters` carries the node's current (partial) parameter values.
+ */
+export interface InvokeNodeMethodRequest {
+  type_version?: number
+  parameters?: Record<string, unknown>
+  credential_refs?: Record<string, string>
+  filter?: string
+  pagination_token?: string
+}
+
+/** One dynamic dropdown entry returned by a load_options method. */
+export interface NodeMethodOption {
+  name: string
+  value: unknown
+  description?: string
+}
+
+export interface InvokeNodeMethodResponse {
+  /** load_options */
+  options?: NodeMethodOption[]
+  /** list_search */
+  results?: unknown
+  pagination_token?: string
+  /** resource_mapper_fields */
+  fields?: unknown
+  /** credential_test */
+  is_valid?: boolean
+  message?: string
+}
+
+// ---------------------------------------------------------------------------
+// Engine-native trigger / agent parameters
+// ---------------------------------------------------------------------------
+// Trigger nodes are executed by workflow-service itself; their parameters stay
+// typed. Action/transform/flow node parameters are descriptor-driven raw JSON.
+
+export interface CronTriggerParams {
+  cron_expression: string
+  timezone: string
+}
+
+export type ManualTriggerParams = Record<string, never>
+
+export interface WebhookTriggerParams {
+  token: string
+}
+
+export type EventVerb = 'created' | 'updated' | 'deleted'
+
+export interface EventTriggerParams {
+  entity_slug: string
+  verbs: EventVerb[]
+}
+
+export interface MessageTriggerParams {
+  direction?: string
+  channels?: string[]
+  connection_id?: string
+  event_types?: string[]
+}
+
+export type KickoffType = 'message' | 'outcome'
+
+/**
+ * Where a kickoff draws its instruction text from: typed inline (`manual`) or
+ * resolved from a reusable agent-service Prompt by key (`prompt`) at run time.
+ */
+export type KickoffSource = 'manual' | 'prompt'
+
+export interface WorkflowContentBlock {
+  type: 'text' | 'file'
+  text?: string
+  file_id?: string
+}
+
+export interface MessageKickoff {
+  source?: KickoffSource
+  /** Inline content blocks (manual source). */
+  content?: WorkflowContentBlock[]
+  /** Prompt key whose body becomes the message text (prompt source). */
+  prompt_key?: string
+}
+
+export interface OutcomeRubric {
+  type: 'text' | 'file'
+  content?: string
+  file_id?: string
+}
+
+export interface OutcomeKickoff {
+  /** Description and rubric are independently sourced (manual vs prompt). */
+  description_source?: KickoffSource
+  description?: string
+  description_prompt_key?: string
+  rubric_source?: KickoffSource
+  rubric?: OutcomeRubric
+  rubric_prompt_key?: string
+  max_iterations?: number
+}
+
+export interface AgentKickoff {
+  type: KickoffType
+  message?: MessageKickoff
+  outcome?: OutcomeKickoff
+}
+
+export interface AgentActionParams {
+  agent_key: string
+  kickoff: AgentKickoff
+}
+
+// ---------------------------------------------------------------------------
+// Workflow
+// ---------------------------------------------------------------------------
+
+export interface Workflow extends AuditFields {
+  org_id: string
+  key: string
+  name: string
+  description: string
+  status: WorkflowStatus
+  graph: WorkflowGraph
+  version: number
+}
+
+export interface CreateWorkflowRequest {
+  key: string
+  name: string
+  description?: string
+  graph: WorkflowGraph
+}
+
+export interface UpdateWorkflowRequest {
+  name: string
+  description?: string
+  graph: WorkflowGraph
+}
+
+/**
+ * Body of a manual "run now" call. `destination_node_id` turns the run into a
+ * partial "run until here" execution: only nodes on a path from the trigger to
+ * the destination (inclusive) execute.
+ */
+export interface RunWorkflowRequest {
+  destination_node_id?: string
+}
+
+/** Where a standalone node test's input comes from. */
+export type TestNodeInputSource = 'last_execution' | 'pinned'
+
+/**
+ * The candidate node definition under test — the editor's in-memory (possibly
+ * unsaved) state. Parameters stay raw; Liquid resolves on the node host per
+ * item, exactly like a real run.
+ */
+export interface TestNodeCandidate {
+  type: NodeTypeKey
+  type_version?: number
+  name?: string
+  parameters?: Record<string, unknown>
+  credential_refs?: Record<string, string>
+}
+
+/**
+ * Runs ONE node ephemerally — no execution rows, real side effects. Input is
+ * seeded from the last execution's mirrored input (default) or from the
+ * pinned output of the node's upstream neighbors.
+ */
+export interface TestNodeRequest {
+  node: TestNodeCandidate
+  input_source?: TestNodeInputSource
+}
+
+/**
+ * The full test round trip: the input that was fed in (shown even when the
+ * node fails) and the produced output, items inline per port. Both sides are
+ * capped (`is_truncated`).
+ */
+export interface TestNodeResponse {
+  status: 'succeeded' | 'failed' | 'skipped'
+  input_source: TestNodeInputSource
+  /** False when the workflow (or this node) never ran — nothing was fed in. */
+  has_prior_execution: boolean
+  input: Record<string, Item[]>
+  output: Record<string, Item[]>
+  item_counts: Record<string, number>
+  error?: ExecutionError
+  metadata?: Record<string, unknown>
+  is_truncated: boolean
+}
+
+export interface ListWorkflowsOptions extends ListOptions {
+  name?: string
+  'name[contains]'?: string
+  status?: WorkflowStatus
+}
+
+// ---------------------------------------------------------------------------
+// Versions
+// ---------------------------------------------------------------------------
+
+/**
+ * The author of a workflow version — a common {@link UserRef} that the
+ * versions endpoints enrich with a resolved display `name` when available.
+ */
+export interface WorkflowVersionAuthor extends UserRef {
+  name?: string
+}
+
+/**
+ * One row of a workflow's version history (newest first). Lightweight — the
+ * graph itself is fetched per version via `getVersion`.
+ */
+export interface WorkflowVersionSummary {
+  version: number
+  nodes_total: number
+  created_at: string
+  created_by: WorkflowVersionAuthor
+}
+
+/**
+ * One immutable, fully materialized workflow version: the graph exactly as it
+ * was saved at that version. Versions are append-only — restoring an old
+ * version writes its graph as a NEW bumped version, never rewrites history.
+ */
+export interface WorkflowVersion {
+  org_id: string
+  workflow_key: string
+  version: number
+  graph: WorkflowGraph
+  created_at: string
+  created_by: WorkflowVersionAuthor
+}
+
+// ---------------------------------------------------------------------------
+// Execution
+// ---------------------------------------------------------------------------
+
+/**
+ * Coarse status of one workflow firing (and of one node run — `skipped` is
+ * node-execution-only: the node never ran because no items reached it).
+ */
+export type ExecutionStatus =
+  | 'pending'
+  | 'running'
+  | 'succeeded'
+  | 'failed'
+  | 'cancelled'
+  | 'skipped'
+
+export type TriggerKind = 'schedule' | 'manual' | 'webhook' | 'event' | 'message' | 'workflow'
+
+/**
+ * Why and how an execution fired. Flat, kind-discriminated: `kind` selects
+ * which optional fields are meaningful. `payload` carries the trigger's data
+ * payload and seeds the workflow's first item.
+ */
+export interface ExecutionTriggerContext {
+  kind: TriggerKind
+  // schedule
+  scheduled_at?: string
+  // manual
+  actor?: UserRef
+  // webhook
+  received_at?: string
+  // event
+  topic?: string
+  event_type?: string
+  record_id?: string
+  // message
+  conversation_id?: string
+  channel?: string
+  // workflow (child executions)
+  parent_execution_id?: string
+  payload?: unknown
+}
+
+export interface ExecutionError {
+  code: string
+  message: string
+  /** Marks business failures the user can fix, vs infrastructure faults. */
+  is_user_error?: boolean
+}
+
+/**
+ * One firing of a Workflow. It pins the immutable workflow version it ran
+ * against; per-node results live in the append-only NodeExecution rows keyed
+ * by (execution_id, node_id, run_index).
+ */
+export interface WorkflowExecution {
+  org_id: string
+  id: string
+  workflow_key: string
+  workflow_version: number
+  status: ExecutionStatus
+  trigger_context: ExecutionTriggerContext
+  temporal_workflow_id?: string
+  temporal_run_id?: string
+  error?: ExecutionError
+  started_at?: string
+  finished_at?: string
+  created_at: string
+  created_by: UserRef
+}
+
+/**
+ * One run of one node within an execution — append-only, a new row per
+ * (node_id, run_index) so loops and retries never overwrite history.
+ * `item_counts` counts output items per port; `metadata` carries node-specific
+ * extras (e.g. the agent session id).
+ */
+export interface NodeExecution {
+  org_id: string
+  execution_id: string
+  node_id: string
+  run_index: number
+  node_name: string
+  node_type: NodeTypeKey
+  status: ExecutionStatus
+  input_counts?: Record<string, number>
+  item_counts?: Record<string, number>
+  error?: ExecutionError
+  metadata?: Record<string, unknown>
+  started_at?: string
+  finished_at?: string
+  created_at: string
+}
+
+export interface ListExecutionsOptions extends ListOptions {
+  workflow_key?: string
+  status?: ExecutionStatus
+}
+
+// ---------------------------------------------------------------------------
+// Execution API shapes
+// ---------------------------------------------------------------------------
+
+/** Execution detail: the header row plus its append-only node executions. */
+export interface GetExecutionDetailResponse {
+  execution: WorkflowExecution
+  node_executions: NodeExecution[]
+}
+
+/** Windows into one node run's stored items on one port. */
+export interface GetNodeExecutionItemsOptions {
+  port?: string
+  /**
+   * Which side of the node run to read: its own output ports (default) or the
+   * mirrored copy of what fed it.
+   */
+  side?: 'input' | 'output'
+  offset?: number
+  limit?: number
+}
+
+/** One window of items plus the true total. */
+export interface GetNodeExecutionItemsResponse {
+  items: Item[]
+  items_total: number
+  offset: number
+  limit: number
+}