@ironflow/node 0.1.0-test.2 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @ironflow/node
 
-Node.js SDK for [Ironflow](https://github.com/anthropics/ironflow) workflow engine. Provides workers, serve handlers, and step execution for serverless and long-running functions.
+Node.js SDK for [Ironflow](https://github.com/sahina/ironflow), an event-driven backend platform. Provides workers, serve handlers, and step execution for serverless and long-running functions.
 
 ## Installation
 
@@ -56,7 +56,7 @@ import { createWorker } from '@ironflow/node';
 const worker = createWorker({
   serverUrl: 'http://localhost:9123',
   functions: [processOrder],
-  maxConcurrentJobs: 4,
+  maxConcurrentJobs: 10,
 });
 
 await worker.start();
@@ -80,8 +80,8 @@ await worker.start();
 | `step.run(id, fn)` | Execute memoized step |
 | `step.sleep(id, duration)` | Durable sleep |
 | `step.waitForEvent(id, options)` | Wait for external event |
-| `step.parallel(steps)` | Execute steps in parallel |
-| `step.map(id, items, fn)` | Map over items in parallel |
+| `step.parallel(name, branches, options?)` | Execute branches in parallel |
+| `step.map(name, items, fn, options?)` | Map over items in parallel |
 
 ## Environment Variables
 

package/dist/client.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Ironflow Node.js Client
+ *
+ * HTTP client for interacting with the Ironflow server.
+ * Provides methods for registering functions, triggering events, and managing runs.
+ */
+import { type RunStatus, type Trigger, type ExecutionMode, type RetryConfig, type ConcurrencyConfig, type AppendEventInput, type AppendOptions, type AppendResult, type ReadStreamOptions, type StreamEvent, type StreamInfo } from "@ironflow/core";
+import { KVClient } from "./kv.js";
+import { ConfigClient } from "./config-client.js";
+/**
+ * Configuration for the Ironflow client
+ */
+export interface IronflowClientConfig {
+    /** Server URL (default: http://localhost:9123 or IRONFLOW_SERVER_URL env var) */
+    serverUrl?: string;
+    /** API key for authentication (optional for local dev) */
+    apiKey?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Function registration request
+ */
+export interface RegisterFunctionRequest {
+    /** Unique function identifier */
+    id: string;
+    /** Display name */
+    name?: string;
+    /** Description */
+    description?: string;
+    /** Event triggers */
+    triggers?: Trigger[];
+    /** Retry configuration */
+    retry?: RetryConfig;
+    /** Timeout in milliseconds */
+    timeoutMs?: number;
+    /** Concurrency configuration */
+    concurrency?: ConcurrencyConfig;
+    /** Preferred execution mode */
+    preferredMode?: ExecutionMode;
+    /** Endpoint URL for push mode */
+    endpointUrl?: string;
+    /** Actor key for sticky routing */
+    actorKey?: string;
+}
+/**
+ * Result from registering a function
+ */
+export interface RegisterFunctionResult {
+    /** Whether the function was newly created (vs updated) */
+    created: boolean;
+}
+/**
+ * Result from emitting an event
+ */
+export interface EmitResult {
+    /** IDs of runs created by this event */
+    runIds: string[];
+    /** ID of the stored event */
+    eventId: string;
+}
+/**
+ * Options for emitting an event
+ */
+export interface EmitOptions {
+    /** Event schema version (default 1) */
+    version?: number;
+    /** Idempotency key to prevent duplicate processing */
+    idempotencyKey?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Run information
+ */
+export interface Run {
+    /** Run ID */
+    id: string;
+    /** Function ID */
+    functionId: string;
+    /** Event ID that triggered this run */
+    eventId: string;
+    /** Current status */
+    status: RunStatus;
+    /** Current attempt number */
+    attempt: number;
+    /** Maximum attempts allowed */
+    maxAttempts: number;
+    /** Input data */
+    input?: unknown;
+    /** Output data (if completed) */
+    output?: unknown;
+    /** Error information (if failed) */
+    error?: {
+        message: string;
+        code: string;
+    };
+    /** When the run started */
+    startedAt?: string;
+    /** When the run ended */
+    endedAt?: string;
+    /** When the run was created */
+    createdAt: string;
+    /** When the run was last updated */
+    updatedAt: string;
+}
+/**
+ * Options for listing runs
+ */
+export interface ListRunsOptions {
+    /** Filter by function ID */
+    functionId?: string;
+    /** Filter by status */
+    status?: RunStatus;
+    /** Maximum number of results */
+    limit?: number;
+    /** Pagination cursor */
+    cursor?: string;
+}
+/**
+ * Result from listing runs
+ */
+export interface ListRunsResult {
+    /** List of runs */
+    runs: Run[];
+    /** Cursor for next page */
+    nextCursor?: string;
+    /** Total count of matching runs */
+    totalCount: number;
+}
+/**
+ * Ironflow client for server-side operations
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from "@ironflow/node";
+ *
+ * const client = createClient({
+ *   serverUrl: "http://localhost:9123",
+ * });
+ *
+ * // Register a function
+ * await client.registerFunction({
+ *   id: "my-function",
+ *   name: "My Function",
+ *   triggers: [{ event: "my.event" }],
+ *   endpointUrl: "http://localhost:3000/api/ironflow",
+ *   preferredMode: "push",
+ * });
+ *
+ * // Emit an event
+ * const result = await client.emit("my.event", { data: "value" });
+ * console.log("Created runs:", result.runIds);
+ * ```
+ */
+export declare class IronflowClient {
+    private readonly serverUrl;
+    private readonly apiKey?;
+    private readonly timeout;
+    constructor(config?: IronflowClientConfig);
+    /**
+     * Register a function with the Ironflow server
+     */
+    registerFunction(request: RegisterFunctionRequest): Promise<RegisterFunctionResult>;
+    /**
+     * Emit an event to trigger workflows
+     *
+     * @example
+     * ```typescript
+     * const result = await client.emit("order.placed", {
+     *   orderId: "123",
+     *   total: 99.99,
+     * });
+     * console.log("Created runs:", result.runIds);
+     * ```
+     */
+    emit(eventName: string, data: unknown, options?: EmitOptions): Promise<EmitResult>;
+    /**
+     * Trigger an event (alias for emit)
+     * @deprecated Use emit() instead
+     */
+    trigger(eventName: string, data: unknown, options?: EmitOptions): Promise<EmitResult>;
+    /**
+     * Get a run by ID
+     */
+    getRun(runId: string): Promise<Run>;
+    /**
+     * List runs with optional filtering
+     */
+    listRuns(options?: ListRunsOptions): Promise<ListRunsResult>;
+    /**
+     * Cancel a running workflow
+     */
+    cancelRun(runId: string, reason?: string): Promise<Run>;
+    /**
+     * Retry a failed run
+     */
+    retryRun(runId: string, fromStep?: string): Promise<Run>;
+    /**
+     * Health check
+     */
+    health(): Promise<string>;
+    /**
+     * Entity stream operations
+     *
+     * @example
+     * ```typescript
+     * // Append an event to a stream
+     * const result = await client.streams.append("order-123", {
+     *   name: "order.created",
+     *   data: { total: 100 },
+     *   entityType: "order",
+     * });
+     *
+     * // Read events from a stream
+     * const { events } = await client.streams.read("order-123", { limit: 10 });
+     *
+     * // Get stream info
+     * const info = await client.streams.getInfo("order-123");
+     * ```
+     */
+    streams: {
+        /**
+         * Append an event to an entity stream
+         */
+        append: (entityId: string, input: AppendEventInput, options?: AppendOptions) => Promise<AppendResult>;
+        /**
+         * Read events from an entity stream
+         */
+        read: (entityId: string, options?: ReadStreamOptions) => Promise<{
+            events: StreamEvent[];
+            totalCount: number;
+        }>;
+        /**
+         * Get information about an entity stream
+         */
+        getInfo: (entityId: string) => Promise<StreamInfo>;
+    };
+    /**
+     * KV store operations
+     *
+     * @example
+     * ```typescript
+     * const kv = client.kv();
+     * const bucket = await kv.createBucket({ name: "sessions", ttlSeconds: 3600 });
+     * const handle = kv.bucket("sessions");
+     * const { revision } = await handle.put("user.123", { token: "abc" });
+     * const entry = await handle.get("user.123");
+     * ```
+     */
+    kv(): KVClient;
+    /**
+     * Config management operations
+     *
+     * @example
+     * ```typescript
+     * const config = client.config();
+     * await config.set("app", { featureX: true });
+     * const { data } = await config.get("app");
+     * await config.patch("app", { maxRetries: 5 });
+     * const configs = await config.list();
+     * await config.delete("app");
+     * ```
+     */
+    config(): ConfigClient;
+    /**
+     * Patch a step's output (hot patching)
+     */
+    patchStep(stepId: string, output: Record<string, unknown>, reason?: string): Promise<void>;
+    /**
+     * Resume a paused or failed run
+     */
+    resumeRun(runId: string, fromStep?: string): Promise<Run>;
+    /**
+     * List registered functions
+     */
+    listFunctions(): Promise<unknown[]>;
+    /**
+     * List connected workers
+     */
+    listWorkers(): Promise<unknown[]>;
+    /**
+     * Make an HTTP request to the server
+     */
+    private request;
+}
+/**
+ * Create a new Ironflow client
+ *
+ * @example
+ * ```typescript
+ * const client = createClient({ serverUrl: "http://localhost:9123" });
+ * ```
+ */
+export declare function createClient(config?: IronflowClientConfig): IronflowClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}