QueueBear

https://www.npmjs.com/package/queuebear
Admin
QueueBear SDK provides tools for building durable workflows, publishing and managing webhook...
Tokens:34,773
Snippets:286
Trust Score:9.6
Update:9 months ago
Show doc for...
Tokens:
Raw
### Complete Workflow Example

Source: https://www.npmjs.com/package/queuebear/v/0.1_activeTab=dependents

An example demonstrating a complete workflow with input types, steps, and pausing.

```APIDOC
## Complete Workflow Example

### Description
This example shows a full workflow definition including typed inputs, sequential steps, and pausing execution.

### Method
POST

### Endpoint
`/api/workflows/onboarding`

### Parameters
#### Request Body
- **userId** (string) - Required - The ID of the user.
- **email** (string) - Required - The email address of the user.

### Request Example
```typescript
// app/api/workflows/onboarding/route.ts
import { serve } from "queuebear";

interface OnboardingInput {
  userId: string;
  email: string;
}

export const POST = serve<OnboardingInput>(
  async (context) => {
    const { userId, email } = context.input;

    // Step 1: Send welcome email (cached if already done)
    await context.run("send-welcome", async () => {
      await sendEmail(email, "welcome");
    });

    // Step 2: Wait 3 days
    await context.sleep("wait-3-days", 60 * 60 * 24 * 3);

    // Step 3: Send tips email
    await context.run("send-tips", async () => {
      await sendEmail(email, "tips");
    });

    return { completed: true };
  },
  {
    signingSecret: process.env.QUEUEBEAR_SIGNING_SECRET,
  }
);
```
```

--------------------------------

### Complete Workflow Example: Onboarding

Source: https://www.npmjs.com/package/queuebear/index_activeTab=readme

An example demonstrating a complete onboarding workflow with multiple steps, including email sending and time delays.

```APIDOC
## POST /api/workflows/onboarding

### Description
This endpoint defines an onboarding workflow that sends welcome and tips emails after a delay.

### Method
POST

### Endpoint
`/api/workflows/onboarding`

### Parameters
#### Request Body
- **userId** (string) - Required - The ID of the user.
- **email** (string) - Required - The email address of the user.

### Request Example
```typescript
// app/api/workflows/onboarding/route.ts
import { serve } from "queuebear";

interface OnboardingInput {
  userId: string;
  email: string;
}

export const POST = serve<OnboardingInput>(
  async (context) => {
    const { userId, email } = context.input;

    // Step 1: Send welcome email (cached if already done)
    await context.run("send-welcome", async () => {
      await sendEmail(email, "welcome");
    });

    // Step 2: Wait 3 days
    await context.sleep("wait-3-days", 60 * 60 * 24 * 3);

    // Step 3: Send tips email
    await context.run("send-tips", async () => {
      await sendEmail(email, "tips");
    });

    return { completed: true };
  },
  {
    signingSecret: process.env.QUEUEBEAR_SIGNING_SECRET,
  }
);
```

### Response
#### Success Response (200)
Indicates the workflow has completed successfully.

#### Response Example
```json
{
  "completed": true
}
```
```

--------------------------------

### Complete Workflow Example

Source: https://www.npmjs.com/package/queuebear/v/0.1_activeTab=readme

An example demonstrating a complete workflow with multiple steps, including email sending and timed pauses.

```APIDOC
## Complete Workflow Example

```typescript
// app/api/workflows/onboarding/route.ts
import { serve } from "queuebear";

interface OnboardingInput {
  userId: string;
  email: string;
}

export const POST = serve<OnboardingInput>(
  async (context) => {
    const { userId, email } = context.input;

    // Step 1: Send welcome email (cached if already done)
    await context.run("send-welcome", async () => {
      await sendEmail(email, "welcome");
    });

    // Step 2: Wait 3 days
    await context.sleep("wait-3-days", 60 * 60 * 24 * 3);

    // Step 3: Send tips email
    await context.run("send-tips", async () => {
      await sendEmail(email, "tips");
    });

    return { completed: true };
  },
  {
    signingSecret: process.env.QUEUEBEAR_SIGNING_SECRET,
  }
);
```
```

--------------------------------

### Install QueueBear SDK

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependents

Installs the QueueBear SDK using npm. This is the first step to integrate QueueBear functionality into your project.

```bash
npm install queuebear
```

--------------------------------

### Complete QueueBear Workflow Example

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependents

A comprehensive example of a QueueBear workflow demonstrating typed inputs, sequential steps, email sending, time-based sleeping, and configuration options like signing secrets.

```typescript
// app/api/workflows/onboarding/route.ts
import { serve } from "queuebear";

interface OnboardingInput {
  userId: string;
  email: string;
}

export const POST = serve<OnboardingInput>(
  async (context) => {
    const { userId, email } = context.input;

    // Step 1: Send welcome email (cached if already done)
    await context.run("send-welcome", async () => {
      await sendEmail(email, "welcome");
    });

    // Step 2: Wait 3 days
    await context.sleep("wait-3-days", 60 * 60 * 24 * 3);

    // Step 3: Send tips email
    await context.run("send-tips", async () => {
      await sendEmail(email, "tips");
    });

    return { completed: true };
  },
  {
    signingSecret: process.env.QUEUEBEAR_SIGNING_SECRET,
  }
);
```

