@upbond/sdk
    Preparing search index...

    Interface UpbondClient

    The browser client returned by createUpbond — the entire supported @upbond/sdk runtime surface. It combines the OIDC auth leg (login, session, claims) with the wallet leg (connect, unlock, sign, recovery) in either redirect or embedded mode. Read UpbondClient.state synchronously or observe it via UpbondClient.subscribe.

    interface UpbondClient {
        state: UpbondState;
        addPasscodeSealer(): Promise<void>;
        closeWallet(): void;
        connect(): Promise<string[]>;
        connectExternal(
            options: ConnectExternalOptions,
        ): Promise<ExternalWalletSession>;
        connectWallet(): Promise<
            { status: WalletStatus; walletAddress: string
            | null },
        >;
        getAccessToken(): string | null;
        getEthereumProvider(): Promise<WidgetProvider>;
        getIdToken(): string | null;
        getRecoveryStatus(): Promise<RecoveryStatus>;
        getSuiAccount(): Promise<SuiAccount>;
        getUser(): IdTokenClaims | null;
        init(): Promise<void>;
        listExternalWallets(): ExternalWalletInfo[];
        listFactors(): Promise<WalletFactor[]>;
        login(hints?: AuthorizationHints): Promise<void>;
        loginAndConnect(hints?: AuthorizationHints): Promise<string[]>;
        logout(options?: { postLogoutRedirectUri?: string }): Promise<void>;
        openWallet(view?: WalletView): Promise<void>;
        recoverWallet(): Promise<string>;
        removeFactor(factorPubHex: string): Promise<void>;
        removePasscodeSealer(): Promise<void>;
        rotateRecoveryFactor(): Promise<void>;
        setupWallet(): Promise<string>;
        signMessage(message: Uint8Array): Promise<`0x${string}`>;
        signTransaction(request: SignRequest): Promise<`0x${string}`>;
        subscribe(listener: (state: UpbondState) => void): () => void;
        unlockWallet(): Promise<string>;
        updateRecoveryContact(opts?: { channel?: "email" | "sms" }): Promise<void>;
    }
    Index
    state
    addPasscodeSealer closeWallet connect connectExternal connectWallet getAccessToken getEthereumProvider getIdToken getRecoveryStatus getSuiAccount getUser init listExternalWallets listFactors login loginAndConnect logout openWallet recoverWallet removeFactor removePasscodeSealer rotateRecoveryFactor setupWallet signMessage signTransaction subscribe unlockWallet updateRecoveryContact
    state: UpbondState

    The current client state (auth + wallet status, claims, address, phase). Always up to date.

    • Add a passcode sealer to this device's factor vault (docs/23): the same wallet afterwards unlocks via passkey OR passcode. Requires an unlocked wallet (wallet_locked otherwise); the core re-gates with a fresh user verification and collects the passcode via wallet.promptPasscode. Refused with passcode_not_allowed under a 'passkey-strict' policy.

      Returns Promise<void>

    • Hide the wallet overlay.

      Returns void

    • Connect the embedded wallet. Requires a signed-in session — call login() first (D20 A-3): the RP authenticates under its own client and the wallet-origin popup only consumes that issuer session as silent SSO (+ passkey onboarding on first use); throws not_signed_in otherwise, before opening anything. MUST be called synchronously from a user gesture (it opens the popup). Returns the connected accounts.

      Returns Promise<string[]>

    • Connect an external wallet: an EIP-6963 injected wallet (MetaMask by default) or WalletConnect v2. Returns a self-contained session exposing the wallet's own EIP-1193 provider — the UPBOND auth session and embedded/redirect wallet are unaffected. The WalletConnect connector needs wallet.walletConnectProjectId and lazy-loads its relay stack (plus QR modal) on first use.

      Parameters

      Returns Promise<ExternalWalletSession>

    • Layer 1 wallet session; also resolves needs-setup vs needs-recovery for new devices.

      Returns Promise<{ status: WalletStatus; walletAddress: string | null }>

    • The OAuth access token for the issuer's userinfo/management APIs, or null when unavailable.

      Returns string | null

    • EIP-1193 provider over the widget (ethers/viem plug in directly). Mounts the widget on first call.

      Returns Promise<WidgetProvider>

    • The raw id_token for downstream verification, or null when there is no valid session.

      Returns string | null

    • Recovery status (enrollment + masked OTP contact). Layer 1 — works right after connectWallet, no unlock.

      Returns Promise<RecoveryStatus>

    • The wallet's Sui-on-secp256k1 account (docs/00-BUILD-SPEC.md §3, issue #205 Option C) — same MPC key as the EVM address, Sui address derivation. Served from state.suiAccount when the session already captured it (zero prompts); otherwise establishes the Layer 2 ceremony, which for a locked wallet means one biometric — call from a user gesture. Throws wallet_not_set_up for a brand-new wallet.

      Returns Promise<SuiAccount>

    • The signed-in user's id_token claims, or null when signed out or the token has expired.

      Returns IdTokenClaims | null

    • Call once on page load: consumes the redirect callback (and cleans the URL) or restores a persisted session.

      Returns Promise<void>

    • The EIP-6963-announced injected wallets currently available in this browser (for install badges / wallet pickers). Announced means installed and responding. Works in every mode; never prompts the user.

      Returns ExternalWalletInfo[]

    • List the account's registered key factors (Layer 2 required — the listing runs behind a biometric).

      Returns Promise<WalletFactor[]>

    • Persists PKCE state, then navigates to the issuer. Optional hints (connection, loginHint) skip the issuer's provider chooser. Does not resolve into app code.

      Parameters

      Returns Promise<void>

    • One user click → sign-in AND wallet connect (docs/24 1.0.0). Opens a popup synchronously, runs the OIDC login under the RP's own client inside it (the registered redirectUri page loads there briefly — its init() relays the callback automatically), exchanges the code on THIS page, then the SAME popup continues into the wallet leg. Resolves with the connected accounts. Already signed in? Behaves exactly like connect.

      MUST be called synchronously from a user gesture. Concurrent calls (and concurrent connect()) share one flow.

      Error contract: unsupported_browser (in-app browser — guide the user to an external browser), popup_blocked (fall back to login()), popup_closed (the user cancelled), the auth-leg codes (authorization_error, state_mismatch, ...) if the login fails, and connect()'s codes for the wallet leg. If the login succeeded but the wallet leg failed, the session REMAINS signed in — retry with connect().

      Requires the RP pages (this one and the callback) to not sever window.opener (Cross-Origin-Opener-Policy: same-origin breaks the relay — use same-origin-allow-popups or none).

      Parameters

      Returns Promise<string[]>

    • Wallet session first (embedded mode: the widget's wallet-origin session too, via wallet_disconnect), then RP-initiated issuer logout redirect. Clears storage; keeps the device factor (B1).

      Parameters

      • Optionaloptions: { postLogoutRedirectUri?: string }

      Returns Promise<void>

    • Open the wallet overlay on a view (RP-initiated, e.g. a "wallet" button).

      Parameters

      Returns Promise<void>

    • New-device recovery: synced-passkey restore first, recoverian ceremony fallback.

      Returns Promise<string>

    • Remove a stale device factor by its public key (Layer 2 required). Recovery factors and this device's own factor are refused (factor_not_deletable).

      Parameters

      • factorPubHex: string

      Returns Promise<void>

    • Remove the passcode sealer (never the last sealer). Same unlocked-wallet contract as addPasscodeSealer.

      Returns Promise<void>

    • Rotate the recovery factor (Layer 2 required).

      Returns Promise<void>

    • First-time onboarding — the first unlock creates the wallet.

      Returns Promise<string>

    • EIP-191 personal message signature. Same ceremony semantics as signTransaction.

      Parameters

      • message: Uint8Array

      Returns Promise<`0x${string}`>

    • Signs with the session ceremony; every signature re-gates with a fresh biometric. Call from a user gesture.

      Parameters

      Returns Promise<`0x${string}`>

    • Observe state changes; returns an unsubscribe function.

      Parameters

      Returns () => void

    • Establishes the session's Layer 2 ceremony (device factor + passkey biometric) and returns the wallet address. Call from a user gesture. One ceremony per session (A2): signatures reuse it, each behind a fresh biometric; logout disposes it.

      Returns Promise<string>

    • Re-register the recovery contact from the current session's claims (recovery change → Layer 2). Requires an unlocked wallet (wallet_locked otherwise); rebinding an already-bound contact runs an OTP ceremony against the OLD contact via wallet.recovery.promptOtp.

      Parameters

      • Optionalopts: { channel?: "email" | "sms" }

      Returns Promise<void>

    Settings
    Member Visibility

    On This Page
    Properties
    Methods