@funelr/events 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 json
+
+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,163 @@
+# @funelr/events
+
+Official JavaScript/TypeScript SDK for [funelr.io](https://funelr.io) — event tracking with batching, consent management, and automatic session handling.
+
+## Introduction
+
+`@funelr/events` sends analytics events from browser applications to the funelr.io ingest API. Key characteristics:
+
+- **Consent-first** — no data is collected until `setConsent(true)` is called
+- **Batched delivery** — events are queued in memory and flushed by threshold, timer, or page lifecycle hooks
+- **Resilient transport** — `sendBeacon` is preferred on page unload; `fetch` with exponential-backoff retry handles the rest
+- **Zero config for sessions** — visitor and session identifiers are generated automatically via `crypto.randomUUID()` once consent is granted
+
+## Requirements
+
+- Node.js ≥ 22 (build / server-side usage)
+- A modern browser with `crypto.randomUUID`, `sessionStorage`, and `fetch`
+
+## Setup
+
+```bash
+npm install @funelr/events
+```
+
+### Basic initialisation
+
+```ts
+import { createFunnelClient } from "@funelr/events"
+
+const client = createFunnelClient({
+  apiKey: "fjs_live_abc123",
+  endpoint: "https://ingest.funelr.io/v1/collect",
+  consent: true, // or call client.setConsent(true) after cookie banner
+})
+```
+
+### With deferred consent
+
+```ts
+const client = createFunnelClient({
+  apiKey: "fjs_live_abc123",
+  endpoint: "https://ingest.funelr.io/v1/collect",
+  // consent defaults to false — nothing is tracked yet
+})
+
+// later, once the user accepts the cookie banner:
+client.setConsent(true)
+```
+
+## Usage
+
+### Tracking events
+
+```ts
+client.track("page_view")
+client.track("cta_click", { label: "Get started", position: "hero" })
+```
+
+`track()` is a no-op when:
+- consent has not been granted
+- `allowedEventNames` is configured and `eventName` is not in the list
+
+### Consent management
+
+```ts
+// grant
+client.setConsent(true)
+
+// revoke — flushes nothing, clears queue and stored IDs
+client.setConsent(false)
+```
+
+### Reading identifiers
+
+```ts
+const sessionId   = client.getSessionId()   // scoped to the current tab (sessionStorage)
+const anonymousId = client.getAnonymousId() // persistent across sessions (localStorage)
+```
+
+Both return `undefined` when consent has not been granted or the storage API is unavailable (e.g. SSR).
+
+### Manual flush and teardown
+
+```ts
+// send all queued events immediately
+client.flush()
+
+// flush, stop the timer, and remove page-lifecycle listeners
+client.destroy()
+```
+
+Call `destroy()` when unmounting a SPA layout or in framework cleanup hooks.
+
+### Configuration reference
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `endpoint` | `string` | — | Base URL of the ingest API (**required**) |
+| `apiKey` | `string` | — | API key sent as `X-Api-Key` header |
+| `consent` | `boolean` | `false` | Initial consent state |
+| `allowedEventNames` | `readonly string[]` | — | Allowlist — unknown names are silently dropped |
+| `batchSize` | `number` | `20` | Queue length that triggers an automatic flush |
+| `flushInterval` | `number` | `5000` | Periodic flush interval in milliseconds |
+| `maxRetries` | `number` | `3` | Retry attempts on network errors or 5xx responses |
+| `sessionStorageKey` | `string` | `"funnel_session_id"` | Custom key for `sessionStorage` |
+| `anonymousIdStorageKey` | `string` | `"funnel_anonymous_id"` | Custom key for `localStorage` |
+
+## Server-side payload validation
+
+The Zod schema is exported for use in API routes or test assertions:
+
+```ts
+import { eventPayloadSchema } from "@funelr/events"
+
+const result = eventPayloadSchema.safeParse(req.body)
+if (!result.success) {
+  return res.status(400).json(result.error)
+}
+```
+
+## Standalone utilities
+
+Session and validation helpers can be used independently of `createFunnelClient`:
+
+```ts
+import {
+  getOrCreateSessionId,
+  getOrCreateAnonymousId,
+  clearSessionId,
+  clearAnonymousId,
+  isValidUUID,
+  isAllowedEventName,
+} from "@funelr/events"
+```
+
+## Source structure
+
+```
+src/
+├── client.ts       # createFunnelClient — public API, batching, consent gate
+├── transport.ts    # sendBatch — fetch + sendBeacon + retry logic
+├── session.ts      # getOrCreateSessionId / getOrCreateAnonymousId
+├── validation.ts   # isValidUUID, isAllowedEventName
+├── schemas.ts      # Zod schema (eventPayloadSchema) and EventPayload type
+├── types.ts        # TypeScript types for Stats & Analytics API responses
+├── constants.ts    # SDK_VERSION, field length limits, UUID_V4_REGEX
+└── index.ts        # public re-exports
+```
+
+## Development
+
+```bash
+npm run build        # compile to dist/
+npm run typecheck    # tsc --noEmit
+npm run test         # vitest run
+npm run test:watch   # vitest (watch mode)
+npm run lint         # biome check
+npm run lint:fix     # biome check --write
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,116 @@
+/** Configuration options for {@link createFunnelClient}. */
+export interface FunnelClientConfig {
+    /**
+     * Base URL of the ingest endpoint.
+     *
+     * @example "https://ingest.funelr.io/v1/collect"
+     */
+    endpoint: string;
+    /**
+     * API key for the project. Events are sent as a batch to `{endpoint}/batch`
+     * with an `X-Api-Key` header.
+     */
+    apiKey?: string;
+    /**
+     * Optional allowlist of accepted event names. Events whose name is not
+     * present in this list are silently dropped. When omitted, all names are
+     * accepted.
+     */
+    allowedEventNames?: readonly string[];
+    /**
+     * Initial consent state. No data is collected until consent is `true`.
+     *
+     * @defaultValue `false`
+     */
+    consent?: boolean;
+    /**
+     * Custom `sessionStorage` key for the session identifier.
+     *
+     * @defaultValue `"funnel_session_id"`
+     */
+    sessionStorageKey?: string;
+    /**
+     * Custom `localStorage` key for the anonymous visitor identifier.
+     *
+     * @defaultValue `"funnel_anonymous_id"`
+     */
+    anonymousIdStorageKey?: string;
+    /**
+     * Number of queued events that triggers an automatic flush.
+     *
+     * @defaultValue `20`
+     */
+    batchSize?: number;
+    /**
+     * Interval in milliseconds between automatic flushes while events are queued.
+     *
+     * @defaultValue `5000`
+     */
+    flushInterval?: number;
+    /**
+     * Maximum retry attempts on network errors or 5xx responses.
+     *
+     * @defaultValue `3`
+     */
+    maxRetries?: number;
+}
+/** Public interface returned by {@link createFunnelClient}. */
+export interface FunnelClient {
+    /**
+     * Records an event in the internal queue.
+     *
+     * The event is flushed automatically when the batch threshold or flush
+     * interval is reached, or when `flush()` is called explicitly. This method
+     * is a no-op when consent has not been granted or when `eventName` is not
+     * in the configured `allowedEventNames` list.
+     */
+    track(eventName: string, properties?: Record<string, unknown>): void;
+    /**
+     * Returns the current session ID, or `undefined` if consent has not been
+     * granted or `sessionStorage` is unavailable.
+     */
+    getSessionId(): string | undefined;
+    /**
+     * Returns the persistent anonymous visitor ID, or `undefined` if consent
+     * has not been granted or `localStorage` is unavailable.
+     */
+    getAnonymousId(): string | undefined;
+    /**
+     * Updates the consent state at runtime.
+     *
+     * When consent is revoked (`false`), all queued events are discarded, the
+     * flush timer is stopped, and all locally stored identifiers are removed.
+     */
+    setConsent(given: boolean): void;
+    /** Immediately sends all queued events to the ingest endpoint. */
+    flush(): void;
+    /**
+     * Flushes remaining events, stops the flush timer, and removes the
+     * page-lifecycle event listeners registered by this client instance.
+     */
+    destroy(): void;
+}
+/**
+ * Creates a new {@link FunnelClient} instance.
+ *
+ * The client batches events in memory and flushes them to the configured
+ * ingest endpoint when the batch size threshold is reached, on a periodic
+ * interval, or when `flush()` is called explicitly. In browser environments
+ * the client also flushes on `beforeunload` and when the tab is hidden.
+ *
+ * Event collection is disabled by default. Pass `consent: true` or call
+ * `setConsent(true)` after the user grants permission before tracking events.
+ *
+ * @example
+ * ```ts
+ * const client = createFunnelClient({
+ *   apiKey: "fjs_live_abc123",
+ *   endpoint: "https://ingest.funelr.io/v1/collect",
+ *   consent: true,
+ * })
+ *
+ * client.track("page_view", { path: "/home" })
+ * ```
+ */
+export declare function createFunnelClient(config: FunnelClientConfig): FunnelClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAUA,4DAA4D;AAC5D,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAEhB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAErC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IAEjB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAE9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAEpE;;;OAGG;IACH,YAAY,IAAI,MAAM,GAAG,SAAS,CAAA;IAElC;;;OAGG;IACH,cAAc,IAAI,MAAM,GAAG,SAAS,CAAA;IAEpC;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;IAEhC,kEAAkE;IAClE,KAAK,IAAI,IAAI,CAAA;IAEb;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAyG3E"}

package/dist/client.js

@@ -0,0 +1,123 @@
+import { SDK_VERSION } from "./constants.js";
+import { clearAnonymousId, clearSessionId, getOrCreateAnonymousId, getOrCreateSessionId, } from "./session.js";
+import { sendBatch } from "./transport.js";
+/**
+ * Creates a new {@link FunnelClient} instance.
+ *
+ * The client batches events in memory and flushes them to the configured
+ * ingest endpoint when the batch size threshold is reached, on a periodic
+ * interval, or when `flush()` is called explicitly. In browser environments
+ * the client also flushes on `beforeunload` and when the tab is hidden.
+ *
+ * Event collection is disabled by default. Pass `consent: true` or call
+ * `setConsent(true)` after the user grants permission before tracking events.
+ *
+ * @example
+ * ```ts
+ * const client = createFunnelClient({
+ *   apiKey: "fjs_live_abc123",
+ *   endpoint: "https://ingest.funelr.io/v1/collect",
+ *   consent: true,
+ * })
+ *
+ * client.track("page_view", { path: "/home" })
+ * ```
+ */
+export function createFunnelClient(config) {
+    try {
+        new URL(config.endpoint);
+    }
+    catch {
+        throw new Error(`[FunnelClient] Invalid endpoint URL: "${config.endpoint}"`);
+    }
+    let consentGiven = config.consent ?? false;
+    const batchSize = config.batchSize ?? 20;
+    const flushInterval = config.flushInterval ?? 5000;
+    const maxRetries = config.maxRetries ?? 3;
+    const queue = [];
+    let flushTimer;
+    function startTimer() {
+        if (flushTimer !== undefined)
+            return;
+        flushTimer = setInterval(flush, flushInterval);
+    }
+    function stopTimer() {
+        if (flushTimer !== undefined) {
+            clearInterval(flushTimer);
+            flushTimer = undefined;
+        }
+    }
+    function flush() {
+        if (queue.length === 0)
+            return;
+        const batch = queue.splice(0, queue.length);
+        sendBatch({
+            endpoint: config.endpoint,
+            events: batch,
+            ...(config.apiKey !== undefined ? { apiKey: config.apiKey } : {}),
+            maxRetries,
+        });
+    }
+    function getAnonymousId() {
+        if (!consentGiven)
+            return undefined;
+        return getOrCreateAnonymousId(config.anonymousIdStorageKey);
+    }
+    function getSessionId() {
+        if (!consentGiven)
+            return undefined;
+        return getOrCreateSessionId(config.sessionStorageKey);
+    }
+    function track(eventName, properties) {
+        if (!consentGiven)
+            return;
+        if (config.allowedEventNames && !config.allowedEventNames.includes(eventName))
+            return;
+        const anonymousId = getAnonymousId();
+        const sessionId = getSessionId();
+        const url = typeof location !== "undefined" ? location.href : undefined;
+        const referrer = typeof document !== "undefined" ? document.referrer || undefined : undefined;
+        const payload = {
+            eventName,
+            timestamp: new Date().toISOString(),
+            sdkVersion: SDK_VERSION,
+            ...(anonymousId !== undefined ? { anonymousId } : {}),
+            ...(sessionId !== undefined ? { sessionId } : {}),
+            ...(url !== undefined ? { url } : {}),
+            ...(referrer !== undefined ? { referrer } : {}),
+            ...(properties !== undefined ? { properties } : {}),
+        };
+        queue.push(payload);
+        startTimer();
+        if (queue.length >= batchSize) {
+            flush();
+        }
+    }
+    function setConsent(given) {
+        consentGiven = given;
+        if (!given) {
+            clearSessionId(config.sessionStorageKey);
+            clearAnonymousId(config.anonymousIdStorageKey);
+            queue.splice(0, queue.length);
+            stopTimer();
+        }
+    }
+    function onVisibilityChange() {
+        if (document.visibilityState === "hidden")
+            flush();
+    }
+    function destroy() {
+        flush();
+        stopTimer();
+        if (typeof window !== "undefined") {
+            window.removeEventListener("beforeunload", flush);
+            window.removeEventListener("visibilitychange", onVisibilityChange);
+        }
+    }
+    if (typeof window !== "undefined") {
+        window.addEventListener("beforeunload", flush);
+        window.addEventListener("visibilitychange", onVisibilityChange);
+    }
+    return { track, getSessionId, getAnonymousId, setConsent, flush, destroy };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/constants.d.ts

@@ -0,0 +1,11 @@
+/** Current version of the SDK, injected into every event payload. */
+export declare const SDK_VERSION = "0.4.0";
+/** Maximum allowed length for event names. */
+export declare const EVENT_NAME_MAX_LENGTH = 100;
+/** Maximum allowed length for session and anonymous identifier fields. */
+export declare const SESSION_ID_MAX_LENGTH = 64;
+/** Maximum allowed length for URL and referrer fields. */
+export declare const URL_MAX_LENGTH = 2048;
+/** Regular expression that matches a UUID v4 string. */
+export declare const UUID_V4_REGEX: RegExp;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,eAAO,MAAM,WAAW,UAAU,CAAA;AAElC,8CAA8C;AAC9C,eAAO,MAAM,qBAAqB,MAAM,CAAA;AAExC,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,KAAK,CAAA;AAEvC,0DAA0D;AAC1D,eAAO,MAAM,cAAc,OAAO,CAAA;AAElC,wDAAwD;AACxD,eAAO,MAAM,aAAa,QACgD,CAAA"}

package/dist/constants.js

@@ -0,0 +1,11 @@
+/** Current version of the SDK, injected into every event payload. */
+export const SDK_VERSION = "0.4.0";
+/** Maximum allowed length for event names. */
+export const EVENT_NAME_MAX_LENGTH = 100;
+/** Maximum allowed length for session and anonymous identifier fields. */
+export const SESSION_ID_MAX_LENGTH = 64;
+/** Maximum allowed length for URL and referrer fields. */
+export const URL_MAX_LENGTH = 2048;
+/** Regular expression that matches a UUID v4 string. */
+export const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAA;AAElC,8CAA8C;AAC9C,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAA;AAExC,0EAA0E;AAC1E,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAA;AAEvC,0DAA0D;AAC1D,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAA;AAElC,wDAAwD;AACxD,MAAM,CAAC,MAAM,aAAa,GACxB,wEAAwE,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createFunnelClient, type FunnelClient, type FunnelClientConfig } from "./client.js";
+export { EVENT_NAME_MAX_LENGTH, SDK_VERSION, SESSION_ID_MAX_LENGTH, URL_MAX_LENGTH, UUID_V4_REGEX, } from "./constants.js";
+export { type EventPayload, eventPayloadSchema } from "./schemas.js";
+export type { FunnelConfig, FunnelStatsResponse, FunnelStep, FunnelStepStat, FunnelSummaryResponse, PropertyBreakdownItem, RawEvent, RawEventsResponse, SessionEvent, TopEventStat, TrendDataPoint, TrendsResponse, } from "./types.js";
+export { clearAnonymousId, clearSessionId, getOrCreateAnonymousId, getOrCreateSessionId, } from "./session.js";
+export { isAllowedEventName, isValidUUID } from "./validation.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,kBAAkB,EAAE,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAC5F,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,qBAAqB,EACrB,cAAc,EACd,aAAa,GACd,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,KAAK,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACpE,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,QAAQ,EACR,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,cAAc,GACf,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createFunnelClient } from "./client.js";
+export { EVENT_NAME_MAX_LENGTH, SDK_VERSION, SESSION_ID_MAX_LENGTH, URL_MAX_LENGTH, UUID_V4_REGEX, } from "./constants.js";
+export { eventPayloadSchema } from "./schemas.js";
+export { clearAnonymousId, clearSessionId, getOrCreateAnonymousId, getOrCreateSessionId, } from "./session.js";
+export { isAllowedEventName, isValidUUID } from "./validation.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,kBAAkB,EAA8C,MAAM,aAAa,CAAA;AAC5F,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,qBAAqB,EACrB,cAAc,EACd,aAAa,GACd,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAqB,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAepE,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/schemas.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+/**
+ * Zod schema for validating an ingest event payload.
+ *
+ * Mirrors the server-side contract accepted by `POST /v1/collect/batch`.
+ * Use this schema on the server or in tests to assert payload correctness.
+ */
+export declare const eventPayloadSchema: z.ZodObject<{
+    /** Name of the event, e.g. `"page_view"` or `"cta_click"`. */
+    eventName: z.ZodString;
+    /** Persistent visitor identifier stored in `localStorage` (post-consent). */
+    anonymousId: z.ZodOptional<z.ZodString>;
+    /** Session-scoped identifier stored in `sessionStorage`. */
+    sessionId: z.ZodOptional<z.ZodString>;
+    /** Full URL of the page where the event occurred. */
+    url: z.ZodOptional<z.ZodString>;
+    /** HTTP referrer. An empty string is accepted when no referrer is present. */
+    referrer: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    /** Arbitrary key/value properties attached to the event. */
+    properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** ISO 8601 timestamp recorded on the client at the time of the event. */
+    timestamp: z.ZodOptional<z.ZodString>;
+    /** Version string of the SDK that produced this payload, e.g. `"0.3.0"`. */
+    sdkVersion: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    eventName: string;
+    anonymousId?: string | undefined;
+    sessionId?: string | undefined;
+    url?: string | undefined;
+    referrer?: string | undefined;
+    properties?: Record<string, unknown> | undefined;
+    timestamp?: string | undefined;
+    sdkVersion?: string | undefined;
+}, {
+    eventName: string;
+    anonymousId?: string | undefined;
+    sessionId?: string | undefined;
+    url?: string | undefined;
+    referrer?: string | undefined;
+    properties?: Record<string, unknown> | undefined;
+    timestamp?: string | undefined;
+    sdkVersion?: string | undefined;
+}>;
+/** Ingest event payload — the unit of data sent to `POST /v1/collect/batch`. */
+export type EventPayload = z.infer<typeof eventPayloadSchema>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;IAC7B,8DAA8D;;IAE9D,6EAA6E;;IAE7E,4DAA4D;;IAE5D,qDAAqD;;IAErD,8EAA8E;;IAE9E,4DAA4D;;IAE5D,0EAA0E;;IAE1E,4EAA4E;;;;;;;;;;;;;;;;;;;;EAE5E,CAAA;AAEF,gFAAgF;AAChF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA"}

package/dist/schemas.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { EVENT_NAME_MAX_LENGTH, SESSION_ID_MAX_LENGTH, URL_MAX_LENGTH } from "./constants.js";
+/**
+ * Zod schema for validating an ingest event payload.
+ *
+ * Mirrors the server-side contract accepted by `POST /v1/collect/batch`.
+ * Use this schema on the server or in tests to assert payload correctness.
+ */
+export const eventPayloadSchema = z.object({
+    /** Name of the event, e.g. `"page_view"` or `"cta_click"`. */
+    eventName: z.string().min(1).max(EVENT_NAME_MAX_LENGTH),
+    /** Persistent visitor identifier stored in `localStorage` (post-consent). */
+    anonymousId: z.string().min(1).max(SESSION_ID_MAX_LENGTH).optional(),
+    /** Session-scoped identifier stored in `sessionStorage`. */
+    sessionId: z.string().max(SESSION_ID_MAX_LENGTH).optional(),
+    /** Full URL of the page where the event occurred. */
+    url: z.string().url().max(URL_MAX_LENGTH).optional(),
+    /** HTTP referrer. An empty string is accepted when no referrer is present. */
+    referrer: z.string().url().max(URL_MAX_LENGTH).optional().or(z.literal("")),
+    /** Arbitrary key/value properties attached to the event. */
+    properties: z.record(z.string(), z.unknown()).optional(),
+    /** ISO 8601 timestamp recorded on the client at the time of the event. */
+    timestamp: z.string().datetime().optional(),
+    /** Version string of the SDK that produced this payload, e.g. `"0.3.0"`. */
+    sdkVersion: z.string().optional(),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAE7F;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,8DAA8D;IAC9D,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,qBAAqB,CAAC;IACvD,6EAA6E;IAC7E,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC,QAAQ,EAAE;IACpE,4DAA4D;IAC5D,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC,QAAQ,EAAE;IAC3D,qDAAqD;IACrD,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE;IACpD,8EAA8E;IAC9E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC3E,4DAA4D;IAC5D,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IACxD,0EAA0E;IAC1E,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC3C,4EAA4E;IAC5E,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAA"}

package/dist/session.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Returns the session ID stored under `key`, creating and persisting a new
+ * UUID v4 if none exists. Returns `undefined` when called outside a browser
+ * context (e.g. SSR).
+ *
+ * The ID is scoped to the current browser tab via `sessionStorage` and is
+ * cleared automatically when the tab is closed.
+ */
+export declare function getOrCreateSessionId(key?: string): string | undefined;
+/**
+ * Removes the session ID from `sessionStorage`.
+ *
+ * Call this when the user revokes tracking consent.
+ */
+export declare function clearSessionId(key?: string): void;
+/**
+ * Returns the persistent anonymous visitor ID stored under `key`, creating
+ * and persisting a new UUID v4 if none exists. Returns `undefined` outside a
+ * browser context or when `localStorage` is unavailable.
+ *
+ * The ID is stored in `localStorage` and persists across sessions.
+ * It must only be created after the user has granted consent.
+ */
+export declare function getOrCreateAnonymousId(key?: string): string | undefined;
+/**
+ * Removes the anonymous visitor ID from `localStorage`.
+ *
+ * Call this when the user revokes tracking consent.
+ */
+export declare function clearAnonymousId(key?: string): void;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AASA;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUrE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAGjD;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUvE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAGnD"}

package/dist/session.js

@@ -0,0 +1,64 @@
+const DEFAULT_SESSION_KEY = "funnel_session_id";
+const DEFAULT_ANONYMOUS_KEY = "funnel_anonymous_id";
+function isBrowser() {
+    return (typeof globalThis.crypto !== "undefined" && typeof globalThis.sessionStorage !== "undefined");
+}
+/**
+ * Returns the session ID stored under `key`, creating and persisting a new
+ * UUID v4 if none exists. Returns `undefined` when called outside a browser
+ * context (e.g. SSR).
+ *
+ * The ID is scoped to the current browser tab via `sessionStorage` and is
+ * cleared automatically when the tab is closed.
+ */
+export function getOrCreateSessionId(key) {
+    if (!isBrowser())
+        return undefined;
+    const storageKey = key ?? DEFAULT_SESSION_KEY;
+    const existing = sessionStorage.getItem(storageKey);
+    if (existing)
+        return existing;
+    const id = crypto.randomUUID();
+    sessionStorage.setItem(storageKey, id);
+    return id;
+}
+/**
+ * Removes the session ID from `sessionStorage`.
+ *
+ * Call this when the user revokes tracking consent.
+ */
+export function clearSessionId(key) {
+    if (!isBrowser())
+        return;
+    sessionStorage.removeItem(key ?? DEFAULT_SESSION_KEY);
+}
+/**
+ * Returns the persistent anonymous visitor ID stored under `key`, creating
+ * and persisting a new UUID v4 if none exists. Returns `undefined` outside a
+ * browser context or when `localStorage` is unavailable.
+ *
+ * The ID is stored in `localStorage` and persists across sessions.
+ * It must only be created after the user has granted consent.
+ */
+export function getOrCreateAnonymousId(key) {
+    if (!isBrowser() || typeof localStorage === "undefined")
+        return undefined;
+    const storageKey = key ?? DEFAULT_ANONYMOUS_KEY;
+    const existing = localStorage.getItem(storageKey);
+    if (existing)
+        return existing;
+    const id = crypto.randomUUID();
+    localStorage.setItem(storageKey, id);
+    return id;
+}
+/**
+ * Removes the anonymous visitor ID from `localStorage`.
+ *
+ * Call this when the user revokes tracking consent.
+ */
+export function clearAnonymousId(key) {
+    if (!isBrowser() || typeof localStorage === "undefined")
+        return;
+    localStorage.removeItem(key ?? DEFAULT_ANONYMOUS_KEY);
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,MAAM,mBAAmB,GAAG,mBAAmB,CAAA;AAC/C,MAAM,qBAAqB,GAAG,qBAAqB,CAAA;AAEnD,SAAS,SAAS;IAChB,OAAO,CACL,OAAO,UAAU,CAAC,MAAM,KAAK,WAAW,IAAI,OAAO,UAAU,CAAC,cAAc,KAAK,WAAW,CAC7F,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAY;IAC/C,IAAI,CAAC,SAAS,EAAE;QAAE,OAAO,SAAS,CAAA;IAElC,MAAM,UAAU,GAAG,GAAG,IAAI,mBAAmB,CAAA;IAC7C,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAA;IACnD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAA;IAE7B,MAAM,EAAE,GAAG,MAAM,CAAC,UAAU,EAAE,CAAA;IAC9B,cAAc,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAA;IACtC,OAAO,EAAE,CAAA;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,IAAI,CAAC,SAAS,EAAE;QAAE,OAAM;IACxB,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,mBAAmB,CAAC,CAAA;AACvD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAY;IACjD,IAAI,CAAC,SAAS,EAAE,IAAI,OAAO,YAAY,KAAK,WAAW;QAAE,OAAO,SAAS,CAAA;IAEzE,MAAM,UAAU,GAAG,GAAG,IAAI,qBAAqB,CAAA;IAC/C,MAAM,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,UAAU,CAAC,CAAA;IACjD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAA;IAE7B,MAAM,EAAE,GAAG,MAAM,CAAC,UAAU,EAAE,CAAA;IAC9B,YAAY,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAA;IACpC,OAAO,EAAE,CAAA;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,IAAI,CAAC,SAAS,EAAE,IAAI,OAAO,YAAY,KAAK,WAAW;QAAE,OAAM;IAC/D,YAAY,CAAC,UAAU,CAAC,GAAG,IAAI,qBAAqB,CAAC,CAAA;AACvD,CAAC"}

package/dist/transport.d.ts

@@ -0,0 +1,23 @@
+import type { EventPayload } from "./schemas.js";
+/** Options for {@link sendBatch}. */
+export interface BatchSendOptions {
+    /** Base endpoint URL, e.g. `"https://ingest.funelr.io/v1/collect"`. */
+    endpoint: string;
+    /** Events to deliver. */
+    events: EventPayload[];
+    /** API key sent as the `X-Api-Key` request header. */
+    apiKey?: string;
+    /** Maximum retry attempts on network errors or 5xx responses. Defaults to `3`. */
+    maxRetries?: number;
+}
+/**
+ * Sends a batch of events to `{endpoint}/batch` via `POST`.
+ *
+ * For single-event flushes the function attempts `navigator.sendBeacon` first
+ * to guarantee delivery during page unload. Multi-event batches fall back to
+ * `fetch` with exponential-backoff retries on network errors and 5xx responses.
+ *
+ * Delivery failures are intentionally silent — event tracking is best-effort.
+ */
+export declare function sendBatch({ endpoint, events, apiKey, maxRetries }: BatchSendOptions): void;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAEhD,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAA;IAChB,yBAAyB;IACzB,MAAM,EAAE,YAAY,EAAE,CAAA;IACtB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AA4BD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAc,EAAE,EAAE,gBAAgB,GAAG,IAAI,CAe9F"}

package/dist/transport.js

@@ -0,0 +1,43 @@
+function backoff(attempt) {
+    return new Promise((resolve) => setTimeout(resolve, Math.min(1000 * 2 ** attempt, 30_000)));
+}
+async function sendWithRetry(endpoint, body, headers, maxRetries, attempt = 0) {
+    try {
+        const res = await fetch(endpoint, { method: "POST", headers, body, keepalive: true });
+        if (!res.ok && res.status >= 500 && attempt < maxRetries) {
+            await backoff(attempt);
+            return sendWithRetry(endpoint, body, headers, maxRetries, attempt + 1);
+        }
+    }
+    catch {
+        if (attempt < maxRetries) {
+            await backoff(attempt);
+            return sendWithRetry(endpoint, body, headers, maxRetries, attempt + 1);
+        }
+    }
+}
+/**
+ * Sends a batch of events to `{endpoint}/batch` via `POST`.
+ *
+ * For single-event flushes the function attempts `navigator.sendBeacon` first
+ * to guarantee delivery during page unload. Multi-event batches fall back to
+ * `fetch` with exponential-backoff retries on network errors and 5xx responses.
+ *
+ * Delivery failures are intentionally silent — event tracking is best-effort.
+ */
+export function sendBatch({ endpoint, events, apiKey, maxRetries = 3 }) {
+    if (events.length === 0)
+        return;
+    const body = JSON.stringify({ events });
+    const headers = { "Content-Type": "application/json" };
+    if (apiKey)
+        headers["X-Api-Key"] = apiKey;
+    const batchEndpoint = `${endpoint}/batch`;
+    if (events.length === 1 && typeof navigator?.sendBeacon === "function") {
+        const blob = new Blob([body], { type: "application/json" });
+        if (navigator.sendBeacon(batchEndpoint, blob))
+            return;
+    }
+    sendWithRetry(batchEndpoint, body, headers, maxRetries).catch(() => { });
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAeA,SAAS,OAAO,CAAC,OAAe;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;AAC7F,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,QAAgB,EAChB,IAAY,EACZ,OAA+B,EAC/B,UAAkB,EAClB,OAAO,GAAG,CAAC;IAEX,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACrF,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;YACzD,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;YACtB,OAAO,aAAa,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,GAAG,CAAC,CAAC,CAAA;QACxE,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;YACzB,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;YACtB,OAAO,aAAa,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,GAAG,CAAC,CAAC,CAAA;QACxE,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,CAAC,EAAoB;IACtF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAM;IAE/B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;IACvC,MAAM,OAAO,GAA2B,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAA;IAC9E,IAAI,MAAM;QAAE,OAAO,CAAC,WAAW,CAAC,GAAG,MAAM,CAAA;IAEzC,MAAM,aAAa,GAAG,GAAG,QAAQ,QAAQ,CAAA;IAEzC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,SAAS,EAAE,UAAU,KAAK,UAAU,EAAE,CAAC;QACvE,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAAC,CAAA;QAC3D,IAAI,SAAS,CAAC,UAAU,CAAC,aAAa,EAAE,IAAI,CAAC;YAAE,OAAM;IACvD,CAAC;IAED,aAAa,CAAC,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;AACzE,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,96 @@
+/** A single step in a funnel definition. */
+export interface FunnelStep {
+    /** Event name that represents reaching this step. */
+    eventName: string;
+    /** Human-readable label shown in the dashboard. */
+    label: string;
+}
+/** Configuration for a funnel, as returned by the funelr.io API. */
+export interface FunnelConfig {
+    /** UUID of the project this funnel belongs to. */
+    siteId: string;
+    /** Ordered list of steps that define the funnel. */
+    steps: FunnelStep[];
+}
+/** Response from `GET /v1/stats/:projectId/summary`. */
+export interface FunnelSummaryResponse {
+    /** Start of the requested period (ISO 8601). */
+    from: string;
+    /** End of the requested period (ISO 8601). */
+    to: string;
+    /** Number of unique `anonymous_id` values observed in the period. */
+    visitors: number;
+    /** Total event count keyed by `event_name`. */
+    eventTotals: Record<string, number>;
+}
+/** A single step entry within a {@link FunnelStatsResponse}. */
+export interface FunnelStepStat {
+    step_order: number;
+    name: string;
+    event_name: string;
+    users_reached: number;
+    /** Conversion rate relative to the first step, or `null` for the first step itself. */
+    conversion_from_first: number | null;
+    /** Conversion rate relative to the previous step, or `null` for the first step. */
+    conversion_from_prev: number | null;
+}
+/** Response from `GET /v1/stats/:projectId/funnels/:funnelId`. */
+export interface FunnelStatsResponse {
+    funnelId: string;
+    funnelName: string;
+    from: string;
+    to: string;
+    overallConversionRate: number;
+    steps: FunnelStepStat[];
+}
+/** A single time-series data point within a {@link TrendsResponse}. */
+export interface TrendDataPoint {
+    /** Bucket start time (ISO 8601). */
+    bucket: string;
+    event_count: number;
+    unique_visitors: number;
+}
+/** Response from `GET /v1/stats/:projectId/trends`. */
+export interface TrendsResponse {
+    series: Array<{
+        eventName: string;
+        data: TrendDataPoint[];
+    }>;
+}
+/** A single row from `GET /analytics/:projectId/events/top`. */
+export interface TopEventStat {
+    event_name: string;
+    total_count: number;
+    unique_visitors: number;
+}
+/** A single row from `GET /analytics/:projectId/property-breakdown`. */
+export interface PropertyBreakdownItem {
+    value: string;
+    count: number;
+}
+/** A single event record from `GET /analytics/:projectId/raw-events`. */
+export interface RawEvent {
+    id: string;
+    event_name: string;
+    anonymous_id: string;
+    properties: Record<string, unknown> | null;
+    server_received_at: string;
+}
+/** Response from `GET /analytics/:projectId/raw-events`. */
+export interface RawEventsResponse {
+    events: RawEvent[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/** A single event record from `GET /analytics/:projectId/sessions/:anonymousId/events`. */
+export interface SessionEvent {
+    id: string;
+    event_name: string;
+    properties: Record<string, unknown> | null;
+    url: string | null;
+    referrer: string | null;
+    server_received_at: string;
+    client_sent_at: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,6 @@
+// ---------------------------------------------------------------------------
+// Convention: nullable fields in API response types use `null` (mirrors JSON).
+// Optional fields in request/config types use `undefined` (TypeScript idiom).
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAC9E,8EAA8E"}

package/dist/validation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns `true` when `value` is a well-formed UUID v4 string.
+ *
+ * @example
+ * isValidUUID("550e8400-e29b-41d4-a716-446655440000") // true
+ * isValidUUID("not-a-uuid")                           // false
+ */
+export declare function isValidUUID(value: string): boolean;
+/**
+ * Returns `true` when `name` is a non-empty string within the allowed length
+ * and, if `allowedNames` is provided, is present in that allowlist.
+ *
+ * @example
+ * isAllowedEventName("page_view")                        // true (no allowlist)
+ * isAllowedEventName("page_view", ["page_view", "click"]) // true
+ * isAllowedEventName("unknown",   ["page_view", "click"]) // false
+ */
+export declare function isAllowedEventName(name: string, allowedNames?: readonly string[]): boolean;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAI1F"}

package/dist/validation.js

@@ -0,0 +1,28 @@
+import { EVENT_NAME_MAX_LENGTH, UUID_V4_REGEX } from "./constants.js";
+/**
+ * Returns `true` when `value` is a well-formed UUID v4 string.
+ *
+ * @example
+ * isValidUUID("550e8400-e29b-41d4-a716-446655440000") // true
+ * isValidUUID("not-a-uuid")                           // false
+ */
+export function isValidUUID(value) {
+    return UUID_V4_REGEX.test(value);
+}
+/**
+ * Returns `true` when `name` is a non-empty string within the allowed length
+ * and, if `allowedNames` is provided, is present in that allowlist.
+ *
+ * @example
+ * isAllowedEventName("page_view")                        // true (no allowlist)
+ * isAllowedEventName("page_view", ["page_view", "click"]) // true
+ * isAllowedEventName("unknown",   ["page_view", "click"]) // false
+ */
+export function isAllowedEventName(name, allowedNames) {
+    if (name.length === 0 || name.length > EVENT_NAME_MAX_LENGTH)
+        return false;
+    if (!allowedNames)
+        return true;
+    return allowedNames.includes(name);
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAErE;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AAClC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,YAAgC;IAC/E,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,qBAAqB;QAAE,OAAO,KAAK,CAAA;IAC1E,IAAI,CAAC,YAAY;QAAE,OAAO,IAAI,CAAA;IAC9B,OAAO,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;AACpC,CAAC"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@funelr/events",
+  "version": "0.4.0",
+  "description": "Official event tracking SDK for funelr.io",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "jsdom": "^28.1.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/funelr/events-sdk.git"
+  },
+  "keywords": [
+    "analytics",
+    "funnel",
+    "tracking",
+    "events",
+    "sdk"
+  ],
+  "license": "MIT"
+}