queuebear 0.1.0

package/dist/index.js

@@ -0,0 +1,1313 @@
+// src/api/base.ts
+var BaseClient = class {
+  baseUrl;
+  apiKey;
+  projectId;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.apiKey = options.apiKey;
+    this.projectId = options.projectId;
+  }
+  /**
+   * Build the full URL for a project-scoped endpoint
+   */
+  buildUrl(path, queryParams) {
+    const url = new URL(`${this.baseUrl}/v1/projects/${this.projectId}${path}`);
+    if (queryParams) {
+      for (const [key, value] of Object.entries(queryParams)) {
+        if (value !== void 0) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    return url.toString();
+  }
+  /**
+   * Make an authenticated request
+   */
+  async request(method, path, options) {
+    const url = this.buildUrl(path, options?.queryParams);
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      ...options?.headers
+    };
+    if (options?.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: options?.body !== void 0 ? JSON.stringify(options.body) : void 0
+    });
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({}));
+      throw new QueueBearError(
+        errorData.error || errorData.message || `Request failed with status ${response.status}`,
+        response.status
+      );
+    }
+    return response.json();
+  }
+};
+var QueueBearError = class extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "QueueBearError";
+  }
+};
+
+// src/api/messages.ts
+var MessagesAPI = class extends BaseClient {
+  constructor(options) {
+    super(options);
+  }
+  /**
+   * Publish a message to be delivered to a destination URL
+   *
+   * @param destination - The URL to deliver the message to
+   * @param body - The message body (will be JSON-stringified)
+   * @param options - Optional configuration for delay, retries, callbacks, etc.
+   * @returns The message ID and deduplication status
+   *
+   * @example
+   * ```typescript
+   * const { messageId } = await qb.messages.publish(
+   *   "https://api.example.com/webhook",
+   *   { event: "user.created", userId: "123" },
+   *   { delay: "30s", retries: 5 }
+   * );
+   * ```
+   */
+  async publish(destination, body, options) {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (options?.delay) {
+      headers["queuebear-delay"] = options.delay;
+    }
+    if (options?.retries !== void 0) {
+      headers["queuebear-retries"] = String(options.retries);
+    }
+    if (options?.method) {
+      headers["queuebear-method"] = options.method;
+    }
+    if (options?.callbackUrl) {
+      headers["queuebear-callback"] = options.callbackUrl;
+    }
+    if (options?.failureCallbackUrl) {
+      headers["queuebear-failure-callback"] = options.failureCallbackUrl;
+    }
+    if (options?.deduplicationId) {
+      headers["queuebear-deduplication-id"] = options.deduplicationId;
+    }
+    if (options?.headers) {
+      for (const [key, value] of Object.entries(options.headers)) {
+        headers[`queuebear-forward-${key}`] = value;
+      }
+    }
+    const encodedDestination = encodeURIComponent(destination);
+    return this.request("POST", `/publish/${encodedDestination}`, {
+      body,
+      headers
+    });
+  }
+  /**
+   * Get message details and delivery history
+   *
+   * @param messageId - The message ID (e.g., "msg_abc123...")
+   * @returns Full message details including delivery logs
+   *
+   * @example
+   * ```typescript
+   * const message = await qb.messages.get("msg_abc123");
+   * console.log(message.status); // "completed" | "pending" | "failed"
+   * console.log(message.deliveryLogs); // Delivery attempt history
+   * ```
+   */
+  async get(messageId) {
+    return this.request("GET", `/messages/${messageId}`);
+  }
+  /**
+   * List messages with optional filtering
+   *
+   * @param options - Filter by status and pagination
+   * @returns Paginated list of messages
+   *
+   * @example
+   * ```typescript
+   * const { messages, pagination } = await qb.messages.list({
+   *   status: "pending",
+   *   limit: 20
+   * });
+   * ```
+   */
+  async list(options) {
+    return this.request("GET", "/messages", {
+      queryParams: {
+        status: options?.status,
+        limit: options?.limit,
+        offset: options?.offset
+      }
+    });
+  }
+  /**
+   * Cancel a pending or active message
+   *
+   * @param messageId - The message ID to cancel
+   * @returns Cancellation result
+   *
+   * @example
+   * ```typescript
+   * const result = await qb.messages.cancel("msg_abc123");
+   * console.log(result.cancelled); // true
+   * ```
+   */
+  async cancel(messageId) {
+    return this.request("DELETE", `/messages/${messageId}`);
+  }
+  /**
+   * Publish a message and wait for delivery completion
+   * Polls the message status until it reaches a terminal state
+   *
+   * @param destination - The URL to deliver the message to
+   * @param body - The message body
+   * @param options - Publish options plus polling configuration
+   * @returns The final message status after delivery
+   *
+   * @example
+   * ```typescript
+   * const message = await qb.messages.publishAndWait(
+   *   "https://api.example.com/webhook",
+   *   { event: "user.created" },
+   *   { timeoutMs: 30000 }
+   * );
+   * console.log(message.status); // "completed"
+   * ```
+   */
+  async publishAndWait(destination, body, options) {
+    const { pollIntervalMs = 1e3, timeoutMs = 6e4, ...publishOptions } = options || {};
+    const { messageId } = await this.publish(destination, body, publishOptions);
+    const terminalStates = ["completed", "failed", "cancelled", "dlq"];
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+      const message = await this.get(messageId);
+      if (terminalStates.includes(message.status)) {
+        return message;
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    throw new Error(`Message ${messageId} did not complete within ${timeoutMs}ms`);
+  }
+};
+
+// src/api/schedules.ts
+var SchedulesAPI = class extends BaseClient {
+  constructor(options) {
+    super(options);
+  }
+  /**
+   * Create a cron-based recurring schedule
+   *
+   * @param options - Schedule configuration including destination, cron, and optional settings
+   * @returns The created schedule details
+   *
+   * @example
+   * ```typescript
+   * const schedule = await qb.schedules.create({
+   *   destination: "https://api.example.com/cron-job",
+   *   cron: "0 9 * * *",           // Daily at 9 AM
+   *   timezone: "America/New_York",
+   *   method: "POST",
+   *   body: JSON.stringify({ type: "daily-report" }),
+   *   retries: 3
+   * });
+   * console.log(schedule.scheduleId);
+   * ```
+   *
+   * @example Common cron expressions
+   * - `"* * * * *"` - Every minute
+   * - `"0 * * * *"` - Every hour
+   * - `"0 9 * * *"` - Daily at 9:00 AM
+   * - `"0 9 * * 1-5"` - Weekdays at 9:00 AM
+   * - `"0 0 1 * *"` - First day of each month
+   * - `"0 *​/6 * * *"` - Every 6 hours
+   */
+  async create(options) {
+    return this.request("POST", "/schedules", {
+      body: options
+    });
+  }
+  /**
+   * Get details of a specific schedule
+   *
+   * @param scheduleId - The schedule ID (e.g., "sched_abc123...")
+   * @returns Full schedule details
+   *
+   * @example
+   * ```typescript
+   * const schedule = await qb.schedules.get("sched_abc123");
+   * console.log(schedule.nextExecutionAt);
+   * console.log(schedule.executionCount);
+   * ```
+   */
+  async get(scheduleId) {
+    return this.request("GET", `/schedules/${scheduleId}`);
+  }
+  /**
+   * List all schedules for the current project
+   *
+   * @param options - Pagination options
+   * @returns Paginated list of schedules
+   *
+   * @example
+   * ```typescript
+   * const { schedules, pagination } = await qb.schedules.list({ limit: 20 });
+   * for (const schedule of schedules) {
+   *   console.log(`${schedule.scheduleId}: ${schedule.cron}`);
+   * }
+   * ```
+   */
+  async list(options) {
+    return this.request("GET", "/schedules", {
+      queryParams: {
+        limit: options?.limit,
+        offset: options?.offset
+      }
+    });
+  }
+  /**
+   * Delete (soft-delete) a schedule
+   *
+   * @param scheduleId - The schedule ID to delete
+   * @returns Deletion confirmation
+   *
+   * @example
+   * ```typescript
+   * const result = await qb.schedules.delete("sched_abc123");
+   * console.log(result.deleted); // true
+   * ```
+   */
+  async delete(scheduleId) {
+    return this.request("DELETE", `/schedules/${scheduleId}`);
+  }
+  /**
+   * Pause a schedule to temporarily stop executions
+   *
+   * @param scheduleId - The schedule ID to pause
+   * @returns Pause confirmation
+   *
+   * @example
+   * ```typescript
+   * await qb.schedules.pause("sched_abc123");
+   * // Schedule will not execute until resumed
+   * ```
+   */
+  async pause(scheduleId) {
+    return this.request("PATCH", `/schedules/${scheduleId}/pause`);
+  }
+  /**
+   * Resume a paused schedule
+   *
+   * @param scheduleId - The schedule ID to resume
+   * @returns Resume confirmation with next execution time
+   *
+   * @example
+   * ```typescript
+   * const result = await qb.schedules.resume("sched_abc123");
+   * console.log(result.nextExecutionAt); // Next scheduled run
+   * ```
+   */
+  async resume(scheduleId) {
+    return this.request("PATCH", `/schedules/${scheduleId}/resume`);
+  }
+};
+
+// src/api/dlq.ts
+var DLQAPI = class extends BaseClient {
+  constructor(options) {
+    super(options);
+  }
+  /**
+   * List all DLQ entries for the current project
+   *
+   * @param options - Pagination options
+   * @returns Paginated list of DLQ entries
+   *
+   * @example
+   * ```typescript
+   * const { entries, pagination } = await qb.dlq.list({ limit: 20 });
+   * for (const entry of entries) {
+   *   console.log(`${entry.id}: ${entry.failureReason}`);
+   * }
+   * ```
+   */
+  async list(options) {
+    return this.request("GET", "/dlq", {
+      queryParams: {
+        limit: options?.limit,
+        offset: options?.offset
+      }
+    });
+  }
+  /**
+   * Get details of a specific DLQ entry
+   *
+   * @param dlqId - The DLQ entry UUID
+   * @returns Full DLQ entry details including original message data
+   *
+   * @example
+   * ```typescript
+   * const entry = await qb.dlq.get("uuid-123...");
+   * console.log(entry.failureReason);
+   * console.log(entry.totalAttempts);
+   * console.log(entry.body); // Original message body
+   * ```
+   */
+  async get(dlqId) {
+    return this.request("GET", `/dlq/${dlqId}`);
+  }
+  /**
+   * Retry a DLQ entry by creating a new message
+   *
+   * Creates a new message from the failed DLQ entry for redelivery.
+   * The DLQ entry is marked as recovered and linked to the new message.
+   *
+   * @param dlqId - The DLQ entry UUID to retry
+   * @returns The new message ID and recovery confirmation
+   * @throws Error if the entry was already recovered
+   *
+   * @example
+   * ```typescript
+   * const result = await qb.dlq.retry("uuid-123...");
+   * console.log(result.newMessageId); // New message created
+   * console.log(result.recovered); // true
+   * ```
+   */
+  async retry(dlqId) {
+    return this.request("POST", `/dlq/${dlqId}/retry`);
+  }
+  /**
+   * Delete a DLQ entry permanently without retry
+   *
+   * @param dlqId - The DLQ entry UUID to delete
+   * @returns Deletion confirmation
+   *
+   * @example
+   * ```typescript
+   * await qb.dlq.delete("uuid-123...");
+   * ```
+   */
+  async delete(dlqId) {
+    return this.request("DELETE", `/dlq/${dlqId}`);
+  }
+  /**
+   * Purge all DLQ entries for the current project
+   *
+   * Permanently deletes all DLQ entries without retry.
+   * Use with caution as this action cannot be undone.
+   *
+   * @returns The number of entries purged
+   *
+   * @example
+   * ```typescript
+   * const result = await qb.dlq.purge();
+   * console.log(`Purged ${result.count} entries`);
+   * ```
+   */
+  async purge() {
+    return this.request("POST", "/dlq/purge");
+  }
+  /**
+   * Retry all DLQ entries for the current project
+   *
+   * Creates new messages from all failed DLQ entries.
+   *
+   * @returns Array of retry results
+   *
+   * @example
+   * ```typescript
+   * const results = await qb.dlq.retryAll();
+   * console.log(`Retried ${results.length} entries`);
+   * ```
+   */
+  async retryAll() {
+    const results = [];
+    let hasMore = true;
+    let offset = 0;
+    const limit = 100;
+    while (hasMore) {
+      const { entries, pagination } = await this.list({ limit, offset });
+      for (const entry of entries) {
+        try {
+          const result = await this.retry(entry.id);
+          results.push(result);
+        } catch {
+        }
+      }
+      hasMore = pagination.hasMore;
+      offset += limit;
+    }
+    return results;
+  }
+};
+
+// src/api/workflows.ts
+var WorkflowsAPI = class extends BaseClient {
+  constructor(options) {
+    super(options);
+  }
+  /**
+   * Trigger a new workflow run
+   *
+   * @param workflowId - Unique identifier for this workflow type
+   * @param workflowUrl - URL of the workflow endpoint
+   * @param input - Input data for the workflow
+   * @param options - Optional settings (idempotencyKey, maxDuration, metadata)
+   * @returns The run ID
+   *
+   * @example
+   * ```typescript
+   * const { runId } = await qb.workflows.trigger(
+   *   "user-onboarding",
+   *   "https://your-app.com/api/workflows/onboarding",
+   *   { userId: "123", email: "user@example.com" },
+   *   { idempotencyKey: "onboarding-user-123" }
+   * );
+   * ```
+   */
+  async trigger(workflowId, workflowUrl, input, options) {
+    return this.request("POST", `/workflows/${workflowId}/trigger`, {
+      body: {
+        workflowUrl,
+        input,
+        idempotencyKey: options?.idempotencyKey,
+        maxDuration: options?.maxDuration,
+        metadata: options?.metadata
+      }
+    });
+  }
+  /**
+   * Get workflow run status with all steps
+   *
+   * @param runId - The workflow run ID
+   * @returns Full run details including steps
+   *
+   * @example
+   * ```typescript
+   * const status = await qb.workflows.getStatus(runId);
+   * console.log(status.status); // "running" | "sleeping" | "completed"
+   * console.log(status.steps); // Array of step details
+   * ```
+   */
+  async getStatus(runId) {
+    return this.request("GET", `/workflows/runs/${runId}`);
+  }
+  /**
+   * Cancel a running workflow
+   *
+   * @param runId - The workflow run ID to cancel
+   *
+   * @example
+   * ```typescript
+   * await qb.workflows.cancel(runId);
+   * ```
+   */
+  async cancel(runId) {
+    await this.request("DELETE", `/workflows/runs/${runId}`);
+  }
+  /**
+   * Retry a failed or timed out workflow
+   * Resumes from the last completed step
+   *
+   * @param runId - The workflow run ID to retry
+   * @returns The new run ID if a new run was created
+   *
+   * @example
+   * ```typescript
+   * const result = await qb.workflows.retry(runId);
+   * console.log(result.runId);
+   * console.log(result.resumed); // true
+   * ```
+   */
+  async retry(runId) {
+    return this.request(
+      "POST",
+      `/workflows/runs/${runId}/retry`
+    );
+  }
+  /**
+   * List runs for a specific workflow
+   *
+   * @param workflowId - The workflow type identifier
+   * @param options - Filter by status and pagination
+   * @returns Paginated list of workflow runs
+   *
+   * @example
+   * ```typescript
+   * const { runs, pagination } = await qb.workflows.listRuns("user-onboarding", {
+   *   status: "completed",
+   *   limit: 20
+   * });
+   * ```
+   */
+  async listRuns(workflowId, options) {
+    return this.request("GET", `/workflows/${workflowId}/runs`, {
+      queryParams: {
+        status: options?.status,
+        limit: options?.limit,
+        offset: options?.offset
+      }
+    });
+  }
+  /**
+   * Send an event to workflows waiting with waitForEvent()
+   *
+   * @param eventName - Name of the event to send
+   * @param options - Optional event key and payload
+   * @returns The number of workflows that received the event
+   *
+   * @example
+   * ```typescript
+   * const result = await qb.workflows.sendEvent("order.approved", {
+   *   eventKey: "order-123",
+   *   payload: { status: "approved" }
+   * });
+   * console.log(`Notified ${result.matchedRuns} workflows`);
+   * ```
+   */
+  async sendEvent(eventName, options) {
+    return this.request(
+      "POST",
+      `/workflows/events/${encodeURIComponent(eventName)}`,
+      {
+        body: {
+          eventKey: options?.eventKey,
+          payload: options?.payload
+        }
+      }
+    );
+  }
+  /**
+   * Wait for a workflow to complete
+   * Polls the status until the workflow reaches a terminal state
+   *
+   * @param runId - The workflow run ID
+   * @param options - Polling options
+   * @returns The final workflow status
+   *
+   * @example
+   * ```typescript
+   * const result = await qb.workflows.waitForCompletion(runId, {
+   *   pollIntervalMs: 2000,
+   *   timeoutMs: 60000
+   * });
+   * console.log(result.status); // "completed" | "failed" | "cancelled"
+   * ```
+   */
+  async waitForCompletion(runId, options) {
+    const pollInterval = options?.pollIntervalMs || 1e3;
+    const timeout = options?.timeoutMs || 3e5;
+    const startTime = Date.now();
+    const terminalStates = [
+      "completed",
+      "failed",
+      "cancelled",
+      "timed_out"
+    ];
+    while (Date.now() - startTime < timeout) {
+      const status = await this.getStatus(runId);
+      if (terminalStates.includes(status.status)) {
+        return status;
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+    throw new Error(`Workflow did not complete within ${timeout}ms`);
+  }
+  /**
+   * Trigger a workflow and wait for completion
+   *
+   * @param workflowId - Unique identifier for this workflow type
+   * @param workflowUrl - URL of the workflow endpoint
+   * @param input - Input data for the workflow
+   * @param options - Trigger and polling options
+   * @returns The final workflow status
+   *
+   * @example
+   * ```typescript
+   * const result = await qb.workflows.triggerAndWait(
+   *   "user-onboarding",
+   *   "https://your-app.com/api/workflows/onboarding",
+   *   { userId: "123" },
+   *   { timeoutMs: 120000 }
+   * );
+   * console.log(result.result); // Workflow output
+   * ```
+   */
+  async triggerAndWait(workflowId, workflowUrl, input, options) {
+    const { pollIntervalMs, timeoutMs, ...triggerOptions } = options || {};
+    const { runId } = await this.trigger(workflowId, workflowUrl, input, triggerOptions);
+    return this.waitForCompletion(runId, { pollIntervalMs, timeoutMs });
+  }
+};
+
+// src/queuebear.ts
+var QueueBear = class {
+  options;
+  /**
+   * Messages API for publishing and managing webhook messages
+   *
+   * @example
+   * ```typescript
+   * // Publish a message
+   * const { messageId } = await qb.messages.publish(
+   *   "https://api.example.com/webhook",
+   *   { event: "user.created", userId: "123" },
+   *   { delay: "30s", retries: 5 }
+   * );
+   *
+   * // Get message status
+   * const message = await qb.messages.get(messageId);
+   *
+   * // List messages
+   * const { messages } = await qb.messages.list({ status: "pending" });
+   *
+   * // Cancel a message
+   * await qb.messages.cancel(messageId);
+   * ```
+   */
+  messages;
+  /**
+   * Schedules API for managing cron-based recurring jobs
+   *
+   * @example
+   * ```typescript
+   * // Create a schedule
+   * const schedule = await qb.schedules.create({
+   *   destination: "https://api.example.com/cron-job",
+   *   cron: "0 9 * * *",           // Daily at 9 AM
+   *   timezone: "America/New_York",
+   * });
+   *
+   * // Pause a schedule
+   * await qb.schedules.pause(schedule.scheduleId);
+   *
+   * // Resume a schedule
+   * await qb.schedules.resume(schedule.scheduleId);
+   *
+   * // Delete a schedule
+   * await qb.schedules.delete(schedule.scheduleId);
+   * ```
+   */
+  schedules;
+  /**
+   * DLQ API for managing failed messages in the dead letter queue
+   *
+   * @example
+   * ```typescript
+   * // List failed messages
+   * const { entries } = await qb.dlq.list();
+   *
+   * // Retry a failed message
+   * const result = await qb.dlq.retry(entries[0].id);
+   *
+   * // Delete a DLQ entry
+   * await qb.dlq.delete(entries[0].id);
+   *
+   * // Purge all DLQ entries
+   * await qb.dlq.purge();
+   * ```
+   */
+  dlq;
+  /**
+   * Workflows API for triggering and managing durable workflows
+   *
+   * @example
+   * ```typescript
+   * // Trigger a workflow
+   * const { runId } = await qb.workflows.trigger(
+   *   "user-onboarding",
+   *   "https://your-app.com/api/workflows/onboarding",
+   *   { userId: "123", email: "user@example.com" },
+   *   { idempotencyKey: "onboarding-user-123" }
+   * );
+   *
+   * // Check status
+   * const status = await qb.workflows.getStatus(runId);
+   *
+   * // Wait for completion
+   * const result = await qb.workflows.waitForCompletion(runId);
+   *
+   * // Send event to waiting workflows
+   * await qb.workflows.sendEvent("order.approved", {
+   *   eventKey: "order-123",
+   *   payload: { status: "approved" }
+   * });
+   * ```
+   */
+  workflows;
+  constructor(options) {
+    this.options = {
+      baseUrl: options.baseUrl.replace(/\/$/, ""),
+      apiKey: options.apiKey,
+      projectId: options.projectId
+    };
+    this.messages = new MessagesAPI(this.options);
+    this.schedules = new SchedulesAPI(this.options);
+    this.dlq = new DLQAPI(this.options);
+    this.workflows = new WorkflowsAPI(this.options);
+  }
+  /**
+   * Publish a message and wait for delivery completion
+   *
+   * Convenience method that combines publish + polling in one call.
+   *
+   * @param destination - The URL to deliver the message to
+   * @param body - The message body
+   * @param options - Publish options plus polling configuration
+   * @returns The final message status after delivery
+   *
+   * @example
+   * ```typescript
+   * const message = await qb.publishAndWait(
+   *   "https://api.example.com/webhook",
+   *   { event: "user.created" },
+   *   { timeoutMs: 30000 }
+   * );
+   * console.log(message.status); // "completed"
+   * ```
+   */
+  async publishAndWait(destination, body, options) {
+    return this.messages.publishAndWait(destination, body, options);
+  }
+  /**
+   * Trigger a workflow and wait for completion
+   *
+   * Convenience method that combines trigger + polling in one call.
+   *
+   * @param workflowId - Unique identifier for this workflow type
+   * @param workflowUrl - URL of the workflow endpoint
+   * @param input - Input data for the workflow
+   * @param options - Trigger and polling options
+   * @returns The final workflow status
+   *
+   * @example
+   * ```typescript
+   * const result = await qb.triggerAndWait(
+   *   "user-onboarding",
+   *   "https://your-app.com/api/workflows/onboarding",
+   *   { userId: "123" },
+   *   { timeoutMs: 120000 }
+   * );
+   * console.log(result.result); // Workflow output
+   * ```
+   */
+  async triggerAndWait(workflowId, workflowUrl, input, options) {
+    return this.workflows.triggerAndWait(workflowId, workflowUrl, input, options);
+  }
+};
+
+// src/context.ts
+var WorkflowPausedError = class extends Error {
+  constructor(reason) {
+    super(reason);
+    this.reason = reason;
+    this.name = "WorkflowPausedError";
+  }
+};
+var WorkflowContext = class {
+  runId;
+  input;
+  runToken;
+  baseUrl;
+  authHeader;
+  stepIndex = 0;
+  constructor(options) {
+    this.runId = options.runId;
+    this.runToken = options.runToken;
+    this.input = options.input;
+    this.baseUrl = options.baseUrl;
+    this.authHeader = options.authHeader;
+  }
+  /**
+   * Execute a step with caching
+   * Step names must be unique within a workflow run
+   * @param stepName - Unique name for this step
+   * @param fn - Function to execute
+   * @param options - Optional retry configuration
+   */
+  async run(stepName, fn, options) {
+    const checkResponse = await fetch(
+      `${this.baseUrl}/v1/workflows/internal/step/check`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: this.authHeader,
+          "X-QueueBear-Run-Token": this.runToken
+        },
+        body: JSON.stringify({
+          runId: this.runId,
+          stepName
+        })
+      }
+    );
+    const checkData = await checkResponse.json();
+    if (checkData.cached) {
+      this.stepIndex++;
+      return checkData.result;
+    }
+    const startResponse = await fetch(
+      `${this.baseUrl}/v1/workflows/internal/step/start`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: this.authHeader,
+          "X-QueueBear-Run-Token": this.runToken
+        },
+        body: JSON.stringify({
+          runId: this.runId,
+          stepName,
+          stepIndex: this.stepIndex,
+          stepType: "run",
+          retryOptions: options
+        })
+      }
+    );
+    if (!startResponse.ok) {
+      const errorData = await startResponse.json();
+      throw new Error(errorData.error || "Failed to start step");
+    }
+    try {
+      const result = await fn();
+      await fetch(`${this.baseUrl}/v1/workflows/internal/step/complete`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: this.authHeader,
+          "X-QueueBear-Run-Token": this.runToken
+        },
+        body: JSON.stringify({
+          runId: this.runId,
+          stepName,
+          result
+        })
+      });
+      this.stepIndex++;
+      return result;
+    } catch (error) {
+      await fetch(`${this.baseUrl}/v1/workflows/internal/step/fail`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: this.authHeader,
+          "X-QueueBear-Run-Token": this.runToken
+        },
+        body: JSON.stringify({
+          runId: this.runId,
+          stepName,
+          error: error instanceof Error ? error.message : String(error)
+        })
+      });
+      throw error;
+    }
+  }
+  /**
+   * Sleep for specified seconds
+   * Step names must be unique within a workflow run
+   */
+  async sleep(stepName, seconds) {
+    const checkResponse = await fetch(
+      `${this.baseUrl}/v1/workflows/internal/step/check`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: this.authHeader,
+          "X-QueueBear-Run-Token": this.runToken
+        },
+        body: JSON.stringify({
+          runId: this.runId,
+          stepName
+        })
+      }
+    );
+    const checkData = await checkResponse.json();
+    if (checkData.cached) {
+      this.stepIndex++;
+      return;
+    }
+    const sleepResponse = await fetch(
+      `${this.baseUrl}/v1/workflows/internal/sleep`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: this.authHeader,
+          "X-QueueBear-Run-Token": this.runToken
+        },
+        body: JSON.stringify({
+          runId: this.runId,
+          stepName,
+          stepIndex: this.stepIndex,
+          seconds
+        })
+      }
+    );
+    if (!sleepResponse.ok) {
+      const errorData = await sleepResponse.json();
+      throw new Error(errorData.error || "Failed to schedule sleep");
+    }
+    throw new WorkflowPausedError(`Sleeping for ${seconds}s`);
+  }
+  /**
+   * Sleep until specific date
+   */
+  async sleepUntil(stepName, until) {
+    const seconds = Math.max(
+      0,
+      Math.ceil((until.getTime() - Date.now()) / 1e3)
+    );
+    return this.sleep(stepName, seconds);
+  }
+  /**
+   * Get all completed steps for the current run
+   * Useful for inspecting progress or debugging
+   */
+  async getCompletedSteps() {
+    const response = await fetch(
+      `${this.baseUrl}/v1/workflows/internal/steps/${this.runId}`,
+      {
+        headers: {
+          Authorization: this.authHeader,
+          "X-QueueBear-Run-Token": this.runToken
+        }
+      }
+    );
+    if (!response.ok) {
+      throw new Error("Failed to fetch completed steps");
+    }
+    const data = await response.json();
+    return data.steps;
+  }
+  /**
+   * Make HTTP call (executed as a step)
+   */
+  async call(stepName, config) {
+    return this.run(stepName, async () => {
+      const response = await fetch(config.url, {
+        method: config.method || "GET",
+        headers: {
+          "Content-Type": "application/json",
+          ...config.headers
+        },
+        body: config.body ? JSON.stringify(config.body) : void 0
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      const contentType = response.headers.get("content-type");
+      if (contentType?.includes("application/json")) {
+        return response.json();
+      }
+      return response.text();
+    });
+  }
+  /**
+   * Wait for an external event
+   * @param stepName - Unique step name
+   * @param eventName - Name of the event to wait for
+   * @param options - Optional event key and timeout
+   */
+  async waitForEvent(stepName, eventName, options) {
+    const checkResponse = await fetch(
+      `${this.baseUrl}/v1/workflows/internal/event/check`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: this.authHeader,
+          "X-QueueBear-Run-Token": this.runToken
+        },
+        body: JSON.stringify({
+          runId: this.runId,
+          stepName
+        })
+      }
+    );
+    const checkData = await checkResponse.json();
+    if (checkData.received) {
+      this.stepIndex++;
+      return checkData.payload;
+    }
+    if (checkData.expired) {
+      throw new Error(`Event "${eventName}" timed out`);
+    }
+    const waitResponse = await fetch(
+      `${this.baseUrl}/v1/workflows/internal/event/wait`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: this.authHeader,
+          "X-QueueBear-Run-Token": this.runToken
+        },
+        body: JSON.stringify({
+          runId: this.runId,
+          stepName,
+          stepIndex: this.stepIndex,
+          eventName,
+          eventKey: options?.eventKey,
+          timeoutSeconds: options?.timeoutSeconds
+        })
+      }
+    );
+    if (!waitResponse.ok) {
+      const errorData = await waitResponse.json();
+      throw new Error(errorData.error || "Failed to register event wait");
+    }
+    throw new WorkflowPausedError(`Waiting for event: ${eventName}`);
+  }
+  /**
+   * Send a fire-and-forget notification event
+   * @param eventName - Name of the event to send
+   * @param payload - Optional payload to include
+   */
+  async notify(eventName, payload) {
+    const response = await fetch(
+      `${this.baseUrl}/v1/workflows/events/${encodeURIComponent(eventName)}`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: this.authHeader
+        },
+        body: JSON.stringify({ payload })
+      }
+    );
+    if (!response.ok) {
+      const errorData = await response.json();
+      throw new Error(errorData.error || `Failed to send event: ${eventName}`);
+    }
+  }
+  /**
+   * Execute multiple steps in parallel
+   * @param steps - Array of step definitions with name and function
+   */
+  async parallel(steps) {
+    const stepNames = steps.map((s) => s.name);
+    const batchResponse = await fetch(
+      `${this.baseUrl}/v1/workflows/internal/steps/batch-check`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: this.authHeader,
+          "X-QueueBear-Run-Token": this.runToken
+        },
+        body: JSON.stringify({
+          runId: this.runId,
+          stepNames
+        })
+      }
+    );
+    if (!batchResponse.ok) {
+      throw new Error("Failed to batch check steps");
+    }
+    const batchData = await batchResponse.json();
+    const results = new Array(steps.length);
+    const pendingPromises = [];
+    const errors = [];
+    for (let i = 0; i < steps.length; i++) {
+      const step = steps[i];
+      const cached = batchData.steps[step.name];
+      if (cached?.cached) {
+        results[i] = cached.result;
+      } else {
+        pendingPromises.push(
+          this.run(step.name, step.fn).then((result) => {
+            results[i] = result;
+          }).catch((error) => {
+            errors.push({
+              index: i,
+              stepName: step.name,
+              error: error instanceof Error ? error : new Error(String(error))
+            });
+          })
+        );
+      }
+    }
+    await Promise.all(pendingPromises);
+    if (errors.length > 0) {
+      const errorMessages = errors.map((e) => `Step "${e.stepName}": ${e.error.message}`).join("; ");
+      throw new ParallelExecutionError(
+        `${errors.length} of ${steps.length} parallel steps failed: ${errorMessages}`,
+        errors
+      );
+    }
+    return results;
+  }
+};
+var ParallelExecutionError = class extends Error {
+  constructor(message, errors) {
+    super(message);
+    this.errors = errors;
+    this.name = "ParallelExecutionError";
+  }
+  get failedStepCount() {
+    return this.errors.length;
+  }
+};
+
+// src/serve.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function serve(handler, options) {
+  return async (request) => {
+    let runId;
+    let runToken;
+    let baseUrl;
+    try {
+      if (options?.signingSecret) {
+        const signature = request.headers.get("X-QueueBear-Signature");
+        const bodyText = await request.clone().text();
+        if (!verifySignature(bodyText, signature, options.signingSecret)) {
+          return new Response(JSON.stringify({ error: "Invalid signature" }), {
+            status: 401,
+            headers: { "Content-Type": "application/json" }
+          });
+        }
+      }
+      const body = await request.json();
+      runId = body.runId || request.headers.get("X-QueueBear-Workflow-Run") || "";
+      runToken = request.headers.get("X-QueueBear-Run-Token") || "";
+      if (!runId) {
+        return new Response(JSON.stringify({ error: "Missing runId" }), {
+          status: 400,
+          headers: { "Content-Type": "application/json" }
+        });
+      }
+      baseUrl = options?.baseUrl || getBaseUrl(request);
+      const runResponse = await fetch(
+        `${baseUrl}/v1/workflows/runs/${runId}`,
+        {
+          headers: {
+            Authorization: request.headers.get("Authorization") || ""
+          }
+        }
+      );
+      if (!runResponse.ok) {
+        return new Response(
+          JSON.stringify({ error: "Failed to fetch workflow run" }),
+          {
+            status: 500,
+            headers: { "Content-Type": "application/json" }
+          }
+        );
+      }
+      const runData = await runResponse.json();
+      const context = new WorkflowContext({
+        runId,
+        runToken,
+        input: runData.input,
+        baseUrl,
+        authHeader: request.headers.get("Authorization") || ""
+      });
+      const result = await handler(context);
+      await fetch(`${baseUrl}/v1/workflows/internal/complete`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: request.headers.get("Authorization") || "",
+          "X-QueueBear-Run-Token": runToken
+        },
+        body: JSON.stringify({ runId, result })
+      });
+      return new Response(JSON.stringify({ completed: true, result }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" }
+      });
+    } catch (error) {
+      if (error instanceof WorkflowPausedError) {
+        return new Response(
+          JSON.stringify({
+            completed: false,
+            paused: true,
+            reason: error.reason
+          }),
+          {
+            status: 200,
+            headers: { "Content-Type": "application/json" }
+          }
+        );
+      }
+      console.error("[Workflow] Unhandled error - failing run:", error);
+      if (runId && runToken && baseUrl) {
+        try {
+          await fetch(`${baseUrl}/v1/workflows/internal/fail`, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: request.headers.get("Authorization") || "",
+              "X-QueueBear-Run-Token": runToken
+            },
+            body: JSON.stringify({
+              runId,
+              error: error instanceof Error ? error.message : String(error)
+            })
+          });
+        } catch (failError) {
+          console.error("[Workflow] Failed to mark run as failed:", failError);
+        }
+      }
+      return new Response(
+        JSON.stringify({
+          error: error instanceof Error ? error.message : "Unknown error",
+          failed: true
+        }),
+        {
+          status: 500,
+          headers: { "Content-Type": "application/json" }
+        }
+      );
+    }
+  };
+}
+function verifySignature(body, signature, secret) {
+  if (!signature) return false;
+  const parts = signature.split(",").reduce(
+    (acc, part) => {
+      const [key, value] = part.split("=");
+      acc[key] = value;
+      return acc;
+    },
+    {}
+  );
+  if (!parts.t || !parts.v1) return false;
+  const timestamp = parseInt(parts.t, 10);
+  const now = Math.floor(Date.now() / 1e3);
+  if (Math.abs(now - timestamp) > 300) return false;
+  const payload = `${parts.t}.${body}`;
+  const expected = createHmac("sha256", secret).update(payload).digest("hex");
+  try {
+    return timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
+  } catch {
+    return false;
+  }
+}
+function getBaseUrl(request) {
+  const url = new URL(request.url);
+  return `${url.protocol}//${url.host}`;
+}
+export {
+  DLQAPI,
+  MessagesAPI,
+  ParallelExecutionError,
+  QueueBear,
+  QueueBearError,
+  SchedulesAPI,
+  WorkflowContext,
+  WorkflowPausedError,
+  WorkflowsAPI,
+  serve
+};