--------------------------------

### Complete QueueBear Workflow Example with Input and Async Operations

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependencies

A full example of a QueueBear workflow, demonstrating how to define input types, execute steps using `context.run`, pause execution with `context.sleep`, and handle asynchronous operations like sending emails. It also shows how to configure QueueBear with a signing secret.

```typescript
// app/api/workflows/onboarding/route.ts
import { serve } from "queuebear";

interface OnboardingInput {
  userId: string;
  email: string;
}

export const POST = serve<OnboardingInput>(
  async (context) => {
    const { userId, email } = context.input;

    // Step 1: Send welcome email (cached if already done)
    await context.run("send-welcome", async () => {
      await sendEmail(email, "welcome");
    });

    // Step 2: Wait 3 days
    await context.sleep("wait-3-days", 60 * 60 * 24 * 3);

    // Step 3: Send tips email
    await context.run("send-tips", async () => {
      await sendEmail(email, "tips");
    });

    return { completed: true };
  },
  {
    signingSecret: process.env.QUEUEBEAR_SIGNING_SECRET,
  }
);

```

--------------------------------

### Install QueueBear Package (NPM)

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependents

Installs the QueueBear npm package using the Node Package Manager. This is the first step to integrate QueueBear functionalities into your Node.js application.

```bash
npm i queuebear
```

--------------------------------

### Framework Integration: Hono

Source: https://www.npmjs.com/package/queuebear/index_activeTab=readme

Example of how to integrate QueueBear workflows with a Hono application.

```APIDOC
## POST /api/workflows/my-workflow

### Description
This endpoint serves as a webhook for QueueBear workflows when using Hono.

### Method
POST

### Endpoint
`/api/workflows/my-workflow`

### Request Body
This endpoint expects a request body which will be processed by the QueueBear `serve` handler.

### Request Example
```typescript
import { Hono } from "hono";
import { serve } from "queuebear";

const app = new Hono();

const handler = serve(async (context) => {
  await context.run("step-1", async () => {
    /* ... */ 
  });
  return { success: true };
});

app.post("/api/workflows/my-workflow", async (c) => {
  const response = await handler(c.req.raw);
  return response;
});
```

### Response
#### Success Response (200)
Returns a success status from the workflow execution.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Framework Integration

Source: https://www.npmjs.com/package/queuebear/index

Examples of how to integrate Queuebear's `serve` function with popular Node.js frameworks like Next.js, Express, and Hono.

```APIDOC
## Framework Integration

### Next.js (App Router)

This example shows how to use Queuebear's `serve` function within the Next.js App Router.

```typescript
// app/api/workflows/my-workflow/route.ts
import { serve } from "queuebear";

export const POST = serve(async (context) => {
  await context.run("step-1", async () => {
    /* ... */ 
  });
  return { success: true };
});
```

### Express

This example demonstrates integrating Queuebear with an Express.js application.

```javascript
import express from "express";
import { serve } from "queuebear";

const app = express();
app.use(express.json());

const handler = serve(async (context) => {
  await context.run("step-1", async () => {
    /* ... */ 
  });
  return { success: true };
});

app.post("/api/workflows/my-workflow", async (req, res) => {
  const response = await handler(
    new Request(req.url, {
      method: "POST",
      headers: req.headers as HeadersInit,
      body: JSON.stringify(req.body),
    })
  );
  res.status(response.status).json(await response.json());
});
```

### Hono

This example shows how to use Queuebear with the Hono web framework.

```javascript
import { Hono } from "hono";
import { serve } from "queuebear";

const app = new Hono();

const handler = serve(async (context) => {
  await context.run("step-1", async () => {
    /* ... */ 
  });
  return { success: true };
});

app.post("/api/workflows/my-workflow", async (c) => {
  const response = await handler(c.req.raw);
  return response;
});
```
```

--------------------------------

### Install Tunnelmole using npm (Node.js)

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependencies

Alternative method to install Tunnelmole globally using npm. This requires Node.js version 16 or higher and installs the 'tunnelmole' package, making the 'tmole' command available.

```javascript
npm install -g tunnelmole
```

--------------------------------

### Framework Integration: Express

Source: https://www.npmjs.com/package/queuebear/index_activeTab=readme

Example of how to integrate QueueBear workflows with an Express.js application.

```APIDOC
## POST /api/workflows/my-workflow

### Description
This endpoint serves as a webhook for QueueBear workflows when using Express.js.

### Method
POST

### Endpoint
`/api/workflows/my-workflow`

### Request Body
This endpoint expects a JSON request body which will be processed by the QueueBear `serve` handler.

### Request Example
```javascript
import express from "express";
import { serve } from "queuebear";

const app = express();
app.use(express.json());

const handler = serve(async (context) => {
  await context.run("step-1", async () => {
    /* ... */ 
  });
  return { success: true };
});

app.post("/api/workflows/my-workflow", async (req, res) => {
  const response = await handler(
    new Request(req.url, {
      method: "POST",
      headers: req.headers as HeadersInit,
      body: JSON.stringify(req.body),
    })
  );
  res.status(response.status).json(await response.json());
});
```

