@reclaimprotocol/js-sdk 4.8.1 → 4.10.0

package/README.md

@@ -308,32 +308,33 @@ The Reclaim SDK offers several advanced options to customize your integration:
    ```
 
 3. **Custom Redirect URL**:
-   Set a custom URL to redirect users after the verification process:
 
-   ```javascript
-   reclaimProofRequest.setRedirectUrl("https://example.com/redirect");
-   ```
+Set a custom URL to redirect users after the verification process:
 
-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");
-   ```
+```javascript
+reclaimProofRequest.setRedirectUrl("https://example.com/redirect");
+```
+
+4. **Custom Cancel Redirect URL**:
+   Set a custom URL to redirect users on a cancellation which aborts the verification process:
+  
+```javascript
+reclaimProofRequest.setCancelRedirectUrl("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.
 
-   ```javascript
    reclaimProofRequest.setAppCallbackUrl("https://example.com/callback", true);
    ```
 
 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:
+   Set a custom cancel callback URL for your app which allows you to receive user or provider initiated cancellation on your callback URL:
 
    ```javascript
-   reclaimProofRequest.setErrorCallbackUrl("https://example.com/error-callback");
-   ```
+   reclaimProofRequest.setCancelCallbackUrl("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:
@@ -442,21 +443,38 @@ const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER
 });
 ```
 
+15. Set preferred locale for verification client:
+
+An identifier used to select a user's language and formatting preferences.
+
+This represents a Unicode Language Identifier (i.e. without Locale extensions), except variants are not supported.
+Locales are expected to be canonicalized according to the "preferred value" entries in the [IANA Language Subtag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry). 
+For example, `he`, and `iw` are equal and both have the languageCode `he`, because `iw` is a deprecated language subtag that was replaced by the subtag `he`.
+
+Defaults to the browser's locale if available, otherwise English (en).
+
+```js
+// Initialize with options
+const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID, {
+  preferredLocale: 'en-US',
+});
+```
+
 ## Handling Proofs on Your Backend
 
-For production applications, it's recommended to handle proofs, and errors on your backend:
+For production applications, it's recommended to handle proofs, and cancellations on your backend:
 
 1. Set a callback URL:
    ```javascript
    reclaimProofRequest.setAppCallbackUrl("https://your-backend.com/receive-proofs");
    ```
 
-2. Set a error callback URL:
+2. Set a cancel callback URL:
    ```javascript
-   reclaimProofRequest.setErrorCallbackUrl("https://your-backend.com/receive-errors");
+   reclaimProofRequest.setCancelCallbackUrl("https://your-backend.com/receive-cancel");
    ```
 
-These options allow you to securely process proofs and status updates on your server.
+These options allow you to securely process proofs or cancellations on your server.
 
 ## Proof Verification
 

package/dist/index.d.ts

