@nimbusnexus/webhooks-sdk 0.2.0 → 0.4.0

package/README.md

@@ -35,15 +35,84 @@ try {
     { orderId: "ord_123", total: 4200 },
     { idempotencyKey: "order-123" }, // makes the publish safe to retry
   );
-  console.log(event.eventUid, event.deliveriesCreated);
+  console.log(event.eventUid, event.projectId, event.deliveriesCreated);
 } catch (e) {
   if (e instanceof WebhookdApiError) console.error(e.statusCode, e.code, e.message);
 }
 ```
 
+**Projects.** A project is addressed by its **id** (`prj_…`), not a slug. Omit `projectId` — as
+above — to publish into your workspace's **default** project; the server resolves it. Pass one only to
+target a specific project:
+
+```ts
+await wh.publish("order.created", { orderId: "ord_123" }, { projectId: "prj_3f9a…" });
+```
+
+The id is opaque and per-workspace, so there is no client-side sentinel for "the default project":
+leaving `projectId` unset omits the field entirely. The response (`event.projectId`) always carries
+the id the event actually landed in.
+
 Transient failures (network errors, `429`, `5xx`) are retried with backoff (a `429` honours
 `Retry-After`); other `4xx` throw `WebhookdApiError` carrying the `{error:{code,message}}` envelope.
 
+## Outbox / durable buffering (producers)
+
+`publish()` calls webhookd synchronously — if webhookd is unreachable it rejects and the event is
+lost. The **write-first outbox** decouples the two: `enqueue()` durably persists the event to a
+pluggable `Store` and resolves IMMEDIATELY (no network); `drain()` (or a background drainer) ships the
+buffered events later. Every send carries `Idempotency-Key = record.id`, so a re-drain after a crash
+or a lost response never double-publishes — webhookd dedupes. Delivery is **at-least-once**: nothing
+is lost while webhookd is down.
+
+```ts
+import { WebhookdClient, SqliteStore } from "@nimbusnexus/webhooks-sdk";
+
+// 1. Configure a durable store (survives process restarts; needs Node >= 22.5 for node:sqlite).
+const store = new SqliteStore("outbox.db");
+
+const wh = new WebhookdClient({
+  baseUrl: "https://webhooks.example.com",
+  apiKey: "whsk_…",
+  store,
+});
+
+// 2. enqueue() instead of publish() — writes to the store and resolves at once, NO network call.
+const { id } = await wh.enqueue("order.created", { orderId: "ord_123", total: 4200 });
+
+// 3a. Drain on demand (resolves to { sent, failed, remaining }):
+await wh.drain();
+
+// 3b. …or run a background drainer that calls drain() every 5s until you stop it.
+wh.startDrainer(5);
+// ... your app keeps enqueuing; the drainer ships in the background ...
+wh.stopDrainer();
+```
+
+**Idempotency guarantee.** `id` is the `idempotencyKey` you pass (or a generated UUID v4) and becomes
+the `Idempotency-Key` header on every delivery attempt for that record. If the process crashes after
+a send but before the response is recorded, the next `drain()` re-sends with the *same* key and
+webhookd returns the original event without re-fanning-out. A record that keeps failing is retried
+with capped exponential backoff up to `maxAttempts` (default 10), then parked **dead** (never retried
+again, retrievable via `store.listDead()`) and passed to the optional `onDead` callback.
+
+`enqueue` takes the same optional `projectId` as `publish` (omit it for the default project). It is
+persisted on the buffered record as a nullable `project_id` — `null` means "the workspace's default
+project", and `drain` then omits the field from the publish body.
+
+**Built-in stores** — pass one as `store` in `ClientOptions`:
+
+| Store | Durable? | Extra needed |
+| --- | --- | --- |
+| `MemoryStore` | No (in-process) | — (built-in) |
+| `FileStore(dir)` | Yes (per-record JSON files) | — (built-in) |
+| `SqliteStore(path)` | Yes (transactional) | — (built-in `node:sqlite`, Node ≥ 22.5) |
+| `RedisStore({ url })` | Yes | `npm install redis` |
+| `PostgresStore({ connectionString })` | Yes | `npm install pg` |
+
+The core SDK stays zero-dependency; `redis` / `pg` are `optionalDependencies`, imported lazily only
+when you construct `RedisStore` / `PostgresStore`.
+
 ## Manage endpoints, keys & deliveries (operators)
 
 The same client wraps the control-plane API — register receivers, mint keys, and drain the
@@ -58,13 +127,15 @@ const wh = new WebhookdClient({ baseUrl: "https://webhooks.example.com", apiKey:
 
 // --- Endpoints ---------------------------------------------------------------
 // Create a receiver — its signing secret is in the response exactly once, so persist it now.
+// Omit `projectId` (here and on listEndpoints) for the workspace's default project.
 const ep = await wh.createEndpoint("https://your-app.example/webhooks", {
   subscriptions: [{ match_kind: "prefix", pattern: "order." }],
   description: "orders service",
 });
 const { id: endpointId, secret: signingSecret } = ep;
 
-await wh.listEndpoints({ environment: "prod" }); // { items, next_offset }
+await wh.listEndpoints();                          // default project — { items, next_offset }
+await wh.listEndpoints({ projectId: "prj_3f9a…" }); // a specific project, by id
 await wh.getEndpoint(endpointId);
 
 // PATCH — send only the keys you want to change (omitted = unchanged, null = cleared):