@clocknext/sdk 0.12.1 → 0.14.0

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;
@@ -310,6 +356,93 @@ interface UsageList {
     };
     logs: SerializedUsageLog[];
 }
+/** A preset time window, or `"custom"` for an explicit `from`/`to` range. */
+type UsageLogPeriod = "all" | "today" | "7d" | "30d" | "90d" | "custom";
+interface UsageLogListParams {
+    customerId: string;
+    /** Default 50, max 200. */
+    limit?: number;
+    /** Pass back a previous page's `nextCursor` to fetch the next page. Omit for
+     *  the first page. */
+    cursor?: string;
+    /** Default `"all"`. Pair `"custom"` with `from`/`to`. */
+    period?: UsageLogPeriod;
+    /** `YYYY-MM-DD`, only used when `period` is `"custom"`. */
+    from?: string;
+    /** `YYYY-MM-DD`, only used when `period` is `"custom"`. */
+    to?: string;
+}
+interface UsageLogAppliedRule {
+    ruleId: string | null;
+    ruleName: string;
+    mode: "MARGIN" | "CREDIT" | null;
+    marginPercentApplied: number | null;
+    /** Formatted, same as {@link UsageLogEntry.credit}'s `amount`. */
+    creditsApplied: string;
+}
+interface UsageLogOutcomeAttribution {
+    /** "2 / 4" — the step this call performed, and the outcome's total step
+     *  count. Not a progress target: a step may repeat within a run. */
+    step: string | null;
+    stepName: string | null;
+    runId: string | null;
+    /** How many signals the run holds. */
+    runSignals: number;
+    /** True once the run closed (`complete: true` was sent for it). */
+    closedRun: boolean;
+}
+/**
+ * One row of a customer's usage history, merged from every meter kind
+ * (`UsageLog`, `UnitUsageLog`, completed composite occurrences) into one
+ * feed and sorted by time — the same rows the customer portal's own "Usage
+ * logs" table shows. `model`, `credit`, `outcome`, `unit` and `composite` are
+ * each `null` unless `kind` matches that group.
+ */
+interface UsageLogEntry {
+    id: string;
+    createdAt: string;
+    kind: "credit" | "outcome" | "unit" | "wallet" | "composite";
+    status: SignalStatus;
+    typeName: string | null;
+    member: string | null;
+    model: {
+        name: string | null;
+        provider: string | null;
+    } | null;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheTokens: number;
+    };
+    /** Formatted USD strings (e.g. `"$0.0064"`). */
+    cost: {
+        providedCost: string;
+        customerCost: string;
+    };
+    /** Populated only when `kind === "credit"`. `amount` is a formatted credit
+     *  value, honouring the org's credit-decimals display setting. */
+    credit: {
+        amount: string;
+        appliedRules: UsageLogAppliedRule[];
+    } | null;
+    /** Populated only when `kind === "outcome"`. */
+    outcome: UsageLogOutcomeAttribution | null;
+    /** Populated only when `kind === "unit"`. `quantity` is formatted. */
+    unit: {
+        quantity: string;
+    } | null;
+    /** Populated only when `kind === "composite"`. `amount` is a formatted USD
+     *  price — the composite's flat price, read live, not stored per row. */
+    composite: {
+        amount: string;
+    } | null;
+}
+interface UsageLogPage {
+    usageLogs: UsageLogEntry[];
+    /** Pass this back as `cursor` to fetch the next page; `null` on the last
+     *  page. */
+    nextCursor: string | null;
+}
 interface ApiCustomer {
     id: string;
     slug: string;
@@ -902,17 +1035,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`. */
@@ -920,14 +1057,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;
@@ -1660,8 +1818,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;
@@ -1670,6 +1831,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;
+    }>;
 }
 
 /**
@@ -1956,6 +2125,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`.
      *
@@ -1993,13 +2181,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
@@ -2018,6 +2206,24 @@ declare class Signals {
         customerId: string;
         limit?: number;
     }): Promise<UnitUsageList>;
