npm - @clamp-sh/analytics - Versions diffs - 0.1.0 - Mend

@clamp-sh/analytics 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,260 @@
+# @clamp-sh/analytics
+Analytics SDK for [Clamp](https://clamp.sh), agentic analytics your coding agent can read, query, and act on. Track pageviews, custom events, and server-side actions. No cookies, no personal data collected, no consent banner required.
+## Install
+```bash
+npm install @clamp-sh/analytics
+```
+## Browser
+```ts
+import { init, track, getAnonymousId } from "@clamp-sh/analytics"
+init("proj_xxx")
+// Custom events
+track("signup", { plan: "pro" })
+// Get visitor ID (for linking server-side events)
+const anonId = getAnonymousId()
+```
+After `init()`, pageviews are tracked automatically, including SPA navigations.
+## React
+```tsx
+import { Analytics } from "@clamp-sh/analytics/react"
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics projectId="proj_xxx" />
+      </body>
+    </html>
+  )
+}
+```
+Add to your root layout. Pageviews are tracked automatically. Use `track()` from `@clamp-sh/analytics` anywhere in your app for custom events.
+## Server
+```ts
+import { init, track } from "@clamp-sh/analytics/server"
+init({ projectId: "proj_xxx", apiKey: "sk_proj_..." })
+await track("account_created", {
+  anonymousId: "anon_abc123",
+  properties: { plan: "pro" },
+})
+```
+Server events require an API key (found in your project settings).
+## Script tag
+```html
+<script src="https://cdn.clamp.sh/v1.js"></script>
+<script>
+  clamp.init("proj_xxx")
+</script>
+```
+## Custom events
+Track any action with `track(name, properties)`. Properties are flat string key-value pairs.
+```ts
+import { track } from "@clamp-sh/analytics"
+track("signup", { plan: "pro", source: "pricing_page" })
+track("feature_used", { name: "csv_export" })
+track("invite_sent", { role: "editor", team: "acme" })
+```
+On the server:
+```ts
+import { track } from "@clamp-sh/analytics/server"
+await track("subscription_created", {
+  anonymousId: "anon_abc123",
+  properties: { plan: "pro", interval: "monthly" },
+})
+```
+Pageviews are tracked automatically. Everything else goes through `track()`.
+## Typed events
+Define your event map once and get autocomplete and type checking across your app. Zero runtime cost.
+```ts
+type Events = {
+  signup: { plan: string; source: string }
+  purchase: { amount: string; currency: string }
+  feature_used: { name: string }
+  invite_sent: { role: string }
+}
+init<Events>("proj_xxx")
+track("signup", { plan: "pro", source: "homepage" })   // autocomplete
+track("signup", { wrong: "field" })                     // type error
+track("unknown_event")                                  // type error
+```
+Works the same way with the server SDK:
+```ts
+import { init, track } from "@clamp-sh/analytics/server"
+init<Events>({ projectId: "proj_xxx", apiKey: "sk_proj_..." })
+await track("purchase", {
+  properties: { amount: "49", currency: "usd" },
+})
+```
+## Properties limits
+Event properties are flat `string → string` maps. Nested objects, arrays, and non-string values are rejected.
+| Constraint     | Limit    |
+| -------------- | -------- |
+| Max keys       | 20       |
+| Key length     | 128 chars |
+| Value length   | 512 chars |
+| Payload size   | 64 KB    |
+## Examples
+### Track signups with plan info
+```ts
+track("signup", { plan: "pro", source: "pricing_page" })
+```
+### Track feature usage
+```ts
+track("feature_used", { name: "csv_export" })
+```
+### Track button clicks
+```tsx
+<button onClick={() => track("cta_clicked", { label: "Get started", page: "/pricing" })}>
+  Get started
+</button>
+```
+### Link browser visitor to server events
+Pass the anonymous ID from the browser to your API, then include it in server-side events to connect the two.
+```ts
+// Browser: send anonymous ID with your API call
+const anonId = getAnonymousId()
+await fetch("/api/checkout", {
+  method: "POST",
+  body: JSON.stringify({ plan: "pro", anonId }),
+})
+```
+```ts
+// Server: include it in the event
+await track("checkout_completed", {
+  anonymousId: req.body.anonId,
+  properties: { plan: "pro", amount: "49" },
+})
+```
+### Track form submissions
+```tsx
+function ContactForm() {
+  const handleSubmit = (e: FormEvent) => {
+    e.preventDefault()
+    track("form_submitted", { form: "contact", page: location.pathname })
+  }
+  return <form onSubmit={handleSubmit}>...</form>
+}
+```
+### Next.js App Router
+```tsx
+// app/layout.tsx
+import { Analytics } from "@clamp-sh/analytics/react"
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics projectId="proj_xxx" />
+      </body>
+    </html>
+  )
+}
+// app/pricing/page.tsx (client component)
+"use client"
+import { track } from "@clamp-sh/analytics"
+export default function Pricing() {
+  return (
+    <button onClick={() => track("plan_selected", { plan: "growth" })}>
+      Choose Growth
+    </button>
+  )
+}
+```
+### Next.js Server Actions
+```ts
+// app/actions.ts
+"use server"
+import { track } from "@clamp-sh/analytics/server"
+export async function createTeam(name: string, anonId: string) {
+  const team = await db.teams.create({ name })
+  await track("team_created", {
+    anonymousId: anonId,
+    properties: { team_id: team.id },
+  })
+  return team
+}
+```
+### Express / Node.js backend
+```ts
+import express from "express"
+import { init, track } from "@clamp-sh/analytics/server"
+init({ projectId: "proj_xxx", apiKey: "sk_proj_..." })
+const app = express()
+app.post("/api/subscribe", async (req, res) => {
+  await track("subscription_started", {
+    anonymousId: req.body.anonId,
+    properties: { plan: req.body.plan },
+  })
+  res.json({ ok: true })
+})
+```
+## License
+MIT

package/dist/index.d.mts ADDED Viewed

@@ -0,0 +1,21 @@
+import { E as EventMap, A as AnyEvents } from './types-Bc30ZeCx.mjs';
+/**
+ * Initialize the browser SDK. Call once at app startup.
+ * Starts auto-pageview tracking, session management, and batching.
+ */
+declare function init<_E extends EventMap = AnyEvents>(projectId: string, opts?: {
+    endpoint?: string;
+}): void;
+/**
+ * Track a custom event. Fire-and-forget; events are batched and sent every 5s.
+ * If called before init(), events are buffered and flushed when init() runs.
+ */
+declare function track<E extends EventMap = AnyEvents, K extends keyof E & string = string>(name: K, properties?: E[K] extends Record<string, string> ? E[K] : Record<string, string>): void;
+/**
+ * Get the anonymous visitor ID (persisted in localStorage).
+ * Pass this to your server so server-side events can be linked to the visitor.
+ */
+declare function getAnonymousId(): string | null;
+export { AnyEvents, EventMap, getAnonymousId, init, track };

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,21 @@
+import { E as EventMap, A as AnyEvents } from './types-Bc30ZeCx.js';
+/**
+ * Initialize the browser SDK. Call once at app startup.
+ * Starts auto-pageview tracking, session management, and batching.
+ */
+declare function init<_E extends EventMap = AnyEvents>(projectId: string, opts?: {
+    endpoint?: string;
+}): void;
+/**
+ * Track a custom event. Fire-and-forget; events are batched and sent every 5s.
+ * If called before init(), events are buffered and flushed when init() runs.
+ */
+declare function track<E extends EventMap = AnyEvents, K extends keyof E & string = string>(name: K, properties?: E[K] extends Record<string, string> ? E[K] : Record<string, string>): void;
+/**
+ * Get the anonymous visitor ID (persisted in localStorage).
+ * Pass this to your server so server-side events can be linked to the visitor.
+ */
+declare function getAnonymousId(): string | null;
+export { AnyEvents, EventMap, getAnonymousId, init, track };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,139 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  getAnonymousId: () => getAnonymousId,
+  init: () => init,
+  track: () => track
+});
+module.exports = __toCommonJS(src_exports);
+var DEFAULT_ENDPOINT = "https://api.clamp.sh";
+var BrowserClient = class {
+  constructor() {
+    this.projectId = null;
+    this.endpoint = DEFAULT_ENDPOINT;
+    this.sessionId = null;
+    this.anonymousId = null;
+    this.queue = [];
+    this.preInitQueue = [];
+    this.timer = null;
+    this.initialized = false;
+  }
+  init(projectId, opts) {
+    if (typeof window === "undefined") return;
+    this.projectId = projectId;
+    if (opts?.endpoint) this.endpoint = opts.endpoint;
+    this.initialized = true;
+    this.sessionId = sessionStorage.getItem("clamp_sid") ?? this.newId("ses");
+    sessionStorage.setItem("clamp_sid", this.sessionId);
+    this.anonymousId = localStorage.getItem("clamp_aid") ?? this.newId("anon");
+    localStorage.setItem("clamp_aid", this.anonymousId);
+    for (const e of this.preInitQueue) {
+      this.track(e.name, e.props);
+    }
+    this.preInitQueue = [];
+    this.pageview();
+    const origPushState = history.pushState.bind(history);
+    const origReplaceState = history.replaceState.bind(history);
+    history.pushState = (...args) => {
+      origPushState(...args);
+      this.pageview();
+    };
+    history.replaceState = (...args) => {
+      origReplaceState(...args);
+      this.pageview();
+    };
+    window.addEventListener("popstate", () => this.pageview());
+    this.timer = setInterval(() => this.flush(), 5e3);
+    const onHide = () => this.flush(true);
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") onHide();
+    });
+    window.addEventListener("pagehide", onHide);
+  }
+  track(name, properties) {
+    if (!this.initialized) {
+      this.preInitQueue.push({ name, props: properties });
+      return;
+    }
+    const event = {
+      name,
+      url: location.href,
+      referrer: document.referrer,
+      sessionId: this.sessionId,
+      anonymousId: this.anonymousId,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      screenWidth: window.innerWidth,
+      screenHeight: window.innerHeight,
+      language: navigator.language,
+      platform: "web",
+      properties
+    };
+    this.queue.push(event);
+  }
+  getAnonymousId() {
+    return this.anonymousId;
+  }
+  // ── Private ─────────────────────────────────────────────────────────
+  pageview() {
+    this.track("pageview");
+  }
+  flush(useBeacon = false) {
+    if (!this.projectId || this.queue.length === 0) return;
+    const events = this.queue.splice(0, 100);
+    const payload = { p: this.projectId, events };
+    const url = `${this.endpoint}/e/batch`;
+    const body = JSON.stringify(payload);
+    if (useBeacon && typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(url, body);
+    } else {
+      fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body,
+        keepalive: true
+      }).catch(() => {
+      });
+    }
+    if (this.queue.length > 0) this.flush(useBeacon);
+  }
+  newId(prefix) {
+    const rand = Math.random().toString(36).slice(2, 10);
+    const ts = Date.now().toString(36);
+    return `${prefix}_${ts}${rand}`;
+  }
+};
+var client = new BrowserClient();
+function init(projectId, opts) {
+  client.init(projectId, opts);
+}
+function track(name, properties) {
+  client.track(name, properties);
+}
+function getAnonymousId() {
+  return client.getAnonymousId();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getAnonymousId,
+  init,
+  track
+});

