@reclaimprotocol/js-sdk 4.7.1 → 4.8.1

package/README.md

@@ -314,7 +314,13 @@ The Reclaim SDK offers several advanced options to customize your integration:
    reclaimProofRequest.setRedirectUrl("https://example.com/redirect");
    ```
 
-4. **Custom Callback URL**:
+4. **Custom Error Redirect URL**:
+   Set a custom URL to redirect users on an error which aborts the verification process:
+   ```javascript
+   reclaimProofRequest.setErrorRedirectUrl("https://example.com/error-redirect");
+   ```
+
+5. **Custom Callback URL**:
    Set a custom callback URL for your app which allows you to receive proofs and status updates on your callback URL:
    Pass in `jsonProofResponse: true` to receive the proof in JSON format: By default, the proof is returned as a url encoded string.
 
@@ -322,7 +328,14 @@ The Reclaim SDK offers several advanced options to customize your integration:
    reclaimProofRequest.setAppCallbackUrl("https://example.com/callback", true);
    ```
 
-5. **Modal Customization for Desktop Users**:
+6. **Custom Error Callback URL**:
+   Set a custom error callback URL for your app which allows you to receive errors and status updates on your error callback URL:
+
+   ```javascript
+   reclaimProofRequest.setErrorCallbackUrl("https://example.com/error-callback");
+   ```
+
+7. **Modal Customization for Desktop Users**:
    Customize the appearance and behavior of the QR code modal shown to desktop users:
 
    ```javascript
@@ -334,7 +347,7 @@ The Reclaim SDK offers several advanced options to customize your integration:
    });
    ```
 
-6. **Browser Extension Configuration**:
+8. **Browser Extension Configuration**:
    Configure browser extension behavior and detection:
 
    ```javascript
@@ -353,7 +366,7 @@ The Reclaim SDK offers several advanced options to customize your integration:
    });
    ```
 
-7. **Custom Share Page and App Clip URLs**:
+9. **Custom Share Page and App Clip URLs**:
    You can customize the share page and app clip URLs for your app:
 
 ```javascript
@@ -364,7 +377,7 @@ const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER
 });
 ```
 
-8. **Platform-Specific Flow Control**:
+10. **Platform-Specific Flow Control**:
    The `triggerReclaimFlow()` method provides intelligent platform detection, but you can still use traditional methods for custom flows:
 
    ```javascript
@@ -377,7 +390,7 @@ const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER
    // Automatically handles platform detection and optimal user experience
    ```
 
-9. **Exporting and Importing SDK Configuration**:
+11. **Exporting and Importing SDK Configuration**:
    You can export the entire Reclaim SDK configuration as a JSON string and use it to initialize the SDK with the same configuration on a different service or backend:
 
    ```javascript
@@ -394,7 +407,7 @@ const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER
 
    This allows you to generate request URLs and other details from your backend or a different service while maintaining the same configuration.
 
-10. **Utility Methods**:
+12. **Utility Methods**:
     Additional utility methods for managing your proof requests:
 
 ```javascript
@@ -403,7 +416,7 @@ const sessionId = reclaimProofRequest.getSessionId();
 console.log("Current session ID:", sessionId);
 ```
 
-11. **Control auto-submission of proofs**:
+13. **Control auto-submission of proofs**:
 
 Whether the verification client should automatically submit necessary proofs once they are generated. If set to false, the user must manually click a button to submit.
 Defaults to true.
@@ -415,7 +428,7 @@ const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER
 });
 ```
 
-12. **Add additional metadata for verification client**:
+14. **Add additional metadata for verification client**:
 
 Additional metadata to pass to the verification client. This can be used to customize the client experience, such as customizing themes or UI by passing context-specific information. 
 The keys and values must be strings. For most clients, this is not required and goes unused.
@@ -431,11 +444,16 @@ const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER
 
 ## Handling Proofs on Your Backend
 
-For production applications, it's recommended to handle proofs on your backend:
+For production applications, it's recommended to handle proofs, and errors on your backend:
 
 1. Set a callback URL:
    ```javascript
-   reclaimProofRequest.setCallbackUrl("https://your-backend.com/receive-proofs");
+   reclaimProofRequest.setAppCallbackUrl("https://your-backend.com/receive-proofs");
+   ```
+
+2. Set a error callback URL:
+   ```javascript
+   reclaimProofRequest.setErrorCallbackUrl("https://your-backend.com/receive-errors");
    ```
 
 These options allow you to securely process proofs and status updates on your server.
