queuebear 0.1.2 → 0.1.4

package/README.md

@@ -219,10 +219,9 @@ export const POST = serve<InputType>(async (context) => {
 
 **Options:**
 
-| Option          | Type     | Description                                            |
-| --------------- | -------- | ------------------------------------------------------ |
-| `signingSecret` | `string` | Secret to verify requests come from QueueBear          |
-| `baseUrl`       | `string` | Override QueueBear base URL (auto-detected if not set) |
+| Option          | Type     | Description                                   |
+| --------------- | -------- | --------------------------------------------- |
+| `signingSecret` | `string` | Secret to verify requests come from QueueBear |
 
 ### Framework Integration
 
@@ -492,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.2",
+  "version": "0.1.4",
   "description": "QueueBear SDK for message queues, scheduled jobs, and durable workflows",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,7 +42,7 @@
   ],
   "author": {
     "name": "Robert Marshall",
-    "email": "hell0@robertmarshall.dev",
+    "email": "hello@robertmarshall.dev",
     "url": "https://robertmarshall.dev"
   },
   "license": "MIT",