@reclaimprotocol/js-sdk 1.3.11 → 2.0.1

package/README.md

@@ -1,152 +1,112 @@
-# Reclaim js-sdk
+<div>
+    <div>
+        <img src="https://raw.githubusercontent.com/reclaimprotocol/.github/main/assets/banners/JS-SDK.png"  />
+    </div>
+</div>
 
-This README provides a step-by-step guide on integrating the Reclaim Protocol JavaScript SDK into application
+# Reclaim Protocol JavaScript SDK Integration Guide
 
-## Pre-requisites
+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.
 
-- An application ID from Reclaim Protocol. You can get one from the [Reclaim Developer Protocol](https://dev.reclaimprotocol.org/)
+## Prerequisites
 
-## Create a new React application
+Before we begin, make sure you have:
 
-```bash
-npx create-react-app reclaim-app
-cd reclaim-app
-```
+1. An application ID from Reclaim Protocol.
+2. An application secret from Reclaim Protocol.
+3. A provider ID for the specific service you want to verify.
 
-## Install the Reclaim Protocol JS-SDK
+You can obtain these details from the [Reclaim Developer Portal](https://dev.reclaimprotocol.org/).
 
-```bash
-npm install @reclaimprotocol/js-sdk
-```
+## Step 1: Create a new React application
 
-## Install other dependencies
+Let's start by creating a new React application:
 
 ```bash
-npm i react-qr-code
-```
-
-## Import dependencies
-
-In your `src/App.js` file, import the Reclaim SDK and the QR code generator
-
-```javascript
-import { useState, useEffect } from 'react'
-import { Reclaim } from '@reclaimprotocol/js-sdk'
-import QRCode from 'react-qr-code'
+npx create-react-app reclaim-app
+cd reclaim-app
 ```
 
-## Initialize the Reclaim SDK
-
-Declare your `application ID` and initialize the Reclaim Protocol client. Replace `YOUR_APPLICATION_ID_HERE` with the actual application ID provided by Reclaim Protocol.
-
-File: `src/App.js`
-
-```javascript
-import './App.css'
-import { useState, useEffect } from 'react'
-import { Reclaim } from '@reclaimprotocol/js-sdk'
-import QRCode from 'react-qr-code'
-
-function App() {
-  const APP_ID = 'YOUR_APPLICATION_ID_HERE'
-  const reclaimProofRequest = new Reclaim.ProofRequest(APP_ID)
+## Step 2: Install necessary dependencies
 
-  return (
-    <div className='App'>
-      <header className='App-header'>
-        <p>Reclaim App</p>
-      </header>
-    </div>
-  )
-}
+Install the Reclaim Protocol SDK and a QR code generator:
 
-export default App
+```bash
+npm install @reclaimprotocol/js-sdk react-qr-code
 ```
 
-## Implement Verification Request Function
-
-Create functions to handle the verification request. You'll need separate functions for prototype and production modes due to the different handling of the application secret and signature.
-
-### Prototype Mode
+## Step 3: Set up your React component
 
-For testing purposes, use the prototype mode. Note that in production, you should handle the application secret securely on your server.
-
-File: `src/App.js`
+Replace the contents of `src/App.js` with the following code:
 
 ```javascript
-import './App.css'
-import { useState, useEffect } from 'react'
-import { Reclaim } from '@reclaimprotocol/js-sdk'
+import React, { useState, useEffect } from 'react'
+import { ReclaimProofRequest } from '@reclaimprotocol/js-sdk'
 import QRCode from 'react-qr-code'
 
 function App() {
+  const [reclaimProofRequest, setReclaimProofRequest] = useState(null)
   const [requestUrl, setRequestUrl] = useState('')
-  const [proofs, setProofs] = useState([])
-
-  const APP_ID = 'YOUR_APPLICATION_ID_HERE'
+  const [statusUrl, setStatusUrl] = useState('')
+  const [proofs, setProofs] = useState(null)
+
+  useEffect(() => {
+    async function initializeReclaim() {
+      const APP_ID = 'YOUR_APPLICATION_ID_HERE'
+      const APP_SECRET = 'YOUR_APPLICATION_SECRET_HERE'
+      const PROVIDER_ID = 'YOUR_PROVIDER_ID_HERE'
+
+      const proofRequest = await ReclaimProofRequest.init(
+        APP_ID,
+        APP_SECRET,
+        PROVIDER_ID
+      )
+      setReclaimProofRequest(proofRequest)
+    }
 
-  const reclaimProofRequest = new Reclaim.ProofRequest(APP_ID)
+    initializeReclaim()
+  }, [])
 
-  async function createVerificationRequest() {
-    // id of the provider you want to generate the proof for
-    await reclaimProofRequest.buildProofRequest('PROVIDER_ID')
+  async function handleCreateClaim() {
+    if (!reclaimProofRequest) {
+      console.error('Reclaim Proof Request not initialized')
+      return
+    }
 
-    reclaimProofRequest.setSignature(
-      await reclaimProofRequest.generateSignature(
-        'YOUR_APPLICATION_SECRET' // Handle securely for production
-      )
-    )
+    const url = await reclaimProofRequest.getRequestUrl()
+    setRequestUrl(url)
 
-    const { requestUrl, statusUrl } =
-      await reclaimProofRequest.createVerificationRequest()
+    const status = reclaimProofRequest.getStatusUrl()
+    setStatusUrl(status)
+    console.log('Status URL:', status)
 
     await reclaimProofRequest.startSession({
-      onSuccessCallback: proofs => {
+      onSuccess: (proofs) => {
         console.log('Verification success', proofs)
         setProofs(proofs)
-        // Your business logic here
       },
-      onFailureCallback: error => {
+      onFailure: (error) => {
         console.error('Verification failed', error)
-        // Your business logic here to handle the error
       }
     })
-
-    setRequestUrl(requestUrl)
   }
 
   return (
-    <div className='App'>
-      <header className='App-header'>
-        <p>Reclaim App</p>
-        <button
-          onClick={createVerificationRequest}
-          style={{ marginBottom: '20px', padding: '10px', cursor: 'pointer' }}
-        >
-          Create Verification Request
-        </button>
-        <div style={{ backgroundColor: 'white', padding: '10px' }}>
-          {requestUrl && (
-            <div style={{ backgroundColor: 'white', padding: '10px' }}>
-              <QRCode value={requestUrl} />
-            </div>
-          )}
-          {proofs.length > 0 && (
-            <div>
-              <h3>Proofs</h3>
-              <ul>
-                {proofs.map((proof, index) => {
-                  return (
-                    <p key={index}>
-                      {JSON.stringify(proof.extractedParameterValues)}
-                    </p>
-                  )
-                })}
-              </ul>
-            </div>
-          )}
+    <div className="App">
+      <h1>Reclaim Protocol Demo</h1>
+      <button onClick={handleCreateClaim}>Create Claim</button>
+      {requestUrl && (
+        <div>
+          <h2>Scan this QR code to start the verification process:</h2>
+          <QRCode value={requestUrl} />
+        </div>
+      )}
+      {proofs && (
+        <div>
+          <h2>Verification Successful!</h2>
+          <pre>{JSON.stringify(proofs, null, 2)}</pre>
         </div>
-      </header>
+      )}
     </div>
   )
 }
@@ -154,52 +114,136 @@ function App() {
 export default App
 ```
 
-### Production Mode
+## Step 4: Understanding the code
 
-In production mode, securely fetch and set the signature from your backend instead of using the application secret directly in the client.
+Let's break down what's happening in this code:
 
-Similar to the prototype mode but ensure to fetch and set the signature securely
+1. We initialize the Reclaim SDK with your application ID, secret, and provider ID. This happens once when the component mounts.
 
-```javascript
-async function createVerificationRequestProductionMode() {
-  // id of the provider you want to generate the proof for
-  await reclaimProofRequest.buildProofRequest('PROVIDER_ID')
-
-  reclaim
-    .setSignature
-    // TODO: fetch signature from your backend
-    // On the backend, generate signature using:
-    // await Reclaim.getSignature(requestedProofs, APP_SECRET)
-    ()
-
-  const { requestUrl, statusUrl } =
-    await reclaimProofRequest.createVerificationRequest()
-
-  await reclaimProofRequest.startSession({
-    onSuccessCallback: proofs => {
-      console.log('Verification success', proofs)
-      setProofs(proofs)
-      // Your business logic here
-    },
-    onFailureCallback: error => {
-      console.error('Verification failed', error)
-      // Your business logic here to handle the error
-    }
-  })
+2. When the user clicks the "Create Claim" button, we:
+   - Generate a request URL using `getRequestUrl()`. This URL is used to create the QR code.
+   - Get the status URL using `getStatusUrl()`. This URL can be used to check the status of the claim process.
+   - Start a session with `startSession()`, which sets up callbacks for successful and failed verifications.
 
-  setRequestUrl(requestUrl)
-}
-```
+3. We display a QR code using the request URL. When a user scans this code, it starts the verification process.
+
+4. The status URL is logged to the console. You can use this URL to check the status of the claim process programmatically.
+
+5. When the verification is successful, we display the proof data on the page.
+
+## Step 5: Run your application
 
-## Run the application
+Start your development server:
 
 ```bash
 npm start
 ```
 
+Your Reclaim SDK demo should now be running. Click the "Create Claim" button to generate a QR code. Scan this code to start the verification process.
+
+## Understanding the Claim Process
+
+1. **Creating a Claim**: When you click "Create Claim", the SDK generates a unique request for verification.
+
+2. **QR Code**: The QR code contains the request URL. When scanned, it initiates the verification process.
+
+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.
+
+5. **Handling Failures**: The `onFailure` is called if verification fails, allowing you to handle errors gracefully.
+
 ## Advanced Configuration
 
-You can configure Reclaim SDK to receive proofs in your preferref backend by setting up a callback URL. This is useful if you want to handle the proofs in your backend.
+The Reclaim SDK offers several advanced options to customize your integration:
+
+1. **Adding Context**:
+   You can add context to your proof request, which can be useful for providing additional information:
+   ```javascript
+   reclaimProofRequest.addContext('0x00000000000', 'Example context message')
+   ```
+
+2. **Setting Parameters**:
+   If your provider requires specific parameters, you can set them like this:
+   ```javascript
+   reclaimProofRequest.setParams({ email: "test@example.com", userName: "testUser" })
+   ```
+
+3. **Custom Redirect URL**:
+   Set a custom URL to redirect users after the verification process:
+   ```javascript
+   reclaimProofRequest.setRedirectUrl('https://example.com/redirect')
+   ```
+
+4. **Custom Callback URL**:
+   Set a custom callback URL for your app which allows you to receive proofs and status updates on your callback URL:
+   ```javascript
+   reclaimProofRequest.setAppCallbackUrl('https://example.com/callback')
+   ```
+
+5. **Exporting and Importing SDK Configuration**:
+   You can export the entire Reclaim SDK configuration as a JSON string and use it to initialize the SDK with the same configuration on a different service or backend:
+   ```javascript
+   // On the client-side or initial service
+   const configJson = reclaimProofRequest.toJsonString()
+   console.log('Exportable config:', configJson)
+   
+   // Send this configJson to your backend or another service
+   
+   // On the backend or different service
+   const importedRequest = ReclaimProofRequest.fromJsonString(configJson)
+   const requestUrl = await importedRequest.getRequestUrl()
+   ```
+   This allows you to generate request URLs and other details from your backend or a different service while maintaining the same configuration.
+
+## Handling Proofs on Your Backend
+
+For production applications, it's recommended to handle proofs on your backend:
+
+1. Set a callback URL:
+   ```javascript
+   reclaimProofRequest.setCallbackUrl('https://your-backend.com/receive-proofs')
+   ```
+
+2. Set a custom status URL:
+   ```javascript
+   reclaimProofRequest.setStatusUrl('https://your-backend.com/receive-status')
+   ```
+
+These options allow you to securely process proofs and status updates on your server.
+
+## Next Steps
+
+Explore the [Reclaim Protocol documentation](https://docs.reclaimprotocol.org/) for more advanced features and best practices for integrating the SDK into your production applications.
+
+Happy coding with Reclaim Protocol!
+
+## Contributing to Our Project
+
+We welcome contributions to our project! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.
+
+## Security Note
+
+Always keep your Application Secret secure. Never expose it in client-side code or public repositories.
+
+## Code of Conduct
+
+Please read and follow our [Code of Conduct](https://github.com/reclaimprotocol/.github/blob/main/Code-of-Conduct.md) to ensure a positive and inclusive environment for all contributors.
+
+## Security
+
+If you discover any security-related issues, please refer to our [Security Policy](https://github.com/reclaimprotocol/.github/blob/main/SECURITY.md) for information on how to responsibly disclose vulnerabilities.
+
+## Contributor License Agreement
+
+Before contributing to this project, please read and sign our [Contributor License Agreement (CLA)](https://github.com/reclaimprotocol/.github/blob/main/CLA.md).
+
+## Indie Hackers
+
+For Indie Hackers: [Check out our guidelines and potential grant opportunities](https://github.com/reclaimprotocol/.github/blob/main/Indie-Hackers.md)
+
+## License
+
+This project is licensed under a [custom license](https://github.com/reclaimprotocol/.github/blob/main/LICENSE). By contributing to this project, you agree that your contributions will be licensed under its terms.
 
-- **Set Callback Url** - `reclaim.setCallbackUrl('https://your-backend.com/receive-proofs')`
-- **Set Status URL** - `reclaim.setStatusUrl('https://your-backend.com/receive-status')`
+Thank you for your contributions!

package/dist/index.d.ts

@@ -1,51 +1,21 @@
-interface ProviderV2 {
-    id: string;
+interface ProviderData {
     httpProviderId: string;
     name: string;
-    logoUrl: string;
     url: string;
-    method?: 'GET' | 'POST';
     loginUrl: string;
-    responseSelections: {
-        invert: boolean;
-        responseMatch: string;
-        xPath?: string | undefined;
-        jsonPath?: string | undefined;
-    }[];
-    headers?: {
-        [key: string]: string;
-    };
-    creatorEmail: string;
-    applicationId: string[];
-    iconPath: {
-        uri: string;
-    };
-    customInjection?: string;
-    urlType: 'CONSTANT' | 'REGEX';
-    proofCardTitle: string;
-    proofCardText: string;
-    bodySniff?: {
-        enabled: boolean;
-        regex?: string;
-    };
-    userAgent?: {
-        ios?: string;
-        android?: string;
-    };
-    geoLocation?: string;
-    matchType?: string;
-    injectionType: string;
-    verificationType: string;
-    disableRequestReplay: boolean;
+    responseSelections: ResponseSelection[];
+    bodySniff?: BodySniff;
 }
 interface ResponseSelection {
-    JSONPath: string;
-    XPath: string;
+    invert: boolean;
     responseMatch: string;
+    xPath?: string;
+    jsonPath?: string;
 }
 interface BodySniff {
     enabled: boolean;
-    regex: string;
+    regex?: string;
+    template?: string;
 }
 interface Proof {
     identifier: string;
@@ -67,68 +37,13 @@ interface ProviderClaimData {
     owner: string;
     timestampS: number;
     context: string;
-    /**
-     * identifier of the claim;
-     * Hash of (provider, parameters, context)
-     *
-     * This is different from the claimId returned
-     * from the smart contract
-     */
     identifier: string;
     epoch: number;
 }
-interface RequestedProofs {
-    id: string;
-    sessionId: string;
-    name: string;
-    callbackUrl: string;
-    statusUrl: string;
-    claims: RequestedClaim[];
-}
-interface RequestedClaim {
-    provider: string;
-    context: string;
-    httpProviderId: string;
-    payload: Payload;
-}
-interface Payload {
-    metadata: {
-        name: string;
-        logoUrl: string;
-        proofCardTitle: string;
-        proofCardText: string;
-    };
+interface RequestedProof {
     url: string;
-    urlType: 'CONSTANT' | 'REGEX';
-    method: 'GET' | 'POST';
-    login: {
-        url: string;
-    };
-    responseSelections: {
-        invert: boolean;
-        responseMatch: string;
-        xPath?: string;
-        jsonPath?: string;
-    }[];
-    headers?: {
-        [key: string]: string;
-    };
-    customInjection?: string;
-    bodySniff?: {
-        enabled: boolean;
-        regex?: string;
-    };
-    userAgent?: {
-        ios?: string;
-        android?: string;
-    };
-    geoLocation?: string;
-    matchType?: string;
-    injectionType: string;
-    verificationType: string;
-    disableRequestReplay: boolean;
     parameters: {
-        [key: string]: string | undefined;
+        [key: string]: string;
     };
 }
 interface Context {
@@ -136,10 +51,6 @@ interface Context {
     contextMessage: string;
 }
 interface Beacon {
-    /**
-     * Get the witnesses for the epoch specified
-     * or the current epoch if none is specified
-     */
     getState(epoch?: number): Promise<BeaconState>;
     close?(): Promise<void>;
 }
@@ -151,72 +62,53 @@ type BeaconState = {
 };
 
 type StartSessionParams = {
-    onSuccessCallback: OnSuccessCallback;
-    onFailureCallback: OnFailureCallback;
+    onSuccess: OnSuccess;
+    onError: OnError;
 };
-type OnSuccessCallback = (proofs: Proof[]) => void;
-type OnFailureCallback = (error: Error) => void;
+type OnSuccess = (proof: Proof) => void;
+type OnError = (error: Error) => void;
 type ProofRequestOptions = {
     log?: boolean;
-    sessionId?: string;
+    acceptAiProviders?: boolean;
 };
-type ApplicationId = string;
-type Signature = string;
-type AppCallbackUrl = string;
-type SessionId = string;
-type StatusUrl = string;
-type NoReturn = void;
 
-declare class Reclaim {
-    static verifySignedProof(proof: Proof): Promise<boolean>;
-    static transformForOnchain(proof: Proof): {
-        claimInfo: {
-            [k: string]: string;
-        };
-        signedClaim: {
-            claim: {
-                [k: string]: string | number;
-            };
-            signatures: string[];
-        };
-    };
-    static verifyProvider(proof: Proof, providerHash: string): boolean;
-    static ProofRequest: {
-        new (applicationId: string, options?: ProofRequestOptions): {
-            applicationId: ApplicationId;
-            signature?: string | undefined;
-            appCallbackUrl?: string | undefined;
-            sessionId: SessionId;
-            statusUrl?: string | undefined;
-            context: Context;
-            requestedProofs?: RequestedProofs | undefined;
-            providerId?: string | undefined;
-            redirectUrl?: string | undefined;
-            intervals: Map<string, NodeJS.Timer>;
-            linkingVersion: string;
-            timeStamp: string;
-            addContext(address: string, message: string): NoReturn;
-            setAppCallbackUrl(url: string): NoReturn;
-            setRedirectUrl(url: string): NoReturn;
-            setStatusUrl(url: string): NoReturn;
-            setSignature(signature: Signature): NoReturn;
-            getAppCallbackUrl(): AppCallbackUrl;
-            getStatusUrl(): StatusUrl;
-            getRequestedProofs(): RequestedProofs;
-            generateSignature(applicationSecret: string): Promise<Signature>;
-            buildProofRequest(providerId: string, redirectUser?: boolean, linkingVersion?: string): Promise<RequestedProofs>;
-            createVerificationRequest(): Promise<{
-                statusUrl: StatusUrl;
-                requestUrl: string;
-            }>;
-            startSession({ onSuccessCallback, onFailureCallback }: StartSessionParams): Promise<void>;
-            scheduleIntervalEndingTask(onFailureCallback: OnFailureCallback): void;
-            availableParams(): string[];
-            setParams(params: {
-                [key: string]: string;
-            }): NoReturn;
-        };
-    };
+declare function verifyProof(proof: Proof): Promise<boolean>;
+declare function transformForOnchain(proof: Proof): {
+    claimInfo: any;
+    signedClaim: any;
+};
+declare class ReclaimProofRequest {
+    private applicationId;
+    private signature?;
+    private appCallbackUrl?;
+    private sessionId;
+    private options?;
+    private context;
+    private requestedProof?;
+    private providerId;
+    private redirectUrl?;
+    private intervals;
+    private timeStamp;
+    private constructor();
+    static init(applicationId: string, appSecret: string, providerId: string, options?: ProofRequestOptions): Promise<ReclaimProofRequest>;
+    static fromJsonString(jsonString: string): Promise<ReclaimProofRequest>;
+    setAppCallbackUrl(url: string): void;
+    setRedirectUrl(url: string): void;
+    addContext(address: string, message: string): void;
+    setParams(params: {
+        [key: string]: string;
+    }): void;
+    getAppCallbackUrl(): string;
+    getStatusUrl(): string;
+    private setSignature;
+    private generateSignature;
+    private buildProofRequest;
+    private getRequestedProof;
+    private availableParams;
+    private clearInterval;
+    toJsonString(options?: ProofRequestOptions): string;
+    getRequestUrl(): Promise<string>;
+    startSession({ onSuccess, onError }: StartSessionParams): Promise<void>;
 }
 
-export { type Beacon, type BeaconState, type BodySniff, type Context, type Payload, type Proof, type ProviderClaimData, type ProviderV2, Reclaim, type RequestedClaim, type RequestedProofs, type ResponseSelection, type WitnessData };
+export { type Beacon, type BeaconState, type BodySniff, type Context, type Proof, type ProviderClaimData, type ProviderData, ReclaimProofRequest, type RequestedProof, type ResponseSelection, type WitnessData, transformForOnchain, verifyProof };