@terminal3/t3n-sdk 3.10.0 → 3.10.1

package/README.md

@@ -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;