npm - alphana-sdk - Versions diffs - 0.2.0 - Mend

alphana-sdk 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,298 @@
+# alphana-sdk
+Client-side analytics SDK for React, Next.js, Vite, and vanilla JS/TS projects. Tracks navigation, time-on-page, heatmaps, error logs, and periodic page screenshots — all without cookies or third parties.
+## Installation
+```bash
+npm install alphana-sdk
+# pnpm
+pnpm add alphana-sdk
+# yarn
+yarn add alphana-sdk
+# bun
+bun add alphana-sdk
+```
+> **Snapshots optional:** If you want the screenshot feature (`trackSnapshots: true`), also install `html2canvas`:
+> ```bash
+> npm install html2canvas
+> ```
+---
+## Quick start
+### React / Vite
+```tsx
+// main.tsx
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { UserTrackerProvider } from 'alphana-sdk/react';
+import App from './App';
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <UserTrackerProvider
+      config={{
+        appId: import.meta.env.VITE_TRACKER_APP_ID,
+        secretKey: import.meta.env.VITE_TRACKER_SECRET,
+      }}
+    >
+      <App />
+    </UserTrackerProvider>
+  </StrictMode>,
+);
+```
+```bash
+# .env.local
+VITE_TRACKER_APP_ID=your_app_id
+VITE_TRACKER_SECRET=your_secret_key
+```
+### Next.js App Router
+Because App Router renders server-side by default, wrap the provider in a Client Component:
+```tsx
+// app/providers.tsx
+'use client';
+import { UserTrackerProvider } from 'alphana-sdk/react';
+import type { ReactNode } from 'react';
+export function Providers({ children }: { children: ReactNode }) {
+  return (
+    <UserTrackerProvider
+      config={{
+        appId: process.env.NEXT_PUBLIC_TRACKER_APP_ID!,
+        secretKey: process.env.NEXT_PUBLIC_TRACKER_SECRET!,
+      }}
+    >
+      {children}
+    </UserTrackerProvider>
+  );
+}
+```
+```tsx
+// app/layout.tsx
+import { Providers } from './providers';
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+```bash
+# .env.local
+NEXT_PUBLIC_TRACKER_APP_ID=your_app_id
+NEXT_PUBLIC_TRACKER_SECRET=your_secret_key
+```
+> **App Router page tracking:** The provider automatically intercepts `pushState` / `popstate`. For App Router you can optionally add an explicit page-view call using the `usePageView` hook in a Client Component:
+>
+> ```tsx
+> // app/components/NavigationTracker.tsx
+> 'use client';
+> import { usePathname } from 'next/navigation';
+> import { usePageView } from 'alphana-sdk/react';
+>
+> export function NavigationTracker() {
+>   usePageView(usePathname());
+>   return null;
+> }
+> ```
+### Vanilla JS / TypeScript
+```ts
+import { UserTracker } from 'alphana-sdk';
+const tracker = new UserTracker({
+  appId: 'YOUR_APP_ID',
+  secretKey: 'YOUR_SECRET_KEY',
+});
+tracker.init(); // attach listeners; no-op in SSR environments
+// Call on teardown / logout
+tracker.destroy();
+```
+---
+## Configuration reference
+| Option               | Type                            | Default                                 | Description                                                                        |
+| -------------------- | ------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------- |
+| `appId`              | `string`                        | —                                       | **Required.** Your app ID from the Alphana dashboard.                              |
+| `secretKey`          | `string`                        | —                                       | **Required.** SDK secret key — sent as `Authorization: Bearer`.                    |
+| `endpoint`           | `string`                        | `https://api.alphana.ir/api/events`     | Override only when self-hosting.                                                   |
+| `sessionId`          | `string`                        | auto UUID                               | Override the auto-generated session identifier.                                    |
+| `trackNavigation`    | `boolean`                       | `true`                                  | Intercept `pushState` / `popstate` for SPA route changes.                          |
+| `trackTime`          | `boolean`                       | `true`                                  | Measure time spent on each page.                                                   |
+| `trackHeatmap`       | `boolean`                       | `true`                                  | Record mouse-move, click, and scroll positions.                                    |
+| `trackLogs`          | `boolean`                       | `true`                                  | Capture `console.info/warn/error`, `window.onerror`, and `unhandledrejection`.     |
+| `trackSnapshots`     | `boolean`                       | `true`                                  | Send a full-page screenshot every interval (requires `html2canvas`).               |
+| `snapshotIntervalMs` | `number` (ms)                   | `300000` (5 min)                        | How often to capture a snapshot when `trackSnapshots` is enabled.                  |
+| `mouseSampleRate`    | `number` (0–1)                  | `0.3`                                   | Fraction of mouse/scroll events to record.                                         |
+| `maxHeatmapPoints`   | `number`                        | `2000`                                  | Maximum in-memory heatmap points per page.                                         |
+| `batchSize`          | `number`                        | `20`                                    | Events queued before an automatic batch flush.                                     |
+| `flushInterval`      | `number` (ms)                   | `5000`                                  | Milliseconds between automatic flushes regardless of queue size.                   |
+| `onEvent`            | `(event: TrackerEvent) => void` | —                                       | Callback invoked synchronously for every emitted event.                            |
+---
+## API
+### `UserTracker`
+```ts
+import { UserTracker } from 'alphana-sdk';
+const tracker = new UserTracker({ appId: 'id', secretKey: 'sk' });
+tracker.init();                         // attach listeners; no-op in SSR; returns `this`
+tracker.destroy();                      // remove all listeners and timers, flush remaining queue
+tracker.trackPageView(path?: string);   // manually record a page view
+tracker.getSession();                   // SessionData snapshot for the current session
+tracker.getPageViews();                 // PageView[] recorded this session
+tracker.getTimeSpent();                 // Record<path, ms> cumulative time per path
+tracker.getHeatmapData(path?: string);  // HeatmapPoint[] for path, or all paths if omitted
+tracker.flush();                        // immediately POST all queued events
+tracker.subscribe(fn);                  // register an event listener; returns an unsubscribe fn
+```
+**Heartbeat:** The SDK emits a `session:heartbeat` event every 30 seconds to keep the session alive.
+**Page-hide flush:** On `visibilitychange` (tab hidden or browser minimised) the SDK calls `navigator.sendBeacon` to ensure no events are dropped.
+### `LogCapture`
+Automatically used by `UserTracker` when `trackLogs: true`. Can also be used standalone:
+```ts
+import { LogCapture } from 'alphana-sdk';
+const capture = new LogCapture({
+  endpoint: 'https://your-backend.com/api/events',
+  sessionId: 'ses_abc123',
+  appId: 'YOUR_APP_ID',
+  secretKey: 'sk_...',
+});
+capture.init();    // patches console.info/warn/error, window.onerror, unhandledrejection
+capture.destroy(); // restores original methods
+```
+### `renderHeatmap`
+Renders a `HeatmapPoint[]` array onto a `<canvas>` element using a blue → red color palette.
+```ts
+import { renderHeatmap } from 'alphana-sdk';
+const canvas = document.getElementById('heatmap') as HTMLCanvasElement;
+canvas.width  = 1280;
+canvas.height = 720;
+renderHeatmap(canvas, points, {
+  radius:     25,    // blur radius in px       (default: 25)
+  maxOpacity: 0.85,  // max alpha for hotspots  (default: 0.85)
+  minOpacity: 0,     // min alpha for cold areas (default: 0)
+});
+```
+### `DEFAULT_ENDPOINT`
+The default API URL is exported if you need it:
+```ts
+import { DEFAULT_ENDPOINT } from 'alphana-sdk';
+// "https://api.alphana.ir/api/events"
+```
+---
+## React hooks
+All hooks are exported from `alphana/react`.
+| Hook                                 | Returns            | Description                                                        |
+| ------------------------------------ | ------------------ | ------------------------------------------------------------------ |
+| `useTracker()`                       | `UserTracker`      | Access the tracker instance from context.                          |
+| `usePageView(path?)`                 | `void`             | Record a page view when `path` changes (App Router helper).        |
+| `useHeatmapData(path?, refreshMs?)`  | `HeatmapPoint[]`   | Live heatmap points for a path, polled every `refreshMs` (500 ms). |
+| `usePageViews()`                     | `PageView[]`       | All page views recorded in the current session.                    |
+| `useTimeSpent()`                     | `number` (seconds) | Total time spent on the current page (updates every second).       |
+```tsx
+import { useTracker, useTimeSpent, useHeatmapData } from 'alphana-sdk/react';
+export function DebugPanel() {
+  const tracker   = useTracker();
+  const timeSpent = useTimeSpent();   // seconds on this page
+  const points    = useHeatmapData(); // HeatmapPoint[]
+  return (
+    <div>
+      <p>Time on page: {timeSpent}s</p>
+      <p>Heatmap points: {points.length}</p>
+      <button onClick={() => tracker.flush()}>Flush now</button>
+    </div>
+  );
+}
+```
+---
+## TypeScript types
+```ts
+import type {
+  TrackerConfig,
+  TrackerEvent,
+  PageView,
+  TimeSpent,
+  HeatmapPoint,
+  SessionData,
+  GeoLocation,
+  LogLevel,
+  LogEntry,
+  HeatmapRenderOptions,
+} from 'alphana-sdk';
+```
+---
+## Self-hosting
+The full backend, dashboard, and landing page are open source. To run on your own infrastructure:
+```bash
+git clone https://github.com/teokamalipour/alphana-sdk.git
+cd alphana-sdk
+cp .env.example .env   # fill in your values
+docker compose up -d   # starts MongoDB, NestJS backend, and React dashboard
+```
+Then point the SDK at your server:
+```ts
+new UserTracker({
+  appId: 'YOUR_APP_ID',
+  secretKey: 'YOUR_SECRET_KEY',
+  endpoint: 'https://your-server.example.com/api/events',
+});
+```