package/dist/index.mjs ADDED Viewed

@@ -0,0 +1,112 @@
+// src/index.ts
+var DEFAULT_ENDPOINT = "https://api.clamp.sh";
+var BrowserClient = class {
+  constructor() {
+    this.projectId = null;
+    this.endpoint = DEFAULT_ENDPOINT;
+    this.sessionId = null;
+    this.anonymousId = null;
+    this.queue = [];
+    this.preInitQueue = [];
+    this.timer = null;
+    this.initialized = false;
+  }
+  init(projectId, opts) {
+    if (typeof window === "undefined") return;
+    this.projectId = projectId;
+    if (opts?.endpoint) this.endpoint = opts.endpoint;
+    this.initialized = true;
+    this.sessionId = sessionStorage.getItem("clamp_sid") ?? this.newId("ses");
+    sessionStorage.setItem("clamp_sid", this.sessionId);
+    this.anonymousId = localStorage.getItem("clamp_aid") ?? this.newId("anon");
+    localStorage.setItem("clamp_aid", this.anonymousId);
+    for (const e of this.preInitQueue) {
+      this.track(e.name, e.props);
+    }
+    this.preInitQueue = [];
+    this.pageview();
+    const origPushState = history.pushState.bind(history);
+    const origReplaceState = history.replaceState.bind(history);
+    history.pushState = (...args) => {
+      origPushState(...args);
+      this.pageview();
+    };
+    history.replaceState = (...args) => {
+      origReplaceState(...args);
+      this.pageview();
+    };
+    window.addEventListener("popstate", () => this.pageview());
+    this.timer = setInterval(() => this.flush(), 5e3);
+    const onHide = () => this.flush(true);
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") onHide();
+    });
+    window.addEventListener("pagehide", onHide);
+  }
+  track(name, properties) {
+    if (!this.initialized) {
+      this.preInitQueue.push({ name, props: properties });
+      return;
+    }
+    const event = {
+      name,
+      url: location.href,
+      referrer: document.referrer,
+      sessionId: this.sessionId,
+      anonymousId: this.anonymousId,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      screenWidth: window.innerWidth,
+      screenHeight: window.innerHeight,
+      language: navigator.language,
+      platform: "web",
+      properties
+    };
+    this.queue.push(event);
+  }
+  getAnonymousId() {
+    return this.anonymousId;
+  }
+  // ── Private ─────────────────────────────────────────────────────────
+  pageview() {
+    this.track("pageview");
+  }
+  flush(useBeacon = false) {
+    if (!this.projectId || this.queue.length === 0) return;
+    const events = this.queue.splice(0, 100);
+    const payload = { p: this.projectId, events };
+    const url = `${this.endpoint}/e/batch`;
+    const body = JSON.stringify(payload);
+    if (useBeacon && typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(url, body);
+    } else {
+      fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body,
+        keepalive: true
+      }).catch(() => {
+      });
+    }
+    if (this.queue.length > 0) this.flush(useBeacon);
+  }
+  newId(prefix) {
+    const rand = Math.random().toString(36).slice(2, 10);
+    const ts = Date.now().toString(36);
+    return `${prefix}_${ts}${rand}`;
+  }
+};
+var client = new BrowserClient();
+function init(projectId, opts) {
+  client.init(projectId, opts);
+}
+function track(name, properties) {
+  client.track(name, properties);
+}
+function getAnonymousId() {
+  return client.getAnonymousId();
+}
+export {
+  getAnonymousId,
+  init,
+  track
+};

