teacupweb 2.2.1

package/Analytics/analytics.controller.js

@@ -0,0 +1,19 @@
+import clicks from './services/click.service';
+import page from './services/page.service';
+import forms from './services/forms.service';
+import save from './save';
+
+function track() {
+  // Track button clicks
+  clicks.track();
+  
+  // Track page views and scrolling
+  page.track();
+
+  // forms
+  forms.track();
+
+  // save
+  save();
+}
+export default { track };

package/Analytics/data.controller.js

@@ -0,0 +1,109 @@
+const data = {
+  button: [],
+  form: [],
+  page: [],
+};
+const prevData = {
+  button: [],
+  form: [],
+  page: [],
+};
+const clearData = () => {
+  prevData.button = [...data.button];
+  prevData.form = [...data.form];
+  prevData.page = [...data.page];
+  data.button = [];
+  data.form = [];
+  data.page = [];
+};
+
+const getNewData = () => {
+  const newData = {
+    button: [],
+    form: [],
+    page: [],
+  };
+
+  // Compare buttons - only include if not in prevData
+  data.button.forEach((btn) => {
+    const isDuplicate = prevData.button.some(
+      (prevBtn) => prevBtn.button === btn.button && prevBtn.page === btn.page
+    );
+    if (!isDuplicate) {
+      newData.button.push(btn);
+    }
+  });
+
+  // Compare pages - only include if page+percentage combo not in prevData
+  data.page.forEach((pg) => {
+    const isDuplicate = prevData.page.some(
+      (prevPg) =>
+        prevPg.page === pg.page && prevPg.percentage === pg.percentage
+    );
+    if (!isDuplicate) {
+      newData.page.push(pg);
+    }
+  });
+
+  // Compare forms - only include if form+percent combo not in prevData
+  data.form.forEach((frm) => {
+    const isDuplicate = prevData.form.some(
+      (prevFrm) =>
+        prevFrm.form === frm.form && prevFrm.percent === frm.percent
+    );
+    if (!isDuplicate) {
+      newData.form.push(frm);
+    }
+  });
+
+  return newData;
+};
+
+const setData = (type, result) => {
+  if (type === 'page') {
+    // Find existing page entry
+    const existingPageIndex = data.page.findIndex(
+      (page) => page.page === result.page
+    );
+
+    if (existingPageIndex !== -1) {
+      // Update only if new percentage is higher
+      const currentPercentage =
+        parseFloat(data.page[existingPageIndex].percentage) || 0;
+      const newPercentage = parseFloat(result.percentage) || 0;
+
+      if (newPercentage > currentPercentage) {
+        data.page[existingPageIndex].percentage = result.percentage;
+      }
+    } else {
+      // Add new entry if it doesn't exist
+      data.page.push(result);
+    }
+  } else if (type === 'form') {
+    // Find existing form entry
+    const existingFormIndex = data.form.findIndex(
+      (form) => form.form === result.form
+    );
+
+    if (existingFormIndex !== -1) {
+      // Update only if new percentage is higher
+      const currentPercent =
+        parseFloat(data.form[existingFormIndex].percent) || 0;
+      const newPercent = parseFloat(result.percent) || 0;
+
+      if (newPercent > currentPercent) {
+        data.form[existingFormIndex].percent = result.percent;
+      }
+    } else {
+      // Add new entry if it doesn't exist
+      data.form.push(result);
+    }
+  } else {
+    // For other types (like 'button'), just push without deduplication
+    data[type].push(result);
+  }
+
+  return data;
+};
+
+export default { setData, data, clearData, getNewData };

package/Analytics/identity.js

@@ -0,0 +1,25 @@
+const FINGERPRINT_KEY = 'teacup_fingerprint';
+
+export default function fingerprint() {
+  // Check if fingerprint already exists in localStorage
+  const existingFingerprint = localStorage.getItem(FINGERPRINT_KEY);
+
+  if (existingFingerprint) {
+    return existingFingerprint;
+  }
+
+  // Generate new fingerprint if not found
+  const canvas = document.createElement('canvas');
+  canvas.width = 20;
+  canvas.height = 2220;
+  const ctx = canvas.getContext('2d');
+  ctx.fillText('Hello', 10, 10);
+
+  const data = canvas.toDataURL();
+  const newFingerprint = data.slice(-32);
+
+  // Store in localStorage for future use
+  localStorage.setItem(FINGERPRINT_KEY, newFingerprint);
+
+  return newFingerprint;
+}