### Response
#### Success Response (200)
Returns a success status from the workflow execution.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Start Tunnelmole for Local Development (Shell)

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependents

Starts a Tunnelmole tunnel to forward external traffic to a local port. This allows QueueBear to send webhook events to your local development server. Replace '3000' with your application's port.

```bash
tmole 3000
```

--------------------------------

### Start Tunnelmole Tunnel (Shell)

Source: https://www.npmjs.com/package/queuebear/v/0.1

This command starts a Tunnelmole tunnel, forwarding traffic from a public URL to a local port. This is essential for local development to allow QueueBear to send webhook events to your application running on localhost.

```shell
tmole 3000
# Output: https://xxxx.tunnelmole.com is forwarding to localhost:3000
```

--------------------------------

### Install Tunnelmole for Local Development (Shell)

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependents

Installs the Tunnelmole utility, which is used to expose local development servers to the internet, enabling QueueBear webhooks to reach your local instance. Supports Linux, macOS, Windows WSL, and Node.js environments.

```bash
curl -O https://install.tunnelmole.com/t357g/install && sudo bash install
```

```bash
npm install -g tunnelmole
```

--------------------------------

### Integrate QueueBear with Hono

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependents

Illustrates the integration of QueueBear's `serve` function with the Hono web framework. This example highlights Hono's lightweight nature for API route handling.

```typescript
import { Hono } from "hono";
import { serve } from "queuebear";

const app = new Hono();

const handler = serve(async (context) => {
  await context.run("step-1", async () => {
    /* ... */
  });
  return { success: true };
});

app.post("/api/workflows/my-workflow", async (c) => {
  const response = await handler(c.req.raw);
  return response;
});
```

--------------------------------

### Workflow Integration

Source: https://www.npmjs.com/package/queuebear/v/0.1_activeTab=readme

Examples of integrating QueueBear workflows with various frameworks like Next.js, Express, and Hono.

```APIDOC
## Framework Integration

### Next.js (App Router)

```typescript
// app/api/workflows/my-workflow/route.ts
import { serve } from "queuebear";

export const POST = serve(async (context) => {
  await context.run("step-1", async () => {
    /* ... */
  });
  return { success: true };
});
```

### Express

```typescript
import express from "express";
import { serve } from "queuebear";

const app = express();
app.use(express.json());

const handler = serve(async (context) => {
  await context.run("step-1", async () => {
    /* ... */
  });
  return { success: true };
});

app.post("/api/workflows/my-workflow", async (req, res) => {
  const response = await handler(
    new Request(req.url, {
      method: "POST",
      headers: req.headers as HeadersInit,
      body: JSON.stringify(req.body),
    })
  );
  res.status(response.status).json(await response.json());
});
```

### Hono

```typescript
import { Hono } from "hono";
import { serve } from "queuebear";

const app = new Hono();

const handler = serve(async (context) => {
  await context.run("step-1", async () => {
    /* ... */
  });
  return { success: true };
});

app.post("/api/workflows/my-workflow", async (c) => {
  const response = await handler(c.req.raw);
  return response;
});
```
```

--------------------------------

### Framework Integration: Next.js (App Router)

Source: https://www.npmjs.com/package/queuebear/index_activeTab=readme

Example of how to integrate QueueBear workflows using the App Router in Next.js.

```APIDOC
## POST /api/workflows/my-workflow

### Description
This endpoint serves as a webhook for QueueBear workflows when using Next.js App Router.

### Method
POST

### Endpoint
`/api/workflows/my-workflow`

### Request Body
This endpoint expects a request body handled by the `serve` function from QueueBear.

### Request Example
```typescript
// app/api/workflows/my-workflow/route.ts
import { serve } from "queuebear";

export const POST = serve(async (context) => {
  await context.run("step-1", async () => {
    /* ... */ 
  });
  return { success: true };
});
```

### Response
#### Success Response (200)
Returns a success status from the workflow execution.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Get Completed Steps with `context.getCompletedSteps`

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependents

Shows how to retrieve a list of all steps that have successfully completed within a QueueBear workflow run. This is primarily useful for debugging purposes.

```typescript
const steps = await context.getCompletedSteps();
console.log(`Completed ${steps.length} steps`);
```

--------------------------------

### Publish Message with Tunnel URL (JavaScript)

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependencies

Example of publishing a message using the QueueBear SDK, specifying a Tunnelmole URL as the callback endpoint. This allows testing message publishing locally by routing through the tunnel.

```javascript
await qb.messages.publish("https://xxxx.tunnelmole.com/api/webhooks", {
  event: "user.created",
  userId: "123"
});
```

--------------------------------

### Wait for QueueBear Workflow Completion

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependents

Provides an example of using `qb.workflows.waitForCompletion` to block execution until a specified QueueBear workflow run finishes. It allows configuring polling intervals and timeouts.

```typescript
const result = await qb.workflows.waitForCompletion(runId, {
  pollIntervalMs: 2000,
  timeoutMs: 60000,
});
```

--------------------------------

### Context Methods

Source: https://www.npmjs.com/package/queuebear/index

Available methods within `serve()` handlers for executing steps, managing state, and interacting with Queuebear.

```APIDOC
## Context Methods

