@terminal3/t3n-sdk 1.2.0 → 1.3.1

package/dist/index.d.ts

@@ -546,12 +546,30 @@ declare class HandshakeError extends T3nError {
     constructor(message: string);
 }
 /**
- * Error thrown during RPC communication
+ * Error thrown during RPC communication.
+ *
+ * `message` is the human-readable error (preferring the server's
+ * `error.data.detail` when present, with the request id appended in
+ * `[<id>]` form so a UI that only surfaces `.message` still gives an
+ * operator something to grep). The structured fields below preserve
+ * the same info for callers that want to render or log them
+ * separately — e.g. a toast that shows `detail` but surfaces
+ * `requestId` in a "copy for support" affordance.
  */
 declare class RpcError extends T3nError {
     readonly rpcMethod?: string | undefined;
     readonly httpStatus?: number | undefined;
-    constructor(message: string, rpcMethod?: string | undefined, httpStatus?: number | undefined);
+    /** Server-attached detail (JSON-RPC `error.data.detail`). User-facing kinds
+     *  carry the specific reason here; internal kinds omit it. */
+    readonly detail?: string | undefined;
+    /** Per-request correlation id (JSON-RPC `error.data.request_id`). */
+    readonly requestId?: string | undefined;
+    constructor(message: string, rpcMethod?: string | undefined, httpStatus?: number | undefined, 
+    /** Server-attached detail (JSON-RPC `error.data.detail`). User-facing kinds
+     *  carry the specific reason here; internal kinds omit it. */
+    detail?: string | undefined, 
+    /** Per-request correlation id (JSON-RPC `error.data.request_id`). */
+    requestId?: string | undefined);
 }
 /**
  * Error thrown when WASM operations fail
@@ -637,6 +655,142 @@ declare class ContractResponseError extends T3nError {
  */
 declare function parseContractResponse<T = unknown>(raw: string, schema?: ContractResponseSchema<T>): T;
 
+/**
+ * KYC types for the `tee:user/contracts::kyc-status` short-poll
+ * function added in MAT-1202.
+ *
+ * The shape mirrors `tee_contracts/user/src/kyc_status.rs::KycStatusResponse`.
+ * Keep the two in sync — the bytes go straight from the contract
+ * through the JSON-RPC envelope into [[T3nClient.kycStatus]].
+ */
+
+/**
+ * Terminal status for a Level 2 KYC verification, plus `pending`.
+ *
+ * - `pending` — provider has not delivered a verdict yet, or the
+ *   webhook arrived but the post-action VC issuance hasn't completed.
+ * - `verified` — provider approved AND a VC has been issued. `vcIds`
+ *   carries the issued credential ids.
+ * - `rejected` — provider declined / required resubmission /
+ *   expired / the user abandoned the flow. `error` may carry a
+ *   provider-supplied reason.
+ * - `orphan` — a Veriff webhook arrived with a `vendorData` that
+ *   couldn't be matched to any user (T3-TS-024 §3.4). Should not
+ *   happen in the MetaMask flow but the contract surfaces it for
+ *   completeness.
+ */
+type KycStatusKind = "pending" | "verified" | "rejected" | "orphan";
+/**
+ * Snapshot returned by `tee:user/contracts::kyc-status`.
+ *
+ * Field names use camelCase on the SDK boundary even though the
+ * wire is snake_case — the wrapper rewrites keys at the client edge
+ * so callers don't see the JSON shape leaking through.
+ */
+interface KycStatus {
+    /** Terminal status if reached, otherwise `pending`. */
+    status: KycStatusKind;
+    /**
+     * Provider being polled. Echoed back so callers that didn't
+     * supply one see the contract's default (`"veriff"` in phase one).
+     */
+    provider: string;
+    /**
+     * Unix-millis of the latest contract-visible event:
+     * VC issuance time, attestation arrival time, session-row
+     * `started_at_ms`, or orphan-record arrival time. Best-effort —
+     * `undefined` when no source carries a usable timestamp.
+     */
+    updatedAt?: number;
+    /**
+     * VC ids appended for this provider, in append order. Empty for
+     * `pending` / `rejected` / `orphan`.
+     */
+    vcIds: string[];
+    /**
+     * Provider-supplied reason for `rejected`, when available.
+     */
+    error?: string;
+}
+/**
+ * Polling cadence for [[T3nClient.kycStatusPoll]]. Defaults match
+ * T3-TS-026 §8.4: poll fast for the first 30 seconds, then back
+ * off, and bail after 5 minutes.
+ */
+interface KycPollCadence {
+    /** Poll interval in ms while `elapsed < switchAtMs`. Default: 2000. */
+    fastMs: number;
+    /** Poll interval in ms once `elapsed >= switchAtMs`. Default: 5000. */
+    slowMs: number;
+    /** Elapsed-ms threshold to switch from fast to slow cadence. Default: 30_000. */
+    switchAtMs: number;
+    /**
+     * Maximum total time to spend polling before rejecting with
+     * [[KycStatusTimeoutError]]. Default: 300_000 (5 minutes).
+     */
+    timeoutMs: number;
+}
+/**
+ * Optional knobs for [[T3nClient.kycStatusPoll]]. Most callers won't
+ * touch any of these — the §8.4 defaults are baked in.
+ */
+interface KycPollOptions {
+    /**
+     * Cancellation signal. When aborted, the helper rejects with
+     * `signal.reason` (or a generic `AbortError` if the consumer
+     * didn't supply a reason). The currently-in-flight `kycStatus()`
+     * call also receives the signal so it can short-circuit.
+     */
+    signal?: AbortSignal;
+    /**
+     * Called with every snapshot the helper receives, including
+     * non-terminal `pending` ones. Useful for surfacing intermediate
+     * UI states (e.g. "still waiting on provider…"). Errors thrown
+     * from this callback are caught and ignored — they must not
+     * sink the poll loop.
+     */
+    onUpdate?: (status: KycStatus) => void;
+    /**
+     * Override one or more cadence fields. Anything not specified
+     * uses the §8.4 defaults from [[DEFAULT_KYC_POLL_CADENCE]].
+     */
+    cadence?: Partial<KycPollCadence>;
+    /**
+     * Provider id to poll. Defaults to the contract default
+     * (`"veriff"` in phase one). Mirrored on the wire as
+     * `input.provider_id`.
+     */
+    providerId?: string;
+}
+/**
+ * Default cadence used by [[T3nClient.kycStatusPoll]] when the caller
+ * doesn't override `cadence.*`. Matches T3-TS-026 §8.4 verbatim.
+ */
+declare const DEFAULT_KYC_POLL_CADENCE: KycPollCadence;
+/**
+ * Subset of [[KycStatusKind]] that ends a poll. `pending` is the
+ * only non-terminal value.
+ */
+declare const TERMINAL_KYC_STATUSES: ReadonlySet<KycStatusKind>;
+/**
+ * Thrown by [[T3nClient.kycStatusPoll]] when the cadence's
+ * `timeoutMs` elapses without a terminal status arriving. The
+ * `lastStatus` field is the most recent (necessarily `pending`)
+ * snapshot the helper saw, useful for surfacing "we tried for N
+ * minutes but Veriff is still working" UX.
+ */
+declare class KycStatusTimeoutError extends T3nError {
+    /** The §8.4 timeout the helper exhausted. */
+    readonly timeoutMs: number;
+    /** The last `pending` snapshot before timeout, if any. */
+    readonly lastStatus?: KycStatus | undefined;
+    constructor(
+    /** The §8.4 timeout the helper exhausted. */
+    timeoutMs: number, 
+    /** The last `pending` snapshot before timeout, if any. */
+    lastStatus?: KycStatus | undefined);
+}
+
 /**
  * T3n Client - Main SDK class
  *
@@ -819,6 +973,57 @@ declare class T3nClient {
      *   the response cannot be decoded.
      */
     removeUserWithWalletAbandonment(): Promise<unknown>;
