@terminal3/t3n-sdk 1.3.1 → 1.3.2

package/README.md

@@ -560,6 +560,128 @@ When upserting a profile with an email address (either for a new profile or when
 3. Guide you through the Google OAuth flow
 4. Allow you to paste the ID token back into the terminal
 
+#### KYC Walkthrough (MAT-1371)
+
+The `--kyc-walkthrough` mode drives the full MetaMask KYC L1 + L2 flow against a running Trinity node, end-to-end, without needing the actual MetaMask front-end. It is useful for:
+
+- Smoke-testing a freshly-built node (`node/bin/start-local`) before pointing the real FE at it.
+- Reproducing edge cases (rejected KYC, OTP expiry, merge suggestions) deterministically.
+- Showing internal stakeholders what the L1 + L2 flow looks like without spinning up MetaMask Snap + Veriff sandbox.
+
+**Quick start (interactive):**
+
+```bash
+pnpm demo:real-wasm --kyc-walkthrough
+```
+
+The walkthrough then prompts at each step in the order Trinity expects:
+
+1. **Handshake** + **authenticate** (existing prompts — wallet / OIDC).
+2. **Email OTP** — request + verify on `tee:user/contracts::user-upsert` (email channel).
+3. **Phone OTP** — request + verify on the same function (SMS channel via `keys.generic_api.otp_channel: "sms"` shadow). Gated by the contract on a verified email.
+4. **Level 1 user-input** — single `user-upsert` call carrying `first_name`, `last_name`, `country_of_residence`, `document_issuance_country`, `ssn`, `address`.
+5. **`create-kyc-provider-session`** ([MAT-1284](https://linear.app/terminal3/issue/MAT-1284)) — prints the Veriff `session_url`. The CLI does **not** auto-open the URL.
+6. **`kyc-status` poll** — until terminal status (`verified`, `rejected`, or `orphan`) or the timeout fires. Each snapshot is logged.
+
+**Veriff is driven manually.** The CLI prints the `session_url` and waits — open it in your browser, drive the Veriff flow to the desired terminal state (approve / reject / abandon), then come back to the terminal. The poll loop will see the contract update and surface the terminal status.
+
+##### KYC walkthrough flags
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--kyc-walkthrough` | off | Enable the walkthrough mode. Implicitly enabled by `--scenario`. |
+| `--scenario <name>` | none | One of `happy-path-l1`, `happy-path-l2`, `rejected`. See *Scenarios* below. |
+| `--auth-method <eth\|metamask\|oidc>` | interactive prompt | Skip the auth-method prompt. |
+| `--email <addr>` | interactive prompt (or `demo+kyc@example.com` in scenario mode) | Email to verify in the L1 OTP step. |
+| `--phone <e164>` | interactive prompt (or `+14155552671` in scenario mode) | Phone in E.164 format for the SMS OTP step. |
+| `--first-name <name>` | interactive prompt (or `Ada` in scenario mode) | L1 first name. |
+| `--last-name <name>` | interactive prompt (or `Lovelace` in scenario mode) | L1 last name. |
+| `--country <ISO-2>` | `US` | Convenience: applies to both `country_of_residence` and `document_issuance_country` unless overridden individually. |
+| `--country-of-residence <ISO-2>` | `--country` value | L1 residence country. |
+| `--document-issuance-country <ISO-2>` | `--country` value | L1 document issuance country. |
+| `--ssn <value>` | interactive prompt (or `123-45-6789` in scenario mode) | L1 SSN (9 digits or `XXX-XX-XXXX`). |
+| `--address <text>` | interactive prompt (or default address in scenario mode) | L1 residential address. |
+| `--kyc-provider-id <id>` | `veriff` | Provider id passed to `create-kyc-provider-session` and `kyc-status`. |
+| `--kyc-poll-fast-ms <ms>` | `2000` | Fast-cadence poll interval (T3-TS-026 §8.4). |
+| `--kyc-poll-slow-ms <ms>` | `5000` | Slow-cadence poll interval. |
+| `--kyc-poll-switch-at-ms <ms>` | `30000` | Elapsed threshold to switch from fast to slow. |
+| `--kyc-poll-timeout-ms <ms>` | `300000` | Total cap before `KycStatusTimeoutError` is raised. |
+| `--skip-create-kyc-session` | off | Stop after L1 — useful when no Veriff sandbox is configured. |
+
+##### Scenarios
+
+Pre-baked shortcuts that auto-feed answers (mock-mode OTP codes, default L1 fields) so the walkthrough runs without operator input. All scenarios still require a running Trinity node configured with the **mock OTP provider** (otherwise the deterministic OTP code algorithm doesn't match what the node actually generated).
+
+| Scenario | What it does | Veriff |
+|---|---|---|
+| `happy-path-l1` | Email OTP → phone OTP → L1 upsert. Stops before `create-kyc-provider-session`. | Not exercised. |
+| `happy-path-l2` | Full L1 + L2 flow. Asserts `kyc-status` terminates with `verified`. | **Manual**: open the printed `session_url` and drive Veriff to approval. |
+| `rejected` | Full L1 + L2 flow. Asserts `kyc-status` terminates with `rejected`. | **Manual**: open the printed `session_url` and drive Veriff to a rejection. |
+
+Examples:
+
+```bash
+# L1-only happy path — no Veriff sandbox needed
+pnpm demo:real-wasm --scenario happy-path-l1
+
+# Full L1 + L2 happy path — drive Veriff to approved manually
+pnpm demo:real-wasm --scenario happy-path-l2
+
+# Rejection scenario — drive Veriff to a rejection manually
+pnpm demo:real-wasm --scenario rejected
+
+# Custom inputs without a scenario
+pnpm demo:real-wasm --kyc-walkthrough \
+  --auth-method eth \
+  --email me@example.com \
+  --phone +14155551234 \
+  --country US \
+  --first-name Ada --last-name Lovelace
+```
+
+##### Mock-mode OTP code
+
+When the Trinity node runs against the mock OTP provider (the default for `node/bin/start-local`), the OTP code is a **deterministic** 6-digit hash of the contact value. The walkthrough always prints the calculated mock code in the OTP-pending log line, so even without a scenario you can simply enter that code at the prompt to advance.
+
+The algorithm matches `node/wasm/src/otp.rs` byte-for-byte: `String((hash * 31 + byte_i) % 1_000_000).padStart(6, "0")` over the UTF-8 bytes of the contact (email address or E.164 phone).
+
+##### Sample output (excerpt)
+
+```text
+🚦 KYC walkthrough mode enabled (MAT-1371)
+   Scenario: happy-path-l1
+
+📧 Step 5/8 — Email OTP: demo+kyc@example.com
+5️⃣ Executing action: user-upsert...
+   ✅ Action executed successfully
+📨 Email verification required
+   📬 OTP code sent to: demo+kyc@example.com
+   📡 Channel: email
+   💡 Mock mode OTP code (deterministic): 482913
+   🤖 Scenario auto-feeding OTP code: 482913
+🔄 Verifying Email OTP code...
+5️⃣ Executing action: user-upsert...
+   ✅ OTP verified successfully
+   📝 Transaction hash: tx:1:42
+
+📱 Step 6/8 — Phone OTP: +14155552671
+6️⃣ Executing action: user-upsert...
+   ...
+
+📋 KYC walkthrough summary
+   ✅ email-otp            demo+kyc@example.com
+   ✅ phone-otp            +14155552671
+   ✅ l1-upsert            tx:1:44
+   ⏭️  create-kyc-session  (scenario)
+   ⏭️  kyc-status-poll     (scenario)
+```
+
+##### Caveats
+
+- **No version bump.** The walkthrough is dev tooling — it does not introduce new `@terminal3/t3n-sdk` public-API surface, so `package.json` is not bumped.
+- **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.
+
 ## WASM Integration
 
 The SDK can work with both real T3n WASM components and mock components for testing.

package/dist/index.d.ts

@@ -804,6 +804,14 @@ declare class KycStatusTimeoutError extends T3nError {
 declare class T3nClient {
     private readonly config;
     private readonly transport;
+    /**
+     * Resolved node base URL. Snapshotted in the constructor so the
+     * typed contract wrappers (`kycStatus`, `getSelfEthAddress`, …)
+     * can call `getScriptVersion()` against the same host the
+     * transport talks to. Used only by the `script_version: "latest"`
+     * resolution path in {@link executeUserContract}.
+     */
+    private readonly effectiveBaseUrl;
     /**
      * Server-minted session ID, set by {@link handshake} from the
      * `Session-Id` response header (pentest M-1 / MAT-983). `null`
@@ -899,6 +907,32 @@ declare class T3nClient {
      * @throws {ContractResponseError} when the response is not valid JSON
      */
     executeAndDecode<T = unknown>(payload: unknown, schema?: ContractResponseSchema<T>): Promise<T>;
+    /**
+     * Build the canonical `ExecuteActionRequest` shape the server
+     * expects in `node/primitives/src/action.rs::ExecuteActionRequest`
+     * (`script_name`, `script_version`, `function_name`, `input`,
+     * optional `pii_did`) and dispatch it through {@link execute}.
+     *
+     * Two pieces of glue live here that every typed user-contract
+     * wrapper would otherwise duplicate:
+     *
+     * 1. **Field naming.** The server deserialises strictly into
+     *    `script_name` / `script_version` / `function_name` —
+     *    sending `contract` / `version` / `function` produces
+     *    `Invalid action request: missing field …` 400s. Centralising
+     *    the names here means every wrapper agrees with the server.
+     * 2. **`"latest"` resolution.** `script_version` is `SemVer` on
+     *    the server, so a literal `"latest"` cannot be parsed. We
+     *    fetch the registered current version via
+     *    `GET /api/contracts/current?name=…` (cached per script name
+     *    in `getScriptVersion`) and forward the resolved
+     *    `MAJOR.MINOR.PATCH` string.
+     *
+     * Wrappers that need PII delegation can extend this helper
+     * later — current call sites are all SelfOnly so `pii_did` stays
+     * implicit.
+     */
+    private executeUserContract;
     /**
      * Return the authenticated user's Ethereum address from their
      * T3N-hosted per-user wallet, as a 0x-prefixed lowercase hex string.