@clocknext/sdk 0.14.0 → 0.16.0

package/examples/node-basic.ts

@@ -1,12 +1,14 @@
 /**
  * Basic usage: record a few signals from a long-lived Node process.
- * Run with: CLOCKNEXT_API_KEY=cnk_… npx tsx examples/node-basic.ts
  *
  * Note the discovery step first. `customerId`, `model` and `agentKey` are not
  * strings you can invent — they name rows that must already exist in your
  * workspace, and a signal naming one that does not is rejected. So this example
- * reads them out of the API rather than hard-coding placeholders that are
- * guaranteed to 422 on someone else's workspace.
+ * reads the customer and its agent keys out of the API rather than hard-coding
+ * placeholders that are guaranteed to 422 on someone else's workspace. The
+ * model id comes from Settings → Models in the dashboard:
+ *
+ *   CLOCKNEXT_API_KEY=cnk_… CLOCKNEXT_MODEL=gpt-4o npx tsx examples/node-basic.ts
  */
 import { ClockNext } from "@clocknext/sdk";
 
@@ -18,34 +20,28 @@ const cnk = new ClockNext({
 });
 
 async function main() {
-  // 0. Ground the integration. Check WHICH workspace this key points at before
-  //    sending anything — a live key bills for real.
-  const { organization } = await cnk.workspace.me();
-  console.log(`workspace: ${organization.name} (${organization.environment})`);
-
-  // 1. Discover real ids instead of guessing them.
-  const [models, credits, customers] = await Promise.all([
-    cnk.workspace.models({ active: true }),
-    cnk.credits.list({ active: true }),
-    cnk.customers.list({ limit: 1 }),
-  ]);
-
-  const model = models[0];
-  const credit = credits[0];
-  const customer = customers.customers[0];
-  if (!model || !credit || !customer) {
+  // 1. Discover real ids instead of guessing them. A customer's balances list
+  //    every credit and outcome step its plan sells, each with its agentKey.
+  const model = process.env.CLOCKNEXT_MODEL;
+  const customer = (await cnk.customers.list({ limit: 1 })).customers[0];
+  if (!model || !customer) {
     throw new Error(
-      "This workspace needs at least one enabled model, one credit type, and one customer before it can meter anything.",
+      "Set CLOCKNEXT_MODEL to a model enabled under Settings → Models, and create at least one customer, before metering anything.",
     );
   }
-  console.log(`metering ${credit.agentKey} on ${model.modelId}`);
+  const balances = await cnk.customers.balances(customer.id);
+  const credit = balances.credits[0];
+  if (!credit) {
+    throw new Error("This customer's plan needs at least one credit before it can meter credit usage.");
+  }
+  console.log(`metering ${credit.agentKey} on ${model}`);
 
   // 2. Credit usage — metered against a credit by its stable `agentKey`, priced
   //    by tokens. Optionally group it into a composite occurrence, billed once
   //    on close.
   await cnk.signals.credit({
     customerId: customer.id,
-    model: model.modelId,
+    model,
     agentKey: credit.agentKey,
     tokens: { input: 1200, output: 340, cache: 0 },
     custom: { feature: "summarize", tier: "pro" },
@@ -54,23 +50,19 @@ async function main() {
   // 3. Wallet usage (debits the customer's USD wallet at model cost).
   await cnk.signals.wallet({
     customerId: customer.id,
-    model: model.modelId,
+    model,
     tokens: { input: 800, output: 5000 },
   });
 
   // 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.
-  const outcomeRow = (await cnk.outcomes.list({ active: true }))[0];
-  const outcome = outcomeRow ? await cnk.outcomes.get(outcomeRow.id) : undefined;
+  //    `agentKey` is the OutcomeStep's key, read off the same balances.
+  const outcome = balances.outcomes[0];
   if (outcome?.steps[0]) {
     const runId = `demo_run_${Date.now()}`;
     await cnk.signals.outcome({
       customerId: customer.id,
-      model: model.modelId,
+      model,
       agentKey: outcome.steps[0].agentKey,
       runId,
       tokens: { input: 600, output: 150 },
@@ -83,8 +75,8 @@ async function main() {
   //    asynchronous, so this — not the track() return value — is what proves a
   //    signal actually landed.
   await cnk.flush();
-  const usage = await cnk.signals.list({ customerId: customer.id, limit: 10 });
-  console.log("recent logs:", usage.logs.length, "totals:", usage.totals);
+  const page = await cnk.signals.usageLog({ customerId: customer.id, limit: 10 });
+  console.log("recent logs:", page.usageLogs.length);
 
   await cnk.close();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clocknext/sdk",
-  "version": "0.14.0",
+  "version": "0.16.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

@@ -12,8 +12,6 @@ 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 { Webhooks } from "./resources/webhooks.js";
-import { Workspace } from "./resources/workspace.js";
 import type { ClockNextConfig, ResolvedConfig } from "./types.js";
 
 /**
@@ -34,32 +32,28 @@ import type { ClockNextConfig, ResolvedConfig } from "./types.js";
  * ```
  */
 export class ClockNext {
-  /** Record + read usage signals (credit / wallet / outcome / unit). */
+  /** Record usage signals (credit / wallet / outcome / unit) and read the usage log. */
   readonly signals: Signals;
-  /** Manage customers, their members, wallet, and balances. */
+  /** Manage customers, their members, and balances. */
   readonly customers: Customers;
-  /** Define and manage 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. */
   readonly invoices: Invoices;
   /** Read payments (paid invoices). */
   readonly payments: Payments;
-  /** Manage the credit-type catalog. */
-  readonly credits: Credits;
-  /** Manage the composite catalog — bundles billed as one thing. */
-  readonly composites: Composites;
-  /** Manage the outcome-type catalog. */
-  readonly outcomes: Outcomes;
-  /** Manage the unit-type catalog. */
-  readonly units: Units;
-  /** Configure threshold webhooks. */
-  readonly webhooks: Webhooks;
   /** Mint customer-portal embed tokens. */
   readonly portal: Portal;
-  /** Identify the workspace (sandbox/live) + list its models. `/me`, `/models`. */
-  readonly workspace: Workspace;
 
   private readonly cfg: ResolvedConfig;
   private readonly flusher: Flusher;
@@ -78,16 +72,14 @@ export class ClockNext {
     this.signals = new Signals(transport, this.flusher, this.cfg);
     this.customers = new Customers(transport);
     this.plans = new Plans(transport);
-    this.purchases = new Purchases(transport);
-    this.invoices = new Invoices(transport);
-    this.payments = new Payments(transport);
     this.credits = new Credits(transport);
-    this.composites = new Composites(transport);
     this.outcomes = new Outcomes(transport);
     this.units = new Units(transport);
-    this.webhooks = new Webhooks(transport);
+    this.composites = new Composites(transport);
+    this.purchases = new Purchases(transport);
+    this.invoices = new Invoices(transport);
+    this.payments = new Payments(transport);
     this.portal = new Portal(transport);
-    this.workspace = new Workspace(transport);
   }
 
   /** Number of signals currently buffered (async mode). */

package/src/customer-ref.ts

@@ -0,0 +1,14 @@
+/**
+ * The customer half of a request body: `customerId` and/or `externalId`,
+ * each only when set. Both are forwarded as given — the server applies the
+ * precedence (`customerId` wins), so the SDK never second-guesses it.
+ */
+export function customerRefToWire(ref: {
+  customerId?: string;
+  externalId?: string;
+}): { customerId?: string; externalId?: string } {
+  return {
+    ...(ref.customerId != null ? { customerId: ref.customerId } : {}),
+    ...(ref.externalId != null ? { externalId: ref.externalId } : {}),
+  };
+}

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).
@@ -154,7 +155,11 @@ export function translateFieldPaths(message: string): string {
  * toward it still classifies, never as the sole test.
  */
 const ALLOWANCE_MESSAGE =
-  /\binsufficient\b|\bno allowance left\b|\bno slots left\b|\boutcomes remaining\b|\btop up the (?:allowance|balance)\b/i;
+  /\binsufficient\b|\bno allowance left\b|\bno slots left\b|\boutcomes remaining\b|\btop up the (?:allowance|balance)\b|\bbelow zero\b/i;
+
+/** The adjust API's 422 for an idempotency key reused with a DIFFERENT
+ *  request. A conflict, not a plan problem — and never worth retrying. */
+const IDEMPOTENCY_KEY_REUSED = /\bidempotency key was already used\b/i;
 
 export function isAllowanceFailure(message: string, code?: string): boolean {
   if (code) return code === "ALLOWANCE_EXHAUSTED";
@@ -205,6 +210,9 @@ export function errorFromResponse(
     });
   }
   if (status === 422) {
+    if (IDEMPOTENCY_KEY_REUSED.test(raw)) {
+      return new ConflictError(raw, { ...opts, retryable: false });
+    }
     return isAllowanceFailure(raw, code)
       ? new AllowanceError(raw, opts)
       : new PlanError(raw, opts);

package/src/filters.ts

@@ -1,5 +1,5 @@
 /**
- * The `active` list filter, shared by every catalog resource.
+ * The `active` list filter, used by `plans.list()`.
  *
  * The API offers exactly ONE filter: `?active=true` narrows a list to active
  * rows. There is no inactive-only parameter — the server tests

package/src/index.ts

@@ -47,7 +47,6 @@ export type {
   OutcomeCompletionInput,
   OutcomeCompletionResult,
   TrackResult,
-  UsageList,
   SerializedUsageLog,
   UsageBalance,
   SerializedRuleApplication,
@@ -56,8 +55,6 @@ export type {
   UnitTrackResult,
   CompositeCompletionInput,
   CompositeCompletionResult,
-  UnitUsageRow,
-  UnitUsageList,
   SerializedUnitUsage,
   UsageLogPeriod,
   UsageLogListParams,
@@ -65,10 +62,8 @@ export type {
   UsageLogOutcomeAttribution,
   UsageLogEntry,
   UsageLogPage,
-  // workspace
-  WorkspaceIdentity,
-  Model,
   // customers
+  CustomerRef,
   ApiCustomer,
   CustomerProfileInput,
   CreateCustomerInput,
@@ -77,6 +72,7 @@ export type {
   CreditBalance,
   OutcomeBalance,
   UnitBalance,
+  CompositeBalance,
   CustomerPlan,
   CustomerPlanDetails,
   // members
@@ -85,30 +81,44 @@ export type {
   RemovedMember,
   AddMemberInput,
   UpdateMemberInput,
-  // wallet & balance adjustments
-  WalletTransaction,
-  WalletTransactionType,
-  WalletTransactionSource,
-  WalletEntitlementKind,
-  WalletList,
-  WalletEntryInput,
+  // balance adjustments
+  WalletAdjustInput,
+  AdjustResult,
+  WalletPool,
   CreditAdjustInput,
   OutcomeAdjustInput,
   UnitAdjustInput,
   CompositeAdjustInput,
+  RecurringGrantInput,
+  RecurringGrantResult,
   // plans
   Plan,
-  PlanDetail,
-  PlanComponent,
-  PlanComponentInput,
-  WalletComponentInput,
-  FlatComponentInput,
-  CreditComponentInput,
-  OutcomeComponentInput,
-  UnitComponentInput,
-  CompositeComponentInput,
+  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,
   PlanKind,
@@ -132,42 +142,6 @@ export type {
   // payments
   PaymentRow,
   PaymentDetail,
-  // cost analytics (credits / outcomes)
-  CostPoint,
-  CostStats,
-  CreditAnalytics,
-  OutcomeAnalytics,
-  // credits catalog
-  Credit,
-  CreditDetail,
-  CreateCreditInput,
-  UpdateCreditInput,
-  ModelBundleEntry,
-  // outcomes catalog
-  Outcome,
-  OutcomeDetail,
-  OutcomeStepInput,
-  CreateOutcomeInput,
-  UpdateOutcomeInput,
-  // composites catalog
-  Composite,
-  CompositeCatalogueRef,
-  CreateCompositeInput,
-  // units catalog
-  Unit,
-  UnitDetail,
-  UnitCustomerRow,
-  UnitTier,
-  UnitTierInput,
-  UnitPricingType,
-  CreateUnitInput,
-  FlatUnitInput,
-  TieredUnitInput,
-  UpdateUnitInput,
-  // webhooks
-  Webhook,
-  UpsertWebhookInput,
-  ThresholdKind,
   // portal
   PortalTokenInput,
   PortalToken,

package/src/resources/composites.ts

@@ -1,31 +1,24 @@
 import { activeQuery, filterByActive } from "../filters.js";
 import type { Transport } from "../http.js";
-import type { Composite, CreateCompositeInput } from "../types.js";
+import type { Composite, CreateCompositeInput, UpdateCompositeInput } from "../types.js";
 
 /**
- * The `composites` resource — manage the org's composite *catalogue*: the
- * bundles of credits / outcomes / units that are grouped under one tag and
- * sold on a plan as a single thing. `/api/v1/composites`.
+ * The `composites` resource — several credits / outcomes / units grouped under
+ * one tag (`refId`) and billed as ONE thing per completed occurrence.
+ * `/api/v1/composites`.
  *
- * Two things live elsewhere, deliberately:
- *   • Tagging a signal into a composite occurrence is `composite: { ref, value }`
- *     on the signal itself (see `signals.credit()` / `.outcome()` / `.unit()`).
- *   • Closing an occurrence — the moment it is billed — is
- *     `signals.completeComposite()`.
+ * Creating a composite charges nobody: it only bills once a plan sells it as
+ * a `PRICING_METRIC` entitlement (`plans.create()` with its `compositeId`).
  *
- * This resource only defines what composites EXIST. Creating one prices it but
- * charges nobody: an invoice is built from plan components, never from a
- * catalogue entry, so a composite starts costing money only once a plan sells
- * it (`quantity × price`, frozen into the purchase at buy time).
+ * 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 composites. Pass `{ active: true }` for only the ones a signal can
-   *  still be tagged with — the default list INCLUDES archived ones, which
-   *  keep every row they already own.
-   *  `{ active: false }` returns only archived ones; omitting it returns
-   *  both. See `activeQuery` — the API itself only supports `true`. */
+  /** 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",
@@ -35,13 +28,55 @@ export class Composites {
     return filterByActive(res.composites, params.active);
   }
 
-  /** Create a composite. `POST /api/v1/composites`. */
-  async create(input: CreateCompositeInput): Promise<Composite> {
+  /** 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

@@ -1,23 +1,24 @@
 import { activeQuery, filterByActive } from "../filters.js";
 import type { Transport } from "../http.js";
-import type {
-  CreateCreditInput,
-  Credit,
-  CreditDetail,
-  UpdateCreditInput,
-} from "../types.js";
+import type { CreateCreditInput, Credit, UpdateCreditInput } from "../types.js";
 
 /**
- * The `credits` resource — manage the org's credit *types* (the catalog). A
- * credit's stable `agentKey` is what you pass to `signals.credit()` when
- * recording usage against it. `/api/v1/credits`.
+ * 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 credit types. Pass `{ active: true }` to only return active ones.
-   *  `{ active: false }` returns only archived ones; omitting it returns
-   *  both. See `activeQuery` — the API itself only supports `true`. */
+  /** 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",
@@ -27,28 +28,30 @@ export class Credits {
     return filterByActive(res.credits, params.active);
   }
 
-  /** Create a credit type; returns the created credit. `POST /api/v1/credits`. */
-  async create(input: CreateCreditInput): Promise<Credit> {
+  /** One credit's configuration. */
+  async get(id: string): Promise<Credit> {
     const res = await this.transport.request<{ credit: Credit }>({
-      method: "POST",
-      path: "/api/v1/credits",
-      body: input,
+      method: "GET",
+      path: `/api/v1/credits/${encodeURIComponent(id)}`,
     });
     return res.credit;
   }
 
-  /** Fetch one credit type with usage stats. `GET /api/v1/credits/:id`. */
-  async get(id: string): Promise<CreditDetail> {
-    const res = await this.transport.request<{ credit: CreditDetail }>({
-      method: "GET",
-      path: `/api/v1/credits/${encodeURIComponent(id)}`,
+  /** 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;
   }
 
-  /** Update a credit type's definition; returns the updated credit. `PATCH /api/v1/credits/:id`. */
+  /** 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<{ credit: Credit }>({
+    const res = await this.transport.request<{ updated: true; credit: Credit }>({
       method: "PATCH",
       path: `/api/v1/credits/${encodeURIComponent(id)}`,
       body: input,
@@ -56,21 +59,23 @@ export class Credits {
     return res.credit;
   }
 
-  /** Activate or deactivate a credit type. */
-  async setActive(id: string, isActive: boolean): Promise<Credit> {
-    const res = await this.transport.request<{ credit: Credit }>({
-      method: "PATCH",
-      path: `/api/v1/credits/${encodeURIComponent(id)}`,
-      body: { isActive },
+  /** 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;
   }
 
-  /** Delete a credit type. Refused while a customer is linked to it. */
-  async delete(id: string): Promise<void> {
-    await this.transport.request({
-      method: "DELETE",
-      path: `/api/v1/credits/${encodeURIComponent(id)}`,
+  /** 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;
   }
 }