# @selfxyz/qrcode-angular

`@selfxyz/qrcode-angular` is an Angular library for generating **verification QR codes** that link to the **Self.xyz app**.
It allows developers to define **what user data (disclosures)** should be requested during verification (such as nationality, age checks, or OFAC restrictions) and automatically builds a QR code that users can scan with the Self app to complete verification.

With a few lines of code, you can:

* Configure disclosures like *minimum age, excluded countries, OFAC checks, or DG1 passport fields*.
* Generate a `SelfApp` configuration via `SelfAppBuilder`.
* Render a QR code that works out-of-the-box with WebSocket or deep link flows.
* Handle **success** and **error** callbacks when verification is completed.

This library is the **Angular equivalent** of the Self QR code React SDK, making it easy to embed Self-powered verification flows into Angular applications.

# @selfxyz/angular-qrcode

`SelfQRcodeComponent` is an Angular standalone component for rendering **QR codes** that connect users to Self.xyz's flows.
It manages session creation, WebSocket connections, and real-time proof state updates, while providing visual feedback through LED states.

---

## ✨ Features

* Generates a unique session ID for every instance.
* Displays a QR code for Self app deep linking or WebSocket flow.
* Handles **WebSocket lifecycle** (connection, cleanup, proof step updates).
* Emits **success** and **error callbacks** when verification completes.
* Supports light/dark mode and configurable QR size.
* Includes success/error animations with `ngx-lottie`.

---

## 📦 Installation

```bash
npm install @selfxyz/qrcode-angular angularx-qrcode ngx-lottie uuid
```

Also ensure you have Angular v15+ with standalone components enabled.

---

## ⚡ Usage

### Import the Component

Since it’s standalone, you can import it directly into any feature component:

```ts
import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { SelfQRcodeComponent, type SelfApp } from '@selfxyz/qrcode-angular';

@Component({
  selector: 'app-demo',
  standalone: true,
  imports: [CommonModule, SelfQRcodeComponent],
  template: `
    <lib-self-qrcode
      [selfApp]="selfApp"
      [successFn]="onSuccess"
      [errorFn]="onError"
      [darkMode]="false"
      [size]="300">
    </lib-self-qrcode>
  `,
})
export class DemoComponent {
  selfApp: SelfApp = {
    appName: 'Demo App',
    scope: 'demo-scope',
    endpoint: 'https://your-api.com/verify',
    endpointType: 'https',
    logoBase64: 'https://i.imgur.com/Rz8B3s7.png',
    userId: '0x123...', // a uuid or address
    disclosures: {
      nationality: true,
      minimumAge: 18,
      ofac: true,
    },
    version: 2,
  };

  onSuccess() {
    console.log('✅ Verification successful!');
  }

  onError(err: { error_code?: string; reason?: string }) {
    console.error('❌ Verification failed', err);
  }
}
```

---

## 🔧 Component API

### Inputs

| Input          | Type                                                       | Default         | Description                                          |
| -------------- | ---------------------------------------------------------- | --------------- | ---------------------------------------------------- |
| `selfApp`      | `SelfApp` (required)                                       | —               | The configured Self app instance.                    |
| `successFn`    | `() => void` (required)                                    | —               | Callback triggered when verification succeeds.       |
| `errorFn`      | `(data: { error_code?: string; reason?: string }) => void` | —               | Callback triggered when verification fails.          |
| `type`         | `'websocket' \| 'deeplink'`                                | `'websocket'`   | Determines whether to use WebSocket or deep link QR. |
| `websocketUrl` | `string`                                                   | `WS_DB_RELAYER` | Custom WebSocket relay URL.                          |
| `size`         | `number`                                                   | `300`           | Size of the QR code in pixels.                       |
| `darkMode`     | `boolean`                                                  | `false`         | Toggles light/dark mode for QR code styling.         |

---

### `SelfApp`

| Property           | Type                                                  | Required | Description                                              |
| ------------------ | ----------------------------------------------------- | -------- | -------------------------------------------------------- |
| `appName`          | `string`                                              | ✅        | The display name of your app shown in the Self flow.     |
| `logoBase64`       | `string` (URL or Base64-encoded image)                | ✅        | The app’s logo (shown to the user during verification).  |
| `endpointType`     | `EndpointType`                                        | ✅        | `staging_https` \| `https` \| `celo` \|  `staging_celo`|
| `endpoint`         | `string`                                              | ✅        | API endpoint where proof is verified (endpoint url or a contract address)|
| `deeplinkCallback` | `string`                                              | Optional | Callback URL for deep link flows.                        |
| `scope`            | `string`                                              | ✅        | Unique identifier for your application           |
| `userId`           | `string`                                              | ✅        | Unique identifier for the end user (address or a uuid)|
| `userIdType`       | `UserIdType`                                          | Optional | Type of identifier used (`email`, `phone`, etc.).        |
| `disclosures`      | [`SelfAppDisclosureConfig`](#selfappdisclosureconfig) | ✅        | Defines which fields are requested during verification.  |
| `version`          | `number`                                              | ✅        | Schema version (e.g., `2`).                              |
| `userDefinedData`      | `any`                                                 | Optional | Arbitrary developer-defined metadata.                    |

---

### `SelfAppDisclosureConfig`

| Property            | Type                   | Default | Description                                               |
| ------------------- | ---------------------- | ------- | --------------------------------------------------------- |
| `issuing_state`     | `boolean`              | `false` | Request the issuing state from the document.              |
| `name`              | `boolean`              | `false` | Request the full name from the document                   |
| `passport_number`   | `boolean`              | `false` | Request the document number.                              |
| `nationality`       | `boolean`              | `false` | Request the user’s nationality.                           |
| `date_of_birth`     | `boolean`              | `false` | Request the date of birth.                                |
| `gender`            | `boolean`              | `false` | Request the gender field.                                 |
| `expiry_date`       | `boolean`              | `false` | Request the passport expiry date.                         |
| `ofac`**              | `boolean`              | `false` | Check against OFAC sanction lists.                        |
| `excludedCountries`** | `Country3LetterCode[]` | `[]`    | Exclude users from specific ISO 3166-1 alpha-3 countries. |
| `minimumAge`**        | `number`               | —       | Require a minimum age (e.g., `18` (upto `99`)).|

>\*\* ⚠️ **Important:** These fields must match your **backend configuration**.


---

## 🎬 Lifecycle

* On init:

  * Generates a **UUID session ID**.
  * Establishes a **WebSocket connection**.
  * Sets the QR code value.
* On destroy:

  * Cleans up the WebSocket connection.
---