npm package: @seedlink/connect
Description: Seedlink Connect — drop-in JavaScript widget for cannabis compliance account linking
Latest version: 0.1.0

# @seedlink/connect

Drop-in JavaScript widget for cannabis operators to securely link their Metrc and BioTrack compliance accounts.

## Install

```bash
npm install @seedlink/connect
```

## Quick Start

```javascript
import { SeedlinkConnect } from "@seedlink/connect";

// 1. Get a link token from your backend
const res = await fetch("/api/create-link-token", { method: "POST" });
const { link_token } = await res.json();

// 2. Open the Connect widget
const link = SeedlinkConnect.create({
  token: link_token,
  onSuccess: (publicToken, metadata) => {
    // Send publicToken to your backend to exchange for connection details
    console.log("Connected!", metadata.provider, metadata.state);
  },
  onExit: (error) => {
    if (error) console.error("Connect error:", error.message);
  },
});

link.open();
```

## How It Works

1. Your backend calls `POST /v1/link/token/create` with your Seedlink API key to get a temporary link token
2. Pass the link token to `SeedlinkConnect.create()` and call `.open()`
3. The user selects their provider (Metrc/BioTrack), state, and enters credentials
4. On success, you receive a `publicToken` — exchange it via `POST /v1/link/token/exchange` for the connection ID
5. Use the connection ID to make Traceability API calls

## API

### `SeedlinkConnect.create(config)`

Returns a `SeedlinkConnectInstance` with `.open()`, `.close()`, and `.destroy()` methods.

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `token` | `string` | Yes | Link token from `POST /v1/link/token/create` |
| `onSuccess` | `(publicToken, metadata) => void` | Yes | Called on successful account link |
| `onExit` | `(error?) => void` | No | Called when widget closes or on error |
| `onEvent` | `(event) => void` | No | Called for analytics/tracking events |
| `theme` | `object` | No | Customize widget appearance |
| `connectUrl` | `string` | No | Override Connect app URL (development) |

### Theme Options

```javascript
SeedlinkConnect.create({
  token: "lt_...",
  onSuccess: (pt, meta) => {},
  theme: {
    primaryColor: "#3b3f1e",   // Header and button color
    fontFamily: "Inter, sans-serif",
    borderRadius: "12px",
  },
});
```

### Events

The `onEvent` callback receives events as the user progresses:

| Event | Description |
|-------|-------------|
| `OPEN` | Widget opened |
| `PROVIDER_SELECTED` | User selected a provider |
| `STATE_SELECTED` | User selected a state |
| `CREDENTIALS_SUBMITTED` | User submitted credentials |
| `VALIDATION_STARTED` | Credential validation began |
| `VALIDATION_COMPLETE` | Validation finished |
| `CLOSE` | Widget closed |

## Backend Integration

```javascript
// 1. Create a link token (server-side)
const response = await fetch("https://api.seedlink.dev/v1/link/token/create", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const { data } = await response.json();
// data.link_token = "lt_..."

// 2. After onSuccess, exchange the public token (server-side)
const exchange = await fetch("https://api.seedlink.dev/v1/link/token/exchange", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ public_token: publicToken }),
});
const { data: connection } = await exchange.json();
// connection.connection_id, connection.provider, connection.state
```

## Requirements

- Works in all modern browsers (ES2020+)
- Zero dependencies
- ~6KB minified

## License

MIT