+    /**
+     * One customer's usage history, merged from every meter kind — credit,
+     * outcome, unit, wallet, and completed composite occurrences — into one
+     * feed sorted by time. `GET /api/v1/signal/usage-log`. Exactly the same
+     * rows the customer portal's own "Usage logs" table shows, so a caller can
+     * build against this instead of the portal UI.
+     *
+     * Cursor-paginated, NOT page-numbered: `limit` + `cursor` in, `nextCursor`
+     * out. Omit `cursor` for the first page; pass the previous page's
+     * `nextCursor` back to fetch the next one, and stop once it comes back
+     * `null`. Unlike offset pagination, the cost of a page never grows with how
+     * deep you've paged — each page only asks for rows strictly before the
+     * cursor's position.
+     *
+     * Read-only; unlike {@link track}/{@link unit}/etc., there is nothing to
+     * buffer or retry here.
+     */
+    usageLog(params: UsageLogListParams): Promise<UsageLogPage>;
 }
 
 /**
@@ -2211,4 +2417,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, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogOutcomeAttribution, type UsageLogPage, type UsageLogPeriod, 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.js

@@ -326,7 +326,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.12.1" ;
+var SDK_VERSION = "0.14.0" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -702,13 +702,15 @@ var Customers = class {
   // (PATCH …/:id) — there is no separate currency endpoint. Credit-type
   // assignment has no public API.
   // --- Balance adjustments -------------------------------------------------
-  /** Grant or claw back a credit balance. `POST …/:id/credits/adjust`. */
+  /** Grant or claw back a credit balance. Returns the remaining balance.
+   *  `POST …/:id/credits/adjust`. */
   async adjustCredit(id, input) {
-    await this.transport.request({
+    const res = await this.transport.request({
       method: "POST",
       path: `/api/v1/customers/${encodeURIComponent(id)}/credits/adjust`,
       body: input
     });
+    return { remaining: res.remaining };
   }
   /** Grant or claw back an outcome balance. Returns the remaining balance. */
   async adjustOutcome(id, input) {
@@ -728,6 +730,19 @@ var Customers = class {
     });
     return { remaining: res.remaining };
   }
+  /**
+   * 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`.
+   */
+  async adjustComposite(id, input) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/composites/adjust`,
+      body: input
+    });
+    return { remaining: res.remaining };
+  }
 };
 
 // src/resources/invoices.ts
@@ -1013,6 +1028,8 @@ var SIGNAL_PATHS = {
 };
 var UNIT_PATH = "/api/v1/signal/unit";
 var COMPOSITE_COMPLETE_PATH = "/api/v1/signal/composite/complete";
+var OUTCOME_COMPLETE_PATH = "/api/v1/signal/outcome/complete";
+var USAGE_LOG_PATH = "/api/v1/signal/usage-log";
 function signalToWire(signal) {
   const t = signal.tokens;
   const body = {
@@ -1033,7 +1050,6 @@ function signalToWire(signal) {
   }
   if (signal.type === "outcome") {
     body.runId = signal.runId;
-    if (signal.complete != null) body.complete = signal.complete;
   }
   if (signal.type !== "wallet" && signal.composite) {
     body.composite = { [signal.composite.ref]: signal.composite.value };
@@ -1103,6 +1119,48 @@ var Signals = class {
   outcome(input, opts) {
     return this.track({ ...input, type: "outcome" }, opts);
   }
+  /**
+   * 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}.
+   */
+  async completeOutcome(input) {
+    const idempotencyKey = input.idempotencyKey ?? newKey();
+    const res = await this.transport.request({
+      method: "POST",
+      path: OUTCOME_COMPLETE_PATH,
+      idempotencyKey,
+      body: {
+        customerId: input.customerId,
+        runId: input.runId,
+        complete: true,
+        ...input.member ? { member: input.member } : {},
+        idempotencyKey
+      },
+      retry: true
+    });
+    const queued = res.queued === true;
+    return {
+      delivery: queued ? "accepted" : "recorded",
+      queued,
+      ...res.status != null ? { status: res.status } : {},
+      usageLog: res.usageLog ?? null,
+      ...handles(res)
+    };
+  }
   /**
    * Recent usage logs + totals for a customer. `GET /api/v1/usage`.
    *
@@ -1175,13 +1233,13 @@ var Signals = class {
    * 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
@@ -1230,6 +1288,37 @@ var Signals = class {
       query: { customerId: params.customerId, limit: params.limit }
     });
   }
+  /**
+   * One customer's usage history, merged from every meter kind — credit,
+   * outcome, unit, wallet, and completed composite occurrences — into one
+   * feed sorted by time. `GET /api/v1/signal/usage-log`. Exactly the same
+   * rows the customer portal's own "Usage logs" table shows, so a caller can
+   * build against this instead of the portal UI.
+   *
+   * Cursor-paginated, NOT page-numbered: `limit` + `cursor` in, `nextCursor`
+   * out. Omit `cursor` for the first page; pass the previous page's
+   * `nextCursor` back to fetch the next one, and stop once it comes back
+   * `null`. Unlike offset pagination, the cost of a page never grows with how
+   * deep you've paged — each page only asks for rows strictly before the
+   * cursor's position.
+   *
+   * Read-only; unlike {@link track}/{@link unit}/etc., there is nothing to
+   * buffer or retry here.
+   */
+  usageLog(params) {
+    return this.transport.request({
+      method: "GET",
+      path: USAGE_LOG_PATH,
+      query: {
+        customerId: params.customerId,
+        limit: params.limit,
+        cursor: params.cursor,
+        period: params.period,
+        from: params.from,
+        to: params.to
+      }
+    });
+  }
 };
 
 // src/resources/units.ts