@@ -82,8 +82,21 @@ type ProofRequestOptions = {
      */
     canAutoSubmit?: boolean;
     /**
-     * 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.
+     * An identifier used to select a user's language and formatting preferences.
+     *
+     * Locales are expected to be canonicalized according to the "preferred value" entries in the [IANA Language Subtag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).
+     * For example, `he`, and `iw` are equal and both have the languageCode `he`, because `iw` is a deprecated language subtag that was replaced by the subtag `he`.
+     *
+     * Defaults to the browser's locale if available, otherwise English (en).
+     *
+     * For more info, refer: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#description
+     *
+     * @since 4.9.0
+     */
+    preferredLocale?: string;
+    /**
+     * Additional metadata to pass to the verification client frontend.
+     * This can be used to customize the client UI 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.
      *
      * This has no effect on the verification process.
@@ -145,8 +158,8 @@ type ProofPropertiesJSON = {
     timeStamp?: string;
     timestamp?: string;
     appCallbackUrl?: string;
-    errorCallbackUrl?: TemplateData['errorCallbackUrl'];
-    errorRedirectUrl?: TemplateData['errorRedirectUrl'];
+    cancelCallbackUrl?: TemplateData['cancelCallbackUrl'];
+    cancelRedirectUrl?: TemplateData['cancelRedirectUrl'];
     claimCreationType?: ClaimCreationType;
     options?: ProofRequestOptions;
     sdkVersion: string;
@@ -166,8 +179,8 @@ type TemplateData = {
         [key: string]: string;
     };
     redirectUrl: string;
-    errorCallbackUrl?: string | null;
-    errorRedirectUrl?: string | null;
+    cancelCallbackUrl?: string | null;
+    cancelRedirectUrl?: string | null;
     acceptAiProviders: boolean;
     sdkVersion: string;
     jsonProofResponse?: boolean;
@@ -176,6 +189,7 @@ type TemplateData = {
     log?: boolean;
     canAutoSubmit?: boolean;
     metadata?: Record<string, string>;
+    preferredLocale?: ProofRequestOptions['preferredLocale'];
 };
 
 /**
@@ -223,8 +237,8 @@ declare class ReclaimProofRequest {
     private resolvedProviderVersion?;
     private parameters;
     private redirectUrl?;
-    private errorCallbackUrl?;
-    private errorRedirectUrl?;
+    private cancelCallbackUrl?;
+    private cancelRedirectUrl?;
     private intervals;
     private timeStamp;
     private sdkVersion;
@@ -324,10 +338,13 @@ declare class ReclaimProofRequest {
      *
      * @example
      * ```typescript
-     * proofRequest.setErrorCallbackUrl('https://your-backend.com/error-callback');
+     * proofRequest.setCancelCallbackUrl('https://your-backend.com/error-callback');
      * ```
+     *
+     * @since 4.8.1
+     *
      */
-    setErrorCallbackUrl(url: string): void;
+    setCancelCallbackUrl(url: string): void;
     /**
      * Sets an error redirect URL where users will be redirected after an error which aborts the verification process
      *
@@ -336,10 +353,13 @@ declare class ReclaimProofRequest {
      *
      * @example
      * ```typescript
-     * proofRequest.setErrorRedirectUrl('https://your-app.com/error');
+     * proofRequest.setCancelRedirectUrl('https://your-app.com/error');
      * ```
+     *
+     * @since 4.10.0
+     *
      */
-    setErrorRedirectUrl(url: string): void;
+    setCancelRedirectUrl(url: string): void;
     /**
      * Sets the claim creation type for the proof request
      *
@@ -444,21 +464,21 @@ declare class ReclaimProofRequest {
      */
     getAppCallbackUrl(): string;
     /**
-     * Returns the currently configured error callback URL
+     * Returns the currently configured cancel 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.
+     * If no custom cancel callback URL was set via setCancelCallbackUrl(), this returns the default
+     * Reclaim service cancel 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
+     * @returns The cancel callback URL where proofs will be submitted
+     * @throws {GetAppCallbackUrlError} When unable to retrieve the cancel callback URL
      *
      * @example
      * ```typescript
-     * const callbackUrl = proofRequest.getErrorCallbackUrl();
+     * const callbackUrl = proofRequest.getCancelCallbackUrl();
      * console.log('Errors will be sent to:', callbackUrl);
      * ```
      */
-    getErrorCallbackUrl(): string;
+    getCancelCallbackUrl(): 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.8.1",
+      version: "4.10.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",
@@ -104,6 +104,7 @@ var require_package = __commonJS({
       },
       scripts: {
         build: "sh scripts/build.sh",
+        prepare: "npm run build",
         release: "release-it",
         test: "jest",
         "test:watch": "jest --watch",
@@ -407,7 +408,7 @@ var constants = {
     return `${BACKEND_BASE_URL}/api/sdk/callback?callbackId=`;
   },
   // Default error callback URL for Reclaim protocol
-  get DEFAULT_RECLAIM_ERROR_CALLBACK_URL() {
+  get DEFAULT_RECLAIM_CANCEL_CALLBACK_URL() {
     return `${BACKEND_BASE_URL}/api/sdk/error-callback?callbackId=`;
   },
   // Default status URL for Reclaim sessions
@@ -442,6 +443,12 @@ function validateFunctionParams(params, functionName) {
     }
   });
 }
+function validateFunctionParamsWithFn(param, functionName) {
+  if (!param.isValid()) {
+    logger3.info(`Validation failed: ${param.paramName} in ${functionName} is not valid`);
+    throw new InvalidParamError(`${param.paramName} passed to ${functionName} must be valid.`);
+  }
+}
 function validateParameters(parameters) {
   try {
     if (typeof parameters !== "object" || parameters === null) {
@@ -494,6 +501,18 @@ function validateSignature(providerId, signature, applicationId, timestamp) {
   }
 }
 function validateContext(context) {
+  if (context && !("contextAddress" in context)) {
+    try {
+      validateFunctionParams([
+        { input: context, paramName: "context", isString: false }
+      ], "validateContext");
+      JSON.parse(canonicalStringify(context));
+      return;
+    } catch (e) {
+      logger3.info(`Context validation failed: Provided JSON serializable context is not valid`);
+      throw new InvalidParamError(`The provided context is not valid`);
+    }
+  }
   if (!context.contextAddress) {
     logger3.info(`Context validation failed: Provided context address in context is not valid`);
     throw new InvalidParamError(`The provided context address in context is not valid`);
@@ -1866,8 +1885,8 @@ var emptyTemplateData = {
   context: "",
   parameters: {},
   redirectUrl: "",
-  errorCallbackUrl: "",
-  errorRedirectUrl: "",
+  cancelCallbackUrl: "",
+  cancelRedirectUrl: "",
   acceptAiProviders: false,
   sdkVersion: "",
   providerVersion: "",
@@ -1889,7 +1908,7 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
      * @returns 
      */
     this.getTemplateData = () => {
-      var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
+      var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
       if (!this.signature) {
         throw new SignatureNotFoundError("Signature is not set.");
       }
@@ -1906,14 +1925,15 @@ 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,
+        cancelCallbackUrl: this.getCancelCallbackUrl(),
+        cancelRedirectUrl: this.cancelRedirectUrl,
         acceptAiProviders: (_f = (_e = this.options) == null ? void 0 : _e.acceptAiProviders) != null ? _f : false,
         sdkVersion: this.sdkVersion,
         jsonProofResponse: this.jsonProofResponse,
         log: (_h = (_g = this.options) == null ? void 0 : _g.log) != null ? _h : false,
         canAutoSubmit: (_j = (_i = this.options) == null ? void 0 : _i.canAutoSubmit) != null ? _j : true,
-        metadata: (_k = this.options) == null ? void 0 : _k.metadata
+        metadata: (_k = this.options) == null ? void 0 : _k.metadata,
+        preferredLocale: (_l = this.options) == null ? void 0 : _l.preferredLocale
       };
       return templateData;
     };
@@ -2031,6 +2051,24 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
               { paramName: "customAppClipUrl", input: options.customAppClipUrl, isString: true }
             ], "the constructor");
           }
+          if (options.preferredLocale) {
+            validateFunctionParams([
+              { paramName: "preferredLocale", input: options.preferredLocale, isString: true }
+            ], "the constructor");
+            validateFunctionParamsWithFn({
+              paramName: "preferredLocale",
+              input: options.preferredLocale,
+              isValid: () => {
+                try {
+                  Intl.getCanonicalLocales(options.preferredLocale);
+                  return true;
+                } catch (error) {
+                  logger7.info("Failed to canonicalize locale", error);
+                  return false;
+                }
+              }
+            }, "the constructor");
+          }
         }
         const proofRequestInstance = new _ReclaimProofRequest(applicationId, providerId, options);
         const signature = yield proofRequestInstance.generateSignature(appSecret);
@@ -2040,6 +2078,7 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
         proofRequestInstance.resolvedProviderVersion = data.resolvedProviderVersion;
         return proofRequestInstance;
       } catch (error) {
+        console.error(error);
         logger7.info("Failed to initialize ReclaimProofRequest", error);
         throw new InitError("Failed to initialize ReclaimProofRequest", error);
       }
