@reclaimprotocol/js-sdk 0.0.23 → 0.1.1

package/README.md

@@ -1,123 +1,205 @@
-# Reclaim SDK v2
+# Reclaim js-sdk
 
-Designed to request proofs from the Reclaim protocol and manage the flow of claims and witness interactions.
+This README provides a step-by-step guide on integrating the Reclaim Protocol JavaScript SDK into application
 
-## Interfaces:
+## Pre-requisites
 
-- ### Reclaim Interface
+- An application ID from Reclaim Protocol. You can get one from the [Reclaim Developer Protocol](https://dev.reclaimprotocol.org/)
 
-  - #### `requestProof(request: ReclaimRequest, AppCallbackUrl: string): TemplateWithLink`
+## Create a new React application
 
-    Requests proof using the provided proof request.
-
-    **Parameters:**
-
-    - `request`: ReclaimRequest (The proof request object)
-    - `AppCallbackUrl`: callback url which will receive the proof from AppClip/InstantApp
-
-    **Returns:**
-
-    - `TemplateWithLink`: A link to AppClip/AppInstant with Template Data
-
-- ### ReclaimRequest Interface
+```bash
+npx create-react-app reclaim-app
+cd reclaim-app
+```
 
-  - **title:** `string` - Title of the request
-  - **requestedProofs:** `RequestedProof[]` - Proofs requested by the application
-  - **contextMessage?:** `string` - Context message for the proof request
-  - **contextAddress?:** `string` - Context address for the proof request
-  - **requestorSignature?:** `string` - Signature of the requestor
+## Install the Reclaim Protocol JS-SDK
 
-- ### RequestedProof interface
+```bash
+npm install @reclaimprotocol/js-sdk
+```
 
-  - **name:** `string` - Title of the request
-  - **provider:** `ProviderV2` - Proof requested by the application
-  - **metadata**: {logoUri?: string, description?: string} - Metadata of the proof provider
+## Install other dependencies
 
-- ### TemplateWithLink Interface:
+```bash
+npm i react-qr-code
+```
 
-  - **template**: `Template`
-  - **link**: `string`
+## Import dependencies
 
-- ### Template Interface:
+In your `src/App.js` file, import the Reclaim SDK and the QR code generator
 
-  - **id:** `string`
-  - **name:** `string`
-  - **callbackUrl:** `string`
-  - **claims:** `RequestedProof[]`
-  - **context:** `string`
-  - **requestorSignature?:** `string`
+```javascript
+import { useState, useEffect } from 'react'
+import { Reclaim } from '@reclaimprotocol/js-sdk'
+import QRCode from 'react-qr-code'
+```
 
-- ### ProviderV2 Interface:
+## Initialize the Reclaim SDK
 
-  - **headers?:** `Map<string, string>` _(Any additional headers to be sent with the request)_
-  - **url:** `string` _(URL to make the request to, e.g., "https://amazon.in/orders?q=abcd")_
-  - **method:** `'GET' | 'POST'` _(HTTP method)_
-  - **body?:** `string | Uint8Array` _(Body of the request, used only if the method is POST)_
-  - **responseRedactions:** `ResponseRedaction[]` _(Portions to select from a response for redaction)_
-  - **responseMatches:** `ResponseMatch[]` _(List to check that the redacted response matches provided strings/regexes)_
-  - **geoLocation?:** `string` \_(Geographical location from where to proxy the request)
+Declare your `application ID` and initialize the Reclaim Protocol client. Replace `YOUR_APPLICATION_ID_HERE` with the actual application ID provided by Reclaim Protocol.
 
-- ### ResponseRedaction Interface:
+File: `src/App.js`
 
-  - **xPath?:** `string` _(XPath for HTML response)_
-  - **jsonPath?:** `string` _(JSONPath for JSON response)_
-  - **regex?:** `string` _(Regex for response matching)_
+```javascript
+import './App.css'
+import { useState, useEffect } from 'react'
+import { Reclaim } from '@reclaimprotocol/js-sdk'
+import QRCode from 'react-qr-code'
 
-- ### ResponseMatch Interface:
+function App() {
+  const APP_ID = 'YOUR_APPLICATION_ID_HERE'
+  const reclaimProofRequest = new Reclaim.ProofRequest(APP_ID)
 
-  - **type:** `'regex' | 'contains'` _("regex" or "contains" indicating the matching type)_
-  - **value:** `string` _(The string/regex to match against)_
+  return (
+    <div className='App'>
+      <header className='App-header'>
+        <p>Reclaim App</p>
+      </header>
+    </div>
+  )
+}
 
-## Usage Flow
+export default App
+```
 
-<img src='./readme/usage-flow-3.svg' width='900' />
+## 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
+
+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`
+
+```javascript
+import './App.css'
+import { useState, useEffect } from 'react'
+import { Reclaim } from '@reclaimprotocol/js-sdk'
+import QRCode from 'react-qr-code'
+
+function App() {
+  const [requestUrl, setRequestUrl] = useState('')
+  const [proofs, setProofs] = useState([])
+
+  const APP_ID = 'YOUR_APPLICATION_ID_HERE'
+
+  const reclaimProofRequest = new Reclaim.ProofRequest(APP_ID)
+
+  async function createVerificationRequest() {
+    // id of the provider you want to generate the proof for
+    await reclaimProofRequest.buildProofRequest('PROVIDER_ID')
+
+    reclaimProofRequest.setSignature(
+      await reclaimProofRequest.generateSignature(
+        'YOUR_APPLICATION_SECRET' // Handle securely for production
+      )
+    )
+
+    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
+      }
+    })
+
+    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>
+      </header>
+    </div>
+  )
+}
 
