@clocknext/sdk 0.7.0 → 0.10.0

package/dist/index.d.ts

@@ -1,10 +1,14 @@
 /**
  * Public types for the ClockNext SDK.
  *
- * The signal types mirror the server's `recordSchema` (the body of
- * `POST /api/v1/usage`) as a discriminated union, so the per-type required
- * fields the server enforces with Zod refinements are enforced here at compile
- * time instead of surfacing as runtime 422s.
+ * 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.
  */
 type SignalType = "wallet" | "credit" | "outcome";
 type SignalStatus = "SUCCESS" | "FAILURE" | "PENDING";
@@ -19,18 +23,37 @@ interface Tokens {
     cache?: number;
 }
 /**
- * Tags a signal with a pricing metric for reporting. `ref` is the metric's
- * `refId` (defined in Settings → Pricing metrics) and `value` is your own
- * correlation id — a session, a call, a tenant — which the metric rolls up one
- * row per distinct value. Reporting only: a metric never affects billing, a bad
- * tag never fails the signal, and a `ref` naming no live metric is simply
- * ignored. Applies to credit and outcome signals (ignored on wallet).
+ * 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.
  */
-interface MetricTag {
-    /** The metric's `refId`. Case-insensitive; must not collide with a reserved
-     *  ingest field (e.g. `model`, `member`, `agentKey`, `runId`, `custom`). */
+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 metric, stored verbatim. */
+    /** Your correlation value for this occurrence, stored verbatim. */
     value: string | number;
 }
 /** The organisation + key behind a request — `cnk.workspace.me()`. */
