@clocknext/sdk 0.12.0 → 0.13.0

package/dist/index.d.cts

@@ -123,7 +123,14 @@ interface WalletSignal extends SignalBase {
 /**
  * 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`.
+ * may repeat freely. The run bills once, when the caller closes it with
+ * `signals.completeOutcome()` — a SEPARATE, dedicated call, never a flag on a
+ * step signal.
+ *
+ * There is no `complete` field here. `POST /api/v1/signal/outcome` (what this
+ * type posts to) now accepts ONLY the step shape and rejects a body that also
+ * carries `complete` — see {@link OutcomeCompletionInput} /
+ * `signals.completeOutcome()`, its own dedicated route.
  */
 interface OutcomeSignal extends SignalBase {
     type: "outcome";
@@ -135,17 +142,6 @@ interface OutcomeSignal extends SignalBase {
      * 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;
 }
@@ -154,6 +150,56 @@ type Signal = CreditSignal | WalletSignal | OutcomeSignal;
 type CreditInput = Omit<CreditSignal, "type">;
 type WalletInput = Omit<WalletSignal, "type">;
 type OutcomeInput = Omit<OutcomeSignal, "type">;
+/**
+ * Input for `signals.completeOutcome()` — closes ONE outcome run, the outcome
+ * mirror of {@link CompositeCompletionInput}. No `agentKey`, no `usage`: this
+ * closes an EXISTING run that an earlier `signals.outcome()` step already
+ * opened, so there is no step behind this call and nothing here to price.
+ *
+ * This closes the RUN only. If a step of this run also carried a `composite`,
+ * that occurrence stays open and unbilled until you separately call
+ * `signals.completeComposite()` — the two completions are independent, and
+ * neither implies the other.
+ */
+interface OutcomeCompletionInput {
+    customerId: string;
+    /** The same `runId` the run's step signals were sent with. */
+    runId: string;
+    /** Optional member (email) this completion is attributed to. */
+    member?: string;
+    /** Idempotency key, auto-generated if omitted. Sending `complete` twice for
+     *  the same run is already a safe no-op server-side, so this only collapses
+     *  a retry into one attempt rather than protecting against a double bill. */
+    idempotencyKey?: string;
+}
+/**
+ * The result of `signals.completeOutcome()`.
+ *
+ * Unlike {@link CompositeCompletionResult}, `ALREADY_COMPLETED` is NOT what a
+ * normal second ping for the same run gets back — that is rejected outright
+ * (a permanent error: the run has already been billed, and completing it again
+ * would bill it twice). `ALREADY_COMPLETED` is reserved for the much rarer case
+ * of two concurrent deliveries of the exact same request (e.g. a client-side
+ * retry racing the original), which really is a harmless echo.
+ */
+interface OutcomeCompletionResult {
+    /** How far the ping got. Never `"buffered"` — completions are always sent
+     *  immediately. See {@link TrackResult.status}. */
+    delivery: Extract<SignalDelivery, "accepted" | "recorded">;
+    /** True when the ping was accepted but not yet applied (`202`). Prefer
+     *  {@link OutcomeCompletionResult.delivery}. */
+    queued: boolean;
+    /** `COMPLETED` on the first close, `ALREADY_COMPLETED` only on the rare
+     *  concurrent-replay case described above. Absent when the ping was queued. */
+    status?: "COMPLETED" | "ALREADY_COMPLETED";
+    /** The priced usage log, when the server closed the run inline. `null` on a
+     *  `202` hand-off. */
+    usageLog?: SerializedUsageLog | null;
+    /** The durable inbox id — see {@link TrackResult.rawId}. */
+    rawId?: string;
+    /** The queue message id, present only on a `202` hand-off. */
+    messageId?: string;
+}
 interface SerializedRuleApplication {
     ruleId: string | null;
     ruleName: string;
@@ -249,8 +295,10 @@ interface TrackResult {
      *   `"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()`.
+     *                  discovered during pricing will NOT come back to you here,
+     *                  nor on `onError`. `signals.list()` shows what got priced;
+     *                  the dashboard's signal log — owner-only, by design — is
+     *                  where an individual rejection says why.
      *   `"recorded"` — the server priced it inline and `usageLog` is populated.
      *   `"dropped"`  — the SDK threw it away without sending: the client is
      *                  closed, or the local queue is full. `onDrop` fired with
@@ -900,17 +948,21 @@ interface WalletEntryInput {
     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`. */
+ *  non-zero whole number. The credit is addressed by its stable `agentKey`. A
+ *  reduce is never rejected or floored for going below 0 — the resulting
+ *  balance may read negative, same as a real-usage overdraft already can. */
 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
+/** Grant/claw an outcome balance. `delta` is a non-zero whole number. The
+ *  outcome is addressed here by a STEP's `agentKey`, which resolves to its
  *  parent outcome — NOT by the outcome's own `agentKey` ({@link Outcome.agentKey}),
- *  which this endpoint does not accept. */
+ *  which this endpoint does not accept. A reduce is never rejected or floored
+ *  for going below 0 — the resulting balance may read negative, same as a
+ *  real-usage overdraft already can. */
 interface OutcomeAdjustInput {
     /** An outcome STEP's stable agent key — identifies the parent outcome. Passing
      *  the outcome's own `agentKey` here fails with `422`. */
@@ -918,14 +970,35 @@ interface OutcomeAdjustInput {
     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`. */
+/** Grant/claw a unit balance. `delta` is non-zero (fractional allowed). The
+ *  unit is addressed by its stable `agentKey`. A reduce is never rejected or
+ *  floored for going below 0 — the resulting balance may read negative, same
+ *  as a real-usage overdraft already can. */
 interface UnitAdjustInput {
     /** The unit's stable agent key (the same key used to record usage). */
     agentKey: string;
     delta: number;
     notes?: string;
 }
+/**
+ * Grant (positive) or claw back (negative) slots on a customer's ADVANCE
+ * composite (pricing metric) pool for the CURRENT billing cycle. `delta` is a
+ * non-zero whole number. A reduce is never rejected or floored for going below
+ * 0 — same as credit/outcome/unit adjustments; the resulting pool may read
+ * negative. Fails if the customer has no active ADVANCE purchase component
+ * selling this composite.
+ */
+interface CompositeAdjustInput {
+    /**
+     * The composite's stable identifier — its `refId` (see {@link Composite.refId}),
+     * the same value signals tag it with, NOT `agentKey` (a composite has no
+     * `agentKey` column of its own). Named `agentKey` on the wire only so the
+     * four adjust endpoints share one request shape.
+     */
+    agentKey: string;
+    delta: number;
+    notes?: string;
+}
 /** A per-model token bundle attached to a credit or outcome step. */
 interface ModelBundleEntry {
     orgModelId: string;
@@ -1658,8 +1731,11 @@ declare class Customers {
         transaction: WalletTransaction;
         balanceUsd: number;
     }>;
-    /** Grant or claw back a credit balance. `POST …/:id/credits/adjust`. */
-    adjustCredit(id: string, input: CreditAdjustInput): Promise<void>;
+    /** Grant or claw back a credit balance. Returns the remaining balance.
+     *  `POST …/:id/credits/adjust`. */
+    adjustCredit(id: string, input: CreditAdjustInput): Promise<{
+        remaining: number;
+    }>;
     /** Grant or claw back an outcome balance. Returns the remaining balance. */
     adjustOutcome(id: string, input: OutcomeAdjustInput): Promise<{
         remaining: number;
@@ -1668,6 +1744,14 @@ declare class Customers {
     adjustUnit(id: string, input: UnitAdjustInput): Promise<{
         remaining: number;
     }>;
+    /**
+     * Grant or claw back slots on a customer's ADVANCE composite pool for the
+     * current billing cycle. Returns the resulting `remaining` slot count.
+     * `POST …/:id/composites/adjust`.
+     */
+    adjustComposite(id: string, input: CompositeAdjustInput): Promise<{
+        remaining: number;
+    }>;
 }
 
 /**
@@ -1916,8 +2000,15 @@ declare function signalToWire(signal: Signal): Record<string, unknown>;
  *
  * Because of that, a signal the server later REJECTS (unknown `agentKey`, a
  * model the org has not enabled, no active plan) cannot come back through this
- * promise. It surfaces on the `onError` hook, and `list()` is how you confirm
- * one actually landed — ingestion being asynchronous, the only way to.
+ * promise — and does not reach `onError` either, since from here that request
+ * succeeded. Such a rejection has no programmatic channel at all: it is
+ * recorded on the workspace's signal log in the ClockNext dashboard, which is
+ * owner-only by design.
+ *
+ * `list()` is the partial check available from code. It returns priced usage
+ * logs with a `status`, so it confirms a signal landed and whether pricing
+ * succeeded — but a signal refused BEFORE pricing never becomes a usage log
+ * and does not appear there.
  */
 declare class Signals {
     private readonly transport;
@@ -1947,6 +2038,25 @@ declare class Signals {
     outcome(input: OutcomeInput, opts?: {
         wait?: boolean;
     }): Promise<TrackResult>;
+    /**
+     * Close ONE outcome run — declares the workflow finished and bills it. The
+     * outcome mirror of {@link Signals.completeComposite}, on its own dedicated
+     * route: `POST /api/v1/signal/outcome/complete`.
+     *
+     * An outcome bills per COMPLETION, never per step, and `signals.outcome()`
+     * never closes one — it accepts only the step shape. Declaring the workflow
+     * finished is always this separate, explicit, contentless call.
+     *
+     * This closes the RUN only. If a step of this run also carried a
+     * `composite`, that occurrence stays open and unbilled until you separately
+     * call {@link Signals.completeComposite} — the two completions are
+     * independent, and neither implies the other.
+     *
+     * Sent immediately, never buffered. A genuinely second, independent call for
+     * an already-closed run is a PERMANENT error (it would bill the run twice),
+     * not a safe no-op — see {@link OutcomeCompletionResult}.
+     */
+    completeOutcome(input: OutcomeCompletionInput): Promise<OutcomeCompletionResult>;
     /**
      * Recent usage logs + totals for a customer. `GET /api/v1/usage`.
      *
@@ -1984,13 +2094,13 @@ declare class Signals {
      * arrive in any order and the occurrence stays open and unbilled until you
      * say otherwise. Put it on the line before your own `return`.
      *
-     * EVERY composite needs this, outcome-backed ones included. An outcome's own
-     * `complete: true` closes its RUN and nothing else — it does not close the
-     * composite occurrence the run was tagged into, whatever mix of credits,
-     * outcomes and units that composite wraps. (Earlier versions of this SDK
-     * documented the opposite. Believing it means the occurrence stays ONGOING
-     * forever and is never billed, so if you tag outcome signals with a
-     * `composite`, you must still call this.)
+     * EVERY composite needs this, outcome-backed ones included. `completeOutcome()`
+     * closes its RUN and nothing else — it does not close the composite
+     * occurrence the run was tagged into, whatever mix of credits, outcomes and
+     * units that composite wraps. (Earlier versions of this SDK documented the
+     * opposite. Believing it means the occurrence stays ONGOING forever and is
+     * never billed, so if you tag outcome signals with a `composite`, you must
+     * still call this.)
      *
      * Closing twice is safe: the second call answers `ALREADY_COMPLETED` and
      * cannot bill again. Calling it EARLY is also safe — before every entitlement
@@ -2202,4 +2312,4 @@ declare class NetworkError extends ClockNextError {
     });
 }
 
-export { type AddMemberInput, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeCatalogueRef, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeComponentInput, type CompositeTag, ConflictError, type CostPoint, type CostStats, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditAnalytics, type CreditBalance, type CreditComponentInput, type CreditDetail, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type DropReason, type FetchLike, type FlatComponentInput, type FlatUnitInput, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type Model, type ModelBundleEntry, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeAnalytics, type OutcomeBalance, type OutcomeComponentInput, type OutcomeDetail, type OutcomeInput, type OutcomeSignal, type OutcomeStepInput, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanComponentInput, type PlanDetail, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type ThresholdKind, type TieredUnitInput, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitComponentInput, type UnitCustomerRow, type UnitDetail, type UnitInput, type UnitPricingType, type UnitTier, type UnitTierInput, type UnitTrackResult, type UnitUsageList, type UnitUsageRow, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UpsertWebhookInput, type UsageBalance, type UsageList, ValidationError, type WalletComponentInput, type WalletEntitlementKind, type WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionSource, type WalletTransactionType, type Webhook, type WorkspaceIdentity, signalToWire };
+export { type AddMemberInput, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeCatalogueRef, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeComponentInput, type CompositeTag, ConflictError, type CostPoint, type CostStats, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditAnalytics, type CreditBalance, type CreditComponentInput, type CreditDetail, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type DropReason, type FetchLike, type FlatComponentInput, type FlatUnitInput, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type Model, type ModelBundleEntry, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeAnalytics, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, type OutcomeComponentInput, type OutcomeDetail, type OutcomeInput, type OutcomeSignal, type OutcomeStepInput, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanComponentInput, type PlanDetail, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type ThresholdKind, type TieredUnitInput, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitComponentInput, type UnitCustomerRow, type UnitDetail, type UnitInput, type UnitPricingType, type UnitTier, type UnitTierInput, type UnitTrackResult, type UnitUsageList, type UnitUsageRow, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UpsertWebhookInput, type UsageBalance, type UsageList, ValidationError, type WalletComponentInput, type WalletEntitlementKind, type WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionSource, type WalletTransactionType, type Webhook, type WorkspaceIdentity, signalToWire };

package/dist/index.d.ts

@@ -123,7 +123,14 @@ interface WalletSignal extends SignalBase {
 /**
  * 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`.
+ * may repeat freely. The run bills once, when the caller closes it with
+ * `signals.completeOutcome()` — a SEPARATE, dedicated call, never a flag on a
+ * step signal.
+ *
+ * There is no `complete` field here. `POST /api/v1/signal/outcome` (what this
+ * type posts to) now accepts ONLY the step shape and rejects a body that also
+ * carries `complete` — see {@link OutcomeCompletionInput} /
+ * `signals.completeOutcome()`, its own dedicated route.
  */
 interface OutcomeSignal extends SignalBase {
     type: "outcome";
@@ -135,17 +142,6 @@ interface OutcomeSignal extends SignalBase {
      * 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;
 }
@@ -154,6 +150,56 @@ type Signal = CreditSignal | WalletSignal | OutcomeSignal;
 type CreditInput = Omit<CreditSignal, "type">;
 type WalletInput = Omit<WalletSignal, "type">;
 type OutcomeInput = Omit<OutcomeSignal, "type">;
+/**
+ * Input for `signals.completeOutcome()` — closes ONE outcome run, the outcome
+ * mirror of {@link CompositeCompletionInput}. No `agentKey`, no `usage`: this
+ * closes an EXISTING run that an earlier `signals.outcome()` step already
+ * opened, so there is no step behind this call and nothing here to price.
+ *
+ * This closes the RUN only. If a step of this run also carried a `composite`,
+ * that occurrence stays open and unbilled until you separately call
+ * `signals.completeComposite()` — the two completions are independent, and
+ * neither implies the other.
+ */
+interface OutcomeCompletionInput {
+    customerId: string;
+    /** The same `runId` the run's step signals were sent with. */
+    runId: string;
+    /** Optional member (email) this completion is attributed to. */
+    member?: string;
+    /** Idempotency key, auto-generated if omitted. Sending `complete` twice for
+     *  the same run is already a safe no-op server-side, so this only collapses
+     *  a retry into one attempt rather than protecting against a double bill. */
+    idempotencyKey?: string;
+}
+/**
+ * The result of `signals.completeOutcome()`.
+ *
+ * Unlike {@link CompositeCompletionResult}, `ALREADY_COMPLETED` is NOT what a
+ * normal second ping for the same run gets back — that is rejected outright
+ * (a permanent error: the run has already been billed, and completing it again
+ * would bill it twice). `ALREADY_COMPLETED` is reserved for the much rarer case
+ * of two concurrent deliveries of the exact same request (e.g. a client-side
+ * retry racing the original), which really is a harmless echo.
+ */
+interface OutcomeCompletionResult {
+    /** How far the ping got. Never `"buffered"` — completions are always sent
+     *  immediately. See {@link TrackResult.status}. */
+    delivery: Extract<SignalDelivery, "accepted" | "recorded">;
+    /** True when the ping was accepted but not yet applied (`202`). Prefer
+     *  {@link OutcomeCompletionResult.delivery}. */
+    queued: boolean;
+    /** `COMPLETED` on the first close, `ALREADY_COMPLETED` only on the rare
+     *  concurrent-replay case described above. Absent when the ping was queued. */
+    status?: "COMPLETED" | "ALREADY_COMPLETED";
+    /** The priced usage log, when the server closed the run inline. `null` on a
+     *  `202` hand-off. */
+    usageLog?: SerializedUsageLog | null;
+    /** The durable inbox id — see {@link TrackResult.rawId}. */
+    rawId?: string;
+    /** The queue message id, present only on a `202` hand-off. */
+    messageId?: string;
+}
 interface SerializedRuleApplication {
     ruleId: string | null;
     ruleName: string;
@@ -249,8 +295,10 @@ interface TrackResult {
      *   `"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()`.
+     *                  discovered during pricing will NOT come back to you here,
+     *                  nor on `onError`. `signals.list()` shows what got priced;
+     *                  the dashboard's signal log — owner-only, by design — is
+     *                  where an individual rejection says why.
      *   `"recorded"` — the server priced it inline and `usageLog` is populated.
      *   `"dropped"`  — the SDK threw it away without sending: the client is
      *                  closed, or the local queue is full. `onDrop` fired with
@@ -900,17 +948,21 @@ interface WalletEntryInput {
     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`. */
+ *  non-zero whole number. The credit is addressed by its stable `agentKey`. A
+ *  reduce is never rejected or floored for going below 0 — the resulting
+ *  balance may read negative, same as a real-usage overdraft already can. */
 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
+/** Grant/claw an outcome balance. `delta` is a non-zero whole number. The
+ *  outcome is addressed here by a STEP's `agentKey`, which resolves to its
  *  parent outcome — NOT by the outcome's own `agentKey` ({@link Outcome.agentKey}),
- *  which this endpoint does not accept. */
+ *  which this endpoint does not accept. A reduce is never rejected or floored
+ *  for going below 0 — the resulting balance may read negative, same as a
+ *  real-usage overdraft already can. */
 interface OutcomeAdjustInput {
     /** An outcome STEP's stable agent key — identifies the parent outcome. Passing
      *  the outcome's own `agentKey` here fails with `422`. */
@@ -918,14 +970,35 @@ interface OutcomeAdjustInput {
     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`. */
+/** Grant/claw a unit balance. `delta` is non-zero (fractional allowed). The
+ *  unit is addressed by its stable `agentKey`. A reduce is never rejected or
+ *  floored for going below 0 — the resulting balance may read negative, same
+ *  as a real-usage overdraft already can. */
 interface UnitAdjustInput {
     /** The unit's stable agent key (the same key used to record usage). */
     agentKey: string;
     delta: number;
     notes?: string;
 }
+/**
+ * Grant (positive) or claw back (negative) slots on a customer's ADVANCE
+ * composite (pricing metric) pool for the CURRENT billing cycle. `delta` is a
+ * non-zero whole number. A reduce is never rejected or floored for going below
+ * 0 — same as credit/outcome/unit adjustments; the resulting pool may read
+ * negative. Fails if the customer has no active ADVANCE purchase component
+ * selling this composite.
+ */
+interface CompositeAdjustInput {
+    /**
+     * The composite's stable identifier — its `refId` (see {@link Composite.refId}),
+     * the same value signals tag it with, NOT `agentKey` (a composite has no
+     * `agentKey` column of its own). Named `agentKey` on the wire only so the
+     * four adjust endpoints share one request shape.
+     */
+    agentKey: string;
+    delta: number;
+    notes?: string;
+}
 /** A per-model token bundle attached to a credit or outcome step. */
 interface ModelBundleEntry {
     orgModelId: string;
@@ -1658,8 +1731,11 @@ declare class Customers {
         transaction: WalletTransaction;
         balanceUsd: number;
     }>;
-    /** Grant or claw back a credit balance. `POST …/:id/credits/adjust`. */
-    adjustCredit(id: string, input: CreditAdjustInput): Promise<void>;
+    /** Grant or claw back a credit balance. Returns the remaining balance.
+     *  `POST …/:id/credits/adjust`. */
+    adjustCredit(id: string, input: CreditAdjustInput): Promise<{
+        remaining: number;
+    }>;
     /** Grant or claw back an outcome balance. Returns the remaining balance. */
     adjustOutcome(id: string, input: OutcomeAdjustInput): Promise<{
         remaining: number;
@@ -1668,6 +1744,14 @@ declare class Customers {
     adjustUnit(id: string, input: UnitAdjustInput): Promise<{
         remaining: number;
     }>;
+    /**
+     * Grant or claw back slots on a customer's ADVANCE composite pool for the
+     * current billing cycle. Returns the resulting `remaining` slot count.
+     * `POST …/:id/composites/adjust`.
+     */
+    adjustComposite(id: string, input: CompositeAdjustInput): Promise<{
+        remaining: number;
+    }>;
 }
 
 /**
@@ -1916,8 +2000,15 @@ declare function signalToWire(signal: Signal): Record<string, unknown>;
  *
  * Because of that, a signal the server later REJECTS (unknown `agentKey`, a
  * model the org has not enabled, no active plan) cannot come back through this
- * promise. It surfaces on the `onError` hook, and `list()` is how you confirm
- * one actually landed — ingestion being asynchronous, the only way to.
+ * promise — and does not reach `onError` either, since from here that request
+ * succeeded. Such a rejection has no programmatic channel at all: it is
+ * recorded on the workspace's signal log in the ClockNext dashboard, which is
+ * owner-only by design.
+ *
+ * `list()` is the partial check available from code. It returns priced usage
+ * logs with a `status`, so it confirms a signal landed and whether pricing
+ * succeeded — but a signal refused BEFORE pricing never becomes a usage log
+ * and does not appear there.
  */
 declare class Signals {
     private readonly transport;
@@ -1947,6 +2038,25 @@ declare class Signals {
     outcome(input: OutcomeInput, opts?: {
         wait?: boolean;
     }): Promise<TrackResult>;
+    /**
+     * Close ONE outcome run — declares the workflow finished and bills it. The
+     * outcome mirror of {@link Signals.completeComposite}, on its own dedicated
+     * route: `POST /api/v1/signal/outcome/complete`.
+     *
+     * An outcome bills per COMPLETION, never per step, and `signals.outcome()`
+     * never closes one — it accepts only the step shape. Declaring the workflow
+     * finished is always this separate, explicit, contentless call.
+     *
+     * This closes the RUN only. If a step of this run also carried a
+     * `composite`, that occurrence stays open and unbilled until you separately
+     * call {@link Signals.completeComposite} — the two completions are
+     * independent, and neither implies the other.
+     *
+     * Sent immediately, never buffered. A genuinely second, independent call for
+     * an already-closed run is a PERMANENT error (it would bill the run twice),
+     * not a safe no-op — see {@link OutcomeCompletionResult}.
+     */
+    completeOutcome(input: OutcomeCompletionInput): Promise<OutcomeCompletionResult>;
     /**
      * Recent usage logs + totals for a customer. `GET /api/v1/usage`.
      *
@@ -1984,13 +2094,13 @@ declare class Signals {
      * arrive in any order and the occurrence stays open and unbilled until you
      * say otherwise. Put it on the line before your own `return`.
      *
-     * EVERY composite needs this, outcome-backed ones included. An outcome's own
-     * `complete: true` closes its RUN and nothing else — it does not close the
-     * composite occurrence the run was tagged into, whatever mix of credits,
-     * outcomes and units that composite wraps. (Earlier versions of this SDK
-     * documented the opposite. Believing it means the occurrence stays ONGOING
-     * forever and is never billed, so if you tag outcome signals with a
-     * `composite`, you must still call this.)
+     * EVERY composite needs this, outcome-backed ones included. `completeOutcome()`
+     * closes its RUN and nothing else — it does not close the composite
+     * occurrence the run was tagged into, whatever mix of credits, outcomes and
+     * units that composite wraps. (Earlier versions of this SDK documented the
+     * opposite. Believing it means the occurrence stays ONGOING forever and is
+     * never billed, so if you tag outcome signals with a `composite`, you must
+     * still call this.)
      *
      * Closing twice is safe: the second call answers `ALREADY_COMPLETED` and
      * cannot bill again. Calling it EARLY is also safe — before every entitlement
@@ -2202,4 +2312,4 @@ declare class NetworkError extends ClockNextError {
     });
 }
 
-export { type AddMemberInput, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeCatalogueRef, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeComponentInput, type CompositeTag, ConflictError, type CostPoint, type CostStats, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditAnalytics, type CreditBalance, type CreditComponentInput, type CreditDetail, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type DropReason, type FetchLike, type FlatComponentInput, type FlatUnitInput, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type Model, type ModelBundleEntry, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeAnalytics, type OutcomeBalance, type OutcomeComponentInput, type OutcomeDetail, type OutcomeInput, type OutcomeSignal, type OutcomeStepInput, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanComponentInput, type PlanDetail, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type ThresholdKind, type TieredUnitInput, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitComponentInput, type UnitCustomerRow, type UnitDetail, type UnitInput, type UnitPricingType, type UnitTier, type UnitTierInput, type UnitTrackResult, type UnitUsageList, type UnitUsageRow, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UpsertWebhookInput, type UsageBalance, type UsageList, ValidationError, type WalletComponentInput, type WalletEntitlementKind, type WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionSource, type WalletTransactionType, type Webhook, type WorkspaceIdentity, signalToWire };
+export { type AddMemberInput, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeCatalogueRef, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeComponentInput, type CompositeTag, ConflictError, type CostPoint, type CostStats, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditAnalytics, type CreditBalance, type CreditComponentInput, type CreditDetail, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type DropReason, type FetchLike, type FlatComponentInput, type FlatUnitInput, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type Model, type ModelBundleEntry, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeAnalytics, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, type OutcomeComponentInput, type OutcomeDetail, type OutcomeInput, type OutcomeSignal, type OutcomeStepInput, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanComponentInput, type PlanDetail, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type ThresholdKind, type TieredUnitInput, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitComponentInput, type UnitCustomerRow, type UnitDetail, type UnitInput, type UnitPricingType, type UnitTier, type UnitTierInput, type UnitTrackResult, type UnitUsageList, type UnitUsageRow, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UpsertWebhookInput, type UsageBalance, type UsageList, ValidationError, type WalletComponentInput, type WalletEntitlementKind, type WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionSource, type WalletTransactionType, type Webhook, type WorkspaceIdentity, signalToWire };