@clocknext/sdk 0.7.0 → 0.10.0

package/README.md

@@ -41,7 +41,16 @@ await cnk.flush();
 ## Recording signals
 
 There are three signal types, matching ClockNext's billable primitives. Each has
-a typed helper that enforces the right required fields at compile time.
+a typed helper that enforces the right required fields at compile time, and each
+posts to **its own route** — `/api/v1/signal/credit`, `/signal/wallet`,
+`/signal/outcome`. The signal's `type` is what picks that route; from 0.10 it is
+no longer sent in the body.
+
+> **Migrating from 0.9 or earlier?** Your calling code does not change — same
+> methods, same arguments. What changed is the wire: the SDK now targets the
+> `/api/v1/signal/*` family instead of the deprecated `POST /api/v1/usage`, and
+> the `metric` field is now `composite` (see [Composites](#composites)). Bump the
+> package and you are migrated.
 
 `model` is always the **catalog model id** enabled in your org (matched
 case-insensitively against `OrgModel.modelId`). Credits and outcomes are
@@ -76,23 +85,54 @@ await cnk.signals.outcome({ customerId, model, agentKey: "resolved_ticket.verify
 await cnk.signals.outcome({ customerId, model, agentKey: "resolved_ticket.resolve", runId, complete: true, tokens: { input: 500, output: 200 } });
 ```
 
-### Pricing metrics
+### Composites
 
-Tag any credit or outcome signal with a **pricing metric** for reporting. `ref`
-is the metric's ref ID (Settings → Pricing metrics) and `value` is your own
-correlation id; the metric rolls usage up one row per distinct value.
+A **composite** bundles several credits / outcomes / units and is priced and
+billed as one thing. Tag a signal with `composite` to group it into one
+*occurrence* — `ref` is the composite's ref ID and `value` is your own
+correlation id for that occurrence (a session, a call, a job):
 
 ```ts
 await cnk.signals.credit({
   customerId, model: "llama-3.3-70b-versatile", agentKey: "api_credit",
   tokens: { input: 1200, output: 340 },
-  metric: { ref: "voice_ai", value: "call_5f3a" },
+  composite: { ref: "voice_ai", value: "call_5f3a" },
 });
 ```
 
-Metric tags are **reporting only** — they never change what's billed, a tag that
-names no live metric is silently ignored, and a bad tag never fails the signal.
-Tags on wallet signals are ignored.
+An occurrence opens on the first tagged signal and costs nothing. **Closing it
+is what bills it** — one charge for the bundle, however many signals it
+contained:
+
+```ts
+await cnk.signals.completeComposite({
+  customerId,
+  composite: { ref: "voice_ai", value: "call_5f3a" },
+});
+```
+
+Only your code knows when the work ended, so closing is a declaration, not
+something ClockNext infers from which signals have arrived: tagged signals may
+arrive in any order and the occurrence stays open and unbilled until you say
+otherwise. Put the call on the line before your own `return`.
+
+An **outcome never needs it** — its own `complete: true` closes its run and the
+matching occurrence together. Credits and units have no "done" signal of their
+own, so this is theirs.
+
+Closing twice is safe (`ALREADY_COMPLETED`, and it cannot bill again), and so is
+closing *early* — before every entitlement in the bundle has reported, or while
+a prepaid slot pool is full: the server parks the request and applies it when
+the blocker clears, rather than failing it.
+
+A tag that names no live composite is ignored and never fails the signal — the
+signal carries money, the tag only decides what it is grouped under. Tags on
+wallet signals are ignored.
+
+> **Renamed in 0.10.** This field was called `metric` and was documented as
+> "reporting only, never changes what's billed". That was wrong: where the plan
+> sells the composite, the occurrence is the billable unit. Rename `metric:` to
+> `composite:` — the shape (`{ ref, value }`) is unchanged.
 
 ### Async vs sync
 
@@ -102,21 +142,31 @@ 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.
+> own POST to its own `/api/v1/signal/*` route; 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:
+To await the request itself (rather than buffering it), either:
 
 ```ts
 // per call
 const res = await cnk.signals.credit({ … }, { wait: true });
-console.log(res.usageLog);
 
 // or globally
 const cnk = new ClockNext({ apiKey, mode: "sync" });
 ```
 
+> **Awaiting is not the same as billed.** Where the server has a durable queue
+> configured it answers `202` and prices the signal in a worker, so you get
+> `{ queued: true, messageId, usageLog: null }` — accepted, not yet recorded, and
+> validated only later (a bad `agentKey` is dropped there, silently). Only when
+> the server prices inline do you get `{ queued: false, usageLog }`. Branch on
+> `queued`; never assume `usageLog` is populated.
+>
+> To validate and price a signal synchronously, use `signals.verify()` (a dry
+> run — it always returns the projected log). To confirm a real signal landed,
+> read it back with `signals.list({ customerId })`.
+
 > In `async` mode, server-side rejections (e.g. insufficient allowance, `422`)
 > surface via the `onError` hook or `flush()`, not from the `track()` call.
 
@@ -150,7 +200,7 @@ const cnk = new ClockNext({ apiKey, mode: "sync" });
 const c   = await cnk.customers.create({ name: "Acme", email: "ops@acme.com" });
 const one = await cnk.customers.get(c.id);
 const page = await cnk.customers.list({ limit: 50, q: "ac" });
-await cnk.customers.update(c.id, { notes: "VIP" });
+await cnk.customers.update(c.id, { legalName: "Acme Inc." });
 await cnk.customers.delete(c.id);
 
 // iterate every customer (auto-follows the cursor)
@@ -166,7 +216,7 @@ await cnk.customers.revenue(c.id, { range: "30d" });
 ### Members
 
 ```ts
-await cnk.customers.addMember(c.id, { name: "Alice", role: "ADMIN", email: "alice@acme.com" });
+await cnk.customers.addMember(c.id, { name: "Alice", 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);
@@ -230,9 +280,12 @@ Define the billable *types*; record usage against them with `signals.*`.
 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
+// outcome type — a multi-step workflow. TWO kinds of agentKey, both required and
+// both unique per org: the outcome's own (its identity) and each step's (what
+// signals.outcome() reports against). They are separate namespaces.
 await cnk.outcomes.create({
   name: "Resolved ticket",
+  agentKey: "resolved_ticket",
   basePrice: 1, marginPercent: 20, pricePerOutcome: 2,
   steps: [{ name: "Triage", agentKey: "resolved_ticket.triage", basePrice: 0.5 }],
 });
@@ -243,13 +296,35 @@ await cnk.units.create({ name: "Seats", agentKey: "seats", pricingType: "FLAT",
 
 ### Unit metering
 
-Record a unit event (no tokens) and read a customer's unit balances:
+Record a unit event (no tokens, no model) and read a customer's unit balances:
 
 ```ts
 await cnk.signals.unit({ customerId: c.id, agentKey: "seats" });
+
+// several at once, instead of N separate calls
+await cnk.signals.unit({ customerId: c.id, agentKey: "seats", quantity: 3 });
+
+// part of a composite, and safe to retry
+await cnk.signals.unit({
+  customerId: c.id, agentKey: "seats",
+  composite: { ref: "voice_ai", value: "call_5f3a" },
+  idempotencyKey: `seats:${requestId}`,
+});
+
 await cnk.signals.unitUsage({ customerId: c.id });
 ```
 
+`quantity` defaults to 1. On a prepaid (ADVANCE) plan the draw is
+all-or-nothing: asking for more than remains is refused in full rather than
+partially filled.
+
+> **Changed in 0.10.** `signals.unit()` moved to `POST /api/v1/signal/unit`,
+> which is **durable** (the report is written down before it is priced, so a
+> failure parks for retry instead of losing a billable event) and **idempotent**
+> (on the old route a retried report drew the balance down twice). Because it can
+> now answer `202`, this resolves `{ queued, unitUsage, rawId }` rather than a
+> bare `{ unitUsage }` — branch on `queued`, don't assume `unitUsage`.
+
 ## Webhooks
 
 Threshold alerts — at most one per kind (`CREDIT` / `OUTCOME` / `WALLET`):

package/dist/index.cjs

@@ -121,7 +121,8 @@ var Flusher = class {
     try {
       await this.transport.request({
         method: "POST",
-        path: "/api/v1/usage",
+        // Per-item, not per-Flusher: one route per meter. See `QueuedSignal`.
+        path: item.path,
         body: item.body,
         // Best-effort metering opts into retries on transient failures.
         retry: true
@@ -229,7 +230,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.7.0" ;
+var SDK_VERSION = "0.10.0" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -324,6 +325,36 @@ var Transport = class {
   }
 };
 
+// src/resources/composites.ts
+var Composites = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /** List composites. Pass `{ active: true }` for only the ones a signal can
+   *  still be tagged with — the default list INCLUDES archived ones, which
+   *  keep every row they already own. */
+  async list(params = {}) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: "/api/v1/composites",
+      query: {
+        active: params.active === void 0 ? void 0 : String(params.active)
+      }
+    });
+    return res.composites;
+  }
+  /** Create a composite. `POST /api/v1/composites`. */
+  async create(input) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: "/api/v1/composites",
+      body: input
+    });
+    return res.composite;
+  }
+};
+
 // src/resources/credits.ts
 var Credits = class {
   constructor(transport) {
@@ -506,7 +537,7 @@ var Customers = class {
     });
     return res.members;
   }
