@cloff/sdk 1.0.0

package/README.md

@@ -0,0 +1,244 @@
+# Clof SDK (Client Analytics & Session Replay)
+
+A lightweight, performance-optimized, and privacy-preserving Web Analytics, Session Replay, and Canister APM observability library, complete with an offline-first buffering engine and embeddable analytics UI widget.
+
+Designed for decentralized apps (dApps) to easily record active user metrics, sessions, custom events, campaign UTM parameters, Core Web Vitals, exceptions (with timeline breadcrumbs), and securely embed verified analytics charts for public display.
+
+---
+
+## Key Features
+
+- ⚡ **Lightweight**: Minimal dependencies, keeping your bundle sizes ultra-small.
+- 📶 **Offline-First Buffering**: Telemetry data (page views, events, exceptions) is safely queued in `localStorage` if the user is offline or a request fails, preventing data loss.
+- 🔄 **Auto-Flush Sync**: Automatically listens to browser connectivity transitions (`online` event) to seamlessly flush buffered logs to the registry database.
+- 🐞 **Error & Exception Tracker**: Capture uncaught runtime exceptions and promise rejections with auto-collected chronological breadcrumbs.
+- 🕒 **Session Lifecycle Manager**: Automatically maintains sessions in `sessionStorage` with a 30-minute idle inactivity timeout.
+- 🏷️ **UTM & Referrer Tracking**: Automatically parses and reports campaign sources (`utm_source`, `utm_medium`, `utm_campaign`) and traffic referrers.
+- ⚙️ **Automatic Page View Tracking**: Listeners to automatically track route changes in single-page apps (SPA) using `window.history` monkeypatching.
+- 📈 **Core Web Vitals Observer**: Natively tracks performance metrics (Page Load Time, Largest Contentful Paint, Cumulative Layout Shift, and Interaction to Next Paint).
+- 🧬 **ICP Canister Observability (APM)**: Track and monitor duration, latency, and status (success/reject/error) of actors and canister calls.
+- 📊 **Embeddable Chart Widget**: A responsive, framework-agnostic Custom Element Web Component `<clof-widget>` to show verified public analytics.
+
+---
+
+## Installation
+
+Install the package via your preferred package manager:
+
+```bash
+npm install @cloff/sdk
+# or
+yarn add @cloff/sdk
+# or
+pnpm add @cloff/sdk
+```
+
+---
+
+## 🚀 Usage
+
+### 1. Initialization Config
+Configure the tracker by passing your API Key and optional configuration attributes:
+
+```typescript
+import { Clof } from '@cloff/sdk';
+
+const tracker = new Clof('YOUR_API_KEY', {
+  debug: false,                // Enable console logs for debugging
+  autoTrackPageViews: true,     // Automatically listen to SPA route changes
+  userId: () => getCurrentUid(), // Dynamic getter to retrieve the current user's ID
+  enableErrors: true,          // Automatically capture uncaught errors & unhandled rejections
+  enableAPM: true,             // Track network request durations and Page Vitals
+  enableCanisterAPM: true,     // Track ICP canister calls automatically
+  captureConsole: false        // Capture console.error statements as breadcrumbs
+});
+```
+
+#### Configuration Options
+*   `debug`: `boolean` (default `false`) — Logs SDK actions to the developer console.
+*   `autoTrackPageViews`: `boolean` (default `false`) — Automatically hooks into browser navigation/history to log page views.
+*   `userId`: `string | (() => string | null | undefined)` — Required if `autoTrackPageViews` is enabled. A string or function returning the active user ID.
+*   `enableErrors`: `boolean` (default `true`) — Automatically catches unhandled browser errors, promise rejections, and enables manual error reporting.
+*   `enableAPM`: `boolean` (default `true`) — Captures web performance metrics and Core Web Vitals (LCP, CLS, INP).
+*   `enableCanisterAPM`: `boolean` (default `true`) — Captures duration, canister ID, method name, call types, and responses for smart contract interactions.
+*   `captureConsole`: `boolean` (default `false`) — Monopoles `console.error` calls and appends them as diagnostic breadcrumbs.
+
+---
+
+### 2. Manual Tracking APIs
+
+#### A. Track Page Views (with Performance Vitals)
+Manually track page views. The SDK automatically appends page load speeds and Web Vitals if observed:
+
+```typescript
+tracker.trackPageView('user_wallet_address', {
+  path: '/marketplace',          // Defaults to window.location.pathname
+  title: 'NFT Marketplace',      // Defaults to document.title
+  referrer: 'https://google.com' // Defaults to document.referrer
+});
+```
+
+#### B. Track Custom Events
+Log custom interaction metrics, user goals, or conversion triggers:
+
+```typescript
+tracker.trackEvent('user_wallet_address', 'swap_completed', {
+  pair: 'ICP-USDT',
+  amount: 250.0,
+  slippage: 0.005
+});
+```
+
+#### C. Deduplicated Active User Ping
+Pings the server once per day per user (automatically cached and deduplicated in `localStorage` to save network bandwidth):
+
+```typescript
+tracker.track('user_wallet_address');
+```
+
+---
+
+### 3. Canister APM Tracking
+
+Track calls to smart contract canisters on the Internet Computer. The SDK collects latencies, success rates, and errors.
+
+```typescript
+tracker.trackCanisterCall(
+  'ryjl3-tyaaa-aaaaa-aaaba-cai', // Canister ID
+  'submitPost',                  // Method Name
+  'success',                     // 'success' | 'error'
+  140,                           // duration in milliseconds
+  { gasLimit: 300000 }           // Optional metadata payload
+);
+```
+
+---
+
+### 4. Error & Exception Handling APIs
+
+You can capture exceptions manually in try/catch blocks or hook them into framework-level error boundaries.
+
+#### A. Capture Exception
+Send a standard `Error` object or string description with optional contextual metadata. Uncaught exceptions will also package a chronological text timeline of the last 50 user journey actions (breadcrumbs) to enable **Session Replay**:
+
+```typescript
+try {
+  executeContractCall();
+} catch (error) {
+  tracker.captureException(error, {
+    gasLimit: 3000000,
+    canisterId: 'ryjl3-tyaaa-aaaaa-aaaba-cai'
+  });
+}
+```
+
+#### B. Capture Message
+Log arbitrary log events, warning states, or telemetry markers:
+
+```typescript
+tracker.captureMessage('Transaction took longer than expected', 'warning', {
+  durationMs: 8200
+});
+```
+
+---
+
+### 5. Offline-First Queuing Engine
+
+If a user's device loses internet connection, the SDK ensures no analytics or crash data is lost:
+1. All events (`trackPageView`, `trackEvent`, `captureException`) are serialized and buffered in `localStorage` under the key `clof_telemetry_queue_[apiKey]`.
+2. A queue buffer holds up to `500` events using First-In-First-Out eviction.
+3. The SDK hooks into the browser `online` window event. When the internet connection returns, it automatically flushes all buffered events sequentially in the background.
+
+---
+
+## 📊 Public Analytics Widget Embed
+
+Embed the responsive `<clof-widget>` (or legacy `<socio-dau-widget>`) Custom Element to display active metrics charts and demographics publicly.
+
+### Widget Properties
+- `api-key`: (Required) Your registered app's API key.
+- `days`: Number of days of history to display on the SVG chart (default `30`).
+- `theme`: `dark` or `light` (default auto-detects browser/system theme).
+- `accent-color`: Hex color overriding the primary purple style (e.g. `#10b981` for emerald).
+
+### 1. React SPA (Vite / CRA)
+```tsx
+import { useEffect } from 'react';
+
+export default function VerifiedAnalytics() {
+  useEffect(() => {
+    // Loads custom element client-side
+    import('@cloff/sdk/widget');
+  }, []);
+
+  return (
+    <div style={{ width: '100%', maxWidth: '600px' }}>
+      {/* @ts-ignore */}
+      <clof-widget api-key="YOUR_API_KEY" days="30" theme="dark" />
+    </div>
+  );
+}
+```
+
+### 2. Next.js (SSR with Dynamic Import)
+To prevent server-side custom element rendering warnings and hydration mismatches, wrap the widget in a client component and load it dynamically with `ssr: false`:
+
+**Step 1: Create a client component wrapper (e.g. `WidgetWrapper.tsx`)**
+```tsx
+'use client';
+
+import { useEffect } from 'react';
+
+export default function WidgetWrapper() {
+  useEffect(() => {
+    import('@cloff/sdk/widget');
+  }, []);
+
+  return <clof-widget api-key="YOUR_API_KEY" days="30" theme="dark" />;
+}
+```
+
+**Step 2: Load with dynamic import in your page**
+```tsx
+import dynamic from 'next/dynamic';
+
+const PublicWidget = dynamic(() => import('./WidgetWrapper'), {
+  ssr: false,
+  loading: () => <p>Loading Analytics Widget...</p>,
+});
+```
+
+### 3. HTML / CDN Embed
+```html
+<!-- Load the widget Custom Element script -->
+<script type="module" src="https://esm.sh/@cloff/sdk@1.0.0/dist/widget.js"></script>
+
+<!-- Embed the custom element -->
+<clof-widget api-key="YOUR_API_KEY" days="30" theme="dark"></clof-widget>
+```
+
+### TypeScript JSX Declarations
+Add this interface to your `global.d.ts` or type declaration file to prevent JSX compilation element errors:
+
+```typescript
+declare namespace JSX {
+  interface IntrinsicElements {
+    'clof-widget': React.DetailedHTMLProps<
+      React.HTMLAttributes<HTMLElement> & {
+        'api-key': string;
+        days?: string | number;
+        theme?: 'dark' | 'light';
+        'accent-color'?: string;
+      },
+      HTMLElement
+    >;
+  }
+}
+```
+
+---
+
+## License
+
+MIT License.

