> ## Documentation Index
> Fetch the complete documentation index at: https://orwel-22af1265.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Reference

> Every method and init option of the Orwel JavaScript SDK.

The SDK is a singleton — initialize once, import the same `orwel` instance anywhere. Every method is safe to call after `init()`.

## Methods

| Method       | Signature                  | Description                                                                                                                 |
| ------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `init`       | `init(config)`             | Initialize with your API key + options. Call once, client-side.                                                             |
| `track`      | `track(code, props?)`      | Record a named event.                                                                                                       |
| `identify`   | `identify(traits?)`        | Attach identity / traits to the visitor.                                                                                    |
| `conversion` | `conversion(code, props?)` | Record a conversion / lead. Async — `await`s visitor resolution and returns the server-acknowledged `{ success, reason? }`. |
| `session`    | `session(props?)`          | Update per-session state. Returns `{ success, sessionId }`.                                                                 |
| `monitor`    | `monitor(opts?)`           | Enable performance / error / network monitoring.                                                                            |
| `form`       | `form(el, opts?)`          | Track interactions on a form element.                                                                                       |
| `flush`      | `flush()`                  | Force-send queued events (rarely needed).                                                                                   |

## `init` options

| Option               | Type      | Description                                                                                      |
| -------------------- | --------- | ------------------------------------------------------------------------------------------------ |
| `apiKey`             | `string`  | Workspace ingest key (from env). **Required.**                                                   |
| `autoMonitor`        | `boolean` | JS errors, console errors, failed network requests, and navigation/resource performance timings. |
| `autoEventDetection` | `boolean` | Auto `page_view` / `click` / `scroll` / `element_visible`.                                       |
| `debug`              | `boolean` | Verbose console logging (dev only).                                                              |

```typescript theme={null}
import orwel from 'orwel';

orwel.init({
  apiKey: process.env.NEXT_PUBLIC_ORWEL_KEY,
  autoMonitor: true,
  autoEventDetection: true,
  debug: process.env.NODE_ENV !== 'production',
});
```

## Validation

The SDK validates inputs at runtime and throws descriptive errors:

* `apiKey` must start with `orwel_` and be ≥ 20 characters.
* Event codes match `^[a-z0-9_]{1,50}$`.
* Emails inside properties / traits are validated — pass valid addresses or omit the field.

<Tip>
  **One instance.** Never re-initialize. Import `orwel` from your wrapper module everywhere; the visitor + session are managed for you and persist across reloads.
</Tip>