@terminal3/t3n-sdk 0.13.1 → 1.0.0

package/dist/index.d.ts

@@ -515,6 +515,128 @@ interface T3nClientConfig {
     handlers?: GuestToHostHandlers;
 }
 
+/**
+ * Error classes for T3n SDK
+ */
+/**
+ * Base error class for T3n SDK errors
+ */
+declare class T3nError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+/**
+ * Error thrown when session is in invalid state for operation
+ */
+declare class SessionStateError extends T3nError {
+    readonly currentState: string;
+    constructor(message: string, currentState: string);
+}
+/**
+ * Error thrown during authentication process
+ */
+declare class AuthenticationError extends T3nError {
+    readonly authMethod?: string | undefined;
+    constructor(message: string, authMethod?: string | undefined);
+}
+/**
+ * Error thrown during handshake process
+ */
+declare class HandshakeError extends T3nError {
+    constructor(message: string);
+}
+/**
+ * Error thrown during RPC communication
+ */
+declare class RpcError extends T3nError {
+    readonly rpcMethod?: string | undefined;
+    readonly httpStatus?: number | undefined;
+    constructor(message: string, rpcMethod?: string | undefined, httpStatus?: number | undefined);
+}
+/**
+ * Error thrown when WASM operations fail
+ */
+declare class WasmError extends T3nError {
+    readonly operation?: string | undefined;
+    readonly payload?: unknown | undefined;
+    constructor(message: string, operation?: string | undefined, payload?: unknown | undefined);
+}
+/**
+ * Decode WASM error message from comma-separated byte array format
+ * WASM errors often come as "83,101,114,100,101..." which represents ASCII bytes
+ *
+ * @param errorMessage - The error message string that may contain comma-separated bytes
+ * @returns Decoded error message if it was encoded, otherwise original message
+ */
+declare function decodeWasmErrorMessage(errorMessage: string): string;
+/**
+ * Extract and decode error from WASM ComponentError
+ *
+ * @param error - The error object from WASM
+ * @returns Decoded error message
+ */
+declare function extractWasmError(error: unknown): string;
+
+/**
+ * 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.
+ */
+
+/**
+ * Minimal validator interface. Any library that exposes `.parse(value) -> T`
+ * (zod, valibot, superstruct, custom) is compatible.
+ */
+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.
+ */
+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`)
+ */
+declare function parseContractResponse<T = unknown>(raw: string, schema?: ContractResponseSchema<T>): T;
+
 /**
  * T3n Client - Main SDK class
  *
@@ -599,9 +721,48 @@ 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).
@@ -780,68 +941,6 @@ declare function bytesToString(bytes: Uint8Array): string;
 
 declare function getScriptVersion(rpcUrl: string, scriptName: string): Promise<string>;
 
-/**
- * Error classes for T3n SDK
- */
-/**
- * Base error class for T3n SDK errors
- */
-declare class T3nError extends Error {
-    readonly code?: string | undefined;
-    constructor(message: string, code?: string | undefined);
-}
-/**
- * Error thrown when session is in invalid state for operation
- */
-declare class SessionStateError extends T3nError {
-    readonly currentState: string;
-    constructor(message: string, currentState: string);
-}
-/**
- * Error thrown during authentication process
- */
-declare class AuthenticationError extends T3nError {
-    readonly authMethod?: string | undefined;
-    constructor(message: string, authMethod?: string | undefined);
-}
-/**
- * Error thrown during handshake process
- */
-declare class HandshakeError extends T3nError {
-    constructor(message: string);
-}
-/**
- * Error thrown during RPC communication
- */
-declare class RpcError extends T3nError {
-    readonly rpcMethod?: string | undefined;
-    readonly httpStatus?: number | undefined;
-    constructor(message: string, rpcMethod?: string | undefined, httpStatus?: number | undefined);
-}
-/**
- * Error thrown when WASM operations fail
- */
-declare class WasmError extends T3nError {
-    readonly operation?: string | undefined;
-    readonly payload?: unknown | undefined;
-    constructor(message: string, operation?: string | undefined, payload?: unknown | undefined);
-}
-/**
- * Decode WASM error message from comma-separated byte array format
- * WASM errors often come as "83,101,114,100,101..." which represents ASCII bytes
- *
- * @param errorMessage - The error message string that may contain comma-separated bytes
- * @returns Decoded error message if it was encoded, otherwise original message
- */
-declare function decodeWasmErrorMessage(errorMessage: string): string;
-/**
- * Extract and decode error from WASM ComponentError
- *
- * @param error - The error object from WASM
- * @returns Decoded error message
- */
-declare function extractWasmError(error: unknown): string;
-
 /**
  * Secret redaction utilities for T3n SDK
  *
@@ -1029,5 +1128,5 @@ declare function clearKeyCache(): void;
  */
 declare function loadConfig(baseUrl?: string): SdkConfig;
 
-export { AuthMethod, AuthenticationError, HandshakeError, HttpTransport, LogLevel, MockTransport, NODE_URLS, RpcError, SessionStateError, SessionStatus, T3nClient, T3nError, WasmError, bytesToString, clearKeyCache, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createRandomHandler, decodeWasmErrorMessage, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, redactSecrets, redactSecretsFromJson, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, validateConfig, verifyDkgAttestation, verifyTdxQuote };
-export type { AuthInput, ClientAuth, ClientHandshake, ConfigValidationResult, Did, DkgAttestation, DkgVerifyResult, Environment, EthAuthInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, Logger, OidcAuthInput, OidcCredentials, PeerQuoteResult, QuoteVerifyResult, SdkConfig, SessionCrypto, SessionId, T3nClientConfig, Transport, WasmComponent, WasmNextResult };
+export { AuthMethod, AuthenticationError, ContractResponseError, HandshakeError, HttpTransport, LogLevel, MockTransport, NODE_URLS, RpcError, SessionStateError, SessionStatus, T3nClient, T3nError, WasmError, bytesToString, clearKeyCache, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createRandomHandler, decodeWasmErrorMessage, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, parseContractResponse, redactSecrets, redactSecretsFromJson, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, validateConfig, verifyDkgAttestation, verifyTdxQuote };
+export type { AuthInput, ClientAuth, ClientHandshake, ConfigValidationResult, ContractResponseSchema, Did, DkgAttestation, DkgVerifyResult, Environment, EthAuthInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, Logger, OidcAuthInput, OidcCredentials, PeerQuoteResult, QuoteVerifyResult, SdkConfig, SessionCrypto, SessionId, T3nClientConfig, Transport, WasmComponent, WasmNextResult };