Available in `serve()` handlers:

### `context.run(stepName, fn, options?)`

Executes a function as a step, with automatic caching based on `stepName`.

```javascript
const result = await context.run("fetch-user", async () => {
  return await db.users.findById(userId);
});
```

### `context.sleep(stepName, seconds)`

Pauses the workflow execution for a specified number of seconds.

```javascript
await context.sleep("wait-1-hour", 3600);
```

### `context.sleepUntil(stepName, date)`

Pauses the workflow execution until a specific date and time.

```javascript
await context.sleepUntil("wait-until-tomorrow", new Date("2024-01-15"));
```

### `context.call(stepName, config)`

Makes an HTTP call as a cached step. Handles caching based on `stepName` and request details.

```javascript
const data = await context.call("fetch-api", {
  url: "https://api.example.com/data",
  method: "POST",
  headers: { Authorization: "Bearer xxx" },
  body: { key: "value" },
});
```

### `context.waitForEvent(stepName, eventName, options?)`

Waits for an external event to be sent to Queuebear. The workflow will resume when the event is received.

```javascript
const payload = await context.waitForEvent("wait-approval", "order.approved", {
  eventKey: "order-123",
  timeoutSeconds: 86400, // 1 day
});
```

### `context.notify(eventName, payload?)`

Sends a fire-and-forget event. This is useful for notifying external systems without blocking workflow execution.

```javascript
await context.notify("user.onboarded", { userId: "123" });
```

### `context.parallel(steps)`

Executes multiple steps concurrently. Returns an array of results corresponding to the input steps.

```javascript
const [user, orders, preferences] = await context.parallel([
  { name: "fetch-user", fn: () => fetchUser(userId) },
  { name: "fetch-orders", fn: () => fetchOrders(userId) },
  { name: "fetch-preferences", fn: () => fetchPreferences(userId) },
]);
```

### `context.getCompletedSteps()`

Retrieves a list of all steps that have successfully completed during the current workflow run. Useful for debugging.

```javascript
const steps = await context.getCompletedSteps();
console.log(`Completed ${steps.length} steps`);
```
```

--------------------------------

### Initialize QueueBear Client

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependents

Initializes the QueueBear client with your API key and project ID. This client instance is used to interact with all QueueBear services.

```javascript
import { QueueBear, serve } from "queuebear";

const qb = new QueueBear({
  apiKey: "qb_live_xxx",
  projectId: "proj_xxx",
});
```

--------------------------------

### Context Methods

Source: https://www.npmjs.com/package/queuebear/v/0.1_activeTab=versions

Available methods within a `serve()` handler for managing workflow execution.

```APIDOC
## Context Methods

Available in `serve()` handlers:

### `context.run(stepName, fn, options?)`
Execute a step with automatic caching.

**Parameters:**
- **stepName** (string) - Required - A unique name for the step.
- **fn** (function) - Required - The asynchronous function to execute.
- **options** (object) - Optional - Options for the step.

**Example:**
```typescript
const result = await context.run("fetch-user", async () => {
  return await db.users.findById(userId);
});
```

### `context.sleep(stepName, seconds)`
Pause workflow for a specified duration.

**Parameters:**
- **stepName** (string) - Required - A unique name for the sleep step.
- **seconds** (number) - Required - The duration in seconds to sleep.

**Example:**
```typescript
await context.sleep("wait-1-hour", 3600);
```

### `context.sleepUntil(stepName, date)`
Pause workflow execution until a specific date and time.

**Parameters:**
- **stepName** (string) - Required - A unique name for the sleep step.
- **date** (Date) - Required - The date and time to resume execution.

**Example:**
```typescript
await context.sleepUntil("wait-until-tomorrow", new Date("2024-01-15"));
```

### `context.call(stepName, config)`
Make an HTTP call as a cached step.

**Parameters:**
- **stepName** (string) - Required - A unique name for the call step.
- **config** (object) - Required - Configuration for the HTTP request.
  - **url** (string) - Required - The URL to call.
  - **method** (string) - Optional - HTTP method (default: GET).
  - **headers** (object) - Optional - Request headers.
  - **body** (any) - Optional - Request body.

**Example:**
```typescript
const data = await context.call("fetch-api", {
  url: "https://api.example.com/data",
  method: "POST",
  headers: { Authorization: "Bearer xxx" },
  body: { key: "value" },
});
```

### `context.waitForEvent(stepName, eventName, options?)`
Wait for an external event to be sent to the workflow.

**Parameters:**
- **stepName** (string) - Required - A unique name for the event wait step.
- **eventName** (string) - Required - The name of the event to wait for.
- **options** (object) - Optional - Options for waiting.
  - **eventKey** (string) - Required - A unique key to identify the specific event instance.
  - **timeoutSeconds** (number) - Optional - Maximum time to wait in seconds.

**Example:**
```typescript
const payload = await context.waitForEvent("wait-approval", "order.approved", {
  eventKey: "order-123",
  timeoutSeconds: 86400, // 1 day
});
```

