@clocknext/sdk 0.13.0 → 0.15.0

package/dist/index.d.cts

@@ -56,37 +56,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 +102,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 +127,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 +139,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 +156,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()`.
  *
@@ -274,7 +269,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 +291,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,23 +336,98 @@ interface TrackResult {
      */
     rawId?: string;
 }
-interface UsageList {
-    customer: {
-        id: string;
-        name: string;
-        creditAllowance: number;
+/** A preset time window, or `"custom"` for an explicit `from`/`to` range. */
+type UsageLogPeriod = "all" | "today" | "7d" | "30d" | "90d" | "custom";
+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;
+}
+interface UsageLogAppliedRule {
+    ruleId: string | null;
+    ruleName: string;
+    mode: "MARGIN" | "CREDIT" | null;
+    marginPercentApplied: number | null;
+    /** Formatted, same as {@link UsageLogEntry.credit}'s `amount`. */
+    creditsApplied: string;
+}
+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.
+ */
+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;
     };
-    totals: {
-        count: number;
-        cost: number;
-        revenue: number;
-        profit: number;
-        creditsUsed: number;
+    /** Formatted USD strings (e.g. `"$0.0064"`). */
+    cost: {
+        providedCost: string;
+        customerCost: string;
     };
-    logs: SerializedUsageLog[];
+    /** 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;
+}
+interface UsageLogPage {
+    usageLogs: UsageLogEntry[];
+    /** Pass this back as `cursor` to fetch the next page; `null` on the last
+     *  page. */
+    nextCursor: string | null;
 }
 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;
@@ -373,11 +443,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;
@@ -392,6 +474,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 & {
@@ -423,7 +509,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;
@@ -450,9 +536,15 @@ interface CustomerBalances {
         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[];
@@ -503,7 +595,6 @@ interface PortalToken {
 type BillingCycle = "MONTHLY" | "QUARTERLY" | "SEMI_ANNUAL" | "YEARLY" | "EVERY_5_MIN" | "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.
  *
@@ -515,116 +606,6 @@ 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 {
     id: string;
     type: ComponentType;
@@ -632,11 +613,9 @@ 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;
@@ -658,22 +637,8 @@ interface Plan {
     isActive: boolean;
     components: PlanComponent[];
 }
-/** The richer plan returned by `plans.get()` (adds aggregate stats). */
-interface PlanDetail extends Plan {
-    createdAt: string;
-    createdByName: string | null;
-    customerCount: number;
-    invoiceCount: number;
-    openInvoiceCount: number;
-    stats: {
-        totalInvoiced: number;
-        totalCollected: number;
-        openBalance: number;
-    };
-}
 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;
@@ -681,7 +646,7 @@ interface CreatePurchaseInput {
     autoPayment?: boolean;
     /** Auto-void the purchase if unpaid after N minutes. */
     voidAfterMinutes?: number;
-}
+};
 interface Purchase {
     id: string;
     purchaseNumber: string;
@@ -739,7 +704,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;
@@ -903,64 +870,76 @@ 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}).
+ */
+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.
+     *
+     * `"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 {
@@ -969,16 +948,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
@@ -990,7 +994,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.
@@ -998,248 +1002,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;
     /**
@@ -1270,7 +1092,7 @@ interface UnitInput {
      * auto key cannot survive.
      */
     idempotencyKey?: string;
-}
+};
 /**
  * The result of `signals.unit()`.
  *
@@ -1298,8 +1120,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;
@@ -1307,71 +1128,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()`.
  *
@@ -1407,8 +1164,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;
@@ -1423,42 +1179,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;
@@ -1590,66 +1310,9 @@ declare class Transport {
     private buildUrl;
 }
 
-/**
- * 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`.
- *
- * 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()`.
- *
- * 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).
- */
-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(params?: {
-        active?: boolean;
-    }): Promise<Composite[]>;
-    /** Create a composite. `POST /api/v1/composites`. */
-    create(input: CreateCompositeInput): 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`.
- */
-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(params?: {
-        active?: boolean;
-    }): Promise<Credit[]>;
-    /** Create a credit type; returns the created credit. `POST /api/v1/credits`. */
-    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`. */
-    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>;
-}
-
 /**
  * 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.
  */
@@ -1676,14 +1339,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
@@ -1711,6 +1385,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. */
@@ -1719,39 +1396,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>;
     /**
-     * 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`.
+     * 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.
      */
