@supernal/interface 1.0.13 → 1.1.0

package/dist/esm/src/tracking/hooks.js

@@ -0,0 +1,215 @@
+/**
+ * SI Tracking React Hooks
+ *
+ * React hooks for integrating Supernal Interface tracking into components.
+ *
+ * @packageDocumentation
+ */
+'use client';
+import { useCallback, useEffect, useRef, useContext, createContext } from 'react';
+// Context for providing tracker instance
+const SITrackerContext = createContext(null);
+export const SITrackerProvider = SITrackerContext.Provider;
+/**
+ * Get the tracker instance from context
+ */
+export function useTracker() {
+    return useContext(SITrackerContext);
+}
+/**
+ * Hook to sync auth state with tracker
+ * Place this once in your app layout
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { user } = useAuth();
+ *   useSITrackingInit(tracker, user?.id);
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+export function useSITrackingInit(tracker, userId) {
+    useEffect(() => {
+        if (tracker) {
+            tracker.setUserId(userId ?? null);
+        }
+    }, [tracker, userId]);
+}
+/**
+ * Hook for tracking click events
+ *
+ * @example
+ * ```tsx
+ * const trackClick = useTrackClick(tracker, 'PostCard');
+ * <button onClick={() => trackClick('like', postId)}>Like</button>
+ * ```
+ */
+export function useTrackClick(tracker, componentId) {
+    return useCallback((action, targetId, metadata) => {
+        if (tracker) {
+            tracker.trackClick(componentId, action, targetId, metadata);
+        }
+    }, [tracker, componentId]);
+}
+/**
+ * Hook for tracking component views (impressions)
+ * Automatically tracks when component mounts
+ *
+ * @example
+ * ```tsx
+ * useTrackView(tracker, 'PostCard', post.id);
+ * ```
+ */
+export function useTrackView(tracker, componentId, targetId, options) {
+    const { trackOnMount = true } = options ?? {};
+    useEffect(() => {
+        if (tracker && trackOnMount) {
+            tracker.trackView(componentId, targetId);
+        }
+    }, [tracker, componentId, targetId, trackOnMount]);
+}
+/**
+ * Hook for tracking engagement time on a specific target
+ * Automatically handles start/end of engagement session
+ *
+ * @example
+ * ```tsx
+ * const { recordInteraction } = useTrackEngagement(tracker, post.id);
+ * <button onClick={recordInteraction}>Interact</button>
+ * ```
+ */
+export function useTrackEngagement(tracker, targetId, componentId = 'Content') {
+    const engagementStarted = useRef(false);
+    useEffect(() => {
+        if (!tracker || !targetId)
+            return;
+        // Start engagement tracking
+        tracker.startEngagement(targetId);
+        engagementStarted.current = true;
+        return () => {
+            // End engagement tracking on unmount
+            if (engagementStarted.current && tracker) {
+                tracker.endEngagement(targetId, componentId);
+                engagementStarted.current = false;
+            }
+        };
+    }, [tracker, targetId, componentId]);
+    const recordInteraction = useCallback(() => {
+        if (tracker) {
+            tracker.recordEngagementInteraction(targetId);
+        }
+    }, [tracker, targetId]);
+    return { recordInteraction };
+}
+/**
+ * Hook for tracking scroll depth in feed
+ * Attach to a scrollable container
+ *
+ * @example
+ * ```tsx
+ * const { handleScroll, resetScroll } = useTrackScrollDepth(tracker);
+ * <div onScroll={handleScroll}>...</div>
+ * ```
+ */
+export function useTrackScrollDepth(tracker, componentId = 'Feed') {
+    const handleScroll = useCallback((event) => {
+        if (!tracker)
+            return;
+        const target = event.currentTarget;
+        const scrollHeight = target.scrollHeight - target.clientHeight;
+        if (scrollHeight <= 0)
+            return;
+        const scrollPercent = Math.round((target.scrollTop / scrollHeight) * 100);
+        tracker.trackScrollDepth(scrollPercent, componentId);
+    }, [tracker, componentId]);
+    const resetScroll = useCallback(() => {
+        if (tracker) {
+            tracker.resetScrollTracking();
+        }
+    }, [tracker]);
+    // Reset on mount
+    useEffect(() => {
+        if (tracker) {
+            tracker.resetScrollTracking();
+        }
+    }, [tracker]);
+    return { handleScroll, resetScroll };
+}
+/**
+ * Hook for tracking intersection observer visibility
+ * Useful for tracking when components come into view in feed
+ *
+ * @example
+ * ```tsx
+ * const ref = useTrackVisibility(tracker, 'PostCard', post.id);
+ * <div ref={ref}>...</div>
+ * ```
+ */
+export function useTrackVisibility(tracker, componentId, targetId, options) {
+    const { threshold = 0.5 } = options ?? {};
+    const hasTracked = useRef(false);
+    const observerRef = useRef(null);
+    const refCallback = useCallback((element) => {
+        // Cleanup previous observer
+        if (observerRef.current) {
+            observerRef.current.disconnect();
+            observerRef.current = null;
+        }
+        if (!element || !tracker)
+            return;
+        // Create new observer
+        observerRef.current = new IntersectionObserver((entries) => {
+            entries.forEach((entry) => {
+                if (entry.isIntersecting && !hasTracked.current) {
+                    tracker.trackView(componentId, targetId);
+                    hasTracked.current = true;
+                }
+            });
+        }, { threshold });
+        observerRef.current.observe(element);
+    }, [tracker, componentId, targetId, threshold]);
+    // Reset tracking flag when targetId changes
+    useEffect(() => {
+        hasTracked.current = false;
+    }, [targetId]);
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => {
+            if (observerRef.current) {
+                observerRef.current.disconnect();
+            }
+        };
+    }, []);
+    return refCallback;
+}
+/**
+ * Create a component-specific tracking hook factory
+ *
+ * @example
+ * ```typescript
+ * // Define your actions
+ * type PostActions = 'like' | 'unlike' | 'share' | 'bookmark';
+ *
+ * // Create hooks for PostCard
+ * export function usePostCardTracking(tracker: SITracker<PostActions>, postId: string) {
+ *   const trackClick = useTrackClick(tracker, 'PostCard');
+ *   const visibilityRef = useTrackVisibility(tracker, 'PostCard', postId);
+ *
+ *   return {
+ *     trackLike: () => trackClick('like', postId),
+ *     trackShare: () => trackClick('share', postId),
+ *     visibilityRef,
+ *   };
+ * }
+ * ```
+ */
+export function createComponentTrackingHook(componentId, factory) {
+    return function useComponentTracking(tracker, targetId) {
+        const trackClick = useTrackClick(tracker, componentId);
+        if (!tracker)
+            return null;
+        return factory(trackClick, tracker, targetId);
+    };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/esm/src/tracking/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../../../src/tracking/hooks.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/tracking/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Supernal Interface Tracking Module
+ *
+ * Analytics and interaction tracking for SI-enabled applications.
+ * Automatically batches events, handles offline scenarios, and provides
+ * React hooks for easy integration.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * // Create a tracker
+ * import { createTracker, TrackingProvider, useTrackClick } from '@supernal/interface/tracking';
+ *
+ * const tracker = createTracker({
+ *   endpoint: '/api/v1/analytics',
+ *   batchSize: 10,
+ *   debug: process.env.NODE_ENV === 'development',
+ * });
+ *
+ * // Provide to React tree
+ * function App() {
+ *   const { user } = useAuth();
+ *   return (
+ *     <TrackingProvider tracker={tracker} userId={user?.id}>
+ *       <YourApp />
+ *     </TrackingProvider>
+ *   );
+ * }
+ *
+ * // Use in components
+ * function PostCard({ post }) {
+ *   const tracker = useTracker();
+ *   const trackClick = useTrackClick(tracker, 'PostCard');
+ *   const visibilityRef = useTrackVisibility(tracker, 'PostCard', post.id);
+ *
+ *   return (
+ *     <div ref={visibilityRef}>
+ *       <button onClick={() => trackClick('like', post.id)}>Like</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export { SITracker, createTracker, type SITrackerConfig, type SIInteraction, type SIBaseAction, } from './tracker';
+export { SITrackerProvider, useTracker, useSITrackingInit, useTrackClick, useTrackView, useTrackEngagement, useTrackScrollDepth, useTrackVisibility, createComponentTrackingHook, } from './hooks';
+export { TrackingProvider, withTracking, type SITrackingProviderProps } from './SITrackingProvider';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/src/tracking/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/tracking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,EACL,SAAS,EACT,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,2BAA2B,GAC5B,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,KAAK,uBAAuB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/esm/src/tracking/index.js

@@ -0,0 +1,51 @@
+/**
+ * Supernal Interface Tracking Module
+ *
+ * Analytics and interaction tracking for SI-enabled applications.
+ * Automatically batches events, handles offline scenarios, and provides
+ * React hooks for easy integration.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * // Create a tracker
+ * import { createTracker, TrackingProvider, useTrackClick } from '@supernal/interface/tracking';
+ *
+ * const tracker = createTracker({
+ *   endpoint: '/api/v1/analytics',
+ *   batchSize: 10,
+ *   debug: process.env.NODE_ENV === 'development',
+ * });
+ *
+ * // Provide to React tree
+ * function App() {
+ *   const { user } = useAuth();
+ *   return (
+ *     <TrackingProvider tracker={tracker} userId={user?.id}>
+ *       <YourApp />
+ *     </TrackingProvider>
+ *   );
+ * }
+ *
+ * // Use in components
+ * function PostCard({ post }) {
+ *   const tracker = useTracker();
+ *   const trackClick = useTrackClick(tracker, 'PostCard');
+ *   const visibilityRef = useTrackVisibility(tracker, 'PostCard', post.id);
+ *
+ *   return (
+ *     <div ref={visibilityRef}>
+ *       <button onClick={() => trackClick('like', post.id)}>Like</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+// Core tracker
+export { SITracker, createTracker, } from './tracker.js';
+// React hooks
+export { SITrackerProvider, useTracker, useSITrackingInit, useTrackClick, useTrackView, useTrackEngagement, useTrackScrollDepth, useTrackVisibility, createComponentTrackingHook, } from './hooks.js';
+// React provider component
+export { TrackingProvider, withTracking } from './SITrackingProvider.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/src/tracking/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/tracking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,eAAe;AACf,OAAO,EACL,SAAS,EACT,aAAa,GAId,MAAM,WAAW,CAAC;AAEnB,cAAc;AACd,OAAO,EACL,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,2BAA2B,GAC5B,MAAM,SAAS,CAAC;AAEjB,2BAA2B;AAC3B,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAgC,MAAM,sBAAsB,CAAC"}

package/dist/esm/src/tracking/tracker.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Supernal Interface Interaction Tracking
+ *
+ * Tracks user interactions with SI components for analytics and AI analysis.
+ * Batches events to minimize network requests and handles offline gracefully.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Base action types for tracking
+ * Apps can extend these with custom actions via generics
+ */
+export type SIBaseAction = 'view' | 'click' | 'expand' | 'collapse' | 'copy' | 'share' | 'like' | 'unlike' | 'bookmark' | 'unbookmark' | 'submit' | 'helpful' | 'challenge' | 'navigate' | 'scroll' | 'refresh' | 'search';
+/**
+ * Interaction event structure
+ */
+export interface SIInteraction<TAction extends string = SIBaseAction> {
+    /** Component that triggered the event */
+    componentId: string;
+    /** Action performed */
+    action: TAction;
+    /** Target entity ID (post, user, etc.) */
+    targetId?: string;
+    /** Additional event metadata */
+    metadata?: Record<string, unknown>;
+    /** Client-side timestamp */
+    timestamp: number;
+    /** Session identifier */
+    sessionId: string;
+}
+/**
+ * Tracker configuration options
+ */
+export interface SITrackerConfig {
+    /** API endpoint for logging events (default: '/api/v1/analytics') */
+    endpoint?: string;
+    /** Maximum events before auto-flush (default: 10) */
+    batchSize?: number;
+    /** Milliseconds between auto-flushes (default: 5000) */
+    flushIntervalMs?: number;
+    /** Minimum engagement time to track (default: 3000) */
+    minEngagementMs?: number;
+    /** Scroll depth debounce (default: 500) */
+    scrollDebounceMs?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Custom fetch implementation for testing */
+    customFetch?: typeof fetch;
+}
+/**
+ * SI Tracker - Core tracking class
+ *
+ * @example
+ * ```typescript
+ * const tracker = new SITracker({ endpoint: '/api/analytics' });
+ * tracker.track('PostCard', 'view', 'post-123');
+ * ```
+ */
+export declare class SITracker<TAction extends string = SIBaseAction> {
+    private queue;
+    private sessionId;
+    private flushInterval;
+    private engagementSessions;
+    private scrollState;
+    private isClient;
+    private userId;
+    private config;
+    constructor(config?: SITrackerConfig);
+    /** Generate a unique session ID */
+    private generateSessionId;
+    /** Log debug message */
+    private log;
+    /** Set the current user ID for tracking */
+    setUserId(userId: string | null): void;
+    /** Get current session ID */
+    getSessionId(): string;
+    /** Get queue length (for testing) */
+    getQueueLength(): number;
+    /**
+     * Track an interaction
+     */
+    track(componentId: string, action: TAction, targetId?: string, metadata?: Record<string, unknown>): void;
+    /** Alias for track - for click events */
+    trackClick(componentId: string, action: TAction, targetId?: string, metadata?: Record<string, unknown>): void;
+    /** Track view (impression) of a component */
+    trackView(componentId: string, targetId?: string): void;
+    /** Start engagement tracking for a target */
+    startEngagement(targetId: string): void;
+    /** Record an interaction during engagement */
+    recordEngagementInteraction(targetId: string): void;
+    /** Update scroll depth for engagement session */
+    updateEngagementScrollDepth(targetId: string, depth: number): void;
+    /** End engagement tracking and log the session */
+    endEngagement(targetId: string, componentId?: string): void;
+    /** Track scroll depth in feed */
+    trackScrollDepth(depth: number, componentId?: string): void;
+    /** Reset scroll tracking (e.g., on page navigation) */
+    resetScrollTracking(): void;
+    /** Start periodic flush interval */
+    private startFlushInterval;
+    /** Stop flush interval */
+    private stopFlushInterval;
+    /** Setup beforeunload handler to flush remaining events */
+    private setupBeforeUnload;
+    /** Flush queued events to the API */
+    flush(): Promise<void>;
+    /** Flush using sendBeacon (for unload events) */
+    private flushWithBeacon;
+    /** Cleanup (for testing or unmounting) */
+    destroy(): void;
+}
+/**
+ * Create a singleton tracker instance
+ *
+ * @example
+ * ```typescript
+ * export const tracker = createTracker({ endpoint: '/api/analytics' });
+ * ```
+ */
+export declare function createTracker<TAction extends string = SIBaseAction>(config?: SITrackerConfig): SITracker<TAction>;
+//# sourceMappingURL=tracker.d.ts.map

package/dist/esm/src/tracking/tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../../../src/tracking/tracker.ts"],"names":[],"mappings":"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"}