### `context.notify(eventName, payload?)`
Send a fire-and-forget event from the workflow to an external system.

**Parameters:**
- **eventName** (string) - Required - The name of the event to send.
- **payload** (object) - Optional - Data associated with the event.

**Example:**
```typescript
await context.notify("user.onboarded", { userId: "123" });
```

### `context.parallel(steps)`
Execute multiple steps in parallel.

**Parameters:**
- **steps** (array) - Required - An array of step objects to execute.
  - **name** (string) - Required - The name of the parallel step.
  - **fn** (function) - Required - The asynchronous function to execute for this step.

**Example:**
```typescript
const [user, orders, preferences] = await context.parallel([
  { name: "fetch-user", fn: () => fetchUser(userId) },
  { name: "fetch-orders", fn: () => fetchOrders(userId) },
  { name: "fetch-preferences", fn: () => fetchPreferences(userId) },
]);
```

### `context.getCompletedSteps()`
Retrieve a list of all steps that have successfully completed in the current workflow run.

**Example:**
```typescript
const steps = await context.getCompletedSteps();
console.log(`Completed ${steps.length} steps`);
```
```

--------------------------------

### Workflows API - serve()

Source: https://www.npmjs.com/package/queuebear/index_activeTab=versions

Create a durable workflow endpoint using the `serve()` function, which handles workflow execution and step caching.

```APIDOC
## Workflows API

Build durable, fault-tolerant workflows with automatic step caching.
Workflows consist of two parts:
  1. **Workflow endpoint** - Created with `serve()`, handles workflow execution
  2. **Client** - Uses `qb.workflows` to trigger and manage workflow runs

### `serve()` - Create a Workflow Endpoint

The `serve()` function creates an HTTP handler for your workflow. It receives requests from QueueBear, executes your workflow code, and manages step caching automatically.

```javascript
import { serve } from "queuebear";

export const POST = serve<InputType>(async (context) => {
  // Your workflow logic here
  return result;
}, options);
```

**Parameters:**

Parameter | Type | Description  
---|---|---
`handler` | `(context: WorkflowContext<T>) => Promise<R>` | Your workflow function  
`options` | `ServeOptions` | Optional configuration  

**Options:**

Option | Type | Description  
---|---|---
`signingSecret` | `string` | Secret to verify requests come from QueueBear  

```

--------------------------------

### Messages API

Source: https://www.npmjs.com/package/queuebear/v/0.1_activeTab=code

Provides functionality to publish, get, list, cancel, and publish-and-wait for messages. Supports delivery retries, callbacks, and deduplication.

```APIDOC
## Messages API

Provides functionality to publish, get, list, cancel, and publish-and-wait for messages. Supports delivery retries, callbacks, and deduplication.

### Publish a Message

This endpoint publishes a message to be delivered to a webhook destination with automatic retries.

#### Method
POST

#### Endpoint
`qb.messages.publish(url, body, options)`

#### Parameters

##### Request Body (Implicit)
- **url** (string) - Required - The webhook URL to send the message to.
- **body** (object) - Required - The payload of the message.
- **options** (object) - Optional - Configuration for message delivery.
  - **delay** (string) - Optional - Delay before delivery (e.g., "30s").
  - **retries** (number) - Optional - Number of retry attempts (default is 5).
  - **method** (string) - Optional - HTTP method for delivery (default is POST).
  - **headers** (object) - Optional - Headers to forward to the webhook.
  - **callbackUrl** (string) - Optional - URL for success callback.
  - **failureCallbackUrl** (string) - Optional - URL for failure callback.
  - **deduplicationId** (string) - Optional - Unique ID to prevent duplicate messages.

#### Request Example
```javascript
const { messageId } = await qb.messages.publish(
  "https://api.example.com/webhook",
  { event: "user.created", userId: "123" },
  {
    delay: "30s",
    retries: 5,
    method: "POST",
    headers: { "X-API-Key": "secret" },
    callbackUrl: "https://...",
    failureCallbackUrl: "https://...",
    deduplicationId: "unique-id",
  }
);
```

#### Response Example (Success Response - 200)
```json
{
  "messageId": "msg_abc123"
}
```

### Get Message Status

Retrieves the status and delivery logs for a specific message.

#### Method
GET

#### Endpoint
`qb.messages.get(messageId)`

#### Parameters

##### Path Parameters
- **messageId** (string) - Required - The ID of the message to retrieve.

#### Response Example (Success Response - 200)
```json
{
  "status": "pending" | "completed" | "failed",
  "deliveryLogs": [
    {
      "attempt": 1,
      "timestamp": "2023-10-27T10:00:00Z",
      "status": "delivered",
      "response": "200 OK"
    }
  ]
}
```

### List Messages

Lists messages with optional filtering by status.

#### Method
GET

#### Endpoint
`qb.messages.list(options)`

#### Parameters

##### Query Parameters
- **status** (string) - Optional - Filter messages by status (e.g., "pending", "completed", "failed").
- **limit** (number) - Optional - Maximum number of messages to return (default is 20).
- **offset** (number) - Optional - Number of messages to skip (default is 0).

