@terminal3/t3n-sdk 1.3.2 → 2.3.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`: