npm package: @finsnap/connect-js
Description: FinSnap Connect JavaScript SDK for secure Chilean financial data linking (SII, banks)
Author: FinSnap
Latest version: 0.2.1

# @finsnap/connect-js

FinSnap Connect JavaScript SDK for securely linking Chilean financial accounts (SII, banks).

## Installation

```bash
npm install @finsnap/connect-js
```

Or via CDN:

```html
<script src="https://unpkg.com/@finsnap/connect-js/dist/finsnap-connect.js"></script>
```

## Usage

### 1. Get a Link Token

First, create a link token from your backend:

```bash
POST /api/v1/link/token/create
Authorization: Bearer <your_access_token>

{
  "connection_type": "sii",
  "company_rut": "76.XXX.XXX-X"
}
```

### 2. Initialize the SDK

```typescript
import { create } from '@finsnap/connect-js';

const handler = create({
  token: 'link_xxx', // from your backend
  onSuccess: (connectionId, metadata) => {
    console.log('Connected:', connectionId);
    // Save connectionId to your backend
  },
  onExit: (error, metadata) => {
    if (error) {
      console.error('Error:', error);
    }
    console.log('Status:', metadata.status);
  },
  onEvent: (eventName, metadata) => {
    console.log('Event:', eventName, metadata);
  },
  onLoad: () => {
    console.log('Widget loaded');
  },
});
```

### 3. Open the Widget

```typescript
// Open the modal
handler.open();

// Later, to close programmatically
handler.exit();

// Clean up when done
handler.destroy();
```

## API Reference

### `create(options)`

Creates a new Connect handler.

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `token` | `string` | Yes | Link token from your backend |
| `onSuccess` | `(connectionId, metadata) => void` | Yes | Called on successful connection |
| `onExit` | `(error, metadata) => void` | No | Called when widget closes |
| `onEvent` | `(eventName, metadata) => void` | No | Called for various events |
| `onLoad` | `() => void` | No | Called when widget loads |
| `embedUrl` | `string` | No | Custom widget URL (defaults to production) |

### Handler Methods

| Method | Description |
|--------|-------------|
| `open()` | Opens the widget modal |
| `exit(options?)` | Closes the widget |
| `destroy()` | Cleans up resources |

## Events

The `onEvent` callback receives these events:

| Event | Description |
|-------|-------------|
| `LOAD` | Widget loaded token info |
| `SUBMIT_CREDENTIALS` | User submitted credentials |
| `SUCCESS` | Connection successful |
| `ERROR` | An error occurred |
| `CLOSE` | Widget closed |

## Environments

The SDK defaults to the production FinSnap Connect endpoint. For development and testing:

```typescript
const handler = create({
  token: 'link_xxx',
  // Use dev environment for testing
  embedUrl: 'https://dev-api-services.finsnap.tax/link/embed',
  onSuccess: (connectionId, metadata) => {
    console.log('Connected:', connectionId);
  },
});
```

| Environment | URL |
|-------------|-----|
| Production | `https://api-services.finsnap.tax/link/embed` (default) |
| Development | `https://dev-api-services.finsnap.tax/link/embed` |

## Security

This SDK follows security best practices:

- **No tokens in URLs**: Link tokens are passed via postMessage, not URL query params
- **Origin validation**: Messages are only accepted from verified origins
- **CSP headers**: Widget is protected by Content-Security-Policy
- **Single-use tokens**: Link tokens expire after 30 minutes and can only be used once
- **Sandboxed iframe**: Widget runs in a sandboxed iframe with minimal permissions
- **Strict message validation**: Only messages from the expected origin with correct source/version are processed

> **Note**: The `embedUrl` option should only be used to point to official FinSnap Connect endpoints (production or development). Never point to untrusted URLs.

## Browser Support

- Chrome 60+
- Firefox 55+
- Safari 11+
- Edge 79+

## License

MIT