#### Response Example (Success Response - 200)
```json
{
  "messages": [
    {
      "messageId": "msg_abc123",
      "status": "pending"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 100
  }
}
```

### Cancel a Message

Cancels a message that has not yet been delivered.

#### Method
DELETE

#### Endpoint
`qb.messages.cancel(messageId)`

#### Parameters

##### Path Parameters
- **messageId** (string) - Required - The ID of the message to cancel.

### Publish and Wait

Publishes a message and waits for its delivery or timeout.

#### Method
POST

#### Endpoint
`qb.messages.publishAndWait(url, body, options)`

#### Parameters

##### Request Body (Implicit)
- **url** (string) - Required - The webhook URL to send the message to.
- **body** (object) - Required - The payload of the message.
- **options** (object) - Optional - Configuration for message delivery.
  - **timeoutMs** (number) - Required - Timeout in milliseconds to wait for delivery.

#### Request Example
```javascript
const message = await qb.messages.publishAndWait(
  "https://api.example.com/webhook",
  { event: "user.created" },
  { timeoutMs: 30000 }
);
console.log(message.status);
```

#### Response Example (Success Response - 200)
```json
{
  "messageId": "msg_abc123",
  "status": "completed",
  "deliveryLogs": [
    {
      "attempt": 1,
      "timestamp": "2023-10-27T10:00:00Z",
      "status": "delivered",
      "response": "200 OK"
    }
  ]
}
```
```

--------------------------------

### Get Message Status

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependents

Retrieves the status and delivery logs of a specific message using its ID. The status can be 'pending', 'completed', or 'failed'.

```javascript
const message = await qb.messages.get(messageId);
console.log(message.status); // "pending" | "completed" | "failed"
console.log(message.deliveryLogs); // Delivery attempt history
```

--------------------------------

### Get DLQ Entry Details

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependents

Retrieves detailed information about a specific DLQ entry, including the original message body and the total number of failed delivery attempts.

```javascript
const entry = await qb.dlq.get(dlqId);
console.log(entry.body); // Original message body
console.log(entry.totalAttempts); // Number of failed attempts
```

--------------------------------

### Trigger a QueueBear Workflow

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependents

Shows how to initiate a QueueBear workflow programmatically using the `qb.workflows.trigger` method. It includes parameters for workflow ID, callback URL, input data, and optional configurations like idempotency keys and maximum duration.

```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",
    maxDuration: 60 * 60 * 24 * 7, // 7 day timeout
  }
);
```

--------------------------------

### Execute Steps in Parallel with `context.parallel`

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependents

Demonstrates how to run multiple workflow steps concurrently using `context.parallel`. This can significantly speed up workflows where steps are independent.

```typescript
const [user, orders, preferences] = await context.parallel([
  { name: "fetch-user", fn: () => fetchUser(userId) },
  { name: "fetch-orders", fn: () => fetchOrders(userId) },
  { name: "fetch-preferences", fn: () => fetchPreferences(userId) },
]);
```

--------------------------------

### Workflows API - Serve Endpoint

Source: https://www.npmjs.com/package/queuebear/v/0.1

Create a durable workflow endpoint using the `serve()` function to handle workflow execution and step caching.

```APIDOC
## Workflows API

Build durable, fault-tolerant workflows with automatic step caching.
Workflows consist of two parts:
  1. **Workflow endpoint** - Created with `serve()`, handles workflow execution
  2. **Client** - Uses `qb.workflows` to trigger and manage workflow runs

### `serve()` - Create a Workflow Endpoint
The `serve()` function creates an HTTP handler for your workflow. It receives requests from QueueBear, executes your workflow code, and manages step caching automatically.

```typescript
import { serve } from "queuebear";

export const POST = serve<InputType>(async (context) => {
  // Your workflow logic here
  return result;
}, options);
```

**Parameters:**
Parameter | Type | Description  
---|---|---
`handler` | `(context: WorkflowContext<T>) => Promise<R>` | Your workflow function  
`options` | `ServeOptions` | Optional configuration  

**Options:**
Option | Type | Description  
---|---|---
`signingSecret` | `string` | Secret to verify requests come from QueueBear  
```

--------------------------------

### Create Workflow Endpoint with serve()

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependents

Creates an HTTP handler for a workflow using the `serve()` function. This function executes workflow logic, handles incoming requests from QueueBear, and manages step caching. It requires a handler function and optional configuration.

```javascript
import { serve } from "queuebear";

export const POST = serve<InputType>(async (context) => {
  // Your workflow logic here
  return result;
}, options);
```

--------------------------------

### Trigger Workflows via QueueBear using Tunnel URL (JavaScript)

Source: https://www.npmjs.com/package/queuebear/index_activeTab=dependents

Triggers a QueueBear workflow using a Tunnelmole URL. This example shows how to route workflow triggers to a local development environment through Tunnelmole, ensuring that callbacks and failure callbacks can be tested locally.

```javascript
// Works for workflows too
await qb.workflows.trigger(
  "onboarding",
  "https://xxxx.tunnelmole.com/api/workflows/onboarding",
  { userId: "123" }
);
```

--------------------------------

### Context Methods

Source: https://www.npmjs.com/package/queuebear/v/0.1_activeTab=dependents

Available methods within a QueueBear workflow handler context.

```APIDOC
## Context Methods

