@rhinestone/1auth 0.6.5 → 0.6.8

package/dist/index.js

@@ -199,6 +199,17 @@ var DEFAULT_EMBED_WIDTH = "400px";
 var DEFAULT_EMBED_HEIGHT = "500px";
 var DEFAULT_PROVIDER_URL = "https://passkey.1auth.box";
 var OneAuthClient = class {
+  /**
+   * Create a new OneAuthClient.
+   *
+   * Normalizes the config (filling in default URLs), then immediately injects
+   * `<link rel="preconnect">` tags for the passkey domain so that DNS lookup
+   * and TLS handshake start before the first dialog is opened, shaving
+   * noticeable latency from the first user interaction.
+   *
+   * @param config - Client configuration including optional providerUrl, dialogUrl,
+   *   clientId, theme, and redirect settings.
+   */
   constructor(config) {
     const providerUrl = config.providerUrl || DEFAULT_PROVIDER_URL;
     const dialogUrl = config.dialogUrl || providerUrl;
@@ -218,7 +229,16 @@ var OneAuthClient = class {
     this.theme = theme;
   }
   /**
-   * Build theme URL parameters
+   * Serialize the active theme into URL query parameters for the dialog.
+   *
+   * Merges the instance-level theme (set via constructor or `setTheme`) with any
+   * per-call override, so callers can temporarily change the appearance for a
+   * single dialog invocation without mutating shared state.
+   *
+   * @param overrideTheme - One-shot theme values that take precedence over the
+   *   instance theme for this call only.
+   * @returns A URL-encoded query string (e.g. `"theme=dark&accent=%230090ff"`),
+   *   or an empty string if no theme properties are set.
    */
   getThemeParams(overrideTheme) {
     const theme = { ...this.theme, ...overrideTheme };
@@ -232,15 +252,30 @@ var OneAuthClient = class {
     return params.toString();
   }
   /**
-   * Get the dialog URL (Vite app URL)
-   * Defaults to providerUrl if dialogUrl is not set
+   * Resolve the URL of the dialog app (the Vite/Next.js frontend that renders
+   * the WebAuthn UI inside the iframe).
+   *
+   * `dialogUrl` is a separate config option to support split deployments where
+   * the API server and the dialog frontend run at different origins. Falls back
+   * to `providerUrl` when not explicitly configured — the common case.
+   *
+   * @returns The base URL used when constructing all dialog endpoint paths.
    */
   getDialogUrl() {
     return this.config.dialogUrl || this.config.providerUrl;
   }
   /**
-   * Get the origin for message validation
-   * Uses dialogUrl origin if set, otherwise providerUrl origin
+   * Extract the trusted origin used to validate incoming postMessage events.
+   *
+   * All `window.addEventListener("message", ...)` handlers in this class check
+   * `event.origin` against this value to prevent cross-origin spoofing. Wraps
+   * `getDialogUrl()` in a `new URL()` parse so that paths and query strings are
+   * stripped — only the scheme + host + port are compared.
+   *
+   * Falls back to the raw dialog URL string if URL parsing fails (e.g. during
+   * unit tests with non-standard URL formats).
+   *
+   * @returns The scheme + host + optional port of the dialog app (e.g. `"https://passkey.1auth.box"`).
    */
   getDialogOrigin() {
     const dialogUrl = this.getDialogUrl();
@@ -262,6 +297,24 @@ var OneAuthClient = class {
   getClientId() {
     return this.config.clientId;
   }
+  /**
+   * Poll the intent status endpoint until a transaction hash appears or the
+   * intent reaches a terminal failure state.
+   *
+   * This is used after `sendIntent` resolves (with `waitForHash: true`) to
+   * continue waiting for the on-chain hash even after the dialog has been
+   * dismissed. It is intentionally separate from the in-dialog polling loop so
+   * callers that don't need the hash can skip it entirely.
+   *
+   * Errors during individual poll attempts are swallowed so that transient
+   * network issues don't abort the wait prematurely.
+   *
+   * @param intentId - The Rhinestone intent ID returned by the execute endpoint.
+   * @param options.timeoutMs - Maximum wait time in milliseconds (default 120 000).
+   * @param options.intervalMs - Time between polls in milliseconds (default 2 000).
+   * @returns The transaction hash string, or `undefined` if the deadline was
+   *   reached or the intent failed/expired before a hash was produced.
+   */
   async waitForTransactionHash(intentId, options = {}) {
     const timeoutMs = options.timeoutMs ?? 12e4;
     const intervalMs = options.intervalMs ?? 2e3;
@@ -667,25 +720,7 @@ var OneAuthClient = class {
    * ```
    */
   async sendIntent(options) {
-    const signedIntent = options.signedIntent ? {
-      ...options.signedIntent,
-      merchantId: options.signedIntent.merchantId || options.signedIntent.developerId
-    } : void 0;
-    const username = signedIntent?.username || options.username;
-    const targetChain = signedIntent?.targetChain || options.targetChain;
-    const calls = signedIntent?.calls || options.calls;
-    if (signedIntent && !signedIntent.merchantId) {
-      return {
-        success: false,
-        intentId: "",
-        status: "failed",
-        error: {
-          code: "INVALID_OPTIONS",
-          message: "Signed intent requires developerId (clientId)"
-        }
-      };
-    }
-    const accountAddress = signedIntent?.accountAddress || options.accountAddress;
+    const { username, accountAddress, targetChain, calls } = options;
     if (!username && !accountAddress) {
       return {
         success: false,
@@ -693,7 +728,7 @@ var OneAuthClient = class {
         status: "failed",
         error: {
           code: "INVALID_OPTIONS",
-          message: "Either username, accountAddress, or signedIntent with user identifier is required"
+          message: "Either username or accountAddress is required"
         }
       };
     }
@@ -704,7 +739,7 @@ var OneAuthClient = class {
         status: "failed",
         error: {
           code: "INVALID_OPTIONS",
-          message: "targetChain and calls are required (either directly or via signedIntent)"
+          message: "targetChain and calls are required"
         }
       };
     }
@@ -713,11 +748,11 @@ var OneAuthClient = class {
       amount: r.amount.toString()
     }));
     let prepareResponse;
-    const requestBody = signedIntent || {
-      username: options.username,
-      accountAddress: options.accountAddress,
-      targetChain: options.targetChain,
-      calls: options.calls,
+    const requestBody = {
+      username,
+      accountAddress,
+      targetChain,
+      calls,
       tokenRequests: serializedTokenRequests,
       sourceAssets: options.sourceAssets,
       sourceChainId: options.sourceChainId,
@@ -833,7 +868,6 @@ var OneAuthClient = class {
       dialogOrigin,
       // Refresh callback - called when dialog requests a quote refresh
       async () => {
-        console.log("[SDK] Dialog requested quote refresh, re-preparing intent");
         try {
           const refreshResponse = await fetch(`${this.config.providerUrl}/api/intent/prepare`, {
             method: "POST",
@@ -1215,7 +1249,6 @@ var OneAuthClient = class {
         if (event.origin !== dialogOrigin) return;
         const message = event.data;
         if (message?.type === "PASSKEY_REFRESH_QUOTE") {
-          console.log("[SDK] Batch dialog requested quote refresh, re-preparing all intents");
           try {
             const refreshResponse = await fetch(`${this.config.providerUrl}/api/intent/batch-prepare`, {
               method: "POST",
@@ -1313,7 +1346,22 @@ var OneAuthClient = class {
     );
   }
   /**
-   * Wait for the signing result without closing the modal
+   * Listen for a signing result that belongs to a specific `requestId`.
+   *
+   * Used by legacy server-side signing request flows (popup/embed/modal) where
+   * the dialog was pre-loaded with a signing request created via the API. The
+   * `requestId` filter is needed because multiple dialogs may be open or there
+   * may be stale messages from a previous dialog in the queue.
+   *
+   * Resolves on `PASSKEY_SIGNING_RESULT` matching `requestId`, or on
+   * `PASSKEY_CLOSE` (user dismissed the dialog).
+   *
+   * @param requestId - The signing request ID to match against incoming messages.
+   * @param dialog - The `<dialog>` element (opened before this call) used to
+   *   `showModal()` so the dialog becomes interactive.
+   * @param _iframe - Unused; kept for signature consistency with other wait helpers.
+   * @param cleanup - Idempotent teardown function that closes and removes the dialog.
+   * @returns A `SigningResult` discriminated union.
    */
   waitForIntentSigningResponse(requestId, dialog, _iframe, cleanup) {
     const dialogOrigin = this.getDialogOrigin();
@@ -1358,18 +1406,30 @@ var OneAuthClient = class {
     });
   }
   /**
-   * Wait for signing result (simplified - no requestId matching)
+   * Listen for a signing result from the currently open modal dialog.
+   *
+   * Unlike `waitForIntentSigningResponse`, this variant does not filter by
+   * `requestId` because the inline intent flow (sendIntent / signMessage /
+   * signTypedData) owns the dialog exclusively — there is no risk of collisions
+   * from other dialogs.
+   *
+   * Handles two result shapes:
+   *   - New "secure flow": dialog executed the intent server-side and returns
+   *     only an `intentId` (no signature exposed to the SDK).
+   *   - Legacy flow: dialog returns a raw `WebAuthnSignature` for the SDK to
+   *     forward to the execute endpoint.
+   *
+   * @param dialog - The `<dialog>` element wrapping the signing iframe.
+   * @param _iframe - Unused; kept for signature consistency with other wait helpers.
+   * @param cleanup - Idempotent teardown that closes and removes the dialog.
+   * @returns A `SigningResult` extended with an optional `signedHash` field
+   *   populated when the dialog performs message signing.
    */
   waitForSigningResponse(dialog, _iframe, cleanup) {
     const dialogOrigin = this.getDialogOrigin();
-    console.log("[SDK] waitForSigningResponse, expecting origin:", dialogOrigin);
     return new Promise((resolve) => {
       const handleMessage = (event) => {
-        console.log("[SDK] Received message:", event.origin, event.data?.type);
-        if (event.origin !== dialogOrigin) {
-          console.log("[SDK] Origin mismatch, ignoring. Expected:", dialogOrigin, "Got:", event.origin);
-          return;
-        }
+        if (event.origin !== dialogOrigin) return;
         const message = event.data;
         const payload = message?.data;
         if (message?.type === "PASSKEY_SIGNING_RESULT") {
@@ -1411,17 +1471,34 @@ var OneAuthClient = class {
     });
   }
   /**
-   * Wait for signing result with auto-refresh support
-   * This method handles both signing results and quote refresh requests from the dialog
+   * Listen for a signing result while also handling quote-refresh requests.
+   *
+   * Quotes from the Rhinestone orchestrator have a short TTL (typically ~60 s).
+   * When the user takes too long to review and the quote expires, the dialog
+   * sends `PASSKEY_REFRESH_QUOTE`. This method intercepts that message, calls
+   * the provided `onRefresh` callback to fetch a new quote, and replies with
+   * either `PASSKEY_REFRESH_COMPLETE` (success) or `PASSKEY_REFRESH_ERROR`
+   * (failure) — allowing the dialog to stay open and show the updated fees
+   * without requiring a full restart.
+   *
+   * Once the user confirms or rejects, the promise resolves with the signing
+   * result exactly as `waitForSigningResponse` would.
+   *
+   * @param dialog - The `<dialog>` element wrapping the signing iframe.
+   * @param iframe - The iframe element; used to post refresh messages back.
+   * @param cleanup - Idempotent teardown that closes and removes the dialog.
+   * @param dialogOrigin - Trusted origin for message validation (passed in to
+   *   avoid redundant `getDialogOrigin()` calls from the hot path).
+   * @param onRefresh - Async callback that fetches a fresh quote and returns the
+   *   updated intent fields, or `null` if the refresh failed.
+   * @returns A `SigningResult` extended with an optional `signedHash`.
    */
   waitForSigningWithRefresh(dialog, iframe, cleanup, dialogOrigin, onRefresh) {
-    console.log("[SDK] waitForSigningWithRefresh, expecting origin:", dialogOrigin);
     return new Promise((resolve) => {
       const handleMessage = async (event) => {
         if (event.origin !== dialogOrigin) return;
         const message = event.data;
         if (message?.type === "PASSKEY_REFRESH_QUOTE") {
-          console.log("[SDK] Received quote refresh request from dialog");
           const refreshedData = await onRefresh();
           if (refreshedData) {
             iframe.contentWindow?.postMessage({
@@ -1476,7 +1553,20 @@ var OneAuthClient = class {
     });
   }
   /**
-   * Wait for the dialog to be closed
+   * Wait for the dialog to be explicitly closed by the user or the iframe.
+   *
+   * Resolves on either:
+   *   - `PASSKEY_CLOSE` postMessage from the iframe (user clicked the X button
+   *     or the dialog programmatically closed itself after showing a result).
+   *   - The native `<dialog> close` event (escape key or `dialog.close()` call).
+   *
+   * Calling `cleanup()` before awaiting this is safe — both resolution paths
+   * call `cleanup()` internally but it is idempotent. The primary use case is
+   * keeping the dialog open while the SDK polls for a transaction hash, then
+   * showing the final success/error state before letting the user dismiss.
+   *
+   * @param dialog - The `<dialog>` element to watch.
+   * @param cleanup - Idempotent teardown that closes and removes the dialog.
    */
   waitForDialogClose(dialog, cleanup) {
     const dialogOrigin = this.getDialogOrigin();
@@ -1500,7 +1590,17 @@ var OneAuthClient = class {
     });
   }
   /**
-   * Inject a preconnect link tag to pre-warm DNS + TLS for a given URL.
+   * Inject a `<link rel="preconnect">` tag for the given URL's origin.
+   *
+   * Browsers use preconnect hints to resolve DNS, perform the TCP handshake,
+   * and negotiate TLS before a resource is actually requested, reducing
+   * time-to-first-byte when the dialog iframe loads. The tag is deduplicated —
+   * if one already exists for the same origin it will not be added again.
+   *
+   * Only called in browser environments (guarded by `typeof document` in the
+   * constructor). Invalid URLs are silently ignored.
+   *
+   * @param url - Any URL whose origin should be preconnected to.
    */
   injectPreconnect(url) {
     try {
@@ -1515,8 +1615,24 @@ var OneAuthClient = class {
     }
   }
   /**
-   * Wait for the dialog iframe to signal ready without sending init data.
-   * Returns a sendInit function the caller uses once prepare data is available.
+   * Wait for the dialog iframe to signal ready, but defer sending `PASSKEY_INIT`
+   * until the caller decides the time is right.
+   *
+   * This is the deferred variant of `waitForDialogReady`, used by flows that run
+   * the dialog and a background API call in parallel (the "two-phase" approach).
+   * Rather than blocking until both the iframe is ready AND the API call is done,
+   * this method resolves as soon as `PASSKEY_READY` arrives and returns a
+   * `sendInit` callback. The caller invokes `sendInit` once prepare data is
+   * available, which may happen before or after the iframe is ready.
+   *
+   * Timeout: if the iframe never signals ready within 10 seconds (e.g. network
+   * error, origin mismatch), resolves with `{ ready: false }` and calls cleanup.
+   *
+   * @param dialog - The `<dialog>` element wrapping the iframe.
+   * @param iframe - The iframe element that will receive `PASSKEY_INIT`.
+   * @param cleanup - Idempotent teardown that closes and removes the dialog.
+   * @returns `{ ready: true, sendInit }` when the iframe is ready, or
+   *   `{ ready: false }` if the dialog was closed or timed out first.
    */
   waitForDialogReadyDeferred(dialog, iframe, cleanup) {
     const dialogOrigin = this.getDialogOrigin();
@@ -1562,8 +1678,23 @@ var OneAuthClient = class {
     });
   }
   /**
-   * Prepare an intent by calling the orchestrator for a quote.
-   * Returns the prepare response and the origin tier from the response header.
+   * Call the passkey service to obtain a Rhinestone orchestrator quote for an
+   * intent (a single target-chain transaction or swap).
+   *
+   * The service contacts the Rhinestone orchestrator, which returns a signed
+   * `intentOp` structure containing the quote, fees, and a WebAuthn challenge
+   * the user must sign to authorize execution.
+   *
+   * The `X-Origin-Tier` response header is forwarded to the dialog so it can
+   * display tier-specific UI (e.g. "Free" vs "Premium" badge).
+   *
+   * Side effect: if the server returns "User not found", the cached user entry
+   * is removed from `localStorage` to force re-authentication.
+   *
+   * @param requestBody - Serialized intent options (bigint amounts converted to
+   *   strings before this call).
+   * @returns On success: `{ success: true, data: PrepareIntentResponse, tier }`.
+   *   On failure: `{ success: false, error: { code, message } }`.
    */
   async prepareIntent(requestBody) {
     try {
@@ -1599,7 +1730,21 @@ var OneAuthClient = class {
     }
   }
   /**
-   * Prepare a batch intent by calling the orchestrator for quotes on all intents.
+   * Call the passkey service to obtain orchestrator quotes for all intents in a
+   * batch, returning a single shared WebAuthn challenge.
+   *
+   * The service prepares each intent independently and assembles a merkle tree
+   * whose root becomes the challenge. Signing that root once authorizes every
+   * intent in the batch. Partially-failed batches are supported: the response
+   * includes both `intents` (succeeded) and `failedIntents` (per-intent errors),
+   * so the dialog can still show the successful subset for signing.
+   *
+   * Side effect: same "User not found" localStorage cleanup as `prepareIntent`.
+   *
+   * @param requestBody - Serialized batch options (bigint amounts converted to
+   *   strings before this call).
+   * @returns On success: `{ success: true, data: PrepareBatchIntentResponse, tier }`.
+   *   On failure: `{ success: false, error, failedIntents? }`.
    */
   async prepareBatchIntent(requestBody) {
     try {
@@ -1627,7 +1772,15 @@ var OneAuthClient = class {
     }
   }
   /**
-   * Send a prepare error message to the dialog iframe.
+   * Forward a prepare-phase error to the dialog iframe so it can display a
+   * human-readable failure message instead of hanging on the loading state.
+   *
+   * The dialog listens for `PASSKEY_PREPARE_ERROR` and transitions to an error
+   * view. The user can then dismiss the dialog, at which point
+   * `waitForDialogClose` resolves and the SDK returns the error to the caller.
+   *
+   * @param iframe - The iframe element to post the error to.
+   * @param error - Human-readable error message from the prepare response.
    */
   sendPrepareError(iframe, error) {
     const dialogOrigin = this.getDialogOrigin();
@@ -1810,13 +1963,6 @@ var OneAuthClient = class {
       };
     }
     const toTokenAddress = toTokenResult.address;
-    console.log("[SDK sendSwap] Token resolution:", {
-      fromToken: options.fromToken ?? "Any",
-      fromTokenAddress: fromTokenAddress ?? "orchestrator picks",
-      toToken: options.toToken,
-      toTokenAddress,
-      targetChain: options.targetChain
-    });
     const formatTokenLabel = (token, fallback) => {
       if (!token.startsWith("0x")) {
         return token;
@@ -1845,16 +1991,10 @@ var OneAuthClient = class {
         const match = getSupportedTokens(chainId).find(
           (t) => t.symbol.toUpperCase() === symbol.toUpperCase()
         );
-        if (match) {
-          console.log(`[SDK] getTokenDecimals(${match.symbol}, ${chainId}) = ${match.decimals}`);
-          return match.decimals;
-        }
-        const decimals = (0, import_sdk.getTokenDecimals)(symbol, chainId);
-        console.log(`[SDK] getTokenDecimals(${symbol}, ${chainId}) = ${decimals}`);
-        return decimals;
-      } catch (e) {
+        if (match) return match.decimals;
+        return (0, import_sdk.getTokenDecimals)(symbol, chainId);
+      } catch {
         const upperSymbol = symbol.toUpperCase();
-        console.warn(`[SDK] getTokenDecimals failed for ${symbol}, using fallback`, e);
         return KNOWN_DECIMALS[upperSymbol] ?? 18;
       }
     };
@@ -1864,13 +2004,6 @@ var OneAuthClient = class {
       token: toTokenAddress,
       amount: (0, import_viem2.parseUnits)(options.amount, toDecimals)
     }];
-    console.log("[SDK sendSwap] Building intent:", {
-      isBridge,
-      isFromNativeEth,
-      isToNativeEth,
-      toDecimals,
-      tokenRequests
-    });
     const result = await this.sendIntent({
       username: options.username,
       targetChain: options.targetChain,
@@ -2131,6 +2264,20 @@ var OneAuthClient = class {
     const iframe = this.createEmbed(request.requestId, embedOptions);
     return this.waitForEmbedResponse(request.requestId, iframe, embedOptions);
   }
+  /**
+   * Create and append a signing iframe to a caller-supplied container element.
+   *
+   * Used by the `signWithEmbed` flow where the integrator wants the signing UI
+   * to appear inline on their page rather than in a modal overlay. The iframe
+   * loads a pre-created signing request URL and fires `options.onReady` once
+   * the page has loaded.
+   *
+   * @param requestId - The signing request ID; used to construct the iframe src
+   *   and give it a stable DOM id for later removal via `removeEmbed`.
+   * @param options - Embed configuration including the container element,
+   *   optional dimensions, and lifecycle callbacks.
+   * @returns The created `<iframe>` element (already appended to the container).
+   */
   createEmbed(requestId, options) {
     const dialogUrl = this.getDialogUrl();
     const iframe = document.createElement("iframe");
@@ -2148,6 +2295,19 @@ var OneAuthClient = class {
     options.container.appendChild(iframe);
     return iframe;
   }
+  /**
+   * Listen for a signing result from an embedded (inline) signing iframe.
+   *
+   * Matches incoming `PASSKEY_SIGNING_RESULT` messages against `requestId`
+   * to avoid reacting to messages from other iframes on the page. On resolution
+   * (success or failure), the iframe is removed from the DOM and
+   * `embedOptions.onClose` is invoked.
+   *
+   * @param requestId - The signing request ID to match against incoming messages.
+   * @param iframe - The embedded signing iframe.
+   * @param embedOptions - Embed configuration; `onClose` is called after cleanup.
+   * @returns A `SigningResult` discriminated union.
+   */
   waitForEmbedResponse(requestId, iframe, embedOptions) {
     const dialogOrigin = this.getDialogOrigin();
     return new Promise((resolve) => {
@@ -2242,6 +2402,22 @@ var OneAuthClient = class {
     const data = await response.json();
     return data.passkeys;
   }
+  /**
+   * Register a signing request with the passkey service and receive a
+   * short-lived `requestId`.
+   *
+   * Used by the legacy popup, redirect, and embed flows. The passkey service
+   * stores the challenge and metadata server-side so the dialog page can fetch
+   * them by `requestId` without relying on URL parameters alone. This avoids
+   * exposing potentially large challenge payloads in query strings.
+   *
+   * @param options - The signing options (challenge, username, description, etc.).
+   * @param mode - How the dialog will be opened (`"popup"`, `"redirect"`, or `"embed"`).
+   * @param redirectUrl - Only required for `"redirect"` mode; the URL the dialog
+   *   will navigate back to after signing.
+   * @returns The created signing request with its unique `requestId`.
+   * @throws If the API call fails.
+   */
   async createSigningRequest(options, mode, redirectUrl) {
     const response = await fetch(
       `${this.config.providerUrl}/api/sign/request`,
@@ -2268,6 +2444,17 @@ var OneAuthClient = class {
     }
     return response.json();
   }
+  /**
+   * Open a centered popup window for the signing or auth dialog.
+   *
+   * Positions the popup near the top of the current window (50px from the top)
+   * and horizontally centered relative to the browser window. Uses `popup=true`
+   * to request a minimal chrome popup (no address bar) on browsers that support
+   * the Window Management API.
+   *
+   * @param url - The full URL to open in the popup.
+   * @returns The popup `Window` reference, or `null` if the browser blocked it.
+   */
   openPopup(url) {
     const left = window.screenX + (window.outerWidth - POPUP_WIDTH) / 2;
     const top = window.screenY + 50;
@@ -2278,9 +2465,24 @@ var OneAuthClient = class {
     );
   }
   /**
-   * Wait for the dialog iframe to signal ready, then send init data.
-   * Also handles early close (X button, escape, backdrop) during the ready phase.
-   * Returns true if dialog is ready, false if it was closed before becoming ready.
+   * Wait for the dialog iframe to signal ready, then immediately send init data.
+   *
+   * This is the synchronous-init variant: `initMessage` is available at call
+   * time, so it can be posted as soon as `PASSKEY_READY` arrives. Use
+   * `waitForDialogReadyDeferred` when init data depends on an in-flight API call.
+   *
+   * Also handles early close (X button, escape key, backdrop click) during the
+   * ready phase so those paths resolve cleanly without leaking event listeners.
+   *
+   * Timeout: resolves `false` after 10 seconds if the iframe never signals ready
+   * (e.g. origin mismatch or network error loading the dialog app).
+   *
+   * @param dialog - The `<dialog>` element wrapping the iframe.
+   * @param iframe - The iframe element that will receive `PASSKEY_INIT`.
+   * @param cleanup - Idempotent teardown that closes and removes the dialog.
+   * @param initMessage - The `PASSKEY_INIT` payload to send when ready.
+   * @returns `true` if the dialog is ready and init was sent; `false` if the
+   *   dialog was closed or timed out before becoming ready.
    */
   waitForDialogReady(dialog, iframe, cleanup, initMessage) {
     const dialogOrigin = this.getDialogOrigin();
@@ -2323,10 +2525,33 @@ var OneAuthClient = class {
     });
   }
   /**
-   * Create a modal dialog with a full-viewport iframe inside.
-   * All visual chrome (backdrop, positioning, animations) is rendered
-   * by the passkey app inside the iframe — the SDK just provides
-   * a transparent full-screen container.
+   * Create and open a full-viewport `<dialog>` containing a passkey iframe.
+   *
+   * The SDK owns only the transparent outer shell; all visible UI (backdrop,
+   * card, animations, close button) is rendered by the passkey app inside the
+   * iframe. This approach means design changes can be shipped server-side
+   * without updating SDK consumers.
+   *
+   * Lifecycle:
+   *   1. A themed "Loading…" overlay is injected and shown immediately while the
+   *      iframe loads, matching the exact visual structure of the passkey app's
+   *      TitleBar + IndeterminateLoader so the transition is seamless.
+   *   2. When the iframe sends `PASSKEY_RENDERED`, the overlay fades out and
+   *      the iframe becomes fully visible.
+   *   3. The returned `cleanup` function tears down all event listeners,
+   *      disconnects the MutationObserver, closes the `<dialog>`, and removes
+   *      it from the DOM. It is idempotent — safe to call multiple times.
+   *
+   * Browser quirks handled:
+   *   - The 1Password extension sets `inert` on the `<dialog>`, making it
+   *     non-interactive. A MutationObserver removes the attribute immediately.
+   *   - Password managers may also set `inert` on dialog siblings; cleanup
+   *     restores those as well.
+   *   - The iframe sandbox includes `allow-popups-to-escape-sandbox` so that
+   *     1Password's popup UI can render outside the sandboxed context.
+   *
+   * @param url - The full URL (including query params) to load in the iframe.
+   * @returns References to the dialog, iframe, and a cleanup function.
    */
   createModalDialog(url) {
     const dialogUrl = this.getDialogUrl();
@@ -2524,6 +2749,24 @@ var OneAuthClient = class {
     };
     return { dialog, iframe, cleanup };
   }
+  /**
+   * Listen for the auth result from the modal dialog.
+   *
+   * Waits for `PASSKEY_READY` before processing any other messages to avoid
+   * acting on stale `PASSKEY_CLOSE` events that may still be in the event queue
+   * from a previously closed dialog.
+   *
+   * Also handles the `PASSKEY_RETRY_POPUP` message: sent by the dialog when a
+   * password manager (e.g. Bitwarden) intercepts the WebAuthn call inside the
+   * iframe. In that case the SDK seamlessly re-opens a standalone popup window,
+   * where WebAuthn works without cross-origin iframe restrictions, and waits
+   * for the result from there instead.
+   *
+   * @param _dialog - Unused; kept for signature consistency.
+   * @param iframe - The iframe element; used to send `PASSKEY_INIT` on ready.
+   * @param cleanup - Idempotent teardown for the modal dialog.
+   * @returns An `AuthResult` discriminated union.
+   */
   waitForModalAuthResponse(_dialog, iframe, cleanup) {
     const dialogOrigin = this.getDialogOrigin();
     return new Promise((resolve) => {
@@ -2640,6 +2883,20 @@ var OneAuthClient = class {
       window.addEventListener("message", handleMessage);
     });
   }
+  /**
+   * Listen for the authenticate result from the modal dialog.
+   *
+   * The authenticate flow combines sign-in/sign-up with optional off-chain
+   * challenge signing. The dialog sends `PASSKEY_AUTHENTICATE_RESULT` on
+   * completion with both user details and, if a challenge was requested, the
+   * WebAuthn signature and the hashed challenge value for server-side
+   * verification.
+   *
+   * @param _dialog - Unused; kept for signature consistency.
+   * @param _iframe - Unused; kept for signature consistency.
+   * @param cleanup - Idempotent teardown for the modal dialog.
+   * @returns An `AuthenticateResult` discriminated union.
+   */
   waitForAuthenticateResponse(_dialog, _iframe, cleanup) {
     const dialogOrigin = this.getDialogOrigin();
     return new Promise((resolve) => {
@@ -2683,6 +2940,22 @@ var OneAuthClient = class {
       window.addEventListener("message", handleMessage);
     });
   }
+  /**
+   * Listen for the connect result from the connect dialog.
+   *
+   * The connect flow is a lightweight "are you still you?" confirmation that
+   * does not require a new passkey ceremony. On success, the dialog returns the
+   * user's username, address, and an `autoConnected` flag indicating whether the
+   * user had previously enabled auto-connect (in which case no UI was shown).
+   *
+   * On failure with `action: "switch"`, the caller should redirect to the full
+   * auth flow because the user has no cached session to confirm.
+   *
+   * @param _dialog - Unused; kept for signature consistency.
+   * @param _iframe - Unused; kept for signature consistency.
+   * @param cleanup - Idempotent teardown for the modal dialog.
+   * @returns A `ConnectResult` discriminated union.
+   */
   waitForConnectResponse(_dialog, _iframe, cleanup) {
     const dialogOrigin = this.getDialogOrigin();
     return new Promise((resolve) => {
@@ -2724,6 +2997,23 @@ var OneAuthClient = class {
       window.addEventListener("message", handleMessage);
     });
   }
+  /**
+   * Listen for the consent result from the consent dialog.
+   *
+   * The consent dialog shows the user which data fields an app is requesting
+   * access to and lets them approve or deny. On approval, `data` contains the
+   * consented field values (e.g. email address, device names) and `grantedAt`
+   * records when consent was given.
+   *
+   * A `PASSKEY_CLOSE` without a prior `PASSKEY_CONSENT_RESULT` is treated as an
+   * explicit user cancellation (distinct from denial, though both yield
+   * `success: false`).
+   *
+   * @param _dialog - Unused; kept for signature consistency.
+   * @param _iframe - Unused; kept for signature consistency.
+   * @param cleanup - Idempotent teardown for the modal dialog.
+   * @returns A `RequestConsentResult` discriminated union.
+   */
   waitForConsentResponse(_dialog, _iframe, cleanup) {
     const dialogOrigin = this.getDialogOrigin();
     return new Promise((resolve) => {
@@ -2763,6 +3053,20 @@ var OneAuthClient = class {
       window.addEventListener("message", handleMessage);
     });
   }
+  /**
+   * Listen for a signing result from a server-request-based modal dialog.
+   *
+   * Similar to `waitForIntentSigningResponse` but intended for the older
+   * `signWithModal` path that pre-creates a signing request via the API (rather
+   * than inlining all data in `PASSKEY_INIT`). Filters by `requestId` to handle
+   * the case where stale messages from a previous dialog may still be in flight.
+   *
+   * @param requestId - The signing request ID to match against incoming messages.
+   * @param _dialog - Unused; kept for signature consistency.
+   * @param _iframe - Unused; kept for signature consistency.
+   * @param cleanup - Idempotent teardown that closes and removes the dialog.
+   * @returns A `SigningResult` discriminated union.
+   */
   waitForModalSigningResponse(requestId, _dialog, _iframe, cleanup) {
     const dialogOrigin = this.getDialogOrigin();
     return new Promise((resolve) => {
@@ -2802,6 +3106,21 @@ var OneAuthClient = class {
       window.addEventListener("message", handleMessage);
     });
   }
+  /**
+   * Listen for a signing result from a popup window.
+   *
+   * Polls for popup closure every 500 ms as a fallback to detect when the user
+   * closes the popup without completing the signing flow (no `PASSKEY_CLOSE`
+   * message is fired in that case because the popup's unload event cannot
+   * reliably postMessage to the opener on all browsers).
+   *
+   * On success or cancellation, the popup is programmatically closed and the
+   * interval is cleared.
+   *
+   * @param requestId - The signing request ID to match against incoming messages.
+   * @param popup - The popup `Window` reference returned by `openPopup`.
+   * @returns A `SigningResult` discriminated union.
+   */
   waitForPopupResponse(requestId, popup) {
     const dialogOrigin = this.getDialogOrigin();
     return new Promise((resolve) => {
@@ -2847,6 +3166,17 @@ var OneAuthClient = class {
       window.addEventListener("message", handleMessage);
     });
   }
+  /**
+   * Fetch the completed signing result from the passkey service by request ID.
+   *
+   * Used by the redirect flow: after the passkey service redirects back to
+   * `redirectUrl`, the integrator calls `handleRedirectCallback()`, which
+   * extracts `requestId` from the URL query params and delegates here to
+   * retrieve the full signature from the server.
+   *
+   * @param requestId - The signing request ID from the redirect callback URL.
+   * @returns A `SigningResult` discriminated union.
+   */
   async fetchSigningResult(requestId) {
     const response = await fetch(
       `${this.config.providerUrl}/api/sign/request/${requestId}`,
@@ -3132,31 +3462,16 @@ function createOneAuthProvider(options) {
     }
     return encodeWebAuthnSignature(result.signature);
   };
-  const resolveIntentPayload = async (payload) => {
-    if (!options.signIntent) {
-      return {
-        username: payload.username,
-        accountAddress: payload.accountAddress,
-        targetChain: payload.targetChain,
-        calls: payload.calls,
-        tokenRequests: payload.tokenRequests
-      };
-    }
-    if (!payload.username) {
-      throw new Error("Username required for signed intents. Set a username first.");
-    }
-    const signedIntent = await options.signIntent({
-      username: payload.username,
-      accountAddress: payload.accountAddress,
-      targetChain: payload.targetChain,
-      calls: payload.calls,
-      tokenRequests: payload.tokenRequests
-    });
-    return { signedIntent };
-  };
+  const resolveIntentPayload = (payload) => ({
+    username: payload.username,
+    accountAddress: payload.accountAddress,
+    targetChain: payload.targetChain,
+    calls: payload.calls,
+    tokenRequests: payload.tokenRequests
+  });
   const sendIntent = async (payload) => {
     const closeOn = options.closeOn ?? (options.waitForHash ?? true ? "completed" : "preconfirmed");
-    const intentPayload = await resolveIntentPayload(payload);
+    const intentPayload = resolveIntentPayload(payload);
     const result = await client.sendIntent({
       ...intentPayload,
       tokenRequests: payload.tokenRequests,
@@ -3317,6 +3632,7 @@ function createOneAuthProvider(options) {
           receipts: data.transactionHash ? [
             {
               logs: [],
+              // 0x1 = success, 0x0 = reverted/failed — mirrors EVM receipt status
               status: data.status === "completed" ? "0x1" : "0x0",
               blockHash: data.blockHash,
               blockNumber: data.blockNumber,
@@ -3430,6 +3746,7 @@ function createPasskeyAccount(client, params) {
       const domain = {
         name: domainInput.name,
         version: domainInput.version,
+        // viem uses bigint for chainId in typed data; the passkey service expects number
         chainId: typeof domainInput.chainId === "bigint" ? Number(domainInput.chainId) : domainInput.chainId,
         verifyingContract: domainInput.verifyingContract,
         salt: domainInput.salt
@@ -3464,6 +3781,7 @@ function createPasskeyAccount(client, params) {
 var import_viem6 = require("viem");
 var import_accounts2 = require("viem/accounts");
 function createPasskeyWalletClient(config) {
+  const resolvedUsername = config.username ?? config.accountAddress;
   const provider = new OneAuthClient({
     providerUrl: config.providerUrl,
     clientId: config.clientId,
@@ -3473,7 +3791,7 @@ function createPasskeyWalletClient(config) {
     const hash = (0, import_viem6.hashMessage)(message);
     const result = await provider.signWithModal({
       challenge: hash,
-      username: config.username,
+      username: resolvedUsername,
       description: "Sign message",
       transaction: {
         actions: [
@@ -3504,7 +3822,7 @@ function createPasskeyWalletClient(config) {
     const hash = hashCalls(calls);
     const result = await provider.signWithModal({
       challenge: hash,
-      username: config.username,
+      username: resolvedUsername,
       description: "Sign transaction",
       transaction: buildTransactionReview(calls)
     });
@@ -3520,7 +3838,7 @@ function createPasskeyWalletClient(config) {
     const hash = (0, import_viem6.hashTypedData)(typedData);
     const result = await provider.signWithModal({
       challenge: hash,
-      username: config.username,
+      username: resolvedUsername,
       description: "Sign typed data",
       transaction: {
         actions: [
@@ -3540,7 +3858,7 @@ function createPasskeyWalletClient(config) {
     }
     return encodeWebAuthnSignature(result.signature);
   };
-  const buildIntentPayload = async (calls, targetChainOverride) => {
+  const buildIntentPayload = async (calls, targetChainOverride, extra) => {
     const targetChain = targetChainOverride ?? config.chain.id;
     const intentCalls = calls.map((call) => ({
       to: call.to,
@@ -3549,17 +3867,9 @@ function createPasskeyWalletClient(config) {
       label: call.label,
       sublabel: call.sublabel
     }));
-    if (config.signIntent) {
-      const signedIntent = await config.signIntent({
-        username: config.username,
-        accountAddress: config.accountAddress,
-        targetChain,
-        calls: intentCalls
-      });
-      return { signedIntent };
-    }
     return {
-      username: config.username,
+      username: resolvedUsername,
+      accountAddress: config.accountAddress,
       targetChain,
       calls: intentCalls
     };
@@ -3606,12 +3916,14 @@ function createPasskeyWalletClient(config) {
      * Send multiple calls as a single batched transaction
      */
     async sendCalls(params) {
-      const { calls, chainId: targetChain, tokenRequests } = params;
+      const { calls, chainId: targetChain, tokenRequests, sourceAssets, sourceChainId } = params;
       const closeOn = config.waitForHash ?? true ? "completed" : "preconfirmed";
-      const intentPayload = await buildIntentPayload(calls, targetChain);
+      const intentPayload = await buildIntentPayload(calls, targetChain, { tokenRequests, sourceAssets });
       const result = await provider.sendIntent({
         ...intentPayload,
         tokenRequests,
+        sourceAssets,
+        sourceChainId,
         closeOn,
         waitForHash: config.waitForHash ?? true,
         hashTimeoutMs: config.hashTimeoutMs,