@reclaimprotocol/js-sdk 4.10.0 → 4.11.0

package/dist/index.js

@@ -72,7 +72,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@reclaimprotocol/js-sdk",
-      version: "4.10.0",
+      version: "4.11.0",
       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",
@@ -179,6 +179,7 @@ __export(index_exports, {
   DeviceType: () => DeviceType,
   RECLAIM_EXTENSION_ACTIONS: () => RECLAIM_EXTENSION_ACTIONS,
   ReclaimProofRequest: () => ReclaimProofRequest,
+  SessionStatus: () => SessionStatus,
   clearDeviceCache: () => clearDeviceCache,
   getDeviceType: () => getDeviceType,
   getMobileDeviceType: () => getMobileDeviceType,
@@ -280,6 +281,22 @@ var DeviceType = /* @__PURE__ */ ((DeviceType2) => {
   DeviceType2["MOBILE"] = "mobile";
   return DeviceType2;
 })(DeviceType || {});
+var SessionStatus = /* @__PURE__ */ ((SessionStatus2) => {
+  SessionStatus2["SESSION_INIT"] = "SESSION_INIT";
+  SessionStatus2["SESSION_STARTED"] = "SESSION_STARTED";
+  SessionStatus2["USER_INIT_VERIFICATION"] = "USER_INIT_VERIFICATION";
+  SessionStatus2["USER_STARTED_VERIFICATION"] = "USER_STARTED_VERIFICATION";
+  SessionStatus2["PROOF_GENERATION_STARTED"] = "PROOF_GENERATION_STARTED";
+  SessionStatus2["PROOF_GENERATION_SUCCESS"] = "PROOF_GENERATION_SUCCESS";
+  SessionStatus2["PROOF_GENERATION_FAILED"] = "PROOF_GENERATION_FAILED";
+  SessionStatus2["PROOF_SUBMITTED"] = "PROOF_SUBMITTED";
+  SessionStatus2["AI_PROOF_SUBMITTED"] = "AI_PROOF_SUBMITTED";
+  SessionStatus2["PROOF_SUBMISSION_FAILED"] = "PROOF_SUBMISSION_FAILED";
+  SessionStatus2["ERROR_SUBMITTED"] = "ERROR_SUBMITTED";
+  SessionStatus2["ERROR_SUBMISSION_FAILED"] = "ERROR_SUBMISSION_FAILED";
+  SessionStatus2["PROOF_MANUAL_VERIFICATION_SUBMITED"] = "PROOF_MANUAL_VERIFICATION_SUBMITED";
+  return SessionStatus2;
+})(SessionStatus || {});
 
 // src/Reclaim.ts
 var import_ethers6 = require("ethers");
@@ -474,6 +491,41 @@ function validateURL(url, functionName) {
     throw new InvalidParamError(`Invalid URL format ${url} passed to ${functionName}.`, e);
   }
 }
+function validateRedirectionMethod(method, functionName) {
+  try {
+    if (method === null || method === void 0) {
+      return;
+    }
+    if (method !== "GET" && method !== "POST") {
+      throw new Error(`Invalid redirection method ${method} passed to ${functionName}.`);
+    }
+  } catch (e) {
+    logger3.info(`Redirection method validation failed for ${method} in ${functionName}: ${e.message}`);
+    throw new InvalidParamError(`Invalid redirection method ${method} passed to ${functionName}.`, e);
+  }
+}
+function validateRedirectionBody(records, functionName) {
+  try {
+    if (records === null || records === void 0) {
+      return;
+    }
+    if (Array.isArray(records)) {
+      for (const record of records) {
+        if ("name" in record && record.name && typeof record.name === "string") {
+          if ("value" in record && typeof record.value === "string") {
+            continue;
+          }
+        }
+        throw new Error("Record in form entries do not have a valid name and/or value");
+      }
+    } else {
+      throw new Error("Redirection body must be an array of objects with name, and value");
+    }
+  } catch (e) {
+    logger3.info(`Redirection body validation failed for ${records} in ${functionName}: ${e.message}`);
+    throw new InvalidParamError(`Invalid redirection body ${records} passed to ${functionName}.`, e);
+  }
+}
 function validateSignature(providerId, signature, applicationId, timestamp) {
   try {
     logger3.info(`Starting signature validation for providerId: ${providerId}, applicationId: ${applicationId}, timestamp: ${timestamp}`);
@@ -1885,8 +1937,10 @@ var emptyTemplateData = {
   context: "",
   parameters: {},
   redirectUrl: "",
+  redirectUrlOptions: { method: "GET" },
   cancelCallbackUrl: "",
   cancelRedirectUrl: "",
+  cancelRedirectUrlOptions: { method: "GET" },
   acceptAiProviders: false,
   sdkVersion: "",
   providerVersion: "",
@@ -1925,8 +1979,10 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
         resolvedProviderVersion: (_c = this.resolvedProviderVersion) != null ? _c : "",
         parameters: this.parameters,
         redirectUrl: (_d = this.redirectUrl) != null ? _d : "",
+        redirectUrlOptions: this.redirectUrlOptions,
         cancelCallbackUrl: this.getCancelCallbackUrl(),
         cancelRedirectUrl: this.cancelRedirectUrl,
+        cancelRedirectUrlOptions: this.cancelRedirectUrlOptions,
         acceptAiProviders: (_f = (_e = this.options) == null ? void 0 : _e.acceptAiProviders) != null ? _f : false,
         sdkVersion: this.sdkVersion,
         jsonProofResponse: this.jsonProofResponse,
@@ -2112,8 +2168,10 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
           parameters,
           signature,
           redirectUrl,
+          redirectUrlOptions,
           cancelCallbackUrl,
           cancelRedirectUrl,
+          cancelRedirectUrlOptions,
           timeStamp,
           timestamp,
           appCallbackUrl,
@@ -2139,12 +2197,20 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
         if (redirectUrl) {
           validateURL(redirectUrl, "fromJsonString");
         }
+        if (redirectUrlOptions) {
+          validateRedirectionMethod(redirectUrlOptions.method, "fromJsonString");
+          validateRedirectionBody(redirectUrlOptions.body, "fromJsonString");
+        }
         if (appCallbackUrl) {
           validateURL(appCallbackUrl, "fromJsonString");
         }
         if (cancelRedirectUrl) {
           validateURL(cancelRedirectUrl, "fromJsonString");
         }
+        if (cancelRedirectUrlOptions) {
+          validateRedirectionMethod(cancelRedirectUrlOptions.method, "fromJsonString");
+          validateRedirectionBody(cancelRedirectUrlOptions.body, "fromJsonString");
+        }
         if (cancelCallbackUrl) {
           validateURL(cancelCallbackUrl, "fromJsonString");
         }
@@ -2198,6 +2264,7 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
         proofRequestInstance.parameters = parameters;
         proofRequestInstance.appCallbackUrl = appCallbackUrl;
         proofRequestInstance.redirectUrl = redirectUrl;
+        proofRequestInstance.redirectUrlOptions = redirectUrlOptions;
         proofRequestInstance.timeStamp = resolvedTimestamp;
         proofRequestInstance.signature = signature;
         proofRequestInstance.sdkVersion = sdkVersion2;
@@ -2206,6 +2273,7 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
         proofRequestInstance.jsonProofResponse = jsonProofResponse != null ? jsonProofResponse : false;
         proofRequestInstance.cancelCallbackUrl = cancelCallbackUrl;
         proofRequestInstance.cancelRedirectUrl = cancelRedirectUrl;
+        proofRequestInstance.cancelRedirectUrlOptions = cancelRedirectUrlOptions;
         return proofRequestInstance;
       } catch (error) {
         logger7.info("Failed to parse JSON string in fromJsonString:", error);
@@ -2214,16 +2282,21 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
     });
   }
   /**
-   * Sets a custom callback URL where proofs will be submitted via HTTP POST
+   * 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().
+   * By default, proofs are sent as HTTP POST with `Content-Type` as `application/x-www-form-urlencoded`. 
+   * Pass function argument `jsonProofResponse` as `true` to send proofs with `Content-Type` as `application/json`.
+   * 
+   * When a custom callback URL is set, proofs are sent to the custom URL *instead* of the Reclaim backend.
+   * Consequently, the startSession `onSuccess` callback will be invoked with an empty array (`[]`) 
+   * instead of the proof data, as the proof is not available to the SDK in this flow.
+   *
+   * This verification session's id will be present in `X-Reclaim-Session-Id` header of the request.
+   * The request URL will contain query param `allowAiWitness` with value `true` when AI Witness should be allowed by handler of the request.
    *
    * 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 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
    *
@@ -2243,6 +2316,13 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
    * 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
+   * @param method - The redirection method that should be used for redirection. Allowed options: `GET`, and `POST`.
+   * `POST` form redirection is only supported in In-Browser SDK.
+   * @param body - List of name-value pairs to be sent as the body of the form request.
+   * `When `method` is set to `POST`, `body` will be sent with 'application/x-www-form-urlencoded' content type.
+   * When `method` is set to `GET`, if `body` is set then `body` will be sent as query parameters.
+   * Sending `body` on redirection is only supported in In-Browser SDK.
+   * 
    * @throws {InvalidParamError} When URL is invalid
    *
    * @example
@@ -2250,29 +2330,50 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
    * proofRequest.setRedirectUrl('https://your-app.com/success');
    * ```
    */
-  setRedirectUrl(url) {
+  setRedirectUrl(url, method = "GET", body) {
     validateURL(url, "setRedirectUrl");
+    validateRedirectionMethod(method, "setRedirectUrl");
+    validateRedirectionBody(body, "setRedirectUrl");
     this.redirectUrl = url;
+    this.redirectUrlOptions = { method: method || "GET", body };
   }
   /**
-   * Sets a custom callback URL where errors that abort the verification process will be submitted via HTTP POST
-   *
-   * Errors will be HTTP POSTed with `header 'Content-Type': 'application/json'`.
-   * When a custom error callback URL is set, Reclaim will no longer receive errors upon submission,
-   * and listeners on the startSession method will not be triggered. Your application must
-   * coordinate with your backend to receive errors.
-   *
-   * @param url - The URL where errors should be submitted via HTTP POST
-   * @throws {InvalidParamError} When URL is invalid
-   *
-   * @example
-   * ```typescript
-   * proofRequest.setCancelCallbackUrl('https://your-backend.com/error-callback');
-   * ```
-   * 
-   * @since 4.8.1
-   * 
-   */
+       * Sets a custom callback URL where errors that abort the verification process will be submitted via HTTP POST
+       *
+       * Errors will be HTTP POSTed with `header 'Content-Type': 'application/json'`.
+       * When a custom error callback URL is set, Reclaim will no longer receive errors upon submission,
+       * and listeners on the startSession method will not be triggered. Your application must
+       * coordinate with your backend to receive errors.
+       *
+       * This verification session's id will be present in `X-Reclaim-Session-Id` header of the request.
+       * 
+       * Following is the data format which is sent as an HTTP POST request to the url with `Content-Type: application/json`:
+  
+       * ```json
+       * {
+       *  "type": "string", // Name of the exception
+       *  "message": "string",
+       *  "sessionId": "string",
+       *   // context as canonicalized json string
+       *   "context": "string",
+       *   // Other fields with more details about error may be present
+       *   // [key: any]: any
+       * }
+       * ```
+       * 
+       * For more details about response format, check out [official documentation of Error Callback URL](https://docs.reclaimprotocol.org/js-sdk/preparing-request#cancel-callback).
+       *
+       * @param url - The URL where errors should be submitted via HTTP POST
+       * @throws {InvalidParamError} When URL is invalid
+       *
+       * @example
+       * ```typescript
+       * proofRequest.setCancelCallbackUrl('https://your-backend.com/error-callback');
+       * ```
+       * 
+       * @since 4.8.1
+       * 
+       */
   setCancelCallbackUrl(url) {
     validateURL(url, "setCancelCallbackUrl");
     this.cancelCallbackUrl = url;
@@ -2281,6 +2382,12 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
    * Sets an error redirect URL where users will be redirected after an error which aborts the verification process
    *
    * @param url - The URL where users should be redirected after an error which aborts the verification process
+   * @param method - The redirection method that should be used for redirection. Allowed options: `GET`, and `POST`.
+   * `POST` form redirection is only supported in In-Browser SDK.
+   * @param body - List of name-value pairs to be sent as the body of the form request.
+   * When `method` is set to `POST`, `body` will be sent with 'application/x-www-form-urlencoded' content type.
+   * When `method` is set to `GET`, if `body` is set then `body` will be sent as query parameters.
+   * Sending `body` on redirection is only supported in In-Browser SDK.
    * @throws {InvalidParamError} When URL is invalid
    *
    * @example
@@ -2291,9 +2398,12 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
    * @since 4.10.0
    * 
    */
-  setCancelRedirectUrl(url) {
+  setCancelRedirectUrl(url, method = "GET", body) {
     validateURL(url, "setCancelRedirectUrl");
+    validateRedirectionMethod(method, "setCancelRedirectUrl");
+    validateRedirectionBody(body, "setCancelRedirectUrl");
     this.cancelRedirectUrl = url;
+    this.cancelRedirectUrlOptions = { method: method || "GET", body };
   }
   /**
    * Sets the claim creation type for the proof request
@@ -2336,11 +2446,13 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
   /**
    * Sets additional context data to be stored with the claim
    *
-   * This allows you to associate custom data (address and message) with the proof claim.
+   * This allows you to associate custom JSON serializable data 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.
    *
+   * [setContext] and [setJsonContext] overwrite each other. Each call replaces the existing context.
+   * 
    * @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
    *
@@ -2366,6 +2478,10 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
    * 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 [setJsonContext] which is an alternate way to set context that allows for custom JSON serializable data.
+   * 
+   * [setContext] and [setJsonContext] overwrite each other. Each call replaces the existing context.
+   * 
    * @param address - Context address identifier
    * @param message - Additional data to associate with the address
    * @throws {SetContextError} When context parameters are invalid
@@ -2582,8 +2698,10 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       parameters: this.parameters,
       signature: this.signature,
       redirectUrl: this.redirectUrl,
+      redirectUrlOptions: this.redirectUrlOptions,
       cancelCallbackUrl: this.cancelCallbackUrl,
       cancelRedirectUrl: this.cancelRedirectUrl,
+      cancelRedirectUrlOptions: this.cancelRedirectUrlOptions,
       timestamp: this.timeStamp,
       // New field with correct spelling
       timeStamp: this.timeStamp,
@@ -2879,7 +2997,16 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
    * 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
+   * For custom callbacks: Monitors submission status and notifies via onSuccess when complete.
+   * In the custom-callback flow (where the SDK submits a proof to a provided callback URL),
+   * onSuccess may be invoked with an empty array (onSuccess([])) when no proof is available
+   * (this happens when a callback is set using setAppCallbackUrl where proof is sent to callback instead of reclaim backend).
+   * 
+   * Please refer to the OnSuccess type signature ((proof?: Proof | Proof[]) => void)
+   * and the startSession function source for more details.
+   * 
+   * > [!TIP]
+   * > **Best Practice:** When using `setAppCallbackUrl` and/or `setCancelCallbackUrl`, your backend receives the proof or cancellation details directly. We recommend your backend notifies the frontend (e.g. via WebSockets, SSE, or polling) to stop the verification process and handle the appropriate success/failure action. Do not rely completely on `startSession` callbacks on the frontend when using these backend callbacks.
    *
    * @param onSuccess - Callback function invoked when proof is successfully submitted
    * @param onError - Callback function invoked when an error occurs during the session
@@ -2955,7 +3082,7 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
             }
             if (statusUrlResponse.session.statusV2 === "PROOF_SUBMITTED" /* PROOF_SUBMITTED */ || statusUrlResponse.session.statusV2 === "AI_PROOF_SUBMITTED" /* AI_PROOF_SUBMITTED */) {
               if (onSuccess) {
-                onSuccess("Proof submitted successfully to the custom callback url");
+                onSuccess([]);
               }
               this.clearInterval();
               (_c = this.modal) == null ? void 0 : _c.close();
@@ -3012,6 +3139,7 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
   DeviceType,
   RECLAIM_EXTENSION_ACTIONS,
   ReclaimProofRequest,
+  SessionStatus,
   clearDeviceCache,
   getDeviceType,
   getMobileDeviceType,