package/Analytics/save.js

@@ -0,0 +1,27 @@
+import fetchAPI from '../Functions/FetchAPI';
+import fingerprint from './identity';
+import data from './data.controller';
+import { initial } from '..';
+
+export default function save() {
+  setInterval(() => {
+    const newData = data.getNewData();
+    
+    // Check if there's any new data to send
+    const hasNewData =
+      newData.button.length > 0 ||
+      newData.form.length > 0 ||
+      newData.page.length > 0;
+
+    if (hasNewData) {
+      fetchAPI('api/analytics', 'POST', {
+        data: newData,
+        initial: initial,
+        fingerprint: fingerprint(),
+      });
+      
+      // Clear data after sending
+      data.clearData();
+    }
+  }, 5000);
+}

package/Analytics/services/click.service.js

@@ -0,0 +1,13 @@
+import data from './../data.controller';
+
+function track() {
+  addEventListener('click', (e) => {
+    if (e.target.tagName == 'BUTTON') {
+      data.setData('button', {
+        button: e.target.innerText,
+        page: window.location.pathname,
+      });
+    }
+  });
+}
+export default { track };

package/Analytics/services/forms.service.js

@@ -0,0 +1,30 @@
+import data from '../data.controller';
+function track() {
+  document.addEventListener('input', (e) => {
+    const form = e.target.closest('form');
+    if (!form) return;
+
+    function findHeadingBeforeForm(form) {
+      let el = form.previousElementSibling;
+      while (el) {
+        if (/H[1-3]/.test(el.tagName)) return el;
+        el = el.previousElementSibling;
+      }
+      return null;
+    }
+
+    const heading = findHeadingBeforeForm(form);
+
+    const fields = form.querySelectorAll('input, textarea, select');
+    const filled = [...fields].filter((f) => f.value.trim() !== '').length;
+
+    const percent = (filled / fields.length) * 100;
+
+    data.setData('form', {
+      form: form.dataset.formName || heading?.innerText || 'unknown-form',
+      percentage: Math.ceil(percent),
+    });
+  });
+}
+
+export default { track };

package/Analytics/services/page.service.js

@@ -0,0 +1,68 @@
+import data from '../data.controller';
+
+let currentPath = window.location.pathname;
+let topPercent = 0;
+
+function trackRoute() {
+  ['pushState', 'replaceState'].forEach((method) => {
+    const original = history[method];
+    history[method] = function () {
+      const result = original.apply(this, arguments);
+      
+      // New page navigation detected
+      const newPath = window.location.pathname;
+      if (newPath !== currentPath) {
+        // Initialize new page with 0%
+        currentPath = newPath;
+        topPercent = 0;
+        data.setData('page', {
+          page: currentPath,
+          percentage: 0,
+        });
+      }
+      
+      return result;
+    };
+  });
+}
+
+function trackPageView() {
+  document.addEventListener('scroll', () => {
+    const scrollTop = document.documentElement.scrollTop;
+    const scrollHeight = document.documentElement.scrollHeight;
+    const clientHeight = document.documentElement.clientHeight;
+
+    const percent = Math.ceil(
+      (scrollTop / (scrollHeight - clientHeight)) * 100
+    );
+    
+    // Update only if percentage increased
+    if (percent > topPercent) {
+      topPercent = percent;
+      
+      // Update the data with new percentage
+      data.setData('page', {
+        page: currentPath,
+        percentage: topPercent,
+      });
+    }
+  });
+}
+
+function track() {
+  // Initialize current page
+  data.setData('page', {
+    page: currentPath,
+    percentage: 0,
+  });
+  
+  // Set up route tracking for navigation
+  trackRoute();
+  
+  // Set up scroll tracking
+  trackPageView();
+}
+
+export default {
+  track,
+};

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## [1.1.0] - 2025-12-26
+
+### Added
+- **Duplicate Prevention System**: Analytics data is now compared with previously sent data to prevent duplicates from being stored in the database
+- **LocalStorage Fingerprint**: Visitor fingerprint now persists in localStorage across browser sessions for consistent identification
+- `getNewData()` function in data controller that filters out duplicate analytics before sending
+
+### Changed
+- Fingerprint generation now happens only once per browser and is stored in localStorage with key `teacupnet_fingerprint`
+- Analytics save function now only sends API requests when there is new data to transmit
+- Data comparison logic ensures button clicks, page views, and form interactions are only sent once
+
+### Fixed
+- Duplicate button clicks on the same page are no longer sent multiple times
+- Same page scroll percentages are no longer duplicated in database
+- Form completion percentages only update when they change
+- Reduced unnecessary API calls when no new analytics data is available
+
+### Performance
+- Reduced database writes by filtering duplicates before transmission
+- Reduced network requests by skipping empty data intervals
+- Fingerprint generation optimized to run only once per browser session
+
+## [1.0.0] - 2025-12-17
+
+### Added
+- Initial release of TeacupNet Library
+- Analytics tracking module with automatic data collection
+- Button click tracking across all pages
+- Page view and scroll depth tracking
+- Form completion percentage tracking
+- Canvas fingerprinting for unique visitor identification
+- Data controller for blog management
+- API for posting data to inboxes
+- Automatic data synchronization every 5 seconds
+- Smart deduplication for page and form analytics
+- TypeScript definitions for better IDE support
+
+### Features
+- **Analytics Module**
+  - `analytics.track()` - Start automatic tracking of user interactions
+  - Real-time button click tracking
+  - Scroll depth monitoring with percentage calculation
+  - Form field completion tracking
+  - Custom form naming via `data-form-name` or heading detection
+
+- **Data Module**
+  - `data.getBlogs()` - Retrieve all blogs for client
+  - `data.getBlog(id)` - Get specific blog by ID
+  - `data.postData(inboxId, data)` - Post data to inbox
+
+### Technical Details
+- ES modules support
+- Production-ready with Vercel backend integration
+- Browser-based fingerprinting for visitor tracking
+- Optimized data storage preventing duplicates
+- Credential validation on initialization
+
+## [Unreleased]
+
+### Planned
+- Custom event tracking
+- Configurable sync intervals
+- Offline data queue
+- Enhanced TypeScript definitions
+- Custom analytics filters
+- Dashboard integration examples

