# SDK Reference

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

The SDK is a singleton: initialize once, then import the same `orwel` instance anywhere (`import orwel from 'orwel'` or `import { orwel } from 'orwel'`). On the server (no `window`) every method is a no-op, so imports are safe in SSR code.

## Methods

| Method | Returns | Description |
| --- | --- | --- |
| `init(config)` | `void` | Configure the SDK with your key and options. Call once, in the browser. Throws on an invalid config. |
| `track(code, props?)` | `{ success, eventId }` | Queue a named event. The code must be in the workspace catalog. |
| `identify(traits?)` | `{ success, visitorId }` | Attach identity and traits to the visitor. |
| `conversion(code, props?)` | `Promise<{ success, reason? }>` | Record a conversion. Waits for the visitor id, adds a `conversionId` and attribution, sends immediately, and resolves with the acknowledged result. `reason` is `visitor_unresolved`, `delivery_failed` or `error`. |
| `session(props?, final?)` | `{ success, sessionId }` | Merge custom properties into the current session. |
| `monitor(opts?)` | `{ success }` | Start error, console, network and performance monitoring. |
| `form(el, opts?)` | `{ success, error? }` | Observe a form element. |
| `flush()` | `Promise<{ success, count }>` | Send the queue now, in batches of up to 100. Rarely needed. |

## `init` options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `apiKey` | `string` | | Production API key (`orwel_pk_...`) or development key (`orwel_dev_...`). **Required.** Read it from an environment variable. |
| `autoMonitor` | `boolean` | `false` | Same as calling `monitor()`: JS errors, console errors, network requests and navigation and resource timings. |
| `autoEventDetection` | `boolean` | `true` | Automatic `page_view`, `click`, `scroll`, `element_visible` and other catalog events. Pass `false` to turn it off. |
| `eventDetectionOptions` | `object` | | `enabledCategories` (for example `['navigation', 'form', 'ecommerce']`) and `confidenceThreshold` (0 to 1). |
| `debug` | `boolean` | `false` | SDK logs in the browser console. |
| `verbose` | `boolean` | `false` | More detailed logs. |

```typescript
import orwel from 'orwel';

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

## `monitor` options

All default to `true` when you call `monitor()` with no options.

| Option | Description |
| --- | --- |
| `errors` | JS errors and unhandled promise rejections. |
| `console` | Console errors and warnings. |
| `network` | Fetch and XHR requests (URL, method, status, duration). |
| `performance` | Navigation and resource timings. |

## `form` options

| Option | Description |
| --- | --- |
| `formId` | Identifier for the form (generated if omitted). |
| `trackFocus`, `trackInput`, `trackChange` | Field level interaction events. |
| `trackSubmit` | `form_submit_attempt`, `form_submit_success`, `form_submit_error`. |
| `trackAbandon` | `form_abandon` when the visitor leaves without submitting. |
| `submitCallback` | Called with `{ success, error? }` after a submit attempt. |

## Validation

The SDK validates inputs at runtime and throws descriptive errors:

- `apiKey` must start with `orwel_` and be at least 20 characters.
- `config`, `traits` and `properties` must be objects.
- Event codes match `^[a-z0-9_]+$` and are at most 50 characters.
- Emails inside properties and traits must be valid addresses. Pass a valid one or omit the field.

## Storage

| Key | Storage | Content |
| --- | --- | --- |
| `__orwel_visitor__` | `localStorage` | Visitor id and traits. |
| `__orwel_session__` | `localStorage` | Current session. |
| `__orwel_queue__` | `localStorage` | Events waiting to be sent (up to 1000). |
| `__orwel_attribution` | `localStorage` | First and last touch UTMs and click ids. |
| `__orwel_utm`, `__orwel_click_ids` | `sessionStorage` | UTMs and click ids of the current session. |

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