package/dist/react.d.mts ADDED Viewed

@@ -0,0 +1,16 @@
+interface AnalyticsProps {
+    projectId: string;
+    endpoint?: string;
+}
+/**
+ * Drop-in React component. Add to your root layout to start tracking.
+ * Calls init() in useEffect, renders nothing.
+ *
+ * ```tsx
+ * import { Analytics } from "@clamp-sh/analytics/react"
+ * <Analytics projectId="proj_xxx" />
+ * ```
+ */
+declare function Analytics({ projectId, endpoint }: AnalyticsProps): null;
+export { Analytics, type AnalyticsProps };

package/dist/react.d.ts ADDED Viewed

@@ -0,0 +1,16 @@
+interface AnalyticsProps {
+    projectId: string;
+    endpoint?: string;
+}
+/**
+ * Drop-in React component. Add to your root layout to start tracking.
+ * Calls init() in useEffect, renders nothing.
+ *
+ * ```tsx
+ * import { Analytics } from "@clamp-sh/analytics/react"
+ * <Analytics projectId="proj_xxx" />
+ * ```
+ */
+declare function Analytics({ projectId, endpoint }: AnalyticsProps): null;
+export { Analytics, type AnalyticsProps };

package/dist/react.js ADDED Viewed

@@ -0,0 +1,141 @@
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+// src/react.tsx
+var react_exports = {};
+__export(react_exports, {
+  Analytics: () => Analytics
+});
+module.exports = __toCommonJS(react_exports);
+var import_react = require("react");
+// src/index.ts
+var DEFAULT_ENDPOINT = "https://api.clamp.sh";
+var BrowserClient = class {
+  constructor() {
+    this.projectId = null;
+    this.endpoint = DEFAULT_ENDPOINT;
+    this.sessionId = null;
+    this.anonymousId = null;
+    this.queue = [];
+    this.preInitQueue = [];
+    this.timer = null;
+    this.initialized = false;
+  }
+  init(projectId, opts) {
+    if (typeof window === "undefined") return;
+    this.projectId = projectId;
+    if (opts?.endpoint) this.endpoint = opts.endpoint;
+    this.initialized = true;
+    this.sessionId = sessionStorage.getItem("clamp_sid") ?? this.newId("ses");
+    sessionStorage.setItem("clamp_sid", this.sessionId);
+    this.anonymousId = localStorage.getItem("clamp_aid") ?? this.newId("anon");
+    localStorage.setItem("clamp_aid", this.anonymousId);
+    for (const e of this.preInitQueue) {
+      this.track(e.name, e.props);
+    }
+    this.preInitQueue = [];
+    this.pageview();
+    const origPushState = history.pushState.bind(history);
+    const origReplaceState = history.replaceState.bind(history);
+    history.pushState = (...args) => {
+      origPushState(...args);
+      this.pageview();
+    };
+    history.replaceState = (...args) => {
+      origReplaceState(...args);
+      this.pageview();
+    };
+    window.addEventListener("popstate", () => this.pageview());
+    this.timer = setInterval(() => this.flush(), 5e3);
+    const onHide = () => this.flush(true);
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") onHide();
+    });
+    window.addEventListener("pagehide", onHide);
+  }
+  track(name, properties) {
+    if (!this.initialized) {
+      this.preInitQueue.push({ name, props: properties });
+      return;
+    }
+    const event = {
+      name,
+      url: location.href,
+      referrer: document.referrer,
+      sessionId: this.sessionId,
+      anonymousId: this.anonymousId,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      screenWidth: window.innerWidth,
+      screenHeight: window.innerHeight,
+      language: navigator.language,
+      platform: "web",
+      properties
+    };
+    this.queue.push(event);
+  }
+  getAnonymousId() {
+    return this.anonymousId;
+  }
+  // ── Private ─────────────────────────────────────────────────────────
+  pageview() {
+    this.track("pageview");
+  }
+  flush(useBeacon = false) {
+    if (!this.projectId || this.queue.length === 0) return;
+    const events = this.queue.splice(0, 100);
+    const payload = { p: this.projectId, events };
+    const url = `${this.endpoint}/e/batch`;
+    const body = JSON.stringify(payload);
+    if (useBeacon && typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(url, body);
+    } else {
+      fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body,
+        keepalive: true
+      }).catch(() => {
+      });
+    }
+    if (this.queue.length > 0) this.flush(useBeacon);
+  }
+  newId(prefix) {
+    const rand = Math.random().toString(36).slice(2, 10);
+    const ts = Date.now().toString(36);
+    return `${prefix}_${ts}${rand}`;
+  }
+};
+var client = new BrowserClient();
+function init(projectId, opts) {
+  client.init(projectId, opts);
+}
+// src/react.tsx
+function Analytics({ projectId, endpoint }) {
+  (0, import_react.useEffect)(() => {
+    init(projectId, { endpoint });
+  }, [projectId, endpoint]);
+  return null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Analytics
+});

