highseat 0.2.0 → 0.3.1

package/next.d.ts

@@ -47,8 +47,10 @@ export interface WithHighseatOptions {
  *
  * The proxy is optional. Without a path, `next dev` and `next build` warn once and leave the
  * rewrite out, and `<Highseat />` loads the tracker from Highseat's host. Nothing here throws,
- * so `next typegen` runs without the variable too. The build writes the rewrite, so a path set
- * only at runtime points a dynamically rendered `<Highseat />` at a route that is not there.
+ * so `next typegen` runs without the variable too. With a path, it also sets `HIGHSEAT_PATH` in
+ * the config's `env`, so Next.js writes the build's value into the bundled code of `<Highseat />`
+ * and `createProxy()`. In the App Router, the script and the rewrite then agree, whatever the
+ * server's environment.
  *
  * ```ts
  * // next.config.ts

package/next.js

@@ -1,5 +1,6 @@
-import { n as useIdentify, t as Highseat$1 } from "./react2.js";
-import { n as findNextSite, r as findProxyPath, t as createProxy } from "./proxy2.js";
+import { findNextSite, findProxyPath } from "./env.js";
+import { Highseat as Highseat$1, useIdentify } from "./react.js";
+import { createProxy } from "./proxy.js";
 import { createElement } from "react";
 //#region src/next.ts
 /**
@@ -32,8 +33,10 @@ let hasWarnedNoPath = false;
 *
 * The proxy is optional. Without a path, `next dev` and `next build` warn once and leave the
 * rewrite out, and `<Highseat />` loads the tracker from Highseat's host. Nothing here throws,
-* so `next typegen` runs without the variable too. The build writes the rewrite, so a path set
-* only at runtime points a dynamically rendered `<Highseat />` at a route that is not there.
+* so `next typegen` runs without the variable too. With a path, it also sets `HIGHSEAT_PATH` in
+* the config's `env`, so Next.js writes the build's value into the bundled code of `<Highseat />`
+* and `createProxy()`. In the App Router, the script and the rewrite then agree, whatever the
+* server's environment.
 *
 * ```ts
 * // next.config.ts
@@ -43,7 +46,7 @@ let hasWarnedNoPath = false;
 */
 function withHighseat(config, options = {}) {
 	const path = findProxyPath(options.path);
-	const { rewrites: ownRewrites } = config;
+	const { rewrites: ownRewrites, env } = config;
 	async function passRewritesThrough() {
 		if (!hasWarnedNoPath) {
 			hasWarnedNoPath = true;
@@ -72,6 +75,10 @@ function withHighseat(config, options = {}) {
 	}
 	return {
 		...config,
+		env: {
+			...env,
+			HIGHSEAT_PATH: path
+		},
 		rewrites
 	};
 }

package/next.js.map

@@ -1 +1 @@
-{"version":3,"file":"next.js","names":["ReactHighseat"],"sources":["../src/next.ts"],"sourcesContent":["import { createElement, type ReactElement } from \"react\"\nimport { findNextSite, findProxyPath } from \"./env\"\nimport { Highseat as ReactHighseat, type HighseatProps as ReactHighseatProps } from \"./react\"\n\nexport { createProxy } from \"./proxy\"\nexport { useIdentify } from \"./react\"\nexport type { ClientIp, ClientIpPreset, ProxyHandler, ProxyOptions } from \"./proxy\"\n\nexport interface HighseatProps extends Partial<ReactHighseatProps> {}\n\n/**\n * Loads the Highseat tracker in a Next.js app. Render it once, in the root layout. The site id\n * comes from `NEXT_PUBLIC_HIGHSEAT_SITE`, and the script loads from the site's proxy path in\n * `HIGHSEAT_PATH` when one is set. `HIGHSEAT_PATH` is a server variable, so in the Pages Router,\n * where the layout also renders in the browser, pass `src` instead. A prop wins over its variable.\n * `userId` takes an id the server already knows. For a session read in the browser, call\n * `useIdentify` in a client component instead.\n */\nexport function Highseat(props: HighseatProps): ReactElement | null {\n  const site = props.site ?? findNextSite()\n  const src = props.src ?? findProxyPath()\n\n  if (!site) {\n    console.warn(\"highseat: set NEXT_PUBLIC_HIGHSEAT_SITE, or pass `site` to <Highseat />\")\n    return null\n  }\n\n  return createElement(ReactHighseat, { ...props, site, src })\n}\n\n/** A Next.js rewrite: the subset of its fields this package writes and reads. */\ninterface Rewrite {\n  source: string\n  destination: string\n}\n\n/** The phases Next.js applies rewrites in, when `rewrites()` returns an object. */\ninterface RewritePhases {\n  beforeFiles?: Rewrite[]\n  afterFiles?: Rewrite[]\n  fallback?: Rewrite[]\n}\n\n/** The part of a Next.js config `withHighseat` reads. */\ninterface NextConfigWithRewrites {\n  rewrites?: () => Promise<Rewrite[] | RewritePhases>\n}\n\n/** A Next.js config with the proxy's rewrite added, or its own rewrites when there is no path. */\nexport type WithHighseatConfig<Config> = Config & {\n  rewrites: () => Promise<Rewrite[] | RewritePhases>\n}\n\nexport interface WithHighseatOptions {\n  /**\n   * The site's proxy path from Installation settings. Defaults to the `HIGHSEAT_PATH`\n   * environment variable, the one `createProxy()` reads, so rotating the path is an\n   * environment change and a redeploy.\n   */\n  path?: string\n  /**\n   * Where the app's proxy route handler lives. Defaults to `/api/highseat`, the route of\n   * `app/api/highseat/route.ts`.\n   */\n  route?: string\n}\n\nconst DEFAULT_ROUTE = \"/api/highseat\"\n\n// A dev session can ask for the rewrites more than once, so the warning is printed once.\nlet hasWarnedNoPath = false\n\n/**\n * Adds a rewrite from the site's proxy path to the app's proxy route handler, ahead of every\n * other route. The rewrite stays inside the app, so the handler still sees the visitor's IP, and\n * the route file never moves when the path rotates.\n *\n * The proxy is optional. Without a path, `next dev` and `next build` warn once and leave the\n * rewrite out, and `<Highseat />` loads the tracker from Highseat's host. Nothing here throws,\n * so `next typegen` runs without the variable too. The build writes the rewrite, so a path set\n * only at runtime points a dynamically rendered `<Highseat />` at a route that is not there.\n *\n * ```ts\n * // next.config.ts\n * import { withHighseat } from \"highseat/next\"\n * export default withHighseat({ reactStrictMode: true })\n * ```\n */\nexport function withHighseat<Config extends object>(\n  config: Config,\n  options: WithHighseatOptions = {},\n): WithHighseatConfig<Config> {\n  const path = findProxyPath(options.path)\n\n  // Typed loosely so any Next.js version's config fits; only `rewrites` is read.\n  const { rewrites: ownRewrites } = config as NextConfigWithRewrites\n\n  async function passRewritesThrough(): Promise<Rewrite[] | RewritePhases> {\n    if (!hasWarnedNoPath) {\n      hasWarnedNoPath = true\n      console.warn(\n        \"highseat/next: no HIGHSEAT_PATH, so this build has no proxy rewrite and the tracker loads from Highseat's host. For first-party delivery, set it to the path from the site's Installation settings, or pass `path`, for the build as well as at runtime: a path set only at runtime points the tracker at a route this build does not have.\",\n      )\n    }\n    return (await ownRewrites?.()) ?? []\n  }\n\n  if (!path) return { ...config, rewrites: passRewritesThrough }\n\n  const rewrite = { source: path, destination: options.route ?? DEFAULT_ROUTE }\n\n  async function rewrites(): Promise<RewritePhases> {\n    const existing = (await ownRewrites?.()) ?? []\n\n    // A plain array is Next.js shorthand for the `afterFiles` phase.\n    if (Array.isArray(existing)) return { beforeFiles: [rewrite], afterFiles: existing }\n    return { ...existing, beforeFiles: [rewrite, ...(existing.beforeFiles ?? [])] }\n  }\n\n  return { ...config, rewrites }\n}\n"],"mappings":";;;;;;;;;;;;AAkBA,SAAgB,SAAS,OAA2C;CAClE,MAAM,OAAO,MAAM,QAAQ,aAAa;CACxC,MAAM,MAAM,MAAM,OAAO,cAAc;CAEvC,IAAI,CAAC,MAAM;EACT,QAAQ,KAAK,yEAAyE;EACtF,OAAO;CACT;CAEA,OAAO,cAAcA,YAAe;EAAE,GAAG;EAAO;EAAM;CAAI,CAAC;AAC7D;AAuCA,MAAM,gBAAgB;AAGtB,IAAI,kBAAkB;;;;;;;;;;;;;;;;;AAkBtB,SAAgB,aACd,QACA,UAA+B,CAAC,GACJ;CAC5B,MAAM,OAAO,cAAc,QAAQ,IAAI;CAGvC,MAAM,EAAE,UAAU,gBAAgB;CAElC,eAAe,sBAA0D;EACvE,IAAI,CAAC,iBAAiB;GACpB,kBAAkB;GAClB,QAAQ,KACN,6UACF;EACF;EACA,OAAQ,MAAM,cAAc,KAAM,CAAC;CACrC;CAEA,IAAI,CAAC,MAAM,OAAO;EAAE,GAAG;EAAQ,UAAU;CAAoB;CAE7D,MAAM,UAAU;EAAE,QAAQ;EAAM,aAAa,QAAQ,SAAS;CAAc;CAE5E,eAAe,WAAmC;EAChD,MAAM,WAAY,MAAM,cAAc,KAAM,CAAC;EAG7C,IAAI,MAAM,QAAQ,QAAQ,GAAG,OAAO;GAAE,aAAa,CAAC,OAAO;GAAG,YAAY;EAAS;EACnF,OAAO;GAAE,GAAG;GAAU,aAAa,CAAC,SAAS,GAAI,SAAS,eAAe,CAAC,CAAE;EAAE;CAChF;CAEA,OAAO;EAAE,GAAG;EAAQ;CAAS;AAC/B"}
+{"version":3,"file":"next.js","names":["ReactHighseat"],"sources":["../src/next.ts"],"sourcesContent":["import { createElement, type ReactElement } from \"react\"\nimport { findNextSite, findProxyPath } from \"./env\"\nimport { Highseat as ReactHighseat, type HighseatProps as ReactHighseatProps } from \"./react\"\n\nexport { createProxy } from \"./proxy\"\nexport { useIdentify } from \"./react\"\nexport type { ClientIp, ClientIpPreset, ProxyHandler, ProxyOptions } from \"./proxy\"\n\nexport interface HighseatProps extends Partial<ReactHighseatProps> {}\n\n/**\n * Loads the Highseat tracker in a Next.js app. Render it once, in the root layout. The site id\n * comes from `NEXT_PUBLIC_HIGHSEAT_SITE`, and the script loads from the site's proxy path in\n * `HIGHSEAT_PATH` when one is set. `HIGHSEAT_PATH` is a server variable, so in the Pages Router,\n * where the layout also renders in the browser, pass `src` instead. A prop wins over its variable.\n * `userId` takes an id the server already knows. For a session read in the browser, call\n * `useIdentify` in a client component instead.\n */\nexport function Highseat(props: HighseatProps): ReactElement | null {\n  const site = props.site ?? findNextSite()\n  const src = props.src ?? findProxyPath()\n\n  if (!site) {\n    console.warn(\"highseat: set NEXT_PUBLIC_HIGHSEAT_SITE, or pass `site` to <Highseat />\")\n    return null\n  }\n\n  return createElement(ReactHighseat, { ...props, site, src })\n}\n\n/** A Next.js rewrite: the subset of its fields this package writes and reads. */\ninterface Rewrite {\n  source: string\n  destination: string\n}\n\n/** The phases Next.js applies rewrites in, when `rewrites()` returns an object. */\ninterface RewritePhases {\n  beforeFiles?: Rewrite[]\n  afterFiles?: Rewrite[]\n  fallback?: Rewrite[]\n}\n\n/** The part of a Next.js config `withHighseat` reads. */\ninterface NextConfigWithRewrites {\n  rewrites?: () => Promise<Rewrite[] | RewritePhases>\n  env?: Record<string, string | undefined>\n}\n\n/** A Next.js config with the proxy's rewrite added, or its own rewrites when there is no path. */\nexport type WithHighseatConfig<Config> = Config & {\n  rewrites: () => Promise<Rewrite[] | RewritePhases>\n}\n\nexport interface WithHighseatOptions {\n  /**\n   * The site's proxy path from Installation settings. Defaults to the `HIGHSEAT_PATH`\n   * environment variable, the one `createProxy()` reads, so rotating the path is an\n   * environment change and a redeploy.\n   */\n  path?: string\n  /**\n   * Where the app's proxy route handler lives. Defaults to `/api/highseat`, the route of\n   * `app/api/highseat/route.ts`.\n   */\n  route?: string\n}\n\nconst DEFAULT_ROUTE = \"/api/highseat\"\n\n// A dev session can ask for the rewrites more than once, so the warning is printed once.\nlet hasWarnedNoPath = false\n\n/**\n * Adds a rewrite from the site's proxy path to the app's proxy route handler, ahead of every\n * other route. The rewrite stays inside the app, so the handler still sees the visitor's IP, and\n * the route file never moves when the path rotates.\n *\n * The proxy is optional. Without a path, `next dev` and `next build` warn once and leave the\n * rewrite out, and `<Highseat />` loads the tracker from Highseat's host. Nothing here throws,\n * so `next typegen` runs without the variable too. With a path, it also sets `HIGHSEAT_PATH` in\n * the config's `env`, so Next.js writes the build's value into the bundled code of `<Highseat />`\n * and `createProxy()`. In the App Router, the script and the rewrite then agree, whatever the\n * server's environment.\n *\n * ```ts\n * // next.config.ts\n * import { withHighseat } from \"highseat/next\"\n * export default withHighseat({ reactStrictMode: true })\n * ```\n */\nexport function withHighseat<Config extends object>(\n  config: Config,\n  options: WithHighseatOptions = {},\n): WithHighseatConfig<Config> {\n  const path = findProxyPath(options.path)\n\n  // Typed loosely so any Next.js version's config fits; only `rewrites` and `env` are read.\n  const { rewrites: ownRewrites, env } = config as NextConfigWithRewrites\n\n  async function passRewritesThrough(): Promise<Rewrite[] | RewritePhases> {\n    if (!hasWarnedNoPath) {\n      hasWarnedNoPath = true\n      console.warn(\n        \"highseat/next: no HIGHSEAT_PATH, so this build has no proxy rewrite and the tracker loads from Highseat's host. For first-party delivery, set it to the path from the site's Installation settings, or pass `path`, for the build as well as at runtime: a path set only at runtime points the tracker at a route this build does not have.\",\n      )\n    }\n    return (await ownRewrites?.()) ?? []\n  }\n\n  if (!path) return { ...config, rewrites: passRewritesThrough }\n\n  const rewrite = { source: path, destination: options.route ?? DEFAULT_ROUTE }\n\n  async function rewrites(): Promise<RewritePhases> {\n    const existing = (await ownRewrites?.()) ?? []\n\n    // A plain array is Next.js shorthand for the `afterFiles` phase.\n    if (Array.isArray(existing)) return { beforeFiles: [rewrite], afterFiles: existing }\n    return { ...existing, beforeFiles: [rewrite, ...(existing.beforeFiles ?? [])] }\n  }\n\n  return { ...config, env: { ...env, HIGHSEAT_PATH: path }, rewrites }\n}\n"],"mappings":";;;;;;;;;;;;;AAkBA,SAAgB,SAAS,OAA2C;CAClE,MAAM,OAAO,MAAM,QAAQ,aAAa;CACxC,MAAM,MAAM,MAAM,OAAO,cAAc;CAEvC,IAAI,CAAC,MAAM;EACT,QAAQ,KAAK,yEAAyE;EACtF,OAAO;CACT;CAEA,OAAO,cAAcA,YAAe;EAAE,GAAG;EAAO;EAAM;CAAI,CAAC;AAC7D;AAwCA,MAAM,gBAAgB;AAGtB,IAAI,kBAAkB;;;;;;;;;;;;;;;;;;;AAoBtB,SAAgB,aACd,QACA,UAA+B,CAAC,GACJ;CAC5B,MAAM,OAAO,cAAc,QAAQ,IAAI;CAGvC,MAAM,EAAE,UAAU,aAAa,QAAQ;CAEvC,eAAe,sBAA0D;EACvE,IAAI,CAAC,iBAAiB;GACpB,kBAAkB;GAClB,QAAQ,KACN,6UACF;EACF;EACA,OAAQ,MAAM,cAAc,KAAM,CAAC;CACrC;CAEA,IAAI,CAAC,MAAM,OAAO;EAAE,GAAG;EAAQ,UAAU;CAAoB;CAE7D,MAAM,UAAU;EAAE,QAAQ;EAAM,aAAa,QAAQ,SAAS;CAAc;CAE5E,eAAe,WAAmC;EAChD,MAAM,WAAY,MAAM,cAAc,KAAM,CAAC;EAG7C,IAAI,MAAM,QAAQ,QAAQ,GAAG,OAAO;GAAE,aAAa,CAAC,OAAO;GAAG,YAAY;EAAS;EACnF,OAAO;GAAE,GAAG;GAAU,aAAa,CAAC,SAAS,GAAI,SAAS,eAAe,CAAC,CAAE;EAAE;CAChF;CAEA,OAAO;EAAE,GAAG;EAAQ,KAAK;GAAE,GAAG;GAAK,eAAe;EAAK;EAAG;CAAS;AACrE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "highseat",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Highseat analytics for JavaScript: typed tracking, a first-party proxy and framework components.",
   "keywords": [
     "analytics",

package/proxy.js

@@ -1 +1,199 @@
-export { t as createProxy } from "./proxy2.js";
+import { findProxyPath, findSecret, isNextBuild } from "./env.js";
+//#region src/proxy.ts
+const DEFAULT_UPSTREAM = "https://cdn.highseat.com";
+const SECRET_PREFIXES = [
+	"hs_secret_",
+	"hs_proxy_",
+	"ana_proxy_"
+];
+const CLIENT_IP_HEADERS = {
+	vercel: "x-real-ip",
+	cloudflare: "cf-connecting-ip",
+	netlify: "x-nf-client-connection-ip",
+	nginx: "x-real-ip"
+};
+const SCRIPT_REQUEST_HEADERS = ["user-agent", "if-none-match"];
+const EVENT_REQUEST_HEADERS = [
+	"content-type",
+	"user-agent",
+	"origin"
+];
+const RESPONSE_HEADERS = [
+	"content-type",
+	"etag",
+	"cache-control",
+	"vary",
+	"retry-after",
+	"x-hs-ip",
+	"x-hs-ip-source"
+];
+const NULL_BODY_STATUSES = /* @__PURE__ */ new Set([
+	101,
+	204,
+	205,
+	304
+]);
+const UPSTREAM_TIMEOUT_MS = 1e4;
+const MAX_EVENT_BYTES = 524288;
+function getClientIpReader(clientIp) {
+	if (typeof clientIp === "function") return {
+		read: (request) => clientIp(request)?.trim() ?? "",
+		source: "the clientIp function"
+	};
+	const header = CLIENT_IP_HEADERS[clientIp];
+	if (!header) throw new Error(`highseat/proxy: unknown clientIp preset "${String(clientIp)}".`);
+	return {
+		read: (request) => request.headers.get(header)?.trim() ?? "",
+		source: `the "${clientIp}" preset's ${header} header`
+	};
+}
+function copyHeaders(from, to, names) {
+	for (const name of names) {
+		const value = from.get(name);
+		if (value !== null) to.set(name, value);
+	}
+}
+function answerError(status, error) {
+	return Response.json({ error }, {
+		status,
+		headers: { "cache-control": "no-store" }
+	});
+}
+function answerOtherPath() {
+	return answerError(404, "Not the proxy path. The Highseat proxy answers on its own path only.");
+}
+/** The site secret, or `undefined` when none is set. Throws on a value that is not one. */
+function findValidSecret(option) {
+	const secret = option ?? findSecret();
+	if (!secret) return;
+	if (!SECRET_PREFIXES.some((prefix) => secret.startsWith(prefix))) throw new Error(`highseat/proxy: not a site secret. Copy it from the site's Installation settings; it starts with "${SECRET_PREFIXES[0]}".`);
+	return secret;
+}
+let hasWarnedMissing = false;
+/**
+* The handler for a proxy missing a variable: every request goes to `fallback`, or the proxy
+* path answers 503 naming what is missing.
+*/
+function createDisabledProxy(missing, path, fallback) {
+	const names = missing.join(" and ");
+	if (!hasWarnedMissing && !isNextBuild()) {
+		hasWarnedMissing = true;
+		console.warn(`highseat/proxy: ${names} not set, so the proxy is off and ${fallback ? "every request goes to `fallback`" : "the proxy path answers 503"}.`);
+	}
+	return async function proxy(request) {
+		if (fallback) return fallback(request);
+		if (path !== void 0 && new URL(request.url).pathname !== path) return answerOtherPath();
+		return answerError(503, `The Highseat proxy is off: set ${names}.`);
+	};
+}
+/** The request body, or `undefined` once it passes `MAX_EVENT_BYTES`. */
+async function readEventBody(request) {
+	if (Number(request.headers.get("content-length")) > MAX_EVENT_BYTES) return;
+	if (!request.body) return /* @__PURE__ */ new Uint8Array();
+	const reader = request.body.getReader();
+	const chunks = [];
+	let size = 0;
+	for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) {
+		size += chunk.value.byteLength;
+		if (size > MAX_EVENT_BYTES) {
+			reader.cancel();
+			return;
+		}
+		chunks.push(chunk.value);
+	}
+	const body = new Uint8Array(size);
+	let offset = 0;
+	for (const chunk of chunks) {
+		body.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return body;
+}
+/**
+* Creates the first-party proxy handler for a site. A GET serves the tracker script and a POST
+* forwards its events, both to the ingest host, with the site secret and the visitor's IP. The
+* returned function takes a `Request` and returns a `Response`, so it mounts as a Next.js route
+* handler, a Cloudflare Worker, a Pages Function, a Netlify or Vercel function, an Astro
+* endpoint or a Hono route.
+*
+* A missing path or secret never throws: the handler passes every request to `fallback`, or
+* answers the proxy path with a 503 naming the variable, and warns once. A value that is not a
+* site secret throws, since that is a copying mistake rather than a variable left unset.
+*/
+function createProxy(options) {
+	const path = findProxyPath(options.path);
+	const { fallback } = options;
+	let foundSecret;
+	try {
+		foundSecret = findValidSecret(options.secret);
+	} catch (error) {
+		if (!isNextBuild()) throw error;
+		return () => Promise.reject(error);
+	}
+	const upstream = new URL(options.upstream ?? DEFAULT_UPSTREAM).origin;
+	const missing = [...fallback && path === void 0 ? ["HIGHSEAT_PATH"] : [], ...foundSecret ? [] : ["HIGHSEAT_SECRET"]];
+	if (!foundSecret || missing.length) return createDisabledProxy(missing, path, fallback);
+	const secret = foundSecret;
+	const clientIpReader = getClientIpReader(options.clientIp);
+	let hasWarnedNoIp = false;
+	function readClientIp(request) {
+		const ip = clientIpReader.read(request);
+		if (!ip && !hasWarnedNoIp) {
+			hasWarnedNoIp = true;
+			console.warn(`highseat/proxy: no visitor IP in ${clientIpReader.source}, so Highseat refuses every event. Set clientIp to the outermost proxy in front of this server.`);
+		}
+		return ip;
+	}
+	function buildUpstreamHeaders(request, names) {
+		const headers = new Headers({
+			"accept-encoding": "identity",
+			"x-hs-secret": secret,
+			"x-hs-client-ip": readClientIp(request)
+		});
+		copyHeaders(request.headers, headers, names);
+		return headers;
+	}
+	async function forward(url, init) {
+		let response;
+		try {
+			response = await fetch(url, {
+				...init,
+				signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS)
+			});
+		} catch {
+			return answerError(502, "Highseat is unreachable from this proxy.");
+		}
+		const headers = new Headers();
+		copyHeaders(response.headers, headers, RESPONSE_HEADERS);
+		if (init.method === "POST") headers.set("cache-control", "no-store");
+		const body = NULL_BODY_STATUSES.has(response.status) ? null : response.body;
+		return new Response(body, {
+			status: response.status,
+			headers
+		});
+	}
+	return async function proxy(request) {
+		if (path !== void 0 && new URL(request.url).pathname !== path) return fallback ? fallback(request) : answerOtherPath();
+		if (request.method === "GET" || request.method === "HEAD") return forward(`${upstream}/script.js`, {
+			method: request.method,
+			headers: buildUpstreamHeaders(request, SCRIPT_REQUEST_HEADERS)
+		});
+		if (request.method === "POST") {
+			const body = await readEventBody(request);
+			if (!body) return answerError(413, "The event batch is too large.");
+			return forward(`${upstream}/api/event`, {
+				method: "POST",
+				headers: buildUpstreamHeaders(request, EVENT_REQUEST_HEADERS),
+				body
+			});
+		}
+		return new Response(null, {
+			status: 405,
+			headers: { allow: "GET, HEAD, POST" }
+		});
+	};
+}
+//#endregion
+export { createProxy };
+
+//# sourceMappingURL=proxy.js.map

package/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","names":[],"sources":["../src/proxy.ts"],"sourcesContent":["import { findProxyPath, findSecret, isNextBuild } from \"./env\"\n\n/** A host whose own header carries the visitor's IP. */\nexport type ClientIpPreset = \"vercel\" | \"cloudflare\" | \"netlify\" | \"nginx\"\n\n/**\n * Where the proxy reads the visitor's IP: a host preset, or a function for any other setup. A\n * function returns the IP, or nothing when the request carries none.\n */\nexport type ClientIp = ClientIpPreset | ((request: Request) => string | null | undefined)\n\nexport interface ProxyOptions {\n  /**\n   * The site's proxy path from Installation settings, such as `/3f9a0c1e2b`, with or without its\n   * leading slash. A request on any\n   * other path is answered 404, or handed to `fallback`. Defaults to the `HIGHSEAT_PATH`\n   * environment variable. Leave both unset on a host whose router already sends only the proxy\n   * path here, such as a file named after the path.\n   */\n  path?: string\n  /**\n   * The site secret, `hs_secret_…`, or an older one that starts `hs_proxy_` or `ana_proxy_`.\n   * Defaults to the `HIGHSEAT_SECRET` environment variable. Without one the proxy is off: the\n   * proxy path answers 503, or every request goes to `fallback`.\n   */\n  secret?: string\n  /**\n   * Where the visitor's IP comes from: `vercel`, `cloudflare`, `netlify`, `nginx` (the\n   * `X-Real-IP` header your nginx sets), or a function. A visitor can write any header the host\n   * does not overwrite, so there is no default.\n   *\n   * The outermost proxy that sets the header decides the preset. Behind a proxied Cloudflare\n   * record, use `cloudflare` on any origin, not only a Worker or a Pages Function: a Next.js,\n   * TanStack Start or Node server behind Cloudflare, with or without Traefik or nginx in between,\n   * sees a Cloudflare edge address in `X-Real-IP`, and the visitor's IP in `cf-connecting-ip`.\n   */\n  clientIp: ClientIp\n  /** The ingest origin the proxy forwards to. Defaults to `https://cdn.highseat.com`. */\n  upstream?: string\n  /**\n   * Answers a request on any path other than `path`, for a handler that sees every request on\n   * the site: `fetch` in a Cloudflare Worker routed on the whole site, `next` in a Pages\n   * Function. Needs `path`: without it, or without the secret, the proxy is off and every\n   * request goes here, so the site still serves in a development setup without the variables.\n   */\n  fallback?: (request: Request) => Response | Promise<Response>\n}\n\n/** A fetch handler, the shape every supported runtime and framework route accepts. */\nexport type ProxyHandler = (request: Request) => Promise<Response>\n\nconst DEFAULT_UPSTREAM = \"https://cdn.highseat.com\"\n// The current prefix first. Ingest still accepts the secrets minted under the older two, so a\n// site keeps its secret when it moves to this handler.\nconst SECRET_PREFIXES = [\"hs_secret_\", \"hs_proxy_\", \"ana_proxy_\"]\n\nconst CLIENT_IP_HEADERS: Record<ClientIpPreset, string> = {\n  vercel: \"x-real-ip\",\n  // Read from the inbound request: Cloudflare overwrites it on the Worker's own subrequest.\n  cloudflare: \"cf-connecting-ip\",\n  netlify: \"x-nf-client-connection-ip\",\n  nginx: \"x-real-ip\",\n}\n\n// The visitor headers each direction forwards. Copied by name, so a cookie, an `Authorization`\n// header or a visitor's own `x-hs-*` header never reaches ingest.\nconst SCRIPT_REQUEST_HEADERS = [\"user-agent\", \"if-none-match\"]\nconst EVENT_REQUEST_HEADERS = [\"content-type\", \"user-agent\", \"origin\"]\n\n// The upstream headers the response keeps. Rebuilt by name because Node, Bun and Deno hand back\n// a decompressed body under the original `content-encoding` and `content-length`, which would\n// describe bytes this handler no longer has. `x-hs-ip` and `x-hs-ip-source` show which IP\n// ingest resolved, for `curl -i` against the proxy path.\nconst RESPONSE_HEADERS = [\n  \"content-type\",\n  \"etag\",\n  \"cache-control\",\n  \"vary\",\n  \"retry-after\",\n  \"x-hs-ip\",\n  \"x-hs-ip-source\",\n]\n\n// Statuses whose response must not carry a body, which the Response constructor enforces.\nconst NULL_BODY_STATUSES = new Set([101, 204, 205, 304])\n\nconst UPSTREAM_TIMEOUT_MS = 10_000\n\n// Ingest refuses a larger batch, so a bigger body is answered here without buffering the rest.\nconst MAX_EVENT_BYTES = 512 * 1024\n\ninterface ClientIpReader {\n  read: (request: Request) => string\n  /** Where `read` looks, for the warning about an empty IP. */\n  source: string\n}\n\nfunction getClientIpReader(clientIp: ClientIp): ClientIpReader {\n  if (typeof clientIp === \"function\") {\n    return { read: request => clientIp(request)?.trim() ?? \"\", source: \"the clientIp function\" }\n  }\n\n  const header = CLIENT_IP_HEADERS[clientIp]\n  if (!header) throw new Error(`highseat/proxy: unknown clientIp preset \"${String(clientIp)}\".`)\n  return {\n    read: request => request.headers.get(header)?.trim() ?? \"\",\n    source: `the \"${clientIp}\" preset's ${header} header`,\n  }\n}\n\nfunction copyHeaders(from: Headers, to: Headers, names: string[]) {\n  for (const name of names) {\n    const value = from.get(name)\n    if (value !== null) to.set(name, value)\n  }\n}\n\nfunction answerError(status: number, error: string) {\n  return Response.json({ error }, { status, headers: { \"cache-control\": \"no-store\" } })\n}\n\n// A JSON body rather than an empty 404, so `curl -i` on the route handler's own URL tells this\n// answer apart from ingest's.\nfunction answerOtherPath() {\n  return answerError(404, \"Not the proxy path. The Highseat proxy answers on its own path only.\")\n}\n\n/** The site secret, or `undefined` when none is set. Throws on a value that is not one. */\nfunction findValidSecret(option: string | undefined): string | undefined {\n  const secret = option ?? findSecret()\n  if (!secret) return\n\n  if (!SECRET_PREFIXES.some(prefix => secret.startsWith(prefix))) {\n    throw new Error(\n      `highseat/proxy: not a site secret. Copy it from the site's Installation settings; it starts with \"${SECRET_PREFIXES[0]}\".`,\n    )\n  }\n  return secret\n}\n\n// The handler can be created per request (a Worker that reads its options from `env`), so a\n// missing variable is reported once per process rather than once per handler.\nlet hasWarnedMissing = false\n\n/**\n * The handler for a proxy missing a variable: every request goes to `fallback`, or the proxy\n * path answers 503 naming what is missing.\n */\nfunction createDisabledProxy(\n  missing: string[],\n  path: string | undefined,\n  fallback: ProxyOptions[\"fallback\"],\n): ProxyHandler {\n  const names = missing.join(\" and \")\n\n  // A Next.js build loads every route without serving one, often without the runtime variables.\n  if (!hasWarnedMissing && !isNextBuild()) {\n    hasWarnedMissing = true\n    const outcome = fallback ? \"every request goes to `fallback`\" : \"the proxy path answers 503\"\n    console.warn(`highseat/proxy: ${names} not set, so the proxy is off and ${outcome}.`)\n  }\n\n  return async function proxy(request) {\n    if (fallback) return fallback(request)\n    if (path !== undefined && new URL(request.url).pathname !== path) return answerOtherPath()\n    return answerError(503, `The Highseat proxy is off: set ${names}.`)\n  }\n}\n\n/** The request body, or `undefined` once it passes `MAX_EVENT_BYTES`. */\nasync function readEventBody(request: Request): Promise<Uint8Array<ArrayBuffer> | undefined> {\n  if (Number(request.headers.get(\"content-length\")) > MAX_EVENT_BYTES) return\n  if (!request.body) return new Uint8Array()\n\n  const reader = request.body.getReader()\n  const chunks: Uint8Array[] = []\n  let size = 0\n\n  for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) {\n    size += chunk.value.byteLength\n    if (size > MAX_EVENT_BYTES) {\n      void reader.cancel()\n      return\n    }\n    chunks.push(chunk.value)\n  }\n\n  const body = new Uint8Array(size)\n  let offset = 0\n  for (const chunk of chunks) {\n    body.set(chunk, offset)\n    offset += chunk.byteLength\n  }\n  return body\n}\n\n/**\n * Creates the first-party proxy handler for a site. A GET serves the tracker script and a POST\n * forwards its events, both to the ingest host, with the site secret and the visitor's IP. The\n * returned function takes a `Request` and returns a `Response`, so it mounts as a Next.js route\n * handler, a Cloudflare Worker, a Pages Function, a Netlify or Vercel function, an Astro\n * endpoint or a Hono route.\n *\n * A missing path or secret never throws: the handler passes every request to `fallback`, or\n * answers the proxy path with a 503 naming the variable, and warns once. A value that is not a\n * site secret throws, since that is a copying mistake rather than a variable left unset.\n */\nexport function createProxy(options: ProxyOptions): ProxyHandler {\n  const path = findProxyPath(options.path)\n  const { fallback } = options\n  let foundSecret: string | undefined\n\n  try {\n    foundSecret = findValidSecret(options.secret)\n  } catch (error) {\n    // Next.js loads every route while it builds, so there the error waits for the first request\n    // rather than failing a build that never serves one.\n    if (!isNextBuild()) throw error\n    return () => Promise.reject(error)\n  }\n\n  const upstream = new URL(options.upstream ?? DEFAULT_UPSTREAM).origin\n\n  // Without a secret, ingest would read every visitor as this server and drop it as datacenter\n  // traffic. Without a path, a handler that sees every request cannot tell the proxy's apart.\n  const missing = [\n    ...(fallback && path === undefined ? [\"HIGHSEAT_PATH\"] : []),\n    ...(foundSecret ? [] : [\"HIGHSEAT_SECRET\"]),\n  ]\n  if (!foundSecret || missing.length) return createDisabledProxy(missing, path, fallback)\n\n  const secret = foundSecret\n\n  const clientIpReader = getClientIpReader(options.clientIp)\n  let hasWarnedNoIp = false\n\n  // Ingest answers 400 to every event without a visitor IP and says nothing about the preset,\n  // so the first request without one names the source it read.\n  function readClientIp(request: Request) {\n    const ip = clientIpReader.read(request)\n\n    if (!ip && !hasWarnedNoIp) {\n      hasWarnedNoIp = true\n      console.warn(\n        `highseat/proxy: no visitor IP in ${clientIpReader.source}, so Highseat refuses every event. Set clientIp to the outermost proxy in front of this server.`,\n      )\n    }\n    return ip\n  }\n\n  function buildUpstreamHeaders(request: Request, names: string[]) {\n    const headers = new Headers({\n      // The response never copies `content-encoding`, so ingest is asked for a plain body.\n      \"accept-encoding\": \"identity\",\n      \"x-hs-secret\": secret,\n      \"x-hs-client-ip\": readClientIp(request),\n    })\n    copyHeaders(request.headers, headers, names)\n    return headers\n  }\n\n  async function forward(url: string, init: RequestInit) {\n    let response: Response\n\n    try {\n      response = await fetch(url, { ...init, signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS) })\n    } catch {\n      return answerError(502, \"Highseat is unreachable from this proxy.\")\n    }\n\n    const headers = new Headers()\n    copyHeaders(response.headers, headers, RESPONSE_HEADERS)\n    if (init.method === \"POST\") headers.set(\"cache-control\", \"no-store\")\n\n    const body = NULL_BODY_STATUSES.has(response.status) ? null : response.body\n    return new Response(body, { status: response.status, headers })\n  }\n\n  return async function proxy(request) {\n    if (path !== undefined && new URL(request.url).pathname !== path) {\n      return fallback ? fallback(request) : answerOtherPath()\n    }\n\n    if (request.method === \"GET\" || request.method === \"HEAD\") {\n      return forward(`${upstream}/script.js`, {\n        method: request.method,\n        headers: buildUpstreamHeaders(request, SCRIPT_REQUEST_HEADERS),\n      })\n    }\n\n    if (request.method === \"POST\") {\n      const body = await readEventBody(request)\n      if (!body) return answerError(413, \"The event batch is too large.\")\n\n      return forward(`${upstream}/api/event`, {\n        method: \"POST\",\n        headers: buildUpstreamHeaders(request, EVENT_REQUEST_HEADERS),\n        body,\n      })\n    }\n\n    return new Response(null, { status: 405, headers: { allow: \"GET, HEAD, POST\" } })\n  }\n}\n"],"mappings":"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"}

package/react.d.ts

@@ -1,4 +1,4 @@
-import { a as InjectOptions, p as UserId } from "./index2.js";
+import { InjectOptions, UserId } from "./index.js";
 //#region src/react.d.ts
 export interface HighseatProps extends InjectOptions {
   /**
@@ -29,6 +29,6 @@ export declare function useIdentify(userId: UserId): void;
  * counts client-side navigation on its own. With `userId`, it also identifies the visitor, as
  * {@link useIdentify} does.
  */
-export declare function Highseat({ site, src, outbound, downloads, hashRouting, userId }: HighseatProps): null;
+export declare function Highseat({ site, src, outbound, downloads, hashRouting, debug, userId }: HighseatProps): null;
 //#endregion
 //# sourceMappingURL=react.d.ts.map

package/react.js

@@ -1,2 +1,56 @@
 "use client";
-export { t as Highseat, n as useIdentify } from "./react2.js";
+import { inject } from "./index.js";
+import { syncIdentity } from "./identity.js";
+import { useEffect, useRef } from "react";
+//#region src/react.ts
+/**
+* Keeps the visitor's user id in step with a session. Each new value is passed to `identify`
+* once: an id identifies the visitor, `null` clears the id at sign-out or session expiry, and
+* `undefined`, a session still loading, changes nothing. Works in any client component, with or
+* without `<Highseat />` on the page, and before the tracker has loaded.
+*
+* Tell loading apart from signed out: `useIdentify(session?.user.id)` passes `undefined` after
+* sign-out too, so it never clears the id.
+*
+* ```tsx
+* const { data, isPending } = useSession()
+* useIdentify(isPending ? undefined : (data?.user.id ?? null))
+* ```
+*/
+function useIdentify(userId) {
+	const identified = useRef(void 0);
+	useEffect(() => {
+		identified.current = syncIdentity(identified.current, userId);
+	}, [userId]);
+}
+/**
+* Loads the Highseat tracker. Render it once, in the root layout. It adds the script tag after
+* the page mounts and renders nothing; mounting it again adds no second tag, and the tracker
+* counts client-side navigation on its own. With `userId`, it also identifies the visitor, as
+* {@link useIdentify} does.
+*/
+function Highseat({ site, src, outbound, downloads, hashRouting, debug, userId }) {
+	useEffect(() => {
+		inject({
+			site,
+			src,
+			outbound,
+			downloads,
+			hashRouting,
+			debug
+		});
+	}, [
+		site,
+		src,
+		outbound,
+		downloads,
+		hashRouting,
+		debug
+	]);
+	useIdentify(userId);
+	return null;
+}
+//#endregion
+export { Highseat, useIdentify };
+
+//# sourceMappingURL=react.js.map

package/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","names":[],"sources":["../src/react.ts"],"sourcesContent":["\"use client\"\n\nimport { useEffect, useRef } from \"react\"\nimport { syncIdentity } from \"./identity\"\nimport { inject, type InjectOptions, type UserId } from \"./index\"\n\nexport interface HighseatProps extends InjectOptions {\n  /**\n   * The signed-in user's id from your own system, never an email or other personal data. Pass\n   * `null` once the visitor is signed out, and `undefined` while the session is still loading.\n   * See {@link useIdentify}.\n   */\n  userId?: UserId\n}\n\n/**\n * Keeps the visitor's user id in step with a session. Each new value is passed to `identify`\n * once: an id identifies the visitor, `null` clears the id at sign-out or session expiry, and\n * `undefined`, a session still loading, changes nothing. Works in any client component, with or\n * without `<Highseat />` on the page, and before the tracker has loaded.\n *\n * Tell loading apart from signed out: `useIdentify(session?.user.id)` passes `undefined` after\n * sign-out too, so it never clears the id.\n *\n * ```tsx\n * const { data, isPending } = useSession()\n * useIdentify(isPending ? undefined : (data?.user.id ?? null))\n * ```\n */\nexport function useIdentify(userId: UserId): void {\n  // The id this component identified last. A ref survives Strict Mode's second effect run, so\n  // the same id is never sent twice.\n  const identified = useRef<UserId>(undefined)\n\n  useEffect(() => {\n    identified.current = syncIdentity(identified.current, userId)\n  }, [userId])\n}\n\n/**\n * Loads the Highseat tracker. Render it once, in the root layout. It adds the script tag after\n * the page mounts and renders nothing; mounting it again adds no second tag, and the tracker\n * counts client-side navigation on its own. With `userId`, it also identifies the visitor, as\n * {@link useIdentify} does.\n */\nexport function Highseat({\n  site,\n  src,\n  outbound,\n  downloads,\n  hashRouting,\n  debug,\n  userId,\n}: HighseatProps): null {\n  useEffect(() => {\n    inject({ site, src, outbound, downloads, hashRouting, debug })\n  }, [site, src, outbound, downloads, hashRouting, debug])\n\n  useIdentify(userId)\n\n  return null\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,YAAY,QAAsB;CAGhD,MAAM,aAAa,OAAe,KAAA,CAAS;CAE3C,gBAAgB;EACd,WAAW,UAAU,aAAa,WAAW,SAAS,MAAM;CAC9D,GAAG,CAAC,MAAM,CAAC;AACb;;;;;;;AAQA,SAAgB,SAAS,EACvB,MACA,KACA,UACA,WACA,aACA,OACA,UACsB;CACtB,gBAAgB;EACd,OAAO;GAAE;GAAM;GAAK;GAAU;GAAW;GAAa;EAAM,CAAC;CAC/D,GAAG;EAAC;EAAM;EAAK;EAAU;EAAW;EAAa;CAAK,CAAC;CAEvD,YAAY,MAAM;CAElB,OAAO;AACT"}

package/index2.d.ts

@@ -1,174 +0,0 @@
-//#region src/index.d.ts
-/**
- * The browser client. Every call goes to the hosted tracker on `window.highseat`; before the
- * tracker has loaded, calls wait in a queue the tracker drains on startup. Nothing here throws:
- * on a server, with the tracker blocked, or with tracking off, a call does nothing.
- */
-/** A value an event property can hold. A `null` or `undefined` value is left out of the event. */
-type PropertyValue = string | number | boolean | null | undefined;
-/**
- * Money attached to an event. `amount` is an integer in the currency's smallest unit, so
- * `{ amount: 4999, currency: "USD" }` is $49.99 and `{ amount: 5000, currency: "JPY" }` is ¥5000.
- */
-interface Revenue {
-  /** An integer in minor units: 4999 for $49.99. An amount with decimals is rejected. */
-  amount: number;
-  /** An ISO 4217 code, such as `USD` or `EUR`. */
-  currency: string;
-}
-/** The properties of an event with no declared shape: any string keys, plus optional revenue. */
-interface Properties {
-  /** Money the event brought in. */
-  revenue?: Revenue;
-  [key: string]: PropertyValue | Revenue;
-}
-/**
- * The events Highseat knows by name. A site extends it, or overrides an entry, through
- * {@link Register}. Type-only: it adds nothing to the bundle.
- */
-interface BuiltInEvents {
-  /** A visitor created an account. */
-  signup: Properties;
-  /** A visitor signed in. */
-  login: Properties;
-  /**
-   * A sale. With a payment provider connected, leave `revenue` out: the provider's webhook
-   * records the money, and revenue sent here as well would count the sale twice. Send `revenue`
-   * only for a checkout no provider reports, and then with an `order_id`, so a provider sale
-   * added later for the same order is not counted again.
-   */
-  purchase: Properties;
-  /** A paid subscription began. */
-  subscription_started: Properties;
-  /** A free trial began. */
-  trial_started: Properties;
-  /** A file download. The tracker records links to files on its own. */
-  file_download: {
-    url: string;
-  };
-  /** A click on a link to another site. The tracker records these on its own. */
-  outbound_link_click: {
-    url: string;
-  };
-  /** A visit to a missing page. Call it from a single-page app's not-found route. */
-  "404": Properties;
-}
-/**
- * Declares a site's own events. Augment it from any file the compiler sees:
- *
- * ```ts
- * declare module "highseat" {
- *   interface Register {
- *     events: {
- *       signup: { plan: "free" | "pro" }
- *     }
- *     strict: true
- *   }
- * }
- * ```
- *
- * `events` adds names, or replaces a built-in one's properties. `strict: true` makes `track`
- * accept only built-in and registered names, so a misspelt name is a type error.
- */
-interface Register {}
-/**
- * A registered event's properties as `track` accepts them. A shape with no properties takes none,
- * and a property whose type an event cannot carry becomes `never`, so a call passing it fails
- * instead of sending `"[object Object]"`. The shape is not rejected at registration, where a
- * failed check would silently drop every registered event at once.
- */
-type CheckedProperties<Shape> = [keyof Shape] extends [never] ? Record<string, never> : { [Key in keyof Shape]: Shape[Key] extends PropertyValue | Revenue ? Shape[Key] : never; };
-type RegisteredEvents = Register extends {
-  events: infer Registered;
-} ? { [Name in keyof Registered]: CheckedProperties<Registered[Name]>; } : {};
-type KnownEvents = Omit<BuiltInEvents, keyof RegisteredEvents> & RegisteredEvents;
-/** Every event name `track` knows, built-in or registered. */
-type EventName = Extract<keyof KnownEvents, string>;
-/**
- * The names `track` accepts: known names, and any other string unless the site is strict.
- * `string & {}` keeps the known names in the editor's suggestions, which a plain `string` in the
- * union would absorb.
- */
-type TrackName = Register extends {
-  strict: true;
-} ? EventName : EventName | (string & {});
-/**
- * The arguments after an event's name. A known name takes its declared properties, required
- * when any of them is; any other name takes {@link Properties}. Wrapped in tuples so a union of
- * names is checked as a whole rather than name by name.
- */
-type TrackArgs<Name extends string> = [Name] extends [EventName] ? {} extends KnownEvents[Name] ? [properties?: KnownEvents[Name]] : [properties: KnownEvents[Name]] : [properties?: Properties];
-/**
- * A user id from your own system, as {@link identify} takes it. A string or a number identifies
- * the visitor, `null` clears the id, and `undefined` or an empty string changes nothing. Pass your
- * own database id, never an email or other personal data.
- */
-type UserId = string | number | null | undefined;
-/** The tracker's API on `window.highseat`, or the queue that stands in for it until it loads. */
-interface HighseatGlobal {
-  /** Records an event. */
-  track?: (name: string, properties?: Properties) => void;
-  /** Sets or clears the visitor's user id. */
-  identify?: (id: UserId) => void;
-  /** The id that joins a payment to this tab's visit. */
-  getAttributionId?: () => string | undefined;
-  /** Calls made before the tracker loaded, drained in order when it starts. */
-  q?: [string, unknown[]][];
-}
-/** How long {@link getAttributionId} waits for the tracker. */
-interface AttributionOptions {
-  /** Milliseconds to wait for the tracker to load. Defaults to 3000. */
-  timeout?: number;
-}
-/** How the tracker is loaded. Each option maps to an attribute on its script tag. */
-interface InjectOptions {
-  /** The site id, `site_…`, from the site's Installation settings. */
-  site: string;
-  /**
-   * Where the script loads from: the site's proxy path (`/3f9a0c1e2b`) for first-party
-   * delivery, or a full URL. Defaults to Highseat's own host. The tracker posts its events back
-   * to the same place.
-   */
-  src?: string;
-  /** Records clicks on links to other sites as `outbound_link_click`. Defaults to `true`. */
-  outbound?: boolean;
-  /** Records clicks on links to files as `file_download`. Defaults to `true`. */
-  downloads?: boolean;
-  /** Counts a change of `#/route` as a page view, for an app that routes by hash. */
-  hashRouting?: boolean;
-}
-declare global {
-  interface Window {
-    highseat?: HighseatGlobal;
-  }
-}
-/** Where the tracker loads from when the site has no proxy path. */
-declare const SCRIPT_URL = "https://cdn.highseat.com/script.js";
-/**
- * Records an event. A known name autocompletes and checks its properties; any other name is a
- * custom event, unless {@link Register} sets `strict`. Names are stored exactly as written, so
- * `Purchase` and `purchase` are two events.
- */
-declare function track<Name extends TrackName>(name: Name, ...args: TrackArgs<Name>): void;
-/**
- * Links the visitor to a user id from your own system, on this event and every later one, across
- * visits. `null` clears it at sign-out. An empty or `undefined` id is ignored, so
- * `identify(user?.id)` before a session loads does not sign the visitor out.
- */
-declare function identify(id: UserId): void;
-/**
- * The id that joins a payment to this tab's visit. Pass it to the checkout as metadata
- * (`attribution_id`), and the payment provider's webhook credits the sale to the visit's source.
- * Resolves to `undefined`, so a checkout that awaits it never hangs: at once when the page has
- * no tracker script or its script fails to load (an ad blocker stopping it), after the timeout
- * when the script is still loading, and on a server or with tracking off.
- */
-declare function getAttributionId(options?: AttributionOptions): Promise<string | undefined>;
-/**
- * Adds the tracker's script tag to the page, once. A second call for the same site, such as a
- * component mounting again, finds the tag and does nothing. Does nothing on a server.
- */
-declare function inject(options: InjectOptions): void;
-//#endregion
-export { track as _, InjectOptions as a, Register as c, TrackArgs as d, TrackName as f, inject as g, identify as h, HighseatGlobal as i, Revenue as l, getAttributionId as m, BuiltInEvents as n, Properties as o, UserId as p, EventName as r, PropertyValue as s, AttributionOptions as t, SCRIPT_URL as u };
-//# sourceMappingURL=index2.d.ts.map