@clocknext/sdk 0.18.0 → 0.19.1

package/dist/index.d.cts

@@ -164,6 +164,8 @@ type OutcomeCompletionInput = CustomerRef & {
     runId: string;
     /** Optional member (email) this completion is attributed to. */
     member?: string;
+    /** Free-form metadata, stored as-is with this completion. Never priced. */
+    custom?: Record<string, unknown>;
     /** Idempotency key, auto-generated if omitted. Sending this completion 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
@@ -385,8 +387,9 @@ interface UsageLogOutcomeAttribution {
 interface UsageLogEntry {
     id: string;
     createdAt: string;
-    /** Which meter this row is. */
-    type: "credit" | "outcome" | "unit" | "wallet" | "composite";
+    /** Which meter this row is. `"outcome"` is one step of a run;
+     *  `"outcome_completion"` is the finished run itself (one per run). */
+    type: "credit" | "outcome" | "outcome_completion" | "unit" | "wallet" | "composite";
     status: SignalStatus;
     typeName: string | null;
     member: string | null;
@@ -424,8 +427,22 @@ interface UsageLogEntry {
     composite: {
         amount: string;
     } | null;
-    /** The `custom` object sent on the signal, as sent. `null` when none was
-     *  sent, and always `null` for unit and composite rows. */
+    /** Populated only when `type === "outcome_completion"`. `amount` is the
+     *  price frozen when the run completed (your plan price, else the catalogue
+     *  price). */
+    outcomeCompletion: {
+        runId: string | null;
+        amount: string;
+        runSignals: number;
+    } | null;
+    /** The composite that covers this row's billing, by name — the row's price
+     *  is then included in that composite's own charge, not billed on top. Set
+     *  on credit / outcome / unit / outcome_completion rows tagged into a
+     *  composite on the customer's plan; `null` otherwise. */
+    coveredByComposite: string | null;
+    /** The `custom` object sent, as sent — on the signal itself, or on the
+     *  `completeComposite()` / `completeOutcome()` call that closed a composite /
+     *  outcome_completion row. `null` when none was sent. */
     custom: Record<string, unknown> | null;
 }
 interface UsageLogPage {
@@ -434,6 +451,104 @@ interface UsageLogPage {
      *  page. */
     nextCursor: string | null;
 }
+/** What a {@link UsageLogLookupEntry} row is. `"outcome"` is one step of a
+ *  run; `"outcome_completion"` and `"composite_completion"` are the finished
+ *  runs themselves. */
+type UsageLogLookupEntitlementType = "credit" | "outcome" | "outcome_completion" | "unit" | "composite_completion" | "wallet";
+/**
+ * One row of `signals.lookupUsageLogs()`. Only the group that matches
+ * `entitlement.type` holds data; the others are `null`.
+ */
+interface UsageLogLookupEntry {
+    id: string;
+    /** The customer this row belongs to — a lookup can span customers. */
+    customerId: string;
+    /** For a finished run (`outcome_completion`, `composite_completion`), when
+     *  it completed. */
+    createdAt: string;
+    status: SignalStatus;
+    /** The credit / outcome / unit / composite this row is for. A wallet row has
+     *  `id: null` and `name: "Wallet"`. */
+    entitlement: {
+        type: UsageLogLookupEntitlementType;
+        id: string | null;
+        name: string | null;
+    };
+    member: string | null;
+    model: {
+        name: string | null;
+        provider: string | null;
+    } | null;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        /** Cache-read tokens. */
+        cacheTokens: number;
+        /** Cache-write tokens, priced separately from cache reads. */
+        cacheWriteTokens: number;
+    };
+    /** Formatted USD strings. `customerCost` is what this row charged:
+     *  `"$0.00"` on an outcome step (the run is billed at completion) and on any
+     *  row a composite pays for. On a unit row it is what the wallet paid for
+     *  that report (debits minus refunds), `"$0.00"` when the wallet paid
+     *  nothing. */
+    cost: {
+        providedCost: string;
+        customerCost: string;
+    };
+    /** `entitlement.type === "credit"`. */
+    credit: {
+        amount: string;
+        appliedRules: UsageLogAppliedRule[];
+    } | null;
+    /** `entitlement.type === "outcome"`. `runCompleted` is true once the run is
+     *  finished — on every step row of that run. */
+    outcome: {
+        step: string | null;
+        stepName: string | null;
+        runId: string | null;
+        runCompleted: boolean;
+    } | null;
+    /** `entitlement.type === "outcome_completion"`. `amount` is the price frozen
+     *  when the run completed. */
+    outcomeCompletion: {
+        runId: string | null;
+        amount: string;
+    } | null;
+    /** `entitlement.type === "unit"`. `quantity` is formatted. */
+    unit: {
+        quantity: string;
+    } | null;
+    /** `entitlement.type === "composite_completion"`. `refId` is the
+     *  composite's tag key, `runId` the tag value you sent. */
+    compositeCompletion: {
+        refId: string | null;
+        runId: string | null;
+        amount: string;
+        startedAt: string;
+    } | null;
+    /** `entitlement.type === "wallet"`. What the wallet paid, formatted USD —
+     *  the same value as `cost.customerCost`. */
+    wallet: {
+        amount: string;
+    } | null;
+    /** The composite that pays for this row — its id, its tag key (`refId`) and
+     *  the tag value you sent (`runId`). `null` when the row is billed by
+     *  itself. */
+    composite: {
+        id: string | null;
+        refId: string | null;
+        runId: string | null;
+    } | null;
+    /** The `custom` object sent, as sent. `null` when none was sent. */
+    custom: Record<string, unknown> | null;
+}
+interface UsageLogLookupResult {
+    /** The rows found, in the order of the ids you asked for. */
+    usageLogs: UsageLogLookupEntry[];
+    /** The ids that matched nothing in your org, in the order you asked. */
+    notFound: string[];
+}
 interface ApiCustomer {
     id: string;
     /** Your own id for this customer, or `null` when unset. See
@@ -454,8 +569,6 @@ interface ApiCustomer {
     taxId: string | null;
     currencyCode: string;
     creditAllowance: number;
-    recurringTransactionEmail: boolean;
-    autoRecurring: boolean;
     createdAt: string;
     updatedAt: string;
 }
@@ -485,10 +598,6 @@ interface CustomerProfileInput {
     taxId?: string | null;
     /** ISO 4217 (3 letters); must be enabled for the org. */
     currencyCode?: string;
-    /** Send the invoice, payment receipt and card-payment-failed emails for recurring invoices. Defaults to `true` on create. */
-    recurringTransactionEmail?: boolean;
-    /** Issue every recurring invoice as `AUTO_CLOSED` (applied as if paid, never payable). Defaults to `false` on create. */
-    autoRecurring?: boolean;
 }
 /** `name` and `email` are required on create; every other field is optional. */
 type CreateCustomerInput = CustomerProfileInput & {
@@ -580,6 +689,79 @@ interface CustomerBalances {
      *  isn't listed. */
     composites: CompositeBalance[];
 }
+/** What caused a wallet ledger row (`WalletTransaction.source`). */
+type WalletTransactionSource = 
+/** Wallet money from a new plan purchase. */
+"SUBSCRIPTION"
+/** Wallet money from a plan renewal, or unused money removed at renewal. */
+ | "RENEWAL"
+/** Changed in the ClockNext dashboard. */
+ | "MANUAL"
+/** Changed with `customers.adjustWallet()`. */
+ | "API"
+/** Top-up paid by the customer in the customer portal. */
+ | "CUSTOMER_PORTAL"
+/** Charged by a signal; `usageLogId` links the signal. */
+ | "USAGE_LOG"
+/** Usage cleared by a paid pay-as-you-go invoice. */
+ | "INVOICE_SETTLEMENT"
+/** Settlement undone by a voided invoice. */
+ | "INVOICE_VOID";
+/** One row of a customer's wallet ledger (`customers.wallet()`). */
+interface WalletTransaction {
+    id: string;
+    /** ISO 8601. */
+    createdAt: string;
+    /** `CREDIT` adds money, `DEBIT` takes it out. */
+    type: "CREDIT" | "DEBIT";
+    /** Which balance moved: the ordinary wallet or the Reserved Wallet. */
+    pool: "main" | "reserved";
+    source: WalletTransactionSource;
+    /** Always positive — `type` gives the direction. In `currencyCode`. */
+    amount: number;
+    /** The same amount in USD. */
+    amountUsd: number;
+    currencyCode: string;
+    /** 1 USD = this many units of `currencyCode`, at write time. */
+    currencyRateUsd: number;
+    /** Only text a person wrote: your own note on an `API` row, the admin's
+     *  note on a `MANUAL` row. `null` on every row the system writes itself —
+     *  `source` says what those are. */
+    notes: string | null;
+    /** On a usage charge for an entitlement: which kind. `null` otherwise. */
+    entitlementType: "CREDIT" | "OUTCOME" | "UNIT" | "COMPOSITE" | null;
+    /** Id of that credit / outcome / unit / composite. */
+    entitlementId: string | null;
+    /** Its name when the row was written. */
+    entitlementName: string | null;
+    /** On a `USAGE_LOG` row: the id of the matching row in
+     *  `signals.usageLog()`. */
+    usageLogId: string | null;
+    /** On a `SUBSCRIPTION` / `RENEWAL` grant: the purchase it came from. */
+    purchaseId: string | null;
+    purchaseNumber: string | null;
+}
+/** One page of a customer's wallet ledger, newest first. */
+interface WalletLedgerPage {
+    /** Ordinary wallet balance, USD. May be negative. */
+    balanceUsd: number;
+    /** Reserved Wallet balance, USD; `null` when the workspace hasn't enabled
+     *  it. */
+    reservedBalanceUsd: number | null;
+    transactions: WalletTransaction[];
+    /** Pass back as `cursor` for the next page; `null` on the last page. */
+    nextCursor: string | null;
+}
+interface WalletLedgerParams {
+    /** Default 50, max 200. */
+    limit?: number;
+    /** A previous page's `nextCursor`. Omit for the first page. */
+    cursor?: string;
+    /** First day to include, `YYYY-MM-DD` (UTC). The whole day is included. */
+    from?: string;
+    /** Last day to include, `YYYY-MM-DD` (UTC). The whole day is included. */
+    to?: string;
+}
 /** The customer's active plan (the `plan` field of `customers.plan()`);
  *  `null` when the customer is unsubscribed. */
 interface CustomerPlanDetails {
@@ -1025,7 +1207,8 @@ interface PurchaseDetail {
         paidCount: number;
     };
 }
-/** `AUTO_CLOSED` — a recurring invoice for a customer with `autoRecurring` on:
+/** `AUTO_CLOSED` — a recurring invoice of an organisation with "Auto close
+ *  invoices on recurring" on (dashboard: Settings → Organisation → Billing):
  *  applied as if paid, but never payable. */
 type InvoiceStatus = "OPEN" | "PAID" | "VOID" | "AUTO_CLOSED";
 /** Trimmed row from `invoices.list()`. */
@@ -1398,6 +1581,8 @@ type UnitInput = CustomerRef & {
     quantity?: number;
     /** Optional composite this unit report belongs to. See {@link CompositeTag}. */
     composite?: CompositeTag;
+    /** Free-form metadata, stored as-is with this unit report. Never priced. */
+    custom?: Record<string, unknown>;
     /**
      * Idempotency key for safe retries — a repeat carrying the same key returns
      * the original result instead of drawing the balance down twice.
@@ -1447,6 +1632,9 @@ type CompositeCompletionInput = CustomerRef & {
     /** Which occurrence to close: the composite's `refId` and the correlation
      *  value the signals were tagged with. */
     composite: CompositeTag;
+    /** Free-form metadata, stored as-is on the occurrence this call closes.
+     *  Never priced. */
+    custom?: Record<string, unknown>;
     /** Idempotency key, auto-generated if omitted. Closing twice is already a
      *  safe no-op, so this only collapses retries into one recorded attempt
      *  rather than protecting against a double charge. */
@@ -1747,6 +1935,22 @@ declare class Customers {
     delete(id: string): Promise<void>;
     /** Wallet / credit / outcome / unit balances. `GET …/:id/balances`. */
     balances(id: string): Promise<CustomerBalances>;
+    /**
+     * One page of the customer's wallet ledger — every movement of wallet
+     * money, newest first — plus both wallet balances. Cursor-paginated: pass
+     * back `nextCursor` as `cursor`. `GET /api/v1/customers/:id/wallet`.
+     */
+    wallet(id: string, params?: WalletLedgerParams): Promise<WalletLedgerPage>;
+    /** {@link wallet}, addressing the customer by its `externalId`.
+     *  `GET /api/v1/customers/ext/:externalId/wallet`. */
+    walletByExternalId(externalId: string, params?: WalletLedgerParams): Promise<WalletLedgerPage>;
+    /**
+     * Async iterator over the customer's WHOLE wallet ledger, newest first,
+     * following the cursor. `params.cursor` is ignored.
+     * `for await (const t of cnk.customers.iterateWallet(id)) { … }`
+     */
+    iterateWallet(id: string, params?: Omit<WalletLedgerParams, "cursor">): AsyncGenerator<WalletTransaction>;
+    private walletPage;
     /** {@link balances}, addressing the customer by its `externalId`.
      *  `GET /api/v1/customers/ext/:externalId/balances`. */
     balancesByExternalId(externalId: string): Promise<CustomerBalances>;
@@ -2218,6 +2422,20 @@ declare class Signals {
      * buffer or retry here.
      */
     usageLog(params: UsageLogListParams): Promise<UsageLogPage>;
+    /**
+     * Fetches up to 100 usage-log rows by id, in one call.
+     * `GET /api/v1/signal/usage-log/lookup`.
+     *
+     * Built for linking a wallet debit to its usage: pass the `usageLogId`s
+     * from `customers.wallet()` instead of paging through
+     * {@link usageLog}. Scoped to your org, not to one customer — every row
+     * carries its own `customerId`.
+     *
+     * Rows come back in the order of `ids`; duplicates are removed. Ids that
+     * match nothing in your org are listed in `notFound`. More than 100
+     * distinct ids is a 400.
+     */
+    lookupUsageLogs(ids: string[]): Promise<UsageLogLookupResult>;
 }
 
 /**
@@ -2406,4 +2624,4 @@ declare class NetworkError extends ClockNextError {
     });
 }
 
-export { type AddMemberInput, type AdjustResult, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeBalance, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeItem, type CompositeTag, ConflictError, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateTaxInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditBalance, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type CustomerRef, type DropReason, type FetchLike, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type ModelBundleLine, type ModelBundleLineInput, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, type OutcomeInput, type OutcomeSignal, type OutcomeStep, type OutcomeStepInput, type OutcomeWithSteps, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanEntitlement, type PlanEntitlementInput, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RecurringGrantInput, type RecurringGrantResult, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type Tax, type TaxBehavior, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitInput, type UnitPricingType, type UnitTier, type UnitTrackResult, type UpdateCompositeInput, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateTaxInput, type UpdateUnitInput, type UsageBalance, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogOutcomeAttribution, type UsageLogPage, ValidationError, type WalletAdjustInput, type WalletInput, type WalletPool, type WalletSignal, signalToWire };
+export { type AddMemberInput, type AdjustResult, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeBalance, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeItem, type CompositeTag, ConflictError, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateTaxInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditBalance, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type CustomerRef, type DropReason, type FetchLike, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type ModelBundleLine, type ModelBundleLineInput, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, type OutcomeInput, type OutcomeSignal, type OutcomeStep, type OutcomeStepInput, type OutcomeWithSteps, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanEntitlement, type PlanEntitlementInput, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RecurringGrantInput, type RecurringGrantResult, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type Tax, type TaxBehavior, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitInput, type UnitPricingType, type UnitTier, type UnitTrackResult, type UpdateCompositeInput, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateTaxInput, type UpdateUnitInput, type UsageBalance, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogLookupEntitlementType, type UsageLogLookupEntry, type UsageLogLookupResult, type UsageLogOutcomeAttribution, type UsageLogPage, ValidationError, type WalletAdjustInput, type WalletInput, type WalletLedgerPage, type WalletLedgerParams, type WalletPool, type WalletSignal, type WalletTransaction, type WalletTransactionSource, signalToWire };

package/dist/index.d.ts

@@ -164,6 +164,8 @@ type OutcomeCompletionInput = CustomerRef & {
     runId: string;
     /** Optional member (email) this completion is attributed to. */
     member?: string;
+    /** Free-form metadata, stored as-is with this completion. Never priced. */
+    custom?: Record<string, unknown>;
     /** Idempotency key, auto-generated if omitted. Sending this completion 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
@@ -385,8 +387,9 @@ interface UsageLogOutcomeAttribution {
 interface UsageLogEntry {
     id: string;
     createdAt: string;
-    /** Which meter this row is. */
-    type: "credit" | "outcome" | "unit" | "wallet" | "composite";
+    /** Which meter this row is. `"outcome"` is one step of a run;
+     *  `"outcome_completion"` is the finished run itself (one per run). */
+    type: "credit" | "outcome" | "outcome_completion" | "unit" | "wallet" | "composite";
     status: SignalStatus;
     typeName: string | null;
     member: string | null;
@@ -424,8 +427,22 @@ interface UsageLogEntry {
     composite: {
         amount: string;
     } | null;
-    /** The `custom` object sent on the signal, as sent. `null` when none was
-     *  sent, and always `null` for unit and composite rows. */
+    /** Populated only when `type === "outcome_completion"`. `amount` is the
+     *  price frozen when the run completed (your plan price, else the catalogue
+     *  price). */
+    outcomeCompletion: {
+        runId: string | null;
+        amount: string;
+        runSignals: number;
+    } | null;
+    /** The composite that covers this row's billing, by name — the row's price
+     *  is then included in that composite's own charge, not billed on top. Set
+     *  on credit / outcome / unit / outcome_completion rows tagged into a
+     *  composite on the customer's plan; `null` otherwise. */
+    coveredByComposite: string | null;
+    /** The `custom` object sent, as sent — on the signal itself, or on the
+     *  `completeComposite()` / `completeOutcome()` call that closed a composite /
+     *  outcome_completion row. `null` when none was sent. */
     custom: Record<string, unknown> | null;
 }
 interface UsageLogPage {
@@ -434,6 +451,104 @@ interface UsageLogPage {
      *  page. */
     nextCursor: string | null;
 }
+/** What a {@link UsageLogLookupEntry} row is. `"outcome"` is one step of a
+ *  run; `"outcome_completion"` and `"composite_completion"` are the finished
+ *  runs themselves. */
+type UsageLogLookupEntitlementType = "credit" | "outcome" | "outcome_completion" | "unit" | "composite_completion" | "wallet";
+/**
+ * One row of `signals.lookupUsageLogs()`. Only the group that matches
+ * `entitlement.type` holds data; the others are `null`.
+ */
+interface UsageLogLookupEntry {
+    id: string;
+    /** The customer this row belongs to — a lookup can span customers. */
+    customerId: string;
+    /** For a finished run (`outcome_completion`, `composite_completion`), when
+     *  it completed. */
+    createdAt: string;
+    status: SignalStatus;
+    /** The credit / outcome / unit / composite this row is for. A wallet row has
+     *  `id: null` and `name: "Wallet"`. */
+    entitlement: {
+        type: UsageLogLookupEntitlementType;
+        id: string | null;
+        name: string | null;
+    };
+    member: string | null;
+    model: {
+        name: string | null;
+        provider: string | null;
+    } | null;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        /** Cache-read tokens. */
+        cacheTokens: number;
+        /** Cache-write tokens, priced separately from cache reads. */
+        cacheWriteTokens: number;
+    };
+    /** Formatted USD strings. `customerCost` is what this row charged:
+     *  `"$0.00"` on an outcome step (the run is billed at completion) and on any
+     *  row a composite pays for. On a unit row it is what the wallet paid for
+     *  that report (debits minus refunds), `"$0.00"` when the wallet paid
+     *  nothing. */
+    cost: {
+        providedCost: string;
+        customerCost: string;
+    };
+    /** `entitlement.type === "credit"`. */
+    credit: {
+        amount: string;
+        appliedRules: UsageLogAppliedRule[];
+    } | null;
+    /** `entitlement.type === "outcome"`. `runCompleted` is true once the run is
+     *  finished — on every step row of that run. */
+    outcome: {
+        step: string | null;
+        stepName: string | null;
+        runId: string | null;
+        runCompleted: boolean;
+    } | null;
+    /** `entitlement.type === "outcome_completion"`. `amount` is the price frozen
+     *  when the run completed. */
+    outcomeCompletion: {
+        runId: string | null;
+        amount: string;
+    } | null;
+    /** `entitlement.type === "unit"`. `quantity` is formatted. */
+    unit: {
+        quantity: string;
+    } | null;
+    /** `entitlement.type === "composite_completion"`. `refId` is the
+     *  composite's tag key, `runId` the tag value you sent. */
+    compositeCompletion: {
+        refId: string | null;
+        runId: string | null;
+        amount: string;
+        startedAt: string;
+    } | null;
+    /** `entitlement.type === "wallet"`. What the wallet paid, formatted USD —
+     *  the same value as `cost.customerCost`. */
+    wallet: {
+        amount: string;
+    } | null;
+    /** The composite that pays for this row — its id, its tag key (`refId`) and
+     *  the tag value you sent (`runId`). `null` when the row is billed by
+     *  itself. */
+    composite: {
+        id: string | null;
+        refId: string | null;
+        runId: string | null;
+    } | null;
+    /** The `custom` object sent, as sent. `null` when none was sent. */
+    custom: Record<string, unknown> | null;
+}
+interface UsageLogLookupResult {
+    /** The rows found, in the order of the ids you asked for. */
+    usageLogs: UsageLogLookupEntry[];
+    /** The ids that matched nothing in your org, in the order you asked. */
+    notFound: string[];
+}
 interface ApiCustomer {
     id: string;
     /** Your own id for this customer, or `null` when unset. See
@@ -454,8 +569,6 @@ interface ApiCustomer {
     taxId: string | null;
     currencyCode: string;
     creditAllowance: number;
-    recurringTransactionEmail: boolean;
-    autoRecurring: boolean;
     createdAt: string;
     updatedAt: string;
 }
@@ -485,10 +598,6 @@ interface CustomerProfileInput {
     taxId?: string | null;
     /** ISO 4217 (3 letters); must be enabled for the org. */
     currencyCode?: string;
-    /** Send the invoice, payment receipt and card-payment-failed emails for recurring invoices. Defaults to `true` on create. */
-    recurringTransactionEmail?: boolean;
-    /** Issue every recurring invoice as `AUTO_CLOSED` (applied as if paid, never payable). Defaults to `false` on create. */
-    autoRecurring?: boolean;
 }
 /** `name` and `email` are required on create; every other field is optional. */
 type CreateCustomerInput = CustomerProfileInput & {
@@ -580,6 +689,79 @@ interface CustomerBalances {
      *  isn't listed. */
     composites: CompositeBalance[];
 }
+/** What caused a wallet ledger row (`WalletTransaction.source`). */
+type WalletTransactionSource = 
+/** Wallet money from a new plan purchase. */
+"SUBSCRIPTION"
+/** Wallet money from a plan renewal, or unused money removed at renewal. */
+ | "RENEWAL"
+/** Changed in the ClockNext dashboard. */
+ | "MANUAL"
+/** Changed with `customers.adjustWallet()`. */
+ | "API"
+/** Top-up paid by the customer in the customer portal. */
+ | "CUSTOMER_PORTAL"
+/** Charged by a signal; `usageLogId` links the signal. */
+ | "USAGE_LOG"
+/** Usage cleared by a paid pay-as-you-go invoice. */
+ | "INVOICE_SETTLEMENT"
+/** Settlement undone by a voided invoice. */
+ | "INVOICE_VOID";
+/** One row of a customer's wallet ledger (`customers.wallet()`). */
+interface WalletTransaction {
+    id: string;
+    /** ISO 8601. */
+    createdAt: string;
+    /** `CREDIT` adds money, `DEBIT` takes it out. */
+    type: "CREDIT" | "DEBIT";
+    /** Which balance moved: the ordinary wallet or the Reserved Wallet. */
+    pool: "main" | "reserved";
+    source: WalletTransactionSource;
+    /** Always positive — `type` gives the direction. In `currencyCode`. */
+    amount: number;
+    /** The same amount in USD. */
+    amountUsd: number;
+    currencyCode: string;
+    /** 1 USD = this many units of `currencyCode`, at write time. */
+    currencyRateUsd: number;
+    /** Only text a person wrote: your own note on an `API` row, the admin's
+     *  note on a `MANUAL` row. `null` on every row the system writes itself —
+     *  `source` says what those are. */
+    notes: string | null;
+    /** On a usage charge for an entitlement: which kind. `null` otherwise. */
+    entitlementType: "CREDIT" | "OUTCOME" | "UNIT" | "COMPOSITE" | null;
+    /** Id of that credit / outcome / unit / composite. */
+    entitlementId: string | null;
+    /** Its name when the row was written. */
+    entitlementName: string | null;
+    /** On a `USAGE_LOG` row: the id of the matching row in
+     *  `signals.usageLog()`. */
+    usageLogId: string | null;
+    /** On a `SUBSCRIPTION` / `RENEWAL` grant: the purchase it came from. */
+    purchaseId: string | null;
+    purchaseNumber: string | null;
+}
+/** One page of a customer's wallet ledger, newest first. */
+interface WalletLedgerPage {
+    /** Ordinary wallet balance, USD. May be negative. */
+    balanceUsd: number;
+    /** Reserved Wallet balance, USD; `null` when the workspace hasn't enabled
+     *  it. */
+    reservedBalanceUsd: number | null;
+    transactions: WalletTransaction[];
+    /** Pass back as `cursor` for the next page; `null` on the last page. */
+    nextCursor: string | null;
+}
+interface WalletLedgerParams {
+    /** Default 50, max 200. */
+    limit?: number;
+    /** A previous page's `nextCursor`. Omit for the first page. */
+    cursor?: string;
+    /** First day to include, `YYYY-MM-DD` (UTC). The whole day is included. */
+    from?: string;
+    /** Last day to include, `YYYY-MM-DD` (UTC). The whole day is included. */
+    to?: string;
+}
 /** The customer's active plan (the `plan` field of `customers.plan()`);
  *  `null` when the customer is unsubscribed. */
 interface CustomerPlanDetails {
@@ -1025,7 +1207,8 @@ interface PurchaseDetail {
         paidCount: number;
     };
 }
-/** `AUTO_CLOSED` — a recurring invoice for a customer with `autoRecurring` on:
+/** `AUTO_CLOSED` — a recurring invoice of an organisation with "Auto close
+ *  invoices on recurring" on (dashboard: Settings → Organisation → Billing):
  *  applied as if paid, but never payable. */
 type InvoiceStatus = "OPEN" | "PAID" | "VOID" | "AUTO_CLOSED";
 /** Trimmed row from `invoices.list()`. */
@@ -1398,6 +1581,8 @@ type UnitInput = CustomerRef & {
     quantity?: number;
     /** Optional composite this unit report belongs to. See {@link CompositeTag}. */
     composite?: CompositeTag;
+    /** Free-form metadata, stored as-is with this unit report. Never priced. */
+    custom?: Record<string, unknown>;
     /**
      * Idempotency key for safe retries — a repeat carrying the same key returns
      * the original result instead of drawing the balance down twice.
@@ -1447,6 +1632,9 @@ type CompositeCompletionInput = CustomerRef & {
     /** Which occurrence to close: the composite's `refId` and the correlation
      *  value the signals were tagged with. */
     composite: CompositeTag;
+    /** Free-form metadata, stored as-is on the occurrence this call closes.
+     *  Never priced. */
+    custom?: Record<string, unknown>;
     /** Idempotency key, auto-generated if omitted. Closing twice is already a
      *  safe no-op, so this only collapses retries into one recorded attempt
      *  rather than protecting against a double charge. */
@@ -1747,6 +1935,22 @@ declare class Customers {
     delete(id: string): Promise<void>;
     /** Wallet / credit / outcome / unit balances. `GET …/:id/balances`. */
     balances(id: string): Promise<CustomerBalances>;
+    /**
+     * One page of the customer's wallet ledger — every movement of wallet
+     * money, newest first — plus both wallet balances. Cursor-paginated: pass
+     * back `nextCursor` as `cursor`. `GET /api/v1/customers/:id/wallet`.
+     */
+    wallet(id: string, params?: WalletLedgerParams): Promise<WalletLedgerPage>;
+    /** {@link wallet}, addressing the customer by its `externalId`.
+     *  `GET /api/v1/customers/ext/:externalId/wallet`. */
+    walletByExternalId(externalId: string, params?: WalletLedgerParams): Promise<WalletLedgerPage>;
+    /**
+     * Async iterator over the customer's WHOLE wallet ledger, newest first,
+     * following the cursor. `params.cursor` is ignored.
+     * `for await (const t of cnk.customers.iterateWallet(id)) { … }`
+     */
+    iterateWallet(id: string, params?: Omit<WalletLedgerParams, "cursor">): AsyncGenerator<WalletTransaction>;
+    private walletPage;
     /** {@link balances}, addressing the customer by its `externalId`.
      *  `GET /api/v1/customers/ext/:externalId/balances`. */
     balancesByExternalId(externalId: string): Promise<CustomerBalances>;
@@ -2218,6 +2422,20 @@ declare class Signals {
      * buffer or retry here.
      */
     usageLog(params: UsageLogListParams): Promise<UsageLogPage>;
+    /**
+     * Fetches up to 100 usage-log rows by id, in one call.
+     * `GET /api/v1/signal/usage-log/lookup`.
+     *
+     * Built for linking a wallet debit to its usage: pass the `usageLogId`s
+     * from `customers.wallet()` instead of paging through
+     * {@link usageLog}. Scoped to your org, not to one customer — every row
+     * carries its own `customerId`.
+     *
+     * Rows come back in the order of `ids`; duplicates are removed. Ids that
+     * match nothing in your org are listed in `notFound`. More than 100
+     * distinct ids is a 400.
+     */
+    lookupUsageLogs(ids: string[]): Promise<UsageLogLookupResult>;
 }
 
 /**
@@ -2406,4 +2624,4 @@ declare class NetworkError extends ClockNextError {
     });
 }
 
-export { type AddMemberInput, type AdjustResult, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeBalance, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeItem, type CompositeTag, ConflictError, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateTaxInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditBalance, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type CustomerRef, type DropReason, type FetchLike, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type ModelBundleLine, type ModelBundleLineInput, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, type OutcomeInput, type OutcomeSignal, type OutcomeStep, type OutcomeStepInput, type OutcomeWithSteps, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanEntitlement, type PlanEntitlementInput, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RecurringGrantInput, type RecurringGrantResult, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type Tax, type TaxBehavior, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitInput, type UnitPricingType, type UnitTier, type UnitTrackResult, type UpdateCompositeInput, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateTaxInput, type UpdateUnitInput, type UsageBalance, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogOutcomeAttribution, type UsageLogPage, ValidationError, type WalletAdjustInput, type WalletInput, type WalletPool, type WalletSignal, signalToWire };
+export { type AddMemberInput, type AdjustResult, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeBalance, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeItem, type CompositeTag, ConflictError, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateTaxInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditBalance, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type CustomerRef, type DropReason, type FetchLike, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type ModelBundleLine, type ModelBundleLineInput, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, type OutcomeInput, type OutcomeSignal, type OutcomeStep, type OutcomeStepInput, type OutcomeWithSteps, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanEntitlement, type PlanEntitlementInput, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RecurringGrantInput, type RecurringGrantResult, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type Tax, type TaxBehavior, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitInput, type UnitPricingType, type UnitTier, type UnitTrackResult, type UpdateCompositeInput, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateTaxInput, type UpdateUnitInput, type UsageBalance, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogLookupEntitlementType, type UsageLogLookupEntry, type UsageLogLookupResult, type UsageLogOutcomeAttribution, type UsageLogPage, ValidationError, type WalletAdjustInput, type WalletInput, type WalletLedgerPage, type WalletLedgerParams, type WalletPool, type WalletSignal, type WalletTransaction, type WalletTransactionSource, signalToWire };