@@ -2073,8 +2112,8 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
           parameters,
           signature,
           redirectUrl,
-          errorCallbackUrl,
-          errorRedirectUrl,
+          cancelCallbackUrl,
+          cancelRedirectUrl,
           timeStamp,
           timestamp,
           appCallbackUrl,
@@ -2103,11 +2142,11 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
         if (appCallbackUrl) {
           validateURL(appCallbackUrl, "fromJsonString");
         }
-        if (errorRedirectUrl) {
-          validateURL(errorRedirectUrl, "fromJsonString");
+        if (cancelRedirectUrl) {
+          validateURL(cancelRedirectUrl, "fromJsonString");
         }
-        if (errorCallbackUrl) {
-          validateURL(errorCallbackUrl, "fromJsonString");
+        if (cancelCallbackUrl) {
+          validateURL(cancelCallbackUrl, "fromJsonString");
         }
         if (context) {
           validateContext(context);
@@ -2127,7 +2166,7 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
         }
         if (options == null ? void 0 : options.providerVersion) {
           validateFunctionParams([
-            { input: options.providerVersion, paramName: "providerVersion", isString: true }
+            { input: options.providerVersion, paramName: "options.providerVersion", isString: true }
           ], "fromJsonString");
         }
         if (resolvedProviderVersion) {
@@ -2135,6 +2174,24 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
             { input: resolvedProviderVersion, paramName: "resolvedProviderVersion", isString: true }
           ], "fromJsonString");
         }
+        if (options == null ? void 0 : options.preferredLocale) {
+          validateFunctionParams([
+            { paramName: "options.preferredLocale", input: options.preferredLocale, isString: true }
+          ], "fromJsonString");
+          validateFunctionParamsWithFn({
+            paramName: "options.preferredLocale",
+            input: options.preferredLocale,
+            isValid: () => {
+              try {
+                Intl.getCanonicalLocales(options.preferredLocale);
+                return true;
+              } catch (error) {
+                logger7.info("Failed to canonicalize locale", error);
+                return false;
+              }
+            }
+          }, "fromJsonString");
+        }
         const proofRequestInstance = new _ReclaimProofRequest(applicationId, providerId, options);
         proofRequestInstance.sessionId = sessionId;
         proofRequestInstance.context = context;
