@byte-42/fantastico-sdk 0.21.0 → 0.22.0

package/README.md

@@ -468,3 +468,17 @@ remint on `401`/`402`; a plain `Error` is treated as an error and nothing more.
 ## Licence
 
 MIT — Byte42 S.r.l. See [LICENSE](LICENSE).
+
+### Displaying account credit
+
+For account keys (`ck-fant-…`), `await ai.balance()` returns `remainingUsd` (free to commit to new
+runtime keys). An updated Cloud also returns `reservedUnspentUsd` (unspent reservations across all
+open keys, priced for the customer) and `totalRemainingUsd` (their sum). Display `totalRemainingUsd`
+as residual credit and use `lowTotalBalance` for its recharge warning. Existing `remainingUsd` and
+`lowBalance` keep their availability semantics; they must not be interpreted as spending.
+
+A $10 account with a $5 reservation that has consumed $0.03 therefore shows $9.97 residual credit,
+not $5.00. Open-key spending is measured so far and can change until reconciliation. No additional
+provider call or money movement is performed by this read. The new fields are optional in the SDK
+so it can still talk to older Cloud versions; when absent, do not invent a total by adding a locally
+cached key's reservation.

package/dist/types.d.ts

@@ -623,7 +623,15 @@ export interface RuntimeKeyHandle {
  * conto è a secco; questo serve a dire "stai per finire" prima che succeda.
  */
 export interface ContoBalance {
+    /** Free to commit to NEW runtime keys. Does not include unspent reservations. Unchanged. */
     remainingUsd: number;
+    /** Unspent reservations across all open keys, at the customer's price. Requires updated Cloud. */
+    reservedUnspentUsd?: number;
+    /** remainingUsd + reservedUnspentUsd. Use for a credit indicator, NOT to authorize spending.
+     * Based on measured usage so far; open-key costs remain provisional until reconciliation. */
+    totalRemainingUsd?: number;
+    /** Warning based on totalRemainingUsd. Optional for compatibility with older Cloud versions. */
+    lowTotalBalance?: boolean;
     lowBalance: boolean;
     status: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byte-42/fantastico-sdk",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "private": false,
   "publishConfig": {
     "access": "public"