@clocknext/sdk 0.12.1 → 0.14.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.1",
+  "version": "0.14.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/index.ts

@@ -44,6 +44,8 @@ export type {
   CreditInput,
   WalletInput,
   OutcomeInput,
+  OutcomeCompletionInput,
+  OutcomeCompletionResult,
   TrackResult,
   UsageList,
   SerializedUsageLog,
@@ -57,6 +59,12 @@ export type {
   UnitUsageRow,
   UnitUsageList,
   SerializedUnitUsage,
+  UsageLogPeriod,
+  UsageLogListParams,
+  UsageLogAppliedRule,
+  UsageLogOutcomeAttribution,
+  UsageLogEntry,
+  UsageLogPage,
   // workspace
   WorkspaceIdentity,
   Model,
@@ -87,6 +95,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,
@@ -15,6 +17,8 @@ import type {
   UnitTrackResult,
   UnitUsageList,
   UsageList,
+  UsageLogListParams,
+  UsageLogPage,
   WalletInput,
 } from "../types.js";
 
@@ -37,10 +41,12 @@ 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";
+const USAGE_LOG_PATH = "/api/v1/signal/usage-log";
 
 /**
  * Builds the request body for a typed Signal.
@@ -82,10 +88,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
@@ -242,6 +250,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`.
    *
@@ -323,13 +381,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
@@ -390,4 +448,36 @@ export class Signals {
       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: UsageLogListParams): Promise<UsageLogPage> {
+    return this.transport.request<UsageLogPage>({
+      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,
+      },
+    });
+  }
 }

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)
 // ---------------------------------------------------------------------------
@@ -337,6 +385,86 @@ export interface UsageList {
   logs: SerializedUsageLog[];
 }
 
+// ---------------------------------------------------------------------------
+// Usage log (mirrors GET /api/v1/signal/usage-log)
+// ---------------------------------------------------------------------------
+
+/** A preset time window, or `"custom"` for an explicit `from`/`to` range. */
+export type UsageLogPeriod = "all" | "today" | "7d" | "30d" | "90d" | "custom";
+
+export interface UsageLogListParams {
+  customerId: string;
+  /** Default 50, max 200. */
+  limit?: number;
+  /** Pass back a previous page's `nextCursor` to fetch the next page. Omit for
+   *  the first page. */
+  cursor?: string;
+  /** Default `"all"`. Pair `"custom"` with `from`/`to`. */
+  period?: UsageLogPeriod;
+  /** `YYYY-MM-DD`, only used when `period` is `"custom"`. */
+  from?: string;
+  /** `YYYY-MM-DD`, only used when `period` is `"custom"`. */
+  to?: string;
+}
+
+export interface UsageLogAppliedRule {
+  ruleId: string | null;
+  ruleName: string;
+  mode: "MARGIN" | "CREDIT" | null;
+  marginPercentApplied: number | null;
+  /** Formatted, same as {@link UsageLogEntry.credit}'s `amount`. */
+  creditsApplied: string;
+}
+
+export interface UsageLogOutcomeAttribution {
+  /** "2 / 4" — the step this call performed, and the outcome's total step
+   *  count. Not a progress target: a step may repeat within a run. */
+  step: string | null;
+  stepName: string | null;
+  runId: string | null;
+  /** How many signals the run holds. */
+  runSignals: number;
+  /** True once the run closed (`complete: true` was sent for it). */
+  closedRun: boolean;
+}
+
+/**
+ * One row of a customer's usage history, merged from every meter kind
+ * (`UsageLog`, `UnitUsageLog`, completed composite occurrences) into one
+ * feed and sorted by time — the same rows the customer portal's own "Usage
+ * logs" table shows. `model`, `credit`, `outcome`, `unit` and `composite` are
+ * each `null` unless `kind` matches that group.
+ */
+export interface UsageLogEntry {
+  id: string;
+  createdAt: string;
+  kind: "credit" | "outcome" | "unit" | "wallet" | "composite";
+  status: SignalStatus;
+  typeName: string | null;
+  member: string | null;
+  model: { name: string | null; provider: string | null } | null;
+  usage: { inputTokens: number; outputTokens: number; cacheTokens: number };
+  /** Formatted USD strings (e.g. `"$0.0064"`). */
+  cost: { providedCost: string; customerCost: string };
+  /** Populated only when `kind === "credit"`. `amount` is a formatted credit
+   *  value, honouring the org's credit-decimals display setting. */
+  credit: { amount: string; appliedRules: UsageLogAppliedRule[] } | null;
+  /** Populated only when `kind === "outcome"`. */
+  outcome: UsageLogOutcomeAttribution | null;
+  /** Populated only when `kind === "unit"`. `quantity` is formatted. */
+  unit: { quantity: string } | null;
+  /** Populated only when `kind === "composite"`. `amount` is a formatted USD
+   *  price — the composite's flat price, read live, not stored per row. */
+  composite: { amount: string } | null;
+}
+
+export interface UsageLogPage {
+  usageLogs: UsageLogEntry[];
+  /** Pass this back as `cursor` to fetch the next page; `null` on the last
+   *  page. */
+  nextCursor: string | null;
+}
+
 // ---------------------------------------------------------------------------
 // Customers (mirrors src/lib/customers/api.ts)
 // ---------------------------------------------------------------------------
@@ -978,7 +1106,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;
@@ -986,10 +1116,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`. */
@@ -998,8 +1130,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;
@@ -1007,6 +1141,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
 // ---------------------------------------------------------------------------