@clocknext/sdk 0.13.0 → 0.15.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.13.0",
+  "version": "0.15.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,19 +1,13 @@
 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 { Webhooks } from "./resources/webhooks.js";
-import { Workspace } from "./resources/workspace.js";
 import type { ClockNextConfig, ResolvedConfig } from "./types.js";
 
 /**
@@ -34,11 +28,11 @@ 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. */
+  /** List billing plans. */
   readonly plans: Plans;
   /** Subscribe customers to plans (purchases). */
   readonly purchases: Purchases;
@@ -46,20 +40,8 @@ export class ClockNext {
   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;
@@ -81,13 +63,7 @@ export class ClockNext {
     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.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

@@ -154,7 +154,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 +209,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,13 +55,15 @@ export type {
   UnitTrackResult,
   CompositeCompletionInput,
   CompositeCompletionResult,
-  UnitUsageRow,
-  UnitUsageList,
   SerializedUnitUsage,
-  // workspace
-  WorkspaceIdentity,
-  Model,
+  UsageLogPeriod,
+  UsageLogListParams,
+  UsageLogAppliedRule,
+  UsageLogOutcomeAttribution,
+  UsageLogEntry,
+  UsageLogPage,
   // customers
+  CustomerRef,
   ApiCustomer,
   CustomerProfileInput,
   CreateCustomerInput,
@@ -79,30 +80,19 @@ 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,
-  CreatePlanInput,
-  UpdatePlanInput,
   BillingCycle,
   PlanType,
   PlanKind,
@@ -126,42 +116,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,