package/dist/react.mjs ADDED Viewed

@@ -0,0 +1,117 @@
+"use client";
+// src/react.tsx
+import { useEffect } from "react";
+// src/index.ts
+var DEFAULT_ENDPOINT = "https://api.clamp.sh";
+var BrowserClient = class {
+  constructor() {
+    this.projectId = null;
+    this.endpoint = DEFAULT_ENDPOINT;
+    this.sessionId = null;
+    this.anonymousId = null;
+    this.queue = [];
+    this.preInitQueue = [];
+    this.timer = null;
+    this.initialized = false;
+  }
+  init(projectId, opts) {
+    if (typeof window === "undefined") return;
+    this.projectId = projectId;
+    if (opts?.endpoint) this.endpoint = opts.endpoint;
+    this.initialized = true;
+    this.sessionId = sessionStorage.getItem("clamp_sid") ?? this.newId("ses");
+    sessionStorage.setItem("clamp_sid", this.sessionId);
+    this.anonymousId = localStorage.getItem("clamp_aid") ?? this.newId("anon");
+    localStorage.setItem("clamp_aid", this.anonymousId);
+    for (const e of this.preInitQueue) {
+      this.track(e.name, e.props);
+    }
+    this.preInitQueue = [];
+    this.pageview();
+    const origPushState = history.pushState.bind(history);
+    const origReplaceState = history.replaceState.bind(history);
+    history.pushState = (...args) => {
+      origPushState(...args);
+      this.pageview();
+    };
+    history.replaceState = (...args) => {
+      origReplaceState(...args);
+      this.pageview();
+    };
+    window.addEventListener("popstate", () => this.pageview());
+    this.timer = setInterval(() => this.flush(), 5e3);
+    const onHide = () => this.flush(true);
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") onHide();
+    });
+    window.addEventListener("pagehide", onHide);
+  }
+  track(name, properties) {
+    if (!this.initialized) {
+      this.preInitQueue.push({ name, props: properties });
+      return;
+    }
+    const event = {
+      name,
+      url: location.href,
+      referrer: document.referrer,
+      sessionId: this.sessionId,
+      anonymousId: this.anonymousId,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      screenWidth: window.innerWidth,
+      screenHeight: window.innerHeight,
+      language: navigator.language,
+      platform: "web",
+      properties
+    };
+    this.queue.push(event);
+  }
+  getAnonymousId() {
+    return this.anonymousId;
+  }
+  // ── Private ─────────────────────────────────────────────────────────
+  pageview() {
+    this.track("pageview");
+  }
+  flush(useBeacon = false) {
+    if (!this.projectId || this.queue.length === 0) return;
+    const events = this.queue.splice(0, 100);
+    const payload = { p: this.projectId, events };
+    const url = `${this.endpoint}/e/batch`;
+    const body = JSON.stringify(payload);
+    if (useBeacon && typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(url, body);
+    } else {
+      fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body,
+        keepalive: true
+      }).catch(() => {
+      });
+    }
+    if (this.queue.length > 0) this.flush(useBeacon);
+  }
+  newId(prefix) {
+    const rand = Math.random().toString(36).slice(2, 10);
+    const ts = Date.now().toString(36);
+    return `${prefix}_${ts}${rand}`;
+  }
+};
+var client = new BrowserClient();
+function init(projectId, opts) {
+  client.init(projectId, opts);
+}
+// src/react.tsx
+function Analytics({ projectId, endpoint }) {
+  useEffect(() => {
+    init(projectId, { endpoint });
+  }, [projectId, endpoint]);
+  return null;
+}
+export {
+  Analytics
+};

