@reclaimprotocol/js-sdk 4.9.0 → 4.10.1

package/README.md

@@ -80,15 +80,17 @@ function App() {
 
     await reclaimProofRequest.startSession({
       onSuccess: (proofs) => {
-        if (proofs && typeof proofs === "string") {
-          // When using a custom callback url, the proof is returned to the callback url and we get a message instead of a proof
-          console.log("SDK Message:", proofs);
-          setProofs(proofs);
-        } else if (proofs && typeof proofs !== "string") {
+        if (proofs && typeof proofs !== "string") {
           // When using the default callback url, we get a proof
           if (Array.isArray(proofs)) {
-            // when using the cascading providers, providers having more than one proof will return an array of proofs
-            console.log(JSON.stringify(proofs.map((p) => p.claimData.context)));
+            if (proofs.length == 0) {
+              // From version 4.10.1, this is the case when using a custom callback url
+              // Proofs are sent to the callback url.
+              console.log("No proofs received. This is expected when using a custom callback url.");
+            } else {
+              // when using the cascading providers, providers having more than one proof will return an array of proofs
+              console.log(JSON.stringify(proofs.map((p) => p.claimData.context)));
+            }
           } else {
             console.log("Proof received:", proofs?.claimData.context);
           }
@@ -164,12 +166,13 @@ async function handleCreateClaim() {
     // Listen for the verification results
     await reclaimProofRequest.startSession({
       onSuccess: (proofs) => {
-        if (proofs && typeof proofs === "string") {
-          console.log("SDK Message:", proofs);
-          setProofs(proofs);
-        } else if (proofs && typeof proofs !== "string") {
+        if (proofs && typeof proofs !== "string") {
           if (Array.isArray(proofs)) {
-            console.log(JSON.stringify(proofs.map((p) => p.claimData.context)));
+            if (proofs.length == 0) {
+              // proofs sent to callback url
+            } else {
+              console.log(JSON.stringify(proofs.map((p) => p.claimData.context)));
+            }
           } else {
             console.log("Proof received:", proofs?.claimData.context);
           }
@@ -282,7 +285,7 @@ Your Reclaim SDK demo should now be running. Click the "Create Claim" button to
 
 3. **Status URL**: This URL (logged to the console) can be used to check the status of the claim process. It's useful for tracking the progress of verification.
 
-4. **Verification**: The `onSuccess` is called when verification is successful, providing the proof data. When using a custom callback url, the proof is returned to the callback url and we get a message instead of a proof.
+4. **Verification**: The `onSuccess` is called when verification is successful, providing the proof data. When using a custom callback url, the proof is returned to the callback url and we get an empty array instead of a proof.
 
 5. **Handling Failures**: The `onFailure` is called if verification fails, allowing you to handle errors gracefully.
 
@@ -308,32 +311,36 @@ 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.
+   
+   **Note**: When a custom callback URL is set, proofs are sent to the custom URL *instead* of the Reclaim backend. Consequently, the `onSuccess` callback will be invoked with an empty array (`[]`) instead of the proof data.
+
+   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`.
 
-   ```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:
@@ -461,19 +468,22 @@ const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER
 
 ## 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.
+
+> [!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.
 
 ## Proof Verification
 
@@ -517,8 +527,9 @@ try {
   const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID);
 
   await proofRequest.startSession({
-    onSuccess: (proof) => {
-      console.log("Proof received:", proof);
+    onSuccess: (proofs) => {
+      // proofs can be empty if callback url set
+      console.log("Proof received:", proofs);
     },
     onError: (error) => {
       // Handle different error types

package/dist/index.d.ts

@@ -53,7 +53,7 @@ type StartSessionParams = {
     onSuccess: OnSuccess;
     onError: OnError;
 };
-type OnSuccess = (proof?: Proof | Proof[] | string) => void;
+type OnSuccess = (proof?: Proof | Proof[]) => void;
 type OnError = (error: Error) => void;
 type ProofRequestOptions = {
     /**
@@ -95,8 +95,8 @@ type ProofRequestOptions = {
      */
     preferredLocale?: string;
     /**
-     * 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.
+     * 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.
@@ -158,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;
@@ -179,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;
@@ -237,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;
@@ -292,16 +292,18 @@ declare class ReclaimProofRequest {
      */
     static fromJsonString(jsonString: string): Promise<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.
      *
      * 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
      *
@@ -338,13 +340,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
      *
@@ -353,13 +355,13 @@ declare class ReclaimProofRequest {
      *
      * @example
      * ```typescript
-     * proofRequest.setErrorRedirectUrl('https://your-app.com/error');
+     * proofRequest.setCancelRedirectUrl('https://your-app.com/error');
      * ```
      *
-     * @since 4.8.1
+     * @since 4.10.0
      *
      */
-    setErrorRedirectUrl(url: string): void;
+    setCancelRedirectUrl(url: string): void;
     /**
      * Sets the claim creation type for the proof request
      *
@@ -390,11 +392,13 @@ declare 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
      *
@@ -410,6 +414,10 @@ declare 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
@@ -464,21 +472,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
      *
@@ -606,7 +614,16 @@ declare 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

package/dist/index.js

@@ -72,7 +72,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@reclaimprotocol/js-sdk",
-      version: "4.9.0",
+      version: "4.10.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",
@@ -408,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
@@ -501,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`);
@@ -1873,8 +1885,8 @@ var emptyTemplateData = {
   context: "",
   parameters: {},
   redirectUrl: "",
-  errorCallbackUrl: "",
-  errorRedirectUrl: "",
+  cancelCallbackUrl: "",
+  cancelRedirectUrl: "",
   acceptAiProviders: false,
   sdkVersion: "",
   providerVersion: "",
@@ -1913,8 +1925,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,
+        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,
@@ -2066,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);
       }
@@ -2099,8 +2112,8 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
           parameters,
           signature,
           redirectUrl,
-          errorCallbackUrl,
-          errorRedirectUrl,
+          cancelCallbackUrl,
+          cancelRedirectUrl,
           timeStamp,
           timestamp,
           appCallbackUrl,
@@ -2129,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);
@@ -2191,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);
@@ -2201,16 +2214,18 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
     });
   }
   /**
-   * 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().
+   * Sets a custom callback URL where proofs will be submitted via HTTP `POST`
    *
+   * 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.
+   * 
    * 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
    *
@@ -2254,15 +2269,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
@@ -2272,15 +2287,15 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
    *
    * @example
    * ```typescript
-   * proofRequest.setErrorRedirectUrl('https://your-app.com/error');
+   * proofRequest.setCancelRedirectUrl('https://your-app.com/error');
    * ```
    * 
-   * @since 4.8.1
+   * @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
@@ -2323,11 +2338,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
    *
@@ -2353,6 +2370,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
@@ -2434,27 +2455,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);
     }
   }
   /**
@@ -2569,8 +2590,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,
@@ -2866,7 +2887,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
@@ -2942,7 +2972,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();