+    /**
+     * One-shot poll of `tee:user/contracts::kyc-status`.
+     *
+     * Returns the current snapshot of the authenticated user's Level 2
+     * KYC state — see [[KycStatus]] for the four possible terminal /
+     * non-terminal values. The caller usually wants
+     * [[kycStatusPoll]] (which loops with §8.4 cadence until a
+     * terminal status arrives), but the bare snapshot is useful for
+     * pages that need to render the user's standing without waiting
+     * (e.g. account-status views, "did the user finish KYC last time
+     * they were here?" gates).
+     *
+     * Phase one default — `providerId` defaults to `"veriff"` (the
+     * contract applies the same default when the field is absent),
+     * so the most common call site is `await t3n.kycStatus()`.
+     *
+     * @param providerId optional provider id, mirrored on the wire as
+     *   `input.provider_id`. Omit for phase-one MetaMask flows.
+     * @throws if unauthenticated, if the node rejects the action
+     *   (e.g. `precondition_failed:` when no `create-kyc-provider-session`
+     *   row exists yet), or if the response shape is unexpected.
+     */
+    kycStatus(providerId?: string): Promise<KycStatus>;
+    /**
+     * Poll `kyc-status` until a terminal status arrives or the
+     * configured timeout elapses.
+     *
+     * Cadence defaults to T3-TS-026 §8.4: 2-second interval for the
+     * first 30 seconds, then 5 seconds, with a 5-minute hard cap.
+     * Override via `opts.cadence` if you need different numbers
+     * (e.g. tests that don't want to wait the full 30 seconds before
+     * the slow window kicks in). [[KycStatusTimeoutError]] is thrown
+     * if the timeout elapses without reaching a terminal state.
+     *
+     * `opts.signal` cancels the loop synchronously — the helper
+     * stops sleeping and rejects with the abort reason; an
+     * already-in-flight `kycStatus()` request is allowed to settle
+     * but its result is discarded.
+     *
+     * `opts.onUpdate` fires once per snapshot, including
+     * intermediate `pending` ones. Errors thrown from the callback
+     * are swallowed so a misbehaving UI handler can't strand the
+     * poll loop.
+     *
+     * @throws [[KycStatusTimeoutError]] when the cadence's
+     *   `timeoutMs` elapses without a terminal status.
+     * @throws the abort reason when `opts.signal` is aborted.
+     * @throws the underlying RPC error when the contract or
+     *   transport raises (e.g. session expiry mid-poll).
+     */
+    kycStatusPoll(opts?: KycPollOptions): Promise<KycStatus>;
     /**
      * The server-minted session ID once handshake has completed, or
      * `null` beforehand (pentest M-1 / MAT-983).
@@ -1184,5 +1389,5 @@ declare function clearKeyCache(): void;
  */
 declare function loadConfig(baseUrl?: string): SdkConfig;
 
-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 };
+export { AuthMethod, AuthenticationError, ContractResponseError, DEFAULT_KYC_POLL_CADENCE, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MockTransport, NODE_URLS, RpcError, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, 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, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, Logger, OidcAuthInput, OidcCredentials, PeerQuoteResult, QuoteVerifyResult, SdkConfig, SessionCrypto, SessionId, T3nClientConfig, Transport, WasmComponent, WasmNextResult };