@clocknext/sdk 0.13.0 → 0.15.0

package/src/types.ts

@@ -65,42 +65,40 @@ export interface CompositeTag {
 }
 
 // ---------------------------------------------------------------------------
-// Workspace (mirrors GET /api/v1/me and GET /api/v1/models)
+// Naming a customer
 // ---------------------------------------------------------------------------
 
-/** The organisation + key behind a request — `cnk.workspace.me()`. */
-export interface WorkspaceIdentity {
-  organization: {
-    id: string;
-    name: string;
-    slug: string | null;
-    /** `sandbox` is a disposable staging twin; `live` bills for real. Check
-     *  this before sending production traffic. */
-    environment: "sandbox" | "live";
-  };
-  apiKey: {
-    prefix: string;
-    lastFour: string;
-    expiresAt: string | null;
-  } | null;
-}
+/**
+ * How a request names its customer: by OUR id (`customerId`) or by YOUR id for
+ * them (`externalId` — the value set on the customer via
+ * `customers.create()` / `customers.update()`). At least one is required.
+ *
+ * When both are sent, `customerId` wins and `externalId` is ignored — the
+ * server does not check that they agree. An `externalId` matching no active
+ * customer is a `NotFoundError` (or, on an async signal, leaves it Pending
+ * with that reason — retry once the customer exists).
+ */
+export type CustomerRef =
+  | {
+      /** Our customer id. Wins over `externalId` when both are sent. */
+      customerId: string;
+      externalId?: string;
+    }
+  | {
+      customerId?: undefined;
+      /** Your id for the customer: 1–32 letters, numbers or "-", matched
+       *  exactly (case-sensitive). */
+      externalId: string;
+    };
 
-/** One model the org has enabled — `cnk.workspace.models()`. The `modelId` is
- *  what you put in a signal's `model`. Prices are USD per 1,000,000 tokens. */
-export interface Model {
-  modelId: string;
-  modelName: string;
-  provider: string;
-  providerName: string;
-  isActive: boolean;
-  inputPrice: number;
-  outputPrice: number;
-  cachePrice: number;
-}
+/** `Omit` that keeps a union a union (plain `Omit` flattens it to the
+ *  members' shared keys, losing the {@link CustomerRef} either/or). */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown
+  ? Omit<T, K>
+  : never;
 