@@ -517,6 +535,7 @@ try {
 - `ProviderFailedError`: Provider failed to generate proof
 - `SessionNotStartedError`: Session could not be started
 - `ProofSubmissionFailedError`: Proof submission to callback failed
+- `ErrorDuringVerificationError`: An abort error during verification which was caused by the user aborting the verification process or provider's JS script raising a validation error
 
 ## Next Steps
 

package/dist/index.d.ts

@@ -145,6 +145,8 @@ type ProofPropertiesJSON = {
     timeStamp?: string;
     timestamp?: string;
     appCallbackUrl?: string;
+    errorCallbackUrl?: TemplateData['errorCallbackUrl'];
+    errorRedirectUrl?: TemplateData['errorRedirectUrl'];
     claimCreationType?: ClaimCreationType;
     options?: ProofRequestOptions;
     sdkVersion: string;
@@ -152,6 +154,29 @@ type ProofPropertiesJSON = {
     resolvedProviderVersion: string;
     modalOptions?: SerializableModalOptions;
 };
+type TemplateData = {
+    sessionId: string;
+    providerId: string;
+    applicationId: string;
+    signature: string;
+    timestamp: string;
+    callbackUrl: string;
+    context: string;
+    parameters: {
+        [key: string]: string;
+    };
+    redirectUrl: string;
+    errorCallbackUrl?: string | null;
+    errorRedirectUrl?: string | null;
+    acceptAiProviders: boolean;
+    sdkVersion: string;
+    jsonProofResponse?: boolean;
+    providerVersion?: string;
+    resolvedProviderVersion: string;
+    log?: boolean;
+    canAutoSubmit?: boolean;
+    metadata?: Record<string, string>;
+};
 
 /**
  * Verifies one or more Reclaim proofs by validating signatures and witness information
@@ -198,6 +223,8 @@ declare class ReclaimProofRequest {
     private resolvedProviderVersion?;
     private parameters;
     private redirectUrl?;
+    private errorCallbackUrl?;
+    private errorRedirectUrl?;
     private intervals;
     private timeStamp;
     private sdkVersion;
@@ -284,6 +311,35 @@ declare class ReclaimProofRequest {
      * ```
      */
     setRedirectUrl(url: string): void;
+    /**
+     * 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.setErrorCallbackUrl('https://your-backend.com/error-callback');
+     * ```
+     */
+    setErrorCallbackUrl(url: string): void;
+    /**
+     * 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
+     * @throws {InvalidParamError} When URL is invalid
+     *
+     * @example
+     * ```typescript
+     * proofRequest.setErrorRedirectUrl('https://your-app.com/error');
+     * ```
+     */
+    setErrorRedirectUrl(url: string): void;
     /**
      * Sets the claim creation type for the proof request
      *
@@ -387,6 +443,22 @@ declare class ReclaimProofRequest {
      * ```
      */
     getAppCallbackUrl(): string;
+    /**
+     * Returns the currently configured error callback URL
+     *
+     * If no custom error callback URL was set via setErrorCallbackUrl(), this returns the default
+     * Reclaim service error callback URL with the current session ID.
+     *
+     * @returns The error callback URL where proofs will be submitted
+     * @throws {GetAppCallbackUrlError} When unable to retrieve the error callback URL
+     *
+     * @example
+     * ```typescript
+     * const callbackUrl = proofRequest.getErrorCallbackUrl();
+     * console.log('Errors will be sent to:', callbackUrl);
+     * ```
+     */
+    getErrorCallbackUrl(): string;
     /**
      * Returns the status URL for monitoring the current session
      *

package/dist/index.js

@@ -72,7 +72,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@reclaimprotocol/js-sdk",
-      version: "4.7.1",
+      version: "4.8.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",
@@ -322,6 +322,7 @@ var GetAppCallbackUrlError = createErrorClass("GetAppCallbackUrlError");
 var StatusUrlError = createErrorClass("StatusUrlError");
 var InavlidParametersError = createErrorClass("InavlidParametersError");
 var ProofSubmissionFailedError = createErrorClass("ProofSubmissionFailedError");
+var ErrorDuringVerificationError = createErrorClass("ErrorDuringVerificationError");
 
 // src/utils/logger.ts
 var SimpleLogger = class {
@@ -405,6 +406,10 @@ var constants = {
   get DEFAULT_RECLAIM_CALLBACK_URL() {
     return `${BACKEND_BASE_URL}/api/sdk/callback?callbackId=`;
   },
+  // Default error callback URL for Reclaim protocol
+  get DEFAULT_RECLAIM_ERROR_CALLBACK_URL() {
+    return `${BACKEND_BASE_URL}/api/sdk/error-callback?callbackId=`;
+  },
   // Default status URL for Reclaim sessions
   get DEFAULT_RECLAIM_STATUS_URL() {
     return `${BACKEND_BASE_URL}/api/sdk/session/`;
@@ -1861,6 +1866,8 @@ var emptyTemplateData = {
   context: "",
   parameters: {},
   redirectUrl: "",
+  errorCallbackUrl: "",
+  errorRedirectUrl: "",
   acceptAiProviders: false,
   sdkVersion: "",
   providerVersion: "",
@@ -1899,6 +1906,8 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
         resolvedProviderVersion: (_c = this.resolvedProviderVersion) != null ? _c : "",
         parameters: this.parameters,
         redirectUrl: (_d = this.redirectUrl) != null ? _d : "",
+        errorCallbackUrl: this.getErrorCallbackUrl(),
+        errorRedirectUrl: this.errorRedirectUrl,
         acceptAiProviders: (_f = (_e = this.options) == null ? void 0 : _e.acceptAiProviders) != null ? _f : false,
         sdkVersion: this.sdkVersion,
         jsonProofResponse: this.jsonProofResponse,
@@ -2064,6 +2073,8 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
           parameters,
           signature,
           redirectUrl,
+          errorCallbackUrl,
+          errorRedirectUrl,
           timeStamp,
           timestamp,
           appCallbackUrl,
@@ -2092,6 +2103,12 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
         if (appCallbackUrl) {
           validateURL(appCallbackUrl, "fromJsonString");
         }
+        if (errorRedirectUrl) {
+          validateURL(errorRedirectUrl, "fromJsonString");
+        }
+        if (errorCallbackUrl) {
+          validateURL(errorCallbackUrl, "fromJsonString");
+        }
         if (context) {
           validateContext(context);
         }
@@ -2130,6 +2147,8 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
         proofRequestInstance.resolvedProviderVersion = resolvedProviderVersion;
         proofRequestInstance.modalOptions = modalOptions;
         proofRequestInstance.jsonProofResponse = jsonProofResponse != null ? jsonProofResponse : false;
+        proofRequestInstance.errorCallbackUrl = errorCallbackUrl;
+        proofRequestInstance.errorRedirectUrl = errorRedirectUrl;
         return proofRequestInstance;
       } catch (error) {
         logger7.info("Failed to parse JSON string in fromJsonString:", error);
@@ -2178,6 +2197,41 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
     validateURL(url, "setRedirectUrl");
     this.redirectUrl = url;
   }
+  /**
+   * 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.setErrorCallbackUrl('https://your-backend.com/error-callback');
+   * ```
+   */
+  setErrorCallbackUrl(url) {
+    validateURL(url, "setErrorCallbackUrl");
+    this.errorCallbackUrl = url;
+  }
+  /**
+   * 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
+   * @throws {InvalidParamError} When URL is invalid
+   *
+   * @example
+   * ```typescript
+   * proofRequest.setErrorRedirectUrl('https://your-app.com/error');
+   * ```
+   */
+  setErrorRedirectUrl(url) {
+    validateURL(url, "setErrorRedirectUrl");
+    this.errorRedirectUrl = url;
+  }
   /**
    * Sets the claim creation type for the proof request
    *
@@ -2329,6 +2383,30 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       throw new GetAppCallbackUrlError("Error getting app callback url", error);
     }
   }
+  /**
+   * Returns the currently configured error callback URL
+   *
+   * If no custom error callback URL was set via setErrorCallbackUrl(), this returns the default
+   * Reclaim service error callback URL with the current session ID.
+   *
+   * @returns The error callback URL where proofs will be submitted
+   * @throws {GetAppCallbackUrlError} When unable to retrieve the error callback URL
+   *
+   * @example
+   * ```typescript
+   * const callbackUrl = proofRequest.getErrorCallbackUrl();
+   * console.log('Errors will be sent to:', callbackUrl);
+   * ```
+   */
+  getErrorCallbackUrl() {
+    try {
+      validateFunctionParams([{ input: this.sessionId, paramName: "sessionId", isString: true }], "getErrorCallbackUrl");
+      return this.errorCallbackUrl || `${constants.DEFAULT_RECLAIM_ERROR_CALLBACK_URL}${this.sessionId}`;
+    } catch (error) {
+      logger7.info("Error getting error callback url", error);
+      throw new GetAppCallbackUrlError("Error getting error callback url", error);
+    }
+  }
   /**
    * Returns the status URL for monitoring the current session
    *
@@ -2441,6 +2519,8 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       parameters: this.parameters,
       signature: this.signature,
       redirectUrl: this.redirectUrl,
+      errorCallbackUrl: this.errorCallbackUrl,
+      errorRedirectUrl: this.errorRedirectUrl,
       timestamp: this.timeStamp,
       // New field with correct spelling
       timeStamp: this.timeStamp,
@@ -2784,6 +2864,9 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
             }
             return;
           }
+          if (statusUrlResponse.session.statusV2 === "ERROR_SUBMISSION_FAILED" /* ERROR_SUBMISSION_FAILED */ || statusUrlResponse.session.statusV2 === "ERROR_SUBMITTED" /* ERROR_SUBMITTED */) {
+            throw new ErrorDuringVerificationError();
+          }
           const isDefaultCallbackUrl = this.getAppCallbackUrl() === `${constants.DEFAULT_RECLAIM_CALLBACK_URL}${this.sessionId}`;
           if (isDefaultCallbackUrl) {
             if (statusUrlResponse.session.proofs && statusUrlResponse.session.proofs.length > 0) {