-  /** Add a member to a customer. Duplicate `employeeId` → ConflictError. */
+  /** Add a member to a customer. Duplicate `email` → ConflictError. */
   async addMember(id, input) {
     const res = await this.transport.request({
       method: "POST",
@@ -515,7 +546,7 @@ var Customers = class {
     });
     return res.member;
   }
-  /** Update a member's profile (role is fixed). `PATCH …/:id/members/:memberId`. */
+  /** Update a member's profile. Duplicate `email` → ConflictError. `PATCH …/:id/members/:memberId`. */
   async updateMember(id, memberId, input) {
     const res = await this.transport.request({
       method: "PATCH",
@@ -524,12 +555,13 @@ var Customers = class {
     });
     return res.member;
   }
-  /** Remove a member from a customer. `DELETE …/:id/members/:memberId`. */
+  /** Remove a member from a customer, returning who was removed. `DELETE …/:id/members/:memberId`. */
   async removeMember(id, memberId) {
-    await this.transport.request({
+    const res = await this.transport.request({
       method: "DELETE",
       path: `/api/v1/customers/${encodeURIComponent(id)}/members/${encodeURIComponent(memberId)}`
     });
+    return res.member;
   }
   // --- Wallet & billing config --------------------------------------------
   /** The customer's wallet balance + transactions. `GET …/:id/wallet`. */
@@ -855,18 +887,28 @@ function newKey() {
 }
 
 // src/resources/signals.ts
+var SIGNAL_PATHS = {
+  credit: "/api/v1/signal/credit",
+  outcome: "/api/v1/signal/outcome",
+  wallet: "/api/v1/signal/wallet"
+};
+var UNIT_PATH = "/api/v1/signal/unit";
+var COMPOSITE_COMPLETE_PATH = "/api/v1/signal/composite/complete";
 function signalToWire(signal) {
+  const t = signal.tokens;
   const body = {
     customerId: signal.customerId,
-    type: signal.type,
-    model: signal.model
+    // `usage` is required on all three model-priced kinds. input/output are
+    // always sent; `cacheTokens` only when provided (the server defaults 0).
+    usage: {
+      model: signal.model,
+      inputTokens: t.input,
+      outputTokens: t.output,
+      ...t.cache != null ? { cacheTokens: t.cache } : {}
+    }
   };
   if (signal.member) body.member = signal.member;
   if (signal.custom) body.custom = signal.custom;
-  const t = signal.tokens;
-  body.inputTokens = t.input;
-  body.outputTokens = t.output;
-  if (t.cache != null) body.cacheTokens = t.cache;
   if (signal.type === "credit" || signal.type === "outcome") {
     body.agentKey = signal.agentKey;
   }
@@ -874,12 +916,18 @@ function signalToWire(signal) {
     body.runId = signal.runId;
     if (signal.complete != null) body.complete = signal.complete;
   }
-  if (signal.type !== "wallet" && signal.metric) {
-    body[signal.metric.ref] = signal.metric.value;
+  if (signal.type !== "wallet" && signal.composite) {
+    body.composite = { [signal.composite.ref]: signal.composite.value };
   }
   if (signal.idempotencyKey) body.idempotencyKey = signal.idempotencyKey;
   return body;
 }
+function handles(res) {
+  return {
+    ...res.messageId != null ? { messageId: res.messageId } : {},
+    ...res.rawId != null ? { rawId: res.rawId } : {}
+  };
+}
 var Signals = class {
   constructor(transport, flusher, cfg) {
     this.transport = transport;
@@ -889,56 +937,79 @@ var Signals = class {
   transport;
   flusher;
   cfg;
+  /**
+   * Record one usage signal, to the route its `type` selects:
+   * `POST /api/v1/signal/credit` | `/signal/outcome` | `/signal/wallet`.
+   *
+   * Returns as soon as the signal is buffered (async mode) or the request has
+   * been answered (`{ wait: true }` / sync mode). See {@link TrackResult}: a
+   * resolved promise means "accepted", which is not the same as "billed".
+   */
   async track(signal, opts = {}) {
     const body = signalToWire(signal);
     if (body.idempotencyKey == null) body.idempotencyKey = newKey();
+    const path = SIGNAL_PATHS[signal.type];
     const sendNow = opts.wait || this.cfg.mode === "sync";
     if (!sendNow) {
-      this.flusher.enqueue({ body, signal });
+      this.flusher.enqueue({ path, body, signal });
       return { queued: true };
     }
     const res = await this.transport.request({
       method: "POST",
-      path: "/api/v1/usage",
+      path,
       body,
       // Best-effort metering opts into retries on transient failures.
       retry: true
     });
     return {
-      queued: false,
-      usageLog: res.usageLog ?? null
+      queued: res.queued === true,
+      usageLog: res.usageLog ?? null,
+      ...handles(res)
     };
   }
   /**
    * Validate + price a signal WITHOUT recording it (server `dryRun`). Returns
    * the projected usage log so an integration can preflight before sending real
    * traffic — no inbox row, wallet / outcome writes, or webhooks fire.
+   *
+   * Only the model-priced kinds support this. A dry run is not offered for unit
+   * reports or composite completions, and the server REJECTS the flag on those
+   * routes rather than accepting and ignoring it — which is why there is no
+   * dry-run path through `unit()` or `completeComposite()`.
    */
   async verify(signal) {
     const body = signalToWire(signal);
     body.dryRun = true;
     const res = await this.transport.request({
       method: "POST",
-      path: "/api/v1/usage",
+      path: SIGNAL_PATHS[signal.type],
       body,
       // A dry run writes nothing, so it is always safe to retry.
       retry: true
     });
     return res.usageLog ?? null;
   }
-  /** Meter a named credit. */
+  /** Meter a named credit. `POST /api/v1/signal/credit`. */
   credit(input, opts) {
     return this.track({ ...input, type: "credit" }, opts);
   }
-  /** Debit the customer's wallet at model cost. */
+  /** Debit the customer's wallet at model cost. `POST /api/v1/signal/wallet`. */
   wallet(input, opts) {
     return this.track({ ...input, type: "wallet" }, opts);
   }
-  /** Advance one step of an outcome workflow. */
+  /** Advance one step of an outcome workflow. `POST /api/v1/signal/outcome`. */
   outcome(input, opts) {
     return this.track({ ...input, type: "outcome" }, opts);
   }
-  /** Recent usage logs + totals for a customer. `GET /api/v1/usage`. */
+  /**
+   * Recent usage logs + totals for a customer. `GET /api/v1/usage`.
+   *
+   * Still the legacy path, deliberately. The `/api/v1/signal/*` family is
+   * POST-only — it replaced how usage is INGESTED, not how it is read — so
+   * `GET /api/v1/usage` has no successor and is not deprecated. It is also the
+   * only way to prove a signal landed, which matters more now that ingestion
+   * answers `202` for everything.
+   */
   async list(params) {
     const res = await this.transport.request({
       method: "GET",
@@ -950,22 +1021,94 @@ var Signals = class {
   /**
    * Record one unit-metered event (a fixed-price meter with no tokens),
    * addressed to a catalog unit by its `agentKey`. Sent immediately — unit
-   * events are not buffered. `POST /api/v1/units`.
+   * events are not buffered. `POST /api/v1/signal/unit`.
+   *
+   * Two things changed with the move off `POST /api/v1/units`, and both show up
+   * in the return type. The route is now durable (the report lands in an inbox
+   * before it is priced, so a failure parks as Pending and can be retried
+   * instead of losing a billable event) and it answers `202` when it queues —
+   * so this resolves {@link UnitTrackResult}, not a bare `{ unitUsage }`.
+   * Branch on `queued`.
    */
   async unit(input) {
-    return this.transport.request({
+    const res = await this.transport.request({
       method: "POST",
-      path: "/api/v1/units",
+      path: UNIT_PATH,
       body: {
         customerId: input.customerId,
         agentKey: input.agentKey,
-        ...input.member ? { member: input.member } : {}
+        ...input.quantity != null ? { quantity: input.quantity } : {},
+        ...input.member ? { member: input.member } : {},
+        ...input.composite ? { composite: { [input.composite.ref]: input.composite.value } } : {},
+        // Assigned HERE, before the send, so the SAME key rides every
+        // transport-level retry below. Without it a single 500 followed by a
+        // success is TWO un-keyed reports, and the server dedups on the key —
+        // so it bills the allowance down twice, up to `retry.maxAttempts`
+        // times. The route gained idempotency precisely to stop that; not
+        // using it by default would leave the double-charge reachable from the
+        // client instead of the server.
+        idempotencyKey: input.idempotencyKey ?? newKey()
       },
       // Best-effort metering opts into retries on transient failures.
       retry: true
     });
+    return {
+      queued: res.queued === true,
+      unitUsage: res.unitUsage ?? null,
+      ...handles(res)
+    };
   }
-  /** A customer's unit balances + recent unit events. `GET /api/v1/units`. */
+  /**
+   * Close ONE occurrence of a composite — a distinct tag value.
+   * `POST /api/v1/signal/composite/complete`.
+   *
+   * A composite bundles several credits / outcomes / units and is billed as one
+   * thing. The occurrence opens on the first tagged signal and costs nothing;
+   * this call is the moment it is billed. Only your code knows when the
+   * workflow ended, so this is a DECLARATION, not a hint: tagged signals may
+   * arrive in any order and the occurrence stays open and unbilled until you
+   * say otherwise. Put it on the line before your own `return`.
+   *
+   * An OUTCOME never needs this — its own `complete: true` closes its run and
+   * the matching occurrence together. Credits and units have no "done" signal
+   * of their own, so this is theirs.
+   *
+   * Closing twice is safe: the second call answers `ALREADY_COMPLETED` and
+   * cannot bill again. Calling it EARLY is also safe — before every entitlement
+   * the composite is restricted to has reported, or while an ADVANCE pool is
+   * full — the server parks the ping and applies it when the blocker clears,
+   * rather than failing it.
+   */
+  async completeComposite(input) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: COMPOSITE_COMPLETE_PATH,
+      body: {
+        customerId: input.customerId,
+        composite: { [input.composite.ref]: input.composite.value },
+        // Auto-assigned like the others. A retry here could not double-BILL
+        // even without it — closing a closed occurrence is a server-side
+        // no-op — but that safety comes from occurrence-level dedup, not from
+        // idempotency, and an un-keyed replay still writes a redundant inbox
+        // row. Keying it collapses the retry into the one attempt it is.
+        idempotencyKey: input.idempotencyKey ?? newKey()
+      },
+      retry: true
+    });
+    return {
+      queued: res.queued === true,
+      ...res.status != null ? { status: res.status } : {},
+      ...res.composite !== void 0 ? { composite: res.composite } : {},
+      ...res.value !== void 0 ? { value: res.value } : {},
+      ...handles(res)
+    };
+  }
+  /**
+   * A customer's unit balances + recent unit events. `GET /api/v1/units`.
+   *
+   * Legacy path for the same reason as {@link list}: the signal family is
+   * POST-only, so the read side has no successor and is not deprecated.
+   */
   unitUsage(params) {
     return this.transport.request({
       method: "GET",
@@ -1109,6 +1252,8 @@ var ClockNext = class {
   payments;
   /** Manage the credit-type catalog. */
   credits;
+  /** Manage the composite catalog — bundles billed as one thing. */
+  composites;
   /** Manage the outcome-type catalog. */
   outcomes;
   /** Manage the unit-type catalog. */
@@ -1137,6 +1282,7 @@ var ClockNext = class {
     this.invoices = new Invoices(transport);
     this.payments = new Payments(transport);
     this.credits = new Credits(transport);
+    this.composites = new Composites(transport);
     this.outcomes = new Outcomes(transport);
     this.units = new Units(transport);
     this.webhooks = new Webhooks(transport);