@clocknext/sdk 0.12.0 → 0.13.0

package/README.md

@@ -46,17 +46,37 @@ A signal is silently discarded if any of these is true:
 | a required field is missing | see the tables below |
 | the allowance is exhausted | top up with `customers.adjustCredit()` etc. |
 
-Two things follow:
-
-- **Always pass `onError`.** It is the only channel a rejected signal has. The
-  SDK logs to `console.error` by default rather than staying silent, but a real
-  integration should handle it.
-- **Prove it landed with `signals.list()`**, not with the return value. That is
-  the only authoritative read.
+Three things follow.
+
+**The per-signal verdict lives in the ClockNext dashboard, and only there.**
+Every signal is logged with its outcome — accepted, processed, or failed with a
+reason — on the workspace's signal log. That view is owner-only in the product
+UI by design and is not exposed through this SDK or any API. When usage is not
+being billed and the causes below do not explain it, that log is where you look.
+
+**`onError` does not see worker-side rejections.** It fires when the HTTP
+request itself fails — network, timeout, auth, a `4xx` returned *before* the
+`202`. A signal that was accepted and then rejected during pricing never
+reaches it, because from the SDK's point of view that request succeeded. Pass it
+anyway: it is how you catch a bad API key, an unreachable host, and a dropped
+buffer.
+
+**`signals.list()` is the programmatic check, and it is partial.** It returns
+priced usage logs, each with a `status`, so it can tell you a signal landed and
+whether pricing succeeded. It cannot tell you about a signal that was rejected
+*before* it was ever priced — an unknown `agentKey`, a customer with no plan —
+because no usage log is written for one. Those appear only in the dashboard.
 
 ```ts
 const usage = await cnk.signals.list({ customerId });
-console.log(usage.totals.count); // 0 means nothing was recorded
+
+// Nothing here at all → rejected before pricing. Check the dashboard's log.
+console.log(usage.totals.count);
+
+// Present but not billed → priced and refused; `status` says which.
+for (const log of usage.logs) {
+  if (log.status !== "SUCCESS") console.warn(log.id, log.status);
+}
 ```
 
 ### 2. Nothing can be metered until five things exist
@@ -103,7 +123,8 @@ if (!apiKey) throw new Error("CLOCKNEXT_API_KEY is required");
 
 const cnk = new ClockNext({
   apiKey,
-  // The only channel a rejected signal has. Do not skip it.
+  // Catches request-level failures (bad key, network, dropped buffer).
+  // Rejections found later, during pricing, are visible only in the dashboard.
   onError: (error, signal) =>
     console.error("[clocknext] signal rejected", signal?.type, error),
 });
@@ -213,7 +234,9 @@ than drawing on a named entitlement — and cannot be grouped into a composite.
 ### Outcome runs
 
 An outcome is billed once per run, not once per step. Reuse the same `runId` for
-every step and set `complete: true` only on the final one.
+every step, then close the run with a separate, dedicated call —
+`signals.completeOutcome()`. `signals.outcome()` accepts ONLY the step shape;
+there is no `complete` flag to set on a step.
 
 ```ts
 const runId = "ticket_9021";
@@ -231,13 +254,18 @@ await cnk.signals.outcome({
   model: model.modelId,
   agentKey: "resolved_ticket.resolve",
   runId,
-  complete: true,
   tokens: { input: 500, output: 200 },
 });
+
+// Closing is ALWAYS its own explicit call — never a flag riding along on a
+// step's real usage.
+await cnk.signals.completeOutcome({ customerId, runId });
 ```
 
 A step may repeat within a run — a verify loop firing three times is three
-signals and one outcome. `complete: true` twice is a safe no-op.
+signals and one outcome. Sending `completeOutcome()` twice for the same run is
+a safe no-op; a genuinely SECOND, independent completion for an
+already-completed run is a permanent error (it would bill the run again).
 
 ### Unit usage
 
