@terminal3/t3n-sdk 0.13.1 → 1.0.0

package/dist/src/client/contract-response.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Contract response decoding for {@link T3nClient.execute}.
+ *
+ * ## On-wire shape
+ *
+ * Trinity contracts are declared as `result<list<u8>, string>` in WIT and
+ * return JSON-encoded bytes. The server-side pipeline is:
+ *
+ * 1. `node/wasm/src/dynamic.rs:component_val_to_json` deserializes those
+ *    bytes to a JSON `Value` (the contract's decoded return value).
+ * 2. `node/wasm/src/runner.rs:run_dynamic` wraps that value in a
+ *    `ContractResponse` struct internally for host-side bookkeeping —
+ *    it carries an extracted `otp_state` alongside the response.
+ * 3. **`node/app/src/services/wasm.rs:200`** then unwraps the struct with
+ *    `Ok((response.response, tx_back))`, discarding the `otp_state` field
+ *    and returning only the inner `Value` across the `WasmExecutor` trait
+ *    boundary.
+ * 4. `node/service/src/action.rs` serialises that plain `Value` through
+ *    the session channel.
+ *
+ * The client therefore receives the contract's **decoded JSON value
+ * directly** — no `{response, otp_state}` envelope, despite what the
+ * struct name suggests. `parseContractResponse` reflects that reality:
+ * it does a typed `JSON.parse` with optional schema validation, nothing
+ * more. OTP flows read their `otp_status` / OTP fields directly off the
+ * contract's response body; there is no separate envelope field for them
+ * on this path.
+ */
+import { T3nError } from "../utils/errors";
+/**
+ * Minimal validator interface. Any library that exposes `.parse(value) -> T`
+ * (zod, valibot, superstruct, custom) is compatible.
+ */
+export interface ContractResponseSchema<T> {
+    parse(value: unknown): T;
+}
+/**
+ * Thrown when the response string from {@link T3nClient.execute} cannot
+ * be parsed as JSON.
+ *
+ * Schema-validation failures are NOT wrapped — they surface as whatever
+ * error the caller's validator throws, preserving the rich diagnostics
+ * those libraries already provide.
+ */
+export declare class ContractResponseError extends T3nError {
+    readonly raw?: string | undefined;
+    constructor(message: string, raw?: string | undefined);
+}
+/**
+ * Parse the JSON-encoded response returned by {@link T3nClient.execute}
+ * into a typed value.
+ *
+ * @param raw - the string returned by {@link T3nClient.execute}
+ * @param schema - optional validator applied to the parsed value
+ * @returns the decoded response, typed as `T`
+ * @throws {ContractResponseError} when `raw` is not valid JSON
+ * @throws whatever the schema throws on validation failure (e.g. `ZodError`)
+ */
+export declare function parseContractResponse<T = unknown>(raw: string, schema?: ContractResponseSchema<T>): T;

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

@@ -8,3 +8,4 @@ export * from "./handlers";
 export * from "./encryption";
 export * from "./actions";
 export * from "./request-parser";
+export * from "./contract-response";

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

@@ -5,6 +5,7 @@
  * All cryptographic complexity is handled in WASM components.
  */
 import { T3nClientConfig } from "./config";
+import { type ContractResponseSchema } from "./contract-response";
 import { SessionId, Did, SessionStatus, AuthInput, HandshakeResult } from "../types";
 /**
  * Main T3n SDK Client
@@ -83,9 +84,48 @@ export declare class T3nClient {
      */
     private authenticateOidc;
     /**
-     * Execute an action on the T3n node
+     * Execute an action on the T3n node.
+     *
+     * Returns the JSON-stringified contract response. Most callers should
+     * prefer {@link executeAndDecode}, which JSON-parses the response and
+     * optionally validates it with a schema.
      */
     execute(payload: unknown): Promise<string>;
+    /**
+     * Execute an action and JSON-decode the response.
+     *
+     * The server strips its internal `ContractResponse` wrapper at
+     * `node/app/src/services/wasm.rs` before sending — the string returned
+     * by {@link execute} is the contract's decoded return value directly
+     * (no `{response, otp_state}` envelope). This helper is a typed
+     * `JSON.parse` with optional schema validation so callers stop
+     * reimplementing it at every call site.
+     *
+     * @param payload - action payload, identical to {@link execute}
+     * @param schema - optional validator applied to the parsed value
+     *   (e.g. a zod schema); anything exposing `.parse(value)` is accepted
+     * @returns the decoded response, typed as `T`
+     * @throws {ContractResponseError} when the response is not valid JSON
+     */
+    executeAndDecode<T = unknown>(payload: unknown, schema?: ContractResponseSchema<T>): Promise<T>;
+    /**
+     * Return the authenticated user's Ethereum address from their
+     * T3N-hosted per-user wallet, as a 0x-prefixed lowercase hex string.
+     * Returns `null` if the user has no wallet yet (pre-backfill edge
+     * case — `tee:user` has not yet been migrated for this DID).
+     *
+     * Backed by the `tee:user/get-self-eth-address` contract function,
+     * which delegates to the signing host's `get-user-eth-address`
+     * primitive (T3-TS-027 §7.1). The request carries no body; the
+     * authenticated user's DID is read from session context by the host.
+     *
+     * Requires the session to be Authenticated (same precondition as
+     * {@link execute}).
+     *
+     * @throws if unauthenticated, if the node rejects the action, or if
+     *   the response is not a JSON string / `null`.
+     */
+    getSelfEthAddress(): Promise<string | null>;
     /**
      * The server-minted session ID once handshake has completed, or
      * `null` beforehand (pentest M-1 / MAT-983).

package/dist/src/index.d.ts

@@ -8,6 +8,8 @@
 export { T3nClient } from "./client";
 export type { T3nClientConfig } from "./client";
 export type { HandshakeResult } from "./types";
+export { parseContractResponse, ContractResponseError, } from "./client";
+export type { ContractResponseSchema, } from "./client";
 export type { Logger } from "./utils/logger";
 export { LogLevel, createLogger, getLogger, setGlobalLogLevel, getGlobalLogLevel, } from "./utils/logger";
 export type { Transport, JsonRpcRequest, JsonRpcResponse } from "./client";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terminal3/t3n-sdk",
-  "version": "0.13.1",
+  "version": "1.0.0",
   "type": "module",
   "description": "T3n TypeScript SDK - A minimal SDK that mirrors the server's RPC handler approach",
   "main": "dist/index.js",