@clocknext/sdk 0.12.0 → 0.13.0

package/examples/node-basic.ts

@@ -58,8 +58,9 @@ async function main() {
     tokens: { input: 800, output: 5000 },
   });
 
-  // 4. Outcome run — every step shares a `runId`; mark the last one `complete`
-  //    to bill the run. `agentKey` is the OutcomeStep's key, which you read off
+  // 4. Outcome run — every step shares a `runId`; a separate, dedicated call
+  //    (`completeOutcome`) closes and bills the run — never a flag on a step.
+  //    `agentKey` is the OutcomeStep's key, which you read off
   //    `cnk.outcomes.list()` the same way.
   // `outcomes.list()` returns catalogue rows WITHOUT their steps; the step
   // agent keys — which is what a signal reports against — are on the detail.
@@ -72,9 +73,10 @@ async function main() {
       model: model.modelId,
       agentKey: outcome.steps[0].agentKey,
       runId,
-      complete: true, // closes the RUN; a composite still needs its own close
       tokens: { input: 600, output: 150 },
     });
+    // Closes the RUN; a composite still needs its own `completeComposite()` close.
+    await cnk.signals.completeOutcome({ customerId: customer.id, runId });
   }
 
   // 5. Flush the background buffer, then read the signals back. Ingestion is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clocknext/sdk",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Official ClockNext SDK — record usage signals and manage plans, purchases, invoices, customers, and billing from your backend.",
   "license": "MIT",
   "type": "module",

package/src/config.ts

@@ -14,9 +14,13 @@ const DEFAULT_BASE_URL = "https://payments.clocknext.com";
  *
  * In the default `async` mode a signal is sent by the background flusher, long
  * after `signals.credit()` resolved `{ status: "buffered" }`. There is no
- * promise left to reject into, so a rejected signal — an unknown `agentKey`, a
- * model the org has not enabled, a customer with no active plan — has nowhere
- * to surface except these hooks.
+ * promise left to reject into, so a failed REQUEST — a bad API key, an
+ * unreachable host, a timeout — has nowhere to surface except these hooks.
+ *
+ * They do not cover a signal the server accepted (`202`) and then refused while
+ * pricing it: that request succeeded as far as this SDK can tell. Those
+ * rejections are recorded on the workspace's signal log in the ClockNext
+ * dashboard, which is owner-only by design.
  *
  * They used to default to nothing at all, which meant a misconfigured
  * integration compiled, ran, returned success-shaped results, and metered

package/src/index.ts

