@clocknext/sdk 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -15,12 +15,15 @@ type SignalStatus = "SUCCESS" | "FAILURE" | "PENDING";
 /**
  * Token counts for a signal. `input` and `output` are required — every metered
  * call has them, and the server requires them. `cache` (provider-specific
- * prompt-cache reads) is optional and defaults to 0 server-side when omitted.
+ * prompt-cache reads) and `cacheWrite` (tokens written into the prompt cache,
+ * priced at the model's separate cache-write rate) are optional and default to
+ * 0 server-side when omitted.
  */
 interface Tokens {
     input: number;
     output: number;
     cache?: number;
+    cacheWrite?: number;
 }
 /**
  * Groups a signal into one occurrence of a **composite** — a bundle of credits
@@ -56,37 +59,31 @@ interface CompositeTag {
     /** Your correlation value for this occurrence, stored verbatim. */
     value: string | number;
 }
-/** The organisation + key behind a request — `cnk.workspace.me()`. */
-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;
-}
-/** 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. */
-interface Model {
-    modelId: string;
-    modelName: string;
-    provider: string;
-    providerName: string;
-    isActive: boolean;
-    inputPrice: number;
-    outputPrice: number;
-    cachePrice: number;
-}
-interface SignalBase {
-    /** The customer this usage belongs to (required). */
+/**
+ * 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).
+ */
+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;
+};
+/** `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;
+/** 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`.
@@ -108,18 +105,19 @@ interface SignalBase {
      */
     idempotencyKey?: string;
 }
+type SignalBase = CustomerRef & SignalFields;
 /** Meters a credit, identified by the credit's stable `agentKey`. */
