@reclaimprotocol/js-sdk 4.5.2 → 4.6.1

package/dist/index.js

@@ -72,7 +72,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@reclaimprotocol/js-sdk",
-      version: "4.5.2",
+      version: "4.6.1",
       description: "Designed to request proofs from the Reclaim protocol and manage the flow of claims and witness interactions.",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -262,7 +262,7 @@ var DeviceType = /* @__PURE__ */ ((DeviceType2) => {
 
 // src/Reclaim.ts
 var import_ethers6 = require("ethers");
-var import_canonicalize2 = __toESM(require("canonicalize"));
+var import_canonicalize3 = __toESM(require("canonicalize"));
 
 // src/utils/errors.ts
 function createErrorClass(name) {
@@ -1757,6 +1757,15 @@ function clearDeviceCache() {
   cachedMobileType = null;
 }
 
+// src/utils/strings.ts
+var import_canonicalize2 = __toESM(require("canonicalize"));
+function canonicalStringify(params) {
+  if (!params) {
+    return "";
+  }
+  return (0, import_canonicalize2.default)(params) || "";
+}
+
 // src/Reclaim.ts
 var logger7 = logger_default.logger;
 var sdkVersion = require_package().version;
@@ -1789,7 +1798,7 @@ function verifyProof(proofOrProofs, allowAiWitness) {
       }
       const calculatedIdentifier = getIdentifierFromClaimInfo({
         parameters: JSON.parse(
-          (0, import_canonicalize2.default)(proof.claimData.parameters)
+          (0, import_canonicalize3.default)(proof.claimData.parameters)
         ),
         provider: proof.claimData.provider,
         context: proof.claimData.context
@@ -1849,14 +1858,41 @@ var emptyTemplateData = {
 };
 var ReclaimProofRequest = class _ReclaimProofRequest {
   // 30 seconds timeout, can be adjusted
-  // Private constructor
   constructor(applicationId, providerId, options) {
     this.context = { contextAddress: "0x0", contextMessage: "sample context" };
     this.claimCreationType = "createClaim" /* STANDALONE */;
     this.intervals = /* @__PURE__ */ new Map();
     this.jsonProofResponse = false;
     this.extensionID = "reclaim-extension";
-    this.FAILURE_TIMEOUT = 3e4;
+    this.FAILURE_TIMEOUT = 30 * 1e3;
+    /**
+     * Validates signature and returns template data
+     * @returns 
+     */
+    this.getTemplateData = () => {
+      var _a, _b, _c, _d, _e, _f;
+      if (!this.signature) {
+        throw new SignatureNotFoundError("Signature is not set.");
+      }
+      validateSignature(this.providerId, this.signature, this.applicationId, this.timeStamp);
+      const templateData = {
+        sessionId: this.sessionId,
+        providerId: this.providerId,
+        applicationId: this.applicationId,
+        signature: this.signature,
+        timestamp: this.timeStamp,
+        callbackUrl: this.getAppCallbackUrl(),
+        context: canonicalStringify(this.context),
+        providerVersion: (_b = (_a = this.options) == null ? void 0 : _a.providerVersion) != null ? _b : "",
+        resolvedProviderVersion: (_c = this.resolvedProviderVersion) != null ? _c : "",
+        parameters: this.parameters,
+        redirectUrl: (_d = this.redirectUrl) != null ? _d : "",
+        acceptAiProviders: (_f = (_e = this.options) == null ? void 0 : _e.acceptAiProviders) != null ? _f : false,
+        sdkVersion: this.sdkVersion,
+        jsonProofResponse: this.jsonProofResponse
+      };
+      return templateData;
+    };
     var _a;
     this.providerId = providerId;
     this.timeStamp = Date.now().toString();
@@ -1892,7 +1928,26 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
     this.sdkVersion = "js-" + sdkVersion;
     logger7.info(`Initializing client with applicationId: ${this.applicationId}`);
   }
-  // Static initialization methods
+  /**
+   * Initializes a new Reclaim proof request instance with automatic signature generation and session creation
+   *
+   * @param applicationId - Your Reclaim application ID
+   * @param appSecret - Your application secret key for signing requests
+   * @param providerId - The ID of the provider to use for proof generation
+   * @param options - Optional configuration options for the proof request
+   * @returns Promise<ReclaimProofRequest> - A fully initialized proof request instance
+   * @throws {InitError} When initialization fails due to invalid parameters or session creation errors
+   *
+   * @example
+   * ```typescript
+   * const proofRequest = await ReclaimProofRequest.init(
+   *   'your-app-id',
+   *   'your-app-secret',
+   *   'provider-id',
+   *   { log: true, acceptAiProviders: true }
+   * );
+   * ```
+   */
   static init(applicationId, appSecret, providerId, options) {
     return __async(this, null, function* () {
       try {
@@ -1966,6 +2021,23 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       }
     });
   }
+  /**
+   * Creates a ReclaimProofRequest instance from a JSON string representation
+   *
+   * This method deserializes a previously exported proof request (via toJsonString) and reconstructs
+   * the instance with all its properties. Useful for recreating requests on the frontend or across different contexts.
+   *
+   * @param jsonString - JSON string containing the serialized proof request data
+   * @returns {Promise<ReclaimProofRequest>} - Reconstructed proof request instance
+   * @throws {InvalidParamError} When JSON string is invalid or contains invalid parameters
+   *
+   * @example
+   * ```typescript
+   * const jsonString = proofRequest.toJsonString();
+   * const reconstructed = await ReclaimProofRequest.fromJsonString(jsonString);
+   * // Can also be used with InApp SDK's startVerificationFromJson method
+   * ```
+   */
   static fromJsonString(jsonString) {
     return __async(this, null, function* () {
       try {
@@ -2047,19 +2119,75 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       }
     });
   }
-  // Setter methods
+  /**
+   * Sets a custom callback URL where proofs will be submitted via HTTP POST
+   *
+   * By default, proofs are posted as `application/x-www-form-urlencoded`.
+   * When a custom callback URL is set, Reclaim will no longer receive proofs upon submission,
+   * and listeners on the startSession method will not be triggered. Your application must
+   * coordinate with your backend to receive and verify proofs using verifyProof().
+   *
+   * Note: InApp SDKs are unaffected by this property as they do not handle proof submission.
+   *
+   * @param url - The URL where proofs should be submitted via HTTP POST
+   * @param jsonProofResponse - Optional. Set to true to submit proofs as `application/json`. Defaults to false
+   * @throws {InvalidParamError} When URL is invalid
+   *
+   * @example
+   * ```typescript
+   * proofRequest.setAppCallbackUrl('https://your-backend.com/callback');
+   * // Or with JSON format
+   * proofRequest.setAppCallbackUrl('https://your-backend.com/callback', true);
+   * ```
+   */
   setAppCallbackUrl(url, jsonProofResponse) {
     validateURL(url, "setAppCallbackUrl");
     this.appCallbackUrl = url;
     this.jsonProofResponse = jsonProofResponse != null ? jsonProofResponse : false;
   }
+  /**
+   * Sets a redirect URL where users will be redirected after successfully acquiring and submitting proof
+   *
+   * @param url - The URL where users should be redirected after successful proof generation
+   * @throws {InvalidParamError} When URL is invalid
+   *
+   * @example
+   * ```typescript
+   * proofRequest.setRedirectUrl('https://your-app.com/success');
+   * ```
+   */
   setRedirectUrl(url) {
     validateURL(url, "setRedirectUrl");
     this.redirectUrl = url;
   }
+  /**
+   * Sets the claim creation type for the proof request
+   *
+   * @param claimCreationType - The type of claim creation (e.g., STANDALONE)
+   *
+   * @example
+   * ```typescript
+   * proofRequest.setClaimCreationType(ClaimCreationType.STANDALONE);
+   * ```
+   */
   setClaimCreationType(claimCreationType) {
     this.claimCreationType = claimCreationType;
   }
+  /**
+   * Sets custom options for the QR code modal display
+   *
+   * @param options - Modal configuration options including title, description, theme, etc.
+   * @throws {SetParamsError} When modal options are invalid
+   *
+   * @example
+   * ```typescript
+   * proofRequest.setModalOptions({
+   *   title: 'Scan QR Code',
+   *   description: 'Scan with your mobile device',
+   *   darkTheme: true
+   * });
+   * ```
+   */
   setModalOptions(options) {
     try {
       validateModalOptions(options, "setModalOptions");
@@ -2070,6 +2198,48 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       throw new SetParamsError("Error setting modal options", error);
     }
   }
+  /**
+   * Sets additional context data to be stored with the claim
+   *
+   * This allows you to associate custom data (address and message) with the proof claim.
+   * The context can be retrieved and validated when verifying the proof. 
+   * 
+   * Also see [setContext] which is an alternate way to set context that has an address & message.
+   *
+   * @param context - Any additional data you want to store with the claim. Should be serializable to a JSON string.
+   * @throws {SetContextError} When context parameters are invalid
+   *
+   * @example
+   * ```typescript
+   * proofRequest.setJsonContext({foo: 'bar'});
+   * ```
+   */
+  setJsonContext(context) {
+    try {
+      validateFunctionParams([
+        { input: context, paramName: "context", isString: false }
+      ], "setJsonContext");
+      this.context = JSON.parse(canonicalStringify(context));
+    } catch (error) {
+      logger7.info("Error setting context", error);
+      throw new SetContextError("Error setting context", error);
+    }
+  }
+  /**
+   * Sets additional context data to be stored with the claim
+   *
+   * This allows you to associate custom data (address and message) with the proof claim.
+   * The context can be retrieved and validated when verifying the proof.
+   *
+   * @param address - Context address identifier
+   * @param message - Additional data to associate with the address
+   * @throws {SetContextError} When context parameters are invalid
+   *
+   * @example
+   * ```typescript
+   * proofRequest.setContext('0x1234...', 'User verification for premium access');
+   * ```
+   */
   setContext(address, message) {
     try {
       validateFunctionParams([
@@ -2082,10 +2252,32 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       throw new SetContextError("Error setting context", error);
     }
   }
-  // deprecated method: use setContext instead
+  /**
+   * @deprecated use setContext instead
+   *
+   * @param address 
+   * @param message additional data you want associated with the [address] 
+   */
   addContext(address, message) {
     this.setContext(address, message);
   }
+  /**
+   * Sets provider-specific parameters for the proof request
+   *
+   * These parameters are passed to the provider and may include configuration options,
+   * filters, or other provider-specific settings required for proof generation.
+   *
+   * @param params - Key-value pairs of parameters to set
+   * @throws {SetParamsError} When parameters are invalid
+   *
+   * @example
+   * ```typescript
+   * proofRequest.setParams({
+   *   minFollowers: '1000',
+   *   platform: 'twitter'
+   * });
+   * ```
+   */
   setParams(params) {
     try {
       validateParameters(params);
@@ -2095,7 +2287,21 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       throw new SetParamsError("Error setting params", error);
     }
   }
-  // Getter methods
+  /**
+   * Returns the currently configured app callback URL
+   *
+   * If no custom callback URL was set via setAppCallbackUrl(), this returns the default
+   * Reclaim service callback URL with the current session ID.
+   *
+   * @returns The callback URL where proofs will be submitted
+   * @throws {GetAppCallbackUrlError} When unable to retrieve the callback URL
+   *
+   * @example
+   * ```typescript
+   * const callbackUrl = proofRequest.getAppCallbackUrl();
+   * console.log('Proofs will be sent to:', callbackUrl);
+   * ```
+   */
   getAppCallbackUrl() {
     try {
       validateFunctionParams([{ input: this.sessionId, paramName: "sessionId", isString: true }], "getAppCallbackUrl");
@@ -2105,6 +2311,20 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       throw new GetAppCallbackUrlError("Error getting app callback url", error);
     }
   }
+  /**
+   * Returns the status URL for monitoring the current session
+   *
+   * This URL can be used to check the status of the proof request session.
+   *
+   * @returns The status monitoring URL for the current session
+   * @throws {GetStatusUrlError} When unable to retrieve the status URL
+   *
+   * @example
+   * ```typescript
+   * const statusUrl = proofRequest.getStatusUrl();
+   * // Use this URL to poll for session status updates
+   * ```
+   */
   getStatusUrl() {
     try {
       validateFunctionParams([{ input: this.sessionId, paramName: "sessionId", isString: true }], "getStatusUrl");
@@ -2114,7 +2334,21 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       throw new GetStatusUrlError("Error fetching status url", error);
     }
   }
-  // getter for SessionId
+  /**
+   * Returns the session ID associated with this proof request
+   *
+   * The session ID is automatically generated during initialization and uniquely
+   * identifies this proof request session.
+   *
+   * @returns The session ID string
+   * @throws {SessionNotStartedError} When session ID is not set
+   *
+   * @example
+   * ```typescript
+   * const sessionId = proofRequest.getSessionId();
+   * console.log('Session ID:', sessionId);
+   * ```
+   */
   getSessionId() {
     if (!this.sessionId) {
       throw new SessionNotStartedError("SessionId is not set");
@@ -2136,7 +2370,7 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
     return __async(this, null, function* () {
       try {
         const wallet = new import_ethers6.ethers.Wallet(applicationSecret);
-        const canonicalData = (0, import_canonicalize2.default)({ providerId: this.providerId, timestamp: this.timeStamp });
+        const canonicalData = (0, import_canonicalize3.default)({ providerId: this.providerId, timestamp: this.timeStamp });
         if (!canonicalData) {
           throw new SignatureGeneratingError("Failed to canonicalize data for signing.");
         }
@@ -2161,7 +2395,22 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
     }
     return `${baseUrl}/?template=${template}`;
   }
-  // Public methods
+  /**
+   * Exports the Reclaim proof verification request as a JSON string
+   *
+   * This serialized format can be sent to the frontend to recreate this request using
+   * ReclaimProofRequest.fromJsonString() or any InApp SDK's startVerificationFromJson()
+   * method to initiate the verification journey.
+   *
+   * @returns JSON string representation of the proof request
+   *
+   * @example
+   * ```typescript
+   * const jsonString = proofRequest.toJsonString();
+   * // Send to frontend or store for later use
+   * // Can be reconstructed with: ReclaimProofRequest.fromJsonString(jsonString)
+   * ```
+   */
   toJsonString() {
     var _a;
     return JSON.stringify({
@@ -2190,40 +2439,48 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       } : void 0
     });
   }
-  getRequestUrl() {
+  /**
+   * Generates and returns the request URL for proof verification
+   *
+   * This URL can be shared with users to initiate the proof generation process.
+   * The URL format varies based on device type:
+   * - Mobile iOS: Returns App Clip URL (if useAppClip is enabled)
+   * - Mobile Android: Returns Instant App URL (if useAppClip is enabled)
+   * - Desktop/Other: Returns standard verification URL
+   *
+   * @param launchOptions - Optional launch configuration to override default behavior
+   * @returns Promise<string> - The generated request URL
+   * @throws {SignatureNotFoundError} When signature is not set
+   *
+   * @example
+   * ```typescript
+   * const requestUrl = await proofRequest.getRequestUrl();
+   * // Share this URL with users or display as QR code
+   * ```
+   */
+  getRequestUrl(launchOptions) {
     return __async(this, null, function* () {
-      var _a, _b, _c, _d, _e, _f, _g;
+      var _a, _b, _c;
+      const options = launchOptions || ((_a = this.options) == null ? void 0 : _a.launchOptions) || {};
       logger7.info("Creating Request Url");
       if (!this.signature) {
         throw new SignatureNotFoundError("Signature is not set.");
       }
       try {
-        validateSignature(this.providerId, this.signature, this.applicationId, this.timeStamp);
-        const templateData = {
-          sessionId: this.sessionId,
-          providerId: this.providerId,
-          providerVersion: (_b = (_a = this.options) == null ? void 0 : _a.providerVersion) != null ? _b : "",
-          resolvedProviderVersion: (_c = this.resolvedProviderVersion) != null ? _c : "",
-          applicationId: this.applicationId,
-          signature: this.signature,
-          timestamp: this.timeStamp,
-          callbackUrl: this.getAppCallbackUrl(),
-          context: JSON.stringify(this.context),
-          parameters: this.parameters,
-          redirectUrl: (_d = this.redirectUrl) != null ? _d : "",
-          acceptAiProviders: (_f = (_e = this.options) == null ? void 0 : _e.acceptAiProviders) != null ? _f : false,
-          sdkVersion: this.sdkVersion,
-          jsonProofResponse: this.jsonProofResponse
-        };
+        const templateData = this.getTemplateData();
         yield updateSession(this.sessionId, "SESSION_STARTED" /* SESSION_STARTED */);
         const deviceType = getDeviceType();
-        if (((_g = this.options) == null ? void 0 : _g.useAppClip) && deviceType === "mobile" /* MOBILE */) {
+        if (((_b = this.options) == null ? void 0 : _b.useAppClip) && deviceType === "mobile" /* MOBILE */) {
           let template = encodeURIComponent(JSON.stringify(templateData));
           template = replaceAll(template, "(", "%28");
           template = replaceAll(template, ")", "%29");
           const isIos = getMobileDeviceType() === "ios" /* IOS */;
           if (!isIos) {
-            const instantAppUrl = this.buildSharePageUrl(template);
+            let instantAppUrl = this.buildSharePageUrl(template);
+            const isDeferredDeeplinksFlowEnabled = (_c = options.canUseDeferredDeepLinksFlow) != null ? _c : false;
+            if (isDeferredDeeplinksFlowEnabled) {
+              instantAppUrl = instantAppUrl.replace("/verifier", "/link");
+            }
             logger7.info("Instant App Url created successfully: " + instantAppUrl);
             return instantAppUrl;
           } else {
@@ -2242,37 +2499,41 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       }
     });
   }
-  triggerReclaimFlow() {
+  /**
+   * Triggers the appropriate Reclaim verification flow based on device type and configuration
+   *
+   * This method automatically detects the device type and initiates the optimal verification flow:
+   * - Desktop with browser extension: Triggers extension flow
+   * - Desktop without extension: Shows QR code modal
+   * - Mobile Android: Redirects to Instant App
+   * - Mobile iOS: Redirects to App Clip
+   *
+   * @param launchOptions - Optional launch configuration to override default behavior
+   * @returns Promise<void>
+   * @throws {SignatureNotFoundError} When signature is not set
+   *
+   * @example
+   * ```typescript
+   * await proofRequest.triggerReclaimFlow();
+   * // The appropriate verification method will be triggered automatically
+   * ```
+   */
+  triggerReclaimFlow(launchOptions) {
     return __async(this, null, function* () {
-      var _a, _b, _c, _d, _e, _f, _g;
+      var _a, _b;
+      const options = launchOptions || ((_a = this.options) == null ? void 0 : _a.launchOptions) || {};
       if (!this.signature) {
         throw new SignatureNotFoundError("Signature is not set.");
       }
       try {
-        validateSignature(this.providerId, this.signature, this.applicationId, this.timeStamp);
-        const templateData = {
-          sessionId: this.sessionId,
-          providerId: this.providerId,
-          applicationId: this.applicationId,
-          signature: this.signature,
-          timestamp: this.timeStamp,
-          callbackUrl: this.getAppCallbackUrl(),
-          context: JSON.stringify(this.context),
-          providerVersion: (_b = (_a = this.options) == null ? void 0 : _a.providerVersion) != null ? _b : "",
-          resolvedProviderVersion: (_c = this.resolvedProviderVersion) != null ? _c : "",
-          parameters: this.parameters,
-          redirectUrl: (_d = this.redirectUrl) != null ? _d : "",
-          acceptAiProviders: (_f = (_e = this.options) == null ? void 0 : _e.acceptAiProviders) != null ? _f : false,
-          sdkVersion: this.sdkVersion,
-          jsonProofResponse: this.jsonProofResponse
-        };
+        const templateData = this.getTemplateData();
         this.templateData = templateData;
         logger7.info("Triggering Reclaim flow");
         const deviceType = getDeviceType();
-        yield updateSession(this.sessionId, "SESSION_STARTED" /* SESSION_STARTED */);
+        updateSession(this.sessionId, "SESSION_STARTED" /* SESSION_STARTED */);
         if (deviceType === "desktop" /* DESKTOP */) {
           const extensionAvailable = yield this.isBrowserExtensionAvailable();
-          if (((_g = this.options) == null ? void 0 : _g.useBrowserExtension) && extensionAvailable) {
+          if (((_b = this.options) == null ? void 0 : _b.useBrowserExtension) && extensionAvailable) {
             logger7.info("Triggering browser extension flow");
             this.triggerBrowserExtensionFlow();
             return;
@@ -2284,10 +2545,10 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
           const mobileDeviceType = getMobileDeviceType();
           if (mobileDeviceType === "android" /* ANDROID */) {
             logger7.info("Redirecting to Android instant app");
-            yield this.redirectToInstantApp();
+            yield this.redirectToInstantApp(options);
           } else if (mobileDeviceType === "ios" /* IOS */) {
             logger7.info("Redirecting to iOS app clip");
-            yield this.redirectToAppClip();
+            this.redirectToAppClip();
           }
         }
       } catch (error) {
@@ -2296,6 +2557,23 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       }
     });
   }
+  /**
+   * Checks if the Reclaim browser extension is installed and available
+   *
+   * This method attempts to communicate with the browser extension to verify its availability.
+   * It uses a timeout mechanism to quickly determine if the extension responds.
+   *
+   * @param timeout - Timeout in milliseconds to wait for extension response. Defaults to 200ms
+   * @returns Promise<boolean> - True if extension is available, false otherwise
+   *
+   * @example
+   * ```typescript
+   * const hasExtension = await proofRequest.isBrowserExtensionAvailable();
+   * if (hasExtension) {
+   *   console.log('Browser extension is installed');
+   * }
+   * ```
+   */
   isBrowserExtensionAvailable(timeout = 200) {
     return __async(this, null, function* () {
       try {
@@ -2349,14 +2627,62 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       }
     });
   }
-  redirectToInstantApp() {
+  redirectToInstantApp(options) {
     return __async(this, null, function* () {
+      var _a;
       try {
         let template = encodeURIComponent(JSON.stringify(this.templateData));
         template = replaceAll(template, "(", "%28");
         template = replaceAll(template, ")", "%29");
-        const instantAppUrl = this.buildSharePageUrl(template);
+        let instantAppUrl = this.buildSharePageUrl(template);
         logger7.info("Redirecting to Android instant app: " + instantAppUrl);
+        const isDeferredDeeplinksFlowEnabled = (_a = options.canUseDeferredDeepLinksFlow) != null ? _a : false;
+        if (isDeferredDeeplinksFlowEnabled) {
+          instantAppUrl = instantAppUrl.replace("/verifier", "/link");
+          const deepLink = `intent://details?id=org.reclaimprotocol.app&url=${encodeURIComponent(
+            instantAppUrl
+          )}&template=${template}#Intent;scheme=market;action=android.intent.action.VIEW;package=com.android.vending;end;`;
+          try {
+            const requestUrl = instantAppUrl;
+            let appInstalled = false;
+            let timeoutId;
+            const iframe = document.createElement("iframe");
+            iframe.style.display = "none";
+            iframe.style.width = "1px";
+            iframe.style.height = "1px";
+            document.body.appendChild(iframe);
+            const cleanup = () => {
+              if (iframe.parentNode) {
+                document.body.removeChild(iframe);
+              }
+              if (timeoutId) {
+                clearTimeout(timeoutId);
+              }
+            };
+            const onVisibilityChange = () => {
+              if (document.hidden) {
+                appInstalled = true;
+                cleanup();
+                window.location.href = deepLink;
+              }
+            };
+            document.addEventListener("visibilitychange", onVisibilityChange, { once: true });
+            iframe.src = deepLink.replace("intent:", "reclaimverifier:");
+            timeoutId = setTimeout(() => {
+              document.removeEventListener("visibilitychange", onVisibilityChange);
+              cleanup();
+              if (!appInstalled) {
+                window.navigator.clipboard.writeText(requestUrl).catch(() => {
+                  console.error("We can't access the clipboard. Please copy this link and open Reclaim Verifier app.");
+                });
+                window.location.href = deepLink;
+              }
+            }, 1500);
+          } catch (e) {
+            window.location.href = instantAppUrl;
+          }
+          return;
+        }
         window.location.href = instantAppUrl;
       } catch (error) {
         logger7.info("Error redirecting to instant app:", error);
@@ -2365,20 +2691,51 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
     });
   }
   redirectToAppClip() {
-    return __async(this, null, function* () {
-      try {
-        let template = encodeURIComponent(JSON.stringify(this.templateData));
-        template = replaceAll(template, "(", "%28");
-        template = replaceAll(template, ")", "%29");
-        const appClipUrl = this.customAppClipUrl ? `${this.customAppClipUrl}&template=${template}` : `https://appclip.apple.com/id?p=org.reclaimprotocol.app.clip&template=${template}`;
-        logger7.info("Redirecting to iOS app clip: " + appClipUrl);
+    try {
+      let template = encodeURIComponent(JSON.stringify(this.templateData));
+      template = replaceAll(template, "(", "%28");
+      template = replaceAll(template, ")", "%29");
+      const appClipUrl = this.customAppClipUrl ? `${this.customAppClipUrl}&template=${template}` : `https://appclip.apple.com/id?p=org.reclaimprotocol.app.clip&template=${template}`;
+      logger7.info("Redirecting to iOS app clip: " + appClipUrl);
+      window.location.href = appClipUrl;
+      setTimeout(() => {
         window.location.href = appClipUrl;
-      } catch (error) {
-        logger7.info("Error redirecting to app clip:", error);
-        throw error;
-      }
-    });
+      }, 5 * 1e3);
+    } catch (error) {
+      logger7.info("Error redirecting to app clip:", error);
+      throw error;
+    }
   }
+  /**
+   * Starts the proof request session and monitors for proof submission
+   *
+   * This method begins polling the session status to detect when
+   * a proof has been generated and submitted. It handles both default Reclaim callbacks
+   * and custom callback URLs.
+   *
+   * For default callbacks: Verifies proofs automatically and passes them to onSuccess
+   * For custom callbacks: Monitors submission status and notifies via onSuccess when complete
+   *
+   * @param onSuccess - Callback function invoked when proof is successfully submitted
+   * @param onError - Callback function invoked when an error occurs during the session
+   * @returns Promise<void>
+   * @throws {SessionNotStartedError} When session ID is not defined
+   * @throws {ProofNotVerifiedError} When proof verification fails (default callback only)
+   * @throws {ProofSubmissionFailedError} When proof submission fails (custom callback only)
+   * @throws {ProviderFailedError} When proof generation fails with timeout
+   *
+   * @example
+   * ```typescript
+   * await proofRequest.startSession({
+   *   onSuccess: (proof) => {
+   *     console.log('Proof received:', proof);
+   *   },
+   *   onError: (error) => {
+   *     console.error('Error:', error);
+   *   }
+   * });
+   * ```
+   */
   startSession(_0) {
     return __async(this, arguments, function* ({ onSuccess, onError }) {
       if (!this.sessionId) {
@@ -2387,6 +2744,7 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
         throw new SessionNotStartedError(message);
       }
       logger7.info("Starting session");
+      const sessionUpdatePollingInterval = 3 * 1e3;
       const interval = setInterval(() => __async(this, null, function* () {
         var _a, _b, _c;
         try {
@@ -2442,11 +2800,23 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
           this.clearInterval();
           (_c = this.modal) == null ? void 0 : _c.close();
         }
-      }), 3e3);
+      }), sessionUpdatePollingInterval);
       this.intervals.set(this.sessionId, interval);
       scheduleIntervalEndingTask(this.sessionId, this.intervals, onError);
     });
   }
+  /**
+   * Closes the QR code modal if it is currently open
+   *
+   * This method can be called to programmatically close the modal, for example,
+   * when implementing custom UI behavior or cleanup logic.
+   *
+   * @example
+   * ```typescript
+   * // Close modal after some condition
+   * proofRequest.closeModal();
+   * ```
+   */
   closeModal() {
     if (this.modal) {
       this.modal.close();