highseat 0.1.0-alpha.0 → 0.1.0-alpha.2

package/README.md

@@ -2,7 +2,7 @@
 
 Highseat analytics for JavaScript: typed tracking, a first-party proxy and framework components.
 
-> **Pre-release.** The `alpha` versions publish the package's shape so the release pipeline can be tested end to end. The functions are placeholders and do nothing yet. Use the script tag from your site's Installation settings until a stable version ships.
+> **Pre-release.** The `alpha` versions can change shape between releases.
 
 ## Install
 
@@ -14,13 +14,291 @@ npm install highseat@alpha
 
 | Import | Contents | Needs |
 | --- | --- | --- |
-| `highseat` | `track()` and `identify()` | Nothing |
+| `highseat` | `track()`, `identify()`, `getAttributionId()` and `inject()` | Nothing |
 | `highseat/react` | `<Highseat />` | React |
-| `highseat/next` | `<Highseat />` and `createProxy()` for Next.js | Next.js |
+| `highseat/next` | `<Highseat />`, `createProxy()` and `withHighseat()` for Next.js | Next.js |
 | `highseat/proxy` | `createProxy()`, a first-party proxy for any runtime with `fetch` | Nothing |
 
 Each entry point loads on its own and imports no framework it does not name, so `highseat/proxy` runs in a Cloudflare Worker without React installed.
 
