site-vigil-visitors 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tithi
+
+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,219 @@
+# `site-vigil-visitors`
+
+Lightweight browser visit tracking with an optional React wrapper.
+
+## Features
+
+- small browser-side tracker
+- configurable `siteId` and `endpoint`
+- uses `navigator.sendBeacon()` when available
+- optional `beforeunload` leave event
+- framework-agnostic core API
+- React wrapper available via `site-vigil-visitors/react`
+
+## Installation
+
+```bash
+npm install site-vigil-visitors
+```
+
+For React projects:
+
+```bash
+npm install react site-vigil-visitors
+```
+
+## Quick start
+
+### React
+
+```tsx
+import { Tracking } from 'site-vigil-visitors/react'
+
+export function App() {
+  return (
+    <Tracking
+      siteId="my-site"
+      endpoint="https://visit-tracker.tithij.workers.dev"
+    />
+  )
+}
+```
+
+### Plain JavaScript / TypeScript
+
+```ts
+import { createTracker } from 'site-vigil-visitors'
+
+const tracker = createTracker({
+  siteId: 'my-site',
+  endpoint: 'https://visit-tracker.tithij.workers.dev',
+})
+
+tracker.start()
+```
+
+## Core usage
+
+```ts
+import { createTracker } from 'site-vigil-visitors'
+
+const tracker = createTracker({
+  siteId: 'my-site',
+  endpoint: 'https://visit-tracker.tithij.workers.dev',
+})
+
+tracker.start()
+tracker.trackEvent('cta_click', { label: 'Register' })
+```
+
+## React usage
+
+```tsx
+import { Tracking } from 'site-vigil-visitors/react'
+
+export function App() {
+  return (
+    <>
+      <Tracking
+        siteId="my-site"
+        endpoint="https://visit-tracker.tithij.workers.dev"
+      />
+      <main>Hello world</main>
+    </>
+  )
+}
+```
+
+## Small demo app
+
+Here is a minimal Vite + React example using the package:
+
+```tsx
+import { Tracking } from 'site-vigil-visitors/react'
+
+export default function App() {
+  return (
+    <div>
+      <Tracking
+        siteId="demo-site"
+        endpoint="https://visit-tracker.tithij.workers.dev"
+      />
+
+      <h1>Visit Tracker Demo</h1>
+      <button
+        onClick={() => {
+          console.log('CTA clicked')
+        }}
+      >
+        Click me
+      </button>
+    </div>
+  )
+}
+```
+
+If you want manual event tracking in the same app:
+
+```ts
+import { createTracker } from 'site-vigil-visitors'
+
+const tracker = createTracker({
+  siteId: 'demo-site',
+  endpoint: 'https://visit-tracker.tithij.workers.dev',
+})
+
+tracker.trackEvent('button_click', { button: 'hero-cta' })
+```
+
+## Next.js example
+
+Use the React wrapper inside a client component:
+
+```tsx
+'use client'
+
+import { Tracking } from 'site-vigil-visitors/react'
+
+export default function TrackingClient() {
+  return (
+    <Tracking
+      siteId="next-app"
+      endpoint="https://visit-tracker.tithij.workers.dev"
+    />
+  )
+}
+```
+
+Then include it in your app layout or page.
+
+## Plain JavaScript example
+
+```html
+<script type="module">
+  import { createTracker } from 'site-vigil-visitors'
+
+  const tracker = createTracker({
+    siteId: 'marketing-site',
+    endpoint: 'https://visit-tracker.tithij.workers.dev',
+  })
+
+  tracker.start()
+
+  document.getElementById('cta')?.addEventListener('click', () => {
+    tracker.trackEvent('cta_click', { location: 'hero' })
+  })
+</script>
+```
+
+## API
+
+### `createTracker(config)`
+
+Config options:
+
+- `siteId: string` — unique identifier for the website/app
+- `endpoint: string` — tracking endpoint URL
+- `sessionKey?: string` — session storage key, defaults to `tithij_session`
+- `includeLeaveEvent?: boolean` — whether to send a `leave` event on unload, defaults to `true`
+
+Returned methods:
+
+- `start()` — sends the initial `visit` event and binds unload tracking
+- `destroy()` — removes unload tracking
+- `trackPageView()` — manually sends a `visit` event
+- `trackEvent(action, metadata?)` — sends a custom event
+
+## Local development
+
+From the package folder:
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+To preview what will be published:
+
+```bash
+npm run pack:check
+```
+
+## Publishing
+
+1. Update the version in `package.json`
+2. Verify the package:
+   ```bash
+   npm test
+   npm run pack:check
+   ```
+3. Publish to npm:
+   ```bash
+   npm publish --access public
+   ```
+
+## Notes
+
+- This package is intended for browser environments.
+- In React development mode with `StrictMode`, effects may run twice.

package/dist/core.d.ts

