@gurulu/web 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @gurulu/web — Gurulu Web SDK
+ *
+ * Programmatic interface for Gurulu analytics.
+ * For React/Next.js, use `@gurulu/web/react` instead.
+ */
+export interface GuruluConfig {
+    siteId: string;
+    token: string;
+    endpoint?: string;
+    features?: Array<'errors' | 'replay' | 'vitals'>;
+    autoTrack?: boolean;
+    consent?: 'full' | 'analytics' | 'necessary' | 'none';
+    debug?: boolean;
+}
+export interface GuruluInstance {
+    track: (eventName: string, properties?: Record<string, unknown>) => void;
+    identify: (userId: string, traits?: Record<string, unknown>) => void;
+    purchase: (params: {
+        value: number;
+        currency: string;
+        transaction_id?: string;
+        items?: unknown[];
+    }) => void;
+    subscribe: (params: {
+        value: number;
+        currency: string;
+        plan_id?: string;
+        interval?: string;
+    }) => void;
+    login: (params?: {
+        method?: string;
+    }) => void;
+    signup: (params?: {
+        method?: string;
+    }) => void;
+    logout: () => void;
+    setConsent: (level: string) => void;
+    destroy: () => void;
+}
+declare let _config: GuruluConfig | null;
+/**
+ * Initialize the Gurulu tracker by injecting the script tag.
+ * Call once at app startup.
+ */
+export declare function init(config: GuruluConfig): void;
+/**
+ * Get the global gurulu instance (available after tracker loads).
+ */
+export declare function getInstance(): GuruluInstance | null;
+/**
+ * Track a custom event.
+ */
+export declare function track(eventName: string, properties?: Record<string, unknown>): void;
+/**
+ * Identify a user with traits.
+ */
+export declare function identify(userId: string, traits?: Record<string, unknown>): void;
+/**
+ * Track a purchase event.
+ */
+export declare function purchase(params: {
+    value: number;
+    currency: string;
+    transaction_id?: string;
+}): void;
+/**
+ * Track a subscription event.
+ */
+export declare function subscribe(params: {
+    value: number;
+    currency: string;
+    plan_id?: string;
+    interval?: string;
+}): void;
+/**
+ * Set consent level.
+ */
+export declare function setConsent(level: string): void;
+export { _config as config };

package/dist/index.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * @gurulu/web — Gurulu Web SDK
+ *
+ * Programmatic interface for Gurulu analytics.
+ * For React/Next.js, use `@gurulu/web/react` instead.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+exports.init = init;
+exports.getInstance = getInstance;
+exports.track = track;
+exports.identify = identify;
+exports.purchase = purchase;
+exports.subscribe = subscribe;
+exports.setConsent = setConsent;
+let _config = null;
+exports.config = _config;
+let _scriptLoaded = false;
+/**
+ * Initialize the Gurulu tracker by injecting the script tag.
+ * Call once at app startup.
+ */
+function init(config) {
+    if (typeof window === 'undefined')
+        return; // SSR guard
+    if (_scriptLoaded)
+        return; // idempotent
+    exports.config = _config = config;
+    const endpoint = config.endpoint || 'https://gurulu.io';
+    const features = config.features?.join(',') || '';
+    const script = document.createElement('script');
+    script.src = `${endpoint}/t.js`;
+    script.defer = true;
+    script.setAttribute('data-site-id', config.siteId);
+    script.setAttribute('data-token', config.token);
+    if (features)
+        script.setAttribute('data-features', features);
+    if (config.consent)
+        script.setAttribute('data-consent', config.consent);
+    if (config.debug)
+        script.setAttribute('data-debug', 'true');
+    document.head.appendChild(script);
+    _scriptLoaded = true;
+}
+/**
+ * Get the global gurulu instance (available after tracker loads).
+ */
+function getInstance() {
+    if (typeof window === 'undefined')
+        return null;
+    return window.gurulu || null;
+}
+/**
+ * Track a custom event.
+ */
+function track(eventName, properties) {
+    getInstance()?.track(eventName, properties);
+}
+/**
+ * Identify a user with traits.
+ */
+function identify(userId, traits) {
+    getInstance()?.identify(userId, traits);
+}
+/**
+ * Track a purchase event.
+ */
+function purchase(params) {
+    getInstance()?.purchase(params);
+}
+/**
+ * Track a subscription event.
+ */
+function subscribe(params) {
+    getInstance()?.subscribe(params);
+}
+/**
+ * Set consent level.
+ */
+function setConsent(level) {
+    getInstance()?.setConsent(level);
+}

