@clocknext/sdk 0.15.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clocknext/sdk",
-  "version": "0.15.0",
+  "version": "0.17.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/client.ts

@@ -1,13 +1,17 @@
 import { resolveConfig } from "./config.js";
 import { Flusher } from "./flusher.js";
 import { Transport } from "./http.js";
+import { Composites } from "./resources/composites.js";
+import { Credits } from "./resources/credits.js";
 import { Customers } from "./resources/customers.js";
 import { Invoices } from "./resources/invoices.js";
+import { Outcomes } from "./resources/outcomes.js";
 import { Payments } from "./resources/payments.js";
 import { Plans } from "./resources/plans.js";
 import { Portal } from "./resources/portal.js";
 import { Purchases } from "./resources/purchases.js";
 import { Signals } from "./resources/signals.js";
+import { Units } from "./resources/units.js";
 import type { ClockNextConfig, ResolvedConfig } from "./types.js";
 
 /**
@@ -32,8 +36,16 @@ export class ClockNext {
   readonly signals: Signals;
   /** Manage customers, their members, and balances. */
   readonly customers: Customers;
-  /** List billing plans. */
+  /** Billing plans: list, get, create, update, archive, unarchive. */
   readonly plans: Plans;
+  /** Credits: list, get, create, update, archive, unarchive (no delete). */
+  readonly credits: Credits;
+  /** Outcomes: list, get, create, update, archive, unarchive (no delete). */
+  readonly outcomes: Outcomes;
+  /** Units: list, get, create, update, archive, unarchive (no delete). */
+  readonly units: Units;
+  /** Composites: list, get, create, update, archive, unarchive (no delete). */
+  readonly composites: Composites;
   /** Subscribe customers to plans (purchases). */
   readonly purchases: Purchases;
   /** Read invoices and mint hosted pay links. */