+The package loads the tracker from Highseat, or from your site's proxy path, rather than bundling it. A call made before the tracker has loaded waits for it, and no call ever throws: on a server, with the tracker blocked, or with tracking off, it does nothing.
+
+## Next.js
+
+Set the site id from your site's Installation settings, and the proxy path for first-party delivery:
+
+```bash
+NEXT_PUBLIC_HIGHSEAT_SITE=site_…
+HIGHSEAT_PATH=/3f9a0c1e2b
+```
+
+Then render `<Highseat />` once, in the root layout:
+
+```tsx
+// app/layout.tsx
+import { Highseat } from "highseat/next"
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <Highseat />
+      </body>
+    </html>
+  )
+}
+```
+
+Without `HIGHSEAT_PATH`, `<Highseat />` loads the tracker from Highseat's host. The tracker counts each client-side navigation as one page view on its own.
+
+## React
+
+```tsx
+import { Highseat } from "highseat/react"
+
+<Highseat site="site_…" />
+```
+
+`src` takes the site's proxy path (`/3f9a0c1e2b`) for first-party delivery. `outbound={false}` and `downloads={false}` turn off the automatic link and download events, and `hashRouting` counts `#/route` changes as page views.
+
+Without React, `inject({ site })` from `highseat` adds the same script tag.
+
+## Events
+
+```ts
+import { identify, track } from "highseat"
+
+track("signup")
+track("purchase", { revenue: { amount: 4999, currency: "USD" }, order_id: order.id })
+identify(user.id)
+```
+
+`revenue.amount` is an integer in the currency's smallest unit: 4999 is $49.99. With a payment provider connected, send `purchase` without `revenue`: the provider's webhook records the money, and revenue sent from the page as well would count the sale twice. Send `revenue` only for a checkout no provider reports, with an `order_id`, so a provider sale added later for the same order is not counted again. Event names are stored exactly as written, so `Purchase` and `purchase` are two events.
+
+A few names are built in, with typed properties: `signup`, `login`, `purchase`, `subscription_started`, `trial_started`, `file_download`, `outbound_link_click` and `404`. Declare your own, and make a misspelt name a type error, by augmenting `Register` in any file your compiler sees:
+
+```ts
+declare module "highseat" {
+  interface Register {
+    events: {
+      signup: { plan: "free" | "pro" }
+      invite_sent: { role: "admin" | "member" }
+    }
+    strict: true
+  }
+}
+```
+
+Without `strict: true`, any other name still compiles as a custom event. The declarations are types only and add nothing to your bundle.
+
+## Revenue attribution
+
+`getAttributionId()` resolves to the id that joins a payment to the visit. Pass it to your checkout as `attribution_id` metadata. It resolves to `undefined` if the tracker has not loaded within three seconds, so a checkout that awaits it never hangs.
+
+```ts
+const attributionId = await getAttributionId()
+await createCheckout({ metadata: { attribution_id: attributionId } })
+```
+
+## First-party proxy
+
+The proxy serves the tracker and forwards its events from your own domain, on the site's own path, so a filter list that blocks Highseat's host does not block your site. A `GET` on the path serves the script and a `POST` forwards events. The proxy sends the visitor's IP under your site secret, which a rewrite or a redirect rule cannot do: without it, every visitor would get your server's country.
+
+Set two environment variables from your site's Installation settings:
+
+```bash
+HIGHSEAT_PATH=/3f9a0c1e2b        # the site's proxy path
+HIGHSEAT_SECRET=hs_secret_...    # the site secret
+```
+
+A missing variable never stops the site. Without the secret, or without the path on a handler with a `fallback`, `createProxy()` warns once and turns the proxy off: with a `fallback`, every request goes to it, and without one the proxy path answers `503` with a JSON `error` naming the variable. A local server without the variables therefore still starts and serves the site.
+
+Then load the tracker from the path. In Next.js, `<Highseat />` reads `HIGHSEAT_PATH` itself. Elsewhere, pass `src="/3f9a0c1e2b"` to `<Highseat />` or `inject()`, or use the script tag from Installation settings.
+
+To rotate the path, rotate it in Installation settings, update `HIGHSEAT_PATH` and the snippet, and redeploy. On a host whose route is a file or a config entry (Netlify, Vercel without Next.js, Astro), move that route too.
+
+### Options
+
+`createProxy(options)` returns a `(request: Request) => Promise<Response>` handler.
+
+| Option | Default | |
+| --- | --- | --- |
+| `clientIp` | Required | Where the visitor's IP comes from: `"vercel"`, `"cloudflare"`, `"netlify"`, `"nginx"` (the `X-Real-IP` header your nginx sets), or a function `(request) => string`. The outermost proxy that sets the header decides the preset: behind a proxied Cloudflare record, use `"cloudflare"` on any origin (Next.js, TanStack Start, a Node server, with or without Traefik or nginx in between), whose `X-Real-IP` holds a Cloudflare edge address. A visitor can write any header the host does not overwrite, so there is no default and no fallback to `X-Forwarded-For`. |
+| `path` | `HIGHSEAT_PATH` | The proxy path. Any other path answers 404, or goes to `fallback`. Leave it unset where your router already sends only the proxy path to the handler. |
+| `secret` | `HIGHSEAT_SECRET` | The site secret. An older secret that starts `hs_proxy_` or `ana_proxy_` works too. A value with neither prefix throws. |
+| `upstream` | `https://cdn.highseat.com` | The Highseat ingest origin. |
+| `fallback` | None | Answers every other path, for a handler that sees every request on the site. Needs `path`. |
+
+### Next.js
+
+```ts
+// app/api/highseat/route.ts
+import { createProxy } from "highseat/next"
+
+const proxy = createProxy({ clientIp: "vercel" })
+
+export { proxy as GET, proxy as POST }
+```
+
+```ts
+// next.config.ts
+import { withHighseat } from "highseat/next"
+
+export default withHighseat({
+  // Your own config.
+})
+```
+
+Next.js loads `next.config.ts` with `require`, and the package is ES modules only, so the config needs Node 20.19 or 22.12 and later, the versions that `require` an ES module without a flag.
+
+`withHighseat()` rewrites `HIGHSEAT_PATH` to the route handler inside the app, so the visitor's IP survives and the route file never moves. Pass `{ route: "/stats" }` for a handler elsewhere. Without `HIGHSEAT_PATH`, `next dev` and `next build` warn once and leave the rewrite out, and `next typegen` runs as usual. Set the variable for the build as well as the server: the rewrite is written at build time. Off Vercel, the outermost proxy that sets the header decides the preset: `"cloudflare"` behind a proxied Cloudflare record, even with nginx or Traefik in between, and `"nginx"` behind nginx alone.
+
+### Cloudflare Worker
+
+```ts
+import { createProxy } from "highseat/proxy"
+
+interface Env {
+  HIGHSEAT_PATH: string
+  HIGHSEAT_SECRET: string
+}
+
+export default {
+  fetch(request: Request, env: Env) {
+    const proxy = createProxy({
+      path: env.HIGHSEAT_PATH,
+      secret: env.HIGHSEAT_SECRET,
+      clientIp: "cloudflare",
+      fallback: fetch,
+    })
+    return proxy(request)
+  },
+}
+```
+
+Route the Worker on `yoursite.com/*`: `fallback: fetch` passes every other request on to your origin. Set the secret with `wrangler secret put HIGHSEAT_SECRET`.
+
+### Cloudflare Pages
+
+```ts
+// functions/[path].ts
+import { createProxy } from "highseat/proxy"
+
+interface Env {
+  HIGHSEAT_PATH: string
+  HIGHSEAT_SECRET: string
+}
+
+export const onRequest: PagesFunction<Env> = ({ request, env, next }) => {
+  const proxy = createProxy({
+    path: env.HIGHSEAT_PATH,
+    secret: env.HIGHSEAT_SECRET,
+    clientIp: "cloudflare",
+    fallback: next,
+  })
+  return proxy(request)
+}
+```
+
+The function sees each one-segment path, and `next` serves your site for every path but the proxy's. Add both variables in the Pages project's settings.
+
+### Netlify
+
+```ts
+// netlify/functions/highseat.ts
+import { createProxy } from "highseat/proxy"
+
+export const config = { path: "/3f9a0c1e2b" }
+
+export default createProxy({ clientIp: "netlify" })
+```
+
+Netlify reads `config.path` from the source, so it cannot come from an environment variable. Set only `HIGHSEAT_SECRET`.
+
+### Vercel without Next.js
+
+```ts
+// api/highseat.ts
+import { createProxy } from "highseat/proxy"
+
+const proxy = createProxy({ clientIp: "vercel" })
+
+export { proxy as GET, proxy as POST }
+```
+
+```json
+// vercel.json
+{ "rewrites": [{ "source": "/3f9a0c1e2b", "destination": "/api/highseat" }] }
+```
+
+The rewrite carries the path, so set only `HIGHSEAT_SECRET`.
+
+### Astro
+
+```ts
+// src/pages/3f9a0c1e2b.ts
+import type { APIRoute } from "astro"
+import { createProxy } from "highseat/proxy"
+
+export const prerender = false
+
+export const ALL: APIRoute = ({ request, clientAddress }) =>
+  createProxy({ clientIp: () => clientAddress })(request)
+```
+
+Needs a server adapter. The file name carries the path, so set only `HIGHSEAT_SECRET`. On the Cloudflare adapter, pass `secret: locals.runtime.env.HIGHSEAT_SECRET`.
+
+### Hono
+
+```ts
+import { Hono } from "hono"
+import { createProxy } from "highseat/proxy"
+
+const proxy = createProxy({ clientIp: "nginx" })
+const app = new Hono()
+
+app.all(process.env.HIGHSEAT_PATH!, context => proxy(context.req.raw))
+```
+
+The outermost proxy that sets the header decides the preset: `"cloudflare"` behind a proxied Cloudflare record, `"nginx"` behind nginx alone, or a function for a server facing visitors directly.
+
+### nginx
+
+For a host without functions, nginx forwards the same two headers. It reads no environment variables, so the secret is written into the config: keep the file out of version control.
+
+```nginx
+# A GET on the path loads the script; a POST goes to the events location below.
+location = /3f9a0c1e2b {
+    if ($request_method = POST) {
+        rewrite ^ /3f9a0c1e2b/events last;
+    }
+    proxy_pass https://cdn.highseat.com/script.js;
+    include highseat-proxy.conf;
+}
+
+location = /3f9a0c1e2b/events {
+    internal;
+    proxy_pass https://cdn.highseat.com/api/event;
+    include highseat-proxy.conf;
+}
+```
+
+```nginx
+# highseat-proxy.conf
+proxy_set_header Host cdn.highseat.com;
+proxy_ssl_server_name on;
+proxy_set_header X-Hs-Secret "hs_secret_...";
+# Behind Cloudflare or another edge, use $http_cf_connecting_ip instead.
+proxy_set_header X-Hs-Client-Ip $remote_addr;
+# An empty value keeps the visitor's own header from reaching Highseat.
+proxy_set_header Cookie "";
+proxy_set_header Authorization "";
+proxy_set_header Referer "";
+```
+
+A host with no functions and no server of its own, such as GitHub Pages or S3, loads the script from Highseat's host instead.
+
 ## Support
 
 Report a problem to [support@highseat.com](mailto:support@highseat.com). The source on GitHub, [highseat/highseat-js](https://github.com/highseat/highseat-js), is a read-only mirror and takes no issues or pull requests.

package/index.d.ts

@@ -1,11 +1,168 @@
 //#region src/index.d.ts
-/** A value an event property can hold. */
-export type PropertyValue = string | number | boolean;
-/** The properties sent with an event. */
-export type Properties = Record<string, PropertyValue>;
-/** Records a custom event. */
-export declare function track(_name: string, _properties?: Properties): void;
-/** Links the current visitor to a user id from your own system. */
-export declare function identify(_id: string): void;
+/**
+ * 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. */
+export 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.
+ */
+export 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. */
+export 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.
+ */
+export 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.
+ */
+export 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. */
+export 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.
+ */
+export 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.
+ */
+export type TrackArgs<Name extends string> = [Name] extends [EventName] ? {} extends KnownEvents[Name] ? [properties?: KnownEvents[Name]] : [properties: KnownEvents[Name]] : [properties?: Properties];
+/** The tracker's API on `window.highseat`, or the queue that stands in for it until it loads. */
+export interface HighseatGlobal {
+  /** Records an event. */
+  track?: (name: string, properties?: Properties) => void;
+  /** Sets or clears the visitor's user id. */
+  identify?: (id: string | number | null | undefined) => 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. */
+export 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. */
+export 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. */
+export 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.
+ */
+export 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.
+ */
+export declare function identify(id: string | number | null | undefined): 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.
+ */
+export 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.
+ */
+export declare function inject(options: InjectOptions): void;
 //#endregion
+export {};
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,9 +1,116 @@
 //#region src/index.ts
-/** Records a custom event. */
-function track(_name, _properties) {}
-/** Links the current visitor to a user id from your own system. */
-function identify(_id) {}
+/** Where the tracker loads from when the site has no proxy path. */
+const SCRIPT_URL = "https://cdn.highseat.com/script.js";
+const LIVE = Symbol.for("highseat");
+const SCRIPT_HOST = new URL(SCRIPT_URL).host;
+const PROXY_PATH = /^\/[0-9a-f]{10}$/;
+const ATTRIBUTION_TIMEOUT = 3e3;
+const ATTRIBUTION_POLL_INTERVAL = 50;
+const injectedScripts = /* @__PURE__ */ new WeakSet();
+const failedScripts = /* @__PURE__ */ new WeakSet();
+function findGlobal() {
+	if (typeof window === "undefined") return;
+	return window.highseat ??= {};
+}
+function isLive(api) {
+	return !!api && api[LIVE] === true;
+}
+function markFailed(event) {
+	failedScripts.add(event.currentTarget);
+}
+/**
+* Whether a script tag loads the tracker, judged as the tracker judges itself. Fathom's snippet
+* carries a `data-site` too, so a tag is matched by a `site_` id, or by a `src` on a proxy path
+* or on Highseat's host: an older site's id is a UUID, which any tool could use.
+*/
+function isTrackerScript(script) {
+	const { site } = script.dataset;
+	if (injectedScripts.has(script) || site?.startsWith("site_")) return true;
+	if (site === void 0) return false;
+	try {
+		const url = new URL(script.src, "http://localhost");
+		return url.host === SCRIPT_HOST || PROXY_PATH.test(url.pathname);
+	} catch {
+		return false;
+	}
+}
+function findTrackerScripts() {
+	return Array.from(document.scripts).filter(isTrackerScript);
+}
+function call(method, args) {
+	const api = findGlobal();
+	if (!api) return;
+	const handler = api[method];
+	if (typeof handler !== "function") {
+		api.q ??= [];
+		api.q.push([method, args]);
+		return;
+	}
+	try {
+		handler(...args);
+	} catch {}
+}
+/**
+* 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.
+*/
+function track(name, ...args) {
+	const [properties] = args;
+	call("track", properties === void 0 ? [name] : [name, properties]);
+}
+/**
+* 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.
+*/
+function identify(id) {
+	call("identify", [id]);
+}
+/**
+* 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.
+*/
+async function getAttributionId(options = {}) {
+	if (typeof window === "undefined" || typeof document === "undefined") return;
+	const deadline = Date.now() + (options.timeout ?? ATTRIBUTION_TIMEOUT);
+	let api = window.highseat;
+	while (!isLive(api)) {
+		if (Date.now() >= deadline) return;
+		const scripts = findTrackerScripts();
+		for (const script of scripts) script.addEventListener("error", markFailed);
+		if (scripts.every((script) => failedScripts.has(script))) return;
+		await new Promise((resolve) => setTimeout(resolve, ATTRIBUTION_POLL_INTERVAL));
+		api = window.highseat;
+	}
+	try {
+		return api.getAttributionId?.();
+	} catch {
+		return;
+	}
+}
+/**
+* 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.
+*/
+function inject(options) {
+	if (typeof document === "undefined") return;
+	const { site, src = SCRIPT_URL, outbound, downloads, hashRouting } = options;
+	if (Array.from(document.scripts).some((script) => script.dataset.site === site)) return;
+	const script = document.createElement("script");
+	script.addEventListener("error", markFailed);
+	injectedScripts.add(script);
+	script.src = src;
+	script.dataset.site = site;
+	if (outbound === false) script.dataset.outbound = "false";
+	if (downloads === false) script.dataset.downloads = "false";
+	if (hashRouting) script.dataset.hashRouting = "";
+	document.head.append(script);
+}
 //#endregion
-export { identify, track };
+export { SCRIPT_URL, getAttributionId, identify, inject, track };
 
 //# sourceMappingURL=index.js.map

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/** A value an event property can hold. */\nexport type PropertyValue = string | number | boolean\n\n/** The properties sent with an event. */\nexport type Properties = Record<string, PropertyValue>\n\n/** Records a custom event. */\nexport function track(_name: string, _properties?: Properties): void {}\n\n/** Links the current visitor to a user id from your own system. */\nexport function identify(_id: string): void {}\n"],"mappings":";;AAOA,SAAgB,MAAM,OAAe,aAAgC,CAAC;;AAGtE,SAAgB,SAAS,KAAmB,CAAC"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * The browser client. Every call goes to the hosted tracker on `window.highseat`; before the\n * tracker has loaded, calls wait in a queue the tracker drains on startup. Nothing here throws:\n * on a server, with the tracker blocked, or with tracking off, a call does nothing.\n */\n\n/** A value an event property can hold. A `null` or `undefined` value is left out of the event. */\nexport type PropertyValue = string | number | boolean | null | undefined\n\n/**\n * Money attached to an event. `amount` is an integer in the currency's smallest unit, so\n * `{ amount: 4999, currency: \"USD\" }` is $49.99 and `{ amount: 5000, currency: \"JPY\" }` is ¥5000.\n */\nexport interface Revenue {\n  /** An integer in minor units: 4999 for $49.99. An amount with decimals is rejected. */\n  amount: number\n  /** An ISO 4217 code, such as `USD` or `EUR`. */\n  currency: string\n}\n\n/** The properties of an event with no declared shape: any string keys, plus optional revenue. */\nexport interface Properties {\n  /** Money the event brought in. */\n  revenue?: Revenue\n  [key: string]: PropertyValue | Revenue\n}\n\n/**\n * The events Highseat knows by name. A site extends it, or overrides an entry, through\n * {@link Register}. Type-only: it adds nothing to the bundle.\n */\nexport interface BuiltInEvents {\n  /** A visitor created an account. */\n  signup: Properties\n  /** A visitor signed in. */\n  login: Properties\n  /**\n   * A sale. With a payment provider connected, leave `revenue` out: the provider's webhook\n   * records the money, and revenue sent here as well would count the sale twice. Send `revenue`\n   * only for a checkout no provider reports, and then with an `order_id`, so a provider sale\n   * added later for the same order is not counted again.\n   */\n  purchase: Properties\n  /** A paid subscription began. */\n  subscription_started: Properties\n  /** A free trial began. */\n  trial_started: Properties\n  /** A file download. The tracker records links to files on its own. */\n  file_download: { url: string }\n  /** A click on a link to another site. The tracker records these on its own. */\n  outbound_link_click: { url: string }\n  /** A visit to a missing page. Call it from a single-page app's not-found route. */\n  \"404\": Properties\n}\n\n/**\n * Declares a site's own events. Augment it from any file the compiler sees:\n *\n * ```ts\n * declare module \"highseat\" {\n *   interface Register {\n *     events: {\n *       signup: { plan: \"free\" | \"pro\" }\n *     }\n *     strict: true\n *   }\n * }\n * ```\n *\n * `events` adds names, or replaces a built-in one's properties. `strict: true` makes `track`\n * accept only built-in and registered names, so a misspelt name is a type error.\n */\nexport interface Register {}\n\n/**\n * A registered event's properties as `track` accepts them. A shape with no properties takes none,\n * and a property whose type an event cannot carry becomes `never`, so a call passing it fails\n * instead of sending `\"[object Object]\"`. The shape is not rejected at registration, where a\n * failed check would silently drop every registered event at once.\n */\ntype CheckedProperties<Shape> = [keyof Shape] extends [never]\n  ? Record<string, never>\n  : { [Key in keyof Shape]: Shape[Key] extends PropertyValue | Revenue ? Shape[Key] : never }\n\ntype RegisteredEvents = Register extends { events: infer Registered }\n  ? { [Name in keyof Registered]: CheckedProperties<Registered[Name]> }\n  : {}\n\ntype KnownEvents = Omit<BuiltInEvents, keyof RegisteredEvents> & RegisteredEvents\n\n/** Every event name `track` knows, built-in or registered. */\nexport type EventName = Extract<keyof KnownEvents, string>\n\n/**\n * The names `track` accepts: known names, and any other string unless the site is strict.\n * `string & {}` keeps the known names in the editor's suggestions, which a plain `string` in the\n * union would absorb.\n */\nexport type TrackName = Register extends { strict: true } ? EventName : EventName | (string & {})\n\n/**\n * The arguments after an event's name. A known name takes its declared properties, required\n * when any of them is; any other name takes {@link Properties}. Wrapped in tuples so a union of\n * names is checked as a whole rather than name by name.\n */\nexport type TrackArgs<Name extends string> = [Name] extends [EventName]\n  ? {} extends KnownEvents[Name]\n    ? [properties?: KnownEvents[Name]]\n    : [properties: KnownEvents[Name]]\n  : [properties?: Properties]\n\n/** The tracker's API on `window.highseat`, or the queue that stands in for it until it loads. */\nexport interface HighseatGlobal {\n  /** Records an event. */\n  track?: (name: string, properties?: Properties) => void\n  /** Sets or clears the visitor's user id. */\n  identify?: (id: string | number | null | undefined) => void\n  /** The id that joins a payment to this tab's visit. */\n  getAttributionId?: () => string | undefined\n  /** Calls made before the tracker loaded, drained in order when it starts. */\n  q?: [string, unknown[]][]\n}\n\n/** How long {@link getAttributionId} waits for the tracker. */\nexport interface AttributionOptions {\n  /** Milliseconds to wait for the tracker to load. Defaults to 3000. */\n  timeout?: number\n}\n\n/** How the tracker is loaded. Each option maps to an attribute on its script tag. */\nexport interface InjectOptions {\n  /** The site id, `site_…`, from the site's Installation settings. */\n  site: string\n  /**\n   * Where the script loads from: the site's proxy path (`/3f9a0c1e2b`) for first-party\n   * delivery, or a full URL. Defaults to Highseat's own host. The tracker posts its events back\n   * to the same place.\n   */\n  src?: string\n  /** Records clicks on links to other sites as `outbound_link_click`. Defaults to `true`. */\n  outbound?: boolean\n  /** Records clicks on links to files as `file_download`. Defaults to `true`. */\n  downloads?: boolean\n  /** Counts a change of `#/route` as a page view, for an app that routes by hash. */\n  hashRouting?: boolean\n}\n\ndeclare global {\n  interface Window {\n    highseat?: HighseatGlobal\n  }\n}\n\n/** Where the tracker loads from when the site has no proxy path. */\nexport const SCRIPT_URL = \"https://cdn.highseat.com/script.js\"\n\n// The tracker marks its own API with this symbol. A site's own stub can define methods too, so\n// only the symbol proves the tracker is running.\nconst LIVE = Symbol.for(\"highseat\")\n\nconst SCRIPT_HOST = new URL(SCRIPT_URL).host\n// A site's proxy path: `/` and ten hex characters.\nconst PROXY_PATH = /^\\/[0-9a-f]{10}$/\n\nconst ATTRIBUTION_TIMEOUT = 3000\nconst ATTRIBUTION_POLL_INTERVAL = 50\n\n// The script tags `inject` added, and every tracker script whose request failed, such as one an\n// ad blocker stopped. A browser keeps no record of a failed script, so a failure is only known\n// to a listener attached before it happened.\nconst injectedScripts = new WeakSet<HTMLScriptElement>()\nconst failedScripts = new WeakSet<HTMLScriptElement>()\n\nfunction findGlobal(): HighseatGlobal | undefined {\n  if (typeof window === \"undefined\") return\n  return (window.highseat ??= {})\n}\n\nfunction isLive(api: HighseatGlobal | undefined): api is HighseatGlobal {\n  return !!api && (api as Record<symbol, unknown>)[LIVE] === true\n}\n\n// One function for every script, so attaching it on each poll adds no second listener.\nfunction markFailed(event: Event) {\n  failedScripts.add(event.currentTarget as HTMLScriptElement)\n}\n\n/**\n * Whether a script tag loads the tracker, judged as the tracker judges itself. Fathom's snippet\n * carries a `data-site` too, so a tag is matched by a `site_` id, or by a `src` on a proxy path\n * or on Highseat's host: an older site's id is a UUID, which any tool could use.\n */\nfunction isTrackerScript(script: HTMLScriptElement) {\n  const { site } = script.dataset\n  if (injectedScripts.has(script) || site?.startsWith(\"site_\")) return true\n  if (site === undefined) return false\n\n  try {\n    // A browser hands back `src` resolved; the base only matters to a relative one.\n    const url = new URL(script.src, \"http://localhost\")\n    return url.host === SCRIPT_HOST || PROXY_PATH.test(url.pathname)\n  } catch {\n    return false\n  }\n}\n\nfunction findTrackerScripts() {\n  return Array.from(document.scripts).filter(isTrackerScript)\n}\n\nfunction call(method: \"track\" | \"identify\", args: unknown[]) {\n  const api = findGlobal()\n  if (!api) return\n\n  const handler = api[method] as ((...values: unknown[]) => void) | undefined\n  if (typeof handler !== \"function\") {\n    api.q ??= []\n    api.q.push([method, args])\n    return\n  }\n\n  try {\n    handler(...args)\n  } catch {}\n}\n\n/**\n * Records an event. A known name autocompletes and checks its properties; any other name is a\n * custom event, unless {@link Register} sets `strict`. Names are stored exactly as written, so\n * `Purchase` and `purchase` are two events.\n */\nexport function track<Name extends TrackName>(name: Name, ...args: TrackArgs<Name>): void {\n  const [properties] = args\n  call(\"track\", properties === undefined ? [name] : [name, properties])\n}\n\n/**\n * Links the visitor to a user id from your own system, on this event and every later one, across\n * visits. `null` clears it at sign-out. An empty or `undefined` id is ignored, so\n * `identify(user?.id)` before a session loads does not sign the visitor out.\n */\nexport function identify(id: string | number | null | undefined): void {\n  call(\"identify\", [id])\n}\n\n/**\n * The id that joins a payment to this tab's visit. Pass it to the checkout as metadata\n * (`attribution_id`), and the payment provider's webhook credits the sale to the visit's source.\n * Resolves to `undefined`, so a checkout that awaits it never hangs: at once when the page has\n * no tracker script or its script fails to load (an ad blocker stopping it), after the timeout\n * when the script is still loading, and on a server or with tracking off.\n */\nexport async function getAttributionId(\n  options: AttributionOptions = {},\n): Promise<string | undefined> {\n  if (typeof window === \"undefined\" || typeof document === \"undefined\") return\n\n  const deadline = Date.now() + (options.timeout ?? ATTRIBUTION_TIMEOUT)\n  let api = window.highseat\n\n  while (!isLive(api)) {\n    if (Date.now() >= deadline) return\n\n    const scripts = findTrackerScripts()\n    for (const script of scripts) script.addEventListener(\"error\", markFailed)\n    // No tracker script at all, or only failed ones: the tracker cannot arrive.\n    if (scripts.every(script => failedScripts.has(script))) return\n\n    await new Promise(resolve => setTimeout(resolve, ATTRIBUTION_POLL_INTERVAL))\n    api = window.highseat\n  }\n\n  try {\n    return api.getAttributionId?.()\n  } catch {\n    return\n  }\n}\n\n/**\n * Adds the tracker's script tag to the page, once. A second call for the same site, such as a\n * component mounting again, finds the tag and does nothing. Does nothing on a server.\n */\nexport function inject(options: InjectOptions): void {\n  if (typeof document === \"undefined\") return\n\n  const { site, src = SCRIPT_URL, outbound, downloads, hashRouting } = options\n  if (Array.from(document.scripts).some(script => script.dataset.site === site)) return\n\n  const script = document.createElement(\"script\")\n  script.addEventListener(\"error\", markFailed)\n  injectedScripts.add(script)\n  script.src = src\n  script.dataset.site = site\n  if (outbound === false) script.dataset.outbound = \"false\"\n  if (downloads === false) script.dataset.downloads = \"false\"\n  if (hashRouting) script.dataset.hashRouting = \"\"\n  document.head.append(script)\n}\n"],"mappings":"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"}

