@bluenath/engage 1.0.0 → 1.0.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bluenath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @bluenath/engage
+
+The intelligent, zero-configuration analytics SDK for modern React applications. @bluenath/engage automatically captures clicks, form submissions, and page views, using heuristic intelligence to classify user intent (Commerce, Frustration, Engagement) without manual tagging.
+
+## ✨ Features
+
+- 🧠 **Auto-Capture Intelligence**: Automatically detects `ADD_TO_CART`, `CHECKOUT`, `REFUND`, and more by analyzing button text and DOM attributes.
+- 😡 **Rage Click Detection**: Detects user frustration (rapid clicking) automatically.
+- ⚡️ **Performance Monitoring**: Tracks Core Web Vitals (LCP, TTFB, Load Time) out of the box.
+- 🔌 **Offline Support**: Queues events in LocalStorage when offline and syncs when connectivity returns.
+- 🛡️ **PII Protection**: Automatically ignores password and credit card fields.
+- ⚛️ **First-Class React Support**: Drop-in Provider component.
+
+## 🚀 Installation
+
+```bash
+npm install @bluenath/engage
+```
+
+or
+
+```bash
+yarn add @bluenath/engage
+```
+
+## 🛠️ Usage
+
+### 1. Wrap your App
+
+Wrap your root component with `EngageProProvider`. This single step enables auto-capture for the entire application.
+
+```jsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { EngageProProvider } from "@bluenath/engage";
+import App from "./App";
+
+const root = ReactDOM.createRoot(document.getElementById("root"));
+
+root.render(
+  <EngageProProvider
+    writeKey="YOUR_WRITE_KEY"
+    apiHost="https://your-api.com/analyticsdk/ingest"
+    tracking={{
+      autoTrack: true, // 🧠 Enable Smart Sentinel
+      useCookies: true, // Persist session across subdomains
+      fingerprint: true, // Device fingerprinting for guest users
+    }}
+  >
+    <App />
+  </EngageProProvider>,
+);
+```
+
+### 2. Manual Tracking (Optional)
+
+While auto-capture handles 90% of events, you can manually track specific actions using the hook.
+
+```jsx
+import { useAnalytics } from "@bluenath/engage";
+
+const ProductPage = () => {
+  const { track, identify } = useAnalytics();
+
+  const handleLogin = (user) => {
+    // Stitch session to user ID
+    identify(user.id, {
+      email: user.email,
+      plan: "premium",
+    });
+  };
+
+  const handleCustomAction = () => {
+    track("Video Watched", {
+      duration: 120,
+      category: "Tutorial",
+    });
+  };
+
+  return <button onClick={handleCustomAction}>Play Video</button>;
+};
+```
+
+## 🧠 Smart Events (Auto-Detected)
+
+The SDK automatically maps user interactions to these standard events based on heuristics:
+
+| Event Name          | Trigger Logic (Example)                            |
+| ------------------- | -------------------------------------------------- |
+| `ADD_TO_CART`       | Clicks on buttons labeled "Add to Cart", "Buy Now" |
+| `INITIATE_CHECKOUT` | Clicks on "Checkout", "Proceed"                    |
+| `PURCHASE`          | Clicks on "Place Order", "Pay Now"                 |
+| `ORDER_CANCEL`      | Clicks on "Cancel Order"                           |
+| `RAGE_CLICK`        | 3+ rapid clicks on the same element (< 500ms)      |
+| `FORM_START`        | User focuses on an input field                     |
+| `PERFORMANCE`       | Page Load metrics (TTFB, Load Time)                |
+
+## 🔒 Configuration Options
+
+| Prop                  | Type      | Default  | Description                               |
+| --------------------- | --------- | -------- | ----------------------------------------- |
+| `writeKey`            | `string`  | Required | Your project's API Key.                   |
+| `apiHost`             | `string`  | `...`    | The endpoint where events are sent.       |
+| `tracking.autoTrack`  | `boolean` | `true`   | Enables/Disables DOM listening.           |
+| `tracking.useCookies` | `boolean` | `false`  | Use cookies for cross-subdomain tracking. |
+| `debug`               | `boolean` | `false`  | Log events to console for debugging.      |
+
+## 📄 License
+
+MIT © Bluenath

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluenath/engage",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",