@wave-av/workflow-sdk 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 1.0.0 (2026-04-02)
+
+- Initial release
+- Workflow builder with fluent API
+- 3 subpath exports: root, `./types`, `./client`
+- Real-time execution events via EventEmitter
+- Zod schema validation

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WAVE Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# @wave-av/workflow-sdk
+
+Official SDK for building and executing workflows on the WAVE platform.
+
+## Installation
+
+```bash
+npm install @wave-av/workflow-sdk
+# or
+yarn add @wave-av/workflow-sdk
+# or
+pnpm add @wave-av/workflow-sdk
+```
+
+## Quick start
+
+```typescript
+import { WaveWorkflowClient } from '@wave-av/workflow-sdk';
+
+// Create a client
+const client = new WaveWorkflowClient({
+  apiKey: process.env.WAVE_API_KEY!,
+  organizationId: 'org_123',
+});
+
+// Execute a workflow
+const execution = await client.execute('my-workflow', {
+  input_params: {
+    environment: 'production',
+  },
+});
+
+console.log('Execution started:', execution.id);
+
+// Wait for completion
+const result = await client.waitForCompletion(execution.id);
+console.log('Result:', result.status);
+```
+
+## Building workflows
+
+Use the fluent builder API to create workflow definitions:
+
+```typescript
+import { WorkflowBuilder } from '@wave-av/workflow-sdk';
+
+const workflow = new WorkflowBuilder('data-pipeline')
+  .name('Data Processing Pipeline')
+  .description('ETL pipeline for processing analytics data')
+  .category('data-processing')
+  .version('1.0.0')
+  .tags('etl', 'analytics')
+  .phase('extract', (phase) =>
+    phase
+      .description('Extract data from source systems')
+      .agent('data-extractor', { source: 'api', endpoint: '/data' })
+  )
+  .phase('transform', (phase) =>
+    phase
+      .description('Transform and validate data')
+      .agent('data-transformer', { format: 'json' })
+      .onFailure('retry')
+  )
+  .phase('load', (phase) =>
+    phase
+      .description('Load data to destination')
+      .agent('data-loader', { destination: 'database' })
+  )
+  .timeout(3600)
+  .enableCheckpoints()
+  .maxRetries(3)
+  .build();
+
+// Export as JSON
+console.log(JSON.stringify(workflow, null, 2));
+```
+
+## API reference
+
+### WaveWorkflowClient
+
+#### Constructor options
+
+```typescript
+const client = new WaveWorkflowClient({
+  apiKey: string;           // Required: API key for authentication
+  organizationId: string;   // Required: Organization ID for tenant isolation
+  baseUrl?: string;         // Optional: API base URL (default: https://api.wave.online)
+  timeout?: number;         // Optional: Request timeout in ms (default: 30000)
+  debug?: boolean;          // Optional: Enable debug logging
+});
+```
+
+#### Methods
+
+##### Workflow definitions
+
+```typescript
+// Get a workflow by slug
+const workflow = await client.getWorkflow('my-workflow');
+
+// List all workflows
+const { workflows, total } = await client.listWorkflows({
+  category: 'devops',
+  status: 'active',
+  limit: 10,
+});
+```
+
+##### Executions
+
+```typescript
+// Execute a workflow
+const execution = await client.execute('my-workflow', {
+  input_params: { key: 'value' },
+  idempotency_key: 'unique-key',
+});
+
+// Get execution status
+const status = await client.getExecution(execution.id);
+
+// List executions
+const { executions } = await client.listExecutions({
+  workflow_id: 'workflow-id',
+  status: 'running',
+  limit: 20,
+});
+
+// Cancel an execution
+await client.cancelExecution(execution.id);
+
+// Pause an execution
+await client.pauseExecution(execution.id);
+
+// Resume a paused execution
+await client.resumeExecution(execution.id);
+
+// Retry a failed execution
+await client.retryExecution(execution.id, { from_checkpoint: true });
+```
+
+##### Convenience methods
+
+```typescript
+// Wait for completion with progress callback
+const result = await client.waitForCompletion(execution.id, {
+  pollInterval: 2000,  // Poll every 2 seconds
+  timeout: 3600000,    // 1 hour timeout
+  onProgress: (exec) => {
+    console.log(`Status: ${exec.status}, Phase: ${exec.current_phase}`);
+  },
+});
+
+// Execute and wait in one call
+const result = await client.executeAndWait('my-workflow', {
+  input_params: { key: 'value' },
+});
+```
+
+##### Logs
+
+```typescript
+// Get execution logs
+const { logs } = await client.getLogs(execution.id, {
+  level: 'error',
+  limit: 100,
+});
+```
+
+##### Real-time events
+
+```typescript
+// Subscribe to execution events
+const unsubscribe = client.subscribeToExecution(execution.id);
+
+client.on('execution.started', (event) => {
+  console.log('Execution started:', event);
+});
+
+client.on('phase.completed', (event) => {
+  console.log('Phase completed:', event.data.phase_name);
+});
+
+client.on('execution.completed', (event) => {
+  console.log('Execution completed in', event.data.duration_ms, 'ms');
+  unsubscribe();
+});
+
+client.on('error', (error) => {
+  console.error('Error:', error);
+});
+```
+
+## Types
+
+All TypeScript types are exported from the package:
+
+```typescript
+import type {
+  WorkflowDefinition,
+  WorkflowPhase,
+  WorkflowAgent,
+  WorkflowConfig,
+  WorkflowExecution,
+  ExecutionStatus,
+  ExecutionLog,
+  AnyWorkflowEvent,
+} from '@wave-av/workflow-sdk';
+```
+
+## Validation
+
+The SDK includes Zod schemas for runtime validation:
+
+```typescript
+import { WorkflowDefinitionSchema } from '@wave-av/workflow-sdk/types';
+
+const result = WorkflowDefinitionSchema.safeParse(workflowData);
+if (!result.success) {
+  console.error('Validation errors:', result.error.issues);
+}
+```
+
+## Error handling
+
+```typescript
+try {
+  const execution = await client.execute('my-workflow');
+} catch (error) {
+  if (error.message.includes('API error (404)')) {
+    console.error('Workflow not found');
+  } else if (error.message.includes('timeout')) {
+    console.error('Request timed out');
+  } else {
+    console.error('Unknown error:', error);
+  }
+}
+```
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `WAVE_API_KEY` | API key for authentication |
+| `WAVE_ORGANIZATION_ID` | Organization ID for tenant isolation |
+| `WAVE_API_URL` | Optional: Custom API base URL |
+
+## License
+
+MIT