@@ -0,0 +1,15 @@
+export interface TrackerConfig {
+    siteId: string;
+    endpoint: string;
+    sessionKey?: string;
+    includeLeaveEvent?: boolean;
+}
+export type TrackMetadata = Record<string, unknown>;
+export interface Tracker {
+    start: () => void;
+    destroy: () => void;
+    trackPageView: () => void;
+    trackEvent: (action: string, metadata?: TrackMetadata) => void;
+}
+export declare function createTracker({ siteId, endpoint, sessionKey, includeLeaveEvent, }: TrackerConfig): Tracker;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEnD,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,aAAa,EAAE,MAAM,IAAI,CAAA;IACzB,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,aAAa,KAAK,IAAI,CAAA;CAC/D;AAYD,wBAAgB,aAAa,CAAC,EAC5B,MAAM,EACN,QAAQ,EACR,UAA6B,EAC7B,iBAAwB,GACzB,EAAE,aAAa,GAAG,OAAO,CAoEzB"}

package/dist/core.js

@@ -0,0 +1,68 @@
+function createSessionId() {
+    const randomUUID = globalThis.crypto?.randomUUID?.bind(globalThis.crypto);
+    if (randomUUID) {
+        return randomUUID();
+    }
+    return `session-${Math.random().toString(36).slice(2)}-${Date.now()}`;
+}
+export function createTracker({ siteId, endpoint, sessionKey = 'tithij_session', includeLeaveEvent = true, }) {
+    const isBrowser = typeof window !== 'undefined' &&
+        typeof document !== 'undefined' &&
+        typeof navigator !== 'undefined';
+    const getSessionId = () => {
+        if (!isBrowser)
+            return 'server';
+        const existing = window.sessionStorage.getItem(sessionKey);
+        if (existing)
+            return existing;
+        const id = createSessionId();
+        window.sessionStorage.setItem(sessionKey, id);
+        return id;
+    };
+    const send = (action, metadata = {}) => {
+        if (!isBrowser)
+            return;
+        const payload = {
+            siteId,
+            timestamp: new Date().toISOString(),
+            page: window.location.pathname,
+            referrer: document.referrer,
+            action,
+            sessionId: getSessionId(),
+            ...metadata,
+        };
+        const body = JSON.stringify(payload);
+        if (typeof navigator.sendBeacon === 'function') {
+            const blob = new Blob([body], { type: 'application/json' });
+            navigator.sendBeacon(endpoint, blob);
+            return;
+        }
+        void fetch(endpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body,
+            keepalive: true,
+        }).catch(() => { });
+    };
+    const handleBeforeUnload = () => send('leave');
+    return {
+        start() {
+            send('visit');
+            if (includeLeaveEvent && isBrowser) {
+                window.addEventListener('beforeunload', handleBeforeUnload);
+            }
+        },
+        destroy() {
+            if (includeLeaveEvent && isBrowser) {
+                window.removeEventListener('beforeunload', handleBeforeUnload);
+            }
+        },
+        trackPageView() {
+            send('visit');
+        },
+        trackEvent(action, metadata = {}) {
+            send(action, metadata);
+        },
+    };
+}
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createTracker } from './core.js';
+export type { Tracker, TrackerConfig, TrackMetadata } from './core.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createTracker } from './core.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA"}

package/dist/react.d.ts

@@ -0,0 +1,5 @@
+import { type TrackerConfig } from './core.js';
+export interface TrackingProps extends TrackerConfig {
+}
+export declare function Tracking({ siteId, endpoint, sessionKey, includeLeaveEvent, }: TrackingProps): null;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAA;AAE7D,MAAM,WAAW,aAAc,SAAQ,aAAa;CAAG;AAEvD,wBAAgB,QAAQ,CAAC,EACvB,MAAM,EACN,QAAQ,EACR,UAAU,EACV,iBAAiB,GAClB,EAAE,aAAa,QAiBf"}

package/dist/react.js

@@ -0,0 +1,18 @@
+import { useEffect } from 'react';
+import { createTracker } from './core.js';
+export function Tracking({ siteId, endpoint, sessionKey, includeLeaveEvent, }) {
+    useEffect(() => {
+        const tracker = createTracker({
+            siteId,
+            endpoint,
+            sessionKey,
+            includeLeaveEvent,
+        });
+        tracker.start();
+        return () => {
+            tracker.destroy();
+        };
+    }, [siteId, endpoint, sessionKey, includeLeaveEvent]);
+    return null;
+}
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACjC,OAAO,EAAE,aAAa,EAAsB,MAAM,WAAW,CAAA;AAI7D,MAAM,UAAU,QAAQ,CAAC,EACvB,MAAM,EACN,QAAQ,EACR,UAAU,EACV,iBAAiB,GACH;IACd,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,OAAO,GAAG,aAAa,CAAC;YAC5B,MAAM;YACN,QAAQ;YACR,UAAU;YACV,iBAAiB;SAClB,CAAC,CAAA;QAEF,OAAO,CAAC,KAAK,EAAE,CAAA;QAEf,OAAO,GAAG,EAAE;YACV,OAAO,CAAC,OAAO,EAAE,CAAA;QACnB,CAAC,CAAA;IACH,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,iBAAiB,CAAC,CAAC,CAAA;IAErD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "site-vigil-visitors",
+  "version": "0.1.0",
+  "description": "Lightweight browser visit tracking with optional React integration.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "analytics",
+    "tracking",
+    "react",
+    "browser",
+    "visit-tracker"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"import('node:fs/promises').then(fs => fs.rm('dist', { recursive: true, force: true }))\"",
+    "test": "npm run build && node --test test/**/*.test.js",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm run test && npm run pack:check"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}