package/Controllers/data.controller.js

@@ -0,0 +1,22 @@
+import fetchAPI from '../Functions/FetchAPI';
+import { initial } from '../index.js';
+
+const getBlogs = async () => {
+  const id = initial.clientID;
+  const result = await fetchAPI(`dashboard/blogs/${id}`);
+  return result;
+};
+
+const getBlog = async (id) => {
+  const clientID = initial.clientID;
+  return await fetchAPI(`dashboard/blogs/${clientID}/${id}`);
+};
+
+const postData = async (id, data) => {
+  return await fetchAPI('api/inboxData', 'POST', {
+    inbox_id: id,
+    data: data,
+  });
+};
+
+export default { getBlogs, getBlog, postData };

package/Functions/FetchAPI.js

@@ -0,0 +1,20 @@
+export default async function fetchAPI(path, method = 'GET', body = null) {
+  const req = {
+    method: method,
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  };
+  if (method === 'GET') delete req.body;
+
+  try {
+    const data = await fetch(
+      `https://backend.teacup.website/${path}`,
+      req
+    );
+    return await data.json();
+  } catch (error) {
+    console.log(error);
+  }
+}

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 Tahmid Jihan, TeacupNet
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,331 @@
+# TeacupNet Library
+
+A powerful JavaScript library for integrating TeacupNet analytics and data management capabilities into your web applications. Track user interactions, page views, form completions, and seamlessly connect to the TeacupNet backend.
+
+## Features
+
+- 📊 **Analytics Tracking**: Automatic tracking of button clicks, page views, and form interactions
+- 🎯 **Smart Form Tracking**: Track form completion percentage in real-time
+- 📈 **Page Scroll Tracking**: Monitor how far users scroll on each page
+- 🔒 **Fingerprinting**: Unique visitor identification using canvas fingerprinting
+- 🚀 **Easy Integration**: Simple initialization and automatic data synchronization
+- 📦 **Lightweight**: Minimal dependencies, optimized for performance
+
+## Installation
+
+```bash
+npm install teacupnet-lib
+```
+
+## Quick Start
+
+### 1. Initialize the Library
+
+```javascript
+import teacupnet from 'teacupnet-lib';
+
+// Initialize with your credentials
+const client = teacupnet('YOUR_CLIENT_ID', 'YOUR_CLIENT_KEY');
+
+if (client.error) {
+  console.error(client.message);
+} else {
+  console.log('TeacupNet initialized successfully!');
+}
+```
+
+### 2. Enable Analytics Tracking
+
+```javascript
+import teacupnet from 'teacupnet-lib';
+
+const client = teacupnet('YOUR_CLIENT_ID', 'YOUR_CLIENT_KEY');
+
+// Start tracking analytics
+client.analytics.track();
+```
+
+That's it! The library will now automatically track:
+
+- Button clicks
+- Page navigation and scroll depth
+- Form completion percentages
+
+## API Reference
+
+### Initialization
+
+#### `teacupnet(clientID, clientKey)`
+
+Initializes the TeacupNet library with your credentials.
+
+**Parameters:**
+
+- `clientID` (string): Your unique client identifier
+- `clientKey` (string): Your secret client key
+
+**Returns:**
+
+- On success: Object with `analytics` and `data` controllers
+- On failure: Object with `error` and `message` properties
+
+**Example:**
+
+```javascript
+const client = teacupnet('123', 'secretKey456');
+```
+
+### Analytics Module
+
+#### `client.analytics.track()`
+
+Starts automatic tracking of user interactions including:
+
+- **Button Clicks**: Tracks every button click with the button text and page location
+- **Page Views**: Tracks page navigation and scroll depth percentage
+- **Form Interactions**: Monitors form completion percentage
+
+**Example:**
+
+```javascript
+client.analytics.track();
+```
+
+**Data Collection:**
+
+- Automatically sends analytics data to the server every 5 seconds
+- Uses canvas fingerprinting for unique visitor identification
+- Tracks only the highest scroll percentage per page (no duplicates)
+- Tracks only the highest form completion percentage per form
+
+### Data Module
+
+#### `client.data.getBlogs()`
+
+Retrieves all blogs associated with your client account.
+
+**Returns:** Promise resolving to an array of blog objects
+
+**Example:**
+
+```javascript
+const blogs = await client.data.getBlogs();
+console.log(blogs);
+```
+
+#### `client.data.getBlog(blogId)`
+
+Retrieves a specific blog by its ID.
+
+**Parameters:**
+
+- `blogId` (string): The unique identifier of the blog
+
+**Returns:** Promise resolving to a blog object
+
+**Example:**
+
+```javascript
+const blog = await client.data.getBlog('blog123');
+console.log(blog);
+```
+
+#### `client.data.postData(inboxId, data)`
+
+Posts data to a specific inbox.
+
+**Parameters:**
+
+- `inboxId` (string): The unique identifier of the inbox
+- `data` (object): The data to be posted
+
+**Returns:** Promise resolving to the server response
+
+**Example:**
+
+```javascript
+const response = await client.data.postData('inbox123', {
+  name: 'John Doe',
+  email: 'john@example.com',
+  message: 'Hello!',
+});
+```
+
+## Analytics Details
+
+### Button Click Tracking
+
+Tracks all button clicks automatically:
+
+```javascript
+// Captured data format:
+{
+  button: "Submit", // Button text
+  page: "/contact"  // Current page path
+}
+```
+
+### Page View Tracking
+
+Monitors page navigation and scroll depth:
+
+```javascript
+// Captured data format:
+{
+  page: "/about",
+  percentage: 75 // Highest scroll depth reached (0-100)
+}
+```
+
+**Note:** Only the highest scroll percentage is stored for each page visit.
+
+### Form Tracking
+
+Tracks form completion in real-time:
+
+```javascript
+// Captured data format:
+{
+  form: "Contact Us", // From data-form-name attribute or preceding H1-H3 heading
+  percent: 66.7       // Percentage of filled fields
+}
+```
+
+**Form Naming:**
+
+1. Use `data-form-name` attribute on your form element
+2. Or place an `<h1>`, `<h2>`, or `<h3>` heading before the form
+3. Fallback: "unknown-form"
+
+**Example:**
+
+```html
+<!-- Option 1: Using data-form-name -->
+<form data-form-name="Newsletter Signup">
+  <input type="email" name="email" />
+  <button type="submit">Subscribe</button>
+</form>
+
+<!-- Option 2: Using heading -->
+<h2>Contact Us</h2>
+<form>
+  <input type="text" name="name" />
+  <input type="email" name="email" />
+  <textarea name="message"></textarea>
+  <button type="submit">Send</button>
+</form>
+```
+
+## Advanced Usage
+
+### Custom Analytics Implementation
+
+If you want more control over tracking:
+
+```javascript
+import teacupnet from 'teacupnet-lib';
+
+const client = teacupnet('YOUR_CLIENT_ID', 'YOUR_CLIENT_KEY');
+
+// Enable only specific tracking
+// Note: This requires manual implementation
+// The track() method enables all tracking automatically
+```
+
+### Working with React/Vue/Angular
+
+The library works seamlessly with modern frameworks:
+
+```javascript
+// React example
+import { useEffect } from 'react';
+import teacupnet from 'teacupnet-lib';
+
+function App() {
+  useEffect(() => {
+    const client = teacupnet(
+      process.env.REACT_APP_CLIENT_ID,
+      process.env.REACT_APP_CLIENT_KEY
+    );
+
+    if (!client.error) {
+      client.analytics.track();
+    }
+  }, []);
+
+  return <div>Your App</div>;
+}
+```
+
+## Data Synchronization
+
+Analytics data is automatically sent to the TeacupNet backend:
+
+- **Interval**: Every 5 seconds
+- **Endpoint**: `https://teacupnet-backend.vercel.app/api/analytics`
+- **Included**: Fingerprint, client credentials, and collected analytics data
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+**Note:** This library uses ES modules and requires a modern browser or build tool.
+
+## Security Considerations
+
+- **Credentials**: Store your `clientID` and `clientKey` securely
+- **Environment Variables**: Use environment variables for credentials in production
+- **HTTPS**: The library communicates with the backend over HTTPS
+
+**Example `.env` file:**
+
+```env
+TEACUPNET_CLIENT_ID=your_client_id
+TEACUPNET_CLIENT_KEY=your_client_key
+```
+
+## Troubleshooting
+
+### Library not tracking
+
+Make sure you've called `client.analytics.track()` after initialization:
+
+```javascript
+const client = teacupnet('CLIENT_ID', 'CLIENT_KEY');
+client.analytics.track(); // Don't forget this!
+```
+
+### Invalid Credentials error
+
+Verify your `clientID` and `clientKey` are correct:
+
+```javascript
+const client = teacupnet('CLIENT_ID', 'CLIENT_KEY');
+if (client.error) {
+  console.error('Initialization failed:', client.message);
+}
+```
+
+### Data not appearing in dashboard
+
+- Check browser console for errors
+- Verify network requests are being sent to the backend
+- Confirm your credentials have the correct permissions
+
+## Support
+
+For issues, questions, or feature requests:
+
+- GitHub Issues: [https://github.com/tahmidjihan/teacupnet-lib/issues](https://github.com/tahmidjihan/teacupnet-lib/issues)
+- Repository: [https://github.com/tahmidjihan/teacupnet-lib](https://github.com/tahmidjihan/teacupnet-lib)
+
+## License
+
+ISC © Tahmid Jihan, Teacupnet
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and updates.

package/index.d.ts

@@ -0,0 +1,6 @@
+declare module 'teacupnet-lib' {
+  export default function init(clientID: string, clientKey: string): any;
+
+  export const initial: any;
+}
+

package/index.js

@@ -0,0 +1,24 @@
+import dataController from './Controllers/data.controller.js';
+import analytics from './Analytics/analytics.controller.js';
+
+export const initial = {
+  clientID: '',
+  clientKey: '',
+};
+
+function init(clientID, clientKey) {
+  if (!clientID || !clientKey) {
+    return {
+      error: 'Invalid Credentials',
+      message: 'Please provide clientID and clientKey',
+    };
+  }
+  initial.clientID = clientID;
+  initial.clientKey = clientKey;
+  return {
+    data: dataController,
+    analytics: analytics,
+  };
+}
+
+export default init;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "teacupweb",
+  "version": "2.2.1",
+  "description": "A powerful JavaScript library for integrating Teacup analytics and data management. Track user interactions, page views, form completions, and seamlessly connect to the Teacup backend.",
+  "keywords": [
+    "analytics",
+    "tracking",
+    "teacup",
+    "user-analytics",
+    "form-tracking",
+    "page-tracking",
+    "click-tracking",
+    "visitor-tracking",
+    "fingerprinting",
+    "web-analytics"
+  ],
+  "homepage": "https://github.com/tahmidjihan/teacup-lib#readme",
+  "bugs": {
+    "url": "https://github.com/tahmidjihan/teacup-lib/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tahmidjihan/teacup-lib.git"
+  },
+  "license": "ISC",
+  "author": "Tahmid Jihan, Teacup",
+  "type": "module",
+  "main": "index.js",
+  "exports": "./index.js",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "Analytics/",
+    "Controllers/",
+    "Functions/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}