@reclaimprotocol/js-sdk 4.10.1 → 4.12.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:
@@ -312,19 +314,56 @@ 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:
    
@@ -335,12 +374,36 @@ reclaimProofRequest.setCancelRedirectUrl("https://example.com/error-redirect");
    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:

package/dist/index.d.ts

@@ -49,6 +49,20 @@ 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;
@@ -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
@@ -209,6 +297,7 @@ type TemplateData = {
  * ```
  */
 declare function verifyProof(proofOrProofs: Proof | Proof[], allowAiWitness?: boolean): Promise<boolean>;
+declare function assertValidProof(proofOrProofs: Proof | Proof[], allowAiWitness?: boolean): Promise<void>;
 /**
  * Transforms a Reclaim proof into a format suitable for on-chain verification
  *
@@ -237,8 +326,10 @@ declare class ReclaimProofRequest {
     private resolvedProviderVersion?;
     private parameters;
     private redirectUrl?;
+    private redirectUrlOptions?;
     private cancelCallbackUrl?;
     private cancelRedirectUrl?;
+    private cancelRedirectUrlOptions?;
     private intervals;
     private timeStamp;
     private sdkVersion;
@@ -301,6 +392,9 @@ declare class ReclaimProofRequest {
      * 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`
@@ -319,6 +413,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
@@ -326,7 +427,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
      *
@@ -335,6 +436,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
      *
@@ -351,6 +470,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
@@ -361,7 +486,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
      *
@@ -700,4 +825,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, assertValidProof, clearDeviceCache, getDeviceType, getMobileDeviceType, isDesktopDevice, isMobileDevice, transformForOnchain, verifyProof };