@@ -90,8 +113,8 @@ interface CreditSignal extends SignalBase {
     type: "credit";
     /** The Credit's stable agent key (assigned when the credit was created). */
     agentKey: string;
-    /** Optional pricing-metric tag for reporting. */
-    metric?: MetricTag;
+    /** 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 {
@@ -118,8 +141,8 @@ interface OutcomeSignal extends SignalBase {
      * can't bill again.
      */
     complete?: boolean;
-    /** Optional pricing-metric tag for reporting. */
-    metric?: MetricTag;
+    /** 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. */
@@ -185,12 +208,50 @@ interface SerializedUsageLog {
     balance: UsageBalance | null;
     createdAt: string;
 }
-/** Result of a single signal send (sync mode, or `{ wait: true }`). */
+/**
+ * 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.
+ */
 interface TrackResult {
-    /** True when the signal was buffered (async mode) and not yet sent. */
+    /** True when the signal has not been priced yet — either buffered locally
+     *  (async mode) or accepted for asynchronous processing by the server. */
     queued: boolean;
-    /** The computed usage log — present only once the signal has been sent. */
+    /** 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;
 }
 interface UsageList {
     customer: {
@@ -217,14 +278,11 @@ interface ApiCustomer {
     phone: string | null;
     legalName: string | null;
     addressLine1: string | null;
-    addressLine2: string | null;
     city: string | null;
     state: string | null;
     country: string | null;
     pincode: string | null;
     taxId: string | null;
-    notes: string | null;
-    logoUrl: string | null;
     currencyCode: string;
     creditAllowance: number;
     createdAt: string;
@@ -239,14 +297,11 @@ interface CustomerProfileInput {
     phone?: string | null;
     legalName?: string | null;
     addressLine1?: string | null;
-    addressLine2?: string | null;
     city?: string | null;
     state?: string | null;
     country?: string | null;
     pincode?: string | null;
     taxId?: string | null;
-    notes?: string | null;
-    logoUrl?: string | null;
     /** ISO 4217 (3 letters); must be enabled for the org. */
     currencyCode?: string;
 }
@@ -279,7 +334,9 @@ interface OutcomeBalance {
     granted: number;
     remaining: number;
     /** Each step's `agentKey` is what `signals.outcome()` and the outcome adjust
-     *  API use to address this outcome (outcomes have no key of their own). */
+     *  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;
@@ -415,15 +472,49 @@ type UnitComponentInput = {
     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;
- *   - CREDIT / OUTCOME / UNIT require `quantity` when billed ADVANCE;
+ *   - 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;
+type PlanComponentInput = WalletComponentInput | FlatComponentInput | CreditComponentInput | OutcomeComponentInput | UnitComponentInput | CompositeComponentInput;
 interface CreatePlanInput {
     name: string;
     description?: string | null;
@@ -675,31 +766,36 @@ interface PaymentDetail {
     payment: Invoice;
     plan: PlanRef | null;
 }
-type MemberRole = "OWNER" | "ADMIN" | "MEMBER";
+/** A customer member as returned by `listMembers` (`GET .../members`). */
 interface Member {
     id: string;
-    role: MemberRole;
     name: string;
     email: string | null;
-    employeeId: string | null;
-    phone: string | null;
     /** True once the member has linked a login. */
     isLinked: boolean;
     joinedAt: string;
 }
+/** A customer member as returned by `addMember` / `updateMember`. */
+interface MemberProfile {
+    id: string;
+    name: string;
+    email: string | null;
+    joinedAt: string;
+}
+/** The member removed by `removeMember` (`DELETE .../members/:memberId`). */
+interface RemovedMember {
+    name: string;
+    email: string | null;
+}
 interface AddMemberInput {
     name: string;
-    role: "ADMIN" | "MEMBER";
+    /** Must be unique (case-insensitively) among the customer's active members. */
     email?: string;
-    employeeId?: string;
-    phone?: string;
 }
-/** Role is fixed after creation; omit it here. */
 interface UpdateMemberInput {
     name: string;
+    /** Must be unique (case-insensitively) among the customer's active members. */
     email?: string;
-    employeeId?: string;
-    phone?: string;
 }
 type WalletTransactionType = "CREDIT" | "DEBIT";
 interface WalletTransaction {
@@ -734,10 +830,12 @@ interface CreditAdjustInput {
     notes?: string;
 }
 /** Grant/claw an outcome balance. `delta` is a non-zero whole number; floored at
- *  0. The outcome is addressed by a STEP's `agentKey` (outcomes have no key of
- *  their own). */
+ *  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. */
 interface OutcomeAdjustInput {
-    /** An outcome step's stable agent key — identifies the parent outcome. */
+    /** 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;
@@ -846,6 +944,17 @@ interface OutcomeStepInput {
 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;
@@ -874,6 +983,15 @@ interface OutcomeDetail extends Outcome {
 }
 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;
@@ -973,6 +1091,160 @@ 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`.
+ */
+interface UnitTrackResult {
+    /** True when the report was accepted but not yet priced (`202`). */
+    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.
+ */
+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;
+}
+/** 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()`.
+ *
+ * `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.
+ */
+interface CompositeCompletionResult {
+    /** True when the ping was accepted but not yet applied (`202`). */
+    queued: boolean;
+    /** `COMPLETED` on the first close, `ALREADY_COMPLETED` on a replay. Absent
+     *  when the ping was queued or parked. */
+    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`. */
@@ -1135,6 +1407,35 @@ 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. */
+    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
@@ -1225,12 +1526,12 @@ declare class Customers {
     plan(id: string): Promise<CustomerPlan>;
     /** List a customer's members. `GET …/:id/members`. */
     listMembers(id: string): Promise<Member[]>;
-    /** Add a member to a customer. Duplicate `employeeId` → ConflictError. */
-    addMember(id: string, input: AddMemberInput): Promise<Member>;
-    /** Update a member's profile (role is fixed). `PATCH …/:id/members/:memberId`. */
-    updateMember(id: string, memberId: string, input: UpdateMemberInput): Promise<Member>;
-    /** Remove a member from a customer. `DELETE …/:id/members/:memberId`. */
-    removeMember(id: string, memberId: string): Promise<void>;
+    /** Add a member to a customer. Duplicate `email` → ConflictError. */
+    addMember(id: string, input: AddMemberInput): Promise<MemberProfile>;
+    /** Update a member's profile. Duplicate `email` → ConflictError. `PATCH …/:id/members/:memberId`. */
+    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;
@@ -1280,8 +1581,14 @@ declare class Invoices {
 
 /**
  * The `outcomes` resource — manage the org's outcome *types* (the catalog). An
- * outcome is a multi-step workflow; each step has a stable `agentKey` you pass
- * to `signals.outcome()`. `/api/v1/outcomes`.
+ * 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;
@@ -1387,7 +1694,17 @@ declare class Purchases {
 
 /** One buffered, wire-ready signal awaiting a background flush. */
 interface QueuedSignal {
-    /** The exact JSON body to POST to /api/v1/usage. */
+    /**
+     * The route this signal posts to (`/api/v1/signal/credit` etc.), decided by
+     * `track()` when the signal was buffered.
+     *
+     * It is stored per item rather than fixed on the Flusher because each meter
+     * now has its own endpoint. A single hardcoded path was fine when everything
+     * went to `/api/v1/usage`; keeping one would have meant async mode silently
+     * posting to the deprecated route while sync mode used the new ones.
+     */
+    path: string;
+    /** The exact JSON body to POST. */
     body: Record<string, unknown>;
     /** The original signal — passed to onError/onDrop hooks. */
     signal: Signal;
@@ -1426,20 +1743,54 @@ declare class Flusher {
     close(): Promise<void>;
 }
 
-/** Builds the `POST /api/v1/usage` body from a typed Signal. */
+/**
+ * Builds the request body for a typed Signal.
+ *
+ * Two grouping changes from the pre-0.10 `POST /api/v1/usage` body, both of
+ * which the server now requires:
+ *
+ *   usage:     { model, inputTokens, outputTokens, cacheTokens }
+ *   composite: { "<refId>": "<value>" }
+ *
+ * `usage` collects the four fields describing one LLM call. `composite` is the
+ * more consequential one: the tag used to sit at the TOP LEVEL under its own
+ * caller-defined property name, which meant a composite called `model` or
+ * `status` shadowed a real ingest field. Nested, the two namespaces are
+ * separate and that collision is impossible.
+ *
+ * The route is NOT part of this body — see {@link SIGNAL_PATHS}.
+ */
 declare function signalToWire(signal: Signal): Record<string, unknown>;
 /**
  * The `signals` resource: record usage signals and read them back.
  *
- * In async mode (default), `track()` buffers the signal and returns immediately
- * with `{ queued: true }`. Pass `{ wait: true }` (or construct the client in
- * `sync` mode) to await the send and receive the computed `usageLog`.
+ * In async mode (default), `track()` buffers the signal locally and returns
+ * immediately with `{ queued: true }`. Pass `{ wait: true }` (or construct the
+ * client in `sync` mode) to await the request.
+ *
+ * Awaiting the request does NOT guarantee a priced result. The server writes
+ * every signal to a durable inbox and then hands it to a worker, so it answers
+ * `202` and `track()` resolves `{ queued: true, messageId, rawId, usageLog:
+ * null }` — accepted and impossible to lose, but not yet billed. Only when the
+ * server prices inline do you get `{ queued: false, usageLog }`. Branch on
+ * `queued`; never assume `usageLog`.
+ *
+ * `verify()` is the way to validate and price a signal synchronously, and
+ * `list()` is how you confirm one actually landed.
  */
 declare class Signals {
     private readonly transport;
     private readonly flusher;
     private readonly cfg;
     constructor(transport: Transport, flusher: Flusher, cfg: ResolvedConfig);
+    /**
+     * Record one usage signal, to the route its `type` selects:
+     * `POST /api/v1/signal/credit` | `/signal/outcome` | `/signal/wallet`.
+     *
+     * Returns as soon as the signal is buffered (async mode) or the request has
+     * been answered (`{ wait: true }` / sync mode). See {@link TrackResult}: a
+     * resolved promise means "accepted", which is not the same as "billed".
+     */
     track(signal: Signal, opts?: {
         wait?: boolean;
     }): Promise<TrackResult>;
@@ -1447,21 +1798,34 @@ declare class Signals {
      * Validate + price a signal WITHOUT recording it (server `dryRun`). Returns
      * the projected usage log so an integration can preflight before sending real
      * traffic — no inbox row, wallet / outcome writes, or webhooks fire.
+     *
+     * Only the model-priced kinds support this. A dry run is not offered for unit
+     * reports or composite completions, and the server REJECTS the flag on those
+     * routes rather than accepting and ignoring it — which is why there is no
+     * dry-run path through `unit()` or `completeComposite()`.
      */
     verify(signal: Signal): Promise<SerializedUsageLog | null>;
-    /** Meter a named credit. */
+    /** Meter a named credit. `POST /api/v1/signal/credit`. */
     credit(input: CreditInput, opts?: {
         wait?: boolean;
     }): Promise<TrackResult>;
-    /** Debit the customer's wallet at model cost. */
+    /** Debit the customer's wallet at model cost. `POST /api/v1/signal/wallet`. */
     wallet(input: WalletInput, opts?: {
         wait?: boolean;
     }): Promise<TrackResult>;
-    /** Advance one step of an outcome workflow. */
+    /** Advance one step of an outcome workflow. `POST /api/v1/signal/outcome`. */
     outcome(input: OutcomeInput, opts?: {
         wait?: boolean;
     }): Promise<TrackResult>;
-    /** Recent usage logs + totals for a customer. `GET /api/v1/usage`. */
+    /**
+     * 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;
@@ -1469,12 +1833,44 @@ declare class Signals {
     /**
      * Record one unit-metered event (a fixed-price meter with no tokens),
      * addressed to a catalog unit by its `agentKey`. Sent immediately — unit
-     * events are not buffered. `POST /api/v1/units`.
+     * events are not buffered. `POST /api/v1/signal/unit`.
+     *
+     * Two things changed with the move off `POST /api/v1/units`, and both show up
+     * in the return type. The route is now durable (the report lands in an inbox
+     * before it is priced, so a failure parks as Pending and can be retried
+     * instead of losing a billable event) and it answers `202` when it queues —
+     * so this resolves {@link UnitTrackResult}, not a bare `{ unitUsage }`.
+     * Branch on `queued`.
+     */
+    unit(input: UnitInput): Promise<UnitTrackResult>;
+    /**
+     * Close ONE occurrence of a composite — a distinct tag value.
+     * `POST /api/v1/signal/composite/complete`.
+     *
+     * A composite bundles several credits / outcomes / units and is billed as one
+     * thing. The occurrence opens on the first tagged signal and costs nothing;
+     * this call is the moment it is billed. Only your code knows when the
+     * workflow ended, so this is a DECLARATION, not a hint: tagged signals may
+     * arrive in any order and the occurrence stays open and unbilled until you
+     * say otherwise. Put it on the line before your own `return`.
+     *
+     * An OUTCOME never needs this — its own `complete: true` closes its run and
+     * the matching occurrence together. Credits and units have no "done" signal
+     * of their own, so this is theirs.
+     *
+     * Closing twice is safe: the second call answers `ALREADY_COMPLETED` and
+     * cannot bill again. Calling it EARLY is also safe — before every entitlement
+     * the composite is restricted to has reported, or while an ADVANCE pool is
+     * full — the server parks the ping and applies it when the blocker clears,
+     * rather than failing it.
+     */
+    completeComposite(input: CompositeCompletionInput): Promise<CompositeCompletionResult>;
+    /**
+     * A customer's unit balances + recent unit events. `GET /api/v1/units`.
+     *
+     * Legacy path for the same reason as {@link list}: the signal family is
+     * POST-only, so the read side has no successor and is not deprecated.
      */
-    unit(input: UnitInput): Promise<{
-        unitUsage: SerializedUnitUsage;
-    }>;
-    /** A customer's unit balances + recent unit events. `GET /api/v1/units`. */
     unitUsage(params: {
         customerId: string;
         limit?: number;
@@ -1569,6 +1965,8 @@ declare class ClockNext {
     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. */
@@ -1639,4 +2037,4 @@ declare class NetworkError extends ClockNextError {
     constructor(message: string);
 }
 
-export { type AddMemberInput, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ComponentType, ConflictError, type CostPoint, type CostStats, 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, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberRole, type MetricTag, type Model, type ModelBundleEntry, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeAnalytics, type OutcomeBalance, 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 SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, 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 UnitUsageList, type UnitUsageRow, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UpsertWebhookInput, type UsageBalance, type UsageList, ValidationError, type WalletComponentInput, type WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionType, type Webhook, type WorkspaceIdentity, signalToWire };
+export { type AddMemberInput, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ComponentType, type Composite, 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, 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 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 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 WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionType, type Webhook, type WorkspaceIdentity, signalToWire };