@amaster.ai/client 1.0.0-alpha.1

package/types/workflow.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 
+ * @module workflow
+ */
+
+import type { ClientResult } from './common';
+
+/**
+ * Workflow execution response mode
+ * - `blocking`: Wait for workflow completion (default)
+ * - `streaming`: Stream workflow execution progress
+ */
+export type WorkflowResponseMode = 'blocking' | 'streaming';
+
+/**
+ * Workflow input value (can be any JSON-serializable type)
+ */
+export type WorkflowInputValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Record<string, unknown>
+  | unknown[];
+
+/**
+ * Workflow file attachment
+ *
+ */
+export interface WorkflowFile {
+  /** File name */
+  name?: string;
+  /** MIME type */
+  type?: string;
+  /** File URL */
+  url?: string;
+  /** Additional metadata */
+  [key: string]: unknown;
+}
+
+/**
+ * Workflow execution request parameters
+ * 
+ * @since 1.0.0
+ */
+export interface WorkflowRunRequest {
+  /** Input variables for the workflow */
+  inputs?: Record<string, WorkflowInputValue>;
+  /** 
+   * Response mode
+   * @default 'blocking'
+   */
+  response_mode?: WorkflowResponseMode;
+  /** 
+   * User identifier
+   * @default 'anonymous'
+   */
+  user?: string;
+  /** File attachments */
+  files?: WorkflowFile[];
+  /** Trace ID for debugging */
+  trace_id?: string;
+}
+
+/**
+ * Workflow execution response
+ * 
+ * @template TOutput - The type of workflow outputs
+ *
+ */
+export interface WorkflowRunResponse<TOutput = Record<string, unknown>> {
+  /** Task ID */
+  task_id: string;
+  /** Workflow run ID */
+  workflow_run_id: string;
+  /** 
+   * Execution status
+   */
+  status: string;
+  /** Workflow output data */
+  outputs: TOutput;
+  /** Error message (if failed) */
+  error: string | null;
+  /** Execution time in milliseconds */
+  elapsed_time: number;
+  /** Total tokens consumed (for LLM workflows) */
+  total_tokens: number;
+  /** Total workflow steps executed */
+  total_steps: number;
+  /** Creation timestamp (Unix time in milliseconds) */
+  created_at: number;
+  /** Completion timestamp (Unix time in milliseconds) */
+  finished_at: number;
+}
+
+// ==================== Workflow Client API ====================
+
+/**
+ * Workflow Execution Client API
+ * 
+ * Provides methods for executing Dify-style workflows.
+ * 
+ * @since 1.0.0
+ */
+export interface WorkflowClientAPI {
+  /**
+   * Execute a workflow
+   * 
+   * Runs a workflow with the provided inputs and returns the result.
+   * Automatically injects `app_id` from URL if in browser environment.
+   * 
+   * @template TOutput - The type of workflow outputs
+   * @param workflowName - Workflow identifier (key/name)
+   * @param inputs - Workflow inputs (can be simple object or WorkflowRunRequest)
+   * @returns Workflow execution result
+   * 
+   * @example
+   * // Simple execution
+   * const result = await client.workflow.run('data-processor', {
+   *   source: 'users',
+   *   limit: 100
+   * });
+   * 
+   * if (result.success) {
+   *   console.log('Output:', result.data.outputs);
+   * }
+   * 
+   * @example
+   * // With type safety
+   * type Output = { processedCount: number; results: string[] };
+   * const result = await client.workflow.run<Output>('batch-processor', {
+   *   batchSize: 50
+   * });
+   * 
+   * @since 1.0.0
+   */
+  run<TOutput = Record<string, unknown>>(
+    workflowName: string,
+    inputs?: Record<string, WorkflowInputValue> | WorkflowRunRequest
+  ): Promise<ClientResult<WorkflowRunResponse<TOutput>>>;
+}