@amaster.ai/client 1.1.0-beta.0

package/types/workflow.d.ts

@@ -0,0 +1,291 @@
+/**
+ * ============================================================================
+ * Workflow Module - Type Definitions
+ * ============================================================================
+ * 
+ * This module provides workflow execution capabilities using Dify-style
+ * workflow engine.
+ * 
+ * ## Key Features
+ * - Execute workflows with inputs
+ * - Blocking or streaming execution modes
+ * - File upload support
+ * - Trace ID for debugging
+ * - Auto-inject app_id from URL
+ * 
+ * @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
+ * 
+ * @example
+ * ```typescript
+ * const file: WorkflowFile = {
+ *   name: 'document.pdf',
+ *   type: 'application/pdf',
+ *   url: 'https://cdn.example.com/document.pdf'
+ * };
+ * ```
+ */
+export interface WorkflowFile {
+  /** File name */
+  name?: string;
+  /** MIME type */
+  type?: string;
+  /** File URL */
+  url?: string;
+  /** Additional metadata */
+  [key: string]: unknown;
+}
+
+/**
+ * Workflow execution request parameters
+ * 
+ * @example
+ * Simple execution:
+ * ```typescript
+ * const request: WorkflowRunRequest = {
+ *   inputs: {
+ *     query: 'What is the weather?',
+ *     location: 'New York'
+ *   }
+ * };
+ * ```
+ * 
+ * @example
+ * With files:
+ * ```typescript
+ * const request: WorkflowRunRequest = {
+ *   inputs: { action: 'analyze' },
+ *   files: [{
+ *     name: 'data.csv',
+ *     type: 'text/csv',
+ *     url: 'https://example.com/data.csv'
+ *   }],
+ *   user: 'user-123',
+ *   trace_id: 'trace-abc-456'
+ * };
+ * ```
+ */
+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
+ * 
+ * @example
+ * ```typescript
+ * interface AnalysisOutput {
+ *   summary: string;
+ *   sentiment: 'positive' | 'negative' | 'neutral';
+ *   keywords: string[];
+ * }
+ * 
+ * const result = await client.workflow.run<AnalysisOutput>('text-analysis', {
+ *   text: 'This is a great product!'
+ * });
+ * 
+ * console.log(result.data.outputs.summary);
+ * console.log(result.data.outputs.sentiment); // 'positive'
+ * ```
+ */
+export interface WorkflowRunResponse<TOutput = Record<string, unknown>> {
+  /** Task ID */
+  task_id: string;
+  /** Workflow run ID */
+  workflow_run_id: string;
+  /** 
+   * Execution status
+   * @example 'succeeded', 'failed', 'running'
+   */
+  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.
+ * 
+ * @example
+ * Complete workflow execution:
+ * ```typescript
+ * const client = createClient({ baseURL: 'https://api.amaster.ai' });
+ * 
+ * // 1. Simple text processing workflow
+ * const result = await client.workflow.run('text-summarizer', {
+ *   text: 'Long article content here...',
+ *   max_words: 100
+ * });
+ * 
+ * if (result.data) {
+ *   console.log('Summary:', result.data.outputs.summary);
+ *   console.log('Time taken:', result.data.elapsed_time, 'ms');
+ *   console.log('Tokens used:', result.data.total_tokens);
+ * }
+ * 
+ * // 2. Data analysis workflow with type safety
+ * interface AnalysisOutput {
+ *   insights: string[];
+ *   score: number;
+ *   recommendations: string[];
+ * }
+ * 
+ * const analysis = await client.workflow.run<AnalysisOutput>('data-analyzer', {
+ *   dataset: 'sales-2024',
+ *   metric: 'revenue'
+ * });
+ * 
+ * console.log('Insights:', analysis.data.outputs.insights);
+ * console.log('Score:', analysis.data.outputs.score);
+ * ```
+ */
+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 with inputs:
+   * ```typescript
+   * const result = await client.workflow.run('greeting', {
+   *   name: 'Alice',
+   *   language: 'en'
+   * });
+   * 
+   * console.log(result.data.outputs.message); // "Hello, Alice!"
+   * ```
+   * 
+   * @example
+   * With full request configuration:
+   * ```typescript
+   * const result = await client.workflow.run('document-processor', {
+   *   inputs: {
+   *     action: 'extract',
+   *     format: 'json'
+   *   },
+   *   files: [{
+   *     name: 'invoice.pdf',
+   *     url: 'https://example.com/invoice.pdf'
+   *   }],
+   *   user: 'user-123',
+   *   trace_id: 'req-abc-456'
+   * });
+   * ```
+   * 
+   * @example
+   * Type-safe outputs:
+   * ```typescript
+   * interface SentimentOutput {
+   *   sentiment: 'positive' | 'negative' | 'neutral';
+   *   confidence: number;
+   *   keywords: string[];
+   * }
+   * 
+   * const result = await client.workflow.run<SentimentOutput>('sentiment-analysis', {
+   *   text: 'I love this product! It works great.'
+   * });
+   * 
+   * if (result.data) {
+   *   // TypeScript knows the structure of outputs
+   *   console.log(result.data.outputs.sentiment);   // Type: 'positive' | 'negative' | 'neutral'
+   *   console.log(result.data.outputs.confidence);  // Type: number
+   *   console.log(result.data.outputs.keywords);    // Type: string[]
+   * }
+   * ```
+   * 
+   * @example
+   * Error handling:
+   * ```typescript
+   * const result = await client.workflow.run('risky-workflow', { input: 'test' });
+   * 
+   * if (result.error) {
+   *   console.error('Workflow failed:', result.error.message);
+   * } else if (result.data.error) {
+   *   console.error('Workflow error:', result.data.error);
+   * } else {
+   *   console.log('Success:', result.data.outputs);
+   * }
+   * ```
+   * 
+   * @example
+   * Performance monitoring:
+   * ```typescript
+   * const startTime = Date.now();
+   * const result = await client.workflow.run('heavy-task', { data: largeDataset });
+   * 
+   * if (result.data) {
+   *   console.log(`Network time: ${Date.now() - startTime}ms`);
+   *   console.log(`Execution time: ${result.data.elapsed_time}ms`);
+   *   console.log(`Steps: ${result.data.total_steps}`);
+   *   console.log(`Tokens: ${result.data.total_tokens}`);
+   * }
+   * ```
+   */
+  run<TOutput = Record<string, unknown>>(
+    workflowName: string,
+    inputs?: Record<string, WorkflowInputValue> | WorkflowRunRequest
+  ): Promise<ClientResult<WorkflowRunResponse<TOutput>>>;
+}