npm package: @paag-io/paagid_sdk
Description: ## Overview
Latest version: 0.1.2

# PaagId SDK Documentation

## Overview

The PaagId SDK provides a flexible way to login users using a popup window. It allows developers to easily integrate login functionalities into their web applications.

## Installation

### Using CDN

```html
<script src="https://cdn.jsdelivr.net/npm/@paag-io/paagid_sdk/dist/paagid_sdk.umd.js"></script>
```

### Using npm

```bash
npm install @paag-io/paagid_sdk
```

### Using Yarn

```bash
yarn add @paag-io/paagid_sdk
```

## Basic Usage

### Importing

```javascript
import PaagIdSDK from '@paag-io/paagid_sdk';
```

### Usage Examples

#### Example in React

```jsx
import { useEffect, useRef } from 'react';
import PaagIdSDK from '@paag-io/paagid_sdk';

export default App() {
  const buttonContainerRef = useRef<HTMLDivElement | null>(null);

  useEffect(() => {
    if (!buttonContainerRef.current) {
      console.error('Ref não está definida');
      return;
    }

    const paagidSDK = new PaagIdSDK({
      host: 'https://your-host.com',
      client_id: 'your-client_id',
      redirect_uri: 'https://your-website.com/callback',
      targetButton: buttonContainerRef.current,
    });

    paagidSDK.on('success', () => {
      console.log('Login successful!');
    });

    paagidSDK.on('error', () => {
      console.error('Login error!');
    });

    paagidSDK.on('fail', () => {
      console.log('Login failed.');
    });

    paagidSDK.on('close', () => {
      console.log('Login closed before completion.');
    });

    return () => {
      paagidSDK.cleanup();
    };
  }, []);

  return (
    <div>
      <div className="w-full" ref={buttonContainerRef} />
    </div>
  );
};
```

## Methods

### `registerAccount(cpf: string): void`

Starts the PaagId Register Account process. The `cpf` parameter is mandatory and represents the user's document.

### `on(event: SDKEvent, handler: () => void): void`

Registers a handler for a specific event. Available events include:

- `success`: Triggered when login is successful.
- `fail`: Triggered when **logical login** fails, meaning the user's provided data or the expected process does not meet the required criteria. Examples:
  - Document validation fails due to incorrect or incomplete information.
  - **Liveness** validation fails because the detected face does not match or facial detection is absent.
- `error`: Triggered when a **technical problem** or **unexpected error** occurs during login. Examples:
  - User connection issues (unstable or unavailable internet).
  - Integration or implementation failures in the system processing the login.
  - System exceptions (such as timeouts or server errors).
- `close`: Triggered when the login window is closed.

### `off(event: SDKEvent, handler?: () => void): void`

Removes the registered handler for a specific event. If a `handler` is provided, only that handler will be removed. If no `handler` is provided, **all** handlers for the event will be removed.

### `close(): void`

Closes the popup window opened for the validation process.

### `cleanup(): void`

Removes all registered event handlers to prevent multiple event instances when starting a new validation. Additionally, this method closes the popup window opened during the validation process.