@dataxamas/tracker-js 1.0.1

package/README.md

@@ -0,0 +1,256 @@
+# Dataxamas SDK
+
+Official JavaScript/TypeScript SDK for the [Dataxamas](https://dataxamas.izakdvlpr.com) analytics platform.
+
+One package, three capabilities:
+
+- **Logs** — structured, colorized logs shipped to Dataxamas (works in Node and the browser).
+- **Error tracking** — capture exceptions manually or hook global handlers automatically.
+- **Web analytics** — page views, clicks, scroll depth, heat-map interactions, and full session replay (rrweb). Browser-only.
+
+Written in TypeScript, ships ESM + CJS with bundled type declarations. No peer dependencies — `rrweb` is bundled and lazy-loaded only when replay actually starts.
+
+---
+
+## Installation
+
+```bash
+bun add @dataxamas/tracker-js
+# or
+npm install @dataxamas/tracker-js
+# or
+pnpm add @dataxamas/tracker-js
+# or
+yarn add @dataxamas/tracker-js
+```
+
+---
+
+## Quick start
+
+### Browser (analytics + logs + error tracking)
+
+```ts
+import { Dataxamas } from "@dataxamas/tracker-js";
+
+const client = new Dataxamas({
+  apiKey: "dx_live_xxx",
+});
+
+// Global error capture is installed automatically.
+// Start collecting page views / clicks / scroll / replay:
+client.tracking.start();
+
+client.logs.info("App booted", { version: "1.0.0" });
+```
+
+### Server / Node (logs + error tracking only)
+
+```ts
+import { Dataxamas } from "@dataxamas/tracker-js";
+
+const client = new Dataxamas({
+  apiKey: "dx_live_xxx",
+  environment: "production",
+  release: "1.0.0",
+});
+
+client.logs.success("Payment processed", { amount: 1999 });
+
+try {
+  riskyWork();
+} catch (error) {
+  client.exceptions.captureException(error, { userId: 42 });
+}
+```
+
+> `client.tracking` exists on the server too, but calling `client.tracking.start()` outside a browser throws. See [Browser vs Server](#browser-vs-server).
+
+---
+
+## Browser vs Server
+
+| Feature | Browser | Node / Server |
+| --- | --- | --- |
+| `client.logs.*` | ✅ | ✅ |
+| `client.exceptions.*` | ✅ | ✅ |
+| `client.tracking.start()` | ✅ | ❌ throws `browser environment` error |
+
+- **Tracking is browser-only.** `DataxamasTracking.start()` throws if `window`/`document` are missing, and is a silent no-op on `localhost`/`127.0.0.1` unless `allowLocalhost` is set.
+- **`rrweb` (session replay) is lazy-loaded.** It is only imported (`await import("rrweb")`) when replay starts in the browser, so importing the SDK on the server never pulls it in. In the build it lives in a separate chunk, keeping the main bundle small.
+
+---
+
+## API Reference
+
+### `Dataxamas`
+
+The all-in-one facade. Creating it wires up logs, exceptions, and tracking, and installs global error handlers (unless disabled).
+
+```ts
+const client = new Dataxamas(options);
+```
+
+**Options** (`DataxamasOptions`)
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `apiKey` | `string` | — | **Required.** Website API key (`dx_live_`) used by logs, errors and tracking. |
+| `baseUrl` | `string` | `https://dataxamas.izakdvlpr.com` | API base URL. |
+| `enableLogs` | `boolean` | `true` | Enable the logs channel. |
+| `enableErrorTracking` | `boolean` | `true` | Enable exception capture. |
+| `captureGlobalErrors` | `boolean` | `true` | Auto-install global error/rejection handlers. |
+| `environment` | `string` | `undefined` | Environment tag attached to captured errors. |
+| `release` | `string` | `undefined` | Release/version tag attached to captured errors. |
+| `replayEnabled` | `boolean` | `true` | Allow session replay (still gated by server config). |
+| `heatMapEnabled` | `boolean` | `true` | Collect heat-map data on clicks. |
+| `allowLocalhost` | `boolean` | `false` | Allow tracking on `localhost`/`127.0.0.1`. |
+
+**Properties**
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `logs` | `DataxamasLogs` | Structured logging. |
+| `exceptions` | `DataxamasExceptions` | Error capture. |
+| `tracking` | `DataxamasTracking` | Web analytics (call `.start()`). |
+
+Throws if `apiKey` is missing.
+
+---
+
+### `DataxamasLogs`
+
+Structured logging. Each call logs locally (pino, colorized) **and** ships the entry to `POST /api/v1/logs`. Accessed via `client.logs`.
+
+All methods share the signature `(message: string, data?: unknown) => void`.
+
+| Method | Level | Use for |
+| --- | --- | --- |
+| `debug(message, data?)` | `DEBUG` | Verbose diagnostics. |
+| `info(message, data?)` | `INFO` | General information. |
+| `warn(message, data?)` | `WARN` | Recoverable issues. |
+| `log(message, data?)` | `LOG` | Plain log lines. |
+| `success(message, data?)` | `SUCCESS` | Successful operations. |
+
+```ts
+client.logs.debug("Cache lookup", { key: "profile:42" });
+client.logs.info("User signed in", { userId: 42 });
+client.logs.warn("Cache miss", { key: "profile:42" });
+client.logs.success("Payment processed", { amount: 1999 });
+```
+
+When `enableLogs` is `false`, every method is a no-op.
+
+---
+
+### `DataxamasExceptions`
+
+Error capture. Accessed via `client.exceptions`. Delivers to `POST /api/v1/errors`, tagging `source` as `CLIENT` in the browser or `SERVER` in Node, plus `environment`/`release` when provided.
+
+#### `captureException(error, context?)`
+
+Capture an error (or any thrown value) with optional structured context.
+
+```ts
+try {
+  JSON.parse(raw);
+} catch (error) {
+  client.exceptions.captureException(error, { action: "parse-config", userId: 42 });
+}
+```
+
+Accepts `Error`, `string`, or any value — it is normalized to `{ name, message, stack }`. In the browser it also attaches `url` and `userAgent`.
+
+#### `install()`
+
+Attach global handlers so uncaught errors are captured automatically. Called for you when `captureGlobalErrors` is `true` (the default).
+
+- **Browser:** `window` `error` + `unhandledrejection`.
+- **Node:** `process` `uncaughtException` + `unhandledRejection`.
+
+Idempotent and a no-op when error tracking is disabled.
+
+---
+
+### `DataxamasTracking`
+
+Web analytics collector. **Browser-only.** Available as `client.tracking`, or standalone:
+
+```ts
+import { DataxamasTracking } from "@dataxamas/tracker-js";
+
+const tracking = new DataxamasTracking({ apiKey: "dx_live_xxx" });
+tracking.start();
+```
+
+**Options** (`DataxamasTrackingOptions`)
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `apiKey` | `string` | — | **Required.** Website API key (`dx_live_`). |
+| `baseUrl` | `string` | `https://dataxamas.izakdvlpr.com` | API base URL. |
+| `replayEnabled` | `boolean` | `true` | Allow session replay (gated by server config). |
+| `heatMapEnabled` | `boolean` | `true` | Collect heat-map coordinates on clicks. |
+| `allowLocalhost` | `boolean` | `false` | Allow tracking on `localhost`/`127.0.0.1`. |
+
+#### `start()`
+
+Begin collecting. Waits for `DOMContentLoaded` if the document is still loading, then tracks:
+
+- **`PAGE_VIEW`** — on init and on SPA path changes (polled every 500 ms).
+- **`CLICK`** — element `tagName`, `text`, `href`, `id`, `classes`, plus heat-map coordinates (viewport ratios, scroll offsets, layout fingerprint) when `heatMapEnabled`.
+- **`SCROLL`** — scroll-depth percentage (debounced).
+
+Events are queued and flushed to `POST /api/v1/events` with a 4s spacing. Every request sends `Authorization: Bearer <apiKey>`. The key is visible to anyone who opens the page, and it can also read events through `GET /api/v1/events` — treat it as public and rotate it from the dashboard if abused. A visitor session id is generated once and stored in `localStorage` under `@dataxamas/session`.
+
+If `replayEnabled` is on and the server config allows it, session replay starts: `rrweb` is lazy-imported and recordings are sent to `POST /api/v1/replay`.
+
+**Behavior notes**
+
+- Throws `"DataxamasTracking: This SDK can only be used in a browser environment."` if called on the server.
+- Silent no-op on `localhost`/`127.0.0.1` unless `allowLocalhost: true` — so development traffic isn't recorded by default.
+
+**Replay privacy** — mark sensitive DOM to keep it out of recordings:
+
+- `class="dx-mask"` — masks the element's text.
+- `class="dx-block"` — blocks the element entirely.
+
+All inputs are masked by default.
+
+---
+
+### `DataxamasApiError`
+
+Error class thrown/returned for failed API responses.
+
+```ts
+class DataxamasApiError extends Error {
+  code: string;
+  message: string;
+  status: number;
+}
+```
+
+---
+
+### Types
+
+Exported for use in your own typings:
+
+- `DataxamasOptions` — options for `new Dataxamas(...)`.
+- `DataxamasTrackingOptions` — options for `new DataxamasTracking(...)`.
+- `LogLevel` — `"DEBUG" | "INFO" | "WARN" | "LOG" | "SUCCESS"`.
+- `LogsConfig` — internal config shape for `DataxamasLogs`.
+- `ErrorSource` — `"CLIENT" | "SERVER"`.
+- `ErrorLevel` — `"ERROR" | "WARNING" | "FATAL"`.
+- `ExceptionsConfig` — internal config shape for `DataxamasExceptions`.
+
+---
+
+## Notes
+
+- **Default endpoint:** `https://dataxamas.izakdvlpr.com`. Override with `baseUrl`.
+- **Session storage key:** `localStorage["@dataxamas/session"]`.
+- **Event flush spacing:** 4 seconds between queued analytics events.
+- **Replay masking classes:** `dx-mask` (text) and `dx-block` (element); all inputs masked by default.
+- **Bundle:** `rrweb` is bundled but split into its own async chunk, loaded only when replay starts — the server/import path never touches it.