screen-flow 1.0.0

package/README.md

@@ -0,0 +1,126 @@
+# screen-flow 🧭
+
+> **Navigation intelligence, not just analytics.** One-stop, platform-agnostic tracker for React and React Native.
+
+[![license](https://img.shields.io/badge/license-ISC-blue.svg)](https://github.com/your-username/screen-flow/blob/main/LICENSE)
+[![size](https://img.shields.io/bundlephobia/minzip/screen-flow)](https://bundlephobia.com/package/screen-flow)
+[![tests](https://img.shields.io/badge/tests-90%25%2B-brightgreen)](https://github.com/your-username/screen-flow)
+
+---
+
+## 🚀 Why ScreenFlow?
+
+In a world of bloated analytics SDKs (Segment, Firebase, Mixpanel), **ScreenFlow** is the minimalist's choice.
+
+- **⚡ Zero Bloat:** Only a few KB. Won't slow down your app or increase your bundle size like 2MB+ commercial SDKs.
+- **🛡️ Privacy First:** No data ever leaves the device unless *you* want it to. Total control over your user's privacy.
+- **📱 True Cross-Platform:** Write once, track everywhere. Same API for Web and React Native with automatic lifecycle detection.
+- **🧠 More than Counters:** Automatically tracks **duration**, maintains **history**, and detects **back-navigation** using smart algorithms.
+- **💾 Persistence Ready:** Unlike other lightweight trackers, ScreenFlow can persist data across app restarts.
+- **🧪 100% Transparent:** Open-source and fully covered by unit tests. No "black-box" tracking.
+
+---
+
+## ✨ Features
+
+- 🔄 **Flow Tracking**: Keeps track of the last 30 screens visited.
+- ⏱️ **Time Awareness**: Automatically tracks time spent on each screen.
+- 🔙 **Smart Back Detection**: Detects back navigation even across multiple screens.
+- ⏸️ **Smart Pausing**: Pauses timers when the app is in background.
+- ⚛️ **React Ready**: Comes with first-class hooks like `useScreenFlow`.
+- 🔌 **Adapter Pattern**: Send data to Console, Firestore, Segment, or your own API.
+
+---
+
+## 🚀 Installation
+
+```bash
+npm install screen-flow
+```
+
+---
+
+## ⚙️ Quick Start
+
+### 1. Initialize (Optional but recommended)
+
+Setup your storage and output adapter.
+
+```typescript
+import { initScreenFlow, ConsoleAdapter } from 'screen-flow';
+
+initScreenFlow({
+  adapter: new ConsoleAdapter(),
+  // Persistence for Web (localStorage) or React Native (AsyncStorage)
+  storage: localStorage, 
+  sessionTimeout: 30 * 60 * 1000 // 30 mins
+});
+```
+
+### 2. Track Screens
+
+#### ⚛️ Functional Components (React)
+
+```tsx
+import { useScreenFlow } from 'screen-flow';
+
+const Dashboard = () => {
+  useScreenFlow('Dashboard', { tab: 'overview' });
+  return <div>My Dashboard</div>;
+};
+```
+
+#### 🖱️ Manual Tracking
+
+```typescript
+import { onScreenChange } from 'screen-flow';
+
+// Anywhere in your logic
+await onScreenChange('Settings');
+```
+
+---
+
+## 🔌 Customizing Output (Adapters)
+
+Connect ScreenFlow to any service in seconds.
+
+```typescript
+import { Adapter, ScreenEvent } from 'screen-flow';
+
+class MyBrandAdapter implements Adapter {
+  onEvent(event: ScreenEvent) {
+    console.log(`User stayed on ${event.previousScreen} for ${event.duration}ms`);
+    // Send to your own server
+    myApi.log(event);
+  }
+}
+```
+
+---
+
+## 📄 Screen Event Data Structure
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `screen` | `string` | Current screen name |
+| `previousScreen` | `string \| null` | Name of the last screen |
+| `duration` | `number` | Time spent on the last screen (ms) |
+| `flow` | `string[]` | Last 30 screens visited |
+| `isBack` | `boolean` | True if this move was a "Back" navigation |
+| `sessionId` | `string` | Unique, persistent session ID |
+| `params` | `object` | Custom metadata provided by you |
+
+---
+
+## 💖 Support
+
+If ScreenFlow saved you hours of work or helped you build a faster app, consider supporting the development!
+
+<a href="https://www.buymeacoffee.com/yourusername" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
+
+---
+
+## 🛡️ License
+
+ISC (Free and Open Source)

package/dist/adapters/console.d.ts

@@ -0,0 +1,7 @@
+import { Adapter, ScreenEvent } from '../types';
+/**
+ * Default adapter that logs screen events to the console.
+ */
+export declare class ConsoleAdapter implements Adapter {
+    onEvent(event: ScreenEvent): void;
+}

package/dist/adapters/console.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleAdapter = void 0;
+/**
+ * Default adapter that logs screen events to the console.
+ */
+class ConsoleAdapter {
+    onEvent(event) {
+        const { screen, duration, isBack, timestamp } = event;
+        const date = new Date(timestamp).toLocaleTimeString();
+        console.log(`[ScreenFlow] ${date} - ${screen} (${duration}ms)${isBack ? ' [BACK]' : ''}`, event);
+    }
+}
+exports.ConsoleAdapter = ConsoleAdapter;

package/dist/core/flow.d.ts

@@ -0,0 +1,17 @@
+import { StorageProvider } from '../types';
+/**
+ * Manages the navigation history stack.
+ * Keeps track of the last 30 screens and detects back navigation.
+ */
+export declare class FlowManager {
+    private history;
+    private storage?;
+    private readonly MAX_HISTORY;
+    private readonly STORAGE_KEY;
+    constructor(storage?: StorageProvider);
+    private init;
+    push(screenName: string): Promise<boolean>;
+    getHistory(): string[];
+    getPreviousScreen(): string | null;
+    private isBackNavigation;
+}

package/dist/core/flow.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowManager = void 0;
+/**
+ * Manages the navigation history stack.
+ * Keeps track of the last 30 screens and detects back navigation.
+ */
+class FlowManager {
+    constructor(storage) {
+        this.history = [];
+        this.MAX_HISTORY = 30;
+        this.STORAGE_KEY = 'sf_history';
+        this.storage = storage;
+        this.init();
+    }
+    async init() {
+        if (this.storage) {
+            const storedHistory = await this.storage.getItem(this.STORAGE_KEY);
+            if (storedHistory) {
+                try {
+                    this.history = JSON.parse(storedHistory);
+                }
+                catch (e) {
+                    this.history = [];
+                }
+            }
+        }
+    }
+    async push(screenName) {
+        const isBack = this.isBackNavigation(screenName);
+        this.history.push(screenName);
+        if (this.history.length > this.MAX_HISTORY) {
+            this.history.shift();
+        }
+        if (this.storage) {
+            await this.storage.setItem(this.STORAGE_KEY, JSON.stringify(this.history));
+        }
+        return isBack;
+    }
+    getHistory() {
+        return [...this.history];
+    }
+    getPreviousScreen() {
+        if (this.history.length < 2)
+            return null;
+        return this.history[this.history.length - 2];
+    }
+    isBackNavigation(screenName) {
+        if (this.history.length < 2)
+            return false;
+        // Smarter back detection: if the screen exists in the recent history
+        // (last 5 screens excluding the current one)
+        const recentHistory = this.history.slice(-6, -1);
+        return recentHistory.includes(screenName);
+    }
+}
+exports.FlowManager = FlowManager;

package/dist/core/session.d.ts

@@ -0,0 +1,16 @@
+import { StorageProvider } from '../types';
+/**
+ * Handles session identification.
+ * Generates a unique ID per session, persisted across restarts.
+ */
+export declare class SessionManager {
+    private sessionId;
+    private storage?;
+    private readonly STORAGE_KEY;
+    private readonly LAST_ACTIVITY_KEY;
+    private readonly sessionTimeout;
+    constructor(storage?: StorageProvider, sessionTimeout?: number);
+    getSessionId(): Promise<string>;
+    private updateActivity;
+    private generateId;
+}

package/dist/core/session.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionManager = void 0;
+/**
+ * Handles session identification.
+ * Generates a unique ID per session, persisted across restarts.
+ */
+class SessionManager {
+    constructor(storage, sessionTimeout = 30 * 60 * 1000) {
+        this.sessionId = null;
+        this.STORAGE_KEY = 'sf_session_id';
+        this.LAST_ACTIVITY_KEY = 'sf_last_activity';
+        this.storage = storage;
+        this.sessionTimeout = sessionTimeout;
+    }
+    async getSessionId() {
+        if (this.sessionId) {
+            await this.updateActivity();
+            return this.sessionId;
+        }
+        if (this.storage) {
+            const storedId = await this.storage.getItem(this.STORAGE_KEY);
+            const lastActivity = await this.storage.getItem(this.LAST_ACTIVITY_KEY);
+            if (storedId && lastActivity) {
+                const elapsed = Date.now() - parseInt(lastActivity, 10);
+                if (elapsed < this.sessionTimeout) {
+                    this.sessionId = storedId;
+                    await this.updateActivity();
+                    return this.sessionId;
+                }
+            }
+        }
+        // New session
+        this.sessionId = this.generateId();
+        if (this.storage) {
+            await this.storage.setItem(this.STORAGE_KEY, this.sessionId);
+            await this.updateActivity();
+        }
+        return this.sessionId;
+    }
+    async updateActivity() {
+        if (this.storage) {
+            await this.storage.setItem(this.LAST_ACTIVITY_KEY, Date.now().toString());
+        }
+    }
+    generateId() {
+        return Math.random().toString(36).substring(2, 11) + Date.now().toString(36);
+    }
+}
+exports.SessionManager = SessionManager;

package/dist/core/timer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Handles duration tracking for screens.
+ * Automatically pauses when app is backgrounded.
+ */
+export declare class ScreenTimer {
+    private startTime;
+    private pausedTime;
+    private isPaused;
+    private lastPauseStart;
+    constructor();
+    start(): void;
+    pause(): void;
+    resume(): void;
+    getDuration(): number;
+    reset(): number;
+}

package/dist/core/timer.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScreenTimer = void 0;
+/**
+ * Handles duration tracking for screens.
+ * Automatically pauses when app is backgrounded.
+ */
+class ScreenTimer {
+    constructor() {
+        this.startTime = 0;
+        this.pausedTime = 0;
+        this.isPaused = false;
+        this.lastPauseStart = 0;
+        this.start();
+    }
+    start() {
+        this.startTime = Date.now();
+        this.pausedTime = 0;
+        this.isPaused = false;
+    }
+    pause() {
+        if (!this.isPaused) {
+            this.lastPauseStart = Date.now();
+            this.isPaused = true;
+        }
+    }
+    resume() {
+        if (this.isPaused) {
+            this.pausedTime += Date.now() - this.lastPauseStart;
+            this.isPaused = false;
+        }
+    }
+    getDuration() {
+        if (this.startTime === 0)
+            return 0;
+        const currentDuration = Date.now() - this.startTime - this.pausedTime;
+        // If currently paused, don't count the time since pause started
+        if (this.isPaused) {
+            return currentDuration - (Date.now() - this.lastPauseStart);
+        }
+        return currentDuration;
+    }
+    reset() {
+        const duration = this.getDuration();
+        this.start();
+        return duration;
+    }
+}
+exports.ScreenTimer = ScreenTimer;

package/dist/core/tracker.d.ts

@@ -0,0 +1,32 @@
+import { TrackerOptions } from '../types';
+/**
+ * Main coordinator for screen tracking.
+ * Manages timer, flow, and session across the application lifecycle.
+ */
+export declare class ScreenTracker {
+    private timer;
+    private flow;
+    private session;
+    private adapter;
+    private currentScreen;
+    constructor(options?: TrackerOptions);
+    /**
+     * Tracks a screen change.
+     * @param screenName The name of the screen being navigated to.
+     * @param params Optional parameters associated with the screen change.
+     */
+    track(screenName: string, params?: Record<string, any>): Promise<void>;
+    /**
+     * Returns the current session ID.
+     */
+    getSessionId(): Promise<string>;
+    /**
+     * Returns the navigation history.
+     */
+    getHistory(): string[];
+    /**
+     * Clears the tracker state (useful for tests).
+     */
+    clearInstance(): void;
+}
+export declare const tracker: ScreenTracker;

package/dist/core/tracker.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tracker = exports.ScreenTracker = void 0;
+const timer_1 = require("./timer");
+const flow_1 = require("./flow");
+const session_1 = require("./session");
+const appState_1 = require("../lifecycle/appState");
+const console_1 = require("../adapters/console");
+/**
+ * Main coordinator for screen tracking.
+ * Manages timer, flow, and session across the application lifecycle.
+ */
+class ScreenTracker {
+    constructor(options = {}) {
+        this.currentScreen = null;
+        this.timer = new timer_1.ScreenTimer();
+        this.flow = new flow_1.FlowManager(options.storage);
+        this.session = new session_1.SessionManager(options.storage, options.sessionTimeout);
+        this.adapter = options.adapter || new console_1.ConsoleAdapter();
+        // Setup platform-agnostic lifecycle listener
+        new appState_1.AppStateListener((status) => {
+            if (status === 'background') {
+                this.timer.pause();
+            }
+            else {
+                this.timer.resume();
+            }
+        });
+    }
+    /**
+     * Tracks a screen change.
+     * @param screenName The name of the screen being navigated to.
+     * @param params Optional parameters associated with the screen change.
+     */
+    async track(screenName, params) {
+        if (this.currentScreen === screenName)
+            return;
+        const previousScreen = this.currentScreen;
+        this.currentScreen = screenName;
+        // Reset timer and get duration spent on the previous screen
+        const duration = this.timer.reset();
+        // Update flow and detect if this is a back navigation
+        const isBack = await this.flow.push(screenName);
+        // Prepare the event
+        const event = {
+            screen: screenName,
+            previousScreen,
+            duration,
+            flow: this.flow.getHistory(),
+            isBack,
+            sessionId: await this.session.getSessionId(),
+            timestamp: Date.now(),
+            params
+        };
+        // Dispatch event to the adapter
+        this.adapter.onEvent(event);
+    }
+    /**
+     * Returns the current session ID.
+     */
+    async getSessionId() {
+        return await this.session.getSessionId();
+    }
+    /**
+     * Returns the navigation history.
+     */
+    getHistory() {
+        return this.flow.getHistory();
+    }
+    /**
+     * Clears the tracker state (useful for tests).
+     */
+    clearInstance() {
+        this.currentScreen = null;
+        this.timer.start();
+        this.flow = new flow_1.FlowManager(this.storage);
+        this.session = new session_1.SessionManager(this.storage);
+    }
+}
+exports.ScreenTracker = ScreenTracker;
+// Export a singleton instance for easier usage
+exports.tracker = new ScreenTracker();

package/dist/hooks.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Hook to automatically track screen changes in React components.
+ *
+ * @param screenName The name of the screen to track.
+ * @param params Optional parameters for the screen.
+ */
+export declare function useScreenFlow(screenName: string, params?: Record<string, any>): void;

package/dist/hooks.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useScreenFlow = useScreenFlow;
+const react_1 = require("react");
+const index_1 = require("./index");
+/**
+ * Hook to automatically track screen changes in React components.
+ *
+ * @param screenName The name of the screen to track.
+ * @param params Optional parameters for the screen.
+ */
+function useScreenFlow(screenName, params) {
+    const isFirstRender = (0, react_1.useRef)(true);
+    (0, react_1.useEffect)(() => {
+        // Track on mount or whenever screenName/params change
+        (0, index_1.onScreenChange)(screenName, params);
+        isFirstRender.current = false;
+    }, [screenName, JSON.stringify(params)]);
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export * from './types';
+export { ScreenTracker, tracker } from './core/tracker';
+export { ConsoleAdapter } from './adapters/console';
+import { tracker } from './core/tracker';
+import { TrackerOptions } from './types';
+/**
+ * Initializes the ScreenTracker with custom options (adapter, storage).
+ */
+export declare const initScreenFlow: (options: TrackerOptions) => void;
+/**
+ * Tracks a screen change.
+ */
+export declare const onScreenChange: (screenName: string, params?: Record<string, any>) => Promise<void>;
+export * from './hooks';
+/**
+ * Main API for screen tracking.
+ * @example
+ * import screenFlow from 'screen-flow';
+ * await screenFlow.track('Home');
+ */
+export default tracker;

package/dist/index.js

@@ -0,0 +1,54 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.onScreenChange = exports.initScreenFlow = exports.ConsoleAdapter = exports.tracker = exports.ScreenTracker = void 0;
+__exportStar(require("./types"), exports);
+var tracker_1 = require("./core/tracker");
+Object.defineProperty(exports, "ScreenTracker", { enumerable: true, get: function () { return tracker_1.ScreenTracker; } });
+Object.defineProperty(exports, "tracker", { enumerable: true, get: function () { return tracker_1.tracker; } });
+var console_1 = require("./adapters/console");
+Object.defineProperty(exports, "ConsoleAdapter", { enumerable: true, get: function () { return console_1.ConsoleAdapter; } });
+const tracker_2 = require("./core/tracker");
+/**
+ * Initializes the ScreenTracker with custom options (adapter, storage).
+ */
+const initScreenFlow = (options) => {
+    tracker_2.tracker.adapter = options.adapter || tracker_2.tracker.adapter;
+    // Update internal managers with storage/options
+    if (options.storage) {
+        tracker_2.tracker.flow['storage'] = options.storage;
+        tracker_2.tracker.session['storage'] = options.storage;
+    }
+    if (options.sessionTimeout) {
+        tracker_2.tracker.session['sessionTimeout'] = options.sessionTimeout;
+    }
+};
+exports.initScreenFlow = initScreenFlow;
+/**
+ * Tracks a screen change.
+ */
+const onScreenChange = async (screenName, params) => {
+    await tracker_2.tracker.track(screenName, params);
+};
+exports.onScreenChange = onScreenChange;
+__exportStar(require("./hooks"), exports);
+/**
+ * Main API for screen tracking.
+ * @example
+ * import screenFlow from 'screen-flow';
+ * await screenFlow.track('Home');
+ */
+exports.default = tracker_2.tracker;

package/dist/lifecycle/appState.d.ts

@@ -0,0 +1,10 @@
+import { AppStateChangeListener } from '../types';
+/**
+ * Platform-agnostic AppState listener.
+ * Automatically detects React Native vs Web.
+ */
+export declare class AppStateListener {
+    private listener;
+    constructor(listener: AppStateChangeListener);
+    private init;
+}

package/dist/lifecycle/appState.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppStateListener = void 0;
+/**
+ * Platform-agnostic AppState listener.
+ * Automatically detects React Native vs Web.
+ */
+class AppStateListener {
+    constructor(listener) {
+        this.listener = listener;
+        this.init();
+    }
+    init() {
+        // Check if we are in React Native
+        try {
+            // Use dynamic require to avoid bundling RN in web builds
+            const { AppState } = require('react-native');
+            if (AppState && AppState.addEventListener) {
+                AppState.addEventListener('change', (nextState) => {
+                    if (nextState === 'active') {
+                        this.listener('active');
+                    }
+                    else if (nextState === 'background' || nextState === 'inactive') {
+                        this.listener('background');
+                    }
+                });
+                return;
+            }
+        }
+        catch (e) {
+            // React Native not available, fallback to Web
+        }
+        // Fallback to Web (document visibility API)
+        if (typeof document !== 'undefined' && document.addEventListener) {
+            document.addEventListener('visibilitychange', () => {
+                const status = document.visibilityState === 'visible' ? 'active' : 'background';
+                this.listener(status);
+            });
+        }
+    }
+}
+exports.AppStateListener = AppStateListener;

package/dist/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Represents a single screen event in the navigation flow.
+ */
+export interface ScreenEvent {
+    screen: string;
+    previousScreen: string | null;
+    duration: number;
+    flow: string[];
+    isBack: boolean;
+    sessionId: string;
+    timestamp: number;
+    params?: Record<string, any>;
+}
+/**
+ * Interface for output adapters.
+ */
+export interface Adapter {
+    onEvent(event: ScreenEvent): void;
+}
+/**
+ * Interface for storage providers (persistence).
+ */
+export interface StorageProvider {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+/**
+ * Options for initializing the ScreenTracker.
+ */
+export interface TrackerOptions {
+    adapter?: Adapter;
+    storage?: StorageProvider;
+    sessionTimeout?: number;
+}
+/**
+ * App state types to unify React and React Native behavior.
+ */
+export type AppStateStatus = 'active' | 'background';
+export type AppStateChangeListener = (status: AppStateStatus) => void;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "screen-flow",
+  "version": "1.0.0",
+  "description": "Navigation intelligence library for React and React Native",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "keywords": [
+    "react",
+    "react-native",
+    "navigation",
+    "analytics",
+    "flow",
+    "screen-tracking"
+  ],
+  "author": "Mansi Kansagara (https://github.com/Mansikansagara9)",
+  "license": "ISC",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mansikansagara9/screen-flow.git"
+  },
+  "contributors": [
+    {
+      "name": "Kaushik Vaghasiya",
+      "email": "kaushikvaghasiya134@gmail.com",
+      "url": "https://github.com/kaushik134"
+    }
+  ],
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.2.7",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-native": ">=0.60.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    }
+  }
+}