@@ -44,6 +44,8 @@ export type {
   CreditInput,
   WalletInput,
   OutcomeInput,
+  OutcomeCompletionInput,
+  OutcomeCompletionResult,
   TrackResult,
   UsageList,
   SerializedUsageLog,
@@ -87,6 +89,7 @@ export type {
   CreditAdjustInput,
   OutcomeAdjustInput,
   UnitAdjustInput,
+  CompositeAdjustInput,
   // plans
   Plan,
   PlanDetail,

package/src/resources/customers.ts

@@ -2,6 +2,7 @@ import type { Transport } from "../http.js";
 import type {
   AddMemberInput,
   ApiCustomer,
+  CompositeAdjustInput,
   CreateCustomerInput,
   CreditAdjustInput,
   CreditBalance,
@@ -261,13 +262,18 @@ export class Customers {
 
   // --- Balance adjustments -------------------------------------------------
 
-  /** Grant or claw back a credit balance. `POST …/:id/credits/adjust`. */
-  async adjustCredit(id: string, input: CreditAdjustInput): Promise<void> {
-    await this.transport.request({
+  /** Grant or claw back a credit balance. Returns the remaining balance.
+   *  `POST …/:id/credits/adjust`. */
+  async adjustCredit(
+    id: string,
+    input: CreditAdjustInput,
+  ): Promise<{ remaining: number }> {
+    const res = await this.transport.request<{ remaining: number }>({
       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. */
@@ -295,4 +301,21 @@ export class Customers {
     });
     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: string,
+    input: CompositeAdjustInput,
+  ): Promise<{ remaining: number }> {
+    const res = await this.transport.request<{ remaining: number }>({
+      method: "POST",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/composites/adjust`,
+      body: input,
+    });
+    return { remaining: res.remaining };
+  }
 }

package/src/resources/signals.ts

@@ -5,6 +5,8 @@ import type {
   CompositeCompletionInput,
   CompositeCompletionResult,
   CreditInput,
+  OutcomeCompletionInput,
+  OutcomeCompletionResult,
   OutcomeInput,
   ResolvedConfig,
   SerializedUnitUsage,
@@ -37,10 +39,11 @@ const SIGNAL_PATHS: Record<SignalType, string> = {
   wallet: "/api/v1/signal/wallet",
 };
 
-/** Unit reports and composite completions are not part of the `Signal` union
- *  (no model, no tokens), so they carry their paths separately. */
+/** Unit reports and completion pings are not part of the `Signal` union (no
+ *  model, no tokens), so they carry their paths separately. */
 const UNIT_PATH = "/api/v1/signal/unit";
 const COMPOSITE_COMPLETE_PATH = "/api/v1/signal/composite/complete";
+const OUTCOME_COMPLETE_PATH = "/api/v1/signal/outcome/complete";
 
 /**
  * Builds the request body for a typed Signal.
@@ -82,10 +85,12 @@ export function signalToWire(signal: Signal): Record<string, unknown> {
     body.agentKey = signal.agentKey;
   }
 
-  // Outcome runs are grouped by `runId`; `complete` ends the run.
+  // Outcome runs are grouped by `runId`. Ending the run is NOT a flag on this
+  // body: `POST /api/v1/signal/outcome` (what this body is sent to) accepts
+  // ONLY the step shape and rejects one that also carries `complete` — see
+  // `signals.completeOutcome()`, its own dedicated route.
   if (signal.type === "outcome") {
     body.runId = signal.runId;
-    if (signal.complete != null) body.complete = signal.complete;
   }
 
   // Composite tag, nested under its `refId`. Never set for wallet — the server
@@ -136,8 +141,15 @@ function handles(res: SignalResponse) {
  *
  * Because of that, a signal the server later REJECTS (unknown `agentKey`, a
  * model the org has not enabled, no active plan) cannot come back through this
- * promise. It surfaces on the `onError` hook, and `list()` is how you confirm
- * one actually landed — ingestion being asynchronous, the only way to.
+ * promise — and does not reach `onError` either, since from here that request
+ * succeeded. Such a rejection 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.
+ *
+ * `list()` is the partial check available from code. It returns priced usage
+ * logs with a `status`, so it confirms a signal landed and whether pricing
+ * succeeded — but a signal refused BEFORE pricing never becomes a usage log
+ * and does not appear there.
  */
 export class Signals {
   constructor(
@@ -235,6 +247,56 @@ export class Signals {
     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: OutcomeCompletionInput,
+  ): Promise<OutcomeCompletionResult> {
+    const idempotencyKey = input.idempotencyKey ?? newKey();
+    const res = await this.transport.request<
+      SignalResponse & {
+        status?: "COMPLETED" | "ALREADY_COMPLETED";
+        usageLog?: OutcomeCompletionResult["usageLog"];
+      }
+    >({
+      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`.
    *
@@ -316,13 +378,13 @@ export class Signals {
    * 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

package/src/types.ts

@@ -140,7 +140,14 @@ export interface WalletSignal extends SignalBase {
 /**
  * Records one step of a multi-call outcome run. The `agentKey` identifies the
  * step (and the outcome); `runId` groups every signal of a single run, so a step
- * may repeat freely. The run bills once, when the caller marks it `complete`.
+ * may repeat freely. The run bills once, when the caller closes it with
+ * `signals.completeOutcome()` — a SEPARATE, dedicated call, never a flag on a
+ * step signal.
+ *
+ * There is no `complete` field here. `POST /api/v1/signal/outcome` (what this
+ * type posts to) now accepts ONLY the step shape and rejects a body that also
+ * carries `complete` — see {@link OutcomeCompletionInput} /
+ * `signals.completeOutcome()`, its own dedicated route.
  */
 export interface OutcomeSignal extends SignalBase {
   type: "outcome";
@@ -152,17 +159,6 @@ export interface OutcomeSignal extends SignalBase {
    * outcome). Opaque to ClockNext — any string you can correlate; unique per org.
    */
   runId: string;
-  /**
-   * Set `true` on the LAST step signal to declare the run finished — completion
-   * is never inferred from step coverage. Sending it twice is a safe no-op and
-   * can't bill again.
-   *
-   * This closes the RUN only. If the signal also carries a `composite`, that
-   * occurrence stays open and unbilled until you call
-   * `signals.completeComposite()` — the two completions are separate, and
-   * neither implies the other.
-   */
-  complete?: boolean;
   /** Optional composite this signal belongs to. See {@link CompositeTag}. */
   composite?: CompositeTag;
 }
@@ -174,6 +170,58 @@ export type CreditInput = Omit<CreditSignal, "type">;
 export type WalletInput = Omit<WalletSignal, "type">;
 export type OutcomeInput = Omit<OutcomeSignal, "type">;
 
+/**
+ * Input for `signals.completeOutcome()` — closes ONE outcome run, the outcome
+ * mirror of {@link CompositeCompletionInput}. No `agentKey`, no `usage`: this
+ * closes an EXISTING run that an earlier `signals.outcome()` step already
+ * opened, so there is no step behind this call and nothing here to price.
+ *
+ * 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
+ * `signals.completeComposite()` — the two completions are independent, and
+ * neither implies the other.
+ */
+export interface OutcomeCompletionInput {
+  customerId: string;
+  /** The same `runId` the run's step signals were sent with. */
+  runId: string;
+  /** Optional member (email) this completion is attributed to. */
+  member?: string;
+  /** Idempotency key, auto-generated if omitted. Sending `complete` twice for
+   *  the same run is already a safe no-op server-side, so this only collapses
+   *  a retry into one attempt rather than protecting against a double bill. */
+  idempotencyKey?: string;
+}
+
+/**
+ * The result of `signals.completeOutcome()`.
+ *
+ * Unlike {@link CompositeCompletionResult}, `ALREADY_COMPLETED` is NOT what a
+ * normal second ping for the same run gets back — that is rejected outright
+ * (a permanent error: the run has already been billed, and completing it again
+ * would bill it twice). `ALREADY_COMPLETED` is reserved for the much rarer case
+ * of two concurrent deliveries of the exact same request (e.g. a client-side
+ * retry racing the original), which really is a harmless echo.
+ */
+export interface OutcomeCompletionResult {
+  /** How far the ping got. Never `"buffered"` — completions are always sent
+   *  immediately. See {@link TrackResult.status}. */
+  delivery: Extract<SignalDelivery, "accepted" | "recorded">;
+  /** True when the ping was accepted but not yet applied (`202`). Prefer
+   *  {@link OutcomeCompletionResult.delivery}. */
+  queued: boolean;
+  /** `COMPLETED` on the first close, `ALREADY_COMPLETED` only on the rare
+   *  concurrent-replay case described above. Absent when the ping was queued. */
+  status?: "COMPLETED" | "ALREADY_COMPLETED";
+  /** The priced usage log, when the server closed the run inline. `null` on a
+   *  `202` hand-off. */
+  usageLog?: SerializedUsageLog | null;
+  /** The durable inbox id — see {@link TrackResult.rawId}. */
+  rawId?: string;
+  /** The queue message id, present only on a `202` hand-off. */
+  messageId?: string;
+}
+
 // ---------------------------------------------------------------------------
 // Server response shapes (mirrors src/lib/usage/log.ts)
 // ---------------------------------------------------------------------------
@@ -278,8 +326,10 @@ export interface TrackResult {
    *   `"accepted"` — the server has written it to its durable inbox (`202`)
    *                  and will price it shortly. It can no longer be lost, but
    *                  it is not billed yet and `usageLog` is null. A rejection
-   *                  discovered during pricing will NOT come back to you here —
-   *                  read it back with `signals.list()`.
+   *                  discovered during pricing will NOT come back to you here,
+   *                  nor on `onError`. `signals.list()` shows what got priced;
+   *                  the dashboard's signal log — owner-only, by design — is
+   *                  where an individual rejection says why.
    *   `"recorded"` — the server priced it inline and `usageLog` is populated.
    *   `"dropped"`  — the SDK threw it away without sending: the client is
    *                  closed, or the local queue is full. `onDrop` fired with
@@ -976,7 +1026,9 @@ export interface WalletEntryInput {
 }
 
 /** Grant (positive) or claw back (negative) a credit balance. `delta` must be a
- *  non-zero whole number. The credit is addressed by its stable `agentKey`. */
+ *  non-zero whole number. The credit is addressed by its stable `agentKey`. 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. */
 export interface CreditAdjustInput {
   /** The credit's stable agent key (the same key used to record usage). */
   agentKey: string;
@@ -984,10 +1036,12 @@ export interface CreditAdjustInput {
   notes?: string;
 }
 
-/** Grant/claw an outcome balance. `delta` is a non-zero whole number; floored at
- *  0. The outcome is addressed here by a STEP's `agentKey`, which resolves to its
+/** Grant/claw an outcome balance. `delta` is a non-zero whole number. The
+ *  outcome is addressed here by a STEP's `agentKey`, which resolves to its
  *  parent outcome — NOT by the outcome's own `agentKey` ({@link Outcome.agentKey}),
- *  which this endpoint does not accept. */
+ *  which this endpoint does not accept. 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. */
 export interface OutcomeAdjustInput {
   /** An outcome STEP's stable agent key — identifies the parent outcome. Passing
    *  the outcome's own `agentKey` here fails with `422`. */
@@ -996,8 +1050,10 @@ export interface OutcomeAdjustInput {
   notes?: string;
 }
 
-/** Grant/claw a unit balance. `delta` is non-zero (fractional allowed); floored
- *  at 0. The unit is addressed by its stable `agentKey`. */
+/** Grant/claw a unit balance. `delta` is non-zero (fractional allowed). The
+ *  unit is addressed by its stable `agentKey`. 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. */
 export interface UnitAdjustInput {
   /** The unit's stable agent key (the same key used to record usage). */
   agentKey: string;
@@ -1005,6 +1061,26 @@ export interface UnitAdjustInput {
   notes?: string;
 }
 
+/**
+ * Grant (positive) or claw back (negative) slots on a customer's ADVANCE
+ * composite (pricing metric) pool for the CURRENT billing cycle. `delta` is a
+ * non-zero whole number. A reduce is never rejected or floored for going below
+ * 0 — same as credit/outcome/unit adjustments; the resulting pool may read
+ * negative. Fails if the customer has no active ADVANCE purchase component
+ * selling this composite.
+ */
+export interface CompositeAdjustInput {
+  /**
+   * The composite's stable identifier — its `refId` (see {@link Composite.refId}),
+   * the same value signals tag it with, NOT `agentKey` (a composite has no
+   * `agentKey` column of its own). Named `agentKey` on the wire only so the
+   * four adjust endpoints share one request shape.
+   */
+  agentKey: string;
+  delta: number;
+  notes?: string;
+}
+
 // ---------------------------------------------------------------------------
 // Entitlement catalogs: Credits, Outcomes, Units
 // ---------------------------------------------------------------------------