@@ -270,7 +298,7 @@ await cnk.signals.credit({
 await cnk.signals.completeComposite({ customerId, composite });
 ```
 
-**An outcome's `complete: true` does not close a composite occurrence.** It
+**`signals.completeOutcome()` does not close a composite occurrence.** It
 closes the run, and nothing else — whatever mix of credits, outcomes and units
 the composite wraps. If you tag outcome signals with a `composite`, you must
 still call `completeComposite()`, or that occurrence stays open and is never
@@ -430,7 +458,13 @@ and `.idempotencyKey` on metering calls. Constructor failures — a missing
 
 Because ingest answers `202` before validating, **a try/catch around
 `signals.credit()` will not catch a rejected signal**, with or without
-`{ wait: true }`. Those surface on the hooks:
+`{ wait: true }` — and neither will `onError`. A rejection discovered during
+pricing has no programmatic channel at all; it is recorded on the workspace's
+signal log in the ClockNext dashboard, which is owner-only by design.
+
+What the hooks below DO cover is everything that fails before the `202`: an
+invalid API key, an unreachable host, a timeout, and signals the SDK dropped
+without sending.
 
 ```ts
 import { ClockNext, ClockNextError } from "@clocknext/sdk";
@@ -452,6 +486,10 @@ const cnk = new ClockNext({
 
 `onFlush` counts signals the server **accepted**, not signals it billed.
 
+So the division of labour is: these hooks tell you your integration cannot
+reach ClockNext; `signals.list()` tells you what got priced; the dashboard's
+signal log tells you why an individual signal did not.
+
 ## Balances and usage
 
 ```ts
@@ -472,12 +510,20 @@ await cnk.signals.list({ customerId, limit: 50 });
 await cnk.signals.unitUsage({ customerId, limit: 50 });
 ```
 
-Adjustments use stable agent keys, not display names:
+Adjustments use stable agent keys, not display names. All four return the
+resulting `{ remaining }` balance; a reduce is never rejected or floored for
+going below 0 — the resulting balance may read negative, same as a real-usage
+overdraft already can.
 
 ```ts
 await cnk.customers.adjustCredit(customerId, { agentKey: "api_credit", delta: 100 });
 await cnk.customers.adjustOutcome(customerId, { agentKey: "resolved_ticket.triage", delta: 1 });
 await cnk.customers.adjustUnit(customerId, { agentKey: "seats", delta: 5 });
+
+// Composite: `agentKey` here is actually the composite's `refId` — the same
+// value signals tag it with — named `agentKey` on the wire so all four share
+// one request shape. Adjusts the CURRENT billing cycle's ADVANCE slot pool.
+await cnk.customers.adjustComposite(customerId, { agentKey: "voice_ai", delta: 2 });
 ```
 
 ## Customers, plans, and billing

package/dist/index.cjs

@@ -328,7 +328,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.12.0" ;
+var SDK_VERSION = "0.13.0" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -704,13 +704,15 @@ var Customers = class {
   // (PATCH …/:id) — there is no separate currency endpoint. Credit-type
   // assignment has no public API.
   // --- Balance adjustments -------------------------------------------------
-  /** Grant or claw back a credit balance. `POST …/:id/credits/adjust`. */
+  /** Grant or claw back a credit balance. Returns the remaining balance.
+   *  `POST …/:id/credits/adjust`. */
   async adjustCredit(id, input) {
-    await this.transport.request({
+    const res = await this.transport.request({
       method: "POST",
       path: `/api/v1/customers/${encodeURIComponent(id)}/credits/adjust`,
       body: input
     });
+    return { remaining: res.remaining };
   }
   /** Grant or claw back an outcome balance. Returns the remaining balance. */
   async adjustOutcome(id, input) {
@@ -730,6 +732,19 @@ var Customers = class {
     });
     return { remaining: res.remaining };
   }
+  /**
+   * Grant or claw back slots on a customer's ADVANCE composite pool for the
+   * current billing cycle. Returns the resulting `remaining` slot count.
+   * `POST …/:id/composites/adjust`.
+   */
+  async adjustComposite(id, input) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/composites/adjust`,
+      body: input
+    });
+    return { remaining: res.remaining };
+  }
 };
 
 // src/resources/invoices.ts
@@ -1015,6 +1030,7 @@ var SIGNAL_PATHS = {
 };
 var UNIT_PATH = "/api/v1/signal/unit";
 var COMPOSITE_COMPLETE_PATH = "/api/v1/signal/composite/complete";
+var OUTCOME_COMPLETE_PATH = "/api/v1/signal/outcome/complete";
 function signalToWire(signal) {
   const t = signal.tokens;
   const body = {
@@ -1035,7 +1051,6 @@ function signalToWire(signal) {
   }
   if (signal.type === "outcome") {
     body.runId = signal.runId;
-    if (signal.complete != null) body.complete = signal.complete;
   }
   if (signal.type !== "wallet" && signal.composite) {
     body.composite = { [signal.composite.ref]: signal.composite.value };
@@ -1105,6 +1120,48 @@ var Signals = class {
   outcome(input, opts) {
     return this.track({ ...input, type: "outcome" }, opts);
   }
+  /**
+   * Close ONE outcome run — declares the workflow finished and bills it. The
+   * outcome mirror of {@link Signals.completeComposite}, on its own dedicated
+   * route: `POST /api/v1/signal/outcome/complete`.
+   *
+   * An outcome bills per COMPLETION, never per step, and `signals.outcome()`
+   * never closes one — it accepts only the step shape. Declaring the workflow
+   * finished is always this separate, explicit, contentless call.
+   *
+   * This closes the RUN only. If a step of this run also carried a
+   * `composite`, that occurrence stays open and unbilled until you separately
+   * call {@link Signals.completeComposite} — the two completions are
+   * independent, and neither implies the other.
+   *
+   * Sent immediately, never buffered. A genuinely second, independent call for
+   * an already-closed run is a PERMANENT error (it would bill the run twice),
+   * not a safe no-op — see {@link OutcomeCompletionResult}.
+   */
+  async completeOutcome(input) {
+    const idempotencyKey = input.idempotencyKey ?? newKey();
+    const res = await this.transport.request({
+      method: "POST",
+      path: OUTCOME_COMPLETE_PATH,
+      idempotencyKey,
+      body: {
+        customerId: input.customerId,
+        runId: input.runId,
+        complete: true,
+        ...input.member ? { member: input.member } : {},
+        idempotencyKey
+      },
+      retry: true
+    });
+    const queued = res.queued === true;
+    return {
+      delivery: queued ? "accepted" : "recorded",
+      queued,
+      ...res.status != null ? { status: res.status } : {},
+      usageLog: res.usageLog ?? null,
+      ...handles(res)
+    };
+  }
   /**
    * Recent usage logs + totals for a customer. `GET /api/v1/usage`.
    *
@@ -1177,13 +1234,13 @@ var Signals = class {
    * arrive in any order and the occurrence stays open and unbilled until you
    * say otherwise. Put it on the line before your own `return`.
    *
-   * EVERY composite needs this, outcome-backed ones included. An outcome's own
-   * `complete: true` closes its RUN and nothing else — it does not close the
-   * composite occurrence the run was tagged into, whatever mix of credits,
-   * outcomes and units that composite wraps. (Earlier versions of this SDK
-   * documented the opposite. Believing it means the occurrence stays ONGOING
-   * forever and is never billed, so if you tag outcome signals with a
-   * `composite`, you must still call this.)
+   * EVERY composite needs this, outcome-backed ones included. `completeOutcome()`
+   * closes its RUN and nothing else — it does not close the composite
+   * occurrence the run was tagged into, whatever mix of credits, outcomes and
+   * units that composite wraps. (Earlier versions of this SDK documented the
+   * opposite. Believing it means the occurrence stays ONGOING forever and is
+   * never billed, so if you tag outcome signals with a `composite`, you must
+   * still call this.)
    *
    * Closing twice is safe: the second call answers `ALREADY_COMPLETED` and
    * cannot bill again. Calling it EARLY is also safe — before every entitlement