@clocknext/sdk 0.12.0 → 0.13.0

package/dist/index.js

@@ -326,7 +326,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;
@@ -702,13 +702,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) {
@@ -728,6 +730,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
@@ -1013,6 +1028,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 = {
@@ -1033,7 +1049,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 };
@@ -1103,6 +1118,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`.
    *
@@ -1175,13 +1232,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