queuebear 0.1.7 → 0.1.9

package/README.md

@@ -493,33 +493,34 @@ The signing secret is available in your QueueBear project settings. When configu
 
 ## Local Development
 
-When developing locally, your webhook endpoints run on `localhost` which isn't accessible from QueueBear's servers. Use a tunnel service to expose your local server.
+When developing locally, your webhook endpoints run on `localhost` which isn't accessible from QueueBear's servers. Use [Tunnelmole](https://tunnelmole.com) to expose your local server - it's free and requires no signup.
 
-### Using ngrok (Recommended)
+### Installing Tunnelmole
 
-[ngrok](https://ngrok.com) provides stable URLs and a built-in request inspector.
-
-**1. Install and authenticate:**
+**Linux, macOS, Windows WSL:**
 
 ```bash
-# Install
-brew install ngrok  # or download from ngrok.com/download
+curl -O https://install.tunnelmole.com/t357g/install && sudo bash install
+```
 
-# Authenticate (free account required)
-ngrok config add-authtoken YOUR_AUTH_TOKEN
+**Node.js (all platforms, requires Node 16+):**
+
+```bash
+npm install -g tunnelmole
 ```
 
-**2. Start the tunnel:**
+### Starting a Tunnel
 
 ```bash
-ngrok http 3000
+tmole 3000
+# Output: https://xxxx.tunnelmole.com is forwarding to localhost:3000
 ```
 
-**3. Use the forwarding URL:**
+### Using the Tunnel URL
 
 ```typescript
-// Use ngrok URL instead of localhost
-await qb.messages.publish("https://abc123.ngrok.io/api/webhooks", {
+// Use tunnelmole URL instead of localhost
+await qb.messages.publish("https://xxxx.tunnelmole.com/api/webhooks", {
   event: "user.created",
   userId: "123"
 });
@@ -527,37 +528,16 @@ await qb.messages.publish("https://abc123.ngrok.io/api/webhooks", {
 // Works for workflows too
 await qb.workflows.trigger(
   "onboarding",
-  "https://abc123.ngrok.io/api/workflows/onboarding",
+  "https://xxxx.tunnelmole.com/api/workflows/onboarding",
   { userId: "123" }
 );
 ```
 
-**Debugging:** ngrok provides a web inspector at `http://localhost:4040` to view requests, responses, and replay failed deliveries.
-
-### Using localtunnel
-
-[localtunnel](https://localtunnel.me) is free and requires no signup.
-
-```bash
-npx localtunnel --port 3000
-# Output: your url is: https://good-months-leave.loca.lt
-```
-
-**Note:** localtunnel shows a reminder page on first visit. Bypass it by adding a header:
-
-```typescript
-await qb.messages.publish(
-  "https://good-months-leave.loca.lt/api/webhooks",
-  { event: "test" },
-  { headers: { "bypass-tunnel-reminder": "true" } }
-);
-```
-
 ### Tips
 
 - Store your tunnel URL in `.env` for easy switching between local and production
 - Both `callbackUrl` and `failureCallbackUrl` need public URLs for local testing
-- ngrok URLs change on restart (stable URLs require a paid plan)
+- Tunnel URLs change on restart
 
 ---
 

package/dist/index.d.ts

@@ -468,6 +468,26 @@ interface PurgeDLQResponse {
     purged: true;
     count: number;
 }
+/**
+ * Options for serveMessage() function
+ */
+interface ServeMessageOptions {
+    /** Signing secret for verifying message authenticity */
+    signingSecret?: string;
+}
+/**
+ * Context provided to message handlers by serveMessage()
+ */
+interface MessageContext<T> {
+    /** The parsed request body */
+    body: T;
+    /** QueueBear message ID (from X-QueueBear-Message-Id header) */
+    messageId?: string;
+    /** Current attempt number (0-indexed) */
+    attemptNumber: number;
+    /** All request headers */
+    headers: Record<string, string>;
+}
 
 /**
  * Messages API client for publishing and managing webhook messages
@@ -495,12 +515,12 @@ declare class MessagesAPI extends BaseClient {
     /**
      * Get message details and delivery history
      *
-     * @param messageId - The message ID (e.g., "msg_abc123...")
+     * @param messageId - The message ID (e.g., "abc123...")
      * @returns Full message details including delivery logs
      *
      * @example
      * ```typescript
-     * const message = await qb.messages.get("msg_abc123");
+     * const message = await qb.messages.get("abc123");
      * console.log(message.status); // "completed" | "pending" | "failed"
      * console.log(message.deliveryLogs); // Delivery attempt history
      * ```
@@ -1189,4 +1209,40 @@ type WorkflowHandler<TInput = unknown, TOutput = unknown> = (context: WorkflowCo
  */
 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, type WorkflowContext, type WorkflowContextOptions, type WorkflowHandler, WorkflowPausedError, type WorkflowRun, type WorkflowRunStatus, type WorkflowStep, WorkflowsAPI, createWorkflowContext, serve };
+/**
+ * Message handler function type for serveMessage()
+ */
+type MessageHandler<TBody = unknown, TResult = unknown> = (context: MessageContext<TBody>) => Promise<TResult>;
+/**
+ * Create a message webhook handler for simple message delivery.
+ *
+ * Unlike serve() which is designed for durable workflows with steps and state,
+ * serveMessage() is for simple message webhooks published via messages.publish().
+ *
+ * @param handler - The handler function to process incoming messages
+ * @param options - Optional configuration (e.g., signing secret for verification)
+ * @returns A Request handler function for use with any HTTP framework
+ *
+ * @example
+ * ```typescript
+ * import { serveMessage } from 'queuebear';
+ *
+ * const handler = serveMessage<{ userId: string }>(
+ *   async (context) => {
+ *     console.log(`Processing message ${context.messageId} for user ${context.body.userId}`);
+ *     await processUser(context.body.userId);
+ *     return { success: true };
+ *   },
+ *   { signingSecret: process.env.QB_SIGNING_SECRET }
+ * );
+ *
+ * // With Hono
+ * app.post('/webhook', (c) => handler(c.req.raw));
+ *
+ * // With Express (using raw Request)
+ * app.post('/webhook', (req, res) => handler(req).then(r => res.send(r)));
+ * ```
+ */
+declare function serveMessage<TBody = unknown, TResult = unknown>(handler: MessageHandler<TBody, TResult>, options?: ServeMessageOptions): (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 MessageContext, type MessageHandler, 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 ServeMessageOptions, type ServeOptions, type StatusResponse, type StepRetryOptions, type StepType, type TriggerOptions, type TriggerResponse, type WaitForEventOptions, type WorkflowContext, type WorkflowContextOptions, type WorkflowHandler, WorkflowPausedError, type WorkflowRun, type WorkflowRunStatus, type WorkflowStep, WorkflowsAPI, createWorkflowContext, serve, serveMessage };

package/dist/index.js

@@ -115,12 +115,12 @@ var MessagesAPI = class extends BaseClient {
   /**
    * Get message details and delivery history
    *
-   * @param messageId - The message ID (e.g., "msg_abc123...")
+   * @param messageId - The message ID (e.g., "abc123...")
    * @returns Full message details including delivery logs
    *
    * @example
    * ```typescript
-   * const message = await qb.messages.get("msg_abc123");
+   * const message = await qb.messages.get("abc123");
    * console.log(message.status); // "completed" | "pending" | "failed"
    * console.log(message.deliveryLogs); // Delivery attempt history
    * ```
@@ -164,7 +164,10 @@ var MessagesAPI = class extends BaseClient {
    * ```
    */
   async cancel(messageId) {
-    return this.request("DELETE", `/messages/${messageId}`);
+    return this.request(
+      "DELETE",
+      `/messages/${messageId}`
+    );
   }
   /**
    * Publish a message and wait for delivery completion
@@ -186,9 +189,18 @@ var MessagesAPI = class extends BaseClient {
    * ```
    */
   async publishAndWait(destination, body, options) {
-    const { pollIntervalMs = 1e3, timeoutMs = 6e4, ...publishOptions } = options || {};
+    const {
+      pollIntervalMs = 1e3,
+      timeoutMs = 6e4,
+      ...publishOptions
+    } = options || {};
     const { messageId } = await this.publish(destination, body, publishOptions);
-    const terminalStates = ["completed", "failed", "cancelled", "dlq"];
+    const terminalStates = [
+      "completed",
+      "failed",
+      "cancelled",
+      "dlq"
+    ];
     const startTime = Date.now();
     while (Date.now() - startTime < timeoutMs) {
       const message = await this.get(messageId);
@@ -197,7 +209,9 @@ var MessagesAPI = class extends BaseClient {
       }
       await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
     }
-    throw new Error(`Message ${messageId} did not complete within ${timeoutMs}ms`);
+    throw new Error(
+      `Message ${messageId} did not complete within ${timeoutMs}ms`
+    );
   }
 };
 
@@ -1257,6 +1271,75 @@ function verifySignature(body, signature, secret) {
     return false;
   }
 }
+
+// src/serve-message.ts
+import { createHmac as createHmac2, timingSafeEqual as timingSafeEqual2 } from "crypto";
+function serveMessage(handler, options) {
+  return async (request) => {
+    try {
+      if (options?.signingSecret) {
+        const signature = request.headers.get("X-QueueBear-Signature");
+        const bodyText = await request.clone().text();
+        if (!verifySignature2(bodyText, signature, options.signingSecret)) {
+          return new Response(JSON.stringify({ error: "Invalid signature" }), {
+            status: 401,
+            headers: { "Content-Type": "application/json" }
+          });
+        }
+      }
+      const messageId = request.headers.get("X-QueueBear-Message-Id") || void 0;
+      const attemptNumber = parseInt(
+        request.headers.get("X-QueueBear-Retry-Count") || "0",
+        10
+      );
+      const body = await request.json();
+      const context = {
+        body,
+        messageId,
+        attemptNumber,
+        headers: Object.fromEntries(request.headers.entries())
+      };
+      const result = await handler(context);
+      return new Response(JSON.stringify({ success: true, result }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" }
+      });
+    } catch (error) {
+      console.error("[serveMessage] Error:", error);
+      return new Response(
+        JSON.stringify({
+          error: error instanceof Error ? error.message : "Unknown error"
+        }),
+        {
+          status: 500,
+          headers: { "Content-Type": "application/json" }
+        }
+      );
+    }
+  };
+}
+function verifySignature2(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 = createHmac2("sha256", secret).update(payload).digest("hex");
+  try {
+    return timingSafeEqual2(Buffer.from(parts.v1), Buffer.from(expected));
+  } catch {
+    return false;
+  }
+}
 export {
   DLQAPI,
   MessagesAPI,
@@ -1267,5 +1350,6 @@ export {
   WorkflowPausedError,
   WorkflowsAPI,
   createWorkflowContext,
-  serve
+  serve,
+  serveMessage
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "queuebear",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "QueueBear SDK for message queues, scheduled jobs, and durable workflows",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,13 +18,12 @@
     "type-check": "tsc --noEmit",
     "clean": "rm -rf dist"
   },
-  "dependencies": {},
   "devDependencies": {
     "@types/node": "^22.10.2",
     "tsup": "^8.3.5",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.16"
   },
-  "peerDependencies": {},
   "files": [
     "dist"
   ],