Available in `serve()` handlers:

### `context.run(stepName, fn, options?)`

#### Description
Executes a function as a distinct step within the workflow, with automatic caching capabilities.

#### Parameters
- **stepName** (string) - A unique identifier for the step.
- **fn** (function) - The asynchronous function to execute.
- **options** (object) - Optional configuration for the step.

#### Request Example
```javascript
const result = await context.run("fetch-user", async () => {
  return await db.users.findById(userId);
});
```

### `context.sleep(stepName, seconds)`

#### Description
Pauses the workflow execution for a specified duration.

#### Parameters
- **stepName** (string) - A unique identifier for the sleep step.
- **seconds** (number) - The duration to sleep in seconds.

#### Request Example
```javascript
await context.sleep("wait-1-hour", 3600);
```

### `context.sleepUntil(stepName, date)`

#### Description
Pauses workflow execution until a specific date and time.

#### Parameters
- **stepName** (string) - A unique identifier for the sleep step.
- **date** (Date) - The target date and time to resume execution.

#### Request Example
```javascript
await context.sleepUntil("wait-until-tomorrow", new Date("2024-01-15"));
```

### `context.call(stepName, config)`

#### Description
Performs an HTTP call as a cached step, allowing for external API interactions.

#### Parameters
- **stepName** (string) - A unique identifier for the call step.
- **config** (object) - Configuration for the HTTP call.
  - **url** (string) - Required - The URL to make the request to.
  - **method** (string) - Optional - HTTP method (e.g., 'GET', 'POST'). Defaults to 'GET'.
  - **headers** (object) - Optional - Request headers.
  - **body** (any) - Optional - Request body.

#### Request Example
```javascript
const data = await context.call("fetch-api", {
  url: "https://api.example.com/data",
  method: "POST",
  headers: { Authorization: "Bearer xxx" },
  body: { key: "value" },
});
```

### `context.waitForEvent(stepName, eventName, options?)`

#### Description
Waits for an external event to be sent to the workflow.

#### Parameters
- **stepName** (string) - A unique identifier for the event waiting step.
- **eventName** (string) - Required - The name of the event to wait for.
- **options** (object) - Optional configuration for waiting.
  - **eventKey** (string) - Required - A unique key to identify the specific event instance.
  - **timeoutSeconds** (number) - Optional - Maximum time to wait for the event in seconds.

#### Request Example
```javascript
const payload = await context.waitForEvent("wait-approval", "order.approved", {
  eventKey: "order-123",
  timeoutSeconds: 86400, // 1 day
});
```

### `context.notify(eventName, payload?)`

#### Description
Sends a fire-and-forget event from the workflow to an external system.

#### Parameters
- **eventName** (string) - Required - The name of the event to send.
- **payload** (object) - Optional - Data associated with the event.

#### Request Example
```javascript
await context.notify("user.onboarded", { userId: "123" });
```

### `context.parallel(steps)`

#### Description
Executes multiple workflow steps concurrently.

#### Parameters
- **steps** (array) - An array of step objects to execute in parallel.
  - **name** (string) - Required - The name of the step.
  - **fn** (function) - Required - The asynchronous function to execute for this step.

#### Request Example
```javascript
const [user, orders, preferences] = await context.parallel([
  { name: "fetch-user", fn: () => fetchUser(userId) },
  { name: "fetch-orders", fn: () => fetchOrders(userId) },
  { name: "fetch-preferences", fn: () => fetchPreferences(userId) },
]);
```

### `context.getCompletedSteps()`

#### Description
Retrieves an array containing details of all steps that have successfully completed within the current workflow run.

#### Request Example
```javascript
const steps = await context.getCompletedSteps();
console.log(`Completed ${steps.length} steps`);
```
```

--------------------------------

### Context Methods

Source: https://www.npmjs.com/package/queuebear/v/0.1_activeTab=readme

Available methods within QueueBear workflow handlers for executing steps, managing state, and interacting with external systems.

```APIDOC
## Context Methods

Available in `serve()` handlers:

### `context.run(stepName, fn, options?)`
Execute a step with automatic caching.

```typescript
const result = await context.run("fetch-user", async () => {
  return await db.users.findById(userId);
});
```

### `context.sleep(stepName, seconds)`
Pause workflow for specified duration.

```typescript
await context.sleep("wait-1-hour", 3600);
```

### `context.sleepUntil(stepName, date)`
Pause until a specific date/time.

```typescript
await context.sleepUntil("wait-until-tomorrow", new Date("2024-01-15"));
```

### `context.call(stepName, config)`
Make an HTTP call as a cached step.

```typescript
const data = await context.call("fetch-api", {
  url: "https://api.example.com/data",
  method: "POST",
  headers: { Authorization: "Bearer xxx" },
  body: { key: "value" },
});
```

### `context.waitForEvent(stepName, eventName, options?)`
Wait for an external event.

