@clocknext/sdk 0.12.1 → 0.14.0

package/README.md

@@ -234,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";
@@ -252,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
 
@@ -291,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
@@ -503,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.1" ;
+var SDK_VERSION = "0.14.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,8 @@ 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";
+var USAGE_LOG_PATH = "/api/v1/signal/usage-log";
 function signalToWire(signal) {
   const t = signal.tokens;
   const body = {
@@ -1035,7 +1052,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 +1121,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 +1235,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
@@ -1232,6 +1290,37 @@ var Signals = class {
       query: { customerId: params.customerId, limit: params.limit }
     });
   }
+  /**
+   * One customer's usage history, merged from every meter kind — credit,
+   * outcome, unit, wallet, and completed composite occurrences — into one
+   * feed sorted by time. `GET /api/v1/signal/usage-log`. Exactly the same
+   * rows the customer portal's own "Usage logs" table shows, so a caller can
+   * build against this instead of the portal UI.
+   *
+   * Cursor-paginated, NOT page-numbered: `limit` + `cursor` in, `nextCursor`
+   * out. Omit `cursor` for the first page; pass the previous page's
+   * `nextCursor` back to fetch the next one, and stop once it comes back
+   * `null`. Unlike offset pagination, the cost of a page never grows with how
+   * deep you've paged — each page only asks for rows strictly before the
+   * cursor's position.
+   *
+   * Read-only; unlike {@link track}/{@link unit}/etc., there is nothing to
+   * buffer or retry here.
+   */
+  usageLog(params) {
+    return this.transport.request({
+      method: "GET",
+      path: USAGE_LOG_PATH,
+      query: {
+        customerId: params.customerId,
+        limit: params.limit,
+        cursor: params.cursor,
+        period: params.period,
+        from: params.from,
+        to: params.to
+      }
+    });
+  }
 };
 
 // src/resources/units.ts