@terminal3/t3n-sdk 3.10.0 → 3.11.0

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

@@ -1708,6 +1708,28 @@ declare class T3nClient {
      * @throws {ContractResponseError} when the response is not valid JSON
      */
     executeAndDecode<T = unknown>(payload: unknown, schema?: ContractResponseSchema<T>): Promise<T>;
+    /**
+     * Create a new organisation owned by the authenticated caller.
+     *
+     * Dispatches `organisation-create-self` on `tee:organisation/contracts`
+     * over the standard authenticated `action.execute` path. The node
+     * injects the caller's DID into the contract call context, and the
+     * contract forces the new organisation's sole initial admin to that
+     * caller — the caller cannot nominate a different admin, and the
+     * organisation is always created as a root. The caller must already be
+     * a registered user, and the call is metered against the caller's own
+     * credits.
+     *
+     * The returned DID is the org identifier the org-data and payroll
+     * surfaces expect (e.g. `OrgDataClient.setGrants({ orgDid, … })`).
+     *
+     * @param name - human-readable organisation name (1..=128 bytes)
+     * @returns the new organisation's DID (`did:t3n:<40-hex>`)
+     * @throws if the session is not authenticated, or if the contract
+     *   refuses (e.g. the caller is not a registered user, or the name is
+     *   empty / too long)
+     */
+    createOrganisation(name: string): Promise<Did>;
     /**
      * Build the canonical `ExecuteActionRequest` shape the server
      * expects (`script_name`, `script_version`, `function_name`, `input`,
@@ -1840,6 +1862,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 +1953,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 +1994,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;