package/next.d.ts

@@ -1,3 +1,60 @@
-import { ProxyHandler, ProxyOptions, createProxy } from "./proxy.js";
-import { Highseat, HighseatProps } from "./react.js";
-export { Highseat, type HighseatProps, type ProxyHandler, type ProxyOptions, createProxy };
+import { InjectOptions } from "./index.js";
+import { ClientIp, ClientIpPreset, ProxyHandler, ProxyOptions, createProxy } from "./proxy.js";
+import { ReactElement } from "react";
+//#region src/next.d.ts
+export interface HighseatProps extends Partial<InjectOptions> {}
+/**
+ * Loads the Highseat tracker in a Next.js app. Render it once, in the root layout. The site id
+ * comes from `NEXT_PUBLIC_HIGHSEAT_SITE`, and the script loads from the site's proxy path in
+ * `HIGHSEAT_PATH` when one is set. `HIGHSEAT_PATH` is a server variable, so in the Pages Router,
+ * where the layout also renders in the browser, pass `src` instead. A prop wins over its variable.
+ */
+export declare function Highseat(props: HighseatProps): ReactElement | null;
+/** A Next.js rewrite: the subset of its fields this package writes and reads. */
+interface Rewrite {
+  source: string;
+  destination: string;
+}
+/** The phases Next.js applies rewrites in, when `rewrites()` returns an object. */
+interface RewritePhases {
+  beforeFiles?: Rewrite[];
+  afterFiles?: Rewrite[];
+  fallback?: Rewrite[];
+}
+/** A Next.js config with the proxy's rewrite added, or its own rewrites when there is no path. */
+export type WithHighseatConfig<Config> = Config & {
+  rewrites: () => Promise<Rewrite[] | RewritePhases>;
+};
+export interface WithHighseatOptions {
+  /**
+   * The site's proxy path from Installation settings. Defaults to the `HIGHSEAT_PATH`
+   * environment variable, the one `createProxy()` reads, so rotating the path is an
+   * environment change and a redeploy.
+   */
+  path?: string;
+  /**
+   * Where the app's proxy route handler lives. Defaults to `/api/highseat`, the route of
+   * `app/api/highseat/route.ts`.
+   */
+  route?: string;
+}
+/**
+ * Adds a rewrite from the site's proxy path to the app's proxy route handler, ahead of every
+ * other route. The rewrite stays inside the app, so the handler still sees the visitor's IP, and
+ * the route file never moves when the path rotates.
+ *
+ * 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.
+ *
+ * ```ts
+ * // next.config.ts
+ * import { withHighseat } from "highseat/next"
+ * export default withHighseat({ reactStrictMode: true })
+ * ```
+ */
+export declare function withHighseat<Config extends object>(config: Config, options?: WithHighseatOptions): WithHighseatConfig<Config>;
+//#endregion
+export { type ClientIp, type ClientIpPreset, type ProxyHandler, type ProxyOptions, createProxy };
+//# sourceMappingURL=next.d.ts.map

