@reclaimprotocol/js-sdk 4.5.2 → 4.6.1

package/dist/index.d.ts

@@ -66,6 +66,22 @@ type ProofRequestOptions = {
     providerVersion?: string;
     customSharePageUrl?: string;
     customAppClipUrl?: string;
+    launchOptions?: ReclaimFlowLaunchOptions;
+};
+type ReclaimFlowLaunchOptions = {
+    /**
+     * Enables deferred deep links for the Reclaim verification flow.
+     *
+     * When enabled, users without the verifier app installed will receive a deferred deep link
+     * that automatically launches the verification flow after they install the app, ensuring
+     * a seamless continuation of the verification process.
+     *
+     * **Platform Support:** Currently Android only
+     *
+     * **Default Behavior:** Opt-in during rollout phase. Will default to `true` for all apps
+     * once fully released. See: https://blog.reclaimprotocol.org/posts/moving-beyond-google-play-instant
+     */
+    canUseDeferredDeepLinksFlow?: boolean;
 };
 type ModalOptions = {
     title?: string;
@@ -87,7 +103,35 @@ declare enum DeviceType {
     MOBILE = "mobile"
 }
 
+/**
+ * Verifies one or more Reclaim proofs by validating signatures and witness information
+ *
+ * @param proofOrProofs - A single proof object or an array of proof objects to verify
+ * @param allowAiWitness - Optional flag to allow AI witness verification. Defaults to false
+ * @returns Promise<boolean> - Returns true if all proofs are valid, false otherwise
+ * @throws {SignatureNotFoundError} When proof has no signatures
+ * @throws {ProofNotVerifiedError} When identifier mismatch occurs
+ *
+ * @example
+ * ```typescript
+ * const isValid = await verifyProof(proof);
+ * const areAllValid = await verifyProof([proof1, proof2, proof3]);
+ * const isValidWithAI = await verifyProof(proof, true);
+ * ```
+ */
 declare function verifyProof(proofOrProofs: Proof | Proof[], allowAiWitness?: boolean): Promise<boolean>;
+/**
+ * Transforms a Reclaim proof into a format suitable for on-chain verification
+ *
+ * @param proof - The proof object to transform
+ * @returns Object containing claimInfo and signedClaim formatted for blockchain contracts
+ *
+ * @example
+ * ```typescript
+ * const { claimInfo, signedClaim } = transformForOnchain(proof);
+ * // Use claimInfo and signedClaim with smart contract verification
+ * ```
+ */
 declare function transformForOnchain(proof: Proof): {
     claimInfo: any;
     signedClaim: any;
@@ -117,33 +161,344 @@ declare class ReclaimProofRequest {
     private modal?;
     private readonly FAILURE_TIMEOUT;
     private constructor();
+    /**
+     * Initializes a new Reclaim proof request instance with automatic signature generation and session creation
+     *
+     * @param applicationId - Your Reclaim application ID
+     * @param appSecret - Your application secret key for signing requests
+     * @param providerId - The ID of the provider to use for proof generation
+     * @param options - Optional configuration options for the proof request
+     * @returns Promise<ReclaimProofRequest> - A fully initialized proof request instance
+     * @throws {InitError} When initialization fails due to invalid parameters or session creation errors
+     *
+     * @example
+     * ```typescript
+     * const proofRequest = await ReclaimProofRequest.init(
+     *   'your-app-id',
+     *   'your-app-secret',
+     *   'provider-id',
+     *   { log: true, acceptAiProviders: true }
+     * );
+     * ```
+     */
     static init(applicationId: string, appSecret: string, providerId: string, options?: ProofRequestOptions): Promise<ReclaimProofRequest>;
+    /**
+     * Creates a ReclaimProofRequest instance from a JSON string representation
+     *
+     * This method deserializes a previously exported proof request (via toJsonString) and reconstructs
+     * the instance with all its properties. Useful for recreating requests on the frontend or across different contexts.
+     *
+     * @param jsonString - JSON string containing the serialized proof request data
+     * @returns {Promise<ReclaimProofRequest>} - Reconstructed proof request instance
+     * @throws {InvalidParamError} When JSON string is invalid or contains invalid parameters
+     *
+     * @example
+     * ```typescript
+     * const jsonString = proofRequest.toJsonString();
+     * const reconstructed = await ReclaimProofRequest.fromJsonString(jsonString);
+     * // Can also be used with InApp SDK's startVerificationFromJson method
+     * ```
+     */
     static fromJsonString(jsonString: string): Promise<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().
+     *
+     * 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 jsonProofResponse - Optional. Set to true to submit proofs as `application/json`. Defaults to false
+     * @throws {InvalidParamError} When URL is invalid
+     *
+     * @example
+     * ```typescript
+     * proofRequest.setAppCallbackUrl('https://your-backend.com/callback');
+     * // Or with JSON format
+     * proofRequest.setAppCallbackUrl('https://your-backend.com/callback', true);
+     * ```
+     */
     setAppCallbackUrl(url: string, jsonProofResponse?: boolean): void;
+    /**
+     * 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
+     * @throws {InvalidParamError} When URL is invalid
+     *
+     * @example
+     * ```typescript
+     * proofRequest.setRedirectUrl('https://your-app.com/success');
+     * ```
+     */
     setRedirectUrl(url: string): void;
+    /**
+     * Sets the claim creation type for the proof request
+     *
+     * @param claimCreationType - The type of claim creation (e.g., STANDALONE)
+     *
+     * @example
+     * ```typescript
+     * proofRequest.setClaimCreationType(ClaimCreationType.STANDALONE);
+     * ```
+     */
     setClaimCreationType(claimCreationType: ClaimCreationType): void;
+    /**
+     * Sets custom options for the QR code modal display
+     *
+     * @param options - Modal configuration options including title, description, theme, etc.
+     * @throws {SetParamsError} When modal options are invalid
+     *
+     * @example
+     * ```typescript
+     * proofRequest.setModalOptions({
+     *   title: 'Scan QR Code',
+     *   description: 'Scan with your mobile device',
+     *   darkTheme: true
+     * });
+     * ```
+     */
     setModalOptions(options: ModalOptions): void;
+    /**
+     * Sets additional context data to be stored with the claim
+     *
+     * 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 [setContext] which is an alternate way to set context that has an address & message.
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * proofRequest.setJsonContext({foo: 'bar'});
+     * ```
+     */
+    setJsonContext(context: Record<string, any>): void;
+    /**
+     * Sets additional context data to be stored with the claim
+     *
+     * 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.
+     *
+     * @param address - Context address identifier
+     * @param message - Additional data to associate with the address
+     * @throws {SetContextError} When context parameters are invalid
+     *
+     * @example
+     * ```typescript
+     * proofRequest.setContext('0x1234...', 'User verification for premium access');
+     * ```
+     */
     setContext(address: string, message: string): void;
+    /**
+     * @deprecated use setContext instead
+     *
+     * @param address
+     * @param message additional data you want associated with the [address]
+     */
     addContext(address: string, message: string): void;
+    /**
+     * Sets provider-specific parameters for the proof request
+     *
+     * These parameters are passed to the provider and may include configuration options,
+     * filters, or other provider-specific settings required for proof generation.
+     *
+     * @param params - Key-value pairs of parameters to set
+     * @throws {SetParamsError} When parameters are invalid
+     *
+     * @example
+     * ```typescript
+     * proofRequest.setParams({
+     *   minFollowers: '1000',
+     *   platform: 'twitter'
+     * });
+     * ```
+     */
     setParams(params: {
         [key: string]: string;
     }): void;
+    /**
+     * Returns the currently configured app callback URL
+     *
+     * If no custom callback URL was set via setAppCallbackUrl(), this returns the default
+     * Reclaim service callback URL with the current session ID.
+     *
+     * @returns The callback URL where proofs will be submitted
+     * @throws {GetAppCallbackUrlError} When unable to retrieve the callback URL
+     *
+     * @example
+     * ```typescript
+     * const callbackUrl = proofRequest.getAppCallbackUrl();
+     * console.log('Proofs will be sent to:', callbackUrl);
+     * ```
+     */
     getAppCallbackUrl(): string;
+    /**
+     * Returns the status URL for monitoring the current session
+     *
+     * This URL can be used to check the status of the proof request session.
+     *
+     * @returns The status monitoring URL for the current session
+     * @throws {GetStatusUrlError} When unable to retrieve the status URL
+     *
+     * @example
+     * ```typescript
+     * const statusUrl = proofRequest.getStatusUrl();
+     * // Use this URL to poll for session status updates
+     * ```
+     */
     getStatusUrl(): string;
+    /**
+     * Returns the session ID associated with this proof request
+     *
+     * The session ID is automatically generated during initialization and uniquely
+     * identifies this proof request session.
+     *
+     * @returns The session ID string
+     * @throws {SessionNotStartedError} When session ID is not set
+     *
+     * @example
+     * ```typescript
+     * const sessionId = proofRequest.getSessionId();
+     * console.log('Session ID:', sessionId);
+     * ```
+     */
     getSessionId(): string;
     private setSignature;
     private generateSignature;
     private clearInterval;
     private buildSharePageUrl;
+    /**
+     * Exports the Reclaim proof verification request as a JSON string
+     *
+     * This serialized format can be sent to the frontend to recreate this request using
+     * ReclaimProofRequest.fromJsonString() or any InApp SDK's startVerificationFromJson()
+     * method to initiate the verification journey.
+     *
+     * @returns JSON string representation of the proof request
+     *
+     * @example
+     * ```typescript
+     * const jsonString = proofRequest.toJsonString();
+     * // Send to frontend or store for later use
+     * // Can be reconstructed with: ReclaimProofRequest.fromJsonString(jsonString)
+     * ```
+     */
     toJsonString(): string;
-    getRequestUrl(): Promise<string>;
-    triggerReclaimFlow(): Promise<void>;
+    /**
+     * Validates signature and returns template data
+     * @returns
+     */
+    private getTemplateData;
+    /**
+     * Generates and returns the request URL for proof verification
+     *
+     * This URL can be shared with users to initiate the proof generation process.
+     * The URL format varies based on device type:
+     * - Mobile iOS: Returns App Clip URL (if useAppClip is enabled)
+     * - Mobile Android: Returns Instant App URL (if useAppClip is enabled)
+     * - Desktop/Other: Returns standard verification URL
+     *
+     * @param launchOptions - Optional launch configuration to override default behavior
+     * @returns Promise<string> - The generated request URL
+     * @throws {SignatureNotFoundError} When signature is not set
+     *
+     * @example
+     * ```typescript
+     * const requestUrl = await proofRequest.getRequestUrl();
+     * // Share this URL with users or display as QR code
+     * ```
+     */
+    getRequestUrl(launchOptions?: ReclaimFlowLaunchOptions): Promise<string>;
+    /**
+     * Triggers the appropriate Reclaim verification flow based on device type and configuration
+     *
+     * This method automatically detects the device type and initiates the optimal verification flow:
+     * - Desktop with browser extension: Triggers extension flow
+     * - Desktop without extension: Shows QR code modal
+     * - Mobile Android: Redirects to Instant App
+     * - Mobile iOS: Redirects to App Clip
+     *
+     * @param launchOptions - Optional launch configuration to override default behavior
+     * @returns Promise<void>
+     * @throws {SignatureNotFoundError} When signature is not set
+     *
+     * @example
+     * ```typescript
+     * await proofRequest.triggerReclaimFlow();
+     * // The appropriate verification method will be triggered automatically
+     * ```
+     */
+    triggerReclaimFlow(launchOptions?: ReclaimFlowLaunchOptions): Promise<void>;
+    /**
+     * Checks if the Reclaim browser extension is installed and available
+     *
+     * This method attempts to communicate with the browser extension to verify its availability.
+     * It uses a timeout mechanism to quickly determine if the extension responds.
+     *
+     * @param timeout - Timeout in milliseconds to wait for extension response. Defaults to 200ms
+     * @returns Promise<boolean> - True if extension is available, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const hasExtension = await proofRequest.isBrowserExtensionAvailable();
+     * if (hasExtension) {
+     *   console.log('Browser extension is installed');
+     * }
+     * ```
+     */
     isBrowserExtensionAvailable(timeout?: number): Promise<boolean>;
     private triggerBrowserExtensionFlow;
     private showQRCodeModal;
     private redirectToInstantApp;
     private redirectToAppClip;
+    /**
+     * Starts the proof request session and monitors for proof submission
+     *
+     * This method begins polling the session status to detect when
+     * a proof has been generated and submitted. It handles both default Reclaim callbacks
+     * 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
+     *
+     * @param onSuccess - Callback function invoked when proof is successfully submitted
+     * @param onError - Callback function invoked when an error occurs during the session
+     * @returns Promise<void>
+     * @throws {SessionNotStartedError} When session ID is not defined
+     * @throws {ProofNotVerifiedError} When proof verification fails (default callback only)
+     * @throws {ProofSubmissionFailedError} When proof submission fails (custom callback only)
+     * @throws {ProviderFailedError} When proof generation fails with timeout
+     *
+     * @example
+     * ```typescript
+     * await proofRequest.startSession({
+     *   onSuccess: (proof) => {
+     *     console.log('Proof received:', proof);
+     *   },
+     *   onError: (error) => {
+     *     console.error('Error:', error);
+     *   }
+     * });
+     * ```
+     */
     startSession({ onSuccess, onError }: StartSessionParams): Promise<void>;
+    /**
+     * Closes the QR code modal if it is currently open
+     *
+     * This method can be called to programmatically close the modal, for example,
+     * when implementing custom UI behavior or cleanup logic.
+     *
+     * @example
+     * ```typescript
+     * // Close modal after some condition
+     * proofRequest.closeModal();
+     * ```
+     */
     closeModal(): void;
 }