@proteos/sdk 0.18.1

package/src/workflow/executions.ts

@@ -0,0 +1,99 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  GetExecutionDetailResponse,
+  GetNodeExecutionItemsOptions,
+  GetNodeExecutionItemsResponse,
+  ListExecutionsOptions,
+  WorkflowExecution,
+} from './types.js'
+
+const EXECUTIONS_BASE_PATH = '/workflows/v1/executions'
+const WORKFLOWS_BASE_PATH = '/workflows/v1/workflows'
+
+/**
+ * Service for reading Workflow Executions — append-only per-firing run records,
+ * keyed by surrogate `id`, referencing their workflow by `workflow_key`.
+ */
+export interface ExecutionService {
+  /** Lists executions, auto-paginating. */
+  list(options?: ListExecutionsOptions): PageIterator<WorkflowExecution, ListExecutionsOptions>
+  /** Fetches a single page of executions with pagination metadata. */
+  listPage(options?: ListExecutionsOptions): Promise<ListResult<WorkflowExecution>>
+  /** Gets a single execution by id. @throws {ProteosError} 404 if not found. */
+  get(id: string): Promise<WorkflowExecution>
+  /**
+   * Gets the execution detail: the header row plus its append-only node
+   * executions (ordered by started_at, then run_index).
+   */
+  getDetail(id: string): Promise<GetExecutionDetailResponse>
+  /**
+   * Windows into one node run's stored output items on one port (defaults:
+   * port `main`, offset 0, server-side default limit).
+   */
+  getNodeItems(
+    executionId: string,
+    nodeId: string,
+    runIndex: number,
+    options?: GetNodeExecutionItemsOptions,
+  ): Promise<GetNodeExecutionItemsResponse>
+  /** Lists executions of one workflow (by key). */
+  listForWorkflow(
+    key: string,
+    options?: ListExecutionsOptions,
+  ): Promise<ListResult<WorkflowExecution>>
+}
+
+export class ExecutionServiceImpl implements ExecutionService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(
+    options: ListExecutionsOptions = {},
+  ): PageIterator<WorkflowExecution, ListExecutionsOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListExecutionsOptions = {}): Promise<ListResult<WorkflowExecution>> {
+    return this.client.requestWithQuery<ListResult<WorkflowExecution>>(
+      'GET',
+      EXECUTIONS_BASE_PATH,
+      options,
+    )
+  }
+
+  async get(id: string): Promise<WorkflowExecution> {
+    return this.client.request<WorkflowExecution>('GET', `${EXECUTIONS_BASE_PATH}/${id}`)
+  }
+
+  async getDetail(id: string): Promise<GetExecutionDetailResponse> {
+    return this.client.request<GetExecutionDetailResponse>(
+      'GET',
+      `${EXECUTIONS_BASE_PATH}/${id}/detail`,
+    )
+  }
+
+  async getNodeItems(
+    executionId: string,
+    nodeId: string,
+    runIndex: number,
+    options: GetNodeExecutionItemsOptions = {},
+  ): Promise<GetNodeExecutionItemsResponse> {
+    return this.client.requestWithQuery<GetNodeExecutionItemsResponse>(
+      'GET',
+      `${EXECUTIONS_BASE_PATH}/${executionId}/nodes/${nodeId}/runs/${runIndex}/items`,
+      options,
+    )
+  }
+
+  async listForWorkflow(
+    key: string,
+    options: ListExecutionsOptions = {},
+  ): Promise<ListResult<WorkflowExecution>> {
+    return this.client.requestWithQuery<ListResult<WorkflowExecution>>(
+      'GET',
+      `${WORKFLOWS_BASE_PATH}/${key}/executions`,
+      options,
+    )
+  }
+}

package/src/workflow/index.ts