package/next.js

@@ -1,3 +1,79 @@
-import { Highseat } from "./react.js";
-import { createProxy } from "./proxy.js";
-export { Highseat, createProxy };
+import { Highseat as Highseat$1 } from "./react.js";
+import { n as findNextSite, r as findProxyPath, t as createProxy } from "./proxy2.js";
+import { createElement } from "react";
+//#region src/next.ts
+/**
+* Loads the Highseat tracker in a Next.js app. Render it once, in the root layout. The site id
+* comes from `NEXT_PUBLIC_HIGHSEAT_SITE`, and the script loads from the site's proxy path in
+* `HIGHSEAT_PATH` when one is set. `HIGHSEAT_PATH` is a server variable, so in the Pages Router,
+* where the layout also renders in the browser, pass `src` instead. A prop wins over its variable.
+*/
+function Highseat(props) {
+	const site = props.site ?? findNextSite();
+	const src = props.src ?? findProxyPath();
+	if (!site) {
+		console.warn("highseat: set NEXT_PUBLIC_HIGHSEAT_SITE, or pass `site` to <Highseat />");
+		return null;
+	}
+	return createElement(Highseat$1, {
+		...props,
+		site,
+		src
+	});
+}
+const DEFAULT_ROUTE = "/api/highseat";
+let hasWarnedNoPath = false;
+/**
+* Adds a rewrite from the site's proxy path to the app's proxy route handler, ahead of every
+* other route. The rewrite stays inside the app, so the handler still sees the visitor's IP, and
+* the route file never moves when the path rotates.
+*
+* 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.
+*
+* ```ts
+* // next.config.ts
+* import { withHighseat } from "highseat/next"
+* export default withHighseat({ reactStrictMode: true })
+* ```
+*/
+function withHighseat(config, options = {}) {
+	const path = findProxyPath(options.path);
+	const { rewrites: ownRewrites } = config;
+	async function passRewritesThrough() {
+		if (!hasWarnedNoPath) {
+			hasWarnedNoPath = true;
+			console.warn("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.");
+		}
+		return await ownRewrites?.() ?? [];
+	}
+	if (!path) return {
+		...config,
+		rewrites: passRewritesThrough
+	};
+	const rewrite = {
+		source: path,
+		destination: options.route ?? DEFAULT_ROUTE
+	};
+	async function rewrites() {
+		const existing = await ownRewrites?.() ?? [];
+		if (Array.isArray(existing)) return {
+			beforeFiles: [rewrite],
+			afterFiles: existing
+		};
+		return {
+			...existing,
+			beforeFiles: [rewrite, ...existing.beforeFiles ?? []]
+		};
+	}
+	return {
+		...config,
+		rewrites
+	};
+}
+//#endregion
+export { Highseat, createProxy, withHighseat };
+
+//# sourceMappingURL=next.js.map

