@clocknext/sdk 0.1.0 → 0.4.0

package/README.md

@@ -1,7 +1,8 @@
 # @clocknext/sdk
 
 Official ClockNext SDK for Node/TypeScript. Record **usage signals** and manage
-**customers** from your backend.
+**plans, purchases, invoices, customers, catalogs, and billing** from your
+backend — full coverage of the ClockNext `/api/v1` surface.
 
 > **Server-side only.** Your `cnk_…` API key has org-wide write access — never
 > ship it to a browser. For embedding the customer portal in a browser, mint a
@@ -13,7 +14,9 @@ Official ClockNext SDK for Node/TypeScript. Record **usage signals** and manage
 npm install @clocknext/sdk
 ```
 
-Requires Node ≥ 18 (native `fetch`). Zero runtime dependencies.
+Requires Node ≥ 18 (native `fetch`). Zero runtime dependencies. Uses only
+Web-standard `fetch` and `crypto`, so it also runs on edge runtimes (Cloudflare
+Workers, Vercel Edge, Deno, Bun).
 
 ## Quick start
 
@@ -25,7 +28,7 @@ const cnk = new ClockNext({ apiKey: process.env.CLOCKNEXT_API_KEY! });
 await cnk.signals.credit({
   customerId: "cus_123",
   model: "llama-3.3-70b-versatile", // catalog model id (OrgModel.modelId)
-  key: "api_credit",                // the credit's stable key
+  agentKey: "api_credit",           // the credit's stable agent key
   member: "alice@acme.com",
   tokens: { input: 1200, output: 340, cache: 0 },
   custom: { feature: "summarize" },
@@ -42,29 +45,31 @@ a typed helper that enforces the right required fields at compile time.
 
 `model` is always the **catalog model id** enabled in your org (matched
 case-insensitively against `OrgModel.modelId`). Credits and outcomes are
-referenced by their **stable `key`** (assigned when you create the credit /
+referenced by their **stable `agentKey`** (assigned when you create the credit /
 outcome step), not by display name.
 
 ```ts
-// Credit — metered against a credit (by key); charged at the model's real cost + your margin
-await cnk.signals.credit({ customerId, model: "llama-3.3-70b-versatile", key: "api_credit", tokens: { input: 1200, output: 340 } });
+// Credit — metered against a credit (by agentKey); charged at the model's real cost + your margin
+await cnk.signals.credit({ customerId, model: "llama-3.3-70b-versatile", agentKey: "api_credit", tokens: { input: 1200, output: 340 } });
 
 // Wallet — debits the customer's USD wallet at model cost
 await cnk.signals.wallet({ customerId, model: "openai/gpt-oss-120b", tokens: { input: 800, output: 5000 } });
 