package/dist/react.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @gurulu/web/react — React/Next.js component for Gurulu analytics.
+ *
+ * Usage:
+ *   import { GuruluProvider } from '@gurulu/web/react';
+ *
+ *   // In your root layout:
+ *   <GuruluProvider siteId="xxx" token="yyy" features={['errors', 'replay']} />
+ */
+import { track, identify, getInstance } from './index';
+import type { GuruluConfig, GuruluInstance } from './index';
+export type { GuruluConfig, GuruluInstance };
+export { track, identify, getInstance };
+export interface GuruluProviderProps {
+    siteId: string;
+    token: string;
+    endpoint?: string;
+    features?: Array<'errors' | 'replay' | 'vitals'>;
+    autoTrack?: boolean;
+    consent?: 'full' | 'analytics' | 'necessary' | 'none';
+    debug?: boolean;
+    /** Auto-identify the current user (pass userId + email after auth) */
+    userId?: string;
+    userEmail?: string;
+}
+/**
+ * Drop-in React component that initializes Gurulu tracking.
+ * Renders nothing — just injects the tracker script and optionally identifies the user.
+ *
+ * ```tsx
+ * // app/layout.tsx
+ * import { GuruluProvider } from '@gurulu/web/react';
+ *
+ * export default function Layout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         {children}
+ *         <GuruluProvider
+ *           siteId="your-site-id"
+ *           token="your-token"
+ *           features={['errors', 'replay']}
+ *         />
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+export declare function GuruluProvider({ siteId, token, endpoint, features, autoTrack, consent, debug, userId, userEmail, }: GuruluProviderProps): null;
+/**
+ * Hook to get the Gurulu tracker instance.
+ * Returns null until the tracker script has loaded.
+ */
+export declare function useGurulu(): GuruluInstance | null;

package/dist/react.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * @gurulu/web/react — React/Next.js component for Gurulu analytics.
+ *
+ * Usage:
+ *   import { GuruluProvider } from '@gurulu/web/react';
+ *
+ *   // In your root layout:
+ *   <GuruluProvider siteId="xxx" token="yyy" features={['errors', 'replay']} />
+ */
+'use client';
+/**
+ * @gurulu/web/react — React/Next.js component for Gurulu analytics.
+ *
+ * Usage:
+ *   import { GuruluProvider } from '@gurulu/web/react';
+ *
+ *   // In your root layout:
+ *   <GuruluProvider siteId="xxx" token="yyy" features={['errors', 'replay']} />
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInstance = exports.identify = exports.track = void 0;
+exports.GuruluProvider = GuruluProvider;
+exports.useGurulu = useGurulu;
+const react_1 = require("react");
+const index_1 = require("./index");
+Object.defineProperty(exports, "track", { enumerable: true, get: function () { return index_1.track; } });
+Object.defineProperty(exports, "identify", { enumerable: true, get: function () { return index_1.identify; } });
+Object.defineProperty(exports, "getInstance", { enumerable: true, get: function () { return index_1.getInstance; } });
+/**
+ * Drop-in React component that initializes Gurulu tracking.
+ * Renders nothing — just injects the tracker script and optionally identifies the user.
+ *
+ * ```tsx
+ * // app/layout.tsx
+ * import { GuruluProvider } from '@gurulu/web/react';
+ *
+ * export default function Layout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         {children}
+ *         <GuruluProvider
+ *           siteId="your-site-id"
+ *           token="your-token"
+ *           features={['errors', 'replay']}
+ *         />
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+function GuruluProvider({ siteId, token, endpoint, features, autoTrack = true, consent, debug, userId, userEmail, }) {
+    const initialized = (0, react_1.useRef)(false);
+    const identified = (0, react_1.useRef)(false);
+    (0, react_1.useEffect)(() => {
+        if (initialized.current)
+            return;
+        initialized.current = true;
+        (0, index_1.init)({
+            siteId,
+            token,
+            endpoint,
+            features,
+            autoTrack,
+            consent,
+            debug,
+        });
+    }, [siteId, token, endpoint, features, autoTrack, consent, debug]);
+    // Auto-identify when userId is provided
+    (0, react_1.useEffect)(() => {
+        if (!userId || identified.current)
+            return;
+        const tryIdentify = () => {
+            const g = (0, index_1.getInstance)();
+            if (g) {
+                g.identify(userId, userEmail ? { email: userEmail } : undefined);
+                identified.current = true;
+                return true;
+            }
+            return false;
+        };
+        if (tryIdentify())
+            return;
+        // Poll until tracker loads
+        let attempts = 0;
+        const interval = setInterval(() => {
+            attempts++;
+            if (tryIdentify() || attempts >= 20)
+                clearInterval(interval);
+        }, 100);
+        return () => clearInterval(interval);
+    }, [userId, userEmail]);
+    return null;
+}
+/**
+ * Hook to get the Gurulu tracker instance.
+ * Returns null until the tracker script has loaded.
+ */
+function useGurulu() {
+    return (0, index_1.getInstance)();
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@gurulu/web",
+  "version": "0.1.0",
+  "description": "Gurulu Web SDK — zero-config analytics, error tracking, and session replay",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "require": "./dist/react.js",
+      "types": "./dist/react.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true }
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "license": "MIT",
+  "keywords": ["analytics", "tracking", "error-tracking", "session-replay", "gurulu"]
+}