@stetcms/analytics 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,13 @@
 # @stetcms/analytics
 
-Product analytics for apps built on Stet: pageviews and your own typed events,
-routed through your backend instead of a third-party endpoint.
+[![CI](https://github.com/jamiedavenport/stet/actions/workflows/ci.yml/badge.svg)](https://github.com/jamiedavenport/stet/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-stetcms.com-black.svg)](https://docs.stetcms.com/reference/analytics)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
+
+Product analytics for apps built on [Stet](https://stetcms.com), the CMS where
+marketing owns the content model and engineering gets a typed client generated
+from it. Pageviews and your own typed events, routed through your backend
+instead of a third-party endpoint.
 
 - No cookies, so no consent banner.
 - No third-party origin in the page, so nothing for a blocker to match on.
@@ -9,6 +15,9 @@ routed through your backend instead of a third-party endpoint.
 - One tracking plan types the browser calls, validates the server ones, and
   becomes the event list your content team builds dashboards from.
 
+The [analytics guide](https://docs.stetcms.com/analytics) covers how this fits
+with the dashboards your content team builds on the same events.
+
 ## Install
 
 ```bash
@@ -18,7 +27,10 @@ npm install @stetcms/analytics
 ## 1. Declare the tracking plan
 
 The plan goes in `stet.config.ts` at the project root, the one file
-`@stetcms/vite` and the `stet` CLI read for everything. Props take any
+[`@stetcms/vite`](https://docs.stetcms.com/reference/codegen) and the
+[`stet` CLI](https://docs.stetcms.com/reference/cli) read for everything
+(see [`@stetcms/config`](https://docs.stetcms.com/reference/configuration)).
+Props take any
 [Standard Schema](https://standardschema.dev) validator, so Zod, Valibot and
 ArkType all work.
 
@@ -80,6 +92,31 @@ type fails the build. It never throws and never rejects, so a tracking mistake
 cannot break the page. Events batch and flush every two seconds, when twenty
 are queued, and when the page is hidden or unloaded.
 
+## 4. Track from your server too
+
+A signup or a subscription belongs to your backend, and recording it there is
+what stops an ad blocker or a closed tab losing it. The same client does this:
+it guards its listeners behind a `window` check, so it runs anywhere `fetch`
+does. Point it at an absolute URL and it posts to the route you already
+mounted, which keeps your key in one place.
+
+```ts
+const analytics = createAnalytics<(typeof config)['analytics']>({
+  endpoint: `${process.env.APP_URL}/api/analytics`,
+  context: { userId },
+  autoPageviews: false,
+});
+
+analytics.track('subscription.started', { plan: 'paid' });
+await analytics.flush();
+```
+
+`context` is fixed when the client is built, so build one per unit of work
+rather than let two concurrent requests stamp each other's identity on their
+events. Nothing on a server fires `pagehide`, so call `flush()` yourself; on
+Cloudflare Workers, `waitUntil(analytics.flush())` sends it without holding up
+the response.
+
 ## Pageviews
 
 On a site where every navigation is a real page load — plain HTML, Astro
@@ -95,6 +132,11 @@ knows; ask it.
 A repeated view of the same URL counts once either way, so the double-invoked
 effects of React Strict Mode do not inflate anything.
 
+Pass the router's parameterized template as `route` when it exposes one. Stet
+then groups `/blog/first` and `/blog/second` under `/blog/[slug]`. Templates
+are framework-native: `$slug`, `[slug]`, and `:slug` all work. When `route` is
+absent, Stet groups by the concrete pathname as before.
+
 ```ts
 export const analytics = createAnalytics<(typeof config)['analytics']>({
   endpoint: '/api/analytics',
@@ -114,14 +156,17 @@ every other one. Every snippet below passes it explicitly for that reason.
 ### TanStack Router
 
 ```tsx
-import { useLocation } from '@tanstack/react-router';
+import { useLocation, useRouterState } from '@tanstack/react-router';
 import { useEffect } from 'react';
 
 export function usePageviews() {
   const location = useLocation();
+  const route = useRouterState({
+    select: (state) => state.matches.at(-1)?.fullPath,
+  });
   useEffect(() => {
-    analytics.pageview(`${window.location.origin}${location.href}`);
-  }, [location.href]);
+    analytics.pageview(`${window.location.origin}${location.href}`, { route });
+  }, [location.href, route]);
 }
 ```
 
@@ -146,6 +191,8 @@ export function Pageviews() {
 
 Render it in `app/layout.tsx`. `useSearchParams` opts the subtree into client
 rendering, so wrap it in `<Suspense>` to keep the rest of the layout static.
+The App Router does not expose its route template to client components, so
+this falls back to the concrete pathname unless your app supplies one.
 
 ### React Router
 
@@ -169,7 +216,7 @@ In `+layout.svelte`:
 ```svelte
 <script>
   import { afterNavigate } from '$app/navigation';
-  afterNavigate(({ to }) => analytics.pageview(to?.url.href));
+  afterNavigate(({ to }) => analytics.pageview(to?.url.href, { route: to?.route.id ?? undefined }));
 </script>
 ```
 
@@ -180,22 +227,34 @@ In a client-only plugin, `plugins/analytics.client.ts`:
 ```ts
 export default defineNuxtPlugin(() => {
   useRouter().afterEach((to) => {
-    analytics.pageview(`${window.location.origin}${to.fullPath}`);
+    const route = to.matched.at(-1)?.path;
+    analytics.pageview(`${window.location.origin}${to.fullPath}`, { route });
   });
 });
 ```
 
 ### Astro
 
-Astro navigations are full page loads, so the default is already correct and
-there is nothing to add. With view transitions enabled the client script runs
-only once, so listen instead — and here a bare call _is_ right, because the
-event fires after the swap, when `window.location` is already the new page:
+Astro navigations are full-page loads, so the default is already correct. With
+view transitions enabled, render the current pattern and read it after each
+page swap:
 
-```ts
-document.addEventListener('astro:page-load', () => analytics.pageview());
+```astro
+<meta name="stet-route" content={Astro.routePattern} />
+
+<script>
+  import { analytics } from '../analytics';
+
+  document.addEventListener('astro:page-load', () => {
+    const route = document.querySelector('meta[name="stet-route"]')?.getAttribute('content');
+    analytics.pageview(window.location.href, { route: route ?? undefined });
+  });
+</script>
 ```
 
+Astro 5 exposes the template as `Astro.routePattern` while rendering. The meta
+element is replaced during navigation, so the listener reads the new pattern.
+
 ## Context vs metadata
 
 Two different trust models, worth keeping straight:
@@ -245,12 +304,16 @@ because a `4xx` only teaches a crawler to retry.
 ### `@stetcms/analytics/sync`
 
 `syncTrackingPlan(options)` publishes the plan to Stet. Called for you by
-`@stetcms/vite` on dev-server start and at the end of a build, and by
-`stet sync`; you rarely call it yourself.
+[`@stetcms/vite`](https://docs.stetcms.com/reference/codegen) on dev-server
+and build start, and by
+[`stet sync`](https://docs.stetcms.com/reference/cli#stet-sync); you rarely
+call it yourself.
 
 ### `@stetcms/analytics/client`
 
 `createAnalytics(options)` → `{ track, pageview, setContext, flush }`.
+`pageview(url?, options?: { route? })` keeps the concrete URL for deduplication and uses
+the optional framework route template for grouping.
 
 | Option          | Default  | Meaning                                    |
 | --------------- | -------- | ------------------------------------------ |
@@ -269,6 +332,7 @@ because a `4xx` only teaches a crawler to retry.
 | `context` | `{}`                          | Props, or a function of the request, that win over the browser's |
 | `origin`  | `STET_ORIGIN`, then the cloud | Stet deployment to forward to                                    |
 | `apiKey`  | `STET_API_KEY`                | Organization API key                                             |
+| `enabled` | whether a key resolved        | Whether to forward batches at all                                |
 | `salt`    | the request's host            | Mixed into the visitor digest                                    |
 | `onError` | `console.error`               | Called when a batch cannot be forwarded                          |
 
@@ -277,6 +341,26 @@ event that does not match the plan, `502` when Stet could not be reached. An
 event outside the plan fails loudly rather than being dropped quietly, so a
 typo surfaces the first time it runs.
 
+### Keeping development out of your analytics
+
+The same organization key generates your content client, so on a developer's
+machine it is present and real, and every page they load would otherwise land
+in the project your dashboards read. `enabled` is the switch, kept separate
+from the key for exactly that reason:
+
+```ts
+const handler = createAnalyticsHandler(plan, {
+  enabled: process.env.ANALYTICS_ENABLED !== 'false',
+});
+```
+
+Test for the off value rather than the on one, so an environment that never
+sets the variable records instead of silently dropping. A disabled handler
+answers `200 { accepted: 0 }` and still checks each batch against the plan, so
+a typo'd event is still a `400` while you are working on it. Leave it on
+locally, point `STET_ORIGIN` at a Stet of your own, and your dashboard fills up
+with your own traffic instead.
+
 ## Development
 
 ```bash
@@ -285,4 +369,9 @@ pnpm tc     # Type check
 pnpm build  # vp pack
 ```
 
-`examples/tanstack` runs this package against a local Stet; see its README.
+[`examples/tanstack`](https://github.com/jamiedavenport/stet/tree/main/examples/tanstack)
+runs this package against a local Stet; see its README.
+
+## License
+
+Apache-2.0

package/dist/client.d.ts

@@ -9,12 +9,15 @@ type AnalyticsOptions = {
   autoPageviews?: boolean; /** Override fetch, e.g. in tests. */
   fetch?: typeof globalThis.fetch;
 };
+type PageviewOptions = {
+  /** Router template for this URL, e.g. `/blog/[slug]`. */route?: string;
+};
 type Analytics<TPlan extends AnalyticsTypes> = {
   /** Record an event from the tracking plan. Never throws and never rejects. */track: <K extends keyof TPlan['$types']['events'] & string>(name: K, ...args: TrackArgs<TPlan['$types']['events'][K]>) => void; /** Record a pageview. Called for you unless `autoPageviews` is off. */
-  pageview: (url?: string) => void; /** Merge props into the context sent with every later batch. */
+  pageview: (url?: string, options?: PageviewOptions) => void; /** Merge props into the context sent with every later batch. */
   setContext: (context: Record<string, unknown>) => void; /** Send anything queued now. Resolves once the request settles. */
   flush: () => Promise<void>;
 };
 declare function createAnalytics<TPlan extends AnalyticsTypes>(options: AnalyticsOptions): Analytics<TPlan>;
 //#endregion
-export { Analytics, AnalyticsOptions, type AnalyticsTypes, createAnalytics };
+export { Analytics, AnalyticsOptions, type AnalyticsTypes, PageviewOptions, createAnalytics };

package/dist/client.js

@@ -1,4 +1,4 @@
-import { n as PAGEVIEW } from "./events-DnYdjoR6.js";
+import { o as PAGEVIEW, r as isValidRoute } from "./wire-CZwVGiU5.js";
 //#region src/client.ts
 /**
 * Browser client. Talks only to the route you mounted in your own app with
@@ -68,17 +68,19 @@ function createAnalytics(options) {
 			...envelope()
 		});
 	}
-	function pageview(url) {
+	function pageview(url, pageviewOptions) {
 		const envelopeUrl = url ?? (isBrowser ? window.location.href : void 0);
 		if (envelopeUrl !== void 0 && envelopeUrl === lastPageviewUrl) return;
 		lastPageviewUrl = envelopeUrl;
-		enqueue({
+		const event = {
 			name: PAGEVIEW,
 			props: {},
 			timestamp: Date.now(),
 			...envelope(),
 			...envelopeUrl === void 0 ? {} : { url: envelopeUrl }
-		});
+		};
+		if (isValidRoute(pageviewOptions?.route)) event.route = pageviewOptions.route;
+		enqueue(event);
 	}
 	if (isBrowser) {
 		window.addEventListener("pagehide", () => void flush());

package/dist/index.d.ts

@@ -43,7 +43,8 @@ type WireEvent = {
   name: string;
   props: Record<string, unknown>; /** Epoch milliseconds, stamped in the browser when the event happened. */
   timestamp: number;
-  url?: string;
+  url?: string; /** Router template for the URL, e.g. `/blog/[slug]`. */
+  route?: string;
   referrer?: string;
 };
 /** The body the browser client POSTs to your route. */

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as isEventDefinition, i as flattenEvents, n as PAGEVIEW, o as resolveEvent, r as event, t as BUILT_IN_EVENTS } from "./events-DnYdjoR6.js";
-import { a as formatIssues, i as defineAnalytics, n as MAX_BATCH_EVENTS, o as validateEvent, r as parseClientBatch, t as DEFAULT_ORIGIN } from "./wire-J3xnrDYj.js";
+import { a as BUILT_IN_EVENTS, c as flattenEvents, i as parseClientBatch, l as isEventDefinition, n as MAX_BATCH_EVENTS, o as PAGEVIEW, s as event, t as DEFAULT_ORIGIN, u as resolveEvent } from "./wire-CZwVGiU5.js";
+import { n as formatIssues, r as validateEvent, t as defineAnalytics } from "./plan-C6WUN0RK.js";
 import { syncTrackingPlan } from "./sync.js";
 export { BUILT_IN_EVENTS, DEFAULT_ORIGIN, MAX_BATCH_EVENTS, PAGEVIEW, defineAnalytics, event, flattenEvents, formatIssues, isEventDefinition, parseClientBatch, resolveEvent, syncTrackingPlan, validateEvent };

package/dist/plan-C6WUN0RK.js

@@ -0,0 +1,61 @@
+import { a as BUILT_IN_EVENTS, u as resolveEvent } from "./wire-CZwVGiU5.js";
+//#region src/plan.ts
+/**
+* Declares the tracking plan, conventionally in `stet.config.ts`:
+*
+* ```ts
+* export default defineAnalytics({
+*   events: {
+*     signup: event({ plan: z.enum(['free', 'paid']) }),
+*     checkout: { completed: event({ total: z.number() }) },
+*   },
+* });
+* ```
+*/
+function defineAnalytics(config) {
+	return {
+		...config,
+		$types: void 0
+	};
+}
+/**
+* Validates an event's props against the plan. Declared props are checked
+* with their own schema; undeclared props pass through, so adding a prop in
+* the browser never blocks on a deploy of the plan.
+*/
+async function validateEvent(events, name, props) {
+	if (BUILT_IN_EVENTS.has(name)) return {
+		ok: true,
+		props: props ?? {}
+	};
+	const definition = resolveEvent(events, name);
+	if (definition === void 0) return {
+		ok: false,
+		issues: [{ message: `unknown event "${name}"` }]
+	};
+	const input = props ?? {};
+	const output = { ...input };
+	const issues = [];
+	for (const [key, schema] of Object.entries(definition.props)) {
+		let result = schema["~standard"].validate(input[key]);
+		if (result instanceof Promise) result = await result;
+		if (result.issues) issues.push(...result.issues.map((issue) => ({
+			...issue,
+			message: `${key}: ${issue.message}`
+		})));
+		else output[key] = result.value;
+	}
+	if (issues.length > 0) return {
+		ok: false,
+		issues
+	};
+	return {
+		ok: true,
+		props: output
+	};
+}
+function formatIssues(issues) {
+	return issues.map((issue) => issue.message).join("; ");
+}
+//#endregion
+export { formatIssues as n, validateEvent as r, defineAnalytics as t };

package/dist/server.d.ts

@@ -11,6 +11,13 @@ type AnalyticsHandlerOptions = {
   context?: Record<string, unknown> | ((request: Request) => Record<string, unknown> | Promise<Record<string, unknown>>); /** Stet deployment. Defaults to the plan's, then `STET_ORIGIN`, then the cloud. */
   origin?: string; /** Organization API key. Defaults to the plan's, then `STET_API_KEY`. */
   apiKey?: string;
+  /**
+   * Whether to forward batches at all. Defaults to whether a key resolved, so
+   * an unconfigured deployment stays quiet rather than erroring. Set it
+   * explicitly to keep a developer's own traffic out of a project whose key is
+   * present for another reason, such as generating the content client.
+   */
+  enabled?: boolean;
   /**
    * Salt mixed into the visitor digest. Defaults to the request's host, which
    * keeps visitor ids from being comparable across sites you run.

package/dist/server.js

@@ -1,4 +1,5 @@
-import { a as formatIssues, o as validateEvent, r as parseClientBatch } from "./wire-J3xnrDYj.js";
+import { i as parseClientBatch } from "./wire-CZwVGiU5.js";
+import { n as formatIssues, r as validateEvent } from "./plan-C6WUN0RK.js";
 import { resolveStetConfig } from "@stetcms/config";
 //#region src/metadata.ts
 const BOT_PATTERN = /bot|crawl|spider|slurp|headless|lighthouse|pingdom|preview|monitor|curl|wget|python-requests|axios|node-fetch/i;
@@ -150,6 +151,7 @@ function createAnalyticsHandler(plan, options = {}) {
 			origin: options.origin,
 			apiKey: options.apiKey
 		});
+		if (!(options.enabled ?? apiKey !== void 0)) return json({ accepted: 0 });
 		if (apiKey === void 0) {
 			onError(/* @__PURE__ */ new Error("No API key. Set STET_API_KEY or pass apiKey."));
 			return json({ error: "analytics is not configured" }, 500);

package/dist/wire-CZwVGiU5.js

@@ -0,0 +1,149 @@
+import { DEFAULT_ORIGIN as DEFAULT_ORIGIN$1 } from "@stetcms/config";
+//#region src/events.ts
+/** The pageview every browser client sends. */
+const PAGEVIEW = "$pageview";
+/**
+* Events the client sends for itself. `$`-prefixed so a tracking plan can
+* never collide with one; their context (url, referrer) rides the envelope
+* rather than the props, so they carry no schema of their own.
+*/
+const BUILT_IN_EVENTS = /* @__PURE__ */ new Set([PAGEVIEW]);
+/**
+* Declares an event and the props it carries. Props are any Standard Schema
+* validator, so the schema library is yours to pick (Zod, Valibot, ArkType).
+* Events group by nesting, and nested events track under dot-joined names:
+*
+* ```ts
+* events: {
+*   signup: event({ plan: z.enum(['free', 'paid']) }),
+*   checkout: { started: event(), completed: event({ total: z.number() }) },
+* }
+* // → 'signup', 'checkout.started', 'checkout.completed'
+* ```
+*/
+function event(props) {
+	return {
+		$event: true,
+		props: props ?? {}
+	};
+}
+function isEventDefinition(value) {
+	return typeof value === "object" && value !== null && value.$event === true;
+}
+/** Walks a dot-joined name (`checkout.completed`) to its definition. */
+function resolveEvent(events, name) {
+	let node = events;
+	for (const part of name.split(".")) {
+		if (isEventDefinition(node)) return;
+		const next = node[part];
+		if (next === void 0) return;
+		node = next;
+	}
+	return isEventDefinition(node) ? node : void 0;
+}
+/** Flattens a nested plan to `[{ name: 'checkout.completed', props: ['total'] }]`. */
+function flattenEvents(events, prefix = "") {
+	const flat = [];
+	for (const [key, value] of Object.entries(events)) {
+		const name = prefix === "" ? key : `${prefix}.${key}`;
+		if (isEventDefinition(value)) flat.push({
+			name,
+			props: Object.keys(value.props)
+		});
+		else flat.push(...flattenEvents(value, name));
+	}
+	return flat;
+}
+//#endregion
+//#region src/wire.ts
+/** Events per batch. Anything larger is a client bug or an abusive caller. */
+const MAX_BATCH_EVENTS = 100;
+const MAX_NAME_LENGTH = 120;
+const MAX_ROUTE_LENGTH = 500;
+function isValidRoute(route) {
+	return typeof route === "string" && route.length > 0 && route.length <= MAX_ROUTE_LENGTH;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseEvent(value, index) {
+	if (!isRecord(value)) return {
+		ok: false,
+		error: `events[${index}] is not an object`
+	};
+	const { name, props, timestamp, url, route, referrer } = value;
+	if (typeof name !== "string" || name === "" || name.length > MAX_NAME_LENGTH) return {
+		ok: false,
+		error: `events[${index}].name must be a name of 1 to ${MAX_NAME_LENGTH} characters`
+	};
+	if (typeof timestamp !== "number" || !Number.isFinite(timestamp) || timestamp < 0) return {
+		ok: false,
+		error: `events[${index}].timestamp must be epoch milliseconds`
+	};
+	if (props !== void 0 && !isRecord(props)) return {
+		ok: false,
+		error: `events[${index}].props must be an object`
+	};
+	if (url !== void 0 && typeof url !== "string") return {
+		ok: false,
+		error: `events[${index}].url must be a string`
+	};
+	if (route !== void 0 && !isValidRoute(route)) return {
+		ok: false,
+		error: `events[${index}].route must be 1 to ${MAX_ROUTE_LENGTH} characters`
+	};
+	if (referrer !== void 0 && typeof referrer !== "string") return {
+		ok: false,
+		error: `events[${index}].referrer must be a string`
+	};
+	const event = {
+		name,
+		props: isRecord(props) ? props : {},
+		timestamp,
+		...typeof url === "string" ? { url } : {},
+		...typeof referrer === "string" ? { referrer } : {}
+	};
+	if (typeof route === "string") event.route = route;
+	return {
+		ok: true,
+		value: event
+	};
+}
+/**
+* Validates a batch posted by a browser. The body is untrusted input from the
+* open internet, so this checks shape by hand rather than trusting a cast;
+* props are validated against the tracking plan separately.
+*/
+function parseClientBatch(body) {
+	if (!isRecord(body)) return {
+		ok: false,
+		error: "body must be an object"
+	};
+	if (!Array.isArray(body.events) || body.events.length === 0) return {
+		ok: false,
+		error: "events must be a non-empty array"
+	};
+	if (body.events.length > 100) return {
+		ok: false,
+		error: `events must hold at most 100 entries`
+	};
+	if (body.context !== void 0 && !isRecord(body.context)) return {
+		ok: false,
+		error: "context must be an object"
+	};
+	const events = [];
+	for (const [index, raw] of body.events.entries()) {
+		const parsed = parseEvent(raw, index);
+		if (!parsed.ok) return parsed;
+		events.push(parsed.value);
+	}
+	return {
+		ok: true,
+		value: {
+			context: isRecord(body.context) ? body.context : {},
+			events
+		}
+	};
+}
+//#endregion
+export { BUILT_IN_EVENTS as a, flattenEvents as c, parseClientBatch as i, isEventDefinition as l, MAX_BATCH_EVENTS as n, PAGEVIEW as o, isValidRoute as r, event as s, DEFAULT_ORIGIN$1 as t, resolveEvent as u };

package/package.json

@@ -1,15 +1,22 @@
 {
   "name": "@stetcms/analytics",
-  "version": "0.1.0",
-  "description": "Type-safe, cookieless product analytics for Stet, routed through your own backend.",
+  "version": "0.2.0",
+  "description": "Cookieless, type-safe product analytics routed through your own backend. Part of Stet, the CMS for marketing and engineering.",
   "keywords": [
     "analytics",
+    "cms",
     "cookieless",
+    "first-party",
+    "headless-cms",
     "pageviews",
+    "privacy",
+    "product-analytics",
     "stet",
-    "tracking"
+    "stetcms",
+    "tracking",
+    "typescript"
   ],
-  "homepage": "https://github.com/jamiedavenport/stet/tree/main/published/analytics#readme",
+  "homepage": "https://docs.stetcms.com/reference/analytics",
   "bugs": "https://github.com/jamiedavenport/stet/issues",
   "license": "Apache-2.0",
   "author": "Jamie Davenport (https://jxd.dev)",
@@ -22,6 +29,7 @@
     "dist"
   ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -45,7 +53,7 @@
   },
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
-    "@stetcms/config": "0.1.0"
+    "@stetcms/config": "0.1.1"
   },
   "devDependencies": {
     "publint": "^0.3.21",

package/dist/events-DnYdjoR6.js

@@ -1,57 +0,0 @@
-//#region src/events.ts
-/** The pageview every browser client sends. */
-const PAGEVIEW = "$pageview";
-/**
-* Events the client sends for itself. `$`-prefixed so a tracking plan can
-* never collide with one; their context (url, referrer) rides the envelope
-* rather than the props, so they carry no schema of their own.
-*/
-const BUILT_IN_EVENTS = /* @__PURE__ */ new Set([PAGEVIEW]);
-/**
-* Declares an event and the props it carries. Props are any Standard Schema
-* validator, so the schema library is yours to pick (Zod, Valibot, ArkType).
-* Events group by nesting, and nested events track under dot-joined names:
-*
-* ```ts
-* events: {
-*   signup: event({ plan: z.enum(['free', 'paid']) }),
-*   checkout: { started: event(), completed: event({ total: z.number() }) },
-* }
-* // → 'signup', 'checkout.started', 'checkout.completed'
-* ```
-*/
-function event(props) {
-	return {
-		$event: true,
-		props: props ?? {}
-	};
-}
-function isEventDefinition(value) {
-	return typeof value === "object" && value !== null && value.$event === true;
-}
-/** Walks a dot-joined name (`checkout.completed`) to its definition. */
-function resolveEvent(events, name) {
-	let node = events;
-	for (const part of name.split(".")) {
-		if (isEventDefinition(node)) return;
-		const next = node[part];
-		if (next === void 0) return;
-		node = next;
-	}
-	return isEventDefinition(node) ? node : void 0;
-}
-/** Flattens a nested plan to `[{ name: 'checkout.completed', props: ['total'] }]`. */
-function flattenEvents(events, prefix = "") {
-	const flat = [];
-	for (const [key, value] of Object.entries(events)) {
-		const name = prefix === "" ? key : `${prefix}.${key}`;
-		if (isEventDefinition(value)) flat.push({
-			name,
-			props: Object.keys(value.props)
-		});
-		else flat.push(...flattenEvents(value, name));
-	}
-	return flat;
-}
-//#endregion
-export { isEventDefinition as a, flattenEvents as i, PAGEVIEW as n, resolveEvent as o, event as r, BUILT_IN_EVENTS as t };

package/dist/wire-J3xnrDYj.js

@@ -1,143 +0,0 @@
-import { o as resolveEvent, t as BUILT_IN_EVENTS } from "./events-DnYdjoR6.js";
-import { DEFAULT_ORIGIN as DEFAULT_ORIGIN$1 } from "@stetcms/config";
-//#region src/plan.ts
-/**
-* Declares the tracking plan, conventionally in `stet.config.ts`:
-*
-* ```ts
-* export default defineAnalytics({
-*   events: {
-*     signup: event({ plan: z.enum(['free', 'paid']) }),
-*     checkout: { completed: event({ total: z.number() }) },
-*   },
-* });
-* ```
-*/
-function defineAnalytics(config) {
-	return {
-		...config,
-		$types: void 0
-	};
-}
-/**
-* Validates an event's props against the plan. Declared props are checked
-* with their own schema; undeclared props pass through, so adding a prop in
-* the browser never blocks on a deploy of the plan.
-*/
-async function validateEvent(events, name, props) {
-	if (BUILT_IN_EVENTS.has(name)) return {
-		ok: true,
-		props: props ?? {}
-	};
-	const definition = resolveEvent(events, name);
-	if (definition === void 0) return {
-		ok: false,
-		issues: [{ message: `unknown event "${name}"` }]
-	};
-	const input = props ?? {};
-	const output = { ...input };
-	const issues = [];
-	for (const [key, schema] of Object.entries(definition.props)) {
-		let result = schema["~standard"].validate(input[key]);
-		if (result instanceof Promise) result = await result;
-		if (result.issues) issues.push(...result.issues.map((issue) => ({
-			...issue,
-			message: `${key}: ${issue.message}`
-		})));
-		else output[key] = result.value;
-	}
-	if (issues.length > 0) return {
-		ok: false,
-		issues
-	};
-	return {
-		ok: true,
-		props: output
-	};
-}
-function formatIssues(issues) {
-	return issues.map((issue) => issue.message).join("; ");
-}
-//#endregion
-//#region src/wire.ts
-/** Events per batch. Anything larger is a client bug or an abusive caller. */
-const MAX_BATCH_EVENTS = 100;
-const MAX_NAME_LENGTH = 120;
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function parseEvent(value, index) {
-	if (!isRecord(value)) return {
-		ok: false,
-		error: `events[${index}] is not an object`
-	};
-	const { name, props, timestamp, url, referrer } = value;
-	if (typeof name !== "string" || name === "" || name.length > MAX_NAME_LENGTH) return {
-		ok: false,
-		error: `events[${index}].name must be a name of 1 to ${MAX_NAME_LENGTH} characters`
-	};
-	if (typeof timestamp !== "number" || !Number.isFinite(timestamp) || timestamp < 0) return {
-		ok: false,
-		error: `events[${index}].timestamp must be epoch milliseconds`
-	};
-	if (props !== void 0 && !isRecord(props)) return {
-		ok: false,
-		error: `events[${index}].props must be an object`
-	};
-	if (url !== void 0 && typeof url !== "string") return {
-		ok: false,
-		error: `events[${index}].url must be a string`
-	};
-	if (referrer !== void 0 && typeof referrer !== "string") return {
-		ok: false,
-		error: `events[${index}].referrer must be a string`
-	};
-	return {
-		ok: true,
-		value: {
-			name,
-			props: isRecord(props) ? props : {},
-			timestamp,
-			...typeof url === "string" ? { url } : {},
-			...typeof referrer === "string" ? { referrer } : {}
-		}
-	};
-}
-/**
-* Validates a batch posted by a browser. The body is untrusted input from the
-* open internet, so this checks shape by hand rather than trusting a cast;
-* props are validated against the tracking plan separately.
-*/
-function parseClientBatch(body) {
-	if (!isRecord(body)) return {
-		ok: false,
-		error: "body must be an object"
-	};
-	if (!Array.isArray(body.events) || body.events.length === 0) return {
-		ok: false,
-		error: "events must be a non-empty array"
-	};
-	if (body.events.length > 100) return {
-		ok: false,
-		error: `events must hold at most 100 entries`
-	};
-	if (body.context !== void 0 && !isRecord(body.context)) return {
-		ok: false,
-		error: "context must be an object"
-	};
-	const events = [];
-	for (const [index, raw] of body.events.entries()) {
-		const parsed = parseEvent(raw, index);
-		if (!parsed.ok) return parsed;
-		events.push(parsed.value);
-	}
-	return {
-		ok: true,
-		value: {
-			context: isRecord(body.context) ? body.context : {},
-			events
-		}
-	};
-}
-//#endregion
-export { formatIssues as a, defineAnalytics as i, MAX_BATCH_EVENTS as n, validateEvent as o, parseClientBatch as r, DEFAULT_ORIGIN$1 as t };