-interface SignalBase {
-  /** The customer this usage belongs to (required). */
-  customerId: string;
+/** Every signal names its customer — see {@link CustomerRef}. */
+interface SignalFields {
   /**
    * The model's catalog id — must be enabled in your ClockNext org
    * (Settings → Models). Matched case-insensitively against `OrgModel.modelId`.
@@ -123,19 +121,21 @@ interface SignalBase {
   idempotencyKey?: string;
 }
 
+type SignalBase = CustomerRef & SignalFields;
+
 /** Meters a credit, identified by the credit's stable `agentKey`. */
-export interface CreditSignal extends SignalBase {
+export type CreditSignal = SignalBase & {
   type: "credit";
   /** The Credit's stable agent key (assigned when the credit was created). */
   agentKey: string;
   /** Optional composite this signal belongs to. See {@link CompositeTag}. */
   composite?: CompositeTag;
-}
+};
 
 /** Debits the customer's wallet in USD at the model's cost. */
-export interface WalletSignal extends SignalBase {
+export type WalletSignal = SignalBase & {
   type: "wallet";
-}
+};
 
 /**
  * Records one step of a multi-call outcome run. The `agentKey` identifies the
@@ -149,7 +149,7 @@ export interface WalletSignal extends SignalBase {
  * carries `complete` — see {@link OutcomeCompletionInput} /
  * `signals.completeOutcome()`, its own dedicated route.
  */
-export interface OutcomeSignal extends SignalBase {
+export type OutcomeSignal = SignalBase & {
   type: "outcome";
   /** The OutcomeStep's stable agent key — identifies the outcome AND the step. */
   agentKey: string;
@@ -161,14 +161,14 @@ export interface OutcomeSignal extends SignalBase {
   runId: string;
   /** Optional composite this signal belongs to. See {@link CompositeTag}. */
   composite?: CompositeTag;
-}
+};
 
 export type Signal = CreditSignal | WalletSignal | OutcomeSignal;
 
 /** Helper input shapes for the per-type convenience methods. */
-export type CreditInput = Omit<CreditSignal, "type">;
-export type WalletInput = Omit<WalletSignal, "type">;
-export type OutcomeInput = Omit<OutcomeSignal, "type">;
+export type CreditInput = DistributiveOmit<CreditSignal, "type">;
+export type WalletInput = DistributiveOmit<WalletSignal, "type">;
+export type OutcomeInput = DistributiveOmit<OutcomeSignal, "type">;
 
 /**
  * Input for `signals.completeOutcome()` — closes ONE outcome run, the outcome
@@ -181,17 +181,17 @@ export type OutcomeInput = Omit<OutcomeSignal, "type">;
  * `signals.completeComposite()` — the two completions are independent, and
  * neither implies the other.
  */
-export interface OutcomeCompletionInput {
-  customerId: string;
+export type OutcomeCompletionInput = CustomerRef & {
   /** 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. */
+  /** Idempotency key, auto-generated if omitted. Sending this completion 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()`.
@@ -304,7 +304,7 @@ export interface SerializedUsageLog {
  * exhausted allowance is detected by the worker LATER and never surfaces here —
  * the signal is simply dropped. A `202` therefore means "accepted", never
  * "recorded". To confirm a signal actually landed, read it back with
- * `signals.list({ customerId })`.
+ * `signals.usageLog({ customerId })`.
  *
  * When the server has no queue configured it prices inline instead and returns
  * `queued: false` with a populated `usageLog`, validating synchronously.
@@ -327,7 +327,7 @@ export interface TrackResult {
    *                  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,
-   *                  nor on `onError`. `signals.list()` shows what got priced;
+   *                  nor on `onError`. `signals.usageLog()` 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.
@@ -373,16 +373,84 @@ export interface TrackResult {
   rawId?: string;
 }
 
-export interface UsageList {
-  customer: { id: string; name: string; creditAllowance: number };
-  totals: {
-    count: number;
-    cost: number;
-    revenue: number;
-    profit: number;
-    creditsUsed: number;
-  };
-  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;
 }
 
 // ---------------------------------------------------------------------------
@@ -391,6 +459,9 @@ export interface UsageList {
 
 export interface ApiCustomer {
   id: string;
+  /** Your own id for this customer, or `null` when unset. See
+   *  {@link CustomerProfileInput.externalId}. */
+  externalId: string | null;
   slug: string;
   name: string;
   description: string | null;
@@ -406,12 +477,24 @@ export interface ApiCustomer {
   taxId: string | null;
   currencyCode: string;
   creditAllowance: number;
+  recurringTransactionEmail: boolean;
+  autoRecurring: boolean;
   createdAt: string;
   updatedAt: string;
 }
 
 /** Writable customer profile fields. `null` clears a column; omit to leave it. */
 export interface CustomerProfileInput {
+  /**
+   * The id YOUR product uses for this customer: 1–32 letters, numbers or "-",
+   * case-sensitive. Unique among the org's active customers (a clash is a
+   * `ConflictError`; an archived customer's id can be reused). Once set,
+   * signals and `purchases.create()` can take `externalId` instead of
+   * `customerId`, and `customers.getByExternalId()` / `updateByExternalId()` /
+   * `updateRecurringGrantByExternalId()` address the customer by it. `null`
+   * clears it on update.
+   */
+  externalId?: string | null;
   name?: string;
   description?: string | null;
   email?: string | null;
@@ -426,6 +509,10 @@ export interface CustomerProfileInput {
   taxId?: string | null;
   /** ISO 4217 (3 letters); must be enabled for the org. */
   currencyCode?: string;
+  /** Send the invoice, payment receipt and card-payment-failed emails for recurring invoices. Defaults to `true` on create. */
+  recurringTransactionEmail?: boolean;
+  /** Issue every recurring invoice as `AUTO_CLOSED` (applied as if paid, never payable). Defaults to `false` on create. */
+  autoRecurring?: boolean;
 }
 
 /** `name` and `email` are required on create; every other field is optional. */
@@ -461,7 +548,7 @@ export interface OutcomeBalance {
   remaining: number;
   /** Each step's `agentKey` is what `signals.outcome()` and the outcome adjust
    *  API use to address this outcome at runtime. The outcome also has its own
-   *  separate key ({@link Outcome.agentKey}), but neither of those APIs accepts
+   *  separate key (the outcome's own `agentKey`), but neither of those APIs accepts
    *  it — it identifies the outcome in the catalogue, not in a signal. */
   steps: { id: string; name: string; agentKey: string }[];
 }
@@ -483,7 +570,11 @@ export interface CustomerBalances {
   customerId: string;
   currency: { code: string; rateUsd: number };
   hasPlan: boolean;
+  /** `null` when the plan has no Wallet component. */
   wallet: { balanceUsd: number } | null;
+  /** The Reserved Wallet; `null` when the org hasn't enabled it. Independent
+   *  of `wallet` — present whether or not the plan has a Wallet. */
+  reservedWallet: { balanceUsd: number } | null;
   credits: CreditBalance[];
   outcomes: OutcomeBalance[];
   units: UnitBalance[];
@@ -545,7 +636,6 @@ export type BillingCycle =
   | "FREE";
 export type PlanType = "WALLET" | "BUNDLE";
 export type PlanKind = "FLAT_PRICE" | "PAY_AS_YOU_GO" | "PAY_PER_SEAT";
-/** A plan component's meter type. */
 /**
  * A plan component's kind.
  *
@@ -564,109 +654,6 @@ export type ComponentType =
 /** ADVANCE bills up-front for the cycle; ARREAR bills for what was consumed. */
 export type BillingMode = "ADVANCE" | "ARREAR";
 
-/** Prepaid USD wallet. `amount` is the funded balance (required). Max one
- *  wallet component per plan. */
-export interface WalletComponentInput {
-  type: "WALLET";
-  billingMode: BillingMode;
-  amount: number;
-}
-
-/** A one-off flat fee — `amount` is required. Max one flat component per plan;
- *  not allowed on FREE plans. */
-export interface FlatComponentInput {
-  type: "FLAT";
-  billingMode: BillingMode;
-  amount: number;
-}
-
-/** A credit entitlement, referenced by `creditId`. Billed ADVANCE it needs a
- *  granted `quantity`; billed ARREAR it meters usage with no upfront grant. */
-export type CreditComponentInput =
-  | { type: "CREDIT"; billingMode: "ADVANCE"; creditId: string; quantity: number }
-  | { type: "CREDIT"; billingMode: "ARREAR"; creditId: string; quantity?: number | null };
-
-/** An outcome entitlement, referenced by `outcomeId`. ADVANCE needs a granted
- *  `quantity`; ARREAR meters usage. */
-export type OutcomeComponentInput =
-  | { type: "OUTCOME"; billingMode: "ADVANCE"; outcomeId: string; quantity: number }
-  | { type: "OUTCOME"; billingMode: "ARREAR"; outcomeId: string; quantity?: number | null };
-
-/** A unit entitlement, referenced by `unitId`. ADVANCE needs a granted
- *  `quantity`; ARREAR meters usage. */
-export type UnitComponentInput =
-  | { type: "UNIT"; billingMode: "ADVANCE"; unitId: string; quantity: number }
-  | { type: "UNIT"; billingMode: "ARREAR"; unitId: string; quantity?: number | null };
-
-/**
- * A COMPOSITE sold on the plan, referenced by `pricingMetricId` (the id from
- * `composites.list()`). This is the line that makes a composite bill: the
- * catalogue entry on its own charges nobody, and this component is what turns
- * it into money — `quantity × the composite's price`, frozen into the purchase
- * snapshot at buy time.
- *
- * The two billing modes differ in what `quantity` means:
- *   - **ADVANCE** — a PREPAID POOL of `quantity` flat-rate slots, shared
- *     across whichever credits / outcomes / units the composite wraps. Each
- *     distinct tag value claims one slot on completion; repeat signals under a
- *     value reuse the slot they already claimed, at no extra cost. Once every
- *     slot is claimed, further occurrences are refused rather than billed.
- *   - **ARREAR** — nothing prepaid; completed occurrences are counted on the
- *     cycle-end line.
- *
- * `type` is the wire value `"PRICING_METRIC"`, not `"COMPOSITE"`: the product
- * word changed but the stored enum did not, and the API still speaks the old
- * one. That mismatch is the server's, and it is surfaced rather than hidden so
- * a response and a request read the same.
- */
-export type CompositeComponentInput =
-  | {
-      type: "PRICING_METRIC";
-      billingMode: "ADVANCE";
-      pricingMetricId: string;
-      quantity: number;
-    }
-  | {
-      type: "PRICING_METRIC";
-      billingMode: "ARREAR";
-      pricingMetricId: string;
-      quantity?: number | null;
-    };
-
-/**
- * One entitlement line in a plan — a discriminated union on `type` (and, where
- * it matters, `billingMode`) so the per-type fields the server requires are
- * enforced at compile time instead of surfacing as runtime 422s:
- *   - CREDIT / OUTCOME / UNIT require their matching id;
- *   - PRICING_METRIC (a composite) requires `pricingMetricId`;
- *   - CREDIT / OUTCOME / UNIT / PRICING_METRIC require `quantity` when billed
- *     ADVANCE;
- *   - WALLET / FLAT require `amount`.
- */
-export type PlanComponentInput =
-  | WalletComponentInput
-  | FlatComponentInput
-  | CreditComponentInput
-  | OutcomeComponentInput
-  | UnitComponentInput
-  | CompositeComponentInput;
-
-export interface CreatePlanInput {
-  name: string;
-  description?: string | null;
-  billingCycle: BillingCycle;
-  /** Carry an unused balance into the next cycle. Default true. */
-  carryForward?: boolean;
-  /** ISO 4217 (3 letters). Default "USD". */
-  currencyCode?: string;
-  isActive?: boolean;
-  /** At least one component. FREE plans must be ADVANCE-only with no FLAT component. */
-  components: PlanComponentInput[];
-}
-
-/** A full-rewrite update carries the complete plan (same shape as create). */
-export type UpdatePlanInput = CreatePlanInput;
-
 export interface PlanComponent {
   id: string;
   type: ComponentType;
@@ -674,11 +661,9 @@ export interface PlanComponent {
   creditId: string | null;
   outcomeId: string | null;
   unitId: string | null;
-  /** The composite this component sells, on a `PRICING_METRIC` component.
-   *  Without it a plan read back could not be written back: the write shape
-   *  ({@link CompositeComponentInput}) requires this id, so a read-modify-write
-   *  silently dropped every composite component. */
-  pricingMetricId: string | null;
+  /** The id of the composite this component sells, on a `PRICING_METRIC`
+   *  component. */
+  compositeId: string | null;
   targetName: string | null;
   quantity: number | null;
   amount: number | null;
@@ -702,24 +687,13 @@ export interface Plan {
   components: PlanComponent[];
 }
 
-/** The richer plan returned by `plans.get()` (adds aggregate stats). */
-export interface PlanDetail extends Plan {
-  createdAt: string;
-  createdByName: string | null;
-  customerCount: number;
-  invoiceCount: number;
-  openInvoiceCount: number;
-  stats: { totalInvoiced: number; totalCollected: number; openBalance: number };
-}
-
 // ---------------------------------------------------------------------------
 // Purchases (subscriptions)
 // ---------------------------------------------------------------------------
 
 export type PurchaseStatus = "SCHEDULED" | "ACTIVE" | "CANCELLED";
 
-export interface CreatePurchaseInput {
-  customerId: string;
+export type CreatePurchaseInput = CustomerRef & {
   planId: string;
   /** `YYYY-MM-DD`. Defaults to today; must be a valid non-past date. */
   billingDate?: string;
@@ -727,7 +701,7 @@ export interface CreatePurchaseInput {
   autoPayment?: boolean;
   /** Auto-void the purchase if unpaid after N minutes. */
   voidAfterMinutes?: number;
-}
+};
 
 export interface Purchase {
   id: string;
@@ -783,7 +757,9 @@ export interface PurchaseDetail {
 // Invoices & Payments
 // ---------------------------------------------------------------------------
 
-export type InvoiceStatus = "OPEN" | "PAID" | "VOID";
+/** `AUTO_CLOSED` — a recurring invoice for a customer with `autoRecurring` on:
+ *  applied as if paid, but never payable. */
+export type InvoiceStatus = "OPEN" | "PAID" | "VOID" | "AUTO_CLOSED";
 
 /** Trimmed row from `invoices.list()`. */
 export interface InvoiceListRow {
@@ -968,78 +944,82 @@ export interface UpdateMemberInput {
 }
 
 // ---------------------------------------------------------------------------
-// Wallet & balance adjustments (customer-scoped)
+// Balance adjustments (customer-scoped)
 // ---------------------------------------------------------------------------
 
-export type WalletTransactionType = "CREDIT" | "DEBIT";
-
-/** What produced a wallet entry. `null` on rows written before the column
- *  existed. */
-export type WalletTransactionSource =
-  | "TOPUP"
-  | "USAGE"
-  | "SETTLE"
-  | "ADJUSTMENT";
-
-/** The entitlement kinds a wallet-funded metering debit can name. */
-export type WalletEntitlementKind = "CREDIT" | "OUTCOME" | "UNIT";
-
-export interface WalletTransaction {
-  id: string;
-  type: WalletTransactionType;
-  /** What produced the entry. Null on rows older than the column. */
-  source: WalletTransactionSource | null;
-  amount: number;
-  amountUsd: number;
-  currencyCode: string;
-  currencyRateUsd: number;
-  notes: string | null;
-  batchId: string | null;
-  createdAt: string;
-  createdByName: string | null;
-  /** Set only on a wallet-funded metering debit: which kind of entitlement was
-   *  consumed. Null on top-ups and manual adjustments. */
-  entitlementType: WalletEntitlementKind | null;
-  /** Id of the credit / outcome / unit consumed. Null unless
-   *  `entitlementType` is set. */
-  targetId: string | null;
-  /** Its name at the time of the debit. */
-  targetName: string | null;
-  /** The signal this debit paid for (credit / outcome). In wallet-funded mode
-   *  no invoice exists, so this is the only trail from a charge to its cause. */
-  usageLogId: string | null;
-  /** The unit event this debit paid for. */
-  unitUsageLogId: string | null;
-}
-
-export interface WalletList {
-  balanceUsd: number;
-  transactions: WalletTransaction[];
-}
-
-export interface WalletEntryInput {
-  /** DEBIT spends, CREDIT tops up. */
-  type: WalletTransactionType;
-  /** Always positive; the sign comes from `type`. */
-  amount: number;
+/**
+ * Which of a customer's two wallet balances an entry moves: `MAIN` (the
+ * ordinary wallet) or `RESERVED` (the Reserved Wallet — an org-gated second
+ * balance behind it; see {@link WalletAdjustInput.pool}).
+ */
+export type WalletPool = "MAIN" | "RESERVED";
+
+/** Top up (positive) or draw down (negative) a customer's wallet. `delta` is
+ *  a non-zero amount in USD (cents allowed); absolute value ≤ 10,000,000. No
+ *  `agentKey` — a customer has exactly one wallet. The wallet can always be
+ *  adjusted, whatever the customer's plan (even with no plan). A draw-down is
+ *  never rejected or floored for going below 0 — the wallet may read negative. */
+export interface WalletAdjustInput {
+  /** Signed change in USD: positive tops up, negative draws down. */
+  delta: number;
   notes?: string;
+  /**
+   * Which balance to move. Default `"MAIN"`, the ordinary wallet.
+   *
+   * `"RESERVED"` moves the Reserved Wallet instead — a second balance behind
+   * the wallet that a wallet-funded Arrear charge draws on once the wallet
+   * runs out (Wallet → Reserved down to 0 → Wallet goes negative). It must be
+   * switched on for the org (Settings → Organisation → "Enable Reserved
+   * balance in wallet"), else this is a `PlanError`. It never goes negative:
+   * a reduce below zero is refused (an `AllowanceError`), not capped — drawing
+   * down to exactly 0 is fine. `remaining` is then the Reserved balance. A
+   * `"MAIN"` adjustment never touches it.
+   */
+  pool?: WalletPool;
+  /**
+   * Optional idempotency key (1–255 characters) that makes this adjustment
+   * safe to retry. The first call with a key adjusts; any repeat with the
+   * same key and the same request adjusts nothing and comes back with
+   * `replayed: true` (and when the original happened, `adjustedAt`). The same
+   * key with a different request is a `ConflictError`. Keys are unique per
+   * workspace and per adjust endpoint. **Auto-generated (UUID v4) if
+   * omitted** and reused across every retry of this call, so a network blip
+   * never adjusts twice — same as signals. Supply your own (e.g. your order
+   * id) to also dedupe your OWN retries, across restarts or redelivery.
+   */
+  idempotencyKey?: string;
 }
 
 /** 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`. 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. */
+ *  non-zero whole number. The credit is addressed by its stable `agentKey`,
+ *  and must be a prepaid (ADVANCE) part of the customer's current plan — else
+ *  a `PlanError` ("… is not part of this customer's plan"). 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;
   delta: number;
   notes?: string;
+  /**
+   * Optional idempotency key (1–255 characters) that makes this adjustment
+   * safe to retry. The first call with a key adjusts; any repeat with the
+   * same key and the same request adjusts nothing and comes back with
+   * `replayed: true` (and when the original happened, `adjustedAt`). The same
+   * key with a different request is a `ConflictError`. Keys are unique per
+   * workspace and per adjust endpoint. **Auto-generated (UUID v4) if
+   * omitted** and reused across every retry of this call, so a network blip
+   * never adjusts twice — same as signals. Supply your own (e.g. your order
+   * id) to also dedupe your OWN retries, across restarts or redelivery.
+   */
+  idempotencyKey?: string;
 }
 
 /** 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. A reduce is never rejected or floored
+ *  parent outcome — NOT by the outcome's own `agentKey`,
+ *  which this endpoint does not accept. The outcome must be a prepaid
+ *  (ADVANCE) part of the customer's current plan — else a `PlanError`. 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 {
@@ -1048,17 +1028,42 @@ export interface OutcomeAdjustInput {
   agentKey: string;
   delta: number;
   notes?: string;
+  /**
+   * Optional idempotency key (1–255 characters) that makes this adjustment
+   * safe to retry. The first call with a key adjusts; any repeat with the
+   * same key and the same request adjusts nothing and comes back with
+   * `replayed: true` (and when the original happened, `adjustedAt`). The same
+   * key with a different request is a `ConflictError`. Keys are unique per
+   * workspace and per adjust endpoint. **Auto-generated (UUID v4) if
+   * omitted** and reused across every retry of this call, so a network blip
+   * never adjusts twice — same as signals. Supply your own (e.g. your order
+   * id) to also dedupe your OWN retries, across restarts or redelivery.
+   */
+  idempotencyKey?: string;
 }
 
 /** 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. */
+ *  unit is addressed by its stable `agentKey`, and must be a prepaid
+ *  (ADVANCE) part of the customer's current plan — else a `PlanError`. 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;
   delta: number;
   notes?: string;
+  /**
+   * Optional idempotency key (1–255 characters) that makes this adjustment
+   * safe to retry. The first call with a key adjusts; any repeat with the
+   * same key and the same request adjusts nothing and comes back with
+   * `replayed: true` (and when the original happened, `adjustedAt`). The same
+   * key with a different request is a `ConflictError`. Keys are unique per
+   * workspace and per adjust endpoint. **Auto-generated (UUID v4) if
+   * omitted** and reused across every retry of this call, so a network blip
+   * never adjusts twice — same as signals. Supply your own (e.g. your order
+   * id) to also dedupe your OWN retries, across restarts or redelivery.
+   */
+  idempotencyKey?: string;
 }
 
 /**
@@ -1071,7 +1076,7 @@ export interface UnitAdjustInput {
  */
 export interface CompositeAdjustInput {
   /**
-   * The composite's stable identifier — its `refId` (see {@link Composite.refId}),
+   * The composite's stable identifier — its `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.
@@ -1079,266 +1084,64 @@ export interface CompositeAdjustInput {
   agentKey: string;
   delta: number;
   notes?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Entitlement catalogs: Credits, Outcomes, Units
-// ---------------------------------------------------------------------------
-
-/** A per-model token bundle attached to a credit or outcome step. */
-export interface ModelBundleEntry {
-  orgModelId: string;
-  /** Display label; the server defaults it from the model when omitted. */
-  modelName?: string;
-  tokens: number;
-  input: number;
-  output: number;
-  cache: number;
-}
-
-/** One point on a cost-over-time analytics series. */
-export interface CostPoint {
-  /** UTC day, `YYYY-MM-DD`. */
-  dateIso: string;
-  /** Short display label, e.g. "Jun 24". */
-  label: string;
-  /** Average cost that day, or `null` on days with no usage. */
-  cost: number | null;
-  reqs: number;
-}
-
-/** Summary stats across a cost-over-time series. */
-export interface CostStats {
-  activeDays: number;
-  avgCost: number | null;
-  peakCost: number | null;
-  troughCost: number | null;
-  deviationPct: number | null;
-}
-
-/** Cost-over-time analytics for a credit (`credits.get().analytics`). */
-export interface CreditAnalytics {
-  basePrice: number;
-  pricePerCredit: number;
-  marginPercent: number;
-  points: CostPoint[];
-  stats: CostStats;
-}
-
-/** Cost-over-time analytics for an outcome (`outcomes.get().analytics`).
- *  Each point adds `completions` (workflows finished that day). */
-export interface OutcomeAnalytics {
-  basePrice: number;
-  pricePerOutcome: number;
-  marginPercent: number;
-  points: (CostPoint & { completions: number })[];
-  stats: CostStats;
-}
-
-export interface Credit {
-  id: string;
-  name: string;
-  agentKey: string;
-  description: string | null;
-  tokensPerCredit: number;
-  basePrice: number;
-  marginPercent: number;
-  pricePerCredit: number;
-  isActive: boolean;
-  createdAt: string;
-}
-
-/** `credits.get()` — adds the model bundle plus usage stats/analytics. */
-export interface CreditDetail extends Credit {
-  modelBundle: ModelBundleEntry[];
-  createdByName: string;
-  stats: {
-    customerCount: number;
-    planCount: number;
-    totalGranted: number;
-    totalUsed: number;
-    revenue: number;
-    usageLogCount: number;
-  };
-  analytics: CreditAnalytics;
-}
-
-export interface CreateCreditInput {
-  name: string;
-  /** Lowercased stable key used by `signals.credit({ agentKey })`. */
-  agentKey: string;
-  basePrice: number;
-  marginPercent: number;
-  pricePerCredit: number;
-  description?: string;
-  tokensPerCredit?: number;
-  modelBundle?: ModelBundleEntry[];
-}
-
-export type UpdateCreditInput = CreateCreditInput;
-
-export interface OutcomeStepInput {
-  id?: string;
-  name: string;
-  /** Lowercased stable key used by `signals.outcome({ agentKey })`. */
-  agentKey: string;
-  basePrice: number;
-  modelBundle?: ModelBundleEntry[];
-}
-
-export interface Outcome {
-  id: string;
-  name: string;
-  /**
-   * The OUTCOME's own stable agent key — its durable identity, mirroring
-   * {@link Credit.agentKey}. Lowercased `[a-z0-9._-]`, max 80 chars, unique per
-   * organisation. A rename never changes it.
-   *
-   * Distinct from each step's `agentKey` in `steps`, and in a SEPARATE
-   * namespace: usage is always reported against a STEP's key
-   * (`signals.outcome({ agentKey })`), never this one. This key identifies the
-   * outcome itself when creating or updating it.
-   */
-  agentKey: string;
-  description: string | null;
-  isActive: boolean;
-  marginPercent: number;
-  pricePerOutcome: number;
-}
-
-/** `outcomes.get()` — adds steps plus in-flight/completed stats. */
-export interface OutcomeDetail extends Outcome {
-  /** Only the DETAIL row carries these — `outcomes.list()` returns neither.
-   *  They were previously declared on {@link Outcome} itself, where
-   *  `createdAt` was typed as a required `string` that is always `undefined`
-   *  in practice. */
-  createdAt: string;
-  createdByName: string | null;
-  steps: { name: string; agentKey: string }[];
-  stats: {
-    stepCount: number;
-    customerCount: number;
-    inFlight: number;
-    completed: number;
-    totalRemaining: number;
-  };
-  analytics: OutcomeAnalytics;
-}
-
-export interface CreateOutcomeInput {
-  name: string;
   /**
-   * The OUTCOME's own stable agent key — REQUIRED. Lowercased `[a-z0-9._-]`,
-   * max 80 chars, unique per organisation (the server lowercases and trims it).
-   *
-   * Separate namespace from `steps[].agentKey`: this names the outcome, a step
-   * key names a step and is what `signals.outcome()` reports against. Omitting
-   * it is rejected with a `ValidationError` (400).
+   * Optional idempotency key (1–255 characters) that makes this adjustment
+   * safe to retry. The first call with a key adjusts; any repeat with the
+   * same key and the same request adjusts nothing and comes back with
+   * `replayed: true` (and when the original happened, `adjustedAt`). The same
+   * key with a different request is a `ConflictError`. Keys are unique per
+   * workspace and per adjust endpoint. **Auto-generated (UUID v4) if
+   * omitted** and reused across every retry of this call, so a network blip
+   * never adjusts twice — same as signals. Supply your own (e.g. your order
+   * id) to also dedupe your OWN retries, across restarts or redelivery.
    */
-  agentKey: string;
-  basePrice: number;
-  marginPercent: number;
-  pricePerOutcome: number;
-  description?: string | null;
-  isActive?: boolean;
-  /** 1–50 steps; step names and agent keys must be unique. */
-  steps: OutcomeStepInput[];
-}
-
-export type UpdateOutcomeInput = CreateOutcomeInput;
-
-export type UnitPricingType = "FLAT" | "SLAB" | "VOLUME";
-
-/** A tier for SLAB/VOLUME pricing; only the last tier may have `upTo: null`. */
-export interface UnitTierInput {
-  id?: string;
-  upTo: number | null;
-  price: number;
-}
-
-export interface UnitTier {
-  id: string;
-  upTo: number | null;
-  price: number;
-  order: number;
-}
-
-export interface Unit {
-  id: string;
-  /** Stable per-org report key — what `signals.unit({ agentKey })` sends.
-   *  The ONLY identifier accepted when reporting unit consumption. */
-  agentKey: string;
-  name: string;
-  description: string | null;
-  pricingType: UnitPricingType;
-  flatPrice: number;
-  tiers: UnitTier[];
-  isActive: boolean;
-  createdAt: string;
-  createdByName: string | null;
+  idempotencyKey?: string;
 }
 
-/** One row in a unit's linked-customer sample (`units.get().customers`). */
-export interface UnitCustomerRow {
-  customerId: string;
-  name: string;
-  legalName: string | null;
-  slug: string;
-  logoUrl: string | null;
-  granted: number;
-  used: number;
+/**
+ * What every adjust call returns.
+ *
+ * `replayed: true` means this call adjusted NOTHING: an earlier call with the
+ * same `idempotencyKey` already did, at `adjustedAt`. `remaining` is always
+ * the balance as it is now. `customerArchived` is true when the customer is
+ * archived — archived customers follow the same rules (archiving cancels
+ * their plan, so usually only the wallet can still move).
+ */
+export interface AdjustResult {
   remaining: number;
-  currentlyMetered: boolean;
-}
-
-/** `units.get()` — adds linked-customer sample plus stats.
- *  `createdByName` is inherited from `Unit`. */
-export interface UnitDetail extends Unit {
-  stats: {
-    planCount: number;
-    customerCount: number;
-    totalRemaining: number;
-    totalUsed: number;
-  };
-  /** First page (≤10) of customers currently metered on this unit. */
-  customers: UnitCustomerRow[];
-}
-
-/** Flat per-event pricing — a single `flatPrice` (defaults to 0), no tiers. */
-export interface FlatUnitInput {
-  name: string;
-  /** Stable per-org report key (`signals.unit({ agentKey })`); `[a-z0-9._-]`. */
-  agentKey: string;
-  pricingType: "FLAT";
-  /** Price per event; defaults to 0. */
-  flatPrice?: number;
-  description?: string | null;
-  isActive?: boolean;
-}
-
-/** Tiered pricing (SLAB or VOLUME) — at least one tier is required. */
-export interface TieredUnitInput {
-  name: string;
-  /** Stable per-org report key (`signals.unit({ agentKey })`); `[a-z0-9._-]`. */
-  agentKey: string;
-  pricingType: "SLAB" | "VOLUME";
-  /** At least one tier (≤50). Only the last tier may have `upTo: null`. */
-  tiers: UnitTierInput[];
-  description?: string | null;
-  isActive?: boolean;
+  replayed: boolean;
+  /** Set only on a replay: when the original adjustment happened (ISO 8601). */
+  adjustedAt?: string;
+  customerArchived: boolean;
 }
 
 /**
- * Create a unit type — a discriminated union on `pricingType`: `FLAT` takes an
- * optional `flatPrice` (defaults to 0); `SLAB`/`VOLUME` require `tiers`, so the
- * server's "add at least one tier" rule is enforced at compile time.
+ * Change how much a customer is granted every billing cycle. The difference is
+ * applied to the current balance immediately (a shrink is never floored — the
+ * balance may read negative). `quantity` is USD for the wallet and a whole
+ * number for everything else. `agentKey` resolves the same way as the adjust
+ * endpoints: a credit's or unit's `agentKey`, an outcome STEP's `agentKey`, or
+ * a composite's `refId`. The wallet needs none — a customer has at most one.
  */
-export type CreateUnitInput = FlatUnitInput | TieredUnitInput;
+export type RecurringGrantInput =
+  | { kind: "wallet"; quantity: number }
+  | {
+      kind: "credit" | "outcome" | "unit" | "composite";
+      agentKey: string;
+      quantity: number;
+    };
 
-export type UpdateUnitInput = CreateUnitInput;
+/** Result of `customers.updateRecurringGrant()`. */
+export interface RecurringGrantResult {
+  kind: RecurringGrantInput["kind"];
+  /** The new per-cycle amount. */
+  quantity: number;
+  /** The wallet balance after the change — only present for `kind: "wallet"`. */
+  balanceUsd?: number;
+}
 
 // ---------------------------------------------------------------------------
-// Unit consumption (recorded via signals; distinct from catalog `Unit`)
+// Unit consumption (recorded via signals)
 // ---------------------------------------------------------------------------
 
 /**
@@ -1347,8 +1150,7 @@ export type UpdateUnitInput = CreateUnitInput;
  * the display name is deliberately not accepted, so a rename can never redirect
  * a live integration. Keys are matched exactly (they are stored lowercased).
  */
-export interface UnitInput {
-  customerId: string;
+export type UnitInput = CustomerRef & {
   agentKey: string;
   member?: string;
   /**
@@ -1379,7 +1181,7 @@ export interface UnitInput {
    * auto key cannot survive.
    */
   idempotencyKey?: string;
-}
+};
 
 /**
  * The result of `signals.unit()`.
@@ -1409,8 +1211,7 @@ export interface UnitTrackResult {
  * Input for `signals.completeComposite()` — closes ONE occurrence of a
  * composite, which is the moment it is billed.
  */
-export interface CompositeCompletionInput {
-  customerId: string;
+export type CompositeCompletionInput = CustomerRef & {
   /** Which occurrence to close: the composite's `refId` and the correlation
    *  value the signals were tagged with. */
   composite: CompositeTag;
@@ -1418,79 +1219,12 @@ export interface CompositeCompletionInput {
    *  safe no-op, so this only collapses retries into one recorded attempt
    *  rather than protecting against a double charge. */
   idempotencyKey?: string;
-}
+};
 
 // ---------------------------------------------------------------------------
-// Composites catalog (mirrors /api/v1/composites)
+// Composite completion
 // ---------------------------------------------------------------------------
 
-/** One catalogue item a composite is restricted to. `agentKey` is what a
- *  signal names, so it is the field you actually integrate against. */
-export interface CompositeCatalogueRef {
-  id: string;
-  name: string;
-  agentKey: string;
-}
-
-/** One composite in the org's catalogue — `cnk.composites.list()`. */
-export interface Composite {
-  id: string;
-  name: string;
-  /** The stable identifier you put in a signal's `composite` block as `ref`. */
-  refId: string;
-  description: string | null;
-  /** USD charged per occurrence WHEN A PLAN SELLS THIS as a composite
-   *  component (`quantity × price`, frozen into the purchase at buy time). The
-   *  catalogue row alone bills nothing. */
-  price: number;
-  /** False once archived. An archived composite stops NEW signals resolving to
-   *  it but keeps every row it already owns. */
-  isActive: boolean;
-  createdAt: string;
-  /**
-   * The credits / outcomes / units this composite is restricted to — only
-   * signals naming one of these may carry its tag.
-   *
-   * All three lists empty means UNRESTRICTED (it accepts any of the org's
-   * traffic under this tag). Nothing created through the API can be
-   * unrestricted, but rows predating that rule exist — so don't assume
-   * non-empty.
-   */
-  entitlements: {
-    credits: CompositeCatalogueRef[];
-    outcomes: CompositeCatalogueRef[];
-    units: CompositeCatalogueRef[];
-  };
-}
-
-/** Input for `cnk.composites.create()`. */
-export interface CreateCompositeInput {
-  name: string;
-  /**
-   * The tag identifier. Lowercased, and restricted to the same characters as
-   * an `agentKey` — but validated harder than one, because it may not collide
-   * with a field the ingest schemas already own (`customerId`, `usage`,
-   * `agentKey`, `runId`, `member`, `custom`, `composite`, …). A colliding
-   * `refId` is refused at create time rather than silently ignored at ingest.
-   */
-  refId: string;
-  /** USD per occurrence once a plan sells it. Required — an unpriced composite
-   *  put on a plan would bill 0, which is a money bug that is hard to see. */
-  price: number;
-  description?: string | null;
-  /**
-   * What the composite wraps. At least one id across the three lists is
-   * REQUIRED: a composite restricted to nothing would accept every signal in
-   * the org. Get the ids from `credits.list()`, `outcomes.list()` and
-   * `units.list()`.
-   */
-  entitlements: {
-    creditIds?: string[];
-    outcomeIds?: string[];
-    unitIds?: string[];
-  };
-}
-
 /**
  * The result of `signals.completeComposite()`.
  *
@@ -1523,8 +1257,7 @@ export interface CompositeCompletionResult {
   rawId?: string;
 }
 
-/** One serialized unit-consumption event — the result of `signals.unit()` and
- *  each element of `UnitUsageList.events`. */
+/** One serialized unit-consumption event — the result of `signals.unit()`. */
 export interface SerializedUnitUsage {
   id: string;
   customerId: string;
@@ -1540,48 +1273,6 @@ export interface SerializedUnitUsage {
   createdAt: string;
 }
 
-export interface UnitUsageRow {
-  unit: string;
-  /** The unit's stable agent key — what to send to report against it. */
-  agentKey: string | null;
-  billingMode: BillingMode;
-  granted?: number;
-  used: number;
-  remaining?: number;
-}
-
-export interface UnitUsageList {
-  customer: { id: string; name: string };
-  units: UnitUsageRow[];
-  events: SerializedUnitUsage[];
-}
-
-// ---------------------------------------------------------------------------
-// Webhooks (threshold alerts)
-// ---------------------------------------------------------------------------
-
-export type ThresholdKind = "CREDIT" | "OUTCOME" | "WALLET";
-
-export interface Webhook {
-  id: string;
-  kind: ThresholdKind;
-  threshold: number;
-  url: string;
-  isActive: boolean;
-  createdAt: string;
-  updatedAt: string;
-  createdByName: string | null;
-}
-
-export interface UpsertWebhookInput {
-  kind: ThresholdKind;
-  /** Fire when the balance crosses this value. */
-  threshold: number;
-  /** http(s) URL to POST the alert to. */
-  url: string;
-  isActive?: boolean;
-}
-
 // ---------------------------------------------------------------------------
 // Config & hooks
 // ---------------------------------------------------------------------------