@clocknext/sdk 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clocknext/sdk",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Official ClockNext SDK — record usage signals and manage plans, purchases, invoices, customers, and billing from your backend.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -68,6 +68,10 @@ export type {
   CreateCustomerInput,
   CustomerList,
   CustomerBalances,
+  WalletLedgerPage,
+  WalletLedgerParams,
+  WalletTransaction,
+  WalletTransactionSource,
   CreditBalance,
   OutcomeBalance,
   UnitBalance,

package/src/resources/customers.ts

@@ -23,6 +23,9 @@ import type {
   UnitBalance,
   UpdateMemberInput,
   WalletAdjustInput,
+  WalletLedgerPage,
+  WalletLedgerParams,
+  WalletTransaction,
 } from "../types.js";
 
 /**
@@ -147,6 +150,57 @@ export class Customers {
     });
   }
 
+  /**
+   * 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> {
+    return this.walletPage(`/api/v1/customers/${encodeURIComponent(id)}/wallet`, params);
+  }
+
+  /** {@link wallet}, addressing the customer by its `externalId`.
+   *  `GET /api/v1/customers/ext/:externalId/wallet`. */
+  walletByExternalId(
+    externalId: string,
+    params: WalletLedgerParams = {},
+  ): Promise<WalletLedgerPage> {
+    return this.walletPage(
+      `/api/v1/customers/ext/${encodeURIComponent(externalId)}/wallet`,
+      params,
+    );
+  }
+
+  /**
+   * 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)) { … }`
+   */
+  async *iterateWallet(
+    id: string,
+    params: Omit<WalletLedgerParams, "cursor"> = {},
+  ): AsyncGenerator<WalletTransaction> {
+    let cursor: string | undefined;
+    do {
+      const page = await this.wallet(id, { ...params, cursor });
+      for (const t of page.transactions) yield t;
+      cursor = page.nextCursor ?? undefined;
+    } while (cursor);
+  }
+
+  private walletPage(path: string, params: WalletLedgerParams): Promise<WalletLedgerPage> {
+    return this.transport.request<WalletLedgerPage>({
+      method: "GET",
+      path,
+      query: {
+        limit: params.limit,
+        cursor: params.cursor,
+        from: params.from,
+        to: params.to,
+      },
+    });
+  }
+
   /** {@link balances}, addressing the customer by its `externalId`.
    *  `GET /api/v1/customers/ext/:externalId/balances`. */
   balancesByExternalId(externalId: string): Promise<CustomerBalances> {

package/src/resources/signals.ts

@@ -286,6 +286,7 @@ export class Signals {
         ...customerRefToWire(input),
         runId: input.runId,
         ...(input.member ? { member: input.member } : {}),
+        ...(input.custom ? { custom: input.custom } : {}),
         idempotencyKey,
       },
       retry: true,
@@ -328,6 +329,7 @@ export class Signals {
         ...(input.composite
           ? { composite: { [input.composite.ref]: input.composite.value } }
           : {}),
+        ...(input.custom ? { custom: input.custom } : {}),
         // Assigned HERE, before the send, so the SAME key rides every
         // transport-level retry below. Without it a single 500 followed by a
         // success is TWO un-keyed reports, and the server dedups on the key —
@@ -391,6 +393,7 @@ export class Signals {
       body: {
         ...customerRefToWire(input),
         composite: { [input.composite.ref]: input.composite.value },
+        ...(input.custom ? { custom: input.custom } : {}),
         // Auto-assigned like the others. A retry here could not double-BILL
         // even without it — closing a closed occurrence is a server-side
         // no-op — but that safety comes from occurrence-level dedup, not from

package/src/types.ts

@@ -189,6 +189,8 @@ export 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
@@ -429,8 +431,9 @@ export interface UsageLogOutcomeAttribution {
 export 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;
@@ -455,8 +458,22 @@ export interface UsageLogEntry {
   /** Populated only when `type === "composite"`. `amount` is a formatted USD
    *  price — the composite's flat price, read live, not stored per row. */
   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;
 }
 
@@ -491,8 +508,6 @@ export interface ApiCustomer {
   taxId: string | null;
   currencyCode: string;
   creditAllowance: number;
-  recurringTransactionEmail: boolean;
-  autoRecurring: boolean;
   createdAt: string;
   updatedAt: string;
 }
@@ -523,10 +538,6 @@ export 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. */
@@ -619,6 +630,83 @@ export interface CustomerBalances {
   composites: CompositeBalance[];
 }
 
+/** What caused a wallet ledger row (`WalletTransaction.source`). */
+export 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()`). */
+export 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. */
+export 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;
+}
+
+export 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. */
 export interface CustomerPlanDetails {
@@ -1120,7 +1208,8 @@ export interface PurchaseDetail {
 // Invoices & Payments
 // ---------------------------------------------------------------------------
 
-/** `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. */
 export type InvoiceStatus = "OPEN" | "PAID" | "VOID" | "AUTO_CLOSED";
 
@@ -1529,6 +1618,8 @@ export 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.
@@ -1580,6 +1671,9 @@ export 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. */