@@ -60,6 +72,10 @@ export class ClockNext {
     this.signals = new Signals(transport, this.flusher, this.cfg);
     this.customers = new Customers(transport);
     this.plans = new Plans(transport);
+    this.credits = new Credits(transport);
+    this.outcomes = new Outcomes(transport);
+    this.units = new Units(transport);
+    this.composites = new Composites(transport);
     this.purchases = new Purchases(transport);
     this.invoices = new Invoices(transport);
     this.payments = new Payments(transport);

package/src/errors.ts

@@ -107,7 +107,7 @@ export class NetworkError extends ClockNextError {
  *
  * The server validates the WIRE body and names the offending path in its 400
  * (`usage.inputTokens: Expected number…`). But the SDK groups those fields
- * differently — `tokens: { input, output, cache }` — so the path it reports
+ * differently — `tokens: { input, output, cache, cacheWrite }` — so the path it reports
  * names something that does not exist anywhere in this SDK's API. A caller
  * (human or LLM) then searches their own code for `usage.inputTokens`, finds
  * nothing, and has no next move.
@@ -120,6 +120,7 @@ const FIELD_PATHS: ReadonlyArray<readonly [RegExp, string]> = [
   [/\busage\.inputTokens\b/g, "tokens.input"],
   [/\busage\.outputTokens\b/g, "tokens.output"],
   [/\busage\.cacheTokens\b/g, "tokens.cache"],
+  [/\busage\.cacheWriteTokens\b/g, "tokens.cacheWrite"],
   [/\busage\.model\b/g, "model"],
   // A missing/invalid `usage` block as a whole: the caller's equivalent is
   // `tokens` (plus `model`, which the SDK hoists to the top level).

package/src/index.ts

@@ -72,6 +72,7 @@ export type {
   CreditBalance,
   OutcomeBalance,
   UnitBalance,
+  CompositeBalance,
   CustomerPlan,
   CustomerPlanDetails,
   // members
@@ -92,6 +93,31 @@ export type {
   RecurringGrantResult,
   // plans
   Plan,
+  PlanEntitlement,
+  PlanEntitlementInput,
+  CreatePlanInput,
+  UpdatePlanInput,
+  // catalogue: credits, outcomes, units, composites
+  ModelBundleLine,
+  ModelBundleLineInput,
+  Credit,
+  CreateCreditInput,
+  UpdateCreditInput,
+  Outcome,
+  OutcomeStep,
+  OutcomeWithSteps,
+  OutcomeStepInput,
+  CreateOutcomeInput,
+  UpdateOutcomeInput,
+  UnitPricingType,
+  UnitTier,
+  Unit,
+  CreateUnitInput,
+  UpdateUnitInput,
+  CompositeItem,
+  Composite,
+  CreateCompositeInput,
+  UpdateCompositeInput,
   PlanComponent,
   BillingCycle,
   PlanType,

package/src/resources/composites.ts

@@ -0,0 +1,82 @@
+import { activeQuery, filterByActive } from "../filters.js";
+import type { Transport } from "../http.js";
+import type { Composite, CreateCompositeInput, UpdateCompositeInput } from "../types.js";
+
+/**
+ * The `composites` resource — several credits / outcomes / units grouped under
+ * one tag (`refId`) and billed as ONE thing per completed occurrence.
+ * `/api/v1/composites`.
+ *
+ * Creating a composite charges nobody: it only bills once a plan sells it as
+ * a `PRICING_METRIC` entitlement (`plans.create()` with its `compositeId`).
+ *
+ * There is no `delete()` — the API never deletes catalogue items. Retire a
+ * composite with `archive()` (new signals stop resolving to it; its history is
+ * kept); `unarchive()` brings it back.
+ */
+export class Composites {
+  constructor(private readonly transport: Transport) {}
+
+  /** List them. `{ active: true }` returns only active ones, `{ active: false }`
+   *  only archived ones; omit it for both. */
+  async list(params: { active?: boolean } = {}): Promise<Composite[]> {
+    const res = await this.transport.request<{ composites: Composite[] }>({
+      method: "GET",
+      path: "/api/v1/composites",
+      query: { active: activeQuery(params.active) },
+    });
+    return filterByActive(res.composites, params.active);
+  }
+
+  /** One composite's configuration. */
+  async get(id: string): Promise<Composite> {
+    const res = await this.transport.request<{ composite: Composite }>({
+      method: "GET",
+      path: `/api/v1/composites/${encodeURIComponent(id)}`,
+    });
+    return res.composite;
+  }
+
+  /** Create one. It starts active. Not retried on failure — a retry could
+   *  create a second row. */
+  async create(input: CreateCompositeInput): Promise<Composite> {
+    const res = await this.transport.request<{ created: true; composite: Composite }>({
+      method: "POST",
+      path: "/api/v1/composites",
+      body: input,
+    });
+    return res.composite;
+  }
+
+  /** PARTIAL update: only the fields you send change. `entitlements`, when
+   *  sent, is the complete new set. Renaming `refId` cuts live traffic over at
+   *  once — ship the new tag to your callers first. */
+  async update(id: string, input: UpdateCompositeInput): Promise<Composite> {
+    const res = await this.transport.request<{ updated: true; composite: Composite }>({
+      method: "PATCH",
+      path: `/api/v1/composites/${encodeURIComponent(id)}`,
+      body: input,
+    });
+    return res.composite;
+  }
+
+  /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+  async archive(id: string): Promise<Composite> {
+    const res = await this.transport.request<{ archived: true; composite: Composite }>({
+      method: "POST",
+      path: `/api/v1/composites/${encodeURIComponent(id)}/archive`,
+      retry: true,
+    });
+    return res.composite;
+  }
+
+  /** Bring an archived one back (`isActive` → true). Safe to retry. */
+  async unarchive(id: string): Promise<Composite> {
+    const res = await this.transport.request<{ unarchived: true; composite: Composite }>({
+      method: "POST",
+      path: `/api/v1/composites/${encodeURIComponent(id)}/unarchive`,
+      retry: true,
+    });
+    return res.composite;
+  }
+}

package/src/resources/credits.ts

@@ -0,0 +1,81 @@
+import { activeQuery, filterByActive } from "../filters.js";
+import type { Transport } from "../http.js";
+import type { CreateCreditInput, Credit, UpdateCreditInput } from "../types.js";
+
+/**
+ * The `credits` resource — the token-metered credits your product draws down
+ * by `agentKey`. `/api/v1/credits`.
+ *
+ * Pricing is never typed in: `create()` takes a `modelBundle` (one line per
+ * model, each with `averageTokensPerLLMCall` and its input / output / cache /
+ * cacheWrite split) and the server works out `basePrice` and
+ * `pricePerCredit` from the models' live prices.
+ *
+ * There is no `delete()` — the API never deletes catalogue items. Retire a
+ * credit with `archive()`; `unarchive()` brings it back unchanged.
+ */
+export class Credits {
+  constructor(private readonly transport: Transport) {}
+
+  /** List them. `{ active: true }` returns only active ones, `{ active: false }`
+   *  only archived ones; omit it for both. */
+  async list(params: { active?: boolean } = {}): Promise<Credit[]> {
+    const res = await this.transport.request<{ credits: Credit[] }>({
+      method: "GET",
+      path: "/api/v1/credits",
+      query: { active: activeQuery(params.active) },
+    });
+    return filterByActive(res.credits, params.active);
+  }
+
+  /** One credit's configuration. */
+  async get(id: string): Promise<Credit> {
+    const res = await this.transport.request<{ credit: Credit }>({
+      method: "GET",
+      path: `/api/v1/credits/${encodeURIComponent(id)}`,
+    });
+    return res.credit;
+  }
+
+  /** Create one. It starts active. Not retried on failure — a retry could
+   *  create a second row. */
+  async create(input: CreateCreditInput): Promise<Credit> {
+    const res = await this.transport.request<{ created: true; credit: Credit }>({
+      method: "POST",
+      path: "/api/v1/credits",
+      body: input,
+    });
+    return res.credit;
+  }
+
+  /** PARTIAL update: only the fields you send change. Send `modelBundle` to
+   *  re-price; leave it out to keep the stored base price. */
+  async update(id: string, input: UpdateCreditInput): Promise<Credit> {
+    const res = await this.transport.request<{ updated: true; credit: Credit }>({
+      method: "PATCH",
+      path: `/api/v1/credits/${encodeURIComponent(id)}`,
+      body: input,
+    });
+    return res.credit;
+  }
+
+  /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+  async archive(id: string): Promise<Credit> {
+    const res = await this.transport.request<{ archived: true; credit: Credit }>({
+      method: "POST",
+      path: `/api/v1/credits/${encodeURIComponent(id)}/archive`,
+      retry: true,
+    });
+    return res.credit;
+  }
+
+  /** Bring an archived one back (`isActive` → true). Safe to retry. */
+  async unarchive(id: string): Promise<Credit> {
+    const res = await this.transport.request<{ unarchived: true; credit: Credit }>({
+      method: "POST",
+      path: `/api/v1/credits/${encodeURIComponent(id)}/unarchive`,
+      retry: true,
+    });
+    return res.credit;
+  }
+}

package/src/resources/customers.ts

@@ -310,7 +310,7 @@ export class Customers {
    * Top up (positive `delta`) or draw down (negative `delta`) a customer's
    * wallet, in USD — allowed whatever the customer's plan. `remaining` is the
    * resulting USD balance. No `agentKey` — a customer has exactly one wallet.
-   * Pass `pool: "RESERVED"` to move the Reserved Wallet instead (then
+   * Pass `pool: "reserved"` to move the Reserved Wallet instead (then
    * `remaining` is its balance). `POST …/:id/wallet/adjust`.
    */
   adjustWallet(id: string, input: WalletAdjustInput): Promise<AdjustResult> {

package/src/resources/outcomes.ts

@@ -0,0 +1,81 @@
+import { activeQuery, filterByActive } from "../filters.js";
+import type { Transport } from "../http.js";
+import type { CreateOutcomeInput, Outcome, OutcomeWithSteps, UpdateOutcomeInput } from "../types.js";
+
+/**
+ * The `outcomes` resource — multi-step deliverables billed per completed
+ * outcome. `/api/v1/outcomes`.
+ *
+ * `list()` and every write return the outcome without its steps; `get()`
+ * returns it with every step in full (ids included). Each new step is priced
+ * from its own `modelBundle`, on the server.
+ *
+ * There is no `delete()` — the API never deletes catalogue items. Retire an
+ * outcome with `archive()`; `unarchive()` brings it back unchanged.
+ */
+export class Outcomes {
+  constructor(private readonly transport: Transport) {}
+
+  /** List them. `{ active: true }` returns only active ones, `{ active: false }`
+   *  only archived ones; omit it for both. */
+  async list(params: { active?: boolean } = {}): Promise<Outcome[]> {
+    const res = await this.transport.request<{ outcomes: Outcome[] }>({
+      method: "GET",
+      path: "/api/v1/outcomes",
+      query: { active: activeQuery(params.active) },
+    });
+    return filterByActive(res.outcomes, params.active);
+  }
+
+  /** One outcome's configuration, with every step in full. */
+  async get(id: string): Promise<OutcomeWithSteps> {
+    const res = await this.transport.request<{ outcome: OutcomeWithSteps }>({
+      method: "GET",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}`,
+    });
+    return res.outcome;
+  }
+
+  /** Create one. It starts active. Not retried on failure — a retry could
+   *  create a second row. */
+  async create(input: CreateOutcomeInput): Promise<Outcome> {
+    const res = await this.transport.request<{ created: true; outcome: Outcome }>({
+      method: "POST",
+      path: "/api/v1/outcomes",
+      body: input,
+    });
+    return res.outcome;
+  }
+
+  /** PARTIAL update: only the fields you send change. Leave `steps` out to
+   *  leave the steps alone; send it and it is the complete list — pass each
+   *  existing step's `id` (or its same `agentKey`) to keep it. */
+  async update(id: string, input: UpdateOutcomeInput): Promise<Outcome> {
+    const res = await this.transport.request<{ updated: true; outcome: Outcome }>({
+      method: "PATCH",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}`,
+      body: input,
+    });
+    return res.outcome;
+  }
+
+  /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+  async archive(id: string): Promise<Outcome> {
+    const res = await this.transport.request<{ archived: true; outcome: Outcome }>({
+      method: "POST",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}/archive`,
+      retry: true,
+    });
+    return res.outcome;
+  }
+
+  /** Bring an archived one back (`isActive` → true). Safe to retry. */
+  async unarchive(id: string): Promise<Outcome> {
+    const res = await this.transport.request<{ unarchived: true; outcome: Outcome }>({
+      method: "POST",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}/unarchive`,
+      retry: true,
+    });
+    return res.outcome;
+  }
+}

package/src/resources/plans.ts

@@ -1,11 +1,16 @@
 import { activeQuery, filterByActive } from "../filters.js";
 import type { Transport } from "../http.js";
-import type { Plan } from "../types.js";
+import type { CreatePlanInput, Plan, UpdatePlanInput } from "../types.js";
 
 /**
- * The `plans` resource — read the billing plans customers can subscribe to.
- * Each plan is a set of entitlement components (wallet / credit / outcome /
- * unit / flat) billed on a cycle. `/api/v1/plans`.
+ * The `plans` resource — the billing plans customers subscribe to. Each plan
+ * is a set of `entitlements` (wallet / credit / outcome / unit / composite /
+ * flat lines) billed on a cycle. `/api/v1/plans`.
+ *
+ * A plan's currency is the workspace's primary currency; it can't be chosen.
+ * There is no `delete()` — the API never deletes plans, so customers already
+ * on one keep what they bought. Retire a plan with `archive()`; `unarchive()`
+ * makes it purchasable again.
  */
 export class Plans {
   constructor(private readonly transport: Transport) {}
@@ -21,4 +26,57 @@ export class Plans {
     });
     return filterByActive(res.plans, params.active);
   }
+
+  /** One plan's configuration. */
+  async get(id: string): Promise<Plan> {
+    const res = await this.transport.request<{ plan: Plan }>({
+      method: "GET",
+      path: `/api/v1/plans/${encodeURIComponent(id)}`,
+    });
+    return res.plan;
+  }
+
+  /** Create a plan. It starts active. Not retried on failure — a retry could
+   *  create a second plan. */
+  async create(input: CreatePlanInput): Promise<Plan> {
+    const res = await this.transport.request<{ created: true; plan: Plan }>({
+      method: "POST",
+      path: "/api/v1/plans",
+      body: input,
+    });
+    return res.plan;
+  }
+
+  /** PARTIAL update: only the fields you send change. `entitlements`, when
+   *  sent, is the complete new list — the list `get()` returned can be sent
+   *  back as it is. Changes apply to new purchases only. */
+  async update(id: string, input: UpdatePlanInput): Promise<Plan> {
+    const res = await this.transport.request<{ updated: true; plan: Plan }>({
+      method: "PATCH",
+      path: `/api/v1/plans/${encodeURIComponent(id)}`,
+      body: input,
+    });
+    return res.plan;
+  }
+
+  /** Retire a plan (`isActive` → false): it can't be bought any more; customers
+   *  already on it are unaffected. Safe to retry. */
+  async archive(id: string): Promise<Plan> {
+    const res = await this.transport.request<{ archived: true; plan: Plan }>({
+      method: "POST",
+      path: `/api/v1/plans/${encodeURIComponent(id)}/archive`,
+      retry: true,
+    });
+    return res.plan;
+  }
+
+  /** Make an archived plan purchasable again (`isActive` → true). Safe to retry. */
+  async unarchive(id: string): Promise<Plan> {
+    const res = await this.transport.request<{ unarchived: true; plan: Plan }>({
+      method: "POST",
+      path: `/api/v1/plans/${encodeURIComponent(id)}/unarchive`,
+      retry: true,
+    });
+    return res.plan;
+  }
 }

package/src/resources/signals.ts

@@ -69,12 +69,14 @@ export function signalToWire(signal: Signal): Record<string, unknown> {
   const body: Record<string, unknown> = {
     ...customerRefToWire(signal),
     // `usage` is required on all three model-priced kinds. input/output are
-    // always sent; `cacheTokens` only when provided (the server defaults 0).
+    // always sent; `cacheTokens` / `cacheWriteTokens` only when provided (the
+    // server defaults each to 0).
     usage: {
       model: signal.model,
       inputTokens: t.input,
       outputTokens: t.output,
       ...(t.cache != null ? { cacheTokens: t.cache } : {}),
+      ...(t.cacheWrite != null ? { cacheWriteTokens: t.cacheWrite } : {}),
     },
   };
   if (signal.member) body.member = signal.member;

package/src/resources/units.ts

@@ -0,0 +1,76 @@
+import { activeQuery, filterByActive } from "../filters.js";
+import type { Transport } from "../http.js";
+import type { CreateUnitInput, Unit, UpdateUnitInput } from "../types.js";
+
+/**
+ * The `units` resource — fixed-price, non-LLM events (uploads, seats, API
+ * calls), priced FLAT, SLAB or VOLUME. `/api/v1/units`.
+ *
+ * There is no `delete()` — the API never deletes catalogue items. Retire a
+ * unit with `archive()`; `unarchive()` brings it back unchanged.
+ */
+export class Units {
+  constructor(private readonly transport: Transport) {}
+
+  /** List them. `{ active: true }` returns only active ones, `{ active: false }`
+   *  only archived ones; omit it for both. */
+  async list(params: { active?: boolean } = {}): Promise<Unit[]> {
+    const res = await this.transport.request<{ units: Unit[] }>({
+      method: "GET",
+      path: "/api/v1/units",
+      query: { active: activeQuery(params.active) },
+    });
+    return filterByActive(res.units, params.active);
+  }
+
+  /** One unit's configuration. */
+  async get(id: string): Promise<Unit> {
+    const res = await this.transport.request<{ unit: Unit }>({
+      method: "GET",
+      path: `/api/v1/units/${encodeURIComponent(id)}`,
+    });
+    return res.unit;
+  }
+
+  /** Create one. It starts active. Not retried on failure — a retry could
+   *  create a second row. */
+  async create(input: CreateUnitInput): Promise<Unit> {
+    const res = await this.transport.request<{ created: true; unit: Unit }>({
+      method: "POST",
+      path: "/api/v1/units",
+      body: input,
+    });
+    return res.unit;
+  }
+
+  /** PARTIAL update: only the fields you send change. `tiers`, when sent, is
+   *  the complete new tier list. */
+  async update(id: string, input: UpdateUnitInput): Promise<Unit> {
+    const res = await this.transport.request<{ updated: true; unit: Unit }>({
+      method: "PATCH",
+      path: `/api/v1/units/${encodeURIComponent(id)}`,
+      body: input,
+    });
+    return res.unit;
+  }
+
+  /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+  async archive(id: string): Promise<Unit> {
+    const res = await this.transport.request<{ archived: true; unit: Unit }>({
+      method: "POST",
+      path: `/api/v1/units/${encodeURIComponent(id)}/archive`,
+      retry: true,
+    });
+    return res.unit;
+  }
+
+  /** Bring an archived one back (`isActive` → true). Safe to retry. */
+  async unarchive(id: string): Promise<Unit> {
+    const res = await this.transport.request<{ unarchived: true; unit: Unit }>({
+      method: "POST",
+      path: `/api/v1/units/${encodeURIComponent(id)}/unarchive`,
+      retry: true,
+    });
+    return res.unit;
+  }
+}