-// Outcome — advances one step of a workflow (key = the OutcomeStep's key)
-await cnk.signals.outcome({ customerId, model: "llama-3.3-70b-versatile", key: "resolved_ticket.triage" });
+// Outcome — advances one step of a workflow (agentKey = the OutcomeStep's agent key)
+await cnk.signals.outcome({ customerId, model: "llama-3.3-70b-versatile", agentKey: "resolved_ticket.triage" });
 ```
 
-> Usage `/api/v1/usage` responses use the envelope
-> `{ statusCode, statusDetail, result }`; customer endpoints currently use
-> `{ ok, … }`. The SDK unwraps both for you.
-
 ### Async vs sync
 
 By default the client is in **`async`** mode: `track()` buffers the signal and
-returns immediately (`{ queued: true }`), and a background flusher sends batches
-on a size/interval trigger. This keeps billing telemetry off your LLM hot path.
+returns immediately (`{ queued: true }`), and a background flusher drains the
+buffer on a size/interval trigger. This keeps billing telemetry off your LLM hot
+path.
+
+> **"Batching" here means timing, not a bulk request.** Each signal is still its
+> own `POST /api/v1/usage`; the flusher just groups *when* sends happen and caps
+> how many run at once (`batch.maxConcurrency`). There is no single bulk-ingest
+> call, so size your request budget per signal.
 
 To get the computed result back (and any real-time allowance rejection), either:
 
@@ -82,15 +87,27 @@ const cnk = new ClockNext({ apiKey, mode: "sync" });
 
 ### Reliability
 
-- **Idempotency:** every signal carries an idempotency key (auto-generated once,
-  reused across retries) so a transport retry can't double-count. Pass your own
-  `idempotencyKey` for deterministic, cross-process dedup. *(Server-side dedup
-  enforcement is rolling out — see the SDK plan.)*
 - **Retries:** transient failures (network, timeout, `408/409/429/5xx`) are
-  retried with exponential backoff + jitter, honoring `Retry-After`. Deterministic
-  `4xx` (`400/401/404/422`) are never retried.
+  retried with exponential backoff + equal jitter, honoring `Retry-After`.
+  Deterministic `4xx` (`400/401/404/422`) are never retried.
+- **Replay safety:** reads (`GET`) and `DELETE` are retried automatically. Metering
+  signals (`signals.*`) opt into retries too — made safe by the idempotency key
+  below. Other non-idempotent writes — e.g. `customers.create`, `plans.create`,
+  `purchases.create` — are *not* auto-retried, so a transient blip can never
+  create a duplicate.
+- **Idempotency:** every metering signal carries an idempotency key — auto-
+  generated per signal, or pass your own via `idempotencyKey` on the signal —
+  reused across all retries, so a retried send is **deduplicated by the server**
+  instead of double-counted. Pass a stable key (e.g. your own event id) to also
+  dedup across process restarts or at-least-once redelivery.
 - **Flushing:** call `await cnk.flush()` before a serverless return, and
   `await cnk.close()` on graceful shutdown to drain the buffer.
+- **Durability:** the async buffer is **in-memory**. A signal already accepted
+  by the server is durable on the server side, but signals still buffered when a
+  process crashes (before send) are lost. For zero-loss-before-receipt, either
+  run in `sync` mode (or `{ wait: true }`) so the send completes before your
+  code continues, or call `flush()`/`close()` at the right boundaries. A
+  pluggable before-send persistence store is not yet available.
 
 ## Customers
 
@@ -111,11 +128,108 @@ await cnk.customers.plan(c.id);
 await cnk.customers.revenue(c.id, { range: "30d" });
 ```
 