@@ -2147,8 +2204,8 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
         proofRequestInstance.resolvedProviderVersion = resolvedProviderVersion;
         proofRequestInstance.modalOptions = modalOptions;
         proofRequestInstance.jsonProofResponse = jsonProofResponse != null ? jsonProofResponse : false;
-        proofRequestInstance.errorCallbackUrl = errorCallbackUrl;
-        proofRequestInstance.errorRedirectUrl = errorRedirectUrl;
+        proofRequestInstance.cancelCallbackUrl = cancelCallbackUrl;
+        proofRequestInstance.cancelRedirectUrl = cancelRedirectUrl;
         return proofRequestInstance;
       } catch (error) {
         logger7.info("Failed to parse JSON string in fromJsonString:", error);
@@ -2210,12 +2267,15 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
    *
    * @example
    * ```typescript
-   * proofRequest.setErrorCallbackUrl('https://your-backend.com/error-callback');
+   * proofRequest.setCancelCallbackUrl('https://your-backend.com/error-callback');
    * ```
+   * 
+   * @since 4.8.1
+   * 
    */
-  setErrorCallbackUrl(url) {
-    validateURL(url, "setErrorCallbackUrl");
-    this.errorCallbackUrl = url;
+  setCancelCallbackUrl(url) {
+    validateURL(url, "setCancelCallbackUrl");
+    this.cancelCallbackUrl = url;
   }
   /**
    * Sets an error redirect URL where users will be redirected after an error which aborts the verification process
@@ -2225,12 +2285,15 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
    *
    * @example
    * ```typescript
-   * proofRequest.setErrorRedirectUrl('https://your-app.com/error');
+   * proofRequest.setCancelRedirectUrl('https://your-app.com/error');
    * ```
+   * 
+   * @since 4.10.0
+   * 
    */
-  setErrorRedirectUrl(url) {
-    validateURL(url, "setErrorRedirectUrl");
-    this.errorRedirectUrl = url;
+  setCancelRedirectUrl(url) {
+    validateURL(url, "setCancelRedirectUrl");
+    this.cancelRedirectUrl = url;
   }
   /**
    * Sets the claim creation type for the proof request
@@ -2384,27 +2447,27 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
     }
   }
   /**
-   * Returns the currently configured error callback URL
+   * Returns the currently configured cancel 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.
+   * If no custom cancel callback URL was set via setCancelCallbackUrl(), this returns the default
+   * Reclaim service cancel 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
+   * @returns The cancel callback URL where proofs will be submitted
+   * @throws {GetAppCallbackUrlError} When unable to retrieve the cancel callback URL
    *
    * @example
    * ```typescript
-   * const callbackUrl = proofRequest.getErrorCallbackUrl();
+   * const callbackUrl = proofRequest.getCancelCallbackUrl();
    * console.log('Errors will be sent to:', callbackUrl);
    * ```
    */
-  getErrorCallbackUrl() {
+  getCancelCallbackUrl() {
     try {
-      validateFunctionParams([{ input: this.sessionId, paramName: "sessionId", isString: true }], "getErrorCallbackUrl");
-      return this.errorCallbackUrl || `${constants.DEFAULT_RECLAIM_ERROR_CALLBACK_URL}${this.sessionId}`;
+      validateFunctionParams([{ input: this.sessionId, paramName: "sessionId", isString: true }], "getCancelCallbackUrl");
+      return this.cancelCallbackUrl || `${constants.DEFAULT_RECLAIM_CANCEL_CALLBACK_URL}${this.sessionId}`;
     } catch (error) {
-      logger7.info("Error getting error callback url", error);
-      throw new GetAppCallbackUrlError("Error getting error callback url", error);
+      logger7.info("Error getting cancel callback url", error);
+      throw new GetAppCallbackUrlError("Error getting cancel callback url", error);
     }
   }
   /**
@@ -2519,8 +2582,8 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       parameters: this.parameters,
       signature: this.signature,
       redirectUrl: this.redirectUrl,
-      errorCallbackUrl: this.errorCallbackUrl,
-      errorRedirectUrl: this.errorRedirectUrl,
+      cancelCallbackUrl: this.cancelCallbackUrl,
+      cancelRedirectUrl: this.cancelRedirectUrl,
       timestamp: this.timeStamp,
       // New field with correct spelling
       timeStamp: this.timeStamp,