package/dist/server.d.mts ADDED Viewed

@@ -0,0 +1,24 @@
+import { E as EventMap, A as AnyEvents } from './types-Bc30ZeCx.mjs';
+/**
+ * Initialize the server SDK. Call once at server startup.
+ * Requires a project API key (found in project settings).
+ */
+declare function init<_E extends EventMap = AnyEvents>(config: {
+    projectId: string;
+    apiKey: string;
+    endpoint?: string;
+}): void;
+/**
+ * Track a server-side event. Returns a promise that resolves when the event is sent.
+ * Accepts an optional anonymousId to link to a browser visitor.
+ */
+declare function track<E extends EventMap = AnyEvents, K extends keyof E & string = string>(name: K, opts?: {
+    anonymousId?: string;
+    properties?: E[K] extends Record<string, string> ? E[K] : Record<string, string>;
+    timestamp?: string;
+}): Promise<{
+    ok: boolean;
+}>;
+export { AnyEvents, EventMap, init, track };

package/dist/server.d.ts ADDED Viewed

@@ -0,0 +1,24 @@
+import { E as EventMap, A as AnyEvents } from './types-Bc30ZeCx.js';
+/**
+ * Initialize the server SDK. Call once at server startup.
+ * Requires a project API key (found in project settings).
+ */
+declare function init<_E extends EventMap = AnyEvents>(config: {
+    projectId: string;
+    apiKey: string;
+    endpoint?: string;
+}): void;
+/**
+ * Track a server-side event. Returns a promise that resolves when the event is sent.
+ * Accepts an optional anonymousId to link to a browser visitor.
+ */
+declare function track<E extends EventMap = AnyEvents, K extends keyof E & string = string>(name: K, opts?: {
+    anonymousId?: string;
+    properties?: E[K] extends Record<string, string> ? E[K] : Record<string, string>;
+    timestamp?: string;
+}): Promise<{
+    ok: boolean;
+}>;
+export { AnyEvents, EventMap, init, track };

