@reclaimprotocol/js-sdk 4.10.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.
 
@@ -324,7 +327,10 @@ 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`.
 
    reclaimProofRequest.setAppCallbackUrl("https://example.com/callback", true);
    ```
@@ -476,6 +482,9 @@ For production applications, it's recommended to handle proofs, and cancellation
 
 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
 
 The SDK provides a `verifyProof` function to manually verify proofs. This is useful when you need to validate proofs outside of the normal flow:
@@ -518,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 = {
     /**
@@ -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
      *
@@ -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
@@ -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.10.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",
@@ -2214,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
    *
@@ -2336,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
    *
@@ -2366,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
@@ -2879,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
@@ -2955,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();