@terminal3/t3n-sdk 2.10.1 → 2.11.0

package/dist/src/client/t3n-client.d.ts

@@ -9,6 +9,7 @@ import { type ContractResponseSchema } from "./contract-response";
 import { SessionId, Did, SessionStatus, AuthInput, HandshakeResult } from "../types";
 import { KycPollOptions, KycStatus } from "../types/kyc";
 import { OtpChannel, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, SubmitUserInputArgs, SubmitUserInputResult } from "../types/user";
+import { GetUsageOptions, UsagePage } from "../types/token";
 /**
  * Main T3n SDK Client
  */
@@ -101,6 +102,22 @@ export declare class T3nClient {
      * optionally validates it with a schema.
      */
     execute(payload: unknown): Promise<string>;
+    /**
+     * Fetch the caller's usage feed — balance plus a bounded slice of
+     * recent token-ledger entries (charges, mints, transfers), newest
+     * first. T3-TS-030 Phase 1D step A (`token.get-usage`).
+     *
+     * `limit` defaults to 50 server-side and clamps silently to
+     * `1..=200`. `afterSeq` is the inclusive upper-bound `seq_no`
+     * passed back from a previous page's `next_cursor` to walk older
+     * 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.
+     */
+    getUsage(opts?: GetUsageOptions): Promise<UsagePage>;
     /**
      * Execute an action with an attached binary blob using multipart RPC.
      */
@@ -445,6 +462,41 @@ export declare class T3nClient {
      * Send an RPC request with automatic encryption/decryption
      */
     private sendRpcRequest;
+    /**
+     * 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.
+     *
+     * Auto-attaches the `Session-Id` header; surfaces JSON-RPC errors
+     * the same way as {@link sendRpcRequest} (typed
+     * `InsufficientCreditError` when applicable, `RpcError` otherwise).
+     * Returns the parsed `result` field — typically a JSON object the
+     * caller will narrow to the endpoint's response type.
+     */
+    private sendUnencryptedSessionRpc;
+    /**
+     * Inspect a JSON-RPC response for an `error` field and throw the
+     * appropriate typed exception. No-op when `response.error` is
+     * absent. Shared by every RPC path so wire-shape changes in the
+     * server's error envelope (typed-error subclasses, request-id
+     * placement, detail formatting) only need to land in one place.
+     *
+     * JSON-RPC `error.message` is the generic category string
+     * ("Invalid params", "Internal error", …). The node attaches the
+     * actionable text and per-request correlation id in `error.data`
+     * — see `node/api/src/responses/rpc.rs::from_service_error`.
+     * Extract both so callers (and toasts that only render `.message`)
+     * get the real reason plus an id an operator can grep in
+     * `api::error` logs.
+     *
+     * T3-TS-030 chargepoint denials surface as a typed
+     * `InsufficientCreditError` so frontends can branch on
+     * `instanceof` to render an "out of credit" UI without
+     * prefix-matching the message themselves. Wire format is pinned
+     * by `api/src/error.rs::service_insufficient_credit_wire_format_is_stable`.
+     */
+    private throwIfRpcError;
     private sendMultipartRpcRequest;
     /**
      * Capture the server-minted `Session-Id` from the last handshake

package/dist/src/client/transport.d.ts

@@ -38,7 +38,9 @@ export interface Transport {
      */
     send(request: JsonRpcRequest, headers: Record<string, string>): Promise<JsonRpcResponse>;
     /**
-     * Optionally send a JSON-RPC request with an attached binary blob.
+     * Send a JSON-RPC request with an attached binary blob (multipart/form-data).
+     * Part 1 (name=jsonrpc): JSON-RPC envelope.
+     * Part 2 (name=blob): raw binary bytes (e.g. WASM bytecode).
      */
     sendMultipart?(request: JsonRpcRequest, headers: Record<string, string>, blob: Blob): Promise<JsonRpcResponse>;
     /**

package/dist/src/types/index.d.ts

@@ -42,3 +42,4 @@ export * from "./session";
 export * from "./auth";
 export * from "./user";
 export * from "./org-data";
+export * from "./token";

package/dist/src/types/token.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Token-metering types — T3-TS-030 wire shapes.
+ *
+ * Mirrors `node/primitives/src/token.rs`. `u128` fields land on the
+ * wire as JSON numbers (same convention as the existing
+ * `token.get-balance` response) — JS clients with histories that
+ * exceed 2⁵³ tokens should switch to a streaming JSON parser; the
+ * common case fits in `number` losslessly.
+ */
+/**
+ * `primitives::token::BalanceRow` — caller's credit row.
+ *
+ * `available` and `reserved` are `u128` on the server; the wire
+ * format is a JSON number. Callers should not assume bigint until
+ * the SDK migrates to a streaming parser (tracked separately).
+ */
+export interface BalanceRow {
+    available: number;
+    reserved: number;
+    last_settled_seq_no: number;
+    version: number;
+    credit_exhausted: boolean;
+}
+/**
+ * `primitives::token::TokenTxKind` snake_case wire alphabet. Every
+ * value listed here is accepted by the server-side
+ * `token.get-usage` `kinds` filter.
+ */
+export type TokenTxKind = "mint" | "burn" | "charge" | "transfer" | "bridge_mint_attest" | "bridge_burn_attest";
+/**
+ * Per-caller view direction. `"in"` = caller's balance went up;
+ * `"out"` = caller's balance went down. Derived host-side from
+ * `(caller_did, tx.src, tx.dst)`; the same `seq_no` appears in both
+ * parties' usage feeds with opposite directions on a transfer.
+ */
+export type Direction = "in" | "out";
+/**
+ * Discriminated union mirroring `primitives::token::ChargeReason`.
+ * Present only when the row's `kind === "charge"`.
+ */
+export type ChargeReason = {
+    kind: "contract_register";
+    script_name: string;
+    version: string;
+} | {
+    kind: "invocation";
+    script_name: string;
+    function: string;
+    fuel_consumed: number;
+    fuel_tokens: number;
+    host_call_count: number;
+    host_call_tokens: number;
+} | {
+    kind: "kv_bytes";
+    map: string;
+} | {
+    kind: "cas_bytes";
+    backend: string;
+} | {
+    kind: "outbox_egress";
+    upstream: string;
+};
+/**
+ * One row in the caller's usage feed — a per-caller projection of
+ * the underlying `TokenTx`. `counterparty` is the other party from
+ * the caller's perspective: `tx.dst` on outbound entries, `tx.src`
+ * on inbound. `null` when the underlying tx has no counterparty
+ * (mints have no `src`; burns and charges have no `dst`).
+ */
+export interface UsageEntry {
+    seq_no: number;
+    kind: TokenTxKind;
+    amount: number;
+    timestamp_ms: number;
+    direction: Direction;
+    counterparty?: string | null;
+    reason?: ChargeReason | null;
+    note?: string | null;
+}
+/**
+ * Response shape of `token.get-usage` — caller's balance plus a
+ * paginated slice of their most-recent `token:tx_log` entries.
+ *
+ * `next_cursor` is the inclusive upper-bound `seq_no` to pass back
+ * as `after_seq` to fetch the next page. `null` (or absent) means
+ * the caller's history is fully drained.
+ */
+export interface UsagePage {
+    balance: BalanceRow;
+    entries: UsageEntry[];
+    next_cursor?: number | null;
+}
+/**
+ * Request shape — all fields optional. `limit` clamps to
+ * `1..=200` server-side; out-of-range values snap silently to the
+ * bounds. `kinds: []` is treated as "no filter".
+ */
+export interface GetUsageOptions {
+    limit?: number;
+    after_seq?: number;
+    kinds?: TokenTxKind[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terminal3/t3n-sdk",
-  "version": "2.10.1",
+  "version": "2.11.0",
   "type": "module",
   "description": "T3n TypeScript SDK - A minimal SDK that mirrors the server's RPC handler approach",
   "main": "dist/index.js",
@@ -41,6 +41,10 @@
     "demo": "pnpm build && tsx demo.ts",
     "demo:dev": "tsx demo.ts",
     "demo:real-wasm": "tsx demo.ts",
+    "demo:tenant:admit": "tsx --tsconfig tsconfig.demo.json tenant-demo.ts --cmd admit",
+    "demo:tenant:setup": "tsx --tsconfig tsconfig.demo.json tenant-demo.ts --cmd setup",
+    "demo:tenant:search": "tsx --tsconfig tsconfig.demo.json tenant-demo.ts --cmd search",
+    "demo:tenant:book": "tsx --tsconfig tsconfig.demo.json tenant-demo.ts --cmd book",
     "verify:pack": "node scripts/verify-pack.js",
     "prepublishOnly": "pnpm run build:public && pnpm run verify:pack",
     "release": "node scripts/release.js release",