package/dist/server.js ADDED Viewed

@@ -0,0 +1,78 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+// src/server.ts
+var server_exports = {};
+__export(server_exports, {
+  init: () => init,
+  track: () => track
+});
+module.exports = __toCommonJS(server_exports);
+var DEFAULT_ENDPOINT = "https://api.clamp.sh";
+var ServerClient = class {
+  constructor() {
+    this.projectId = null;
+    this.apiKey = null;
+    this.endpoint = DEFAULT_ENDPOINT;
+    this.initialized = false;
+  }
+  init(config) {
+    this.projectId = config.projectId;
+    this.apiKey = config.apiKey;
+    if (config.endpoint) this.endpoint = config.endpoint;
+    this.initialized = true;
+  }
+  async track(name, opts) {
+    if (!this.initialized || !this.projectId || !this.apiKey) {
+      throw new Error("@clamp-sh/analytics/server: call init() before track()");
+    }
+    const payload = {
+      p: this.projectId,
+      name,
+      anonymousId: opts?.anonymousId,
+      properties: opts?.properties,
+      timestamp: opts?.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const res = await fetch(`${this.endpoint}/e/s`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-clamp-key": this.apiKey
+      },
+      body: JSON.stringify(payload)
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`@clamp-sh/analytics/server: ${res.status} ${body}`);
+    }
+    return { ok: true };
+  }
+};
+var client = new ServerClient();
+function init(config) {
+  client.init(config);
+}
+async function track(name, opts) {
+  return client.track(name, opts);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  init,
+  track
+});