-interface CreditSignal extends SignalBase {
+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. */
-interface WalletSignal extends SignalBase {
+type WalletSignal = SignalBase & {
     type: "wallet";
-}
+};
 /**
  * Records one step of a multi-call outcome run. The `agentKey` identifies the
  * step (and the outcome); `runId` groups every signal of a single run, so a step
@@ -132,7 +130,7 @@ interface WalletSignal extends SignalBase {
  * carries `complete` — see {@link OutcomeCompletionInput} /
  * `signals.completeOutcome()`, its own dedicated route.
  */
-interface OutcomeSignal extends SignalBase {
+type OutcomeSignal = SignalBase & {
     type: "outcome";
     /** The OutcomeStep's stable agent key — identifies the outcome AND the step. */
     agentKey: string;
@@ -144,12 +142,12 @@ interface OutcomeSignal extends SignalBase {
     runId: string;
     /** Optional composite this signal belongs to. See {@link CompositeTag}. */
     composite?: CompositeTag;
-}
+};
 type Signal = CreditSignal | WalletSignal | OutcomeSignal;
 /** Helper input shapes for the per-type convenience methods. */
-type CreditInput = Omit<CreditSignal, "type">;
-type WalletInput = Omit<WalletSignal, "type">;
-type OutcomeInput = Omit<OutcomeSignal, "type">;
+type CreditInput = DistributiveOmit<CreditSignal, "type">;
+type WalletInput = DistributiveOmit<WalletSignal, "type">;
+type OutcomeInput = DistributiveOmit<OutcomeSignal, "type">;
 /**
  * Input for `signals.completeOutcome()` — closes ONE outcome run, the outcome
  * mirror of {@link CompositeCompletionInput}. No `agentKey`, no `usage`: this
@@ -161,17 +159,17 @@ type OutcomeInput = Omit<OutcomeSignal, "type">;
  * `signals.completeComposite()` — the two completions are independent, and
  * neither implies the other.
  */
-interface OutcomeCompletionInput {
-    customerId: string;
+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()`.
  *
@@ -244,7 +242,10 @@ interface SerializedUsageLog {
     member: string | null;
     inputTokens: number;
     outputTokens: number;
+    /** Cache-read tokens. */
     cacheTokens: number;
+    /** Cache-write tokens, priced separately from cache reads. */
+    cacheWriteTokens: number;
     /** Total credits deducted: the call's real per-model provider cost as a
      *  fraction of the credit's base price (i.e. cost + your margin), plus any
      *  credit-rule add-ons; 0 for wallet-money calls. */
@@ -274,7 +275,7 @@ 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.
@@ -296,7 +297,7 @@ 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.
@@ -341,21 +342,6 @@ interface TrackResult {
      */
     rawId?: string;
 }
-interface UsageList {
-    customer: {
-        id: string;
-        name: string;
-        creditAllowance: number;
-    };
-    totals: {
-        count: number;
-        cost: number;
-        revenue: number;
-        profit: number;
-        creditsUsed: number;
-    };
-    logs: SerializedUsageLog[];
-}
 /** A preset time window, or `"custom"` for an explicit `from`/`to` range. */
 type UsageLogPeriod = "all" | "today" | "7d" | "30d" | "90d" | "custom";
 interface UsageLogListParams {
@@ -412,7 +398,10 @@ interface UsageLogEntry {
     usage: {
         inputTokens: number;
         outputTokens: number;
+        /** Cache-read tokens. */
         cacheTokens: number;
+        /** Cache-write tokens, priced separately from cache reads. */
+        cacheWriteTokens: number;
     };
     /** Formatted USD strings (e.g. `"$0.0064"`). */
     cost: {
@@ -445,6 +434,9 @@ interface UsageLogPage {
 }
 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;
@@ -460,11 +452,23 @@ 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. */
 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;
@@ -479,6 +483,10 @@ 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. */
 type CreateCustomerInput = CustomerProfileInput & {
@@ -510,7 +518,7 @@ 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;
@@ -528,8 +536,25 @@ interface UnitBalance {
     granted: number;
     remaining: number;
 }
-/** Wallet / credit / outcome / unit balances for a customer's active plan
- *  (`customers.balances()`). */
+/** One prepaid (ADVANCE) composite pool on a customer's plan. */
+interface CompositeBalance {
+    compositeId: string;
+    /** The tag signals send in their `composite` block. */
+    refId: string;
+    name: string;
+    /** The pool size the plan grants this cycle. */
+    granted: number;
+    /** Slots claimed this cycle — one per distinct tag value. */
+    used: number;
+    /** `granted - used` plus this cycle's manual adjustments. May be negative:
+     *  running past the pool is allowed and carries into the next cycle. */
+    remaining: number;
+    /** What `granted` was before the pool was ever resized for this customer;
+     *  `null` if it never was. */
+    originalGranted: number | null;
+}
+/** Wallet / credit / outcome / unit balances and composite pools for a
+ *  customer's active plan (`customers.balances()`). */
 interface CustomerBalances {
     customerId: string;
     currency: {
@@ -537,12 +562,21 @@ interface CustomerBalances {
         rateUsd: number;
     };
     hasPlan: boolean;
+    /** Both wallet balances, in USD. Always present. */
     wallet: {
-        balanceUsd: number;
-    } | null;
+        /** The ordinary wallet — always reported, also when the plan has no
+         *  Wallet component or there's no plan. May be negative. */
+        balance: number;
+        /** The Reserved Wallet; absent when the org hasn't enabled it, otherwise
+         *  present whether or not the plan has a Wallet. Never negative. */
+        reservedBalance?: number;
+    };
     credits: CreditBalance[];
     outcomes: OutcomeBalance[];
     units: UnitBalance[];
+    /** ADVANCE composite pools. A composite billed in ARREAR has no pool and
+     *  isn't listed. */
+    composites: CompositeBalance[];
 }
 /** The customer's active plan (the `plan` field of `customers.plan()`);
  *  `null` when the customer is unsubscribed. */
@@ -586,11 +620,10 @@ interface PortalToken {
     /** Seconds until expiry. */
     expiresIn: number;
 }
-/** How often a plan bills. `FREE` is a one-time grant; `EVERY_5_MIN` is a test cadence. */
-type BillingCycle = "MONTHLY" | "QUARTERLY" | "SEMI_ANNUAL" | "YEARLY" | "EVERY_5_MIN" | "FREE";
+/** How often a plan bills. `FREE` is a one-time grant. */
+type BillingCycle = "MONTHLY" | "QUARTERLY" | "SEMI_ANNUAL" | "YEARLY" | "FREE";
 type PlanType = "WALLET" | "BUNDLE";
 type PlanKind = "FLAT_PRICE" | "PAY_AS_YOU_GO" | "PAY_PER_SEAT";
-/** A plan component's meter type. */
 /**
  * A plan component's kind.
  *
@@ -602,138 +635,31 @@ type PlanKind = "FLAT_PRICE" | "PAY_AS_YOU_GO" | "PAY_PER_SEAT";
 type ComponentType = "WALLET" | "CREDIT" | "OUTCOME" | "UNIT" | "FLAT" | "PRICING_METRIC";
 /** ADVANCE bills up-front for the cycle; ARREAR bills for what was consumed. */
 type BillingMode = "ADVANCE" | "ARREAR";
-/** Prepaid USD wallet. `amount` is the funded balance (required). Max one
- *  wallet component per plan. */
-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. */
-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. */
-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. */
-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. */
-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.
- */
-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`.
- */
-type PlanComponentInput = WalletComponentInput | FlatComponentInput | CreditComponentInput | OutcomeComponentInput | UnitComponentInput | CompositeComponentInput;
-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). */
-type UpdatePlanInput = CreatePlanInput;
-interface PlanComponent {
+/** One line of a plan (`plan.entitlements[]`). */
+interface PlanEntitlement {
     id: string;
     type: ComponentType;
     billingMode: BillingMode;
     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;
+    /** ADVANCE credit / outcome / composite / wallet components: what's left at
+     *  the end of a cycle carries into the next one instead of resetting.
+     *  Always false for unit, flat and ARREAR components and on FREE plans. */
+    rollover: boolean;
 }
+/** @deprecated Renamed to {@link PlanEntitlement} — a plan's lines are `entitlements` now. */
+type PlanComponent = PlanEntitlement;
 interface Plan {
     id: string;
     name: string;
     description: string | null;
-    type: PlanType;
-    kind: PlanKind;
     billingCycle: BillingCycle;
     cost: number;
     /** Signed adjustment applied to the plan's headline price (default 0). */
@@ -741,26 +667,256 @@ interface Plan {
     /** When true, ARREAR consumption is funded from the customer's wallet as it
      *  happens instead of being invoiced at cycle end. All-or-nothing per plan. */
     walletFundedArrear: boolean;
+    /** The workspace's primary currency when the plan was created. */
     currencyCode: string;
     isActive: boolean;
-    components: PlanComponent[];
+    createdAt: string;
+    updatedAt: string;
+    /** The plan's lines — what a customer on it is granted or metered for. */
+    entitlements: PlanEntitlement[];
+}
+/** One line of a plan, as you send it to `plans.create()` / `plans.update()`.
+ *  Set the id that matches `type`: `creditId` (CREDIT), `outcomeId`
+ *  (OUTCOME), `unitId` (UNIT) or `compositeId` (PRICING_METRIC — a
+ *  composite). The lines `plans.get()` returns can be sent back as they are. */
+interface PlanEntitlementInput {
+    type: ComponentType;
+    billingMode: BillingMode;
+    creditId?: string | null;
+    outcomeId?: string | null;
+    unitId?: string | null;
+    compositeId?: string | null;
+    /** ADVANCE credit / outcome / unit / composite: granted each cycle (0 allowed). */
+    quantity?: number | null;
+    /** WALLET (ADVANCE prepaid balance, $0 allowed) or FLAT (fee, above $0), in USD. */
+    amount?: number | null;
+    /** ADVANCE credit / outcome / composite / wallet: carry leftovers into the next cycle. */
+    rollover?: boolean;
+}
+/** `plans.create()` body. The plan's currency is the workspace's primary
+ *  currency — it can't be chosen. A new plan is active; retire it with
+ *  `plans.archive()`. */
+interface CreatePlanInput {
+    name: string;
+    billingCycle: BillingCycle;
+    description?: string | null;
+    /** Pay ARREAR usage from the prepaid wallet as it happens. Needs an ADVANCE
+     *  WALLET line and at least one ARREAR credit / outcome / unit / composite. */
+    walletFundedArrear?: boolean;
+    /** Signed rounding nudge (USD) on the due-at-purchase total. */
+    priceAdjustment?: number;
+    /** At least one line. At most one WALLET and one FLAT. */
+    entitlements: PlanEntitlementInput[];
+}
+/** `plans.update()` body — a PARTIAL update: only the fields you send change.
+ *  `entitlements`, when sent, is the complete new list. */
+type UpdatePlanInput = Partial<CreatePlanInput>;
+/** One model line of a credit's / outcome step's pricing bundle, as returned. */
+interface ModelBundleLine {
+    /** The workspace's model row id (`id` from the Models API). */
+    orgModelId: string;
+    /** The model's display name, filled in by the server. */
+    modelName: string;
+    /** Average tokens one LLM call uses on this model. */
+    averageTokensPerLLMCall: number;
+    /** Whole-percent split of those tokens; the four add up to 100. */
+    input: number;
+    output: number;
+    cache: number;
+    /** 0 on a model with no cache-write price. */
+    cacheWrite: number;
+}
+/** One model line as you send it. Several lines (one per model) are allowed;
+ *  the price is the sum of their costs, worked out on the server from the
+ *  models' live prices. */
+interface ModelBundleLineInput {
+    orgModelId: string;
+    /** Above 0. */
+    averageTokensPerLLMCall: number;
+    input: number;
+    output: number;
+    cache: number;
+    /** Default 0. Only on a model that has a cache-write price. */
+    cacheWrite?: number;
+}
+/** A credit — a token-metered entitlement your product draws down by its
+ *  `agentKey`. */
+interface Credit {
+    id: string;
+    name: string;
+    /** What a credit signal names; unique in the workspace. */
+    agentKey: string;
+    description: string | null;
+    /** Sum of the bundle lines' tokens (display figure). */
+    tokensPerCredit: number;
+    /** Cost of one credit, worked out from `modelBundle`. */
+    basePrice: number;
+    modelBundle: ModelBundleLine[];
+    marginPercent: number;
+    /** `basePrice` plus the margin — what a customer pays per credit. */
+    pricePerCredit: number;
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** `credits.create()` body. The price is always worked out on the server from
+ *  `modelBundle` — it is never typed in. */
+interface CreateCreditInput {
+    name: string;
+    agentKey: string;
+    /** -100 or more. */
+    marginPercent: number;
+    /** At least one line. */
+    modelBundle: ModelBundleLineInput[];
+    description?: string | null;
+}
+/** `credits.update()` body — PARTIAL. Send `modelBundle` to re-price; leave it
+ *  out to keep the stored base price (a new margin is applied on top). */
+type UpdateCreditInput = Partial<CreateCreditInput>;
+/** An outcome — a multi-step deliverable billed per completed outcome. */
+interface Outcome {
+    id: string;
+    name: string;
+    /** The outcome's own key (unique in the workspace) — not what a step signal
+     *  names; each step has its own `agentKey`. */
+    agentKey: string;
+    description: string | null;
+    isActive: boolean;
+    /** Sum of the steps' base prices. */
+    basePrice: number;
+    marginPercent: number;
+    pricePerOutcome: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One step of an outcome. */
+interface OutcomeStep {
+    /** Send it back on `outcomes.update()` to keep this step. */
+    id: string;
+    name: string;
+    /** What an outcome step signal names; unique in the workspace. */
+    agentKey: string;
+    order: number;
+    basePrice: number;
+    modelBundle: ModelBundleLine[];
+}
+/** `outcomes.get()` — the outcome with its steps in full. */
+interface OutcomeWithSteps extends Outcome {
+    steps: OutcomeStep[];
+}
+/** One step as you send it. */
+interface OutcomeStepInput {
+    /** An existing step's id, to keep that step (update only). A step sent
+     *  without an id but with an existing step's `agentKey` is that step too. */
+    id?: string;
+    name: string;
+    agentKey: string;
+    /** Required for a new step. Leave it out on an existing step to keep its
+     *  price. */
+    modelBundle?: ModelBundleLineInput[];
+}
+/** `outcomes.create()` body. */
+interface CreateOutcomeInput {
+    name: string;
+    agentKey: string;
+    /** -100 or more. */
+    marginPercent: number;
+    /** 1–50 steps; names and agent keys unique. */
+    steps: OutcomeStepInput[];
+    description?: string | null;
+}
+/** `outcomes.update()` body — PARTIAL. Leave `steps` out to leave the steps
+ *  alone; send it and it is the complete step list (stored steps left out are
+ *  removed). */
+type UpdateOutcomeInput = Partial<CreateOutcomeInput>;
+/** How a unit is priced. */
+type UnitPricingType = "FLAT" | "SLAB" | "VOLUME";
+/** One price band of a SLAB / VOLUME unit. */
+interface UnitTier {
+    id: string;
+    /** Inclusive upper bound; `null` on the last tier ("and above"). */
+    upTo: number | null;
+    /** Per-unit price for this band. */
+    price: number;
+    order: number;
 }
-/** The richer plan returned by `plans.get()` (adds aggregate stats). */
-interface PlanDetail extends Plan {
+/** A unit — a fixed-price, non-LLM event (an upload, a seat, an API call). */
+interface Unit {
+    id: string;
+    name: string;
+    /** What a unit signal names; unique in the workspace. */
+    agentKey: string;
+    description: string | null;
+    pricingType: UnitPricingType;
+    /** FLAT only. */
+    flatPrice: number;
+    /** SLAB / VOLUME only. */
+    tiers: UnitTier[];
+    isActive: boolean;
     createdAt: string;
+    updatedAt: string;
     createdByName: string | null;
-    customerCount: number;
-    invoiceCount: number;
-    openInvoiceCount: number;
-    stats: {
-        totalInvoiced: number;
-        totalCollected: number;
-        openBalance: number;
+}
+/** `units.create()` body. */
+interface CreateUnitInput {
+    name: string;
+    agentKey: string;
+    pricingType: UnitPricingType;
+    /** FLAT only. */
+    flatPrice?: number;
+    /** SLAB / VOLUME: 1–50 tiers, `upTo` rising; the last one `upTo: null`. */
+    tiers?: {
+        upTo: number | null;
+        price: number;
+    }[];
+    description?: string | null;
+}
+/** `units.update()` body — PARTIAL. `tiers`, when sent, is the complete list. */
+type UpdateUnitInput = Partial<CreateUnitInput>;
+/** A catalogue item a composite wraps. */
+interface CompositeItem {
+    id: string;
+    name: string;
+    agentKey: string;
+}
+/** A composite — several credits / outcomes / units grouped under one tag and
+ *  billed as ONE thing, per completed occurrence, once a plan sells it. */
+interface Composite {
+    id: string;
+    name: string;
+    /** The tag your signals send in their `composite` block. */
+    refId: string;
+    description: string | null;
+    /** USD per completed occurrence, once a plan sells it. */
+    price: number;
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+    entitlements: {
+        credits: CompositeItem[];
+        outcomes: CompositeItem[];
+        units: CompositeItem[];
+    };
+}
+/** `composites.create()` body. */
+interface CreateCompositeInput {
+    name: string;
+    refId: string;
+    price: number;
+    description?: string | null;
+    /** At least one id across the three lists. Every item must be active, and a
+     *  unit must be FLAT-priced. */
+    entitlements: {
+        creditIds?: string[];
+        outcomeIds?: string[];
+        unitIds?: string[];
     };
 }
+/** `composites.update()` body — PARTIAL. `entitlements`, when sent, is the
+ *  complete new set. */
+type UpdateCompositeInput = Partial<CreateCompositeInput>;
 type PurchaseStatus = "SCHEDULED" | "ACTIVE" | "CANCELLED";
-interface CreatePurchaseInput {
-    customerId: string;
+type CreatePurchaseInput = CustomerRef & {
     planId: string;
     /** `YYYY-MM-DD`. Defaults to today; must be a valid non-past date. */
     billingDate?: string;
@@ -768,7 +924,7 @@ interface CreatePurchaseInput {
     autoPayment?: boolean;
     /** Auto-void the purchase if unpaid after N minutes. */
     voidAfterMinutes?: number;
-}
+};
 interface Purchase {
     id: string;
     purchaseNumber: string;
@@ -826,7 +982,9 @@ interface PurchaseDetail {
         paidCount: number;
     };
 }
-type InvoiceStatus = "OPEN" | "PAID" | "VOID";
+/** `AUTO_CLOSED` — a recurring invoice for a customer with `autoRecurring` on:
+ *  applied as if paid, but never payable. */
+type InvoiceStatus = "OPEN" | "PAID" | "VOID" | "AUTO_CLOSED";
 /** Trimmed row from `invoices.list()`. */
 interface InvoiceListRow {
     id: string;
@@ -990,64 +1148,78 @@ interface UpdateMemberInput {
     /** Must be unique (case-insensitively) among the customer's active members. */
     email?: string;
 }
-type WalletTransactionType = "CREDIT" | "DEBIT";
-/** What produced a wallet entry. `null` on rows written before the column
- *  existed. */
-type WalletTransactionSource = "TOPUP" | "USAGE" | "SETTLE" | "ADJUSTMENT";
-/** The entitlement kinds a wallet-funded metering debit can name. */
-type WalletEntitlementKind = "CREDIT" | "OUTCOME" | "UNIT";
-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;
-}
-interface WalletList {
-    balanceUsd: number;
-    transactions: WalletTransaction[];
-}
-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}). Lowercase only —
+ * the API refuses `"MAIN"` / `"RESERVED"`.
+ */
+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. */
+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 (leave it
+     * out; `null` is refused).
+     *
+     * `"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. */
 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. */
 interface OutcomeAdjustInput {
@@ -1056,16 +1228,41 @@ 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. */
 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;
 }
 /**
  * Grant (positive) or claw back (negative) slots on a customer's ADVANCE
@@ -1077,7 +1274,7 @@ interface UnitAdjustInput {
  */
 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.
@@ -1085,248 +1282,66 @@ interface CompositeAdjustInput {
     agentKey: string;
     delta: number;
     notes?: string;
-}
-/** A per-model token bundle attached to a credit or outcome step. */
-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. */
-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. */
-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`). */
-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). */
-interface OutcomeAnalytics {
-    basePrice: number;
-    pricePerOutcome: number;
-    marginPercent: number;
-    points: (CostPoint & {
-        completions: number;
-    })[];
-    stats: CostStats;
-}
-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. */
-interface CreditDetail extends Credit {
-    modelBundle: ModelBundleEntry[];
-    createdByName: string;
-    stats: {
-        customerCount: number;
-        planCount: number;
-        totalGranted: number;
-        totalUsed: number;
-        revenue: number;
-        usageLogCount: number;
-    };
-    analytics: CreditAnalytics;
-}
-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[];
-}
-type UpdateCreditInput = CreateCreditInput;
-interface OutcomeStepInput {
-    id?: string;
-    name: string;
-    /** Lowercased stable key used by `signals.outcome({ agentKey })`. */
-    agentKey: string;
-    basePrice: number;
-    modelBundle?: ModelBundleEntry[];
-}
-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. */
-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;
-}
-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[];
-}
-type UpdateOutcomeInput = CreateOutcomeInput;
-type UnitPricingType = "FLAT" | "SLAB" | "VOLUME";
-/** A tier for SLAB/VOLUME pricing; only the last tier may have `upTo: null`. */
-interface UnitTierInput {
-    id?: string;
-    upTo: number | null;
-    price: number;
-}
-interface UnitTier {
-    id: string;
-    upTo: number | null;
-    price: number;
-    order: number;
-}
-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`). */
-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).
+ */
+interface AdjustResult {
     remaining: number;
-    currentlyMetered: boolean;
-}
-/** `units.get()` — adds linked-customer sample plus stats.
- *  `createdByName` is inherited from `Unit`. */
-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. */
-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. */
-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.
  */
-type CreateUnitInput = FlatUnitInput | TieredUnitInput;
-type UpdateUnitInput = CreateUnitInput;
+type RecurringGrantInput = {
+    kind: "wallet";
+    quantity: number;
+} | {
+    kind: "credit" | "outcome" | "unit" | "composite";
+    agentKey: string;
+    quantity: number;
+};
+/** Result of `customers.updateRecurringGrant()`. */
+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;
+}
 /**
  * Record one unit-metered event. The unit is addressed by its `agentKey` (the
  * stable key set when the unit was created) — the ONLY accepted identifier;
  * the display name is deliberately not accepted, so a rename can never redirect
  * a live integration. Keys are matched exactly (they are stored lowercased).
  */
-interface UnitInput {
-    customerId: string;
+type UnitInput = CustomerRef & {
     agentKey: string;
     member?: string;
     /**
@@ -1357,7 +1372,7 @@ interface UnitInput {
      * auto key cannot survive.
      */
     idempotencyKey?: string;
-}
+};
 /**
  * The result of `signals.unit()`.
  *
@@ -1385,8 +1400,7 @@ interface UnitTrackResult {
  * Input for `signals.completeComposite()` — closes ONE occurrence of a
  * composite, which is the moment it is billed.
  */
-interface CompositeCompletionInput {
-    customerId: string;
+type CompositeCompletionInput = CustomerRef & {
     /** Which occurrence to close: the composite's `refId` and the correlation
      *  value the signals were tagged with. */
     composite: CompositeTag;
@@ -1394,71 +1408,7 @@ interface CompositeCompletionInput {
      *  safe no-op, so this only collapses retries into one recorded attempt
      *  rather than protecting against a double charge. */
     idempotencyKey?: string;
-}
-/** One catalogue item a composite is restricted to. `agentKey` is what a
- *  signal names, so it is the field you actually integrate against. */
-interface CompositeCatalogueRef {
-    id: string;
-    name: string;
-    agentKey: string;
-}
-/** One composite in the org's catalogue — `cnk.composites.list()`. */
-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()`. */
-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()`.
  *
@@ -1494,8 +1444,7 @@ interface CompositeCompletionResult {
     /** The durable inbox id — see {@link TrackResult.rawId}. */
     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()`. */
 interface SerializedUnitUsage {
     id: string;
     customerId: string;
@@ -1510,42 +1459,6 @@ interface SerializedUnitUsage {
     member: string | null;
     createdAt: string;
 }
-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;
-}
-interface UnitUsageList {
-    customer: {
-        id: string;
-        name: string;
-    };
-    units: UnitUsageRow[];
-    events: SerializedUnitUsage[];
-}
-type ThresholdKind = "CREDIT" | "OUTCOME" | "WALLET";
-interface Webhook {
-    id: string;
-    kind: ThresholdKind;
-    threshold: number;
-    url: string;
-    isActive: boolean;
-    createdAt: string;
-    updatedAt: string;
-    createdByName: string | null;
-}
-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;
-}
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 interface Logger {
     debug?: (...args: unknown[]) => void;
@@ -1678,65 +1591,77 @@ declare class Transport {
 }
 
 /**
- * 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.
  */
 declare class Composites {
     private readonly transport;
     constructor(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. */
     list(params?: {
         active?: boolean;
     }): Promise<Composite[]>;
-    /** Create a composite. `POST /api/v1/composites`. */
+    /** One composite's configuration. */
+    get(id: string): Promise<Composite>;
+    /** Create one. It starts active. Not retried on failure — a retry could
+     *  create a second row. */
     create(input: CreateCompositeInput): Promise<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. */
+    update(id: string, input: UpdateCompositeInput): Promise<Composite>;
+    /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+    archive(id: string): Promise<Composite>;
+    /** Bring an archived one back (`isActive` → true). Safe to retry. */
+    unarchive(id: string): Promise<Composite>;
 }
 
 /**
- * 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.
  */
 declare class Credits {
     private readonly transport;
     constructor(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. */
     list(params?: {
         active?: boolean;
     }): Promise<Credit[]>;
-    /** Create a credit type; returns the created credit. `POST /api/v1/credits`. */
+    /** One credit's configuration. */
+    get(id: string): Promise<Credit>;
+    /** Create one. It starts active. Not retried on failure — a retry could
+     *  create a second row. */
     create(input: CreateCreditInput): Promise<Credit>;
-    /** Fetch one credit type with usage stats. `GET /api/v1/credits/:id`. */
-    get(id: string): Promise<CreditDetail>;
-    /** 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. */
     update(id: string, input: UpdateCreditInput): Promise<Credit>;
-    /** Activate or deactivate a credit type. */
-    setActive(id: string, isActive: boolean): Promise<Credit>;
-    /** Delete a credit type. Refused while a customer is linked to it. */
-    delete(id: string): Promise<void>;
+    /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+    archive(id: string): Promise<Credit>;
+    /** Bring an archived one back (`isActive` → true). Safe to retry. */
+    unarchive(id: string): Promise<Credit>;
 }
 
 /**
  * The `customers` resource — full CRUD over the org's customers plus the
- * read-only insight endpoints (usage / balances / plan). Every call is scoped
+ * read-only insight endpoints (balances / plan). Every call is scoped
  * to the API key's organisation server-side; a customer in another org
  * resolves as a NotFoundError.
  */
@@ -1763,14 +1688,25 @@ declare class Customers {
     get(id: string): Promise<ApiCustomer>;
     /** Update a customer (partial). `PATCH /api/v1/customers/:id`. */
     update(id: string, input: CustomerProfileInput): Promise<ApiCustomer>;
+    /**
+     * Fetch one customer by YOUR id for them (its `externalId`), instead of
+     * ours. Same result as {@link get}. `GET /api/v1/customers/ext/:externalId`.
+     * An unknown external id is a `NotFoundError`; only active customers match.
+     */
+    getByExternalId(externalId: string): Promise<ApiCustomer>;
+    /** Update a customer (partial), addressed by its `externalId`. Same body as
+     *  {@link update}. `PATCH /api/v1/customers/ext/:externalId`. */
+    updateByExternalId(externalId: string, input: CustomerProfileInput): Promise<ApiCustomer>;
+    /** {@link delete}, addressing the customer by its `externalId`.
+     *  `DELETE /api/v1/customers/ext/:externalId`. */
+    deleteByExternalId(externalId: string): Promise<void>;
     /** Delete a customer (members, invitations, usage logs cascade). */
     delete(id: string): Promise<void>;
-    /** A customer's usage history. `GET /api/v1/usage?customerId=`. */
-    usage(id: string, params?: {
-        limit?: number;
-    }): Promise<UsageList>;
     /** Wallet / credit / outcome / unit balances. `GET …/:id/balances`. */
     balances(id: string): Promise<CustomerBalances>;
+    /** {@link balances}, addressing the customer by its `externalId`.
+     *  `GET /api/v1/customers/ext/:externalId/balances`. */
+    balancesByExternalId(externalId: string): Promise<CustomerBalances>;
     /**
      * One credit balance for a customer, matched by `creditId` or `creditName`;
      * `null` when the customer has no plan or no matching credit. Convenience
@@ -1798,6 +1734,9 @@ declare class Customers {
     }): Promise<UnitBalance | null>;
     /** The customer's current plan. `GET …/:id/plan`. */
     plan(id: string): Promise<CustomerPlan>;
+    /** {@link plan}, addressing the customer by its `externalId`.
+     *  `GET /api/v1/customers/ext/:externalId/plan`. */
+    planByExternalId(externalId: string): Promise<CustomerPlan>;
     /** List a customer's members. `GET …/:id/members`. */
     listMembers(id: string): Promise<Member[]>;
     /** Add a member to a customer. Duplicate `email` → ConflictError. */
@@ -1806,39 +1745,63 @@ declare class Customers {
     updateMember(id: string, memberId: string, input: UpdateMemberInput): Promise<MemberProfile>;
     /** Remove a member from a customer, returning who was removed. `DELETE …/:id/members/:memberId`. */
     removeMember(id: string, memberId: string): Promise<RemovedMember>;
-    /** The customer's wallet balance + transactions. `GET …/:id/wallet`. */
-    wallet(id: string, params?: {
-        limit?: number;
-    }): Promise<WalletList>;
+    /** Grant or claw back a credit balance. The credit must be a prepaid part of
+     *  the customer's current plan. Pass `idempotencyKey` to make it safe to
+     *  retry. `POST …/:id/credits/adjust`. */
+    adjustCredit(id: string, input: CreditAdjustInput): Promise<AdjustResult>;
+    /** Grant or claw back an outcome balance. The outcome must be a prepaid part
+     *  of the customer's current plan. `POST …/:id/outcomes/adjust`. */
+    adjustOutcome(id: string, input: OutcomeAdjustInput): Promise<AdjustResult>;
+    /** Grant or claw back a unit balance. The unit must be a prepaid part of the
+     *  customer's current plan. `POST …/:id/units/adjust`. */
+    adjustUnit(id: string, input: UnitAdjustInput): Promise<AdjustResult>;
+    /** Grant or claw back slots on a customer's ADVANCE composite pool for the
+     *  current billing cycle. `remaining` is the resulting slot count.
+     *  `POST …/:id/composites/adjust`. */
+    adjustComposite(id: string, input: CompositeAdjustInput): Promise<AdjustResult>;
     /**
-     * Record a manual wallet entry (top-up or deduction). `amount` is always
-     * positive; the sign comes from `type`. `POST …/:id/wallet`.
+     * 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
+     * `remaining` is its balance). `POST …/:id/wallet/adjust`.
      */
-    addWalletEntry(id: string, input: WalletEntryInput): Promise<{
-        transaction: WalletTransaction;
-        balanceUsd: number;
-    }>;
-    /** Grant or claw back a credit balance. Returns the remaining balance.
-     *  `POST …/:id/credits/adjust`. */
-    adjustCredit(id: string, input: CreditAdjustInput): Promise<{
-        remaining: number;
-    }>;
-    /** Grant or claw back an outcome balance. Returns the remaining balance. */
-    adjustOutcome(id: string, input: OutcomeAdjustInput): Promise<{
-        remaining: number;
-    }>;
-    /** Grant or claw back a unit balance. Returns the remaining balance. */
-    adjustUnit(id: string, input: UnitAdjustInput): Promise<{
-        remaining: number;
-    }>;
+    adjustWallet(id: string, input: WalletAdjustInput): Promise<AdjustResult>;
+    /** {@link adjustCredit}, addressing the customer by its `externalId` (`id`
+     *  here). `POST /api/v1/customers/ext/:externalId/credits/adjust`. */
+    adjustCreditByExternalId(id: string, input: CreditAdjustInput): Promise<AdjustResult>;
+    /** {@link adjustOutcome}, addressing the customer by its `externalId` (`id`
+     *  here). `POST /api/v1/customers/ext/:externalId/outcomes/adjust`. */
+    adjustOutcomeByExternalId(id: string, input: OutcomeAdjustInput): Promise<AdjustResult>;
+    /** {@link adjustUnit}, addressing the customer by its `externalId` (`id`
+     *  here). `POST /api/v1/customers/ext/:externalId/units/adjust`. */
+    adjustUnitByExternalId(id: string, input: UnitAdjustInput): Promise<AdjustResult>;
+    /** {@link adjustComposite}, addressing the customer by its `externalId`
+     *  (`id` here). `POST /api/v1/customers/ext/:externalId/composites/adjust`. */
+    adjustCompositeByExternalId(id: string, input: CompositeAdjustInput): Promise<AdjustResult>;
+    /** {@link adjustWallet}, addressing the customer by its `externalId` (`id`
+     *  here). `POST /api/v1/customers/ext/:externalId/wallet/adjust`. */
+    adjustWalletByExternalId(id: string, input: WalletAdjustInput): Promise<AdjustResult>;
+    /**
+     * The one body behind all ten adjust calls.
+     *
+     * Every adjustment carries an idempotency key — the caller's, or one
+     * generated here ONCE per call, exactly like signals. The server
+     * deduplicates on it, so a transient failure is safe to retry: the same key
+     * rides every attempt, and a retry of one that already landed comes back as
+     * `replayed: true` instead of adjusting again. The key is also copied onto
+     * any thrown error (`error.idempotencyKey`) so the caller can replay safely.
+     */
+    private adjust;
     /**
-     * Grant or claw back slots on a customer's ADVANCE composite pool for the
-     * current billing cycle. Returns the resulting `remaining` slot count.
-     * `POST …/:id/composites/adjust`.
+     * Change how much a customer is granted every billing cycle (wallet top-up,
+     * credits, outcomes, units or a composite pool). Any increase or decrease
+     * applies to their current balance immediately. `PUT …/:id/recurring-grant`.
      */
-    adjustComposite(id: string, input: CompositeAdjustInput): Promise<{
-        remaining: number;
-    }>;
+    updateRecurringGrant(id: string, input: RecurringGrantInput): Promise<RecurringGrantResult>;
+    /** {@link updateRecurringGrant}, addressing the customer by its
+     *  `externalId`. `PUT /api/v1/customers/ext/:externalId/recurring-grant`. */
+    updateRecurringGrantByExternalId(externalId: string, input: RecurringGrantInput): Promise<RecurringGrantResult>;
 }
 
 /**
@@ -1858,42 +1821,44 @@ declare class Invoices {
     /** Fetch one full invoice + its plan snapshot. `GET /api/v1/invoices/:id`. */
     get(id: string): Promise<InvoiceDetail>;
     /**
-     * Mint a hosted pay link for an OPEN invoice. PAID/VOID invoices are rejected
+     * Mint a hosted pay link for an OPEN invoice. PAID/VOID/AUTO_CLOSED invoices are rejected
      * with a `ConflictError`. `GET /api/v1/invoices/:id/pay-link`.
      */
     payLink(id: string): Promise<PayLink>;
 }
 
 /**
- * The `outcomes` resource — manage the org's outcome *types* (the catalog). An
- * outcome is a multi-step workflow. `/api/v1/outcomes`.
+ * 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.
  *
- * Two distinct kinds of agent key, in separate namespaces, each unique per
- * organisation — do not conflate them:
- * - the OUTCOME's own `agentKey`, REQUIRED on `create()` and `update()`, which
- *   names the outcome itself in the catalogue;
- * - each STEP's `agentKey`, which is what you pass to `signals.outcome()` to
- *   report usage and to the outcome-adjust API.
+ * There is no `delete()` — the API never deletes catalogue items. Retire an
+ * outcome with `archive()`; `unarchive()` brings it back unchanged.
  */
 declare class Outcomes {
     private readonly transport;
     constructor(transport: Transport);
-    /** List outcome 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. */
     list(params?: {
         active?: boolean;
     }): Promise<Outcome[]>;
-    /** Create an outcome type with its steps. `POST /api/v1/outcomes`. */
+    /** One outcome's configuration, with every step in full. */
+    get(id: string): Promise<OutcomeWithSteps>;
+    /** Create one. It starts active. Not retried on failure — a retry could
+     *  create a second row. */
     create(input: CreateOutcomeInput): Promise<Outcome>;
-    /** Fetch one outcome type with steps + stats. `GET /api/v1/outcomes/:id`. */
-    get(id: string): Promise<OutcomeDetail>;
-    /** Update an outcome type's definition. `PATCH /api/v1/outcomes/:id`. */
+    /** 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. */
     update(id: string, input: UpdateOutcomeInput): Promise<Outcome>;
-    /** Activate or deactivate an outcome type; returns the updated outcome. */
-    setActive(id: string, isActive: boolean): Promise<Outcome>;
-    /** Delete an outcome type. */
-    delete(id: string): Promise<void>;
+    /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+    archive(id: string): Promise<Outcome>;
+    /** Bring an archived one back (`isActive` → true). Safe to retry. */
+    unarchive(id: string): Promise<Outcome>;
 }
 
 /**
@@ -1913,9 +1878,14 @@ declare class Payments {
 }
 
 /**
- * The `plans` resource — define and manage the billing plans customers
- * 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.
  */
 declare class Plans {
     private readonly transport;
@@ -1926,16 +1896,20 @@ declare class Plans {
     list(params?: {
         active?: boolean;
     }): Promise<Plan[]>;
-    /** Create a plan. `POST /api/v1/plans`. */
+    /** One plan's configuration. */
+    get(id: string): Promise<Plan>;
+    /** Create a plan. It starts active. Not retried on failure — a retry could
+     *  create a second plan. */
     create(input: CreatePlanInput): Promise<Plan>;
-    /** Fetch one plan with aggregate subscriber/invoice stats. `GET /api/v1/plans/:id`. */
-    get(id: string): Promise<PlanDetail>;
-    /** Replace a plan's definition (components + settings). `PATCH /api/v1/plans/:id`. */
+    /** 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. */
     update(id: string, input: UpdatePlanInput): Promise<Plan>;
-    /** Activate or deactivate a plan without rewriting it. */
-    setActive(id: string, isActive: boolean): Promise<Plan>;
-    /** Delete a plan. Refused once any customer has purchased it. */
-    delete(id: string): Promise<void>;
+    /** Retire a plan (`isActive` → false): it can't be bought any more; customers
+     *  already on it are unaffected. Safe to retry. */
+    archive(id: string): Promise<Plan>;
+    /** Make an archived plan purchasable again (`isActive` → true). Safe to retry. */
+    unarchive(id: string): Promise<Plan>;
 }
 
 /**
@@ -2144,19 +2118,6 @@ declare class Signals {
      * not a safe no-op — see {@link OutcomeCompletionResult}.
      */
     completeOutcome(input: OutcomeCompletionInput): Promise<OutcomeCompletionResult>;
-    /**
-     * Recent usage logs + totals for a customer. `GET /api/v1/usage`.
-     *
-     * Still the legacy path, deliberately. The `/api/v1/signal/*` family is
-     * POST-only — it replaced how usage is INGESTED, not how it is read — so
-     * `GET /api/v1/usage` has no successor and is not deprecated. It is also the
-     * only way to prove a signal landed, which matters more now that ingestion
-     * answers `202` for everything.
-     */
-    list(params: {
-        customerId: string;
-        limit?: number;
-    }): Promise<UsageList>;
     /**
      * Record one unit-metered event (a fixed-price meter with no tokens),
      * addressed to a catalog unit by its `agentKey`. Sent immediately — unit
@@ -2196,16 +2157,6 @@ declare class Signals {
      * rather than failing it.
      */
     completeComposite(input: CompositeCompletionInput): Promise<CompositeCompletionResult>;
-    /**
-     * A customer's unit balances + recent unit events. `GET /api/v1/units`.
-     *
-     * Legacy path for the same reason as {@link list}: the signal family is
-     * POST-only, so the read side has no successor and is not deprecated.
-     */
-    unitUsage(params: {
-        customerId: string;
-        limit?: number;
-    }): Promise<UnitUsageList>;
     /**
      * One customer's usage history, merged from every meter kind — credit,
      * outcome, unit, wallet, and completed composite occurrences — into one
@@ -2227,63 +2178,32 @@ declare class Signals {
 }
 
 /**
- * The `units` resource — manage the org's unit *types* (the catalog): named,
- * quantity-priced meters (FLAT / SLAB / VOLUME). Record consumption against a
- * unit with `signals.unit()`. `/api/v1/units-catalog`.
+ * 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.
  */
 declare class Units {
     private readonly transport;
     constructor(transport: Transport);
-    /** List unit 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. */
     list(params?: {
         active?: boolean;
     }): Promise<Unit[]>;
-    /** Create a unit type. `POST /api/v1/units-catalog`. */
+    /** One unit's configuration. */
+    get(id: string): Promise<Unit>;
+    /** Create one. It starts active. Not retried on failure — a retry could
+     *  create a second row. */
     create(input: CreateUnitInput): Promise<Unit>;
-    /** Fetch one unit type with stats. `GET /api/v1/units-catalog/:id`. */
-    get(id: string): Promise<UnitDetail>;
-    /** Update a unit type's definition. `PATCH /api/v1/units-catalog/:id`. */
+    /** PARTIAL update: only the fields you send change. `tiers`, when sent, is
+     *  the complete new tier list. */
     update(id: string, input: UpdateUnitInput): Promise<Unit>;
-    /** Activate or deactivate a unit type. */
-    setActive(id: string, isActive: boolean): Promise<Unit>;
-    /** Delete a unit type. */
-    delete(id: string): Promise<void>;
-}
-
-/**
- * The `webhooks` resource — threshold alerts. At most one webhook per kind
- * (CREDIT / OUTCOME / WALLET); posting a kind again upserts it. `/api/v1/webhooks`.
- */
-declare class Webhooks {
-    private readonly transport;
-    constructor(transport: Transport);
-    /** List configured webhooks. `GET /api/v1/webhooks`. */
-    list(): Promise<Webhook[]>;
-    /** Create or replace the webhook for a kind. `POST /api/v1/webhooks`. */
-    upsert(input: UpsertWebhookInput): Promise<Webhook>;
-    /** Delete the webhook for a kind (idempotent). `DELETE /api/v1/webhooks/:kind`. */
-    delete(kind: ThresholdKind): Promise<void>;
-}
-
-/**
- * The `workspace` resource — read-only introspection of the org behind the API
- * key. Grounds an integration (which workspace, and is it `sandbox` or `live`?)
- * and lists the models it may meter against. `/api/v1/me`, `/api/v1/models`.
- */
-declare class Workspace {
-    private readonly transport;
-    constructor(transport: Transport);
-    /** Identify the org + key behind the request, incl. `sandbox` | `live`. */
-    me(): Promise<WorkspaceIdentity>;
-    /** The org's enabled models with live prices. `{ active: true }` returns only
-     *  the models that can be metered right now.
-     *  `{ active: false }` returns only archived ones; omitting it returns
-     *  both. See `activeQuery` — the API itself only supports `true`. */
-    models(params?: {
-        active?: boolean;
-    }): Promise<Model[]>;
+    /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+    archive(id: string): Promise<Unit>;
+    /** Bring an archived one back (`isActive` → true). Safe to retry. */
+    unarchive(id: string): Promise<Unit>;
 }
 
 /**
@@ -2304,32 +2224,28 @@ declare class Workspace {
  * ```
  */
 declare 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;
     private readonly flusher;
     constructor(config: ClockNextConfig);
@@ -2417,4 +2333,4 @@ declare class NetworkError extends ClockNextError {
     });
 }
 
-export { type AddMemberInput, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeCatalogueRef, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeComponentInput, type CompositeTag, ConflictError, type CostPoint, type CostStats, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditAnalytics, type CreditBalance, type CreditComponentInput, type CreditDetail, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type DropReason, type FetchLike, type FlatComponentInput, type FlatUnitInput, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type Model, type ModelBundleEntry, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeAnalytics, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, type OutcomeComponentInput, type OutcomeDetail, type OutcomeInput, type OutcomeSignal, type OutcomeStepInput, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanComponentInput, type PlanDetail, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type ThresholdKind, type TieredUnitInput, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitComponentInput, type UnitCustomerRow, type UnitDetail, type UnitInput, type UnitPricingType, type UnitTier, type UnitTierInput, type UnitTrackResult, type UnitUsageList, type UnitUsageRow, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UpsertWebhookInput, type UsageBalance, type UsageList, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogOutcomeAttribution, type UsageLogPage, type UsageLogPeriod, ValidationError, type WalletComponentInput, type WalletEntitlementKind, type WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionSource, type WalletTransactionType, type Webhook, type WorkspaceIdentity, signalToWire };
+export { type AddMemberInput, type AdjustResult, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeBalance, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeItem, type CompositeTag, ConflictError, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditBalance, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type CustomerRef, type DropReason, type FetchLike, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type ModelBundleLine, type ModelBundleLineInput, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, type OutcomeInput, type OutcomeSignal, type OutcomeStep, type OutcomeStepInput, type OutcomeWithSteps, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanEntitlement, type PlanEntitlementInput, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RecurringGrantInput, type RecurringGrantResult, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitInput, type UnitPricingType, type UnitTier, type UnitTrackResult, type UpdateCompositeInput, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UsageBalance, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogOutcomeAttribution, type UsageLogPage, type UsageLogPeriod, ValidationError, type WalletAdjustInput, type WalletInput, type WalletPool, type WalletSignal, signalToWire };