@journeybee/sdk 0.1.0 → 0.2.0

package/README.md

@@ -11,7 +11,14 @@ npm install @journeybee/sdk
 ## Quick Start
 
 ```typescript
-import { client, listPartners, getLead, createLead } from "@journeybee/sdk";
+import {
+  client,
+  createLogicalOperationId,
+  idempotencyHeaders,
+  listPartners,
+  getLead,
+  createLead,
+} from "@journeybee/sdk";
 
 // Configure once
 client.setConfig({
@@ -30,16 +37,32 @@ const { data: lead } = await getLead({
 });
 
 // Create a lead
-const { data: newLead } = await createLead({
+// Generate once before the first mutation. Keep it if the response is lost.
+const operationId = createLogicalOperationId();
+const createLeadOptions = {
+  headers: idempotencyHeaders(operationId),
   body: {
     first_name: "Jane",
     last_name: "Smith",
     email: "jane@acme.com",
     partnership_uuid: "partner-uuid",
   },
-});
+};
+const { data: newLead } = await createLead(createLeadOptions);
+
+// Lost-response retry: reuse the same operation id and exact request data
+// within the API's 24-hour Redis replay window.
+const retry = await createLead(createLeadOptions);
 ```
 
+The default SDK clients automatically add a fresh `Idempotency-Key` to every
+mutation (`POST`, `PUT`, `PATCH`, `DELETE`) without overwriting an explicit
+header. Use an explicit logical ID only when you need to retry a lost response.
+Journeybee replays terminal 4xx, 429, and 5xx responses too, and Redis/store
+failures fail closed. This is replay protection rather than a transaction with
+the business database: it cannot guarantee no duplicate after the 24-hour
+window or across a database/Redis crash boundary.
+
 ## Authentication
 
 Get your API key from **Settings > API Keys** in the Journeybee app.
@@ -56,9 +79,9 @@ client.setConfig({
 The default singleton is fine for single-tenant servers and CLI tools. For multi-tenant servers (one Node process handling multiple users) use `createClient` to build per-request clients instead of mutating the singleton:
 
 ```typescript
-import { createClient, createConfig, listPartners } from "@journeybee/sdk";
+import { createIdempotentClient, createConfig, listPartners } from "@journeybee/sdk";
 
-const userClient = createClient(
+const userClient = createIdempotentClient(
   createConfig({
     baseUrl: "https://api.journeybee.io/v1",
     auth: userApiKey,