package/dist/server.mjs ADDED Viewed

@@ -0,0 +1,52 @@
+// src/server.ts
+var DEFAULT_ENDPOINT = "https://api.clamp.sh";
+var ServerClient = class {
+  constructor() {
+    this.projectId = null;
+    this.apiKey = null;
+    this.endpoint = DEFAULT_ENDPOINT;
+    this.initialized = false;
+  }
+  init(config) {
+    this.projectId = config.projectId;
+    this.apiKey = config.apiKey;
+    if (config.endpoint) this.endpoint = config.endpoint;
+    this.initialized = true;
+  }
+  async track(name, opts) {
+    if (!this.initialized || !this.projectId || !this.apiKey) {
+      throw new Error("@clamp-sh/analytics/server: call init() before track()");
+    }
+    const payload = {
+      p: this.projectId,
+      name,
+      anonymousId: opts?.anonymousId,
+      properties: opts?.properties,
+      timestamp: opts?.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const res = await fetch(`${this.endpoint}/e/s`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-clamp-key": this.apiKey
+      },
+      body: JSON.stringify(payload)
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`@clamp-sh/analytics/server: ${res.status} ${body}`);
+    }
+    return { ok: true };
+  }
+};
+var client = new ServerClient();
+function init(config) {
+  client.init(config);
+}
+async function track(name, opts) {
+  return client.track(name, opts);
+}
+export {
+  init,
+  track
+};

package/dist/types-Bc30ZeCx.d.mts ADDED Viewed

@@ -0,0 +1,6 @@
+/** Typed event map for generics. Keys = event names, values = property shapes. */
+type EventMap = Record<string, Record<string, string> | undefined>;
+/** Default event map (no type checking on event names). */
+type AnyEvents = Record<string, Record<string, string> | undefined>;
+export type { AnyEvents as A, EventMap as E };

package/dist/types-Bc30ZeCx.d.ts ADDED Viewed

@@ -0,0 +1,6 @@
+/** Typed event map for generics. Keys = event names, values = property shapes. */
+type EventMap = Record<string, Record<string, string> | undefined>;
+/** Default event map (no type checking on event names). */
+type AnyEvents = Record<string, Record<string, string> | undefined>;
+export type { AnyEvents as A, EventMap as E };

package/package.json ADDED Viewed

@@ -0,0 +1,51 @@
+{
+  "name": "@clamp-sh/analytics",
+  "version": "0.1.0",
+  "description": "Lightweight analytics SDK for Clamp. Auto-pageviews, sessions, batching. Browser, server, and React.",
+  "license": "MIT",
+  "homepage": "https://clamp.sh",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/clamp-sh/analytics"
+  },
+  "keywords": ["analytics", "tracking", "pageviews", "sessions", "react", "nextjs"],
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.mjs",
+      "require": "./dist/server.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.mjs",
+      "require": "./dist/react.js"
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true }
+  },
+  "devDependencies": {
+    "react": "^19",
+    "@types/react": "^19",
+    "tsup": "^8",
+    "typescript": "^5"
+  }
+}