@terminal3/t3n-sdk 3.9.0 → 3.10.1

package/README.md

@@ -103,10 +103,10 @@ const did = await client.authenticate(
 
 The SDK targets the public T3n networks.
 
-- `testnet` — the public test network, for integration and pre-production use.
+- `sandbox` — the public test network, for integration and pre-production use.
 - `production` — the public mainnet network.
 
-Select the network with `setEnvironment("testnet" | "production")` — this sets the
+Select the network with `setEnvironment("sandbox" | "production")` — this sets the
 default node used by clients created afterwards. To target a specific node, pass an
 explicit `baseUrl` to `new T3nClient({ baseUrl, … })`; `baseUrl` takes precedence over
 the environment default.
@@ -156,6 +156,18 @@ try {
 For tests that "just want it to work", `runOtpThenUserInput` chains the three
 calls behind a single `getOtpCode` callback.
 
+### Email-OTP login: skip the user-layer OTP
+
+The example above is for a **wallet / OIDC** session proving an email for the
+first time. If the session instead logged in via email-OTP
+(`authenticate(createEmailOtpAuthInput(...))`), the node already proved that
+email during login and sent the only OTP code. For that email,
+`submitUserInput` passes the verified-email gate on the session authenticator
+alone and the node auto-stamps `verified_contacts.email` — so call it directly,
+with **no** `otpRequest` / `otpVerify` in between (those would send a redundant
+second OTP email). Use the user-layer OTP only to verify a contact the session
+has not already proven — a phone, or an email on a wallet/OIDC session.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1840,6 +1840,14 @@ declare class T3nClient {
      * when the node is configured with `skip_otp = true`). The next
      * step is {@link otpVerify} with the code the user typed.
      *
+     * Do NOT call this to re-verify the email a session already
+     * authenticated with via email-OTP: that email is
+     * already proven by the login authenticator, so this call only
+     * dispatches a redundant SECOND OTP email. For an email-OTP login,
+     * go straight to {@link submitUserInput}. Use `otpRequest` to
+     * verify a contact the session has NOT already proven — a phone, or
+     * an email on a wallet/OIDC session.
+     *
      * Behaviour notes:
      *
      * - Contact is a discriminated object: `emailChannel` or
@@ -1923,10 +1931,18 @@ declare class T3nClient {
      * verified email — either because {@link otpVerify} bound one or
      * because the session carries a proving authenticator (OIDC /
      * Email auth). Calls without proof are rejected with
-     * {@link UserUpsertError} `kind = "EmailNotVerified"`. The
-     * recommended UX is "request OTP -> verify OTP -> submit user
-     * input" (or use {@link runOtpThenUserInput} which chains all
-     * three).
+     * {@link UserUpsertError} `kind = "EmailNotVerified"`.
+     *
+     * Two recommended flows depending on how the session logged in:
+     * - **Email-OTP login** ({@link createEmailOtpAuthInput}): the
+     *   login already proved the email (and sent the only OTP email),
+     *   so call `submitUserInput` DIRECTLY — the gate passes on the
+     *   session authenticator and `verified_contacts.email` is
+     *   auto-stamped. Do NOT call {@link otpRequest} first; that sends
+     *   a redundant second OTP email.
+     * - **Wallet / OIDC login** (no proven email yet): "request OTP ->
+     *   verify OTP -> submit user input" (or use
+     *   {@link runOtpThenUserInput} which chains all three).
      *
      * The KYC webhook orphan-attestation flow stays here: when
      * `requireExistingUser` is set, the contract identifies the user
@@ -1956,6 +1972,14 @@ declare class T3nClient {
      * {@link otpRequest}, {@link otpVerify}, and
      * {@link submitUserInput} explicitly so the application owns the
      * flow.
+     *
+     * Do NOT use this for the email a session authenticated with via
+     * email-OTP login: it always runs {@link otpRequest},
+     * which dispatches a redundant second OTP email for an
+     * already-proven email. For an email-OTP login, call
+     * {@link submitUserInput} directly. This helper is for sessions
+     * that still need to prove the contact (phone, or an email on a
+     * wallet/OIDC session).
      */
     runOtpThenUserInput(args: {
         channel: OtpChannel;
@@ -2969,7 +2993,7 @@ declare function isObject(value: unknown): value is Record<string, unknown>;
  */
 declare function assertShape<T>(value: unknown, guard: (v: unknown) => v is T, where: string): T;
 
-type Environment = "testnet" | "production";
+type Environment = "sandbox" | "testnet" | "production";
 declare const NODE_URLS: Record<Environment, string>;
 
 /**
@@ -3137,7 +3161,7 @@ declare function clearKeyCache(): void;
  */
 declare function loadConfig(baseUrl?: string): SdkConfig;
 
-type TenantSdkEnvironment = "testnet" | "production";
+type TenantSdkEnvironment = "sandbox" | "testnet" | "production";
 
 /**
  * Minimal structural seam for the authenticated base client a TenantClient