queuebear 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1209 @@
+/**
+ * Base HTTP client for QueueBear API requests
+ */
+interface BaseClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    projectId: string;
+}
+/**
+ * HTTP methods supported by the API
+ */
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * Base client providing shared HTTP functionality
+ */
+declare class BaseClient {
+    protected baseUrl: string;
+    protected apiKey: string;
+    protected projectId: string;
+    constructor(options: BaseClientOptions);
+    /**
+     * Build the full URL for a project-scoped endpoint
+     */
+    protected buildUrl(path: string, queryParams?: Record<string, string | number | undefined>): string;
+    /**
+     * Make an authenticated request
+     */
+    protected request<T>(method: HttpMethod, path: string, options?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+        queryParams?: Record<string, string | number | undefined>;
+    }): Promise<T>;
+}
+/**
+ * Custom error class for QueueBear API errors
+ */
+declare class QueueBearError extends Error {
+    statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+
+/**
+ * Workflow run status types
+ */
+type WorkflowRunStatus = "pending" | "running" | "sleeping" | "waiting_event" | "completed" | "failed" | "cancelled" | "timed_out";
+/**
+ * Step types
+ */
+type StepType = "run" | "sleep" | "call" | "continuation" | "wait_event";
+/**
+ * Workflow run information returned by client.getStatus()
+ */
+interface WorkflowRun {
+    runId: string;
+    workflowId: string;
+    workflowUrl: string;
+    status: WorkflowRunStatus;
+    input: unknown;
+    result?: unknown;
+    currentStepIndex: number;
+    completedSteps: number;
+    lastError?: string;
+    errorCount: number;
+    createdAt: string;
+    startedAt?: string;
+    completedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Step information within a workflow run
+ */
+interface WorkflowStep {
+    stepName: string;
+    stepIndex: number;
+    stepType: StepType;
+    status: "pending" | "completed" | "failed";
+    result?: unknown;
+    error?: string;
+    createdAt: string;
+    completedAt?: string;
+}
+/**
+ * Response from client.trigger()
+ */
+interface TriggerResponse {
+    runId: string;
+}
+/**
+ * Response from client.getStatus() - includes run details and steps
+ */
+interface StatusResponse extends WorkflowRun {
+    steps: WorkflowStep[];
+}
+/**
+ * Options for triggering a workflow
+ */
+interface TriggerOptions {
+    idempotencyKey?: string;
+    maxDuration?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for step-level retry configuration
+ */
+interface StepRetryOptions {
+    retries?: number;
+    backoff?: {
+        type: "exponential" | "fixed";
+        delay: number;
+    };
+}
+/**
+ * Options for serve() function
+ */
+interface ServeOptions {
+    baseUrl?: string;
+    retries?: number;
+    signingSecret?: string;
+}
+/**
+ * Completed step info returned by context.getCompletedSteps()
+ */
+interface CompletedStep {
+    stepName: string;
+    stepIndex: number;
+    stepType: StepType;
+    result: unknown;
+    completedAt: string;
+}
+/**
+ * HTTP call configuration for context.call()
+ */
+interface CallConfig {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+/**
+ * Options for listing workflow runs
+ */
+interface ListRunsOptions {
+    status?: WorkflowRunStatus;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Pagination info in list responses
+ */
+interface Pagination {
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+/**
+ * Response from client.listRuns()
+ */
+interface ListRunsResponse {
+    runs: WorkflowRun[];
+    pagination: Pagination;
+}
+/**
+ * Options for context.waitForEvent()
+ */
+interface WaitForEventOptions {
+    eventKey?: string;
+    timeoutSeconds?: number;
+}
+/**
+ * Definition for a parallel step
+ */
+interface ParallelStepDefinition<T> {
+    name: string;
+    fn: () => Promise<T>;
+}
+/**
+ * Options for client.sendEvent()
+ */
+interface SendEventOptions {
+    eventKey?: string;
+    payload?: unknown;
+}
+/**
+ * Response from client.sendEvent()
+ */
+interface SendEventResponse {
+    eventName: string;
+    eventKey?: string;
+    matchedRuns: number;
+}
+/**
+ * HTTP methods for message delivery
+ */
+type MessageMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * Message status values
+ */
+type MessageStatus = "pending" | "active" | "completed" | "failed" | "cancelled" | "dlq";
+/**
+ * Options for publishing a message
+ */
+interface PublishOptions {
+    /** Delay before delivery. Format: "{value}{unit}" where unit is s/m/h/d (e.g., "30s", "5m", "2h", "1d") */
+    delay?: string;
+    /** Number of retry attempts (1-5, default: 3) */
+    retries?: number;
+    /** HTTP method for delivery (default: POST) */
+    method?: MessageMethod;
+    /** Headers to forward to the destination */
+    headers?: Record<string, string>;
+    /** URL to call after successful delivery */
+    callbackUrl?: string;
+    /** URL to call after all retries exhausted */
+    failureCallbackUrl?: string;
+    /** Unique ID for message deduplication (max 128 chars) */
+    deduplicationId?: string;
+}
+/**
+ * Response from publishing a message
+ */
+interface PublishResponse {
+    messageId: string;
+    /** True if this message was deduplicated */
+    deduplicated?: boolean;
+}
+/**
+ * Delivery log entry for a message
+ */
+interface DeliveryLog {
+    id: string;
+    responseStatus: number | null;
+    success: boolean;
+    errorMessage: string | null;
+    durationMs: number | null;
+    attemptNumber: number;
+    createdAt: string;
+}
+/**
+ * Last response from message delivery
+ */
+interface LastResponse {
+    statusCode: number;
+    body: string;
+    headers?: Record<string, string>;
+    duration: number;
+}
+/**
+ * Message details returned by messages.get()
+ */
+interface Message {
+    messageId: string;
+    destination: string;
+    method: MessageMethod;
+    body: string | null;
+    headers: Record<string, string>;
+    status: MessageStatus;
+    retries: number;
+    retryCount: number;
+    delay: number | null;
+    scheduledFor: string | null;
+    createdAt: string;
+    processedAt: string | null;
+    completedAt: string | null;
+    lastResponse: LastResponse | null;
+    lastError: string | null;
+    deliveryLogs: DeliveryLog[];
+}
+/**
+ * Message summary in list responses
+ */
+interface MessageSummary {
+    messageId: string;
+    destination: string;
+    status: MessageStatus;
+    retries: number;
+    retryCount: number;
+    createdAt: string;
+    completedAt: string | null;
+}
+/**
+ * Options for listing messages
+ */
+interface ListMessagesOptions {
+    status?: MessageStatus;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Response from messages.list()
+ */
+interface ListMessagesResponse {
+    messages: MessageSummary[];
+    pagination: Pagination;
+}
+/**
+ * Response from messages.cancel()
+ */
+interface CancelMessageResponse {
+    messageId: string;
+    cancelled: boolean;
+    previousStatus: MessageStatus;
+    bullmqCancelled: boolean;
+}
+/**
+ * Options for creating a schedule
+ */
+interface CreateScheduleOptions {
+    /** URL to call on each execution */
+    destination: string;
+    /** Cron expression (e.g., "0 9 * * *" for 9 AM daily) */
+    cron: string;
+    /** IANA timezone (default: "UTC") */
+    timezone?: string;
+    /** HTTP method (default: POST) */
+    method?: MessageMethod;
+    /** Request body to send */
+    body?: string;
+    /** Headers to include in request */
+    headers?: Record<string, string>;
+    /** Retry attempts per execution (0-5, default: 3) */
+    retries?: number;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Schedule details
+ */
+interface Schedule {
+    scheduleId: string;
+    destination: string;
+    cron: string;
+    timezone: string;
+    method: MessageMethod;
+    body: string | null;
+    headers: Record<string, string>;
+    retries: number;
+    isActive: boolean;
+    isPaused: boolean;
+    lastExecutedAt: string | null;
+    nextExecutionAt: string | null;
+    executionCount: number;
+    failureCount: number;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string | null;
+}
+/**
+ * Schedule summary in list responses
+ */
+interface ScheduleSummary {
+    scheduleId: string;
+    destination: string;
+    cron: string;
+    timezone: string;
+    method: MessageMethod;
+    retries: number;
+    isActive: boolean;
+    isPaused: boolean;
+    lastExecutedAt: string | null;
+    nextExecutionAt: string | null;
+    executionCount: number;
+    failureCount: number;
+    createdAt: string;
+}
+/**
+ * Options for listing schedules
+ */
+interface ListSchedulesOptions {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Response from schedules.list()
+ */
+interface ListSchedulesResponse {
+    schedules: ScheduleSummary[];
+    pagination: Pagination;
+}
+/**
+ * Response from schedules.create()
+ */
+interface CreateScheduleResponse extends Schedule {
+}
+/**
+ * Response from schedules.delete()
+ */
+interface DeleteScheduleResponse {
+    scheduleId: string;
+    deleted: boolean;
+}
+/**
+ * Response from schedules.pause()
+ */
+interface PauseScheduleResponse {
+    scheduleId: string;
+    isPaused: true;
+}
+/**
+ * Response from schedules.resume()
+ */
+interface ResumeScheduleResponse {
+    scheduleId: string;
+    isPaused: false;
+    nextExecutionAt: string;
+}
+/**
+ * DLQ entry details
+ */
+interface DLQEntry {
+    id: string;
+    originalMessageId: string;
+    destination: string;
+    method: MessageMethod;
+    body: string | null;
+    headers: Record<string, string>;
+    failureReason: string;
+    lastStatusCode: number | null;
+    totalAttempts: number;
+    lastAttemptAt: string;
+    recoveredAt: string | null;
+    recoveryMessageId: string | null;
+    createdAt: string;
+}
+/**
+ * DLQ entry summary in list responses
+ */
+interface DLQEntrySummary {
+    id: string;
+    originalMessageId: string;
+    destination: string;
+    method: MessageMethod;
+    failureReason: string;
+    lastStatusCode: number | null;
+    totalAttempts: number;
+    lastAttemptAt: string;
+    createdAt: string;
+}
+/**
+ * Options for listing DLQ entries
+ */
+interface ListDLQOptions {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Response from dlq.list()
+ */
+interface ListDLQResponse {
+    entries: DLQEntrySummary[];
+    pagination: Pagination;
+}
+/**
+ * Response from dlq.retry()
+ */
+interface RetryDLQResponse {
+    dlqId: string;
+    newMessageId: string;
+    recovered: true;
+}
+/**
+ * Response from dlq.delete()
+ */
+interface DeleteDLQResponse {
+    dlqId: string;
+    deleted: boolean;
+}
+/**
+ * Response from dlq.purge()
+ */
+interface PurgeDLQResponse {
+    purged: true;
+    count: number;
+}
+
+/**
+ * Messages API client for publishing and managing webhook messages
+ */
+declare class MessagesAPI extends BaseClient {
+    constructor(options: BaseClientOptions);
+    /**
+     * 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 }
+     * );
+     * ```
+     */
+    publish(destination: string, body: unknown, options?: PublishOptions): Promise<PublishResponse>;
+    /**
+     * 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
+     * ```
+     */
+    get(messageId: string): Promise<Message>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    list(options?: ListMessagesOptions): Promise<ListMessagesResponse>;
+    /**
+     * 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
+     * ```
+     */
+    cancel(messageId: string): Promise<CancelMessageResponse>;
+    /**
+     * 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"
+     * ```
+     */
+    publishAndWait(destination: string, body: unknown, options?: PublishOptions & {
+        /** Polling interval in milliseconds (default: 1000) */
+        pollIntervalMs?: number;
+        /** Maximum time to wait in milliseconds (default: 60000) */
+        timeoutMs?: number;
+    }): Promise<Message>;
+}
+
+/**
+ * Schedules API client for managing cron-based recurring jobs
+ */
+declare class SchedulesAPI extends BaseClient {
+    constructor(options: BaseClientOptions);
+    /**
+     * 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
+     */
+    create(options: CreateScheduleOptions): Promise<CreateScheduleResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    get(scheduleId: string): Promise<Schedule>;
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    list(options?: ListSchedulesOptions): Promise<ListSchedulesResponse>;
+    /**
+     * 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
+     * ```
+     */
+    delete(scheduleId: string): Promise<DeleteScheduleResponse>;
+    /**
+     * 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
+     * ```
+     */
+    pause(scheduleId: string): Promise<PauseScheduleResponse>;
+    /**
+     * 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
+     * ```
+     */
+    resume(scheduleId: string): Promise<ResumeScheduleResponse>;
+}
+
+/**
+ * DLQ (Dead Letter Queue) API client for managing failed messages
+ *
+ * Messages that fail all retry attempts are moved to the DLQ for manual review and recovery.
+ */
+declare class DLQAPI extends BaseClient {
+    constructor(options: BaseClientOptions);
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    list(options?: ListDLQOptions): Promise<ListDLQResponse>;
+    /**
+     * 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
+     * ```
+     */
+    get(dlqId: string): Promise<DLQEntry>;
+    /**
+     * 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
+     * ```
+     */
+    retry(dlqId: string): Promise<RetryDLQResponse>;
+    /**
+     * 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...");
+     * ```
+     */
+    delete(dlqId: string): Promise<DeleteDLQResponse>;
+    /**
+     * 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`);
+     * ```
+     */
+    purge(): Promise<PurgeDLQResponse>;
+    /**
+     * 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`);
+     * ```
+     */
+    retryAll(): Promise<RetryDLQResponse[]>;
+}
+
+/**
+ * Workflows API client for triggering and managing workflow runs
+ */
+declare class WorkflowsAPI extends BaseClient {
+    constructor(options: BaseClientOptions);
+    /**
+     * 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" }
+     * );
+     * ```
+     */
+    trigger<T = unknown>(workflowId: string, workflowUrl: string, input?: T, options?: TriggerOptions): Promise<TriggerResponse>;
+    /**
+     * 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
+     * ```
+     */
+    getStatus(runId: string): Promise<StatusResponse>;
+    /**
+     * Cancel a running workflow
+     *
+     * @param runId - The workflow run ID to cancel
+     *
+     * @example
+     * ```typescript
+     * await qb.workflows.cancel(runId);
+     * ```
+     */
+    cancel(runId: string): Promise<void>;
+    /**
+     * 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
+     * ```
+     */
+    retry(runId: string): Promise<{
+        runId: string;
+        resumed: boolean;
+    }>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    listRuns(workflowId: string, options?: ListRunsOptions): Promise<ListRunsResponse>;
+    /**
+     * 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`);
+     * ```
+     */
+    sendEvent(eventName: string, options?: SendEventOptions): Promise<SendEventResponse>;
+    /**
+     * 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"
+     * ```
+     */
+    waitForCompletion(runId: string, options?: {
+        /** Polling interval in milliseconds (default: 1000) */
+        pollIntervalMs?: number;
+        /** Maximum time to wait in milliseconds (default: 300000 = 5 minutes) */
+        timeoutMs?: number;
+    }): Promise<StatusResponse>;
+    /**
+     * 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
+     * ```
+     */
+    triggerAndWait<T = unknown>(workflowId: string, workflowUrl: string, input?: T, options?: TriggerOptions & {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<StatusResponse>;
+}
+
+/**
+ * QueueBear client options
+ */
+interface QueueBearOptions {
+    /** Base URL of your QueueBear instance */
+    baseUrl: string;
+    /** API key (qb_live_* or qb_test_*) */
+    apiKey: string;
+    /** Project ID */
+    projectId: string;
+}
+/**
+ * Unified QueueBear client for all API operations
+ *
+ * Provides access to Messages, Schedules, DLQ, and Workflows APIs
+ * through a single client instance.
+ *
+ * @example
+ * ```typescript
+ * import { QueueBear, serve } from "@queuebear/workflow";
+ *
+ * const qb = new QueueBear({
+ *   baseUrl: "https://your-queuebear-instance.com",
+ *   apiKey: "qb_live_xxx",
+ *   projectId: "proj_xxx",
+ * });
+ *
+ * // Messages
+ * await qb.messages.publish("https://api.example.com/webhook", { data: "test" });
+ *
+ * // Schedules
+ * await qb.schedules.create({ destination: "...", cron: "0 9 * * *" });
+ *
+ * // DLQ
+ * await qb.dlq.list();
+ *
+ * // Workflows
+ * await qb.workflows.trigger("my-workflow", "https://...", input);
+ * ```
+ */
+declare class QueueBear {
+    private readonly 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);
+     * ```
+     */
+    readonly messages: MessagesAPI;
+    /**
+     * 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);
+     * ```
+     */
+    readonly schedules: SchedulesAPI;
+    /**
+     * 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();
+     * ```
+     */
+    readonly dlq: DLQAPI;
+    /**
+     * 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" }
+     * });
+     * ```
+     */
+    readonly workflows: WorkflowsAPI;
+    constructor(options: QueueBearOptions);
+    /**
+     * 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"
+     * ```
+     */
+    publishAndWait(destination: string, body: unknown, options?: PublishOptions & {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<Message>;
+    /**
+     * 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
+     * ```
+     */
+    triggerAndWait<T = unknown>(workflowId: string, workflowUrl: string, input?: T, options?: TriggerOptions & {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<StatusResponse>;
+}
+
+/**
+ * Error thrown when workflow needs to pause (e.g., for sleep)
+ */
+declare class WorkflowPausedError extends Error {
+    reason: string;
+    constructor(reason: string);
+}
+/**
+ * Context options for creating a new WorkflowContext
+ */
+interface WorkflowContextOptions<T> {
+    runId: string;
+    runToken: string;
+    input: T;
+    baseUrl: string;
+    authHeader: string;
+}
+/**
+ * WorkflowContext provides methods for executing workflow steps
+ */
+declare class WorkflowContext<T> {
+    readonly runId: string;
+    readonly input: T;
+    private runToken;
+    private baseUrl;
+    private authHeader;
+    private stepIndex;
+    constructor(options: WorkflowContextOptions<T>);
+    /**
+     * 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
+     */
+    run<R>(stepName: string, fn: () => Promise<R>, options?: StepRetryOptions): Promise<R>;
+    /**
+     * Sleep for specified seconds
+     * Step names must be unique within a workflow run
+     */
+    sleep(stepName: string, seconds: number): Promise<void>;
+    /**
+     * Sleep until specific date
+     */
+    sleepUntil(stepName: string, until: Date): Promise<void>;
+    /**
+     * Get all completed steps for the current run
+     * Useful for inspecting progress or debugging
+     */
+    getCompletedSteps(): Promise<CompletedStep[]>;
+    /**
+     * Make HTTP call (executed as a step)
+     */
+    call<R>(stepName: string, config: CallConfig): Promise<R>;
+    /**
+     * 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
+     */
+    waitForEvent<T = unknown>(stepName: string, eventName: string, options?: WaitForEventOptions): Promise<T>;
+    /**
+     * Send a fire-and-forget notification event
+     * @param eventName - Name of the event to send
+     * @param payload - Optional payload to include
+     */
+    notify(eventName: string, payload?: unknown): Promise<void>;
+    /**
+     * Execute multiple steps in parallel
+     * @param steps - Array of step definitions with name and function
+     */
+    parallel<T extends readonly unknown[]>(steps: {
+        [K in keyof T]: {
+            name: string;
+            fn: () => Promise<T[K]>;
+        };
+    }): Promise<T>;
+}
+/**
+ * Error thrown when parallel execution has failures
+ */
+declare class ParallelExecutionError extends Error {
+    errors: Array<{
+        index: number;
+        stepName: string;
+        error: Error;
+    }>;
+    constructor(message: string, errors: Array<{
+        index: number;
+        stepName: string;
+        error: Error;
+    }>);
+    get failedStepCount(): number;
+}
+
+/**
+ * Workflow handler function type
+ */
+type WorkflowHandler<TInput = unknown, TOutput = unknown> = (context: WorkflowContext<TInput>) => Promise<TOutput>;
+/**
+ * Create a workflow endpoint handler
+ */
+declare function serve<TInput = unknown, TOutput = unknown>(handler: WorkflowHandler<TInput, TOutput>, options?: ServeOptions): (request: Request) => Promise<Response>;
+
+export { type CallConfig, type CancelMessageResponse, type CompletedStep, type CreateScheduleOptions, type CreateScheduleResponse, DLQAPI, type DLQEntry, type DLQEntrySummary, type DeleteDLQResponse, type DeleteScheduleResponse, type DeliveryLog, type LastResponse, type ListDLQOptions, type ListDLQResponse, type ListMessagesOptions, type ListMessagesResponse, type ListRunsOptions, type ListRunsResponse, type ListSchedulesOptions, type ListSchedulesResponse, type Message, type MessageMethod, type MessageStatus, type MessageSummary, MessagesAPI, type Pagination, ParallelExecutionError, type ParallelStepDefinition, type PauseScheduleResponse, type PublishOptions, type PublishResponse, type PurgeDLQResponse, QueueBear, QueueBearError, type QueueBearOptions, type ResumeScheduleResponse, type RetryDLQResponse, type Schedule, type ScheduleSummary, SchedulesAPI, type SendEventOptions, type SendEventResponse, type ServeOptions, type StatusResponse, type StepRetryOptions, type StepType, type TriggerOptions, type TriggerResponse, type WaitForEventOptions, WorkflowContext, type WorkflowContextOptions, type WorkflowHandler, WorkflowPausedError, type WorkflowRun, type WorkflowRunStatus, type WorkflowStep, WorkflowsAPI, serve };