@clocknext/sdk 0.20.1 → 0.20.2

package/package.json

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

package/src/types.ts

@@ -768,10 +768,10 @@ export interface WalletLedgerPage {
   /** Reserved Wallet balance, USD; `null` when the workspace hasn't enabled
    *  it. */
   reservedBalanceUsd: number | null;
-  /** The customer's own low-balance alert level, USD; `null` when none is set.
+  /** The customer's own low-balance threshold, USD; `null` when none is set.
    *  At or below it the `wallet.balance.drop` webhook fires for this customer.
    *  Set with `customers.setWalletAlert()`. */
-  lowBalanceAlertUsd: number | null;
+  lowBalanceThresholdUsd: number | null;
   transactions: WalletTransaction[];
   /** Pass back as `cursor` for the next page; `null` on the last page. */
   nextCursor: string | null;
@@ -779,8 +779,8 @@ export interface WalletLedgerPage {
 
 /** Result of `customers.setWalletAlert()`. */
 export interface WalletAlert {
-  /** The saved low-balance alert level, USD; `null` once cleared. */
-  lowBalanceAlertUsd: number | null;
+  /** The saved low-balance threshold, USD; `null` once cleared. */
+  lowBalanceThresholdUsd: number | null;
 }
 
 export interface WalletLedgerParams {

package/src/webhooks.ts

@@ -8,14 +8,19 @@ import { WebhookSignatureError } from "./errors.js";
  * dashboard (Settings → Webhooks). Two events exist today:
  *
  *   wallet.balance.update  a customer's MAIN wallet balance moved (credit or
- *                          debit). Invoice settlements and the Reserved
- *                          Wallet do not fire it.
+ *                          debit). NOT sent for changes caused by signals
+ *                          (usage debits and outcome / unit / composite
+ *                          charges): they can arrive thousands of times a
+ *                          minute. Invoice settlements and the Reserved
+ *                          Wallet do not fire it either. To read the current
+ *                          balance use `customers.balances()`.
  *   wallet.balance.drop    a debit took the balance from above a level to at
  *                          or below it. The level is the customer's own alert
  *                          level (`customers.setWalletAlert`) when they have
  *                          one, otherwise the endpoint's threshold. Fires once
  *                          per drop through the level, not on every debit while
- *                          the balance stays under it.
+ *                          the balance stays under it. A signal that crosses
+ *                          the level DOES fire it.
  *
  * Verify every request before trusting it — {@link constructWebhookEvent} does
  * that and returns the typed event. It needs the RAW request body: parsing the
@@ -38,6 +43,7 @@ export type WebhookEventType = "wallet.balance.update" | "wallet.balance.drop";
  * The ledger also has a `SETTLE` source (an invoice being paid off), but
  * `wallet.balance.update` is never sent for it, so it is not in this type.
  */
+// `USAGE` still arrives, but only from the dashboard's hand-recorded unit usage report — signal usage no longer sends `wallet.balance.update`.
 export type WebhookWalletSource = "TOPUP" | "USAGE" | "ADJUSTMENT";
 
 /** The customer a wallet event is about. */