@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

`

Usage

$3

First, create a link token from your backend:

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

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

$3

`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

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

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

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

API Reference

$3

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) |

$3

| 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