package/dist/index.d.mts ADDED Viewed

@@ -0,0 +1,289 @@
+interface TrackerConfig {
+    /**
+     * URL to POST events to.
+     * Defaults to `https://api.alphana.ir/api/events` — override only if self-hosting.
+     */
+    endpoint?: string;
+    /**
+     * App ID obtained from the UserTracker dashboard.
+     * Sent in every request body so the backend associates events with the correct app.
+     */
+    appId?: string;
+    /**
+     * App secret key obtained from the UserTracker dashboard.
+     * Sent as the `Authorization: Bearer` header on every request.
+     */
+    secretKey?: string;
+    /** Provide a custom session ID; auto-generated via crypto.randomUUID if omitted. */
+    sessionId?: string;
+    /** Track SPA route changes (pushState / replaceState / popstate). Default: true */
+    trackNavigation?: boolean;
+    /** Track time spent on each page. Default: true */
+    trackTime?: boolean;
+    /** Collect mouse-move, click, and scroll data for heatmap. Default: true */
+    trackHeatmap?: boolean;
+    /**
+     * Fraction of mousemove / scroll events to record (0–1).
+     * 1 = record every event, 0.3 = ~30 % sampled. Default: 0.3
+     */
+    mouseSampleRate?: number;
+    /** Maximum heatmap points stored in memory per page. Default: 2000 */
+    maxHeatmapPoints?: number;
+    /**
+     * Number of events to accumulate before an automatic flush is triggered.
+     * Default: 20
+     */
+    batchSize?: number;
+    /**
+     * Milliseconds between automatic batch flushes regardless of queue size.
+     * Default: 5000 (5 s)
+     */
+    flushInterval?: number;
+    /**
+     * Automatically capture console.info/warn/error, window.onerror, and
+     * unhandledrejection events and send them to the backend log endpoint.
+     * Default: true (when endpoint is provided)
+     */
+    trackLogs?: boolean;
+    /**
+     * Automatically capture and send full-page screenshots to the backend
+     * every 5 minutes for use in the heatmap view.
+     * Requires `html2canvas` to be installed in the host application:
+     *   npm install html2canvas
+     * Default: true (when endpoint is provided and html2canvas is installed)
+     */
+    trackSnapshots?: boolean;
+    /**
+     * Minimum milliseconds between screenshots for the same page path.
+     * Defaults to 300 000 (5 minutes). Only used when `trackSnapshots` is true.
+     */
+    snapshotIntervalMs?: number;
+    /** Called synchronously for every emitted event. */
+    onEvent?: (event: TrackerEvent) => void;
+}
+interface GeoLocation {
+    /** ISO 3166-1 alpha-2 country code, e.g. "US" */
+    country: string;
+    /** Human-readable country name, e.g. "United States" */
+    countryName: string;
+    city?: string;
+    region?: string;
+    latitude?: number;
+    longitude?: number;
+}
+interface PageView {
+    path: string;
+    title: string;
+    timestamp: number;
+    sessionId: string;
+    referrer?: string;
+}
+interface TimeSpent {
+    path: string;
+    /** Duration in milliseconds */
+    duration: number;
+    sessionId: string;
+    timestamp: number;
+}
+interface HeatmapPoint {
+    /** X position as a percentage of the full page width (0–100) */
+    xPct: number;
+    /** Y position as a percentage of the full page height (0–100) */
+    yPct: number;
+    /** Absolute X pixel in the viewport at the time of the event */
+    x: number;
+    /** Absolute Y pixel from the top of the page (includes scroll) */
+    y: number;
+    type: "move" | "click" | "scroll";
+    path: string;
+    timestamp: number;
+}
+type TrackerEvent = {
+    type: "pageview";
+    data: PageView;
+} | {
+    type: "timespent";
+    data: TimeSpent;
+} | {
+    type: "heatmap";
+    data: HeatmapPoint;
+};
+interface SessionData {
+    id: string;
+    startedAt: number;
+    pageViews: PageView[];
+    /** Cumulative milliseconds per path */
+    timeSpent: Record<string, number>;
+    /** Collected points per path */
+    heatmap: Record<string, HeatmapPoint[]>;
+    /** Approximate visitor location resolved from IP (filled asynchronously) */
+    location?: GeoLocation;
+}
+interface HeatmapRenderOptions {
+    /** Influence radius of each point in pixels. Default: 25 */
+    radius?: number;
+    /** Maximum opacity of the hottest areas (0–1). Default: 0.85 */
+    maxOpacity?: number;
+    /** Minimum opacity for the coolest visible areas (0–1). Default: 0 */
+    minOpacity?: number;
+}
+declare global {
+    interface WindowEventMap {
+        "tracker:navigate": CustomEvent<{
+            path: string;
+            title: string;
+        }>;
+    }
+}
+type LogLevel = "info" | "warn" | "error";
+interface LogEntry {
+    sessionId?: string;
+    appId?: string;
+    level: LogLevel;
+    message: string;
+    url?: string;
+    stack?: string;
+    meta?: Record<string, unknown>;
+    timestamp: number;
+}
+/**
+ * Automatically captures console.info/warn/error output and unhandled errors,
+ * then ships them to the backend `/logs/ingest` endpoint.
+ *
+ * All console methods are restored exactly in `destroy()`.
+ */
+declare class LogCapture {
+    private readonly endpoint;
+    private readonly sessionId;
+    private readonly appId?;
+    private readonly authHeaders;
+    private origInfo;
+    private origWarn;
+    private origError;
+    private prevOnError;
+    private prevOnUnhandledRejection;
+    private initialized;
+    constructor(options: {
+        endpoint: string;
+        sessionId: string;
+        secretKey?: string;
+        appId?: string;
+    });
+    init(): void;
+    destroy(): void;
+    /** Manually capture a log entry (e.g. from try/catch). */
+    capture(level: LogLevel, message: string, extra?: {
+        stack?: string;
+        meta?: Record<string, unknown>;
+    }): void;
+    private format;
+    private send;
+}
+declare const DEFAULT_ENDPOINT = "https://api.alphana.ir/api/events";
+type SubscriberFn = (event: TrackerEvent) => void;
+declare class UserTracker {
+    private readonly cfg;
+    private session;
+    private navigation?;
+    private time?;
+    private heatmap?;
+    /** Public so consumers can call logCapture.capture() for manual log entries. */
+    logCapture?: LogCapture;
+    private snapshot?;
+    private initialized;
+    private readonly subscribers;
+    /** In-memory queue of events waiting to be flushed. */
+    private queue;
+    private flushTimer;
+    private heartbeatTimer;
+    private location;
+    constructor(config?: TrackerConfig);
+    /**
+     * Attach event listeners and start tracking.
+     * Safe to call during SSR — returns `this` immediately if `window` is
+     * undefined so it can be chained: `const tracker = new UserTracker(cfg).init()`.
+     */
+    init(): this;
+    /** Remove all event listeners, flush remaining queue, and reset state. */
+    destroy(): void;
+    private handleVisibilityChange;
+    private handlePageHide;
+    private handleNavigate;
+    /**
+     * Send a keep-alive heartbeat so the backend knows this session is still
+     * active. Called every 30 s while the tab is visible.
+     */
+    private sendHeartbeat;
+    /**
+     * Send a synchronous beacon to mark this session as inactive.
+     * Called on page unload / tab hidden so the dashboard reflects real-time.
+     */
+    private sendDeactivate;
+    /** Emit a tracker event. Also used internally by the plugins. */
+    emit(event: TrackerEvent): void;
+    /**
+     * Subscribe to every emitted event. Returns an unsubscribe function.
+     *
+     * ```ts
+     * const unsub = tracker.subscribe(event => console.log(event));
+     * // later…
+     * unsub();
+     * ```
+     */
+    subscribe(fn: SubscriberFn): () => void;
+    /**
+     * Manually record a page view and dispatch `tracker:navigate`.
+     * Required for Next.js App Router — call it inside a `useEffect` that
+     * depends on `usePathname()`:
+     *
+     * ```tsx
+     * const pathname = usePathname();
+     * useEffect(() => { tracker.trackPageView(pathname); }, [pathname]);
+     * ```
+     */
+    trackPageView(path?: string): void;
+    /** A read-only snapshot of the current session. */
+    getSession(): Readonly<SessionData>;
+    /** All page views recorded so far. */
+    getPageViews(): PageView[];
+    /** Cumulative milliseconds spent per path. */
+    getTimeSpent(): Record<string, number>;
+    /** Heatmap points for a specific path. */
+    getHeatmapData(path: string): HeatmapPoint[];
+    /** Heatmap points for all tracked paths. */
+    getHeatmapData(): Record<string, HeatmapPoint[]>;
+    /** Drain the queue and POST all pending events to the batch endpoint. */
+    private flush;
+    /**
+     * Synchronous best-effort flush via `navigator.sendBeacon`.
+     * Used on `pagehide` / `visibilitychange:hidden` where async fetch may be
+     * cancelled by the browser before it completes.
+     */
+    private flushBeacon;
+    private buildBatchBody;
+    private sendBatch;
+}
+/**
+ * Renders `points` onto `canvas` as a color heatmap.
+ *
+ * Algorithm:
+ *   1. Draw each point as a soft radial gradient on an off-screen canvas,
+ *      accumulating "heat" in the alpha channel.
+ *   2. Map each pixel's accumulated alpha value through the color palette
+ *      (blue → cyan → green → yellow → orange → red) and write to the
+ *      destination canvas.
+ *
+ * Coordinates in `HeatmapPoint` are percentages (0–100) of page dimensions,
+ * which are scaled to the canvas size at render time — making it resolution
+ * independent.
+ *
+ * @param canvas  Target canvas element (will NOT be resized automatically).
+ * @param points  Array of heatmap points to render.
+ * @param options Visual tuning options.
+ */
+declare function renderHeatmap(canvas: HTMLCanvasElement, points: HeatmapPoint[], options?: HeatmapRenderOptions): void;
+export { DEFAULT_ENDPOINT, type GeoLocation, type HeatmapPoint, type HeatmapRenderOptions, LogCapture, type LogEntry, type LogLevel, type PageView, type SessionData, type TimeSpent, type TrackerConfig, type TrackerEvent, UserTracker, renderHeatmap };