@clocknext/sdk 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -18,6 +18,21 @@ interface Tokens {
     output: number;
     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).
+ */
+interface MetricTag {
+    /** The metric's `refId`. Case-insensitive; must not collide with a reserved
+     *  ingest field (e.g. `model`, `member`, `agentKey`, `runId`, `custom`). */
+    ref: string;
+    /** Your correlation value for this metric, stored verbatim. */
+    value: string | number;
+}
 /** The organisation + key behind a request — `cnk.workspace.me()`. */
 interface WorkspaceIdentity {
     organization: {
@@ -75,16 +90,36 @@ 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;
 }
 /** Debits the customer's wallet in USD at the model's cost. */
 interface WalletSignal extends SignalBase {
     type: "wallet";
 }
-/** Advances one step of a multi-call outcome workflow, by the step's `agentKey`. */
+/**
+ * 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`.
+ */
 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.
+     */
+    complete?: boolean;
+    /** Optional pricing-metric tag for reporting. */
+    metric?: MetricTag;
 }
 type Signal = CreditSignal | WalletSignal | OutcomeSignal;
 /** Helper input shapes for the per-type convenience methods. */
@@ -98,9 +133,21 @@ interface SerializedRuleApplication {
 }
 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;
-    progressSteps: string[];
+    /** 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
@@ -138,12 +185,38 @@ 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;
 }
 interface UsageList {
     customer: {
@@ -232,7 +305,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;
@@ -687,10 +762,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;
@@ -799,6 +876,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;
@@ -827,6 +915,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;
@@ -1233,8 +1330,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;
@@ -1384,15 +1487,31 @@ 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. Where the server has
+ * a durable queue configured it answers `202` and prices the signal in a worker,
+ * so `track()` resolves `{ queued: true, messageId, usageLog: null }` — accepted,
+ * not yet billed, and validated only later (a bad `agentKey` is dropped there,
+ * silently). 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. `POST /api/v1/usage`.
+     *
+     * 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>;
@@ -1592,4 +1711,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 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, 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 };

package/dist/index.d.ts

@@ -18,6 +18,21 @@ interface Tokens {
     output: number;
     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).
+ */
+interface MetricTag {
+    /** The metric's `refId`. Case-insensitive; must not collide with a reserved
+     *  ingest field (e.g. `model`, `member`, `agentKey`, `runId`, `custom`). */
+    ref: string;
+    /** Your correlation value for this metric, stored verbatim. */
+    value: string | number;
+}
 /** The organisation + key behind a request — `cnk.workspace.me()`. */
 interface WorkspaceIdentity {
     organization: {
@@ -75,16 +90,36 @@ 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;
 }
 /** Debits the customer's wallet in USD at the model's cost. */
 interface WalletSignal extends SignalBase {
     type: "wallet";
 }
-/** Advances one step of a multi-call outcome workflow, by the step's `agentKey`. */
+/**
+ * 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`.
+ */
 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.
+     */
+    complete?: boolean;
+    /** Optional pricing-metric tag for reporting. */
+    metric?: MetricTag;
 }
 type Signal = CreditSignal | WalletSignal | OutcomeSignal;
 /** Helper input shapes for the per-type convenience methods. */
@@ -98,9 +133,21 @@ interface SerializedRuleApplication {
 }
 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;
-    progressSteps: string[];
+    /** 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
@@ -138,12 +185,38 @@ 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;
 }
 interface UsageList {
     customer: {
@@ -232,7 +305,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;
@@ -687,10 +762,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;
@@ -799,6 +876,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;
@@ -827,6 +915,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;
@@ -1233,8 +1330,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;
@@ -1384,15 +1487,31 @@ 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. Where the server has
+ * a durable queue configured it answers `202` and prices the signal in a worker,
+ * so `track()` resolves `{ queued: true, messageId, usageLog: null }` — accepted,
+ * not yet billed, and validated only later (a bad `agentKey` is dropped there,
+ * silently). 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. `POST /api/v1/usage`.
+     *
+     * 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>;
@@ -1592,4 +1711,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 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, 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 };

package/dist/index.js

@@ -227,7 +227,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.6.0" ;
+var SDK_VERSION = "0.8.0" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -868,6 +868,13 @@ function signalToWire(signal) {
   if (signal.type === "credit" || signal.type === "outcome") {
     body.agentKey = signal.agentKey;
   }
+  if (signal.type === "outcome") {
+    body.runId = signal.runId;
+    if (signal.complete != null) body.complete = signal.complete;
+  }
+  if (signal.type !== "wallet" && signal.metric) {
+    body[signal.metric.ref] = signal.metric.value;
+  }
   if (signal.idempotencyKey) body.idempotencyKey = signal.idempotencyKey;
   return body;
 }
@@ -880,6 +887,13 @@ var Signals = class {
   transport;
   flusher;
   cfg;
+  /**
+   * Record one usage signal. `POST /api/v1/usage`.
+   *
+   * 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".
+   */
   async track(signal, opts = {}) {
     const body = signalToWire(signal);
     if (body.idempotencyKey == null) body.idempotencyKey = newKey();
@@ -896,8 +910,9 @@ var Signals = class {
       retry: true
     });
     return {
-      queued: false,
-      usageLog: res.usageLog ?? null
+      queued: res.queued === true,
+      usageLog: res.usageLog ?? null,
+      ...res.messageId != null ? { messageId: res.messageId } : {}
     };
   }
   /**