swetrix 4.1.0 → 4.3.0

package/README.md

@@ -1,26 +1,257 @@
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://swetrix.com/assets/logo_white.png">
-  <img alt="" src="https://swetrix.com/assets/logo_blue.png" height="80">
+  <source media="(prefers-color-scheme: dark)" srcset="https://swetrix.com/assets/logo_white.png?v=2">
+  <img alt="Swetrix" src="https://swetrix.com/assets/logo_blue.png?v=2" height="80">
 </picture>
 <br /><br />
 
-[![JSDelivr hits](https://data.jsdelivr.com/v1/package/gh/Swetrix/swetrix-js/badge?style=rounded)](https://data.jsdelivr.com/v1/package/gh/Swetrix/swetrix-js/stats)
-[![Package size](https://img.shields.io/bundlephobia/minzip/swetrix)](https://bundlephobia.com/api/size?package=swetrix)
+[![NPM](https://img.shields.io/npm/v/swetrix)](https://www.npmjs.com/package/swetrix)
+[![Package size](https://img.shields.io/bundlephobia/minzip/swetrix)](https://bundlephobia.com/package/swetrix)
+[![JSDelivr hits](https://data.jsdelivr.com/v1/package/npm/swetrix/badge?style=rounded)](https://www.jsdelivr.com/package/npm/swetrix)
 [![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/swetrix/swetrix-js/issues)
 
 # Swetrix Tracking Script
 
-This repository contains the analytics script which is used at https://swetrix.com \
-You can find the detailed documentation and use cases at our [docs page](https://docs.swetrix.com/).
+Privacy-first, lightweight analytics tracking library for [Swetrix](https://swetrix.com). Tracks page views, custom events, errors, feature flags, and A/B experiments — all without cookies or invading user privacy.
 
-Feel free to contribute to the source code by opening a pull requests. \
-For any questions, you can open an issue ticket, refer to our [FAQs](https://swetrix.com/#faq) page or reach us at contact@swetrix.com
+## Installation
 
-The latest live versions of the script are located at [jsDelivr](https://swetrix.org/swetrix.js) and [NPM](https://www.npmjs.com/package/swetrix).
+### npm / yarn / pnpm
 
-# Selfhosted API
-If you are selfhosting the [Swetrix-API](https://github.com/Swetrix/swetrix-api), be sure to point the `apiUrl` parameter to: `https://yourapiinstance.com/log`
+```bash
+npm install swetrix
+```
 
-# Donate
-You can support the project by donating us at https://ko-fi.com/andriir \
-We can only run our services by once again asking for your financial support!
+### CDN
+
+```html
+<script src="https://swetrix.org/swetrix.js" defer></script>
+```
+
+## Quick Start
+
+### ES Modules
+
+```javascript
+import { init, trackViews, trackErrors } from 'swetrix'
+
+init('YOUR_PROJECT_ID')
+trackViews()
+trackErrors()
+```
+
+### CDN / Script Tag
+
+```html
+<script src="https://swetrix.org/swetrix.js" defer></script>
+<script>
+  document.addEventListener('DOMContentLoaded', () => {
+    swetrix.init('YOUR_PROJECT_ID')
+    swetrix.trackViews()
+    swetrix.trackErrors()
+  })
+</script>
+```
+
+## API
+
+### `init(projectId, options?)`
+
+Initialise the library. Must be called before any other method.
+
+```javascript
+init('YOUR_PROJECT_ID', {
+  apiURL: 'https://api.swetrix.com/log',
+  devMode: false,
+  disabled: false,
+  respectDNT: false,
+  profileId: 'user-123',
+  preloadSessionReplay: false,
+})
+```
+
+| Option | Description | Default |
+|---|---|---|
+| `apiURL` | API endpoint. Change this if you're self-hosting. | `'https://api.swetrix.com/log'` |
+| `devMode` | When `true`, localhost events are sent to the server. | `false` |
+| `disabled` | When `true`, no data is sent. Useful for dev environments. | `false` |
+| `respectDNT` | When `true`, disables tracking for users with Do Not Track enabled. | `false` |
+| `profileId` | Profile ID for long-term user tracking (MAU/DAU). | `undefined` |
+| `preloadSessionReplay` | Preload the session replay recorder after `init()`. Recording only starts after `startSessionReplay()`. | `undefined` |
+
+### `trackViews(options?)`
+
+Automatically tracks page views, including navigation changes in SPAs. Returns a `Promise<{ stop() }>`.
+
+```javascript
+const { stop } = await trackViews({
+  hash: false,
+  search: false,
+  unique: false,
+  heartbeatOnBackground: false,
+  callback: undefined,
+})
+
+// Stop tracking when needed
+stop()
+```
+
+| Option | Description | Default |
+|---|---|---|
+| `hash` | Track hash-based routing (e.g. `/#/path`). | `false` |
+| `search` | Track search/query-based routing (e.g. `/path?query`). | `false` |
+| `unique` | Only count unique page views per session. | `false` |
+| `heartbeatOnBackground` | Send heartbeat when the tab is not active. | `false` |
+| `callback` | A function to edit or prevent pageview payloads. Return `false` to block, `true` to send as-is, or return a modified payload object. | `undefined` |
+
+### `track(event)`
+
+Track custom events (e.g. button clicks, sign-ups).
+
+```javascript
+track({
+  ev: 'signup',
+  unique: true,
+  meta: { plan: 'pro', source: 'landing' },
+  profileId: 'user-123',
+})
+```
+
+| Option | Description | Default |
+|---|---|---|
+| `ev` | Event name (max 256 chars). | **required** |
+| `unique` | Only count once per session. | `false` |
+| `meta` | Key-value metadata (max 20 keys, 1000 chars total). | `{}` |
+| `profileId` | Optional profile ID. Overrides the global `profileId` for this event. | `undefined` |
+
+### `trackErrors(options?)`
+
+Automatically captures client-side errors. Returns `{ stop() }`.
+
+```javascript
+const { stop } = trackErrors({
+  sampleRate: 1,
+  callback: undefined,
+})
+```
+
+| Option | Description | Default |
+|---|---|---|
+| `sampleRate` | Fraction of errors to send (`0` to `1`). | `1` |
+| `callback` | Edit or prevent error payloads. Return `false` to block. | `undefined` |
+
+### `trackError(payload)`
+
+Manually report an error.
+
+```javascript
+trackError({
+  name: 'PaymentError',
+  message: 'Card declined',
+  meta: { gateway: 'stripe' },
+})
+```
+
+### `pageview(options)`
+
+Manually track a single page view (useful for custom routing).
+
+```javascript
+pageview({
+  payload: { pg: '/checkout', lc: 'en-US' },
+  unique: true,
+})
+```
+
+### Feature Flags
+
+```javascript
+// Get all flags. Results are cached for 5 minutes.
+const flags = await getFeatureFlags({ profileId: 'user-123' })
+
+// Force a fresh fetch
+const freshFlags = await getFeatureFlags({ profileId: 'user-123' }, true)
+
+// Get a single flag. The third argument is an optional fallback value.
+const enabled = await getFeatureFlag('dark-mode', { profileId: 'user-123' })
+const enabledWithFallback = await getFeatureFlag('dark-mode', { profileId: 'user-123' }, false)
+
+// Clear the shared feature flag / experiment cache
+clearFeatureFlagsCache()
+```
+
+### A/B Experiments
+
+```javascript
+// Get all running experiment assignments. Results are cached for 5 minutes.
+const experiments = await getExperiments({ profileId: 'user-123' })
+
+// Force a fresh fetch
+const freshExperiments = await getExperiments({ profileId: 'user-123' }, true)
+
+// Get a specific experiment variant. The third argument is an optional fallback variant.
+const variant = await getExperiment('checkout-redesign-experiment-id', { profileId: 'user-123' })
+const variantWithFallback = await getExperiment('checkout-redesign-experiment-id', { profileId: 'user-123' }, 'control')
+
+// Clear the shared feature flag / experiment cache
+clearExperimentsCache()
+```
+
+### `startSessionReplay(options?)`
+
+Start recording a session replay. Session replays use `total` privacy by default, which masks text and inputs and blocks media/canvas capture unless you explicitly choose another mode.
+
+If you use the npm package, rrweb is dynamically imported from your installed dependencies only when the recorder is preloaded or started. If you use the CDN/script-tag build, the standalone replay recorder is loaded with an async script tag.
+
+```javascript
+const replay = await startSessionReplay({
+  privacy: 'total',
+  sampleRate: 0.25,
+  maxDurationMs: 10 * 60 * 1000,
+  idleTimeoutMs: 2 * 60 * 1000,
+})
+
+// Stop or flush manually when needed
+await replay.flush()
+await replay.stop()
+```
+
+| Option | Description | Default |
+|---|---|---|
+| `privacy` | Privacy mode: `total`, `normal`, or `none`. | `'total'` |
+| `sampleRate` | Fraction of sessions to record (`0` to `1`). | `1` |
+| `maxDurationMs` | Stop recording after this duration. | `undefined` |
+| `idleTimeoutMs` | Stop recording after this much visitor inactivity. | `undefined` |
+| `flushIntervalMs` | Upload buffered replay events at this interval. | `5000` |
+| `maxEventsPerChunk` | Upload once this many events are buffered. | `100` |
+| `rrweb` | Additional rrweb record options. | `undefined` |
+
+### Session & Profile IDs
+
+```javascript
+const profileId = await getProfileId()
+const sessionId = await getSessionId()
+```
+
+These are useful for revenue attribution with payment providers like Paddle.
+
+## Self-Hosting
+
+If you're running a self-hosted [Swetrix API](https://github.com/Swetrix/swetrix-api) instance, point the `apiURL` to your server:
+
+```javascript
+init('YOUR_PROJECT_ID', {
+  apiURL: 'https://your-api.example.com/log',
+})
+```
+
+## Documentation
+
+Full reference and guides are available at [docs.swetrix.com](https://docs.swetrix.com).
+
+## Contributing
+
+Contributions are welcome — feel free to [open an issue](https://github.com/swetrix/swetrix-js/issues) or submit a pull request.
+
+## License
+
+MIT

package/dist/esnext/Lib.d.ts

@@ -1,3 +1,22 @@
+type RrwebEvent = Record<string, unknown>;
+type RrwebEmit = (event: RrwebEvent) => void;
+interface RrwebRecordOptions {
+    emit?: RrwebEmit;
+    [key: string]: unknown;
+}
+interface RrwebGlobal {
+    record?: (options: RrwebRecordOptions) => (() => void) | undefined;
+    Replayer?: unknown;
+}
+type SessionReplayPreloadOption = boolean | {
+    rrwebUrl?: string;
+};
+declare global {
+    interface Window {
+        rrweb?: RrwebGlobal;
+        __SWETRIX_RRWEB_LOADING__?: Promise<void>;
+    }
+}
 export interface LibOptions {
     /**
      * When set to `true`, localhost events will be sent to server.
@@ -19,6 +38,10 @@ export interface LibOptions {
      * If set, it will be used for all pageviews and events unless overridden per-call.
      */
     profileId?: string;
+    /**
+     * Preload session replay recorder code. Recording only starts after calling startSessionReplay().
+     */
+    preloadSessionReplay?: SessionReplayPreloadOption;
 }
 export interface TrackEventOptions {
     /** The custom event name. */
@@ -42,6 +65,12 @@ export interface IPageViewPayload {
     te?: string;
     co?: string;
     pg?: string | null;
+    /**
+     * Raw URL query string of the landing page (without the leading `?`).
+     * Used server-side to recover the traffic source from ad/social click
+     * IDs (gclid, fbclid, etc.) when the browser stripped the referrer.
+     */
+    qs?: string;
     /** Pageview-related metadata object with string values. */
     meta?: {
         [key: string]: string | number | boolean | null | undefined;
@@ -111,6 +140,21 @@ export interface ErrorActions {
     /** Stops the tracking of errors. */
     stop: () => void;
 }
+declare const SESSION_REPLAY_PRIVACY_VALUES: readonly ["total", "normal", "none"];
+export type SessionReplayPrivacy = (typeof SESSION_REPLAY_PRIVACY_VALUES)[number];
+export interface SessionReplayOptions {
+    privacy?: SessionReplayPrivacy;
+    rrweb?: RrwebRecordOptions;
+    flushIntervalMs?: number;
+    maxEventsPerChunk?: number;
+    sampleRate?: number;
+    maxDurationMs?: number;
+    idleTimeoutMs?: number;
+}
+export interface SessionReplayActions {
+    stop: () => Promise<void>;
+    flush: () => Promise<void>;
+}
 export interface PageData {
     /** Current URL path. */
     path: string;
@@ -163,6 +207,7 @@ export interface PageViewsOptions {
 export declare const defaultActions: {
     stop(): void;
 };
+export declare const defaultSessionReplayActions: SessionReplayActions;
 export declare class Lib {
     private projectID;
     private options?;
@@ -173,6 +218,9 @@ export declare class Lib {
     private activePage;
     private errorListenerExists;
     private cachedData;
+    private rrwebLoader;
+    private sessionReplayActions;
+    private sessionReplayInitPromise;
     constructor(projectID: string, options?: LibOptions | undefined);
     captureError(event: ErrorEvent): void;
     trackErrors(options?: ErrorOptions): ErrorActions;
@@ -181,10 +229,10 @@ export declare class Lib {
     trackPageViews(options?: PageViewsOptions): PageActions;
     getPerformanceStats(): IPerfPayload | {};
     /**
-     * Fetches all feature flags and experiments for the project.
-     * Results are cached for 5 minutes by default.
+     * Fetches all feature flags for the project.
+     * Results are cached for 5 minutes by default and share a cache with experiments.
      *
-     * @param options - Options for evaluating feature flags.
+     * @param options - Options for evaluating feature flags (`profileId` only).
      * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
      * @returns A promise that resolves to a record of flag keys to boolean values.
      */
@@ -197,8 +245,8 @@ export declare class Lib {
      * Gets the value of a single feature flag.
      *
      * @param key - The feature flag key.
-     * @param options - Options for evaluating the feature flag.
-     * @param defaultValue - Default value to return if the flag is not found. Defaults to false.
+     * @param options - Options for evaluating the feature flag (`profileId` only).
+     * @param defaultValue - Optional default value to return if the flag is not found. Defaults to false.
      * @returns A promise that resolves to the boolean value of the flag.
      */
     getFeatureFlag(key: string, options?: FeatureFlagsOptions, defaultValue?: boolean): Promise<boolean>;
@@ -207,16 +255,16 @@ export declare class Lib {
      */
     clearFeatureFlagsCache(): void;
     /**
-     * Fetches all A/B test experiments for the project.
+     * Fetches variant assignments for running A/B test experiments returned by feature flag evaluation.
      * Results are cached for 5 minutes by default (shared cache with feature flags).
      *
-     * @param options - Options for evaluating experiments.
+     * @param options - Options for evaluating experiments (`profileId` only).
      * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
      * @returns A promise that resolves to a record of experiment IDs to variant keys.
      *
      * @example
      * ```typescript
-     * const experiments = await getExperiments()
+     * const experiments = await getExperiments({ profileId: 'user-123' })
      * // experiments = { 'exp-123': 'variant-a', 'exp-456': 'control' }
      * ```
      */
@@ -225,13 +273,16 @@ export declare class Lib {
      * Gets the variant key for a specific A/B test experiment.
      *
      * @param experimentId - The experiment ID.
-     * @param options - Options for evaluating the experiment.
-     * @param defaultVariant - Default variant key to return if the experiment is not found. Defaults to null.
+     * @param options - Options for evaluating the experiment (`profileId` only).
+     * @param defaultVariant - Optional default variant key to return if the experiment is not found. Defaults to null.
      * @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.
      *
      * @example
      * ```typescript
-     * const variant = await getExperiment('checkout-redesign')
+     * const variant = await getExperiment('checkout-redesign', { profileId: 'user-123' })
+     *
+     * // Optional fallback variant:
+     * const variantWithFallback = await getExperiment('checkout-redesign', undefined, 'control')
      *
      * if (variant === 'new-checkout') {
      *   // Show new checkout flow
@@ -292,6 +343,10 @@ export declare class Lib {
      * ```
      */
     getSessionId(): Promise<string | null>;
+    startSessionReplay(options?: SessionReplayOptions): Promise<SessionReplayActions>;
+    private initialiseSessionReplay;
+    private shouldSampleSessionReplay;
+    private getSessionReplayPrivacy;
     /**
      * Gets the API base URL (without /log suffix).
      */
@@ -301,6 +356,19 @@ export declare class Lib {
     private trackPage;
     submitPageView(payload: Partial<IPageViewPayload>, unique: boolean, perf: IPerfPayload | {}, evokeCallback?: boolean): void;
     private canTrack;
+    private getSessionReplayUrl;
+    private getSessionReplayPreloadOption;
+    private getDefaultSessionReplayUrl;
+    private getTrackerScript;
+    private preloadSessionReplay;
+    private loadSessionReplayRecorder;
+    private loadSessionReplayPackage;
+    private loadSessionReplayScript;
+    private getSessionReplayRecordOptions;
+    private mergeSelectors;
+    private createReplayId;
+    private sendSessionReplayStart;
+    private sendSessionReplayChunk;
     private sendRequest;
 }
 export {};