@@ -0,0 +1,109 @@
+import type { ProteosClient } from '../client.js'
+import { type ExecutionService, ExecutionServiceImpl } from './executions.js'
+import { type NodeTypeService, NodeTypeServiceImpl } from './node-types.js'
+import { type WorkflowService, WorkflowServiceImpl } from './workflows.js'
+
+/**
+ * Client for the Proteos Workflow Service API.
+ *
+ * Manages n8n-shaped automation workflows (keyed by immutable `key`), the
+ * node-type catalog (NodeDescriptors) that drives the editor, and workflow
+ * executions (Temporal-backed, surrogate-id'd).
+ *
+ * @example
+ * ```ts
+ * import { ProteosClient, WorkflowClient } from '@proteos/sdk';
+ *
+ * const client = new ProteosClient({ baseUrl, token });
+ * const workflow = new WorkflowClient(client);
+ *
+ * const catalog = await workflow.nodeTypes.list();
+ * const workflows = await workflow.workflows.list().all();
+ * const execution = await workflow.workflows.run('nightly-triage');
+ * const detail = await workflow.executions.getDetail(execution.id);
+ * ```
+ */
+export class WorkflowClient {
+  /** Service for managing workflow definitions. */
+  readonly workflows: WorkflowService
+  /** Service for reading workflow executions. */
+  readonly executions: ExecutionService
+  /** Service for the node-type catalog + dynamic node methods. */
+  readonly nodeTypes: NodeTypeService
+
+  constructor(client: ProteosClient) {
+    this.workflows = new WorkflowServiceImpl(client)
+    this.executions = new ExecutionServiceImpl(client)
+    this.nodeTypes = new NodeTypeServiceImpl(client)
+  }
+}
+
+export type { ExecutionService } from './executions.js'
+export type { NodeTypeService } from './node-types.js'
+export type {
+  AgentActionParams,
+  AgentKickoff,
+  BinaryRef,
+  ConnectionEndpoint,
+  CreateWorkflowRequest,
+  CredentialSpec,
+  CronTriggerParams,
+  DisplayOptions,
+  EventTriggerParams,
+  EventVerb,
+  ExecutionError,
+  ExecutionStatus,
+  ExecutionTriggerContext,
+  GetExecutionDetailResponse,
+  GetNodeExecutionItemsOptions,
+  GetNodeExecutionItemsResponse,
+  GetNodeTypesResponse,
+  InvokeNodeMethodRequest,
+  InvokeNodeMethodResponse,
+  Item,
+  KickoffSource,
+  KickoffType,
+  ListExecutionsOptions,
+  ListWorkflowsOptions,
+  ManualTriggerParams,
+  MessageKickoff,
+  MessageTriggerParams,
+  NodeDescriptor,
+  NodeExecution,
+  NodeGroup,
+  NodeMethodOption,
+  NodePosition,
+  NodeProperty,
+  NodeRetryPolicy,
+  NodeRuntime,
+  NodeTypeKey,
+  NodeTypeStatus,
+  OnErrorPolicy,
+  OutcomeKickoff,
+  OutcomeRubric,
+  PairedItem,
+  PortSpec,
+  PropertyOption,
+  PropertyType,
+  RunWorkflowRequest,
+  TestNodeCandidate,
+  TestNodeInputSource,
+  TestNodeRequest,
+  TestNodeResponse,
+  TriggerKind,
+  UpdateWorkflowRequest,
+  WebhookTriggerParams,
+  Workflow,
+  WorkflowConnection,
+  WorkflowContentBlock,
+  WorkflowExecution,
+  WorkflowGraph,
+  WorkflowNode,
+  WorkflowNodeType,
+  WorkflowStatus,
+  WorkflowVersion,
+  WorkflowVersionAuthor,
+  WorkflowVersionSummary,
+} from './types.js'
+export { DEFAULT_PORT, ERROR_PORT } from './types.js'
+export type { WorkflowService } from './workflows.js'

package/src/workflow/node-types.ts

@@ -0,0 +1,50 @@
+import type { ProteosClient } from '../client.js'
+import type {
+  GetNodeTypesResponse,
+  InvokeNodeMethodRequest,
+  InvokeNodeMethodResponse,
+  NodeTypeKey,
+  WorkflowNodeType,
+} from './types.js'
+
+const NODE_TYPES_BASE_PATH = '/workflows/v1/node-types'
+
+/**
+ * Service for the node-type catalog — the registered NodeDescriptors that
+ * drive the editor's picker and parameter forms — and for proxying editor
+ * dynamic-method calls (load_options / list_search / …) to the node host.
+ */
+export interface NodeTypeService {
+  /**
+   * Lists the catalog visible to the caller's org (platform-global +
+   * org-installed types, all registered versions, active only).
+   */
+  list(): Promise<WorkflowNodeType[]>
+  /**
+   * Invokes a dynamic method on a node type (e.g. `load_options:listEntities`
+   * — pass the full `<kind>:<method_name>` string; it is URL-encoded here).
+   */
+  invokeMethod(
+    type: NodeTypeKey,
+    method: string,
+    request?: InvokeNodeMethodRequest,
+  ): Promise<InvokeNodeMethodResponse>
+}
+
+export class NodeTypeServiceImpl implements NodeTypeService {
+  constructor(private readonly client: ProteosClient) {}
+
+  async list(): Promise<WorkflowNodeType[]> {
+    const response = await this.client.request<GetNodeTypesResponse>('GET', NODE_TYPES_BASE_PATH)
+    return response.data
+  }
+
+  async invokeMethod(
+    type: NodeTypeKey,
+    method: string,
+    request: InvokeNodeMethodRequest = {},
+  ): Promise<InvokeNodeMethodResponse> {
+    const path = `${NODE_TYPES_BASE_PATH}/${encodeURIComponent(type)}/methods/${encodeURIComponent(method)}`
+    return this.client.request<InvokeNodeMethodResponse>('POST', path, request)
+  }
+}