package/dist/index.d.ts

@@ -0,0 +1,205 @@
+export interface TrackerConfig {
+    supabaseUrl?: string;
+    supabaseAnonKey?: string;
+    debug?: boolean;
+    autoTrackPageViews?: boolean;
+    userId?: string | (() => string | null | undefined);
+    enableErrors?: boolean;
+    enableAPM?: boolean;
+    enableCanisterAPM?: boolean;
+    captureConsole?: boolean;
+}
+export declare class Clof {
+    private apiKey;
+    private supabase;
+    private debug;
+    private sessionId;
+    private configUserId;
+    private enableErrors;
+    private enableAPM;
+    private enableCanisterAPM;
+    private captureConsole;
+    private breadcrumbs;
+    private maxBreadcrumbs;
+    private vitals;
+    constructor(apiKey: string, config?: TrackerConfig);
+    /**
+     * Helper to identify device form-factor from Navigator UA string
+     */
+    private getDeviceType;
+    /**
+     * Helper to extract browser name from UA string
+     */
+    private getBrowser;
+    /**
+     * Helper to extract OS name from UA string
+     */
+    private getOS;
+    /**
+     * Helper to retrieve timezone identifier as location
+     */
+    private getLocation;
+    /**
+     * Helper to parse UTM parameters from search URL
+     */
+    private getUTMParams;
+    /**
+     * Generate UUID v4
+     */
+    private generateUUID;
+    /**
+     * Resolve and ping the current user session
+     */
+    private getSessionId;
+    private registerSession;
+    private pingSession;
+    /**
+     * Observes page loading performance and layout stability
+     */
+    private setupVitalsObserver;
+    /**
+     * Setup a click listener to log interaction breadcrumbs
+     */
+    private setupClickObserver;
+    /**
+     * Intercept console warnings & errors to record breadcrumbs
+     */
+    private setupConsoleObserver;
+    /**
+     * Listen to global unhandled exceptions and promise rejections
+     */
+    private setupErrorObservers;
+    /**
+     * Hook global fetch to auto-trace API durations and catch status >= 400 silent errors
+     */
+    private setupFetchInterception;
+    /**
+     * Estimate cycles consumed by a canister call using client-side heuristics.
+     * Query calls are free on ICP. Update calls incur:
+     *   base_fee (5M) + est_instructions × 1 cycle/instruction + ingress_bytes × 2000 cycles/byte
+     */
+    static estimateCanisterCycles(callType: 'query' | 'update', durationMs: number, requestSize?: number): number;
+    /**
+     * Log a canister call action manually
+     */
+    trackCanisterCall(canisterId: string, method: string, status: 'success' | 'error', durationMs?: number, metadata?: any): void;
+    /**
+     * Add manual trace breadcrumbs
+     */
+    addBreadcrumb(message: string, category?: string, metadata?: any): void;
+    /**
+     * Track user activity (Legacy DAU Ping).
+     * Uses localStorage to deduplicate pings on the same day for a given user.
+     */
+    track(userId: string | number, force?: boolean): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Track specific Page Views.
+     * Logs page navigation events, referrer, and captures performance Web Vitals.
+     */
+    trackPageView(userId: string | number, options?: {
+        path?: string;
+        title?: string;
+        referrer?: string;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Track Custom Events (actions, goals, conversions)
+     */
+    trackEvent(userId: string | number, eventName: string, properties?: Record<string, any>): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Log an exception manually to the database
+     */
+    captureException(error: any, extraContext?: any): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Log a custom severity warning or info message to the database
+     */
+    captureMessage(message: string, severity?: 'error' | 'warning' | 'info', extraContext?: any): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Helper function to execute error logging RPC
+     */
+    private logErrorToDatabase;
+    /**
+     * Log latency of a duration in milliseconds manually
+     */
+    trackPerformanceSpan(name: string, durationMs: number, entryType?: string, metadata?: any): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Log latency of an ICP canister call with method-level granularity
+     */
+    trackCanisterSpan(canisterId: string, methodName: string, callType: 'query' | 'update', durationMs: number, status?: 'success' | 'reject' | 'error', errorMsg?: string, requestSize?: number, responseSize?: number): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Wrap an @dfinity/agent HttpAgent to intercept canister calls for APM.
+     * Returns the same agent proxied — no @dfinity/agent dependency needed.
+     *
+     * Usage:
+     *   import { HttpAgent } from '@dfinity/agent';
+     *   const agent = new HttpAgent();
+     *   const wrapped = tracker.wrapHttpAgent(agent);
+     *   // use wrapped everywhere instead of agent
+     */
+    wrapHttpAgent<T>(agent: T): T;
+    /**
+     * Start a performance span timer
+     */
+    startSpan(name: string, entryType?: string): {
+        end: (metadata?: any) => Promise<void>;
+    };
+    /**
+     * Measure latency of a function and resolve its result
+     */
+    measure<T>(name: string, fn: () => Promise<T> | T, entryType?: string, metadata?: any): Promise<T>;
+    /**
+     * Define a user funnel for conversion analysis.
+     * Stores the ordered event sequence to the database so the
+     * dashboard can visualize drop-off at each step.
+     *
+     * Example:
+     *   tracker.defineFunnel('Swap Flow', [
+     *     'connect_wallet',
+     *     'click_swap_token',
+     *     'sign_transaction',
+     *     'swap_success'
+     *   ])
+     */
+    defineFunnel(name: string, steps: string[]): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    private resolveUserId;
+    /**
+     * Listen to Single-Page App (SPA) route changes and track page views automatically
+     */
+    private setupAutoTracking;
+    private setupOnlineListener;
+    private isOnline;
+    private isNetworkError;
+    private getQueueKey;
+    private getOfflineQueue;
+    private saveOfflineQueue;
+    private enqueueOfflineAction;
+    private isFlushing;
+    private flushOfflineQueue;
+    private executeRpc;
+    private logDebug;
+    private logError;
+}
+export { Clof as SocioDauTracker, Clof as ClofTracker };