@nimbusnexus/webhooks-sdk 0.1.1 → 0.3.0

package/README.md

@@ -1,7 +1,8 @@
 # @nimbusnexus/webhooks-sdk (TypeScript)
 
-Official TypeScript SDK for **NimbusNexus Webhooks** — publish events, and verify the webhooks you
-receive. Zero runtime dependencies (uses the built-in `fetch` and `node:crypto`); Node ≥ 20.
+Official TypeScript SDK for **NimbusNexus Webhooks** — publish events, manage your endpoints / keys /
+deliveries, and verify the webhooks you receive. Zero runtime dependencies (uses the built-in `fetch`
+and `node:crypto`); Node ≥ 20.
 
 ```sh
 npm install @nimbusnexus/webhooks-sdk
@@ -43,6 +44,99 @@ try {
 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.
+
+**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
+dead-letter queue from code (needs an **admin**-scoped key). Management methods return the API's
+snake_case JSON through typed interfaces (`Endpoint`, `ApiKey`, `Delivery`, `Page<T>`); list methods
+return `{ items, next_offset }`; `deleteEndpoint` / `revokeApiKey` resolve to `void` (a `204`).
+
+```ts
+import { WebhookdClient } from "@nimbusnexus/webhooks-sdk";
+
+const wh = new WebhookdClient({ baseUrl: "https://webhooks.example.com", apiKey: "whsk_admin_…" });
+
+// --- Endpoints ---------------------------------------------------------------
+// Create a receiver — its signing secret is in the response exactly once, so persist it now.
+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.getEndpoint(endpointId);
+
+// PATCH — send only the keys you want to change (omitted = unchanged, null = cleared):
+await wh.updateEndpoint(endpointId, { max_attempts: 10, status: "disabled" });
+
+await wh.rotateEndpointSecret(endpointId);       // returns the new secret, once
+await wh.enableEndpoint(endpointId);             // recover an auto-disabled endpoint
+await wh.deleteEndpoint(endpointId);             // -> void (204)
+
+// --- API keys ----------------------------------------------------------------
+const key = await wh.createApiKey({ name: "ci-publisher", scope: "publish", expiresInDays: 90 });
+console.log(key.key);                            // shown once
+await wh.revokeApiKey(key.id);                   // -> void (204)
+
+// --- Deliveries / dead-letter recovery ---------------------------------------
+const dead = await wh.listDeliveries({ status: "dead" });
+for (const d of dead.items) await wh.redeliver(d.id);
+```
+
 ## Develop
 
 ```sh