-    adjustComposite(id: string, input: CompositeAdjustInput): Promise<{
-        remaining: number;
-    }>;
+    private 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`.
+     */
+    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>;
 }
 
 /**
@@ -1771,44 +1472,12 @@ 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`.
- *
- * 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.
- */
-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(params?: {
-        active?: boolean;
-    }): Promise<Outcome[]>;
-    /** Create an outcome type with its steps. `POST /api/v1/outcomes`. */
-    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`. */
-    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>;
-}
-
 /**
  * The `payments` resource — read-only. A payment is a PAID invoice; the `id`
  * used here is that underlying invoice id. `/api/v1/payments`.
@@ -1826,9 +1495,9 @@ 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 — read the billing plans customers can subscribe to.
+ * Each plan is a set of entitlement components (wallet / credit / outcome /
+ * unit / flat) billed on a cycle. `/api/v1/plans`.
  */
 declare class Plans {
     private readonly transport;
@@ -1839,16 +1508,6 @@ declare class Plans {
     list(params?: {
         active?: boolean;
     }): Promise<Plan[]>;
-    /** Create a plan. `POST /api/v1/plans`. */
-    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`. */
-    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>;
 }
 
 /**
@@ -2057,19 +1716,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
@@ -2110,75 +1756,23 @@ declare class Signals {
      */
     completeComposite(input: CompositeCompletionInput): Promise<CompositeCompletionResult>;
     /**
-     * A customer's unit balances + recent unit events. `GET /api/v1/units`.
+     * One customer's usage history, merged from every meter kind — credit,
+     * outcome, unit, wallet, and completed composite occurrences — into one
+     * feed sorted by time. `GET /api/v1/signal/usage-log`. Exactly the same
+     * rows the customer portal's own "Usage logs" table shows, so a caller can
+     * build against this instead of the portal UI.
+     *
+     * Cursor-paginated, NOT page-numbered: `limit` + `cursor` in, `nextCursor`
+     * out. Omit `cursor` for the first page; pass the previous page's
+     * `nextCursor` back to fetch the next one, and stop once it comes back
+     * `null`. Unlike offset pagination, the cost of a page never grows with how
+     * deep you've paged — each page only asks for rows strictly before the
+     * cursor's position.
      *
-     * 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.
+     * Read-only; unlike {@link track}/{@link unit}/etc., there is nothing to
+     * buffer or retry here.
      */
-    unitUsage(params: {
-        customerId: string;
-        limit?: number;
-    }): Promise<UnitUsageList>;
-}
-
-/**
- * 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`.
- */
-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(params?: {
-        active?: boolean;
-    }): Promise<Unit[]>;
-    /** Create a unit type. `POST /api/v1/units-catalog`. */
-    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`. */
-    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[]>;
+    usageLog(params: UsageLogListParams): Promise<UsageLogPage>;
 }
 
 /**
@@ -2199,11 +1793,11 @@ 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. */
+    /** List billing plans. */
     readonly plans: Plans;
     /** Subscribe customers to plans (purchases). */
     readonly purchases: Purchases;
@@ -2211,20 +1805,8 @@ declare class ClockNext {
     readonly invoices: Invoices;
     /** Read payments (paid invoices). */
     readonly payments: Payments;
-    /** Manage the credit-type catalog. */
-    readonly credits: Credits;
-    /** Manage the composite catalog — bundles billed as one thing. */
-    readonly composites: Composites;
-    /** Manage the outcome-type catalog. */
-    readonly outcomes: Outcomes;
-    /** Manage the unit-type catalog. */
-    readonly units: Units;
-    /** Configure threshold webhooks. */
-    readonly webhooks: Webhooks;
     /** Mint customer-portal embed tokens. */
     readonly portal: Portal;
-    /** Identify the workspace (sandbox/live) + list its models. `/me`, `/models`. */
-    readonly workspace: Workspace;
     private readonly cfg;
     private readonly flusher;
     constructor(config: ClockNextConfig);
@@ -2312,4 +1894,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, 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 CompositeAdjustInput, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeTag, ConflictError, type CreateCustomerInput, type CreatePurchaseInput, 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, NetworkError, NotFoundError, type OutcomeAdjustInput, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, type OutcomeInput, type OutcomeSignal, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, 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 UnitAdjustInput, type UnitBalance, type UnitInput, type UnitTrackResult, type UpdateMemberInput, type UsageBalance, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogOutcomeAttribution, type UsageLogPage, type UsageLogPeriod, ValidationError, type WalletAdjustInput, type WalletInput, type WalletPool, type WalletSignal, signalToWire };