+### Members
+
+```ts
+await cnk.customers.addMember(c.id, { name: "Alice", role: "ADMIN", email: "alice@acme.com" });
+const members = await cnk.customers.listMembers(c.id);
+await cnk.customers.updateMember(c.id, members[0].id, { name: "Alice R." });
+await cnk.customers.removeMember(c.id, members[0].id);
+```
+
+### Wallet & billing config
+
+```ts
+// wallet
+await cnk.customers.wallet(c.id, { limit: 50 });               // { balanceUsd, transactions }
+await cnk.customers.addWalletEntry(c.id, { type: "CREDIT", amount: 25 }); // top up (DEBIT to spend)
+
+// billing config — currency is set through update()
+await cnk.customers.update(c.id, { currencyCode: "EUR" });
+
+// grant / claw back balances (delta is signed)
+await cnk.customers.adjustCredit(c.id, { creditId: "cr_1", delta: 100 });
+const { remaining } = await cnk.customers.adjustOutcome(c.id, { outcomeId: "out_1", delta: -1 });
+await cnk.customers.adjustUnit(c.id, { unitId: "un_1", delta: 5 });
+```
+
+## Plans & purchases
+
+```ts
+// define a plan
+const plan = await cnk.plans.create({
+  name: "Pro",
+  billingCycle: "MONTHLY",
+  currencyCode: "USD",
+  components: [
+    { type: "WALLET", billingMode: "ADVANCE", amount: 100 },
+    { type: "CREDIT", billingMode: "ADVANCE", creditId: "cr_1", quantity: 10_000 },
+  ],
+});
+await cnk.plans.list({ active: true });
+await cnk.plans.setActive(plan.id, false);
+
+// subscribe a customer (auto-cancels their existing active/scheduled purchase)
+const purchase = await cnk.purchases.create({ customerId: c.id, planId: plan.id });
+await cnk.purchases.setAutoPayment(purchase.id, false, { pauseReason: "trial" });
+await cnk.purchases.cancel(purchase.id);
+```
+
+## Invoices & payments (read-only)
+
+```ts
+const invoices = await cnk.invoices.list({ customerId: c.id, status: "OPEN" });
+const { invoice, plan } = await cnk.invoices.get(invoices[0].id);
+const { url } = await cnk.invoices.payLink(invoices[0].id); // hosted pay link (OPEN only)
+
+const payments = await cnk.payments.list({ customerId: c.id });
+await cnk.payments.get(payments[0].id); // id = the paid invoice id
+```
+
+## Catalogs: credits, outcomes, units
+
+Define the billable *types*; record usage against them with `signals.*`.
+
+```ts
+// credit type — signals.credit({ agentKey }) meters against it
+await cnk.credits.create({ name: "API", agentKey: "api_credit", basePrice: 1, marginPercent: 20, pricePerCredit: 0.01 });
+await cnk.credits.list({ active: true });
+
+// outcome type — a multi-step workflow; each step has its own agentKey
+await cnk.outcomes.create({
+  name: "Resolved ticket",
+  basePrice: 1, marginPercent: 20, pricePerOutcome: 2,
+  steps: [{ name: "Triage", agentKey: "resolved_ticket.triage", basePrice: 0.5 }],
+});
+
+// unit type — a quantity-priced meter (FLAT / SLAB / VOLUME)
+await cnk.units.create({ name: "Seats", agentKey: "seats", pricingType: "FLAT", flatPrice: 5 });
+```
+
+### Unit metering
+
+Record a unit event (no tokens) and read a customer's unit balances:
+
+```ts
+await cnk.signals.unit({ customerId: c.id, agentKey: "seats" });
+await cnk.signals.unitUsage({ customerId: c.id });
+```
+
+## Webhooks
+
+Threshold alerts — at most one per kind (`CREDIT` / `OUTCOME` / `WALLET`):
+
+```ts
+await cnk.webhooks.upsert({ kind: "WALLET", threshold: 10, url: "https://acme.com/hooks/clocknext" });
+await cnk.webhooks.list();
+await cnk.webhooks.delete("WALLET");
+```
+
 ## Customer portal token
 
 ```ts
 const { token, expiresAt } = await cnk.portal.createToken({ customerId: "cus_123", ttlSeconds: 600 });
-// render <iframe src={`https://app.clocknext.com/portal/embed?token=${token}`} />
+// render <iframe src={`https://payments.clocknext.com/portal/embed?token=${token}`} />
 ```
 
 ## Errors
@@ -137,14 +251,14 @@ try {
 `ValidationError (400)` · `AuthError (401)` · `NotFoundError (404)` ·
 `PlanError (422)` · `AllowanceError (422)` · `ConflictError (409)` ·
 `RateLimitError (429)` · `ServerError (5xx)` · `NetworkError` — all extend
-`ClockNextError` (`.status`, `.retryable`, `.idempotencyKey`).
+`ClockNextError` (`.status`, `.retryable`).
 
 ## Configuration
 
 ```ts
 new ClockNext({
   apiKey: "cnk_…",                 // required
-  baseUrl: "https://app.clocknext.com",
+  baseUrl: "https://payments.clocknext.com",
   mode: "async",                    // "async" | "sync"
   timeoutMs: 10_000,
   batch: { maxSize: 20, maxIntervalMs: 2000, maxConcurrency: 5, maxQueueSize: 10_000 },
@@ -156,6 +270,9 @@ new ClockNext({
 });
 ```
 
+Numeric options are validated: a negative or non-finite value (e.g. a bad
+`timeoutMs`) falls back to its default rather than silently breaking the client.
+
 ## License
 
 MIT