package/dist/chunk-M3UAADWT.mjs

@@ -0,0 +1,237 @@
+// src/client.ts
+import { EventEmitter } from "eventemitter3";
+var WaveWorkflowClient = class extends EventEmitter {
+  config;
+  headers;
+  constructor(config) {
+    super();
+    this.config = {
+      baseUrl: "https://api.wave.online",
+      timeout: 3e4,
+      debug: false,
+      ...config
+    };
+    this.headers = {
+      "Authorization": `Bearer ${this.config.apiKey}`,
+      "Content-Type": "application/json",
+      "X-Organization-Id": this.config.organizationId
+    };
+  }
+  // ==========================================================================
+  // Workflow Definitions
+  // ==========================================================================
+  /**
+   * Get a workflow definition by slug
+   */
+  async getWorkflow(slug) {
+    return this.request(`/v1/workflows/${slug}`);
+  }
+  /**
+   * List all workflows
+   */
+  async listWorkflows(options) {
+    const params = new URLSearchParams();
+    if (options?.category) params.set("category", options.category);
+    if (options?.status) params.set("status", options.status);
+    if (options?.limit) params.set("limit", String(options.limit));
+    if (options?.offset) params.set("offset", String(options.offset));
+    return this.request(`/v1/workflows?${params.toString()}`);
+  }
+  // ==========================================================================
+  // Workflow Executions
+  // ==========================================================================
+  /**
+   * Execute a workflow
+   */
+  async execute(workflowSlug, request) {
+    const response = await this.request(
+      `/v1/workflows/${workflowSlug}/execute`,
+      {
+        method: "POST",
+        body: JSON.stringify(request || {})
+      }
+    );
+    return response.execution;
+  }
+  /**
+   * Get execution status
+   */
+  async getExecution(executionId) {
+    return this.request(`/v1/executions/${executionId}`);
+  }
+  /**
+   * List executions
+   */
+  async listExecutions(request) {
+    const params = new URLSearchParams();
+    if (request?.workflow_id) params.set("workflow_id", request.workflow_id);
+    if (request?.status) params.set("status", request.status);
+    if (request?.limit) params.set("limit", String(request.limit));
+    if (request?.offset) params.set("offset", String(request.offset));
+    if (request?.order_by) params.set("order_by", request.order_by);
+    if (request?.order) params.set("order", request.order);
+    return this.request(`/v1/executions?${params.toString()}`);
+  }
+  /**
+   * Cancel a running execution
+   */
+  async cancelExecution(executionId) {
+    return this.request(
+      `/v1/executions/${executionId}/cancel`,
+      { method: "POST" }
+    );
+  }
+  /**
+   * Pause a running execution
+   */
+  async pauseExecution(executionId) {
+    return this.request(
+      `/v1/executions/${executionId}/pause`,
+      { method: "POST" }
+    );
+  }
+  /**
+   * Resume a paused execution
+   */
+  async resumeExecution(executionId) {
+    return this.request(
+      `/v1/executions/${executionId}/resume`,
+      { method: "POST" }
+    );
+  }
+  /**
+   * Retry a failed execution
+   */
+  async retryExecution(executionId, options) {
+    return this.request(
+      `/v1/executions/${executionId}/retry`,
+      {
+        method: "POST",
+        body: JSON.stringify(options || {})
+      }
+    );
+  }
+  // ==========================================================================
+  // Execution Logs
+  // ==========================================================================
+  /**
+   * Get execution logs
+   */
+  async getLogs(executionId, options) {
+    const params = new URLSearchParams();
+    if (options?.level) params.set("level", options.level);
+    if (options?.limit) params.set("limit", String(options.limit));
+    if (options?.offset) params.set("offset", String(options.offset));
+    return this.request(`/v1/executions/${executionId}/logs?${params.toString()}`);
+  }
+  // ==========================================================================
+  // Convenience Methods
+  // ==========================================================================
+  /**
+   * Wait for an execution to complete
+   */
+  async waitForCompletion(executionId, options) {
+    const pollInterval = options?.pollInterval || 2e3;
+    const timeout = options?.timeout || 36e5;
+    const startTime = Date.now();
+    const terminalStatuses = [
+      "completed",
+      "failed",
+      "cancelled",
+      "timeout"
+    ];
+    while (Date.now() - startTime < timeout) {
+      const execution = await this.getExecution(executionId);
+      if (options?.onProgress) {
+        options.onProgress(execution);
+      }
+      if (terminalStatuses.includes(execution.status)) {
+        return execution;
+      }
+      await this.sleep(pollInterval);
+    }
+    throw new Error(`Execution ${executionId} timed out after ${timeout}ms`);
+  }
+  /**
+   * Execute a workflow and wait for completion
+   */
+  async executeAndWait(workflowSlug, request, waitOptions) {
+    const execution = await this.execute(workflowSlug, request);
+    return this.waitForCompletion(execution.id, waitOptions);
+  }
+  // ==========================================================================
+  // Real-time Events (WebSocket)
+  // ==========================================================================
+  /**
+   * Subscribe to real-time execution events
+   */
+  subscribeToExecution(executionId) {
+    const wsUrl = this.config.baseUrl.replace("https://", "wss://").replace("http://", "ws://");
+    const ws = new WebSocket(
+      `${wsUrl}/v1/executions/${executionId}/events?token=${this.config.apiKey}`
+    );
+    ws.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        this.emit(data.type, data);
+      } catch (error) {
+        this.emit("error", error);
+      }
+    };
+    ws.onerror = (error) => {
+      this.emit("error", new Error(`WebSocket error: ${error}`));
+    };
+    return () => {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.close();
+      }
+    };
+  }
+  // ==========================================================================
+  // Private Helpers
+  // ==========================================================================
+  async request(path, options) {
+    const url = `${this.config.baseUrl}${path}`;
+    if (this.config.debug) {
+      console.log(`[WaveWorkflowClient] ${options?.method || "GET"} ${url}`);
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(
+      () => controller.abort(),
+      this.config.timeout
+    );
+    try {
+      const response = await fetch(url, {
+        ...options,
+        headers: {
+          ...this.headers,
+          ...options?.headers
+        },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`API error (${response.status}): ${error}`);
+      }
+      return response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new Error(`Request timeout after ${this.config.timeout}ms`);
+      }
+      throw error;
+    }
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+function createClient(config) {
+  return new WaveWorkflowClient(config);
+}
+
+export {
+  WaveWorkflowClient,
+  createClient
+};

package/dist/chunk-O4EIGRTS.mjs

@@ -0,0 +1,57 @@
+// src/types.ts
+import { z } from "zod";
+var WorkflowAgentSchema = z.object({
+  type: z.string().min(1),
+  config: z.record(z.unknown()).optional(),
+  timeout_seconds: z.number().int().positive().optional(),
+  retry_policy: z.object({
+    max_attempts: z.number().int().positive(),
+    backoff_type: z.enum(["fixed", "exponential"]),
+    initial_delay_ms: z.number().int().positive(),
+    max_delay_ms: z.number().int().positive().optional()
+  }).optional()
+});
+var WorkflowPhaseSchema = z.object({
+  name: z.string().min(1).max(100),
+  description: z.string().max(500).optional(),
+  order: z.number().int().positive(),
+  agents: z.array(WorkflowAgentSchema),
+  condition: z.object({
+    type: z.enum(["expression", "previous_phase_status"]),
+    expression: z.string().optional(),
+    required_status: z.enum(["completed", "skipped"]).optional()
+  }).optional(),
+  on_failure: z.enum(["fail", "skip", "retry"]).optional()
+});
+var WorkflowConfigSchema = z.object({
+  timeout_seconds: z.number().int().positive().max(86400).optional(),
+  max_retries: z.number().int().min(0).max(10).optional(),
+  checkpoint_enabled: z.boolean().optional(),
+  parallel_phases: z.boolean().optional(),
+  fail_fast: z.boolean().optional(),
+  notification_channels: z.array(z.string()).optional()
+});
+var WorkflowDefinitionSchema = z.object({
+  name: z.string().min(1).max(200),
+  slug: z.string().regex(/^[a-z0-9-]+$/).min(1).max(100),
+  description: z.string().max(1e3).optional(),
+  category: z.string().min(1).max(50),
+  version: z.string().regex(/^\d+\.\d+\.\d+$/),
+  phases: z.array(WorkflowPhaseSchema).min(1),
+  config: WorkflowConfigSchema.optional(),
+  tags: z.array(z.string().max(50)).max(10).optional()
+});
+var ExecuteWorkflowRequestSchema = z.object({
+  input_params: z.record(z.unknown()).optional(),
+  trigger_type: z.enum(["manual", "api"]).optional(),
+  idempotency_key: z.string().max(100).optional(),
+  checkpoint_id: z.string().uuid().optional()
+});
+
+export {
+  WorkflowAgentSchema,
+  WorkflowPhaseSchema,
+  WorkflowConfigSchema,
+  WorkflowDefinitionSchema,
+  ExecuteWorkflowRequestSchema
+};