@clocknext/sdk 0.6.0 → 0.8.0

package/README.md

@@ -55,10 +55,45 @@ await cnk.signals.credit({ customerId, model: "llama-3.3-70b-versatile", agentKe
 // 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 (agentKey = the OutcomeStep's agent key)
-await cnk.signals.outcome({ customerId, model: "llama-3.3-70b-versatile", agentKey: "resolved_ticket.triage" });
+// Outcome — one step of a run (agentKey = the OutcomeStep's agent key)
+await cnk.signals.outcome({ customerId, model: "llama-3.3-70b-versatile", agentKey: "resolved_ticket.triage", runId: "ticket_9021", tokens: { input: 600, output: 150 } });
 ```
 
+### Outcome runs
+
+An outcome is billed per **run**, not per step. Every signal for one run shares a
+`runId` (opaque — any id you can correlate, e.g. your ticket/session id), so a
+step can fire as many times as it needs to. The run bills **once**, when you mark
+the final step `complete: true` — completion is never inferred from step
+coverage. Sending `complete` twice is a safe no-op.
+
+```ts
+const runId = "ticket_9021";
+// each step of the run carries the same runId…
+await cnk.signals.outcome({ customerId, model, agentKey: "resolved_ticket.triage", runId, tokens: { input: 600, output: 150 } });
+await cnk.signals.outcome({ customerId, model, agentKey: "resolved_ticket.verify", runId, tokens: { input: 200, output: 80 } }); // may repeat
+// …and the last one closes (and bills) the run:
+await cnk.signals.outcome({ customerId, model, agentKey: "resolved_ticket.resolve", runId, complete: true, tokens: { input: 500, output: 200 } });
+```
+
+### Pricing metrics
+
+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.
+
+```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" },
+});
+```
+
+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.
+
 ### Async vs sync
 
 By default the client is in **`async`** mode: `track()` buffers the signal and
@@ -71,17 +106,27 @@ path.
 > 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.
 
@@ -195,9 +240,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 }],
 });

package/dist/index.cjs

@@ -229,7 +229,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.6.0" ;
+var SDK_VERSION = "0.8.0" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -870,6 +870,13 @@ function signalToWire(signal) {
   if (signal.type === "credit" || signal.type === "outcome") {
     body.agentKey = signal.agentKey;
   }
+  if (signal.type === "outcome") {
+    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.idempotencyKey) body.idempotencyKey = signal.idempotencyKey;
   return body;
 }
@@ -882,6 +889,13 @@ var Signals = class {
   transport;
   flusher;
   cfg;
+  /**
+   * Record one usage signal. `POST /api/v1/usage`.
+   *
+   * 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();
@@ -898,8 +912,9 @@ var Signals = class {
       retry: true
     });
     return {
-      queued: false,
-      usageLog: res.usageLog ?? null
+      queued: res.queued === true,
+      usageLog: res.usageLog ?? null,
+      ...res.messageId != null ? { messageId: res.messageId } : {}
     };
   }
   /**