Dataxamas SDK

Official JavaScript/TypeScript SDK for the Dataxamas 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

bun add dataxamas
# or
npm install dataxamas
# or
pnpm add dataxamas
# or
yarn add dataxamas

Quick start

Browser (analytics + logs + error tracking)

import { Dataxamas } from "dataxamas";

const client = new Dataxamas({
  token: "dx_live_xxx",
  websiteId: "your-website-id",
});

// 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)

import { Dataxamas } from "dataxamas";

const client = new Dataxamas({
  token: "dx_live_xxx",
  websiteId: "your-website-id",
  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

| 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).

const client = new Dataxamas(options);

Options (DataxamasOptions)

| Option | Type | Default | Description | | --- | --- | --- | --- | | token | string | — | Required. API token for authenticating logs/errors. | | websiteId | string | — | Required. Target website id for analytics. | | 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 token or websiteId 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. |

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.

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:

import { DataxamasTracking } from "dataxamas";

const tracking = new DataxamasTracking({ websiteId: "your-website-id" });
tracking.start();

Options (DataxamasTrackingOptions)

| Option | Type | Default | Description | | --- | --- | --- | --- | | websiteId | string | — | Required. Target website id. | | 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/websites/events with a 4s spacing. 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/websites/{websiteId}/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.

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.