# refport-js

Browser SDK for [Refport](https://refport.co) — captures referral click IDs from URLs, stores them in cookies for conversion attribution, and embeds the referral portal.

## Install

```bash
npm install refport-js
```

### Manual Installation

Add this snippet to the `<head>` of your site to capture referral clicks without a framework:

```html
<script
  src="https://cdn.jsdelivr.net/npm/refport-js/dist/auto.iife.js"
  defer
  data-query-param="refp_id"
  data-cookie-name="refp_id"
></script>
```

For production, pin the package version in the URL, for example `refport-js@<version>`.

You can customize cookie behavior with script attributes:

```html
<script
  src="https://cdn.jsdelivr.net/npm/refport-js/dist/auto.iife.js"
  defer
  data-query-param="refp_id"
  data-cookie-name="refp_id"
  data-cookie-domain=".example.com"
  data-cookie-options='{"expiresInDays":60,"sameSite":"Lax"}'
></script>
```

Verify the installation with these checks:

1. Open the browser console and type `window._refport`. If the script loaded, you should see the Refport object.
2. Visit your site with `?refp_id=test` in the URL and confirm the `refp_id` cookie is set.

If either check fails, make sure the script is added to the `<head>` and any CDN/page cache has been cleared.

Supported script attributes:

| Attribute             | Description                                           |
| --------------------- | ----------------------------------------------------- |
| `data-query-param`    | URL query parameter to capture                        |
| `data-query-params`   | JSON array or comma-separated query parameters        |
| `data-cookie-name`    | Cookie name                                           |
| `data-cookie-domain`  | Cookie domain, such as `.example.com`                 |
| `data-cookie-path`    | Cookie path                                           |
| `data-max-age`        | Cookie max age in seconds                             |
| `data-same-site`      | Cookie SameSite value: `Strict`, `Lax`, or `None`     |
| `data-secure`         | Set to `true` or `false` to override the Secure flag  |
| `data-clean-url`      | Set to `false` to keep the query parameter in the URL |
| `data-cookie-options` | JSON object with cookie options like `expiresInDays`  |

### CDN API

Use the IIFE bundle when you want to call the browser SDK manually:

```html
<script src="https://cdn.jsdelivr.net/npm/refport-js/dist/index.iife.js"></script>
<script>
  Refport.init();
</script>
```

Or use the ES module bundle:

```html
<script type="module">
  import { init } from "https://cdn.jsdelivr.net/npm/refport-js/dist/index.mjs";
  init();
</script>
```

## Embed Portal

```ts
import { createEmbed } from "refport-js";

const embed = createEmbed(document.getElementById("portal")!, {
  token: "pub_...",
  theme: "light",
  cssVars: { "--accent": "#ff6600" },
  onError: (err) => console.error(err.message),
});

embed.destroy();
```

### `createEmbed(target, options)`

Mounts a Refport referral portal iframe into the given DOM element. Returns a `RefportEmbedInstance` with:

- `container` — the wrapper `<div>` element
- `iframe` — the `<iframe>` element
- `destroy()` — removes the embed and cleans up event listeners

### Embed Options

| Option    | Type                                                 | Default                    | Description                   |
| --------- | ---------------------------------------------------- | -------------------------- | ----------------------------- |
| `token`   | `string`                                             | —                          | Public embed token (required) |
| `theme`   | `"light" \| "dark" \| "system"`                      | —                          | Color theme                   |
| `cssVars` | `Record<string, string>`                             | —                          | Custom CSS variables          |
| `baseUrl` | `string`                                             | `"https://app.refport.co"` | API base URL                  |
| `onError` | `(error: { code: string; message: string }) => void` | —                          | Error callback                |

## Click Tracking

```ts
import { init, getClickId, reset } from "refport-js";

const result = init();

if (result.clickId) {
  console.log(`Click ID: ${result.clickId} (from ${result.source})`);
}

const clickId = getClickId();

reset();
```

### `init(options?)`

Checks the URL for a `refp_id` query parameter. If found, stores it in a cookie and optionally strips the parameter from the URL. Falls back to reading an existing cookie.

Returns a `RefportTrackingResult`:

```ts
{
  tracked: boolean;
  clickId: string | null;
  source: "url" | "cookie" | null;
}
```

- `tracked: true` — a new click ID was captured from the URL
- `tracked: false, source: "cookie"` — click ID was already stored
- `tracked: false, source: null` — no click ID found

### `getClickId(cookieName?)`

Reads the click ID from the cookie. Returns `string | null`.

### `reset(options?)`

Deletes the tracking cookie. Accepts `cookieName`, `path`, and `domain` options.

### Tracking Options

| Option       | Type                          | Default                     | Description                                           |
| ------------ | ----------------------------- | --------------------------- | ----------------------------------------------------- |
| `cookieName` | `string`                      | `"refp_id"`                 | Cookie name                                           |
| `paramName`  | `string`                      | `"refp_id"`                 | URL query parameter name                              |
| `maxAge`     | `number`                      | `7776000` (90 days)         | Cookie max age in seconds                             |
| `path`       | `string`                      | `"/"`                       | Cookie path                                           |
| `domain`     | `string`                      | —                           | Cookie domain                                         |
| `sameSite`   | `"Strict" \| "Lax" \| "None"` | `"Lax"`                     | Cookie SameSite attribute                             |
| `secure`     | `boolean`                     | Auto-detected from protocol | Cookie Secure flag                                    |
| `cleanUrl`   | `boolean`                     | `true`                      | Remove the query parameter from the URL after capture |

## License

MIT
