@terminal3/t3n-sdk 2.10.1 → 2.11.0

package/README.md

@@ -764,6 +764,72 @@ The algorithm matches `node/wasm/src/otp.rs` byte-for-byte: `String((hash * 31 +
 - **Spec alignment.** The walkthrough follows the as-built code, which differs from earlier T3-TS-026 versions on two points: `user-upsert` has no `op:` discriminator (dispatch is implicit on input shape), and the function for L2 session creation is `tee:user/contracts::create-kyc-provider-session` rather than `tee:kyc/contracts::create-session`. See [T3-TS-026 v0.6.0 changelog](../../docs/specs/T3-TS-026-kyc-frontend-integration.md) and [MAT-1374](https://linear.app/terminal3/issue/MAT-1374) for the deferred discriminator-vs-split decision.
 - **`STRICT_SCENARIO=true`** in the environment turns scenario assertion failures into a non-zero exit code (otherwise they're logged but the demo exits zero). `--scenario` always exits non-zero on a terminal-status mismatch.
 
+### Tenant Developer Demo
+
+Three-entity walkthrough: an **Admin** admits a tenant, the **Tenant** registers the Duffel flight contract and seeds credentials, a **User** (created via `demo:dev`) authenticates and searches / books flights. Each step is a separate command so you can run them independently.
+
+#### Three entities
+
+| Entity | Key env var | Role |
+|---|---|---|
+| Admin | `ADMIN_KEY` | Signs `tenant.admit` via the admin API |
+| Tenant | `TENANT_KEY` | Registers contract, creates KV map, injects Duffel API key |
+| User | `USER_KEY` | Authenticates and calls `search-offers` / `book-offer` on behalf of an AI agent |
+
+#### Environment variables
+
+| Variable | Default | Used by |
+|---|---|---|
+| `CRYPTO_NODE_URL` | `http://localhost:3000` | all commands |
+| `ADMIN_KEY` | `0x000...0001` | `admit` |
+| `TENANT_KEY` | `0x000...0002` | `admit`, `setup` |
+| `DUFFEL_API_KEY` | `duffel_test_placeholder` | `setup` |
+| `FLIGHT_WASM_PATH` | _(unset)_ | `setup` — path to compiled `z-tenant-flight` WASM; falls back to a placeholder |
+| `USER_KEY` | `0x000...0003` | `search`, `book` — ETH key of a user already registered via `demo:dev` |
+| `OFFER_ID` | _(required)_ | `book` — offer ID printed by `search` |
+| `TOTAL_AMOUNT` | _(required)_ | `book` — total price printed by `search` |
+| `TOTAL_CURRENCY` | _(required)_ | `book` — currency code printed by `search` |
+
+#### Step 1 — Admit the tenant (Admin)
+
+```bash
+ADMIN_KEY=0x... TENANT_KEY=0x... pnpm demo:tenant:admit
+```
+
+#### Step 2 — Register contract + seed credentials (Tenant)
+
+```bash
+TENANT_KEY=0x... DUFFEL_API_KEY=duffel_test_... FLIGHT_WASM_PATH=../z-tenant-flight/target/wasm32-wasip2/release/z_tenant_flight.wasm pnpm demo:tenant:setup
+```
+
+This registers `z:<tid>:duffel-flight`, creates the `z:<tid>:secrets` KV map restricted to that contract, then calls `store-credentials` on the contract to write the Duffel API key into the map.
+
+#### Step 3 — Create the user (User)
+
+Use the standard user demo — no changes needed:
+
+```bash
+USER_KEY=0x... pnpm demo:dev
+```
+
+#### Step 4 — Search for flights (User / Agent)
+
+```bash
+USER_KEY=0x... pnpm demo:tenant:search
+```
+
+Prints up to 5 offers. The last line of output is the exact `book` command with the correct `OFFER_ID`, `TOTAL_AMOUNT`, and `TOTAL_CURRENCY` pre-filled.
+
+#### Step 5 — Book a flight (User / Agent)
+
+```bash
+USER_KEY=0x... OFFER_ID=off_... TOTAL_AMOUNT=199.00 TOTAL_CURRENCY=GBP pnpm demo:tenant:book
+```
+
+The passenger record is a hardcoded fixture (Jane Doe, GB passport). PII enters the TEE enclave and is never returned — only `booking_id`, `pnr`, and `status` cross the WIT boundary back to the caller.
+
+---
+
 ## WASM Integration
 
 The SDK can work with both real T3n WASM components and mock components for testing.

package/dist/index.d.ts

@@ -809,6 +809,109 @@ interface OrgDataActionWire {
     signature: string;
 }
 
+/**
+ * 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).
+ */
+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.
+ */
+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.
+ */
+type Direction = "in" | "out";
+/**
+ * Discriminated union mirroring `primitives::token::ChargeReason`.
+ * Present only when the row's `kind === "charge"`.
+ */
+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`).
+ */
+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.
+ */
+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".
+ */
+interface GetUsageOptions {
+    limit?: number;
+    after_seq?: number;
+    kinds?: TokenTxKind[];
+}
+
 /**
  * Public types export for T3n SDK
  */
@@ -890,7 +993,9 @@ 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>;
     /**
@@ -1306,6 +1411,22 @@ 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.
      */
@@ -1650,6 +1771,41 @@ 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