@clocknext/sdk 0.11.0 → 0.12.0

package/src/types.ts

@@ -0,0 +1,1599 @@
+/**
+ * Public types for the ClockNext SDK.
+ *
+ * The signal types mirror the bodies of the `/api/v1/signal/*` routes as a
+ * discriminated union, so the per-kind required fields the server enforces with
+ * Zod are enforced here at compile time instead of surfacing as runtime 400s.
+ *
+ * The server now has one schema per route rather than one schema with a `type`
+ * discriminator, which is why `type` no longer appears on the wire — it selects
+ * the route instead. It stays on these types because it is still the
+ * discriminator callers write and TypeScript narrows on.
+ */
+
+// ---------------------------------------------------------------------------
+// Signals
+// ---------------------------------------------------------------------------
+
+export type SignalType = "wallet" | "credit" | "outcome";
+export 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.
+ */
+export interface Tokens {
+  input: number;
+  output: number;
+  cache?: number;
+}
+
+/**
+ * Groups a signal into one occurrence of a **composite** — a bundle of credits
+ * / outcomes / units that is priced and billed as a single thing.
+ *
+ * `ref` is the composite's `refId` (defined in the dashboard) and `value` is
+ * your own correlation id for one occurrence: a session, a call, a job. Every
+ * signal sharing a value belongs to the same occurrence.
+ *
+ * This is NOT reporting-only (earlier versions of this SDK called it a
+ * "pricing metric" and said so — that was wrong). Where the customer's plan
+ * sells the composite, the occurrence IS the billable unit: it opens on the
+ * first tagged signal costing nothing, and is charged once when you close it
+ * with `signals.completeComposite()` — claiming a prepaid slot on an ADVANCE
+ * component, or becoming countable on an ARREAR one.
+ *
+ * What stays true is that a bad tag never fails the signal: a `ref` naming no
+ * live composite is ignored rather than rejected, because the signal carries
+ * money and the tag only decides what it is grouped under. Applies to credit,
+ * outcome and unit signals; a tag on a wallet signal is accepted and ignored,
+ * since raw wallet spend is not entitlement traffic.
+ *
+ * Only ONE composite per signal is expressible here. The wire format accepts
+ * several (`composite` is an object of ref → value), so if you need a signal
+ * in two composites at once, that is the limit to lift.
+ */
+export interface CompositeTag {
+  /** The composite's `refId`. Case-insensitive. Unlike earlier versions this
+   *  no longer shares a namespace with the ingest fields — the tag is nested
+   *  under `composite` on the wire — so a composite may safely be called
+   *  `model`, `status`, or anything else. */
+  ref: string;
+  /** Your correlation value for this occurrence, stored verbatim. */
+  value: string | number;
+}
+
+// ---------------------------------------------------------------------------
+// Workspace (mirrors GET /api/v1/me and GET /api/v1/models)
+// ---------------------------------------------------------------------------
+
+/** The organisation + key behind a request — `cnk.workspace.me()`. */
+export interface WorkspaceIdentity {
+  organization: {
+    id: string;
+    name: string;
+    slug: string | null;
+    /** `sandbox` is a disposable staging twin; `live` bills for real. Check
+     *  this before sending production traffic. */
+    environment: "sandbox" | "live";
+  };
+  apiKey: {
+    prefix: string;
+    lastFour: string;
+    expiresAt: string | null;
+  } | null;
+}
+
+/** One model the org has enabled — `cnk.workspace.models()`. The `modelId` is
+ *  what you put in a signal's `model`. Prices are USD per 1,000,000 tokens. */
+export interface Model {
+  modelId: string;
+  modelName: string;
+  provider: string;
+  providerName: string;
+  isActive: boolean;
+  inputPrice: number;
+  outputPrice: number;
+  cachePrice: number;
+}
+
+interface SignalBase {
+  /** The customer this usage belongs to (required). */
+  customerId: string;
+  /**
+   * The model's catalog id — must be enabled in your ClockNext org
+   * (Settings → Models). Matched case-insensitively against `OrgModel.modelId`.
+   */
+  model: string;
+  /** Token counts for this call — required; every metered signal is priced on
+   *  tokens. (`cache` within is optional; `input`/`output` are not.) */
+  tokens: Tokens;
+  /** Optional member (email) this usage is attributed to. */
+  member?: string;
+  /** Free-form metadata. Credit rules can target `custom.<key>` paths. */
+  custom?: Record<string, unknown>;
+  /**
+   * Idempotency key for safe retries. **Auto-generated (UUID v4) if omitted**
+   * and reused across every retry of this signal, so a retried send is
+   * deduplicated server-side instead of double-recording. Supply your own — a
+   * stable id for this logical event — to also dedup across process restarts or
+   * at-least-once redelivery, which an in-memory auto key can't survive.
+   */
+  idempotencyKey?: string;
+}
+
+/** Meters a credit, identified by the credit's stable `agentKey`. */
+export interface CreditSignal extends SignalBase {
+  type: "credit";
+  /** The Credit's stable agent key (assigned when the credit was created). */
+  agentKey: string;
+  /** Optional composite this signal belongs to. See {@link CompositeTag}. */
+  composite?: CompositeTag;
+}
+
+/** Debits the customer's wallet in USD at the model's cost. */
+export interface WalletSignal extends SignalBase {
+  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
+ * may repeat freely. The run bills once, when the caller marks it `complete`.
+ */
+export interface OutcomeSignal extends SignalBase {
+  type: "outcome";
+  /** The OutcomeStep's stable agent key — identifies the outcome AND the step. */
+  agentKey: string;
+  /**
+   * Correlates every signal of one workflow run. Required. A step may fire more
+   * than once within a run (a "verify" loop firing 3× is three signals, one
+   * outcome). Opaque to ClockNext — any string you can correlate; unique per org.
+   */
+  runId: string;
+  /**
+   * Set `true` on the LAST step signal to declare the run finished — completion
+   * is never inferred from step coverage. Sending it twice is a safe no-op and
+   * can't bill again.
+   *
+   * This closes the RUN only. If the signal also carries a `composite`, that
+   * occurrence stays open and unbilled until you call
+   * `signals.completeComposite()` — the two completions are separate, and
+   * neither implies the other.
+   */
+  complete?: boolean;
+  /** Optional composite this signal belongs to. See {@link CompositeTag}. */
+  composite?: CompositeTag;
+}
+
+export type Signal = CreditSignal | WalletSignal | OutcomeSignal;
+
+/** Helper input shapes for the per-type convenience methods. */
+export type CreditInput = Omit<CreditSignal, "type">;
+export type WalletInput = Omit<WalletSignal, "type">;
+export type OutcomeInput = Omit<OutcomeSignal, "type">;
+
+// ---------------------------------------------------------------------------
+// Server response shapes (mirrors src/lib/usage/log.ts)
+// ---------------------------------------------------------------------------
+
+export interface SerializedRuleApplication {
+  ruleId: string | null;
+  ruleName: string;
+  creditsApplied: number;
+}
+
+export interface SerializedOutcomeAttribution {
+  name: string;
+  /** The step of the outcome this signal performed. */
+  step: string;
+  /** The caller's run id — every signal of one run shares it. `null` on logs
+   *  recorded before the run-based flow. */
+  runId: string | null;
+  /** True when this signal ended the run (`complete: true`). */
+  closedRun: boolean;
+  /** True once the run's completion was counted against the allowance. Diverges
+   *  from `closedRun` only when a run closes with no allowance left — it waits,
+   *  then flips true once a top-up settles it. */
+  completed: boolean;
+  /** How many signals the run holds after this one. */
+  signalCount: number;
+  /** The outcome's catalogue step count — not a progress target, since steps
+   *  may repeat within a run. */
+  totalSteps: number;
+}
+
+/** The customer's remaining balance for the dimension a signal metered, AFTER
+ *  the signal was applied — update an on-screen meter straight from the record
+ *  response. Populated on recorded (inline / `{ wait: true }`) signals; `null`
+ *  on read-back. */
+export interface UsageBalance {
+  dimension: "credit" | "outcome" | "wallet";
+  /** Post-signal remaining. `null` when the meter is uncapped — an ARREAR
+   *  (pay-as-you-go) credit or outcome has no fixed allowance. */
+  remaining: number | null;
+  /** The credit / outcome name; `null` for the wallet. */
+  name: string | null;
+}
+
+export interface SerializedUsageLog {
+  id: string;
+  customerId: string;
+  modelName: string | null;
+  creditName: string | null;
+  member: string | null;
+  inputTokens: number;
+  outputTokens: number;
+  cacheTokens: 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. */
+  credit: number;
+  providedCost: number;
+  customerCost: number;
+  status: SignalStatus;
+  appliedRules: SerializedRuleApplication[];
+  outcome: SerializedOutcomeAttribution | null;
+  /** Post-signal balance for the metered dimension. Null on
+   *  read-back. */
+  balance: UsageBalance | null;
+  createdAt: string;
+}
+
+/**
+ * Result of a single signal send (sync mode, or `{ wait: true }`).
+ *
+ * `queued: true` has TWO causes, and they are not the same thing:
+ * 1. **Client-side buffering** (async mode, no `wait`) — the signal is in this
+ *    process's buffer and has not been sent. No `messageId`.
+ * 2. **Server-side durable hand-off** — the request WAS sent and the server
+ *    answered `202 Accepted`, having enqueued it for a worker to price. Carries
+ *    a `messageId`. `usageLog` is null: the log does not exist yet.
+ *
+ * In case 2 the signal is accepted but **not yet billed**, and it has only been
+ * shallowly validated. A bad `agentKey`, a customer with no matching plan, or an
+ * 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 })`.
+ *
+ * When the server has no queue configured it prices inline instead and returns
+ * `queued: false` with a populated `usageLog`, validating synchronously.
+ */
+
+/**
+ * How far a metering call actually got. See {@link TrackResult.status} — the
+ * three states differ in whether the signal can still be lost, and in whether
+ * it has been billed.
+ */
+export type SignalDelivery = "buffered" | "accepted" | "recorded" | "dropped";
+export interface TrackResult {
+  /**
+   * How far this signal has actually got. Branch on this, not on `queued`.
+   *
+   *   `"buffered"` — held in THIS process's memory and not yet sent. Lost if
+   *                  the process exits first, so `flush()`/`close()` before it
+   *                  can. No `rawId` exists yet.
+   *   `"accepted"` — the server has written it to its durable inbox (`202`)
+   *                  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 —
+   *                  read it back with `signals.list()`.
+   *   `"recorded"` — the server priced it inline and `usageLog` is populated.
+   *   `"dropped"`  — the SDK threw it away without sending: the client is
+   *                  closed, or the local queue is full. `onDrop` fired with
+   *                  the reason. This state exists because the alternative was
+   *                  reporting `"buffered"` for a signal that was discarded —
+   *                  a success-shaped answer to a lost billable event.
+   *
+   * Note what none of these mean: "waited for a price". Even `{ wait: true }`
+   * waits only for the server to ACCEPT the signal, never for it to finish
+   * pricing — holding a request thread open for a billing round-trip is
+   * exactly the cost this design exists to avoid.
+   */
+  status: SignalDelivery;
+  /**
+   * True for both `"buffered"` and `"accepted"` — i.e. "not priced yet".
+   *
+   * Kept for compatibility, but it collapses two states with opposite failure
+   * behaviour (one is lost when the process dies, the other cannot be) into
+   * one boolean, which is why {@link TrackResult.status} exists. Prefer that.
+   */
+  queued: boolean;
+  /** The computed usage log. Non-null ONLY when the server priced the signal
+   *  inline (`queued: false`); null on a `202` hand-off and absent while the
+   *  signal sits in the client-side buffer. */
+  usageLog?: SerializedUsageLog | null;
+  /** The server's durable-queue message id, present only on a `202` hand-off
+   *  (server-side queueing). Absent for client-side buffering and for inline
+   *  pricing. */
+  messageId?: string;
+  /**
+   * The signal's durable inbox id, returned by every `/api/v1/signal/*`
+   * response — the `202` hand-off AND inline pricing. Present whenever the
+   * server has written the request down, which it now does BEFORE validating
+   * or pricing it, so a `rawId` means "this signal cannot be lost" even when
+   * `usageLog` is null. Quote it when asking why a signal has not been billed;
+   * it is the row the dashboard shows as Processing / Pending / Processed.
+   *
+   * Absent while the signal sits in the client-side buffer (nothing has been
+   * sent yet, so the server has no id for it).
+   */
+  rawId?: string;
+}
+
+export interface UsageList {
+  customer: { id: string; name: string; creditAllowance: number };
+  totals: {
+    count: number;
+    cost: number;
+    revenue: number;
+    profit: number;
+    creditsUsed: number;
+  };
+  logs: SerializedUsageLog[];
+}
+
+// ---------------------------------------------------------------------------
+// Customers (mirrors src/lib/customers/api.ts)
+// ---------------------------------------------------------------------------
+
+export interface ApiCustomer {
+  id: string;
+  slug: string;
+  name: string;
+  description: string | null;
+  email: string | null;
+  website: string | null;
+  phone: string | null;
+  legalName: string | null;
+  addressLine1: string | null;
+  city: string | null;
+  state: string | null;
+  country: string | null;
+  pincode: string | null;
+  taxId: string | null;
+  currencyCode: string;
+  creditAllowance: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Writable customer profile fields. `null` clears a column; omit to leave it. */
+export interface CustomerProfileInput {
+  name?: string;
+  description?: string | null;
+  email?: string | null;
+  website?: string | null;
+  phone?: string | null;
+  legalName?: string | null;
+  addressLine1?: string | null;
+  city?: string | null;
+  state?: string | null;
+  country?: string | null;
+  pincode?: string | null;
+  taxId?: string | null;
+  /** ISO 4217 (3 letters); must be enabled for the org. */
+  currencyCode?: string;
+}
+
+/** `name` and `email` are required on create; every other field is optional. */
+export type CreateCustomerInput = CustomerProfileInput & {
+  name: string;
+  email: string;
+};
+
+export interface CustomerList {
+  customers: ApiCustomer[];
+  nextCursor: string | null;
+}
+
+/** One credit type's running balance for a customer (an element of
+ *  `customers.balances().credits`). */
+export interface CreditBalance {
+  creditId: string;
+  /** The credit's stable agent key — the same key used to record usage and to
+   *  adjust this balance. */
+  agentKey: string;
+  creditName: string;
+  granted: number;
+  used: number;
+  remaining: number;
+}
+
+/** One outcome's running balance for a customer. Unlike a credit balance it
+ *  has no `used`, and it carries the outcome's ordered step list. */
+export interface OutcomeBalance {
+  outcomeId: string;
+  outcomeName: string;
+  granted: number;
+  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
+   *  it — it identifies the outcome in the catalogue, not in a signal. */
+  steps: { id: string; name: string; agentKey: string }[];
+}
+
+/** One unit's advance allowance for a customer. No `used` field. */
+export interface UnitBalance {
+  unitId: string;
+  /** The unit's stable agent key — the same key used to record usage and to
+   *  adjust this balance. */
+  agentKey: string;
+  unitName: string;
+  granted: number;
+  remaining: number;
+}
+
+/** Wallet / credit / outcome / unit balances for a customer's active plan
+ *  (`customers.balances()`). */
+export interface CustomerBalances {
+  customerId: string;
+  currency: { code: string; rateUsd: number };
+  hasPlan: boolean;
+  wallet: { balanceUsd: number } | null;
+  credits: CreditBalance[];
+  outcomes: OutcomeBalance[];
+  units: UnitBalance[];
+}
+
+/** The customer's active plan (the `plan` field of `customers.plan()`);
+ *  `null` when the customer is unsubscribed. */
+export interface CustomerPlanDetails {
+  purchaseId: string;
+  planId: string | null;
+  planName: string;
+  planType: PlanType;
+  planKind: PlanKind;
+  seatScope: "CUSTOMER" | "MEMBER" | null;
+  billingCycle: BillingCycle;
+  cost: number;
+  status: "SCHEDULED" | "ACTIVE";
+  billingDate: string;
+  spendingLimit: number | null;
+  spentThisCycle: number | null;
+  meters: { wallet: boolean; credit: boolean; outcome: boolean; unit: boolean };
+}
+
+export interface CustomerPlan {
+  customerId: string;
+  currency: { code: string; rateUsd: number };
+  plan: CustomerPlanDetails | null;
+}
+
+// ---------------------------------------------------------------------------
+// Portal
+// ---------------------------------------------------------------------------
+
+export interface PortalTokenInput {
+  customerId: string;
+  ttlSeconds?: number;
+  memberEmail?: string;
+}
+
+export interface PortalToken {
+  token: string;
+  /** Unix seconds. */
+  expiresAt: number;
+  /** Seconds until expiry. */
+  expiresIn: number;
+}
+
+// ---------------------------------------------------------------------------
+// Plans
+// ---------------------------------------------------------------------------
+
+/** How often a plan bills. `FREE` is a one-time grant; `EVERY_5_MIN` is a test cadence. */
+export type BillingCycle =
+  | "MONTHLY"
+  | "QUARTERLY"
+  | "SEMI_ANNUAL"
+  | "YEARLY"
+  | "EVERY_5_MIN"
+  | "FREE";
+export type PlanType = "WALLET" | "BUNDLE";
+export type PlanKind = "FLAT_PRICE" | "PAY_AS_YOU_GO" | "PAY_PER_SEAT";
+/** A plan component's meter type. */
+/**
+ * A plan component's kind.
+ *
+ * `PRICING_METRIC` is a COMPOSITE component — the server's wire name for it,
+ * kept verbatim because that is the string you will actually receive and must
+ * send back. It was missing here, which made a `switch` over `PlanComponent.type`
+ * look exhaustive to TypeScript while silently skipping every composite.
+ */
+export type ComponentType =
+  | "WALLET"
+  | "CREDIT"
+  | "OUTCOME"
+  | "UNIT"
+  | "FLAT"
+  | "PRICING_METRIC";
+/** ADVANCE bills up-front for the cycle; ARREAR bills for what was consumed. */
+export type BillingMode = "ADVANCE" | "ARREAR";
+
+/** Prepaid USD wallet. `amount` is the funded balance (required). Max one
+ *  wallet component per plan. */
+export interface WalletComponentInput {
+  type: "WALLET";
+  billingMode: BillingMode;
+  amount: number;
+}
+
+/** A one-off flat fee — `amount` is required. Max one flat component per plan;
+ *  not allowed on FREE plans. */
+export interface FlatComponentInput {
+  type: "FLAT";
+  billingMode: BillingMode;
+  amount: number;
+}
+
+/** A credit entitlement, referenced by `creditId`. Billed ADVANCE it needs a
+ *  granted `quantity`; billed ARREAR it meters usage with no upfront grant. */
+export type CreditComponentInput =
+  | { type: "CREDIT"; billingMode: "ADVANCE"; creditId: string; quantity: number }
+  | { type: "CREDIT"; billingMode: "ARREAR"; creditId: string; quantity?: number | null };
+
+/** An outcome entitlement, referenced by `outcomeId`. ADVANCE needs a granted
+ *  `quantity`; ARREAR meters usage. */
+export type OutcomeComponentInput =
+  | { type: "OUTCOME"; billingMode: "ADVANCE"; outcomeId: string; quantity: number }
+  | { type: "OUTCOME"; billingMode: "ARREAR"; outcomeId: string; quantity?: number | null };
+
+/** A unit entitlement, referenced by `unitId`. ADVANCE needs a granted
+ *  `quantity`; ARREAR meters usage. */
+export type UnitComponentInput =
+  | { type: "UNIT"; billingMode: "ADVANCE"; unitId: string; quantity: number }
+  | { type: "UNIT"; billingMode: "ARREAR"; unitId: string; quantity?: number | null };
+
+/**
+ * A COMPOSITE sold on the plan, referenced by `pricingMetricId` (the id from
+ * `composites.list()`). This is the line that makes a composite bill: the
+ * catalogue entry on its own charges nobody, and this component is what turns
+ * it into money — `quantity × the composite's price`, frozen into the purchase
+ * snapshot at buy time.
+ *
+ * The two billing modes differ in what `quantity` means:
+ *   - **ADVANCE** — a PREPAID POOL of `quantity` flat-rate slots, shared
+ *     across whichever credits / outcomes / units the composite wraps. Each
+ *     distinct tag value claims one slot on completion; repeat signals under a
+ *     value reuse the slot they already claimed, at no extra cost. Once every
+ *     slot is claimed, further occurrences are refused rather than billed.
+ *   - **ARREAR** — nothing prepaid; completed occurrences are counted on the
+ *     cycle-end line.
+ *
+ * `type` is the wire value `"PRICING_METRIC"`, not `"COMPOSITE"`: the product
+ * word changed but the stored enum did not, and the API still speaks the old
+ * one. That mismatch is the server's, and it is surfaced rather than hidden so
+ * a response and a request read the same.
+ */
+export type CompositeComponentInput =
+  | {
+      type: "PRICING_METRIC";
+      billingMode: "ADVANCE";
+      pricingMetricId: string;
+      quantity: number;
+    }
+  | {
+      type: "PRICING_METRIC";
+      billingMode: "ARREAR";
+      pricingMetricId: string;
+      quantity?: number | null;
+    };
+
+/**
+ * One entitlement line in a plan — a discriminated union on `type` (and, where
+ * it matters, `billingMode`) so the per-type fields the server requires are
+ * enforced at compile time instead of surfacing as runtime 422s:
+ *   - CREDIT / OUTCOME / UNIT require their matching id;
+ *   - PRICING_METRIC (a composite) requires `pricingMetricId`;
+ *   - CREDIT / OUTCOME / UNIT / PRICING_METRIC require `quantity` when billed
+ *     ADVANCE;
+ *   - WALLET / FLAT require `amount`.
+ */
+export type PlanComponentInput =
+  | WalletComponentInput
+  | FlatComponentInput
+  | CreditComponentInput
+  | OutcomeComponentInput
+  | UnitComponentInput
+  | CompositeComponentInput;
+
+export interface CreatePlanInput {
+  name: string;
+  description?: string | null;
+  billingCycle: BillingCycle;
+  /** Carry an unused balance into the next cycle. Default true. */
+  carryForward?: boolean;
+  /** ISO 4217 (3 letters). Default "USD". */
+  currencyCode?: string;
+  isActive?: boolean;
+  /** At least one component. FREE plans must be ADVANCE-only with no FLAT component. */
+  components: PlanComponentInput[];
+}
+
+/** A full-rewrite update carries the complete plan (same shape as create). */
+export type UpdatePlanInput = CreatePlanInput;
+
+export interface PlanComponent {
+  id: string;
+  type: ComponentType;
+  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;
+  targetName: string | null;
+  quantity: number | null;
+  amount: number | null;
+}
+
+export 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). */
+  priceAdjustment: number;
+  /** 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;
+  currencyCode: string;
+  isActive: boolean;
+  components: PlanComponent[];
+}
+
+/** The richer plan returned by `plans.get()` (adds aggregate stats). */
+export interface PlanDetail extends Plan {
+  createdAt: string;
+  createdByName: string | null;
+  customerCount: number;
+  invoiceCount: number;
+  openInvoiceCount: number;
+  stats: { totalInvoiced: number; totalCollected: number; openBalance: number };
+}
+
+// ---------------------------------------------------------------------------
+// Purchases (subscriptions)
+// ---------------------------------------------------------------------------
+
+export type PurchaseStatus = "SCHEDULED" | "ACTIVE" | "CANCELLED";
+
+export interface CreatePurchaseInput {
+  customerId: string;
+  planId: string;
+  /** `YYYY-MM-DD`. Defaults to today; must be a valid non-past date. */
+  billingDate?: string;
+  notes?: string;
+  autoPayment?: boolean;
+  /** Auto-void the purchase if unpaid after N minutes. */
+  voidAfterMinutes?: number;
+}
+
+export interface Purchase {
+  id: string;
+  purchaseNumber: string;
+  customerId: string;
+  customerName: string;
+  customerLogoUrl: string | null;
+  planId: string | null;
+  planName: string;
+  planType: PlanType;
+  hasWallet: boolean;
+  hasCredit: boolean;
+  hasOutcome: boolean;
+  hasUnit: boolean;
+  /** True when the purchased plan sells at least one composite. */
+  hasComposite: boolean;
+  billingCycle: BillingCycle;
+  cost: number;
+  currencyCode: string;
+  billingDate: string;
+  nextBillingDate: string;
+  status: PurchaseStatus;
+  voidAfterMinutes: number;
+  autoPayment: boolean;
+  autoPaymentPauseReason: string | null;
+  notes: string | null;
+  createdAt: string;
+}
+
+/** The purchase returned by `purchases.get()` — a different, detail-oriented shape. */
+export interface PurchaseDetail {
+  id: string;
+  purchaseNumber: string;
+  status: PurchaseStatus;
+  cost: number;
+  billingCycle: BillingCycle;
+  planName: string;
+  billingDate: string;
+  nextBillingDate: string;
+  createdAt: string;
+  createdByName: string;
+  customer: { id: string; name: string; logoUrl: string | null };
+  voidAfterMinutes: number;
+  notes: string | null;
+  autoPayment: boolean;
+  autoPaymentPauseReason: string | null;
+  autoPaymentPausedAt: string | null;
+  plan: { id: string } | null;
+  stats: { invoiceCount: number; paidCount: number };
+}
+
+// ---------------------------------------------------------------------------
+// Invoices & Payments
+// ---------------------------------------------------------------------------
+
+export type InvoiceStatus = "OPEN" | "PAID" | "VOID";
+
+/** Trimmed row from `invoices.list()`. */
+export interface InvoiceListRow {
+  id: string;
+  invoiceNumber: string;
+  purchaseNumber: string | null;
+  purchaseId: string | null;
+  customerId: string;
+  customerName: string;
+  planName: string;
+  billingCycle: BillingCycle;
+  cycleIndex: number;
+  amount: number;
+  currencyCode: string;
+  status: InvoiceStatus;
+  issuedAt: string;
+  paidAt: string | null;
+}
+
+/** A billing party (your org, or the customer) on an invoice. */
+export interface InvoiceParty {
+  name: string;
+  logoUrl: string | null;
+  legalName: string | null;
+  email: string | null;
+  phone: string | null;
+  website: string | null;
+  taxId: string | null;
+  addressLine1: string | null;
+  city: string | null;
+  state: string | null;
+  country: string | null;
+  pincode: string | null;
+}
+
+export interface InvoiceLineItem {
+  kind: "credit" | "outcome";
+  label: string;
+  quantity: number;
+}
+
+/** The plan snapshot embedded in a full invoice. */
+export interface InvoicePlanSnapshot {
+  name: string;
+  type: PlanType;
+  hasWallet: boolean;
+  hasCredit: boolean;
+  hasOutcome: boolean;
+  hasUnit: boolean;
+  kind: PlanKind;
+  billingCycle: BillingCycle;
+  cost: number;
+  currencyCode: string;
+  spendingLimit: number | null;
+  seatScope: "CUSTOMER" | "MEMBER" | null;
+  carryForward: boolean;
+  billingDate: string;
+  status: "SCHEDULED" | "ACTIVE";
+}
+
+/** The full invoice from `invoices.get()` (also the `payment` in `payments.get()`). */
+export interface Invoice {
+  id: string;
+  invoiceNumber: string;
+  paymentNumber: string | null;
+  purchaseNumber: string | null;
+  customerId: string;
+  customerName: string;
+  customerSlug: string;
+  customerParty: InvoiceParty;
+  orgParty: InvoiceParty;
+  purchaseId: string | null;
+  stream: BillingMode;
+  planId: string | null;
+  planName: string;
+  planType: PlanType;
+  plan: InvoicePlanSnapshot | null;
+  billingCycle: BillingCycle;
+  cycleIndex: number;
+  lineItems: InvoiceLineItem[];
+  hasWallet: boolean;
+  hasCredit: boolean;
+  hasOutcome: boolean;
+  hasUnit: boolean;
+  amount: number;
+  currencyCode: string;
+  currencyRateUsd: number;
+  status: InvoiceStatus;
+  issuedAt: string;
+  paidAt: string | null;
+  voidedAt: string | null;
+  /** One of the server `PaymentMode` values (e.g. "CASH", "STRIPE", …). */
+  paymentMode: string | null;
+  paymentReference: string | null;
+  stripePaymentIntentId: string | null;
+  autoPaid: boolean;
+  notes: string | null;
+  createdAt: string;
+  createdByName: string;
+  paidByName: string | null;
+  voidedByName: string | null;
+}
+
+/** A short `{ id, name }` plan reference alongside a full invoice/payment. */
+export interface PlanRef {
+  id: string;
+  name: string;
+}
+
+export interface InvoiceDetail {
+  invoice: Invoice;
+  plan: PlanRef | null;
+}
+
+/** A hosted pay link for an OPEN invoice. */
+export interface PayLink {
+  url: string;
+  invoiceId: string;
+  invoiceNumber: string;
+}
+
+/** Trimmed row from `payments.list()` (a payment is a PAID invoice). */
+export interface PaymentRow {
+  id: string;
+  paymentNumber: string;
+  invoiceNumber: string;
+  purchaseNumber: string | null;
+  customerId: string;
+  customerName: string;
+  planName: string;
+  amount: number;
+  currencyCode: string;
+  paymentMode: string | null;
+  paymentReference: string | null;
+  paidAt: string;
+  paidByName: string | null;
+}
+
+export interface PaymentDetail {
+  payment: Invoice;
+  plan: PlanRef | null;
+}
+
+// ---------------------------------------------------------------------------
+// Customer members
+// ---------------------------------------------------------------------------
+
+/** A customer member as returned by `listMembers` (`GET .../members`). */
+export interface Member {
+  id: string;
+  name: string;
+  email: string | null;
+  /** True once the member has linked a login. */
+  isLinked: boolean;
+  joinedAt: string;
+}
+
+/** A customer member as returned by `addMember` / `updateMember`. */
+export interface MemberProfile {
+  id: string;
+  name: string;
+  email: string | null;
+  joinedAt: string;
+}
+
+/** The member removed by `removeMember` (`DELETE .../members/:memberId`). */
+export interface RemovedMember {
+  name: string;
+  email: string | null;
+}
+
+export interface AddMemberInput {
+  name: string;
+  /** Must be unique (case-insensitively) among the customer's active members. */
+  email?: string;
+}
+
+export interface UpdateMemberInput {
+  name: string;
+  /** Must be unique (case-insensitively) among the customer's active members. */
+  email?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Wallet & balance adjustments (customer-scoped)
+// ---------------------------------------------------------------------------
+
+export type WalletTransactionType = "CREDIT" | "DEBIT";
+
+/** What produced a wallet entry. `null` on rows written before the column
+ *  existed. */
+export type WalletTransactionSource =
+  | "TOPUP"
+  | "USAGE"
+  | "SETTLE"
+  | "ADJUSTMENT";
+
+/** The entitlement kinds a wallet-funded metering debit can name. */
+export type WalletEntitlementKind = "CREDIT" | "OUTCOME" | "UNIT";
+
+export interface WalletTransaction {
+  id: string;
+  type: WalletTransactionType;
+  /** What produced the entry. Null on rows older than the column. */
+  source: WalletTransactionSource | null;
+  amount: number;
+  amountUsd: number;
+  currencyCode: string;
+  currencyRateUsd: number;
+  notes: string | null;
+  batchId: string | null;
+  createdAt: string;
+  createdByName: string | null;
+  /** Set only on a wallet-funded metering debit: which kind of entitlement was
+   *  consumed. Null on top-ups and manual adjustments. */
+  entitlementType: WalletEntitlementKind | null;
+  /** Id of the credit / outcome / unit consumed. Null unless
+   *  `entitlementType` is set. */
+  targetId: string | null;
+  /** Its name at the time of the debit. */
+  targetName: string | null;
+  /** The signal this debit paid for (credit / outcome). In wallet-funded mode
+   *  no invoice exists, so this is the only trail from a charge to its cause. */
+  usageLogId: string | null;
+  /** The unit event this debit paid for. */
+  unitUsageLogId: string | null;
+}
+
+export interface WalletList {
+  balanceUsd: number;
+  transactions: WalletTransaction[];
+}
+
+export interface WalletEntryInput {
+  /** DEBIT spends, CREDIT tops up. */
+  type: WalletTransactionType;
+  /** Always positive; the sign comes from `type`. */
+  amount: number;
+  notes?: 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`. */
+export interface CreditAdjustInput {
+  /** The credit's stable agent key (the same key used to record usage). */
+  agentKey: string;
+  delta: number;
+  notes?: string;
+}
+
+/** Grant/claw an outcome balance. `delta` is a non-zero whole number; floored at
+ *  0. 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. */
+export interface OutcomeAdjustInput {
+  /** An outcome STEP's stable agent key — identifies the parent outcome. Passing
+   *  the outcome's own `agentKey` here fails with `422`. */
+  agentKey: string;
+  delta: number;
+  notes?: string;
+}
+
+/** Grant/claw a unit balance. `delta` is non-zero (fractional allowed); floored
+ *  at 0. The unit is addressed by its stable `agentKey`. */
+export interface UnitAdjustInput {
+  /** The unit's stable agent key (the same key used to record usage). */
+  agentKey: string;
+  delta: number;
+  notes?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Entitlement catalogs: Credits, Outcomes, Units
+// ---------------------------------------------------------------------------
+
+/** A per-model token bundle attached to a credit or outcome step. */
+export interface ModelBundleEntry {
+  orgModelId: string;
+  /** Display label; the server defaults it from the model when omitted. */
+  modelName?: string;
+  tokens: number;
+  input: number;
+  output: number;
+  cache: number;
+}
+
+/** One point on a cost-over-time analytics series. */
+export interface CostPoint {
+  /** UTC day, `YYYY-MM-DD`. */
+  dateIso: string;
+  /** Short display label, e.g. "Jun 24". */
+  label: string;
+  /** Average cost that day, or `null` on days with no usage. */
+  cost: number | null;
+  reqs: number;
+}
+
+/** Summary stats across a cost-over-time series. */
+export interface CostStats {
+  activeDays: number;
+  avgCost: number | null;
+  peakCost: number | null;
+  troughCost: number | null;
+  deviationPct: number | null;
+}
+
+/** Cost-over-time analytics for a credit (`credits.get().analytics`). */
+export interface CreditAnalytics {
+  basePrice: number;
+  pricePerCredit: number;
+  marginPercent: number;
+  points: CostPoint[];
+  stats: CostStats;
+}
+
+/** Cost-over-time analytics for an outcome (`outcomes.get().analytics`).
+ *  Each point adds `completions` (workflows finished that day). */
+export interface OutcomeAnalytics {
+  basePrice: number;
+  pricePerOutcome: number;
+  marginPercent: number;
+  points: (CostPoint & { completions: number })[];
+  stats: CostStats;
+}
+
+export interface Credit {
+  id: string;
+  name: string;
+  agentKey: string;
+  description: string | null;
+  tokensPerCredit: number;
+  basePrice: number;
+  marginPercent: number;
+  pricePerCredit: number;
+  isActive: boolean;
+  createdAt: string;
+}
+
+/** `credits.get()` — adds the model bundle plus usage stats/analytics. */
+export interface CreditDetail extends Credit {
+  modelBundle: ModelBundleEntry[];
+  createdByName: string;
+  stats: {
+    customerCount: number;
+    planCount: number;
+    totalGranted: number;
+    totalUsed: number;
+    revenue: number;
+    usageLogCount: number;
+  };
+  analytics: CreditAnalytics;
+}
+
+export interface CreateCreditInput {
+  name: string;
+  /** Lowercased stable key used by `signals.credit({ agentKey })`. */
+  agentKey: string;
+  basePrice: number;
+  marginPercent: number;
+  pricePerCredit: number;
+  description?: string;
+  tokensPerCredit?: number;
+  modelBundle?: ModelBundleEntry[];
+}
+
+export type UpdateCreditInput = CreateCreditInput;
+
+export interface OutcomeStepInput {
+  id?: string;
+  name: string;
+  /** Lowercased stable key used by `signals.outcome({ agentKey })`. */
+  agentKey: string;
+  basePrice: number;
+  modelBundle?: ModelBundleEntry[];
+}
+
+export interface Outcome {
+  id: string;
+  name: string;
+  /**
+   * The OUTCOME's own stable agent key — its durable identity, mirroring
+   * {@link Credit.agentKey}. Lowercased `[a-z0-9._-]`, max 80 chars, unique per
+   * organisation. A rename never changes it.
+   *
+   * Distinct from each step's `agentKey` in `steps`, and in a SEPARATE
+   * namespace: usage is always reported against a STEP's key
+   * (`signals.outcome({ agentKey })`), never this one. This key identifies the
+   * outcome itself when creating or updating it.
+   */
+  agentKey: string;
+  description: string | null;
+  isActive: boolean;
+  marginPercent: number;
+  pricePerOutcome: number;
+}
+
+/** `outcomes.get()` — adds steps plus in-flight/completed stats. */
+export interface OutcomeDetail extends Outcome {
+  /** Only the DETAIL row carries these — `outcomes.list()` returns neither.
+   *  They were previously declared on {@link Outcome} itself, where
+   *  `createdAt` was typed as a required `string` that is always `undefined`
+   *  in practice. */
+  createdAt: string;
+  createdByName: string | null;
+  steps: { name: string; agentKey: string }[];
+  stats: {
+    stepCount: number;
+    customerCount: number;
+    inFlight: number;
+    completed: number;
+    totalRemaining: number;
+  };
+  analytics: OutcomeAnalytics;
+}
+
+export interface CreateOutcomeInput {
+  name: string;
+  /**
+   * The OUTCOME's own stable agent key — REQUIRED. Lowercased `[a-z0-9._-]`,
+   * max 80 chars, unique per organisation (the server lowercases and trims it).
+   *
+   * Separate namespace from `steps[].agentKey`: this names the outcome, a step
+   * key names a step and is what `signals.outcome()` reports against. Omitting
+   * it is rejected with a `ValidationError` (400).
+   */
+  agentKey: string;
+  basePrice: number;
+  marginPercent: number;
+  pricePerOutcome: number;
+  description?: string | null;
+  isActive?: boolean;
+  /** 1–50 steps; step names and agent keys must be unique. */
+  steps: OutcomeStepInput[];
+}
+
+export type UpdateOutcomeInput = CreateOutcomeInput;
+
+export type UnitPricingType = "FLAT" | "SLAB" | "VOLUME";
+
+/** A tier for SLAB/VOLUME pricing; only the last tier may have `upTo: null`. */
+export interface UnitTierInput {
+  id?: string;
+  upTo: number | null;
+  price: number;
+}
+
+export interface UnitTier {
+  id: string;
+  upTo: number | null;
+  price: number;
+  order: number;
+}
+
+export interface Unit {
+  id: string;
+  /** Stable per-org report key — what `signals.unit({ agentKey })` sends.
+   *  The ONLY identifier accepted when reporting unit consumption. */
+  agentKey: string;
+  name: string;
+  description: string | null;
+  pricingType: UnitPricingType;
+  flatPrice: number;
+  tiers: UnitTier[];
+  isActive: boolean;
+  createdAt: string;
+  createdByName: string | null;
+}
+
+/** One row in a unit's linked-customer sample (`units.get().customers`). */
+export interface UnitCustomerRow {
+  customerId: string;
+  name: string;
+  legalName: string | null;
+  slug: string;
+  logoUrl: string | null;
+  granted: number;
+  used: number;
+  remaining: number;
+  currentlyMetered: boolean;
+}
+
+/** `units.get()` — adds linked-customer sample plus stats.
+ *  `createdByName` is inherited from `Unit`. */
+export interface UnitDetail extends Unit {
+  stats: {
+    planCount: number;
+    customerCount: number;
+    totalRemaining: number;
+    totalUsed: number;
+  };
+  /** First page (≤10) of customers currently metered on this unit. */
+  customers: UnitCustomerRow[];
+}
+
+/** Flat per-event pricing — a single `flatPrice` (defaults to 0), no tiers. */
+export interface FlatUnitInput {
+  name: string;
+  /** Stable per-org report key (`signals.unit({ agentKey })`); `[a-z0-9._-]`. */
+  agentKey: string;
+  pricingType: "FLAT";
+  /** Price per event; defaults to 0. */
+  flatPrice?: number;
+  description?: string | null;
+  isActive?: boolean;
+}
+
+/** Tiered pricing (SLAB or VOLUME) — at least one tier is required. */
+export interface TieredUnitInput {
+  name: string;
+  /** Stable per-org report key (`signals.unit({ agentKey })`); `[a-z0-9._-]`. */
+  agentKey: string;
+  pricingType: "SLAB" | "VOLUME";
+  /** At least one tier (≤50). Only the last tier may have `upTo: null`. */
+  tiers: UnitTierInput[];
+  description?: string | null;
+  isActive?: boolean;
+}
+
+/**
+ * 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.
+ */
+export type CreateUnitInput = FlatUnitInput | TieredUnitInput;
+
+export type UpdateUnitInput = CreateUnitInput;
+
+// ---------------------------------------------------------------------------
+// Unit consumption (recorded via signals; distinct from catalog `Unit`)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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).
+ */
+export interface UnitInput {
+  customerId: string;
+  agentKey: string;
+  member?: string;
+  /**
+   * How many units this one report covers. Defaults to 1 server-side, so a
+   * caller reporting one unit per call simply omits it. Whole numbers, at most
+   * 1,000,000 per call.
+   *
+   * On an ADVANCE (prepaid) plan the draw is all-or-nothing: asking for more
+   * than remains is refused IN FULL rather than partially filled.
+   */
+  quantity?: number;
+  /** Optional composite this unit report belongs to. See {@link CompositeTag}. */
+  composite?: CompositeTag;
+  /**
+   * Idempotency key for safe retries — a repeat carrying the same key returns
+   * the original result instead of drawing the balance down twice.
+   *
+   * New in the `/api/v1/signal/unit` route: the legacy `/api/v1/units` had no
+   * idempotency at all, so a retried unit report double-charged.
+   *
+   * **Auto-generated (UUID v4) if omitted** and reused across every retry of
+   * this call, exactly like a signal's. That matters more here than it looks:
+   * unit reports opt into transport retries, so without a key one 500-then-200
+   * is two distinct billable reports.
+   *
+   * Supply your own — a stable id for this logical event — to also dedup
+   * across process restarts or at-least-once redelivery, which an in-memory
+   * auto key cannot survive.
+   */
+  idempotencyKey?: string;
+}
+
+/**
+ * The result of `signals.unit()`.
+ *
+ * Shaped like {@link TrackResult} and for the same reason: `/api/v1/signal/unit`
+ * is durable, so it answers `202` with no priced event when the server hands
+ * the report to its queue, and `200` with `unitUsage` when it prices inline.
+ * The legacy `/api/v1/units` always priced inline, which is why this used to be
+ * a bare `{ unitUsage }`. Branch on `queued`; never assume `unitUsage`.
+ */
+export interface UnitTrackResult {
+  /** How far the report got. Never `"buffered"` — unit reports are always sent
+   *  immediately, not queued client-side. See {@link TrackResult.status}. */
+  status: Extract<SignalDelivery, "accepted" | "recorded">;
+  /** True when the report was accepted but not yet priced (`202`). Prefer
+   *  {@link UnitTrackResult.status}. */
+  queued: boolean;
+  /** The priced unit event. Non-null ONLY when the server priced inline. */
+  unitUsage?: SerializedUnitUsage | null;
+  /** The durable-queue message id, present only on a `202`. */
+  messageId?: string;
+  /** The durable inbox id — see {@link TrackResult.rawId}. */
+  rawId?: string;
+}
+
+/**
+ * Input for `signals.completeComposite()` — closes ONE occurrence of a
+ * composite, which is the moment it is billed.
+ */
+export interface CompositeCompletionInput {
+  customerId: string;
+  /** Which occurrence to close: the composite's `refId` and the correlation
+   *  value the signals were tagged with. */
+  composite: CompositeTag;
+  /** Idempotency key, auto-generated if omitted. Closing twice is already a
+   *  safe no-op, so this only collapses retries into one recorded attempt
+   *  rather than protecting against a double charge. */
+  idempotencyKey?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Composites catalog (mirrors /api/v1/composites)
+// ---------------------------------------------------------------------------
+
+/** One catalogue item a composite is restricted to. `agentKey` is what a
+ *  signal names, so it is the field you actually integrate against. */
+export interface CompositeCatalogueRef {
+  id: string;
+  name: string;
+  agentKey: string;
+}
+
+/** One composite in the org's catalogue — `cnk.composites.list()`. */
+export interface Composite {
+  id: string;
+  name: string;
+  /** The stable identifier you put in a signal's `composite` block as `ref`. */
+  refId: string;
+  description: string | null;
+  /** USD charged per occurrence WHEN A PLAN SELLS THIS as a composite
+   *  component (`quantity × price`, frozen into the purchase at buy time). The
+   *  catalogue row alone bills nothing. */
+  price: number;
+  /** False once archived. An archived composite stops NEW signals resolving to
+   *  it but keeps every row it already owns. */
+  isActive: boolean;
+  createdAt: string;
+  /**
+   * The credits / outcomes / units this composite is restricted to — only
+   * signals naming one of these may carry its tag.
+   *
+   * All three lists empty means UNRESTRICTED (it accepts any of the org's
+   * traffic under this tag). Nothing created through the API can be
+   * unrestricted, but rows predating that rule exist — so don't assume
+   * non-empty.
+   */
+  entitlements: {
+    credits: CompositeCatalogueRef[];
+    outcomes: CompositeCatalogueRef[];
+    units: CompositeCatalogueRef[];
+  };
+}
+
+/** Input for `cnk.composites.create()`. */
+export interface CreateCompositeInput {
+  name: string;
+  /**
+   * The tag identifier. Lowercased, and restricted to the same characters as
+   * an `agentKey` — but validated harder than one, because it may not collide
+   * with a field the ingest schemas already own (`customerId`, `usage`,
+   * `agentKey`, `runId`, `member`, `custom`, `composite`, …). A colliding
+   * `refId` is refused at create time rather than silently ignored at ingest.
+   */
+  refId: string;
+  /** USD per occurrence once a plan sells it. Required — an unpriced composite
+   *  put on a plan would bill 0, which is a money bug that is hard to see. */
+  price: number;
+  description?: string | null;
+  /**
+   * What the composite wraps. At least one id across the three lists is
+   * REQUIRED: a composite restricted to nothing would accept every signal in
+   * the org. Get the ids from `credits.list()`, `outcomes.list()` and
+   * `units.list()`.
+   */
+  entitlements: {
+    creditIds?: string[];
+    outcomeIds?: string[];
+    unitIds?: string[];
+  };
+}
+
+/**
+ * The result of `signals.completeComposite()`.
+ *
+ * `status` distinguishes the first close from a replay. Note that an EARLY
+ * ping — one sent before every credit / outcome / unit the composite is
+ * restricted to has reported under the same value — is not an error: the
+ * server parks it and completes it automatically when the missing signal
+ * lands. That case answers with no `status`, only a `rawId` to follow.
+ */
+export interface CompositeCompletionResult {
+  /** How far the ping got. Never `"buffered"` — completions are always sent
+   *  immediately. `"recorded"` means the occurrence was closed inline. See
+   *  {@link TrackResult.status}. */
+  delivery: Extract<SignalDelivery, "accepted" | "recorded">;
+  /** True when the ping was accepted but not yet applied (`202`). Prefer
+   *  {@link CompositeCompletionResult.delivery}. */
+  queued: boolean;
+  /** `COMPLETED` on the first close, `ALREADY_COMPLETED` on a replay. Absent
+   *  when the ping was queued or parked. Distinct from `delivery`: this is the
+   *  server's verdict on the OCCURRENCE, that is how far the REQUEST got. */
+  status?: "COMPLETED" | "ALREADY_COMPLETED";
+  /** The composite that was closed. Null on the replay of a historical row
+   *  whose occurrence can no longer be read back. */
+  composite?: { id: string; name: string; refId: string } | null;
+  /** The correlation value whose occurrence was closed. */
+  value?: string | null;
+  /** The durable-queue message id, present only on a `202`. */
+  messageId?: string;
+  /** 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`. */
+export interface SerializedUnitUsage {
+  id: string;
+  customerId: string;
+  /** Display name of the unit. */
+  unit: string;
+  /** The unit's stable agent key; `null` if the unit was deleted. */
+  agentKey: string | null;
+  billingMode: BillingMode;
+  /** Remaining ADVANCE allowance after this event; `null` for ARREAR. */
+  remaining: number | null;
+  customerCost: number;
+  member: string | null;
+  createdAt: string;
+}
+
+export interface UnitUsageRow {
+  unit: string;
+  /** The unit's stable agent key — what to send to report against it. */
+  agentKey: string | null;
+  billingMode: BillingMode;
+  granted?: number;
+  used: number;
+  remaining?: number;
+}
+
+export interface UnitUsageList {
+  customer: { id: string; name: string };
+  units: UnitUsageRow[];
+  events: SerializedUnitUsage[];
+}
+
+// ---------------------------------------------------------------------------
+// Webhooks (threshold alerts)
+// ---------------------------------------------------------------------------
+
+export type ThresholdKind = "CREDIT" | "OUTCOME" | "WALLET";
+
+export interface Webhook {
+  id: string;
+  kind: ThresholdKind;
+  threshold: number;
+  url: string;
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
+  createdByName: string | null;
+}
+
+export interface UpsertWebhookInput {
+  kind: ThresholdKind;
+  /** Fire when the balance crosses this value. */
+  threshold: number;
+  /** http(s) URL to POST the alert to. */
+  url: string;
+  isActive?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Config & hooks
+// ---------------------------------------------------------------------------
+
+export type FetchLike = (
+  input: string,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export interface Logger {
+  debug?: (...args: unknown[]) => void;
+  warn?: (...args: unknown[]) => void;
+  error?: (...args: unknown[]) => void;
+}
+
+/**
+ * Why a signal was dropped without being billed.
+ *
+ *   `queue_full`  — the local buffer hit `batch.maxQueueSize`; never sent.
+ *   `closed`      — tracked after `close()`; never sent.
+ *   `send_failed` — sent, and permanently rejected or unreachable. This is the
+ *                   only reason that also fires `onError`, which carries the
+ *                   error (and its `idempotencyKey`, for a safe replay).
+ */
+export type DropReason = "queue_full" | "closed" | "send_failed";
+
+export interface ClockNextConfig {
+  /** The org API key (`cnk_…`). Required. */
+  apiKey: string;
+  /** API base URL. Defaults to https://payments.clocknext.com */
+  baseUrl?: string;
+  /**
+   * "async" (default) buffers signals and flushes in the background.
+   * "sync" awaits every send inside `track()`.
+   */
+  mode?: "async" | "sync";
+  /** Per-request timeout (ms). Default 10_000. */
+  timeoutMs?: number;
+  /** Background batching config (async mode). */
+  batch?: {
+    /** Flush when this many signals are buffered. Default 20. */
+    maxSize?: number;
+    /** Flush at least this often (ms). Default 2000. */
+    maxIntervalMs?: number;
+    /** Max concurrent in-flight sends per flush. Default 5. */
+    maxConcurrency?: number;
+    /** Drop new signals once the buffer reaches this size. Default 10_000. */
+    maxQueueSize?: number;
+  };
+  /** Retry policy for transient failures. */
+  retry?: {
+    /** Total attempts including the first. Default 5. */
+    maxAttempts?: number;
+    /** Base backoff (ms). Default 200. */
+    baseDelayMs?: number;
+    /** Max backoff (ms). Default 10_000. */
+    maxDelayMs?: number;
+  };
+  /** Injectable fetch (defaults to global fetch). */
+  fetch?: FetchLike;
+  logger?: Logger;
+  /** Called when a signal permanently fails (after retries / non-retryable). */
+  onError?: (error: unknown, signal?: Signal) => void;
+  /** Called after each successful background flush with the sent count. */
+  onFlush?: (sentCount: number) => void;
+  /** Called before each retry attempt. */
+  onRetry?: (info: { attempt: number; delayMs: number; error: unknown }) => void;
+  /** Called when a signal is dropped without being sent. */
+  onDrop?: (signal: Signal, reason: DropReason) => void;
+}
+
+/** Fully-resolved config with defaults applied. */
+export interface ResolvedConfig {
+  apiKey: string;
+  baseUrl: string;
+  mode: "async" | "sync";
+  timeoutMs: number;
+  batch: {
+    maxSize: number;
+    maxIntervalMs: number;
+    maxConcurrency: number;
+    maxQueueSize: number;
+  };
+  retry: { maxAttempts: number; baseDelayMs: number; maxDelayMs: number };
+  fetch: FetchLike;
+  logger: Logger;
+  onError?: (error: unknown, signal?: Signal) => void;
+  onFlush?: (sentCount: number) => void;
+  onRetry?: (info: { attempt: number; delayMs: number; error: unknown }) => void;
+  onDrop?: (signal: Signal, reason: DropReason) => void;
+}