@terminal3/t3n-sdk 4.12.0 → 4.13.0

package/dist/index.d.ts

@@ -1880,11 +1880,29 @@ declare class T3nClient {
      * entries. `kinds` filters by `TokenTxKind`; an empty array is
      * treated as "no filter".
      *
-     * Unlike {@link execute}, the body of this RPC is plaintext —
-     * `token.get-usage` is a session-authed read endpoint and the
-     * server-side handler does not run the encryption layer.
+     * Like {@link getAuditEvents} / {@link execute}, this runs the
+     * session-payload encryption: balance and ledger history are
+     * self-only data, so the request params and response are sealed to
+     * the session key rather than sent plaintext over TLS. (Transitional:
+     * the node still accepts the legacy plaintext shape during the
+     * staggered rollout, so a leaked `Session-Id` alone is not fully
+     * de-fanged on this endpoint until the sealed shape becomes
+     * mandatory.)
      */
     getUsage(opts?: GetUsageOptions): Promise<UsagePage>;
+    /**
+     * Fetch the caller's own credit row (`token.get-balance`).
+     *
+     * Like {@link getUsage} / {@link getAuditEvents}, this runs the
+     * session-payload encryption: the balance is self-only data, so the
+     * request (an empty sealed blob showing possession of the session
+     * key) and the response are sealed to the session key rather than
+     * sent plaintext over TLS. (Transitional: the node still accepts the
+     * legacy plaintext shape during the staggered rollout.) Prefer this
+     * over reading `getUsage().balance` when only the credit row is
+     * needed.
+     */
+    getBalance(): Promise<BalanceRow>;
     /**
      * List the caller's discoverable contracts (`contracts.list`) — the
      * node-backed source for the MCP `listContracts` funnel tool.
@@ -1896,8 +1914,9 @@ declare class T3nClient {
      * discovery-grant gated and return a uniform, non-disclosive empty page on a
      * gate miss (R5 anti-enumeration).
      *
-     * Plaintext session read (like {@link getUsage}): the response carries only
-     * public contract-registry metadata, so it is not sealed.
+     * Plaintext session read: the response carries only public
+     * contract-registry metadata (no PII), so it is not sealed — unlike
+     * the self-only reads {@link getUsage} / {@link getBalance}, which are.
      */
     listContracts(params?: ListContractsParams): Promise<ListContractsResult>;
     /**
@@ -1911,7 +1930,9 @@ declare class T3nClient {
      * and the verdict is uniform + non-disclosive (`disclosed:false`) when the
      * agent is not registered under the member (R5 anti-enumeration).
      *
-     * Plaintext session read (like {@link getUsage}).
+     * Plaintext session read: the verdict is uniform and non-disclosive,
+     * so it is not sealed (unlike the self-only reads {@link getUsage} /
+     * {@link getBalance}).
      */
     checkDelegation(params: GrantCheckParams): Promise<GrantCheckResult>;
     /**
@@ -2458,8 +2479,10 @@ declare class T3nClient {
     /**
      * Send a session-authenticated JSON-RPC request with plaintext
      * params/result (no SessionEncryption layer). Used for tenant-facing
-     * read endpoints (`token.get-balance`, `token.get-usage`) where the
-     * server-side handler reads the JSON envelope directly.
+     * read endpoints whose payloads carry only public / non-disclosive
+     * metadata (`contracts.list`, `delegation.check`) where the
+     * server-side handler reads the JSON envelope directly. (The token
+     * self-reads moved to the sealed path — see {@link getUsage}.)
      *
      * Auto-attaches the `Session-Id` header; surfaces JSON-RPC errors
      * the same way as {@link sendRpcRequest} (typed