queuebear 0.1.3 → 0.1.4

package/README.md

@@ -491,6 +491,76 @@ 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.
+
+### Using ngrok (Recommended)
+
+[ngrok](https://ngrok.com) provides stable URLs and a built-in request inspector.
+
+**1. Install and authenticate:**
+
+```bash
+# Install
+brew install ngrok  # or download from ngrok.com/download
+
+# Authenticate (free account required)
+ngrok config add-authtoken YOUR_AUTH_TOKEN
+```
+
+**2. Start the tunnel:**
+
+```bash
+ngrok http 3000
+```
+
+**3. Use the forwarding URL:**
+
+```typescript
+// Use ngrok URL instead of localhost
+await qb.messages.publish("https://abc123.ngrok.io/api/webhooks", {
+  event: "user.created",
+  userId: "123"
+});
+
+// Works for workflows too
+await qb.workflows.trigger(
+  "onboarding",
+  "https://abc123.ngrok.io/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)
+
+---
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "queuebear",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "QueueBear SDK for message queues, scheduled jobs, and durable workflows",
   "type": "module",
   "main": "./dist/index.js",