uac-package 1.1.0

package/README.md

@@ -0,0 +1,572 @@
+# uac-package
+
+**User Activity Control** — zero-config npm package for domain registration, click tracking, device detection, and analytics. Install in any frontend project; data flows to your [UAC backend](https://github.com/sandeep-sana/uac-package) and dashboard.
+
+---
+
+## What it does
+
+| Feature | Description |
+| -------- | ------------ |
+| **Domain tracking** | Auto-registers `localhost:5173`, production URLs, etc. when you run `dev` / `start` |
+| **Click tracking** | Every click sent with timestamp, page route, element info, time on page |
+| **Device tracking** | Unique device ID (localStorage) + platform (Windows, Mac, Mobile, Linux) |
+| **Zero config** | `npm install` patches scripts and injects the tracker automatically (Vite projects) |
+
+Works with the **UAC Dashboard** for day → platform → device → route → activity drill-down.
+
+---
+
+## Prerequisites
+
+1. **UAC Backend** running (MongoDB + Express API on port 3000 by default)
+2. **Node.js 18+**
+
+```bash
+# Clone / run your backend (separate repo or monorepo)
+cd uac-backend
+npm install
+npm start
+# → http://localhost:3000
+```
+
+---
+
+## Quick start (any Vite app — Vue, React, Svelte)
+
+```bash
+npm install uac-package
+npm run dev
+```
+
+On install, the package automatically:
+
+- Patches `dev` / `preview` scripts to register domains from Vite output
+- Injects `import 'uac-package/track'` into `src/main.js` or `src/main.ts`
+
+No manual code required.
+
+---
+
+## Publish to npm (for maintainers)
+
+Follow these steps to publish so **everyone can install** with `npm install uac-package`.
+
+### 1. Create an npm account
+
+- Sign up at [https://www.npmjs.com/signup](https://www.npmjs.com/signup)
+- Verify your email
+
+### 2. Log in locally
+
+```bash
+cd uac-package
+npm login
+```
+
+Enter username, password, and OTP if 2FA is enabled.
+
+### 3. Check package name availability
+
+```bash
+npm view uac-package
+```
+
+If the name is taken, use a **scoped name** in `package.json`:
+
+```json
+{
+  "name": "@your-username/uac-package",
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+Users install with:
+
+```bash
+npm install @your-username/uac-package
+```
+
+### 4. Update version before each release
+
+```bash
+npm version patch   # 1.0.0 → 1.0.1
+# or
+npm version minor   # 1.0.0 → 1.1.0
+# or
+npm version major   # 1.0.0 → 2.0.0
+```
+
+### 5. Publish
+
+```bash
+npm publish
+# scoped public package:
+npm publish --access public
+```
+
+### 6. Verify
+
+```bash
+npm view uac-package
+npm install uac-package@latest
+```
+
+### 7. CI publish (optional — GitHub Actions)
+
+```yaml
+# .github/workflows/publish.yml
+name: Publish npm
+on:
+  release:
+    types: [published]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+      - run: npm ci
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+Create an **npm Access Token** (Automation type) at npmjs.com → Account → Access Tokens → add as `NPM_TOKEN` in GitHub Secrets.
+
+---
+
+## Install in any project (users)
+
+```bash
+npm install uac-package
+```
+
+Then run your app as usual. For Vite projects, integration is automatic after install.
+
+---
+
+## Framework guides
+
+### Vue 3 + Vite (recommended — fully automatic)
+
+```bash
+npm install uac-package
+npm run dev
+```
+
+After install, `package.json` scripts look like:
+
+```json
+{
+  "scripts": {
+    "dev": "node ./node_modules/uac-package/bin/cli.js dev vite"
+  }
+}
+```
+
+And `src/main.js` gets:
+
+```js
+import 'uac-package/track' // @uac-auto
+```
+
+---
+
+### React + Vite
+
+Same as Vue — install and run:
+
+```bash
+npm install uac-package
+npm run dev
+```
+
+If entry is `src/main.tsx`, postinstall injects there automatically.
+
+**Manual** (if auto-inject did not run):
+
+```tsx
+// src/main.tsx — add at the very top
+import 'uac-package/track'
+
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />)
+```
+
+Patch `package.json` dev script:
+
+```json
+"dev": "node ./node_modules/uac-package/bin/cli.js dev vite"
+```
+
+---
+
+### Svelte + Vite
+
+```bash
+npm install uac-package
+```
+
+Add to `src/main.js` if not auto-injected:
+
+```js
+import 'uac-package/track'
+```
+
+Use patched dev script (same as Vue).
+
+---
+
+### Next.js (App Router)
+
+Next.js does not use Vite by default. Use **manual** setup:
+
+**1. Install**
+
+```bash
+npm install uac-package
+```
+
+**2. Client tracker** — create `components/UacTracker.tsx`:
+
+```tsx
+'use client'
+
+import { useEffect } from 'react'
+
+export default function UacTracker() {
+  useEffect(() => {
+    import('uac-package/track')
+  }, [])
+  return null
+}
+```
+
+**3. Root layout** — `app/layout.tsx`:
+
+```tsx
+import UacTracker from '@/components/UacTracker'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <UacTracker />
+        {children}
+      </body>
+    </html>
+  )
+}
+```
+
+**4. Domain registration** — register on start or in CI:
+
+```js
+// scripts/register-domain.js
+const uac = require('uac-package')
+uac.init({ url: process.env.NEXT_PUBLIC_APP_URL || 'https://yourapp.com' })
+```
+
+Or set `PORT` / `UAC_API_URL` when running:
+
+```bash
+UAC_API_URL=https://api.yourapp.com node -r uac-package/register server.js
+```
+
+**5. Environment** — `.env.local`:
+
+```env
+NEXT_PUBLIC_UAC_API_URL=http://localhost:3000
+```
+
+> Note: Browser tracker reads `VITE_UAC_*` in Vite apps. For Next.js you may set backend URL via a small wrapper or extend env in your build. Default backend is `http://localhost:3000`.
+
+---
+
+### Angular
+
+**1. Install**
+
+```bash
+npm install uac-package
+```
+
+**2. Entry file** — `src/main.ts`:
+
+```ts
+import 'uac-package/track'
+
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'
+import { AppModule } from './app/app.module'
+
+platformBrowserDynamic().bootstrapModule(AppModule)
+```
+
+**3. Dev script** — if using Vite-based Angular or custom server, patch `package.json`:
+
+```json
+"start": "node ./node_modules/uac-package/bin/cli.js dev ng serve"
+```
+
+For domain registration with `ng serve`, use the Vite plugin alternative or manual `init`:
+
+```js
+const uac = require('uac-package')
+uac.init({ port: 4200, host: 'localhost' })
+```
+
+---
+
+### Nuxt 3
+
+**1. Install**
+
+```bash
+npm install uac-package
+```
+
+**2. Plugin** — `plugins/uac.client.ts`:
+
+```ts
+import 'uac-package/track'
+
+export default defineNuxtPlugin(() => {})
+```
+
+**3. Domain** — register in `nuxt.config` hook or on deploy:
+
+```js
+// server/plugins/uac.ts or build script
+import uac from 'uac-package'
+await uac.init({ url: process.env.NUXT_PUBLIC_SITE_URL })
+```
+
+---
+
+### Plain HTML / CDN (no bundler)
+
+Host `track` via your bundler or copy approach — recommended to use npm + Vite/webpack. Minimal ESM setup:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>My App</title>
+  </head>
+  <body>
+    <button id="demo">Click me</button>
+    <script type="module">
+      import 'uac-package/track'
+    </script>
+  </body>
+</html>
+```
+
+Serve with Vite and use patched dev script for domain registration.
+
+---
+
+### Node.js / Express API
+
+Register domain when server starts:
+
+**Option A — require hook**
+
+```json
+{
+  "scripts": {
+    "start": "node -r uac-package/register index.js"
+  }
+}
+```
+
+**Option B — programmatic**
+
+```js
+const uac = require('uac-package')
+
+const PORT = process.env.PORT || 4000
+
+uac.init({ port: PORT, host: 'localhost' }).then(() => {
+  app.listen(PORT, () => console.log(`Listening on ${PORT}`))
+})
+```
+
+> Click tracking is browser-only. Node apps get **domain registration** only unless you call the backend API yourself.
+
+---
+
+### Vite plugin (manual alternative)
+
+If you prefer not to patch `dev` script:
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import uac from 'uac-package/vite'
+
+export default defineConfig({
+  plugins: [vue(), uac()],
+})
+```
+
+Still add `import 'uac-package/track'` in your entry file for clicks.
+
+---
+
+## Environment variables
+
+### Server / CLI (domain registration)
+
+| Variable | Default | Description |
+| -------- | ------- | ----------- |
+| `UAC_API_URL` | `https://uac-backend.clay.in` | UAC backend base URL |
+| `UAC_AUTO_TRACK` | `true` | Set `false` to disable auto domain registration |
+| `PORT` | — | App port (used to build domain) |
+| `HOST` | `localhost` | App host |
+
+### Browser (click tracking — Vite projects)
+
+| Variable | Default | Description |
+| -------- | ------- | ----------- |
+| `VITE_UAC_API_URL` | `https://uac-backend.clay.in` | Backend URL in the browser |
+| `VITE_UAC_AUTO_TRACK` | `true` | Set `false` to disable click tracking |
+
+Example `.env`:
+
+```env
+VITE_UAC_API_URL=http://localhost:3000
+UAC_API_URL=http://localhost:3000
+```
+
+Production:
+
+```env
+VITE_UAC_API_URL=https://api.yourcompany.com
+```
+
+---
+
+## What gets tracked on each click
+
+```json
+{
+  "domain": "localhost:5173",
+  "deviceId": "uuid-from-localStorage",
+  "device": {
+    "deviceType": "windows",
+    "deviceOperatingSystem": "Windows"
+  },
+  "name": "click:button",
+  "description": "Clicked 3 times | button#home-increment | /products",
+  "spentTime": 5200,
+  "clickedAt": "2026-06-26T13:03:24.000Z"
+}
+```
+
+- **domain** — `window.location.host`
+- **route** — parsed from `description` (last segment, e.g. `/products`)
+- **deviceId** — persistent per browser
+- **platform** — Windows / Mac / Mobile / Linux
+
+---
+
+## UAC Dashboard
+
+Run `uac-frontend` (separate app) to view analytics:
+
+1. **Daily Overview** — unique users per day
+2. **Day tab** — platform chart (Windows, Mac, Mobile…)
+3. **Platform tab** — devices + page routes chart
+4. **Device tab** — routes chart + user flow log
+5. **Route tab** — all click activities on that page
+
+---
+
+## Manual API
+
+```js
+const uac = require('uac-package')
+
+// Register domain
+await uac.init({ port: 5173, host: 'localhost' })
+await uac.init({ url: 'https://myapp.com' })
+
+// Run integration manually (patch scripts + inject tracker)
+uac.integrate(process.cwd())
+
+// Vite plugin
+import uacVite from 'uac-package/vite'
+```
+
+| Export | Description |
+| ------ | ----------- |
+| `init()` | Register domain with backend |
+| `registerDomain()` | Register by domain string |
+| `autoTrack()` | Auto-register from env/port |
+| `integrate()` | Patch project scripts + inject tracker |
+| `vite()` | Vite plugin for domain on server start |
+| `uac-package/track` | Browser click + device tracker (ESM) |
+
+---
+
+## Disable tracking
+
+```bash
+# Disable domain auto-track (CLI)
+UAC_AUTO_TRACK=false npm run dev
+
+# Disable click tracking (browser — Vite)
+VITE_UAC_AUTO_TRACK=false npm run dev
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+| ------- | --- |
+| Clicks not saved | Ensure backend is running at `UAC_API_URL` / `VITE_UAC_API_URL` |
+| Domain not registered | Check dev script includes `uac-package/bin/cli.js dev` |
+| No tracker in app | Add `import 'uac-package/track'` to entry file |
+| CORS errors | Configure CORS on backend for your frontend origin |
+| `409 Domain exists` | Normal — domain already registered |
+| Windows script fails | Use `node ./node_modules/uac-package/bin/cli.js dev vite` |
+
+Re-run integration manually:
+
+```js
+require('uac-package').integrate(process.cwd())
+```
+
+---
+
+## Project structure (monorepo)
+
+```
+UAC/
+├── uac-backend/      # Express + MongoDB API
+├── uac-package/      # This npm package ← publish this
+├── uac-frontend/     # Analytics dashboard
+└── vue-project/      # Example test app
+```
+
+---
+
+## License
+
+MIT
+
+## Repository
+
+[https://github.com/sandeep-sana/uac-package](https://github.com/sandeep-sana/uac-package)

package/bin/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+const { run } = require('./dev');
+
+const [, , command, ...args] = process.argv;
+
+if (command === 'dev') {
+  run(args);
+} else {
+  console.log('Usage: uac-package dev <command> [args...]');
+  console.log('Example: uac-package dev vite');
+  process.exit(command ? 1 : 0);
+}

package/bin/dev.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const { autoTrack } = require('../lib/autoTrack');
+
+const URL_PATTERN = /(?:Local|Network):\s+(https?:\/\/[^\s]+)/gi;
+const trackedUrls = new Set();
+
+function trackFromOutput(text) {
+  URL_PATTERN.lastIndex = 0;
+  let match;
+
+  while ((match = URL_PATTERN.exec(text)) !== null) {
+    const url = match[1];
+
+    if (trackedUrls.has(url)) {
+      continue;
+    }
+
+    trackedUrls.add(url);
+
+    try {
+      const parsed = new URL(url);
+      autoTrack({
+        host: parsed.hostname,
+        port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+        protocol: parsed.protocol.replace(':', ''),
+      });
+    } catch {
+      autoTrack({ url });
+    }
+  }
+}
+
+function run(args) {
+  if (!args.length) {
+    console.error('[UAC] Usage: uac-package dev <command> [args...]');
+    process.exit(1);
+  }
+
+  const [command, ...commandArgs] = args;
+  const child = spawn(command, commandArgs, {
+    stdio: ['inherit', 'pipe', 'pipe'],
+    shell: true,
+    cwd: process.cwd(),
+    env: process.env,
+  });
+
+  child.stdout.on('data', (chunk) => {
+    process.stdout.write(chunk);
+    trackFromOutput(chunk.toString());
+  });
+
+  child.stderr.on('data', (chunk) => {
+    process.stderr.write(chunk);
+    trackFromOutput(chunk.toString());
+  });
+
+  child.on('exit', (code) => {
+    process.exit(code ?? 0);
+  });
+}
+
+module.exports = { run };
+
+if (require.main === module) {
+  run(process.argv.slice(2));
+}

package/index.d.ts

@@ -0,0 +1,54 @@
+export interface RegisterResult {
+  created: boolean;
+  name: string;
+  domain?: {
+    _id: string;
+    name: string;
+    createdAt: string;
+    updatedAt: string;
+  };
+  message?: string;
+}
+
+export interface UacOptions {
+  apiUrl?: string;
+  url?: string;
+  domain?: string;
+  name?: string;
+  host?: string;
+  port?: number | string;
+  protocol?: string;
+  headers?: Record<string, string>;
+}
+
+export interface BootResult {
+  port: number | string;
+  appUrl: string;
+  domain: string;
+  registration: RegisterResult;
+  apiUrl: string;
+}
+
+export interface StartResult extends BootResult {
+  server: import('http').Server;
+}
+
+export class UacError extends Error {
+  status?: number;
+  code?: string;
+}
+
+export function normalizeDomain(input: string): string;
+export function isValidDomain(name: string): boolean;
+export function resolveAppUrl(options?: UacOptions): string;
+export function getApiUrl(options?: UacOptions): string;
+export function registerDomain(
+  input: string,
+  options?: UacOptions
+): Promise<RegisterResult>;
+export function init(input?: string | UacOptions, options?: UacOptions): Promise<RegisterResult>;
+export function boot(options?: UacOptions): Promise<BootResult>;
+export function start(options?: UacOptions): Promise<StartResult>;
+export function autoTrack(options?: UacOptions): Promise<RegisterResult | null>;
+export function integrate(projectRoot: string): boolean;
+export function vite(options?: UacOptions): import('vite').Plugin;

package/index.js

@@ -0,0 +1,22 @@
+const { normalizeDomain, isValidDomain, resolveAppUrl } = require('./lib/normalizeDomain');
+const { UacError, getApiUrl, registerDomain, init } = require('./lib/client');
+const { boot } = require('./lib/boot');
+const { start } = require('./lib/start');
+const { autoTrack } = require('./lib/autoTrack');
+const { vitePlugin } = require('./lib/vite');
+const { integrate } = require('./lib/integrate');
+
+module.exports = {
+  UacError,
+  normalizeDomain,
+  isValidDomain,
+  resolveAppUrl,
+  getApiUrl,
+  registerDomain,
+  init,
+  boot,
+  start,
+  autoTrack,
+  integrate,
+  vite: vitePlugin,
+};