package/next.js.map

@@ -0,0 +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 type { InjectOptions } from \"./index\"\nimport { Highseat as ReactHighseat } from \"./react\"\n\nexport { createProxy } from \"./proxy\"\nexport type { ClientIp, ClientIpPreset, ProxyHandler, ProxyOptions } from \"./proxy\"\n\nexport interface HighseatProps extends Partial<InjectOptions> {}\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 */\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":";;;;;;;;;;AAgBA,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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "highseat",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "description": "Highseat analytics for JavaScript: typed tracking, a first-party proxy and framework components.",
   "keywords": [
     "analytics",
@@ -25,19 +25,19 @@
   "exports": {
     ".": {
       "types": "./index.d.ts",
-      "import": "./index.js"
+      "default": "./index.js"
     },
     "./react": {
       "types": "./react.d.ts",
-      "import": "./react.js"
+      "default": "./react.js"
     },
     "./next": {
       "types": "./next.d.ts",
-      "import": "./next.js"
+      "default": "./next.js"
     },
     "./proxy": {
       "types": "./proxy.d.ts",
-      "import": "./proxy.js"
+      "default": "./proxy.js"
     }
   },
   "publishConfig": {
@@ -56,7 +56,7 @@
     }
   },
   "engines": {
-    "node": ">=18"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "main": "./index.js",
   "module": "./index.js",

package/proxy.d.ts

@@ -1,15 +1,60 @@
 //#region src/proxy.d.ts
+/** A host whose own header carries the visitor's IP. */
+export type ClientIpPreset = "vercel" | "cloudflare" | "netlify" | "nginx";
+/**
+ * Where the proxy reads the visitor's IP: a host preset, or a function for any other setup. A
+ * function returns the IP, or nothing when the request carries none.
+ */
+export type ClientIp = ClientIpPreset | ((request: Request) => string | null | undefined);
 export interface ProxyOptions {
-  /** The site's proxy path. */
+  /**
+   * The site's proxy path from Installation settings, such as `/3f9a0c1e2b`, with or without its
+   * leading slash. A request on any
+   * other path is answered 404, or handed to `fallback`. Defaults to the `HIGHSEAT_PATH`
+   * environment variable. Leave both unset on a host whose router already sends only the proxy
+   * path here, such as a file named after the path.
+   */
   path?: string;
-  /** The site secret, `hs_secret_…`. */
+  /**
+   * The site secret, `hs_secret_…`, or an older one that starts `hs_proxy_` or `ana_proxy_`.
+   * Defaults to the `HIGHSEAT_SECRET` environment variable. Without one the proxy is off: the
+   * proxy path answers 503, or every request goes to `fallback`.
+   */
   secret?: string;
-  /** The ingest origin the proxy forwards to. */
+  /**
+   * Where the visitor's IP comes from: `vercel`, `cloudflare`, `netlify`, `nginx` (the
+   * `X-Real-IP` header your nginx sets), or a function. A visitor can write any header the host
+   * does not overwrite, so there is no default.
+   *
+   * The outermost proxy that sets the header decides the preset. Behind a proxied Cloudflare
+   * record, use `cloudflare` on any origin, not only a Worker or a Pages Function: a Next.js,
+   * TanStack Start or Node server behind Cloudflare, with or without Traefik or nginx in between,
+   * sees a Cloudflare edge address in `X-Real-IP`, and the visitor's IP in `cf-connecting-ip`.
+   */
+  clientIp: ClientIp;
+  /** The ingest origin the proxy forwards to. Defaults to `https://cdn.highseat.com`. */
   upstream?: string;
+  /**
+   * Answers a request on any path other than `path`, for a handler that sees every request on
+   * the site: `fetch` in a Cloudflare Worker routed on the whole site, `next` in a Pages
+   * Function. Needs `path`: without it, or without the secret, the proxy is off and every
+   * request goes here, so the site still serves in a development setup without the variables.
+   */
+  fallback?: (request: Request) => Response | Promise<Response>;
 }
 /** A fetch handler, the shape every supported runtime and framework route accepts. */
 export type ProxyHandler = (request: Request) => Promise<Response>;
-/** Creates the first-party proxy handler for a site. */
-export declare function createProxy(_options?: ProxyOptions): ProxyHandler;
+/**
+ * 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.
+ */
+export declare function createProxy(options: ProxyOptions): ProxyHandler;
 //#endregion
 //# sourceMappingURL=proxy.d.ts.map

package/proxy.js

@@ -1,9 +1 @@
-//#region src/proxy.ts
-/** Creates the first-party proxy handler for a site. */
-function createProxy(_options = {}) {
-	return async () => new Response("Not implemented", { status: 501 });
-}
-//#endregion
-export { createProxy };
-
-//# sourceMappingURL=proxy.js.map
+export { t as createProxy } from "./proxy2.js";

package/proxy2.js

@@ -0,0 +1,235 @@
+//#region src/env.ts
+/**
+* The variables the package reads from a customer's environment. Each is named in full, never
+* looked up by a computed key: Next.js inlines a `NEXT_PUBLIC_` variable into browser code only
+* where the source spells out `process.env.NEXT_PUBLIC_…`. The server variables return
+* `undefined` where the runtime has no `process`: a Cloudflare Worker without `nodejs_compat`,
+* whose options carry the values instead.
+*/
+/** The site id for `<Highseat />` in Next.js. Public, so it reaches the browser. */
+function findNextSite() {
+	return process.env.NEXT_PUBLIC_HIGHSEAT_SITE;
+}
+/**
+* The site's proxy path: `option` when given, else `HIGHSEAT_PATH`, a server variable shared by
+* `<Highseat />`, `withHighseat()` and the proxy handler. A value written without its leading
+* slash gets one, as Installation settings shows it (`/3f9a0c1e2b`). An empty value counts as
+* unset.
+*/
+function findProxyPath(option) {
+	const path = option ?? (typeof process === "undefined" ? void 0 : process.env.HIGHSEAT_PATH);
+	if (!path) return;
+	return path.startsWith("/") ? path : `/${path}`;
+}
+/** The site secret for the proxy handler. */
+function findSecret() {
+	if (typeof process === "undefined") return;
+	return process.env.HIGHSEAT_SECRET;
+}
+/**
+* Whether this runs inside `next build`, which loads every route without serving one. Set in the
+* build's route workers only: `next.config.ts` receives the phase as an argument instead.
+*/
+function isNextBuild() {
+	if (typeof process === "undefined") return false;
+	return process.env.NEXT_PHASE === "phase-production-build";
+}
+//#endregion
+//#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 { findNextSite as n, findProxyPath as r, createProxy as t };
+
+//# sourceMappingURL=proxy2.js.map

package/proxy2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy2.js","names":[],"sources":["../src/env.ts","../src/proxy.ts"],"sourcesContent":["/**\n * The variables the package reads from a customer's environment. Each is named in full, never\n * looked up by a computed key: Next.js inlines a `NEXT_PUBLIC_` variable into browser code only\n * where the source spells out `process.env.NEXT_PUBLIC_…`. The server variables return\n * `undefined` where the runtime has no `process`: a Cloudflare Worker without `nodejs_compat`,\n * whose options carry the values instead.\n */\n\n/** The site id for `<Highseat />` in Next.js. Public, so it reaches the browser. */\nexport function findNextSite(): string | undefined {\n  return process.env.NEXT_PUBLIC_HIGHSEAT_SITE\n}\n\n/**\n * The site's proxy path: `option` when given, else `HIGHSEAT_PATH`, a server variable shared by\n * `<Highseat />`, `withHighseat()` and the proxy handler. A value written without its leading\n * slash gets one, as Installation settings shows it (`/3f9a0c1e2b`). An empty value counts as\n * unset.\n */\nexport function findProxyPath(option?: string): string | undefined {\n  const path = option ?? (typeof process === \"undefined\" ? undefined : process.env.HIGHSEAT_PATH)\n  if (!path) return\n  return path.startsWith(\"/\") ? path : `/${path}`\n}\n\n/** The site secret for the proxy handler. */\nexport function findSecret(): string | undefined {\n  if (typeof process === \"undefined\") return\n  return process.env.HIGHSEAT_SECRET\n}\n\n/**\n * Whether this runs inside `next build`, which loads every route without serving one. Set in the\n * build's route workers only: `next.config.ts` receives the phase as an argument instead.\n */\nexport function isNextBuild(): boolean {\n  if (typeof process === \"undefined\") return false\n  return process.env.NEXT_PHASE === \"phase-production-build\"\n}\n","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,11 +1,11 @@
+import { InjectOptions } from "./index.js";
 //#region src/react.d.ts
-export interface HighseatProps {
-  /** The site id, `site_…`. */
-  site: string;
-  /** The script URL, when the tracker is served from your own path. */
-  src?: string;
-}
-/** Loads the Highseat tracker on the page. */
-export declare function Highseat(_props: HighseatProps): null;
+export interface HighseatProps extends InjectOptions {}
+/**
+ * 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.
+ */
+export declare function Highseat({ site, src, outbound, downloads, hashRouting }: HighseatProps): null;
 //#endregion
 //# sourceMappingURL=react.d.ts.map

package/react.js

@@ -1,6 +1,28 @@
+"use client";
+import { inject } from "./index.js";
+import { useEffect } from "react";
 //#region src/react.ts
-/** Loads the Highseat tracker on the page. */
-function Highseat(_props) {
+/**
+* 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.
+*/
+function Highseat({ site, src, outbound, downloads, hashRouting }) {
+	useEffect(() => {
+		inject({
+			site,
+			src,
+			outbound,
+			downloads,
+			hashRouting
+		});
+	}, [
+		site,
+		src,
+		outbound,
+		downloads,
+		hashRouting
+	]);
 	return null;
 }
 //#endregion

package/react.js.map

@@ -1 +1 @@
-{"version":3,"file":"react.js","names":[],"sources":["../src/react.ts"],"sourcesContent":["export interface HighseatProps {\n  /** The site id, `site_…`. */\n  site: string\n  /** The script URL, when the tracker is served from your own path. */\n  src?: string\n}\n\n/** Loads the Highseat tracker on the page. */\nexport function Highseat(_props: HighseatProps): null {\n  return null\n}\n"],"mappings":";;AAQA,SAAgB,SAAS,QAA6B;CACpD,OAAO;AACT"}
+{"version":3,"file":"react.js","names":[],"sources":["../src/react.ts"],"sourcesContent":["\"use client\"\n\nimport { useEffect } from \"react\"\nimport { inject, type InjectOptions } from \"./index\"\n\nexport interface HighseatProps extends InjectOptions {}\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.\n */\nexport function Highseat({ site, src, outbound, downloads, hashRouting }: HighseatProps): null {\n  useEffect(() => {\n    inject({ site, src, outbound, downloads, hashRouting })\n  }, [site, src, outbound, downloads, hashRouting])\n\n  return null\n}\n"],"mappings":";;;;;;;;;AAYA,SAAgB,SAAS,EAAE,MAAM,KAAK,UAAU,WAAW,eAAoC;CAC7F,gBAAgB;EACd,OAAO;GAAE;GAAM;GAAK;GAAU;GAAW;EAAY,CAAC;CACxD,GAAG;EAAC;EAAM;EAAK;EAAU;EAAW;CAAW,CAAC;CAEhD,OAAO;AACT"}

package/proxy.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"proxy.js","names":[],"sources":["../src/proxy.ts"],"sourcesContent":["export interface ProxyOptions {\n  /** The site's proxy path. */\n  path?: string\n  /** The site secret, `hs_secret_…`. */\n  secret?: string\n  /** The ingest origin the proxy forwards to. */\n  upstream?: string\n}\n\n/** A fetch handler, the shape every supported runtime and framework route accepts. */\nexport type ProxyHandler = (request: Request) => Promise<Response>\n\n/** Creates the first-party proxy handler for a site. */\nexport function createProxy(_options: ProxyOptions = {}): ProxyHandler {\n  return async () => new Response(\"Not implemented\", { status: 501 })\n}\n"],"mappings":";;AAaA,SAAgB,YAAY,WAAyB,CAAC,GAAiB;CACrE,OAAO,YAAY,IAAI,SAAS,mBAAmB,EAAE,QAAQ,IAAI,CAAC;AACpE"}