@terminal3/t3n-sdk 1.2.0 → 1.3.1

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

@@ -7,6 +7,7 @@
 import { T3nClientConfig } from "./config";
 import { type ContractResponseSchema } from "./contract-response";
 import { SessionId, Did, SessionStatus, AuthInput, HandshakeResult } from "../types";
+import { KycPollOptions, KycStatus } from "../types/kyc";
 /**
  * Main T3n SDK Client
  */
@@ -182,6 +183,57 @@ export 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).

package/dist/src/index.d.ts

@@ -16,6 +16,8 @@ export type { Transport, JsonRpcRequest, JsonRpcResponse } from "./client";
 export { HttpTransport, MockTransport } from "./client";
 export type { SessionId, Did, OidcCredentials, AuthInput, EthAuthInput, OidcAuthInput, GuestToHostHandler, GuestToHostHandlers, } from "./types";
 export { SessionStatus, AuthMethod, createEthAuthInput, createOidcAuthInput, } from "./types";
+export type { KycStatus, KycStatusKind, KycPollOptions, KycPollCadence, } from "./types/kyc";
+export { DEFAULT_KYC_POLL_CADENCE, TERMINAL_KYC_STATUSES, KycStatusTimeoutError, } from "./types/kyc";
 export { metamask_sign, metamask_get_address, eth_get_address, createDefaultHandlers, createMlKemPublicKeyHandler, createRandomHandler, } from "./client/handlers";
 export type { WasmComponent, ClientHandshake, ClientAuth, SessionCrypto, WasmNextResult, } from "./wasm";
 export { loadWasmComponent } from "./wasm";

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

@@ -0,0 +1,135 @@
+/**
+ * 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]].
+ */
+import { T3nError } from "../utils/errors";
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare const DEFAULT_KYC_POLL_CADENCE: KycPollCadence;
+/**
+ * Subset of [[KycStatusKind]] that ends a poll. `pending` is the
+ * only non-terminal value.
+ */
+export 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.
+ */
+export 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);
+}

package/dist/src/utils/errors.d.ts

@@ -29,12 +29,30 @@ export 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.
  */
 export 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terminal3/t3n-sdk",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "type": "module",
   "description": "T3n TypeScript SDK - A minimal SDK that mirrors the server's RPC handler approach",
   "main": "dist/index.js",
@@ -107,7 +107,8 @@
     "overrides": {
       "rollup": ">=4.59.0",
       "esbuild": ">=0.25.0",
-      "minimatch": ">=9.0.7"
+      "minimatch": ">=9.0.7",
+      "postcss": ">=8.5.10"
     }
   }
-}
+}