@clocknext/sdk 0.18.0 → 0.19.1

package/README.md

@@ -618,6 +618,71 @@ wallet.reservedBalance; // number | undefined
 
 When the feature is off, `wallet.reservedBalance` is left out of `balances()`.
 
+### Wallet ledger
+
+`customers.wallet()` lists every movement of wallet money, newest first, with
+both balances. Each row's `source` says what caused it:
+
+| `source` | Meaning |
+|---|---|
+| `SUBSCRIPTION` | Wallet money from a new plan purchase |
+| `RENEWAL` | Wallet money from a plan renewal, or unused money removed at renewal |
+| `MANUAL` | Changed in the ClockNext dashboard |
+| `API` | Changed with `adjustWallet()` |
+| `CUSTOMER_PORTAL` | Top-up paid by the customer in the customer portal |
+| `USAGE_LOG` | Charged by a signal; `usageLogId` links the signal |
+| `INVOICE_SETTLEMENT` | Usage cleared by a paid pay-as-you-go invoice |
+| `INVOICE_VOID` | Settlement undone by a voided invoice |
+
+On a `USAGE_LOG` row, `usageLogId` is the id of the matching row in
+`signals.usageLog()`, so each charge links to the exact signal that caused it.
+`notes` is only text a person wrote — your own note on an `API` row, the
+admin's note on a `MANUAL` row — and `null` on every row the system writes.
+
+```ts
+const page = await cnk.customers.wallet(customerId, { from: "2026-10-01", to: "2026-10-07" });
+page.balanceUsd;          // ordinary wallet, USD
+page.reservedBalanceUsd;  // Reserved Wallet, or null when the feature is off
+
+for (const t of page.transactions) {
+  // t.type: "CREDIT" | "DEBIT"; t.amount is always positive
+  // t.entitlementType: "CREDIT" | "OUTCOME" | "UNIT" | "COMPOSITE" | null
+}
+
+// Every row, across all pages — pick out the signal charges:
+for await (const t of cnk.customers.iterateWallet(customerId)) {
+  if (t.source === "USAGE_LOG") console.log(t.usageLogId, t.amountUsd);
+}
+```
+
+### Look up usage rows by id
+
+`signals.lookupUsageLogs(ids)` returns up to 100 usage-log rows in one call —
+for example the row behind each wallet debit's `usageLogId`. It is scoped to
+your org, not one customer: every row has its own `customerId`. Rows come back
+in the order of `ids`; ids with no row in your org are listed in `notFound`.
+
+Each row has `entitlement: { type, id, name }` — `type` is `credit`, `outcome`,
+`outcome_completion`, `unit`, `composite_completion` or `wallet` (a wallet row
+is named `"Wallet"`) — and only the matching group (`credit`, `outcome`,
+`outcomeCompletion`, `unit`, `compositeCompletion`, `wallet`) is set.
+`composite: { id, refId, runId }` names the composite that pays for a row.
+`cost.customerCost` is what the row charged, so it matches the wallet debit.
+
+```ts
+const ledger = await cnk.customers.wallet(customerId);
+const ids = ledger.transactions
+  .filter((t) => t.source === "USAGE_LOG" && t.usageLogId)
+  .map((t) => t.usageLogId!);
+
+const { usageLogs, notFound } = await cnk.signals.lookupUsageLogs(ids);
+for (const row of usageLogs) {
+  row.entitlement.type;   // what was charged
+  row.cost.customerCost;  // what it charged
+  row.composite;          // { id, refId, runId } | null
+}
+```
+
 To change how much a customer is granted **every billing cycle** (not just
 their balance right now), use `updateRecurringGrant`. Any increase or decrease
 applies to their balance immediately. `quantity` is USD for the wallet and a
@@ -656,9 +721,10 @@ cnk.customers.get / update / delete / iterate
 cnk.customers.getByExternalId / updateByExternalId / updateRecurringGrantByExternalId
 cnk.customers.adjustCreditByExternalId / adjustOutcomeByExternalId / adjustUnitByExternalId
 cnk.customers.adjustCompositeByExternalId / adjustWalletByExternalId
-cnk.customers.deleteByExternalId / balancesByExternalId / planByExternalId
+cnk.customers.deleteByExternalId / balancesByExternalId / planByExternalId / walletByExternalId
 cnk.customers.listMembers / addMember / updateMember / removeMember
 cnk.customers.balances / creditBalance / outcomeBalance / unitBalance / plan
+cnk.customers.wallet / iterateWallet
 cnk.customers.adjustCredit / adjustOutcome / adjustUnit / adjustComposite / adjustWallet
 cnk.customers.updateRecurringGrant
 

package/dist/index.cjs

@@ -333,7 +333,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.18.0" ;
+var SDK_VERSION = "0.19.1" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -682,6 +682,47 @@ var Customers = class {
       path: `/api/v1/customers/${encodeURIComponent(id)}/balances`
     });
   }
+  /**
+   * 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, params = {}) {
+    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, params = {}) {
+    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, params = {}) {
+    let cursor;
+    do {
+      const page = await this.wallet(id, { ...params, cursor });
+      for (const t of page.transactions) yield t;
+      cursor = page.nextCursor ?? void 0;
+    } while (cursor);
+  }
+  walletPage(path, params) {
+    return this.transport.request({
+      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) {
@@ -1187,6 +1228,7 @@ 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";
+var USAGE_LOG_LOOKUP_PATH = "/api/v1/signal/usage-log/lookup";
 function signalToWire(signal) {
   const t = signal.tokens;
   const body = {
@@ -1306,6 +1348,7 @@ var Signals = class {
         ...customerRefToWire(input),
         runId: input.runId,
         ...input.member ? { member: input.member } : {},
+        ...input.custom ? { custom: input.custom } : {},
         idempotencyKey
       },
       retry: true
@@ -1343,6 +1386,7 @@ var Signals = class {
         ...input.quantity != null ? { quantity: input.quantity } : {},
         ...input.member ? { member: input.member } : {},
         ...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 —
@@ -1397,6 +1441,7 @@ var Signals = class {
       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
@@ -1446,6 +1491,26 @@ var Signals = class {
       }
     });
   }
+  /**
+   * 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) {
+    return this.transport.request({
+      method: "GET",
+      path: USAGE_LOG_LOOKUP_PATH,
+      query: { ids: ids.join(",") }
+    });
+  }
 };
 
 // src/resources/units.ts