```typescript
const payload = await context.waitForEvent("wait-approval", "order.approved", {
  eventKey: "order-123",
  timeoutSeconds: 86400, // 1 day
});
```

### `context.notify(eventName, payload?)`
Send fire-and-forget event.

```typescript
await context.notify("user.onboarded", { userId: "123" });
```

### `context.parallel(steps)`
Execute steps in parallel.

```typescript
const [user, orders, preferences] = await context.parallel([
  { name: "fetch-user", fn: () => fetchUser(userId) },
  { name: "fetch-orders", fn: () => fetchOrders(userId) },
  { name: "fetch-preferences", fn: () => fetchPreferences(userId) },
]);
```

### `context.getCompletedSteps()`
Get all completed steps for debugging.

```typescript
const steps = await context.getCompletedSteps();
console.log(`Completed ${steps.length} steps`);
```
```

--------------------------------

### Triggering a QueueBear Workflow

Source: https://www.npmjs.com/package/queuebear/index_activeTab=code

Shows how to initiate a QueueBear workflow programmatically. This involves specifying the workflow name, its endpoint URL, input data, and optional configuration like an idempotency key and maximum duration.

```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",
    maxDuration: 60 * 60 * 24 * 7, // 7 day timeout
  }
);

```

--------------------------------

### Trigger a Workflow

Source: https://www.npmjs.com/package/queuebear/v/0.1_activeTab=readme

Instructions on how to trigger a QueueBear workflow programmatically with input data and options.

```APIDOC
## Trigger a Workflow

```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",
    maxDuration: 60 * 60 * 24 * 7, // 7 day timeout
  }
);
```
```

--------------------------------

### Context Method: context.run()

Source: https://www.npmjs.com/package/queuebear/index_activeTab=readme

Executes a function as a step within a workflow, with automatic caching enabled.

```APIDOC
## context.run(stepName, fn, options?)

### Description
Executes a given function as a step within a QueueBear workflow. Results can be cached to avoid re-computation if the step is run again with the same inputs.

### Parameters
- **stepName** (string) - Required - A unique name for this step within the workflow.
- **fn** (Function) - Required - The asynchronous function to execute.
- **options** (object) - Optional - Configuration options for the step.

### Request Example
```javascript
const result = await context.run("fetch-user", async () => {
  return await db.users.findById(userId);
});
```

### Response
#### Success Response
Returns the result of the executed function `fn`.
```

--------------------------------

### Workflows API

Source: https://www.npmjs.com/package/queuebear/index_activeTab=code

APIs for building and managing durable workflows with automatic step caching.

```APIDOC
## Workflows API

### `serve()` - Create a Workflow Endpoint

**Description**: Creates an HTTP handler for your workflow. This endpoint receives requests from QueueBear, executes your workflow logic, and manages step caching.

**Method**: POST (for incoming requests handled by `serve()`)

**Endpoint**: The URL you configure for your workflow.

#### Parameters

**Path Parameters**: None

**Query Parameters**: None

#### Request Body (for incoming requests handled by `serve()`)

- **context** (`WorkflowContext<T>`) - Object containing input and execution context for the workflow step.

#### `serve()` Function Parameters

- **handler** (`(context: WorkflowContext<T>) => Promise<R>`) - Required - Your workflow function that processes the input and returns a result.
- **options** (`ServeOptions`) - Optional - Configuration for the workflow endpoint.
  - **signingSecret** (`string`) - Required - Secret used to verify that incoming requests originate from QueueBear.

### Request Example (Defining the workflow endpoint)

```javascript
import { serve } from "queuebear";

// Define the expected input type for your workflow
interface MyInputType {
  name: string;
}

// Define the expected return type for your workflow
interface MyResultType {
  greeting: string;
}

export const POST = serve<MyInputType, MyResultType>(async (context) => {
  const { name } = context.input; // Access input data
  console.log("Workflow step executed for:", name);

  // Perform your workflow logic here
  const result: MyResultType = { greeting: `Hello, ${name}!` };

  return result;
}, {
  signingSecret: "your_signing_secret_here",
});
```

### Response (for incoming requests handled by `serve()`)

#### Success Response (200)

- **Result** (`R`) - The result returned by your workflow handler function.

#### Response Example (from QueueBear to your workflow endpoint)

```json
{
  "greeting": "Hello, World!"
}
```

---

### Triggering a Workflow Run (using `qb.workflows`)

**Description**: Initiates a new run of a defined workflow.

**Method**: POST (implicitly through SDK)

**Endpoint**: Not directly exposed, managed by the SDK.

#### Parameters

**Path Parameters**: None

**Query Parameters**: None

#### Request Body (implicit in SDK call)

- **workflowId** (string) - Required - The ID of the workflow to trigger.
- **input** (object) - Optional - The input data for the first step of the workflow.

### Request Example

```javascript
const workflowRun = await qb.workflows.trigger("your_workflow_id", {
  name: "Alice",
});
console.log("Workflow run started:", workflowRun.runId);
```

### Response

#### Success Response (200)

- **runId** (string) - The unique identifier for the triggered workflow run.

#### Response Example

```json
{
  "runId": "run_abc123"
}
```
```
Tokens:
Raw