earthid-web-sdk/README.md

A simple SDK for interacting with EarthID's web features

# EarthID Web SDK

A lightweight SDK to easily integrate EarthID's web-based identity and document-sharing features into your web or JavaScript application.

Supports secure authentication, QR code generation, and real-time socket communication with the EarthID platform.

---

## 📦 Installation

Install via npm:

```bash
npm install earthid-web-sdk
```

---

## 🚀 Quick Start

```js
import EarthIDSDK from 'earthid-web-sdk';

const sdk = new EarthIDSDK({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://stage-apiv2.myearth.id',
  socketUrl: 'https://stage-socketv2.myearth.id',
  debug: true  // Optional: Enable debug logging
});
```

---

## 📚 Table of Contents

- Installation
- Quick Start
- Initialization
- API Methods
  - getVendor
  - generateHash
  - generateQrCodeNest
  - listenForServiceProviderResponse
  - listenForUserData
  - disconnect
- QR Code Use Cases & Examples
- Typical Flow Sequence
- License

---

## 🛠 Initialization

Initialize the SDK using your EarthID credentials:

```js
const sdk = new EarthIDSDK({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://stage-apiv2.myearth.id',
  socketUrl: 'https://stage-socketv2.myearth.id'
});
```

---

## 📡 Available Methods

### 1. getVendor()

Fetch vendor information using your vendor API key and a session ID.

```js
const vendor = await sdk.getVendor('VENDOR_API_KEY', 'SESSION_ID');
console.log(vendor);
```

Returns vendor metadata including secretKey and apiKey.

---

### 2. generateHash()

Generate a secure HMAC SHA-256 hash for authentication.

```js
const timestamp = Date.now();
const hash = sdk.getHash('VENDOR_SECRET_KEY', 'VENDOR_API_KEY', timestamp);
```

Parameters:

- vendorSecretKey (string)
- vendorApiKey (string)
- timestamp (number, optional)

---

### 3. generateQrCodeNest()

Generate a QR code for a specific request type using a hash.

```js
const qrCode = await sdk.generateQrCodeNest(hash, 'VENDOR_API_KEY', timestamp, 'document');
```

---

### 4. listenForServiceProviderResponse()

Listen for service provider events via WebSocket:

```js
sdk.listenForServiceProviderResponse((err, data) => {
  if (err) console.error(err);
  else console.log('Service Provider:', data);
});
```

---

### 5. listenForUserData()

Listen for user authentication data:

```js
sdk.listenForUserData((err, data) => {
  if (err) console.error(err);
  else console.log('User Data:', data);
});
```

---

### 6. disconnect()

Disconnect from the WebSocket server:

```js
sdk.disconnect();
```

---

## 📘 QR Code Use Cases & Examples

When calling generateQrCodeNest(), the requestType parameter determines the use case:

| Request Type     | Description                                                                 |
|------------------|-----------------------------------------------------------------------------|
| login            | Initiate Passwordless(QR-based) login and wallet authentication                          |
| document         | Request for document access from wallet                                     |
| selectiveData    | Selective Data Disclosure — request specific fields from user's document    |
| minAge           | Request Proof of Age for ZKP for minimum age (e.g., 18+, 21+)               |
| ageRange         | Request Proof of Age for a specific age range (e.g., 5-12, 18-35)           |
| balance          | Request proof of minimum wallet balance                                     |
| idvProof         | Request for ID Verification proof from the wallet                          |


Examples:

1. Passwordless Login flow
```js
const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, 'login');
```

2. Document request
```js
const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, 'document');
```

3. Selective Data Disclosure
```js
const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, 'selectiveData');
```

4. ZKP Minimum Age (e.g., 18+)
```js
const zkpData = {
    "request": "minAge",
    "type": "date",
    "value": inputValue(i.e. 18, 21, etc.),
    "unit": "years"
}

const zkpDataString = JSON.stringify(zkpData);

const jsonStringWithSingleQuotes = zkpDataString.replace(/"/g, "'");

const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, jsonStringWithSingleQuotes);
```

5. ZKP Age Range (e.g., 18-35)
```js
const ageData = {
      request: "ageRange",
      type: "date",
      minValue: "13",
      maxValue: "16",
      unit: "years"
};

const ageDataString = JSON.stringify(ageData);

const jsonStringWithSingleQuotes = ageDataString.replace(/"/g, "'");

const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, jsonStringWithSingleQuotes);
```

6. ZKP for Proof of Funds
```js
const zkpData = {
    "request": "balance",
    "type": "number",
    "minimum": formDataJson.inputValue
}

const zkpDataString = JSON.stringify(zkpData);

const jsonStringWithSingleQuotes = zkpDataString.replace(/"/g, "'");

const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, jsonStringWithSingleQuotes);
```

7. ID Verification Proof
```js
const idvData = {
    "request": "idvProof",
    "company": "EarthID"
}

const idvDataString = JSON.stringify(idvData);

const jsonStringWithSingleQuotes = idvDataString.replace(/"/g, "'");

const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, jsonStringWithSingleQuotes);
```

---

## 🔁 Typical Flow Sequence (Example: Login)

Below is the typical sequence for initiating a secure login flow using the SDK:

```js
// Step 1: Create SDK instance
const sdk = new EarthIDSDK({ apiKey, baseUrl, socketUrl });

// Step 2: Get vendor metadata
const vendor = await sdk.getVendor('VENDOR_API_KEY', 'SESSION_ID');

// Step 3: Generate a secure hash
const timestamp = Date.now();
const hash = sdk.getHash(vendor.values[0].secretKey, vendor.values[0].apiKey, timestamp);

// Step 4: Generate QR code for login (or any request type)
const qrCode = await sdk.generateQrCodeNest(hash, vendor.values[0].apiKey, timestamp, 'login');

// Step 5: Set up listeners to receive data in real-time
sdk.listenForServiceProviderResponse((err, data) => console.log('Service Provider:', data));
sdk.listenForUserData((err, data) => console.log('User Data:', data));

// Step 6: After receiving the user data process it for further verification or data handling as per the use case

```

Use the same sequence for any other request type — just change the last parameter in generateQrCodeNest() based on your use case.

---

## 🧪 Debug Mode

Enable debug logging by passing debug: true during initialization. Logs include socket connections, QR code responses, and internal status.

---

## 📦 Version

The SDK includes a static version:

```js
console.log(EarthIDSDK.version); // "1.0.0"
```

---

## 📝 License

MIT License — Feel free to use, modify, and contribute.