-## Dependency Diagram
+export default App
+```
 
-<img src='./readme/depemdency-diagram.svg' width='600' />
+### Production Mode
 
-## Error Codes
+In production mode, securely fetch and set the signature from your backend instead of using the application secret directly in the client.
 
-- `Malformed proof request`: The proof request is structurally incorrect or missing required elements.
+Similar to the prototype mode but ensure to fetch and set the signature securely
 
-- `Invalid AppCallbackUrl format`: The provided AppCallbackUrl is not in the expected format.
+```javascript
+async function createVerificationRequestProductionMode() {
+  // id of the provider you want to generate the proof for
+  await reclaimProofRequest.buildProofRequest('PROVIDER_ID')
 
-## Create ProofRequest Example
+  reclaim
+    .setSignature
+    // TODO: fetch signature from your backend
+    // On the backend, generate signature using:
+    // await Reclaim.getSignature(requestedProofs, APP_SECRET)
+    ()
 
-```typescript
-const privateKey = 'YOUR_PRIVATE_KEY'
+  const { requestUrl, statusUrl } =
+    await reclaimProofRequest.createVerificationRequest()
 
-const proofRequest: ProofRequest = {
-  title: 'Example Proof Request',
-  requestedProofs: [
-    {
-      url: 'https://api.example.com/data',
-      method: 'GET',
-      responseRedactions: [
-        { start: 10, end: 20 },
-        { start: 30, end: 40 }
-      ],
-      responseMatches: [
-        { type: 'string', value: 'important-data' },
-        { type: 'regex', pattern: '\\d{3}-\\d{2}-\\d{4}' }
-      ],
-      geoLocation: '37.7749,-122.4194'
+  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
     }
-  ],
-  contextMessage: 'Please provide the necessary proofs for verification.',
-  contextAddress: '0x0'
+  })
+
+  setRequestUrl(requestUrl)
 }
+```
 
-const dataToSign = JSON.stringify(proofRequest)
+## Run the application
 
-const signature = signData(dataToSign, privateKey)
+```bash
+npm start
+```
 
-const proofRequestWithSignature: ProofRequest = {
-  ...proofRequestWithoutSensitiveHeaders,
-  requestorSignature: signature
-}
+## Advanced Configuration
 
-// Send the proof request to the AppClip/InstantApp
-// Verify the signature on the AppClip side
-const isSignatureValid = verifySignature(dataToSign, signature)
-```
+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.
+
+- **Set Callback Url** - `reclaim.setCallbackUrl('https://your-backend.com/receive-proofs')`
+- **Set Status URL** - `reclaim.setStatusUrl('https://your-backend.com/receive-status')`

package/dist/index.d.ts

@@ -136,41 +136,52 @@ type BeaconState = {
     nextEpochTimestampS: number;
 };
 
-declare class ReclaimClient {
-    applicationId: string;
-    signature?: string;
-    appCallbackUrl?: string;
-    statusUrl?: string;
-    sessionId: string;
-    requestedProofs?: RequestedProofs;
-    context: Context;
-    verificationRequest?: ReclaimVerificationRequest;
-    myProvidersList: ProviderV2[];
-    constructor(applicationId: string, sessionId?: string);
-    createVerificationRequest(providers: string[]): Promise<ReclaimVerificationRequest>;
-    createLinkRequest(providers: string[]): Promise<string>;
-    setAppCallbackUrl(url: string): void;
-    getAppCallbackUrl(): string;
-    setStatusUrl(url: string): void;
-    getStatusUrl(): string;
-    setSignature(signature: string): void;
-    getSignature(requestedProofs: RequestedProofs, applicationSecret: string): Promise<string>;
-    buildHttpProviderV2ByID(providerIds: string[]): Promise<ProviderV2[]>;
-    buildRequestedProofs(providers: ProviderV2[], callbackUrl: string, statusUrl?: string): RequestedProofs;
-    addContext(address: string, message: string): Context;
+type StartSessionParams = {
+    onSuccessCallback: OnSuccessCallback;
+    onFailureCallback: OnFailureCallback;
+};
+type OnSuccessCallback = (proofs: Proof[]) => void;
+type OnFailureCallback = (error: Error) => void;
+type ProofRequestOptions = {
+    log?: boolean;
+    sessionId?: string;
+};
+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>;
-    getMyProvidersList(): Promise<ProviderV2[]>;
-}
-declare class ReclaimVerificationRequest {
-    onSuccessCallback?: (data: Proof | Error | unknown) => void | unknown;
-    onFailureCallback?: (data: Proof | Error | unknown) => void | unknown;
-    sessionId: string;
-    template: string;
-    statusUrl: string;
-    intervals: Map<string, NodeJS.Timer>;
-    constructor(sessionId: string, statusUrl: string, template: string);
-    on(event: string, callback: (data: Proof | Error | unknown) => void | unknown): this;
-    start(): Promise<string | undefined>;
+    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;
+            intervals: Map<string, NodeJS.Timer>;
+            addContext(address: string, message: string): NoReturn;
+            setAppCallbackUrl(url: string): NoReturn;
+            setStatusUrl(url: string): NoReturn;
+            setSignature(signature: Signature): NoReturn;
+            getAppCallbackUrl(): AppCallbackUrl;
+            getStatusUrl(): StatusUrl;
+            getRequestedProofs(): Promise<RequestedProofs>;
+            generateSignature(applicationSecret: string): Promise<Signature>;
+            buildProofRequest(providerId: string): Promise<RequestedProofs>;
+            createVerificationRequest(): Promise<{
+                statusUrl: StatusUrl;
+                requestUrl: string;
+            }>;
+            startSession({ onSuccessCallback, onFailureCallback }: StartSessionParams): Promise<void>;
+            scheduleIntervalEndingTask(onFailureCallback: OnFailureCallback): void;
+        };
+    };
 }
 
-export { type Beacon, type BeaconState, type BodySniff, type Context, type Payload, type Proof, type ProviderClaimData, type ProviderV2, ReclaimClient, ReclaimVerificationRequest, type RequestedClaim, type RequestedProofs, type ResponseSelection, type WitnessData };
+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 };