@reclaimprotocol/js-sdk 4.10.0 → 4.11.0

package/README.md

@@ -8,6 +8,8 @@
 
 This guide will walk you through integrating the Reclaim Protocol JavaScript SDK into your application. We'll create a simple React application that demonstrates how to use the SDK to generate proofs and verify claims.
 
+[Official documentation](https://docs.reclaimprotocol.org/js-sdk/installation)
+
 ## Prerequisites
 
 Before we begin, make sure you have:
@@ -80,15 +82,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 +168,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 +287,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.
 
@@ -309,32 +314,96 @@ 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:
+Set a custom URL to redirect users after the verification process.
 
 ```javascript
 reclaimProofRequest.setRedirectUrl("https://example.com/redirect");
 ```
 
+Redirection with body:
+
+   - **url**: The URL where users should be redirected after successful proof generation.
+   - **method** (optional): The redirection method to use. Allowed options: `GET` (default) and `POST`. 
+     *Note: `POST` form redirection is only supported in In-Browser SDK.*
+   - **body** (optional): List of name-value pairs to be sent as the body of the form request.
+     - When `method` is `POST`, `body` is sent with `application/x-www-form-urlencoded` content type.
+     - When `method` is `GET`, if `body` is set, it is sent as query parameters.
+     *Note: Sending `body` on redirection is only supported in In-Browser SDK.*
+
+```javascript
+reclaimProofRequest.setRedirectUrl(
+  "https://example.com/redirect",
+  "POST", // In-Browser SDK only
+  [{ name: "foo", value: "bar" }]  // In-Browser SDK only
+);
+```
+
 4. **Custom Cancel Redirect URL**:
-   Set a custom URL to redirect users on a cancellation which aborts the verification process:
+   Set a custom URL to redirect users on a cancellation which aborts the verification process.
+
   
 ```javascript
 reclaimProofRequest.setCancelRedirectUrl("https://example.com/error-redirect");
 ```
 
+Redirection with body:
+
+   - **url**: The URL where users should be redirected after an error which aborts the verification process.
+   - **method** (optional): The redirection method to use. Allowed options: `GET` (default) and `POST`.
+     *Note: `POST` form redirection is only supported in In-Browser SDK.*
+   - **body** (optional): List of name-value pairs to be sent as the body of the form request.
+     - When `method` is `POST`, `body` is sent with `application/x-www-form-urlencoded` content type.
+     - When `method` is `GET`, if `body` is set, it is sent as query parameters.
+     *Note: Sending `body` on redirection is only supported in In-Browser SDK.*
+  
+```javascript
+reclaimProofRequest.setCancelRedirectUrl(
+  "https://example.com/error-redirect",
+  "POST",  // In-Browser SDK only
+  [{ name: "error_code", value: "1001" }]  // In-Browser SDK only
+);
+```
+
 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);
    ```
 
+This verification session's id will also 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.
+
 6. **Custom 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.setCancelCallbackUrl("https://example.com/error-callback");
-   
+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.setCancelCallbackUrl("https://example.com/error-callback");
+```
+
+When verificaiton is cancelled by user (or upon error when auto-submit is enabled), following data 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
+}
+```
+
+This verification session's id will also be present in `X-Reclaim-Session-Id` header of the request. 
+
+For more details about response format, check out [official documentation of Error Callback URL](https://docs.reclaimprotocol.org/js-sdk/preparing-request#cancel-callback).
+
 
 7. **Modal Customization for Desktop Users**:
    Customize the appearance and behavior of the QR code modal shown to desktop users:
@@ -476,6 +545,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 +590,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

@@ -49,11 +49,25 @@ type BeaconState = {
     nextEpochTimestampS: number;
 };
 
+type ClaimID = ProviderClaimData['identifier'];
+type ClaimInfo = Pick<ProviderClaimData, 'context' | 'provider' | 'parameters'>;
+type AnyClaimInfo = ClaimInfo | {
+    identifier: ClaimID;
+};
+type CompleteClaimData = Pick<ProviderClaimData, 'owner' | 'timestampS' | 'epoch'> & AnyClaimInfo;
+type SignedClaim = {
+    claim: CompleteClaimData;
+    signatures: Uint8Array[];
+};
+type CreateVerificationRequest = {
+    providerIds: string[];
+    applicationSecret?: string;
+};
 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 = {
     /**
@@ -142,6 +156,29 @@ declare enum DeviceType {
     DESKTOP = "desktop",
     MOBILE = "mobile"
 }
+type InitSessionResponse = {
+    sessionId: string;
+    resolvedProviderVersion: string;
+};
+interface UpdateSessionResponse {
+    success: boolean;
+    message?: string;
+}
+declare enum SessionStatus {
+    SESSION_INIT = "SESSION_INIT",
+    SESSION_STARTED = "SESSION_STARTED",
+    USER_INIT_VERIFICATION = "USER_INIT_VERIFICATION",
+    USER_STARTED_VERIFICATION = "USER_STARTED_VERIFICATION",
+    PROOF_GENERATION_STARTED = "PROOF_GENERATION_STARTED",
+    PROOF_GENERATION_SUCCESS = "PROOF_GENERATION_SUCCESS",
+    PROOF_GENERATION_FAILED = "PROOF_GENERATION_FAILED",
+    PROOF_SUBMITTED = "PROOF_SUBMITTED",
+    AI_PROOF_SUBMITTED = "AI_PROOF_SUBMITTED",
+    PROOF_SUBMISSION_FAILED = "PROOF_SUBMISSION_FAILED",
+    ERROR_SUBMITTED = "ERROR_SUBMITTED",
+    ERROR_SUBMISSION_FAILED = "ERROR_SUBMISSION_FAILED",
+    PROOF_MANUAL_VERIFICATION_SUBMITED = "PROOF_MANUAL_VERIFICATION_SUBMITED"
+}
 type ProofPropertiesJSON = {
     applicationId: string;
     providerId: string;
@@ -149,6 +186,7 @@ type ProofPropertiesJSON = {
     context: Context;
     signature: string;
     redirectUrl?: string;
+    redirectUrlOptions?: TemplateData['redirectUrlOptions'];
     parameters: {
         [key: string]: string;
     };
@@ -160,6 +198,7 @@ type ProofPropertiesJSON = {
     appCallbackUrl?: string;
     cancelCallbackUrl?: TemplateData['cancelCallbackUrl'];
     cancelRedirectUrl?: TemplateData['cancelRedirectUrl'];
+    cancelRedirectUrlOptions?: TemplateData['cancelRedirectUrlOptions'];
     claimCreationType?: ClaimCreationType;
     options?: ProofRequestOptions;
     sdkVersion: string;
@@ -167,6 +206,41 @@ type ProofPropertiesJSON = {
     resolvedProviderVersion: string;
     modalOptions?: SerializableModalOptions;
 };
+type HttpFormEntry = {
+    name: string;
+    value: string;
+};
+type HttpRedirectionMethod = 'GET' | 'POST';
+/**
+ * Options for HTTP redirection.
+ *
+ * Only supported by In-Browser SDK.
+ * On other SDKs, this will be ignored and a GET redirection will be performed with the URL.
+ *
+ * @since 4.11.0
+ * @default "{ method: 'GET' }"
+ */
+type HttpRedirectionOptions = {
+    /**
+     * 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`, `body` will be sent as query parameters.
+     *
+     * @default undefined
+     */
+    body?: HttpFormEntry[] | null | undefined;
+    /**
+     * HTTP method to use for the redirection.
+     *
+     * POST will result in `body` being sent with 'application/x-www-form-urlencoded' content type.
+     * GET will result in `body`, if present, being sent as query parameters.
+     *
+     * With `method` set to `GET` and no `body`, this will result in a simple GET redirection using `window.location.href`.
+     *
+     * @default 'GET'
+     */
+    method?: HttpRedirectionMethod;
+};
 type TemplateData = {
     sessionId: string;
     providerId: string;
@@ -179,8 +253,10 @@ type TemplateData = {
         [key: string]: string;
     };
     redirectUrl: string;
+    redirectUrlOptions?: HttpRedirectionOptions;
     cancelCallbackUrl?: string | null;
     cancelRedirectUrl?: string | null;
+    cancelRedirectUrlOptions?: HttpRedirectionOptions;
     acceptAiProviders: boolean;
     sdkVersion: string;
     jsonProofResponse?: boolean;
@@ -191,6 +267,18 @@ type TemplateData = {
     metadata?: Record<string, string>;
     preferredLocale?: ProofRequestOptions['preferredLocale'];
 };
+type StatusUrlResponse = {
+    message: string;
+    session?: {
+        id: string;
+        appId: string;
+        httpProviderId: string[];
+        sessionId: string;
+        proofs?: Proof[];
+        statusV2: string;
+    };
+    providerId?: string;
+};
 
 /**
  * Verifies one or more Reclaim proofs by validating signatures and witness information
@@ -237,8 +325,10 @@ declare class ReclaimProofRequest {
     private resolvedProviderVersion?;
     private parameters;
     private redirectUrl?;
+    private redirectUrlOptions?;
     private cancelCallbackUrl?;
     private cancelRedirectUrl?;
+    private cancelRedirectUrlOptions?;
     private intervals;
     private timeStamp;
     private sdkVersion;
@@ -292,16 +382,21 @@ 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.
+     *
+     * 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
      *
@@ -317,6 +412,13 @@ declare 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
@@ -324,7 +426,7 @@ declare class ReclaimProofRequest {
      * proofRequest.setRedirectUrl('https://your-app.com/success');
      * ```
      */
-    setRedirectUrl(url: string): void;
+    setRedirectUrl(url: string, method?: HttpRedirectionMethod, body?: HttpFormEntry[] | undefined): void;
     /**
      * Sets a custom callback URL where errors that abort the verification process will be submitted via HTTP POST
      *
@@ -333,6 +435,24 @@ declare class ReclaimProofRequest {
      * 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
      *
@@ -349,6 +469,12 @@ declare 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
@@ -359,7 +485,7 @@ declare class ReclaimProofRequest {
      * @since 4.10.0
      *
      */
-    setCancelRedirectUrl(url: string): void;
+    setCancelRedirectUrl(url: string, method?: HttpRedirectionMethod, body?: HttpFormEntry[] | undefined): void;
     /**
      * Sets the claim creation type for the proof request
      *
@@ -390,11 +516,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 +538,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 +738,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
@@ -683,4 +824,4 @@ declare function isDesktopDevice(): boolean;
  */
 declare function clearDeviceCache(): void;
 
-export { type Beacon, type BeaconState, ClaimCreationType, type Context, DeviceType, type ExtensionMessage, type ModalOptions, type Proof, type ProofPropertiesJSON, type ProviderClaimData, RECLAIM_EXTENSION_ACTIONS, ReclaimProofRequest, type WitnessData, clearDeviceCache, getDeviceType, getMobileDeviceType, isDesktopDevice, isMobileDevice, transformForOnchain, verifyProof };
+export { type AnyClaimInfo, type Beacon, type BeaconState, ClaimCreationType, type ClaimID, type ClaimInfo, type CompleteClaimData, type Context, type CreateVerificationRequest, DeviceType, type ExtensionMessage, type HttpFormEntry, type HttpRedirectionMethod, type HttpRedirectionOptions, type InitSessionResponse, type ModalOptions, type OnError, type OnSuccess, type Proof, type ProofPropertiesJSON, type ProofRequestOptions, type ProviderClaimData, RECLAIM_EXTENSION_ACTIONS, type ReclaimFlowLaunchOptions, ReclaimProofRequest, type SerializableModalOptions, SessionStatus, type SignedClaim, type StartSessionParams, type StatusUrlResponse, type TemplateData, type UpdateSessionResponse, type WitnessData, clearDeviceCache, getDeviceType, getMobileDeviceType, isDesktopDevice, isMobileDevice, transformForOnchain, verifyProof };