onedollarstats 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Drizzle Team
+
+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,122 @@
+# OneDollarStats
+
+[![npm version](https://img.shields.io/npm/v/onedollarstats)](https://www.npmjs.com/package/onedollarstats)  
+[![Website](https://img.shields.io/badge/site-onedollarstats.com-blue)](https://onedollarstats.com/home)
+
+A lightweight, zero-dependency analytics tracker for client apps. OneDollarStats automatically collects pageviews, UTM parameters, and custom events with minimal setup.
+
+## Features
+
+-Automatic pageview tracking (supports client/server side navigation and hash routing)
+-Automatic UTM parameter collection
+-Automatic event tracking on clicks of elements with data-s-event attributes
+-Zero dependencies, easy to integrate
+
+## Installation
+
+```bash
+npm i onedollarstats
+```
+
+## Getting Started
+
+### Configure analytics
+
+> ⚠️ Initialize analytics on every page for static sites, or at the root layout (app entrypoint) in SPA apps.
+> Calling `view` or `event` before `configure` will automatically initialize the tracker with the default configuration.
+
+```ts
+import { configure } from "onedollarstats";
+
+// Configure analytics
+configure({
+  collectorUrl: "https://collector.onedollarstats.com/events",
+  autocollect: true, // automatically tracks pageviews & clicks
+  hashRouting: true // track SPA hash route changes
+});
+```
+
+#### Track Pageviews Manually
+
+By default, pageviews are tracked automatically. If you want to track them manually (for example, with autocollect: false), you can use the `view` function:
+
+```ts
+import { view } from "onedollarstats";
+
+// Simple pageview
+view("/homepage");
+
+// Pageview with extra properties
+view("/checkout", { step: 2, plan: "pro" });
+```
+
+#### Track Custom Events Manually
+
+The `event` function can accept different types of arguments depending on your needs:
+
+```ts
+import { event } from "onedollarstats";
+
+// Simple event
+event("Purchase");
+
+// Event with a path
+event("Purchase", "/product");
+
+// Event with properties
+event("Purchase", { amount: 1, color: "green" });
+
+// Event with path + properties
+event("Purchase", "/product", { amount: 1, color: "green" });
+```
+
+## API
+
+#### `configure(config?: AnalyticsConfig)` initializes the tracker with your configuration.
+
+**Config Options:**
+
+| Option             | Type             | Default                                         | Description                                |
+| ------------------ | ---------------- | ----------------------------------------------- | ------------------------------------------ |
+| `collectorUrl`     | `string`         | `"https://collector.onedollarstats.com/events"` | URL to send analytics events               |
+| `trackLocalhostAs` | `string \| null` | `null`                                          | Replace localhost hostname for dev testing |
+| `hashRouting`      | `boolean`        | `false`                                         | Track hash route changes as pageviews      |
+| `autocollect`      | `boolean`        | `true`                                          | Automatically track pageviews & clicks     |
+| `excludePages`     | `string[]`       | `[]`                                            | Pages to ignore for automatic tracking     |
+| `includePages`     | `string[]`       | `[]`                                            | Pages to explicitly include for tracking   |
+
+> **Notes:**
+>
+> - Manual calls of `view` or `event` **ignore** `excludePages`/`includePages`.
+> - By default, events from `localhost` are ignored. Use the `trackLocalhostAs` option to simulate a hostname for local development.
+
+---
+
+#### `view(pathOrProps?: string | Record<string, string>, props?:  Record<string, string>)` sends a pageview event.
+
+**Parameters:**
+
+- `pathOrProps` – Optional, **string** represents the path, **object** represents custom properties.
+- `props` – Optional, properties if the first argument is a path string.
+
+---
+
+#### `event(eventName: string, pathOrProps?: string |  Record<string, string>, props?:  Record<string, string>)` sends a custom event.
+
+**Parameters:**
+
+- `eventName` – Name of the event.
+- `pathOrProps` – Optional, **string** represents the path, **object** represents custom properties.
+- `props` – Optional, properties if the second argument is a path string.
+
+---
+
+## Click Autocapture
+
+Automatically capture clicks on elements using these HTML attributes:
+
+- `data-s-event`– Name of the event
+- `data-s-event-path` Optional, the path representing the page where the event occurred
+- `data-s-event-props` – Optional, properties to send with the event
+
+For full details, see the [Click Autocapture documentation](https://docs.onedollarstats.com/send-events).

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { AnalyticsConfig, BaseProps } from "./types";
+export declare const configure: (userConfig?: AnalyticsConfig) => void;
+export declare const event: (eventName: string, pathOrProps?: string | BaseProps, props?: BaseProps) => Promise<void>;
+export declare const view: (pathOrProps?: string | BaseProps, props?: BaseProps) => Promise<void>;

package/dist/index.js

@@ -0,0 +1,261 @@
+// src/utils/environment.ts
+var getEnvironment = () => ({
+  isLocalhost: /^localhost$|^127(\.[0-9]+){0,2}\.[0-9]+$|^\[::1?\]$/.test(location.hostname) || location.protocol === "file:",
+  isHeadlessBrowser: Boolean(
+    window.navigator.webdriver || "_phantom" in window && window._phantom || "__nightmare" in window && window.__nightmare || "Cypress" in window && window.Cypress
+  )
+});
+var isClient = () => {
+  try {
+    if (typeof window === "undefined" || typeof document === "undefined") return false;
+    const ua = typeof navigator !== "undefined" ? navigator.userAgent : "";
+    if (/node|jsdom/i.test(ua)) return false;
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// src/utils/parse-utm-params.ts
+var parseUtmParams = (urlSearchParams) => {
+  const utm = {};
+  ["utm_campaign", "utm_source", "utm_medium", "utm_term", "utm_content"].forEach((key) => {
+    const values = urlSearchParams.getAll(key);
+    if (values.length === 1) {
+      utm[key] = values[0];
+    } else if (values.length > 1) {
+      utm[key] = values;
+    }
+  });
+  return utm;
+};
+
+// src/utils/props-parser.ts
+var parseProps = (propsString) => {
+  if (!propsString) return void 0;
+  const splittedProps = propsString.split(";");
+  const propsObj = {};
+  for (const keyValueString of splittedProps) {
+    const keyValuePair = keyValueString.split("=").map((el) => el.trim());
+    if (keyValuePair.length !== 2 || keyValuePair[0] === "" || keyValuePair[1] === "") continue;
+    propsObj[keyValuePair[0]] = keyValuePair[1];
+  }
+  return Object.keys(propsObj).length === 0 ? void 0 : propsObj;
+};
+
+// src/utils/should-track.ts
+var matchesPattern = (path, pattern) => {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`).test(path);
+};
+var shouldTrackPath = (path, config) => {
+  if (config.excludePages.some((pattern) => matchesPattern(path, pattern))) return false;
+  if (config.includePages.length && !config.includePages.some((pattern) => matchesPattern(path, pattern))) return false;
+  return true;
+};
+
+// src/index.ts
+var defaultConfig = {
+  trackLocalhostAs: null,
+  collectorUrl: "https://collector.onedollarstats.com/events",
+  hashRouting: false,
+  autocollect: true,
+  excludePages: [],
+  includePages: []
+};
+var _AnalyticsTracker = class _AnalyticsTracker {
+  constructor(userConfig = {}) {
+    this.autocollectSetupDone = false;
+    this.lastPage = null;
+    this.config = { ...defaultConfig, ...userConfig };
+    if (!isClient()) return;
+    if (this.config.autocollect) this.setupAutocollect();
+  }
+  static getInstance(userConfig = {}) {
+    if (!isClient()) {
+      console.warn("[onedollarstats] Running in non-browser environment. Returning no-op instance.");
+      return new _AnalyticsTracker(userConfig);
+    }
+    if (!_AnalyticsTracker.instance) {
+      _AnalyticsTracker.instance = new _AnalyticsTracker(userConfig);
+    }
+    return _AnalyticsTracker.instance;
+  }
+  async sendWithBeaconOrFetch(stringifiedBody) {
+    if (navigator.sendBeacon?.(this.config.collectorUrl, stringifiedBody)) return;
+    fetch(this.config.collectorUrl, {
+      method: "POST",
+      body: stringifiedBody,
+      headers: { "Content-Type": "application/json" },
+      keepalive: true
+    }).catch((err) => console.error("[onedollarstats] fetch() failed:", err.message));
+  }
+  // Handles localhost replacement, referrer, UTM parameters, and debug mode.
+  // Uses img beacon then `navigator.sendBeacon` if available, otherwise falls back to `fetch`.
+  async send(data) {
+    const { isLocalhost, isHeadlessBrowser } = getEnvironment();
+    if (isLocalhost && !this.config.trackLocalhostAs || isHeadlessBrowser) return;
+    const urlToSend = new URL(location.href);
+    let isDebug = false;
+    if (isLocalhost && this.config.trackLocalhostAs && urlToSend.hostname !== this.config.trackLocalhostAs) {
+      isDebug = true;
+      urlToSend.hostname = this.config.trackLocalhostAs;
+    }
+    urlToSend.search = "";
+    if (data.path) urlToSend.pathname = data.path;
+    const cleanUrl = urlToSend.href.replace(/\/$/, "");
+    let referrer = data.referrer;
+    try {
+      if (!referrer && document.referrer && document.referrer !== "null") {
+        const referrerURL = new URL(document.referrer);
+        if (referrerURL.hostname !== urlToSend.hostname) referrer = referrerURL.href;
+      }
+    } catch {
+    }
+    const body = {
+      u: cleanUrl,
+      e: [
+        {
+          t: data.type,
+          h: this.config.hashRouting,
+          r: referrer,
+          p: data.props
+        }
+      ]
+    };
+    if (data.utm && Object.keys(data.utm).length > 0) body.qs = data.utm;
+    if (isDebug) body.debug = true;
+    const stringifiedBody = JSON.stringify(body);
+    const payloadBase64 = btoa(stringifiedBody);
+    const safeGetThreshold = 1500;
+    const tryImageBeacon = payloadBase64.length <= safeGetThreshold;
+    if (tryImageBeacon) {
+      const img = new Image(1, 1);
+      img.onerror = () => {
+        this.sendWithBeaconOrFetch(stringifiedBody).catch((err) => console.error("[onedollarstats] fallback failed:", err?.message || err));
+      };
+      img.src = `${this.config.collectorUrl}?data=${payloadBase64}`;
+    }
+    await this.sendWithBeaconOrFetch(stringifiedBody);
+  }
+  // Prevents duplicate pageviews and respects include/exclude page rules. Automatically parses UTM parameters from URL.
+  trackPageView({ path, props }, checkBlock = false) {
+    if (!isClient()) return;
+    const cleanPath = path || location.pathname;
+    if (!this.config.hashRouting && this.lastPage === cleanPath) return;
+    if (checkBlock && !shouldTrackPath(cleanPath, this.config)) return;
+    this.lastPage = cleanPath;
+    const utm = parseUtmParams(new URLSearchParams(location.search));
+    this.send({ type: "PageView", path: cleanPath, props, utm });
+  }
+  /**
+   * Tracks a custom event.
+   * Can accept path string or a props object.
+   *
+   * @param eventName Name of the event to track.
+   * @param pathOrProps Optional path string or props object.
+   * @param props Optional props object if path string is provided.
+   */
+  async event(eventName, pathOrProps, props) {
+    if (!isClient()) return;
+    const { isLocalhost, isHeadlessBrowser } = getEnvironment();
+    if (isLocalhost && !this.config.trackLocalhostAs || isHeadlessBrowser) return;
+    const args = {};
+    if (typeof pathOrProps === "string") {
+      args.path = pathOrProps;
+      args.props = props;
+    } else if (typeof pathOrProps === "object") args.props = pathOrProps;
+    this.send({ type: eventName, ...args });
+  }
+  /**
+   * Records a page view.
+   * Can accept path string or a props object.
+   *
+   * @param pathOrProps Optional path string or props object.
+   * @param props Optional props when first arg is a path string.
+   */
+  async view(pathOrProps, props) {
+    if (!isClient()) return;
+    const args = {};
+    if (typeof pathOrProps === "string") {
+      args.path = pathOrProps;
+      args.props = props;
+    } else if (typeof pathOrProps === "object") {
+      args.props = pathOrProps;
+    }
+    this.trackPageView(args);
+  }
+  /**
+   * Installs global DOM/window listeners exactly once for:
+   *  - visibilitychange
+   *  - history.pushState
+   *  - popstate
+   *  - hashchange
+   *  - click autocapture for elements annotated with `data-s:event` & `data-s-event`
+   *
+   */
+  setupAutocollect() {
+    if (!isClient() || this.autocollectSetupDone) return;
+    this.autocollectSetupDone = true;
+    const handlePageView = () => this.trackPageView({ path: location.pathname }, true);
+    const onVisibility = () => {
+      if (document.visibilityState === "visible") handlePageView();
+    };
+    document.addEventListener("visibilitychange", onVisibility);
+    const origPush = history.pushState.bind(history);
+    history.pushState = (...args) => {
+      origPush(...args);
+      requestAnimationFrame(() => {
+        handlePageView();
+      });
+    };
+    window.addEventListener("popstate", handlePageView);
+    window.addEventListener("hashchange", handlePageView);
+    const onClick = (ev) => {
+      const clickEvent = ev;
+      if (clickEvent.type === "auxclick" && clickEvent.button !== 1) return;
+      const target = clickEvent.target;
+      if (!target) return;
+      const insideInteractive = !!target.closest("a, button");
+      let el = target;
+      let depth = 0;
+      while (el) {
+        const eventName = el.getAttribute("data-s:event") ?? el.getAttribute("data-s-event");
+        if (eventName) {
+          const propsAttr = el.getAttribute("data-s:event-props") ?? el.getAttribute("data-s-event-props");
+          const props = propsAttr ? parseProps(propsAttr) : void 0;
+          const path = el.getAttribute("data-s:event-path") || el.getAttribute("data-s-event-path") || void 0;
+          if (path && !shouldTrackPath(path, this.config) || !shouldTrackPath(location.pathname, this.config)) {
+            return;
+          }
+          this.event(eventName, path ?? props, props);
+          return;
+        }
+        el = el.parentElement;
+        depth++;
+        if (!insideInteractive && depth >= 3) break;
+      }
+    };
+    document.addEventListener("click", onClick);
+    if (document.visibilityState === "visible") handlePageView();
+  }
+};
+_AnalyticsTracker.instance = null;
+var AnalyticsTracker = _AnalyticsTracker;
+var configure = (userConfig = {}) => {
+  AnalyticsTracker.getInstance(userConfig);
+};
+var event = async (eventName, pathOrProps, props) => {
+  const instance = AnalyticsTracker.getInstance();
+  await instance.event(eventName, pathOrProps, props);
+};
+var view = async (pathOrProps, props) => {
+  const instance = AnalyticsTracker.getInstance();
+  await instance.view(pathOrProps, props);
+};
+export {
+  configure,
+  event,
+  view
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/utils/environment.ts", "../src/utils/parse-utm-params.ts", "../src/utils/props-parser.ts", "../src/utils/should-track.ts", "../src/index.ts"],
+  "sourcesContent": ["export const getEnvironment = (): {\n  isLocalhost: boolean;\n  isHeadlessBrowser: boolean;\n} => ({\n  isLocalhost: /^localhost$|^127(\\.[0-9]+){0,2}\\.[0-9]+$|^\\[::1?\\]$/.test(location.hostname) || location.protocol === \"file:\",\n  isHeadlessBrowser: Boolean(\n    window.navigator.webdriver ||\n      (\"_phantom\" in window && window._phantom) ||\n      (\"__nightmare\" in window && window.__nightmare) ||\n      (\"Cypress\" in window && window.Cypress)\n  )\n});\nexport const isClient = (): boolean => {\n  try {\n    // Basic checks for window and document\n    if (typeof window === \"undefined\" || typeof document === \"undefined\") return false;\n\n    // Check for navigator safely\n    const ua = typeof navigator !== \"undefined\" ? navigator.userAgent : \"\";\n    if (/node|jsdom/i.test(ua)) return false;\n    return true;\n  } catch {\n    return false;\n  }\n};\n", "export const parseUtmParams = (urlSearchParams: URLSearchParams) => {\n  const utm: Record<string, string | string[]> = {};\n\n  [\"utm_campaign\", \"utm_source\", \"utm_medium\", \"utm_term\", \"utm_content\"].forEach((key) => {\n    const values = urlSearchParams.getAll(key);\n    if (values.length === 1) {\n      utm[key] = values[0];\n    } else if (values.length > 1) {\n      utm[key] = values; // store array if multiple values\n    }\n  });\n\n  return utm;\n};\n", "export const parseProps = (propsString: string): Record<string, string> | undefined => {\n  if (!propsString) return undefined;\n  // \"key1=value1;key2=value2\"\n\n  const splittedProps = propsString.split(\";\");\n  const propsObj: Record<string, string> = {};\n\n  for (const keyValueString of splittedProps) {\n    const keyValuePair = keyValueString.split(\"=\").map((el) => el.trim());\n    if (keyValuePair.length !== 2 || keyValuePair[0] === \"\" || keyValuePair[1] === \"\") continue;\n    // @ts-ignore\n    propsObj[keyValuePair[0]] = keyValuePair[1];\n  }\n\n  return Object.keys(propsObj).length === 0 ? undefined : propsObj;\n};\n", "import type { AnalyticsConfig } from \"../types\";\n\nconst matchesPattern = (path: string, pattern: string): boolean => {\n  // Escape special regex characters except '*' which becomes '.*'\n  const escaped = pattern.replace(/[.+^${}()|[\\]\\\\]/g, \"\\\\$&\").replace(/\\*/g, \".*\");\n  return new RegExp(`^${escaped}$`).test(path);\n};\n\nexport const shouldTrackPath = (path: string, config: Required<AnalyticsConfig>): boolean => {\n  // Exclude pages first\n  if (config.excludePages.some((pattern) => matchesPattern(path, pattern))) return false;\n  // If includePages is defined, only allow matching paths\n  if (config.includePages.length && !config.includePages.some((pattern) => matchesPattern(path, pattern))) return false;\n  return true;\n};\n", "import type { AnalyticsConfig, BaseProps, BodyToSend, Event, ViewArguments } from \"./types\";\nimport { getEnvironment, isClient } from \"./utils/environment\";\nimport { parseUtmParams } from \"./utils/parse-utm-params\";\nimport { parseProps } from \"./utils/props-parser\";\nimport { shouldTrackPath } from \"./utils/should-track\";\n\nconst defaultConfig: Required<AnalyticsConfig> = {\n  trackLocalhostAs: null,\n  collectorUrl: \"https://collector.onedollarstats.com/events\",\n  hashRouting: false,\n  autocollect: true,\n  excludePages: [],\n  includePages: []\n};\n\nclass AnalyticsTracker {\n  private static instance: AnalyticsTracker | null = null;\n\n  private autocollectSetupDone = false;\n  private config: Required<AnalyticsConfig>;\n  private lastPage: string | null = null;\n\n  public static getInstance(userConfig: AnalyticsConfig = {}): AnalyticsTracker {\n    if (!isClient()) {\n      console.warn(\"[onedollarstats] Running in non-browser environment. Returning no-op instance.\");\n      return new AnalyticsTracker(userConfig); // Fresh no-op instance for SSR\n    }\n\n    if (!AnalyticsTracker.instance) {\n      AnalyticsTracker.instance = new AnalyticsTracker(userConfig);\n    }\n    return AnalyticsTracker.instance;\n  }\n\n  private constructor(userConfig: AnalyticsConfig = {}) {\n    this.config = { ...defaultConfig, ...userConfig };\n\n    // Skip setup in non-client environments\n    if (!isClient()) return;\n\n    // Auto-start autocollect\n    if (this.config.autocollect) this.setupAutocollect();\n  }\n\n  private async sendWithBeaconOrFetch(stringifiedBody: string): Promise<void> {\n    // First fallback: try sendBeacon\n    if (navigator.sendBeacon?.(this.config.collectorUrl, stringifiedBody)) return;\n\n    // Second fallback: use fetch() with keepalive\n    fetch(this.config.collectorUrl, {\n      method: \"POST\",\n      body: stringifiedBody,\n      headers: { \"Content-Type\": \"application/json\" },\n      keepalive: true\n    }).catch((err: Error) => console.error(\"[onedollarstats] fetch() failed:\", err.message));\n  }\n\n  // Handles localhost replacement, referrer, UTM parameters, and debug mode.\n  // Uses img beacon then `navigator.sendBeacon` if available, otherwise falls back to `fetch`.\n  private async send(data: Event): Promise<void> {\n    const { isLocalhost, isHeadlessBrowser } = getEnvironment();\n    if ((isLocalhost && !this.config.trackLocalhostAs) || isHeadlessBrowser) return;\n\n    const urlToSend = new URL(location.href);\n\n    // Determine debug mode and handle localhost replacement\n    let isDebug: boolean = false;\n    if (isLocalhost && this.config.trackLocalhostAs && urlToSend.hostname !== this.config.trackLocalhostAs) {\n      isDebug = true;\n      urlToSend.hostname = this.config.trackLocalhostAs;\n    }\n\n    // Clean query string unless UTM is explicitly provided\n    urlToSend.search = \"\";\n    if (data.path) urlToSend.pathname = data.path;\n\n    const cleanUrl = urlToSend.href.replace(/\\/$/, \"\");\n\n    // Determine referrer\n    let referrer: string | undefined = data.referrer;\n    try {\n      if (!referrer && document.referrer && document.referrer !== \"null\") {\n        const referrerURL = new URL(document.referrer);\n        if (referrerURL.hostname !== urlToSend.hostname) referrer = referrerURL.href;\n      }\n    } catch {} // ignore malformed referrer\n\n    // Build request body\n    const body: BodyToSend = {\n      u: cleanUrl,\n      e: [\n        {\n          t: data.type,\n          h: this.config.hashRouting,\n          r: referrer,\n          p: data.props\n        }\n      ]\n    };\n\n    if (data.utm && Object.keys(data.utm).length > 0) body.qs = data.utm;\n    if (isDebug) body.debug = true;\n\n    // Prepare the event payload\n    const stringifiedBody = JSON.stringify(body);\n    // Encode for safe inclusion in query string using Base64\n    const payloadBase64 = btoa(stringifiedBody);\n\n    const safeGetThreshold = 1500; // limit for query-string-containing URLs\n    const tryImageBeacon = payloadBase64.length <= safeGetThreshold;\n\n    if (tryImageBeacon) {\n      // Send via image beacon\n      const img = new Image(1, 1);\n\n      // If loading image fails (server unavailable, blocked, etc.)\n      img.onerror = () => {\n        this.sendWithBeaconOrFetch(stringifiedBody).catch((err) => console.error(\"[onedollarstats] fallback failed:\", err?.message || err));\n      };\n\n      // Primary attempt: send data via image beacon (GET request with query string)\n      img.src = `${this.config.collectorUrl}?data=${payloadBase64}`;\n    }\n\n    await this.sendWithBeaconOrFetch(stringifiedBody);\n  }\n\n  // Prevents duplicate pageviews and respects include/exclude page rules. Automatically parses UTM parameters from URL.\n  private trackPageView({ path, props }: ViewArguments, checkBlock: boolean = false) {\n    if (!isClient()) return;\n\n    const cleanPath = path || location.pathname;\n\n    // Skip duplicate pageviews or excluded pages\n    if (!this.config.hashRouting && this.lastPage === cleanPath) return;\n\n    // Skip page if checkBlock is true and the path should be excluded\n    if (checkBlock && !shouldTrackPath(cleanPath, this.config)) return;\n\n    this.lastPage = cleanPath;\n\n    const utm = parseUtmParams(new URLSearchParams(location.search));\n    this.send({ type: \"PageView\", path: cleanPath, props, utm });\n  }\n\n  /**\n   * Tracks a custom event.\n   * Can accept path string or a props object.\n   *\n   * @param eventName Name of the event to track.\n   * @param pathOrProps Optional path string or props object.\n   * @param props Optional props object if path string is provided.\n   */\n  public async event(eventName: string, pathOrProps?: string | BaseProps, props?: BaseProps) {\n    if (!isClient()) return;\n\n    const { isLocalhost, isHeadlessBrowser } = getEnvironment();\n    if ((isLocalhost && !this.config.trackLocalhostAs) || isHeadlessBrowser) return;\n\n    const args: ViewArguments = {};\n    if (typeof pathOrProps === \"string\") {\n      args.path = pathOrProps;\n      args.props = props;\n    } else if (typeof pathOrProps === \"object\") args.props = pathOrProps;\n\n    this.send({ type: eventName, ...args });\n  }\n\n  /**\n   * Records a page view.\n   * Can accept path string or a props object.\n   *\n   * @param pathOrProps Optional path string or props object.\n   * @param props Optional props when first arg is a path string.\n   */\n  public async view(pathOrProps?: string | BaseProps, props?: BaseProps) {\n    if (!isClient()) return;\n\n    const args: ViewArguments = {};\n\n    if (typeof pathOrProps === \"string\") {\n      args.path = pathOrProps;\n      args.props = props;\n    } else if (typeof pathOrProps === \"object\") {\n      args.props = pathOrProps;\n    }\n\n    this.trackPageView(args);\n  }\n\n  /**\n   * Installs global DOM/window listeners exactly once for:\n   *  - visibilitychange\n   *  - history.pushState\n   *  - popstate\n   *  - hashchange\n   *  - click autocapture for elements annotated with `data-s:event` & `data-s-event`\n   *\n   */\n  private setupAutocollect() {\n    if (!isClient() || this.autocollectSetupDone) return;\n    this.autocollectSetupDone = true;\n\n    const handlePageView = () => this.trackPageView({ path: location.pathname }, true);\n\n    // visibilitychange\n    const onVisibility = () => {\n      if (document.visibilityState === \"visible\") handlePageView();\n    };\n    document.addEventListener(\"visibilitychange\", onVisibility);\n\n    // pushState\n    const origPush = history.pushState.bind(history);\n    history.pushState = (...args) => {\n      origPush(...args);\n      requestAnimationFrame(() => {\n        handlePageView();\n      });\n    };\n\n    // popstate\n    window.addEventListener(\"popstate\", handlePageView);\n\n    // hashchange\n    window.addEventListener(\"hashchange\", handlePageView);\n\n    // click autocapture\n    const onClick: EventListener = (ev: Event) => {\n      const clickEvent = ev as MouseEvent;\n      if (clickEvent.type === \"auxclick\" && clickEvent.button !== 1) return;\n\n      const target = clickEvent.target as Element | null;\n      if (!target) return;\n\n      // Check if inside <a> or <button>\n      const insideInteractive = !!target.closest(\"a, button\");\n\n      let el: Element | null = target;\n      let depth = 0;\n\n      while (el) {\n        const eventName = el.getAttribute(\"data-s:event\") ?? el.getAttribute(\"data-s-event\");\n        if (eventName) {\n          const propsAttr = el.getAttribute(\"data-s:event-props\") ?? el.getAttribute(\"data-s-event-props\");\n          const props = propsAttr ? parseProps(propsAttr) : undefined;\n          const path = el.getAttribute(\"data-s:event-path\") || el.getAttribute(\"data-s-event-path\") || undefined;\n\n          if ((path && !shouldTrackPath(path, this.config)) || !shouldTrackPath(location.pathname, this.config)) {\n            return;\n          }\n\n          this.event(eventName, path ?? props, props);\n          return;\n        }\n\n        el = el.parentElement;\n        depth++;\n\n        // If not in <a>/<button>, stop after 3 levels\n        if (!insideInteractive && depth >= 3) break;\n      }\n    };\n\n    document.addEventListener(\"click\", onClick);\n\n    // Fire initial pageview if already visible\n    if (document.visibilityState === \"visible\") handlePageView();\n  }\n}\n\nexport const configure = (userConfig: AnalyticsConfig = {}) => {\n  AnalyticsTracker.getInstance(userConfig);\n};\n\nexport const event = async (eventName: string, pathOrProps?: string | BaseProps, props?: BaseProps) => {\n  const instance = AnalyticsTracker.getInstance();\n  await instance.event(eventName, pathOrProps, props);\n};\n\nexport const view = async (pathOrProps?: string | BaseProps, props?: BaseProps) => {\n  const instance = AnalyticsTracker.getInstance();\n  await instance.view(pathOrProps, props);\n};\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/types.d.ts

@@ -0,0 +1,34 @@
+type UtmParams = Record<string, string | string[]>;
+export type BaseProps = Record<string, string>;
+type MinimizedEvent = {
+    t: string;
+    h?: boolean;
+    r?: string;
+    p?: BaseProps;
+};
+export type Event = {
+    type: string;
+    path?: string;
+    props?: BaseProps;
+    utm?: UtmParams;
+    referrer?: string;
+};
+export type BodyToSend = {
+    u: string;
+    e: [MinimizedEvent];
+    qs?: UtmParams;
+    debug?: boolean;
+};
+export type ViewArguments = {
+    path?: string;
+    props?: BaseProps;
+};
+export type AnalyticsConfig = {
+    collectorUrl?: string;
+    trackLocalhostAs?: string | null;
+    hashRouting?: boolean;
+    autocollect?: boolean;
+    excludePages?: string[];
+    includePages?: string[];
+};
+export {};

package/dist/utils/environment.d.ts

@@ -0,0 +1,5 @@
+export declare const getEnvironment: () => {
+    isLocalhost: boolean;
+    isHeadlessBrowser: boolean;
+};
+export declare const isClient: () => boolean;

package/dist/utils/parse-utm-params.d.ts

@@ -0,0 +1 @@
+export declare const parseUtmParams: (urlSearchParams: URLSearchParams) => Record<string, string | string[]>;

package/dist/utils/props-parser.d.ts

@@ -0,0 +1 @@
+export declare const parseProps: (propsString: string) => Record<string, string> | undefined;

package/dist/utils/should-track.d.ts

@@ -0,0 +1,2 @@
+import type { AnalyticsConfig } from "../types";
+export declare const shouldTrackPath: (path: string, config: Required<AnalyticsConfig>) => boolean;

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "onedollarstats",
+  "version": "0.0.1",
+  "description": "A lightweight, zero-dependency analytics tracker for frontend apps",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc --emitDeclarationOnly && esbuild src/index.ts --bundle --outfile=dist/index.js --platform=browser --format=esm --target=es2020 --sourcemap"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "analytics",
+    "tracking",
+    "lightweight",
+    "zero-dependency",
+    "javascript",
+    "typescript",
+    "events",
+    "onedollarstats"
+  ],
+  "author": "",
+  "license": "MIT",
+  "packageManager": "pnpm@10.16.1",
+  "devDependencies": {
+    "esbuild": "^0.25.10",
+    "typescript": "^5.9.2"
+  }
+}