@terminal3/t3n-sdk 1.3.1 → 2.1.0

package/README.md

@@ -86,6 +86,88 @@ const oidcCredentials = {
 const did = await client.authenticate(createOidcAuthInput(oidcCredentials));
 ```
 
+## Migrating from 1.x
+
+`@terminal3/t3n-sdk@2.0.0` cuts over to `tee:user/contracts@2.0.0`
+(MAT-1374). The implicit-dispatch monolith `user-upsert` on the user
+contract was split into three explicit functions on the same
+contract:
+
+- `otp-request` — request + dispatch an OTP code.
+- `otp-verify` — redeem an OTP and bind the contact.
+- `user-upsert` (slim) — Level 1 user-input ingest only. Rejects
+  callers without a verified email with the typed
+  `UserUpsertError { kind: "EmailNotVerified" }` (wire form
+  `email_not_verified:<detail>`).
+
+If you used the typed `T3nClient` methods to wrap `executeAction`,
+the SDK now ships `client.otpRequest` / `client.otpVerify` /
+`client.submitUserInput` (plus a convenience
+`client.runOtpThenUserInput`) so you can migrate one call site at a
+time:
+
+| Pre-2.0.0 (`tee:user@1.5.0`)                                                             | 2.x (`tee:user@2.0.0`, contract ≥ 2.1.0 for discriminated OTP)         |
+| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `executeAction({ function_name: "user-upsert", input: { profile: { email_address } } })` | `client.otpRequest({ emailChannel: { emailAddress } })`                |
+| `executeAction({ function_name: "user-upsert", input: { profile, otp_code } })`          | `client.otpVerify({ otpCode, request: { emailChannel: { emailAddress } } })` |
+| `executeAction({ function_name: "user-upsert", input: { profile, keys: { generic_api: { otp_channel: "sms" } } } })` | `client.otpRequest({ smsChannel: { phoneNumber } })` |
+| `executeAction({ function_name: "user-upsert", input: { profile } })` (post-OTP)         | `client.submitUserInput({ profile })`                                 |
+
+### Worked example: full email + L1 ingest
+
+```typescript
+import { T3nClient, UserUpsertError } from "@terminal3/t3n-sdk";
+
+// 1) Bind the user's email via OTP.
+const requested = await client.otpRequest({
+  emailChannel: { emailAddress: "alice@example.com" },
+});
+const code = await prompt(`Code sent to ${requested.contact}: `);
+await client.otpVerify({
+  otpCode: code,
+  request: { emailChannel: { emailAddress: "alice@example.com" } },
+});
+
+// 2) Slim user-upsert: Level 1 user-input ingest. Rejects with
+// UserUpsertError(kind: "EmailNotVerified") if step 1 was skipped.
+try {
+  const result = await client.submitUserInput({
+    profile: {
+      first_name: "Alice",
+      last_name: "Smith",
+      country_of_residence: "US",
+      // ...other Level-1 fields
+    },
+  });
+  console.log("tx:", result.txHash);
+} catch (err) {
+  if (err instanceof UserUpsertError && err.kind === "EmailNotVerified") {
+    // run otp-request + otp-verify, then retry.
+  }
+  throw err;
+}
+```
+
+For tests that "just want it to work", `runOtpThenUserInput` chains
+the three calls behind a single `getOtpCode` callback.
+
+### Hard-error fields
+
+Passing any of these to the wrong function returns the typed
+`UserUpsertError(kind: "LegacyField")` (wire form
+`legacy_field:<detail>`):
+
+- `otp_code` to anything other than `otp-verify`.
+- `keys.generic_api.otp_channel` to anything (channel is now a
+  top-level field).
+
+### Raw `executeAction` callers
+
+If you bypass the typed wrappers, see the migration table above:
+the function names (`otp-request` / `otp-verify` / `user-upsert`)
+and JSON input shapes line up 1:1 with the wrappers' camelCase
+fields converted to `snake_case`.
+
 ## Architecture
 
 The T3n SDK follows the same architectural principles as the server's `rpc.rs`:
@@ -560,6 +642,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.