highseat 0.3.1 → 0.5.0

package/README.md

@@ -12,12 +12,13 @@ npm install highseat
 
 | Import | Contents | Needs |
 | --- | --- | --- |
-| `highseat` | `track()`, `identify()`, `getAttributionId()` and `inject()` | Nothing |
-| `highseat/react` | `<Highseat />` and `useIdentify()` | React |
-| `highseat/next` | `<Highseat />`, `useIdentify()`, `createProxy()` and `withHighseat()` for Next.js | Next.js |
+| `highseat` | `track()`, `identify()`, `getAttributionId()`, `inject()` and `setBeforeSend()` | Nothing |
+| `highseat/react` | `<Highseat />`, `useIdentify()` and `useBeforeSend()` | React |
+| `highseat/next` | `<Highseat />`, `useIdentify()`, `useBeforeSend()`, `createProxy()` and `withHighseat()` for Next.js | Next.js |
 | `highseat/proxy` | `createProxy()`, a first-party proxy for any runtime with `fetch` | Nothing |
+| `highseat/server` | `track()`, `flush()`, `close()` and `createTracker()`, for events sent from your backend | 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.
+Each entry point loads on its own and imports no framework it does not name, so `highseat/proxy` and `highseat/server` run 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.
 
@@ -165,6 +166,59 @@ The value has to tell loading apart from signed out. `useIdentify(session?.user.
 
 Without React, call `identify()` from `highseat` after each sign-in and sign-out.
 
+## Redact or drop events
+
+A page URL can carry a secret: a password-reset token in the path, an email address in the query. A `beforeSend` hook runs in the browser on every event before the tracker sends it, page views from client-side navigation included. Return the event, changed or not, or `null` to drop it. The hook can change the URL, the referrer and the properties, and the page path follows the URL it returns. It cannot change the site or the user id.
+
+```ts
+import type { BeforeSendEvent } from "highseat"
+
+// Strips `email` from the query and templates the reset token, in the URL and the referrer.
+function redact(value: string) {
+  const url = new URL(value)
+  url.searchParams.delete("email")
+  url.pathname = url.pathname.replace(/^\/reset\/[^/]+/, "/reset/:token")
+  return url.href
+}
+
+export function beforeSend(event: BeforeSendEvent) {
+  // Drops every event on the admin pages, so an in-app navigation there sends nothing.
+  if (new URL(event.url).pathname.startsWith("/admin/")) return null
+  return { ...event, url: redact(event.url), referrer: event.referrer && redact(event.referrer) }
+}
+```
+
+A hook that throws drops the event, since sending it unchanged would leak what the hook was there to remove. The error still reaches the console. Returning nothing drops the event too.
+
+A function cannot pass from a server component to the browser, so in a Next.js App Router layout, set the hook with `useBeforeSend()` in a client component rendered beside `<Highseat />`:
+
+```tsx
+"use client"
+
+import { useBeforeSend } from "highseat/next"
+import { beforeSend } from "~/lib/analytics"
+
+export function Redact() {
+  useBeforeSend(beforeSend)
+  return null
+}
+```
+
+`highseat/react` takes the hook as a prop, `<Highseat site="site_…" beforeSend={beforeSend} />`, and `inject({ site, beforeSend })` takes it as an option. `setBeforeSend()` from `highseat` sets or clears it at any time. Each of them works before the tracker has loaded, and the first page view already passes through the hook.
+
+A site with only the script tag sets the hook on `window.highseat` in a script before the tracker's tag:
+
+```html
+<script>
+  window.highseat = {
+    beforeSend(event) {
+      return new URL(event.url).pathname.startsWith("/admin/") ? null : event
+    },
+  }
+</script>
+<script defer src="https://cdn.highseat.com/script.js" data-site="site_…"></script>
+```
+
 ## 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.
@@ -174,6 +228,106 @@ const attributionId = await getAttributionId()
 await createCheckout({ metadata: { attribution_id: attributionId } })
 ```
 
+## Server-side events
+
+`highseat/server` records an event from your own backend: a server action, a route handler, a webhook handler or a job. It sends with the site secret, so set both variables from your site's Installation settings on the server:
+
+```bash
+HIGHSEAT_SITE=site_…              # NEXT_PUBLIC_HIGHSEAT_SITE works too
+HIGHSEAT_SECRET=hs_secret_...
+```
+
+Pass the request you are handling, and the event takes the visitor's IP, user agent and hostname from it, so it gets their country and device:
+
+```ts
+import { track } from "highseat/server"
+
+export async function POST(request: Request) {
+  const user = await createAccount(request)
+  track("signup", { plan: "pro" }, { request, userId: user.id })
+  return Response.json(user)
+}
+```
+
+In a Next.js server action, pass the headers instead:
+
+```ts
+"use server"
+
+import { headers } from "next/headers"
+import { track } from "highseat/server"
+
+export async function subscribe(plan: string) {
+  track("subscription_started", { plan }, { headers: await headers() })
+}
+```
+
+`track()` takes the same names and properties as in the browser, checked by the same `Register`. It returns at once and never throws. Events wait up to a second to share a request, at most 25 to one, and go one request at a time. A batch Highseat answers `429` or `5xx`, or never answers, is retried with backoff, honoring `Retry-After`, and the events behind it wait. Every event gets a UUID, so a retried batch is stored once. Up to 1000 events wait during an outage. A newer one is reported to `onError` and not kept.
+
+An event no visitor caused, from a job or a webhook, leaves the request out. With a `userId` it counts as that user, and without one as a visitor of its own:
+
+```ts
+track("invoice_paid", { plan: "pro" }, { userId: customer.id, eventId: stripeEvent.id, hostname: "example.com" })
+```
+
+Pass an id your system already holds as `eventId` (a job id, a webhook event id), and a retry of the same event within three days is stored once. `timestamp` dates an event that happened earlier, up to a day ago.
+
+### Serverless functions
+
+A serverless function can stop as soon as it answers, before a batch leaves. Pass `waitUntil`, and the event is sent at once while the function stays alive until it lands:
+
+```ts
+import { waitUntil } from "@vercel/functions"
+
+track("signup", undefined, { request, userId: user.id, waitUntil })
+```
+
+In a Cloudflare Worker, pass `waitUntil: promise => ctx.waitUntil(promise)`, and in a Netlify function `context.waitUntil`. A script or a test that exits on its own awaits `flush()` first. A long-running server calls `close()` at shutdown, which sends what is queued. During an outage that can take minutes of retries, so give it a deadline inside your shutdown's grace period:
+
+```ts
+process.on("SIGTERM", async () => {
+  await close({ timeout: 5000 })
+  process.exit(0)
+})
+```
+
+Past the deadline, `close()` stops sending, reports the events not confirmed sent to `onError`, and resolves.
+
+### Your own tracker
+
+`createTracker(options)` returns a tracker with its own `track()`, `flush()` and `close()`, for credentials or a `fetch` of your own, or several sites in one process:
+
+```ts
+import { createTracker } from "highseat/server"
+
+const tracker = createTracker({
+  hostname: "example.com",
+  onError: error => logger.warn(error.message, { events: error.events }),
+})
+
+tracker.track("tier_created", { tier: "gold" }, { userId: publisher.id, ip, userAgent })
+```
+
+| Option | Default | |
+| --- | --- | --- |
+| `site` | `HIGHSEAT_SITE`, then `NEXT_PUBLIC_HIGHSEAT_SITE` | The site id. |
+| `secret` | `HIGHSEAT_SECRET` | The site secret. A value that is not one throws. Without the site or the secret, the tracker warns once and sends nothing. |
+| `hostname` | The request's host | The hostname events are filed under. An event's own `hostname` wins. |
+| `clientIp` | `"cloudflare"` in a Worker, `"vercel"` on Vercel, `"netlify"` on Netlify | Where the visitor's IP is read from a request, as for `createProxy()`. Those three hosts overwrite their header, so a visitor cannot forge it. Anywhere else, set it or pass `ip` with each event: without either, an event carries no IP and no country. |
+| `waitUntil` | None | Sends every event at once, as above. |
+| `onError` | `console.warn` | Receives each failure. `type` is `"rejected"` for events Highseat refused as invalid, `"dropped"` for events it accepted but did not store (a hostname that is not the site's, a bot, excluded traffic), each with its `reason`, or `"failed"` for events that never landed, were refused whole (a wrong secret), or were left at `close()`'s deadline. A retry Highseat recognised as already stored is not a failure. |
+| `fetch` | The global `fetch` | The `fetch` events are sent with, such as a mock in tests. |
+| `upstream` | `https://cdn.highseat.com` | The Highseat ingest origin. |
+| `flushInterval` | `1000` | Milliseconds an event waits for others to share its request. |
+| `maxRetries` | `4` | Retries of a batch before it is reported as failed. |
+| `timeout` | `10000` | Milliseconds one request may take. |
+
+Each event takes `request` or `headers`, then `ip`, `userAgent`, `userId`, `hostname`, `url`, `referrer`, `eventId`, `timestamp` and `waitUntil`. An explicit `ip` or `userAgent` wins over the request's. A `pageview` takes its `url` and `referrer` from the request too.
+
+### Without the package
+
+Any language can send the same request. `POST https://cdn.highseat.com/api/event` with `x-site-id` and `x-hs-secret` headers and a JSON array of up to 25 events. Each event names `event_name`, `hostname` (or a `page_url`), and optionally `event_id`, `user_id`, `ip`, `user_agent`, `page_url`, `referrer`, `properties` (string values) and `revenue`. The answer lists each refused event in `rejections` and each event it did not store in `dropped`, by its index in the batch.
+
 ## 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.

package/env.js

@@ -21,7 +21,24 @@ function findProxyPath(option) {
 	if (!path) return;
 	return path.startsWith("/") ? path : `/${path}`;
 }
-/** The site secret for the proxy handler. */
+/**
+* The site id for `highseat/server`: `HIGHSEAT_SITE`, else the Next.js variable `<Highseat />`
+* reads, so a Next.js app sets it once.
+*/
+function findServerSite() {
+	if (typeof process === "undefined") return;
+	return process.env.HIGHSEAT_SITE ?? process.env.NEXT_PUBLIC_HIGHSEAT_SITE;
+}
+/**
+* The host the server runs on, when its platform sets a variable that says so and a header of
+* its own carries the visitor's IP.
+*/
+function findHostPlatform() {
+	if (typeof process === "undefined") return;
+	if (process.env.VERCEL) return "vercel";
+	if (process.env.NETLIFY) return "netlify";
+}
+/** The site secret for the proxy handler and `highseat/server`. */
 function findSecret() {
 	if (typeof process === "undefined") return;
 	return process.env.HIGHSEAT_SECRET;
@@ -46,6 +63,6 @@ function isDevelopment() {
 	}
 }
 //#endregion
-export { findNextSite, findProxyPath, findSecret, isDevelopment, isNextBuild };
+export { findHostPlatform, findNextSite, findProxyPath, findSecret, findServerSite, isDevelopment, isNextBuild };
 
 //# sourceMappingURL=env.js.map

package/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","names":[],"sources":["../src/env.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\n/**\n * Whether the build runs in development. A bundler replaces `process.env.NODE_ENV` with a\n * literal. A browser without that replacement has no `process`, so the read throws.\n */\nexport function isDevelopment(): boolean {\n  try {\n    return process.env.NODE_ENV === \"development\"\n  } catch {\n    return false\n  }\n}\n"],"mappings":";;;;;;;;;AASA,SAAgB,eAAmC;CACjD,OAAO,QAAQ,IAAI;AACrB;;;;;;;AAQA,SAAgB,cAAc,QAAqC;CACjE,MAAM,OAAO,WAAW,OAAO,YAAY,cAAc,KAAA,IAAY,QAAQ,IAAI;CACjF,IAAI,CAAC,MAAM;CACX,OAAO,KAAK,WAAW,GAAG,IAAI,OAAO,IAAI;AAC3C;;AAGA,SAAgB,aAAiC;CAC/C,IAAI,OAAO,YAAY,aAAa;CACpC,OAAO,QAAQ,IAAI;AACrB;;;;;AAMA,SAAgB,cAAuB;CACrC,IAAI,OAAO,YAAY,aAAa,OAAO;CAC3C,OAAO,QAAQ,IAAI,eAAe;AACpC;;;;;AAMA,SAAgB,gBAAyB;CACvC,IAAI;EACF,OAAO,QAAQ,IAAI,aAAa;CAClC,QAAQ;EACN,OAAO;CACT;AACF"}
+{"version":3,"file":"env.js","names":[],"sources":["../src/env.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/**\n * The site id for `highseat/server`: `HIGHSEAT_SITE`, else the Next.js variable `<Highseat />`\n * reads, so a Next.js app sets it once.\n */\nexport function findServerSite(): string | undefined {\n  if (typeof process === \"undefined\") return\n  return process.env.HIGHSEAT_SITE ?? process.env.NEXT_PUBLIC_HIGHSEAT_SITE\n}\n\n/**\n * The host the server runs on, when its platform sets a variable that says so and a header of\n * its own carries the visitor's IP.\n */\nexport function findHostPlatform(): \"vercel\" | \"netlify\" | undefined {\n  if (typeof process === \"undefined\") return\n  if (process.env.VERCEL) return \"vercel\"\n  if (process.env.NETLIFY) return \"netlify\"\n  return\n}\n\n/** The site secret for the proxy handler and `highseat/server`. */\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\n/**\n * Whether the build runs in development. A bundler replaces `process.env.NODE_ENV` with a\n * literal. A browser without that replacement has no `process`, so the read throws.\n */\nexport function isDevelopment(): boolean {\n  try {\n    return process.env.NODE_ENV === \"development\"\n  } catch {\n    return false\n  }\n}\n"],"mappings":";;;;;;;;;AASA,SAAgB,eAAmC;CACjD,OAAO,QAAQ,IAAI;AACrB;;;;;;;AAQA,SAAgB,cAAc,QAAqC;CACjE,MAAM,OAAO,WAAW,OAAO,YAAY,cAAc,KAAA,IAAY,QAAQ,IAAI;CACjF,IAAI,CAAC,MAAM;CACX,OAAO,KAAK,WAAW,GAAG,IAAI,OAAO,IAAI;AAC3C;;;;;AAMA,SAAgB,iBAAqC;CACnD,IAAI,OAAO,YAAY,aAAa;CACpC,OAAO,QAAQ,IAAI,iBAAiB,QAAQ,IAAI;AAClD;;;;;AAMA,SAAgB,mBAAqD;CACnE,IAAI,OAAO,YAAY,aAAa;CACpC,IAAI,QAAQ,IAAI,QAAQ,OAAO;CAC/B,IAAI,QAAQ,IAAI,SAAS,OAAO;AAElC;;AAGA,SAAgB,aAAiC;CAC/C,IAAI,OAAO,YAAY,aAAa;CACpC,OAAO,QAAQ,IAAI;AACrB;;;;;AAMA,SAAgB,cAAuB;CACrC,IAAI,OAAO,YAAY,aAAa,OAAO;CAC3C,OAAO,QAAQ,IAAI,eAAe;AACpC;;;;;AAMA,SAAgB,gBAAyB;CACvC,IAAI;EACF,OAAO,QAAQ,IAAI,aAAa;CAClC,QAAQ;EACN,OAAO;CACT;AACF"}

package/index.d.ts

@@ -104,6 +104,36 @@ export type TrackArgs<Name extends string> = [Name] extends [EventName] ? {} ext
  * own database id, never an email or other personal data.
  */
 export type UserId = string | number | null | undefined;
+/**
+ * The part of an event {@link BeforeSend} sees and may change. The site, the visitor's user id
+ * and the attribution id are out of reach, so a hook cannot change who an event belongs to.
+ */
+export interface BeforeSendEvent {
+  /** The event's name: `pageview`, `engagement`, or a name passed to `track`. Read-only. */
+  readonly name: string;
+  /** The page's full URL. The page path is read off the URL you return. */
+  url: string;
+  /** The page the visitor came from, or the page left on a client-side navigation. */
+  referrer?: string;
+  /** The event's properties, each value a string. */
+  properties?: Record<string, string>;
+}
+/**
+ * Runs in the browser on every event before the tracker sends it, page views from client-side
+ * navigation included. Return the event, changed or not, or `null` to drop it. Any other falsy
+ * answer drops it too, and so does a hook that throws: a hook that keeps a secret out of the
+ * data must not leak it when it fails. The error still reaches the console.
+ *
+ * ```ts
+ * function beforeSend(event: BeforeSendEvent) {
+ *   const url = new URL(event.url)
+ *   if (url.pathname.startsWith("/admin/")) return null
+ *   url.searchParams.delete("email")
+ *   return { ...event, url: url.href }
+ * }
+ * ```
+ */
+export type BeforeSend = (event: BeforeSendEvent) => BeforeSendEvent | null;
 /** The tracker's API on `window.highseat`, or the queue that stands in for it until it loads. */
 export interface HighseatGlobal {
   /** Records an event. */
@@ -114,6 +144,8 @@ export interface HighseatGlobal {
   getAttributionId?: () => string | undefined;
   /** Calls made before the tracker loaded, drained in order when it starts. */
   q?: [string, unknown[]][];
+  /** The site's {@link BeforeSend} hook, read on every event. */
+  beforeSend?: BeforeSend;
 }
 /** How long {@link getAttributionId} waits for the tracker. */
 export interface AttributionOptions {
@@ -136,6 +168,8 @@ export interface InjectOptions {
   downloads?: boolean;
   /** Counts a change of `#/route` as a page view, for an app that routes by hash. */
   hashRouting?: boolean;
+  /** Changes or drops each event before it leaves the browser. See {@link BeforeSend}. */
+  beforeSend?: BeforeSend;
   /**
    * Logs every `track()` and `identify()` call to the console, and warns once when no tracker
    * script is on the page or the script failed to load. Defaults to `true` when
@@ -170,6 +204,12 @@ export declare function identify(id: UserId): void;
  * when the script is still loading, and on a server or with tracking off.
  */
 export declare function getAttributionId(options?: AttributionOptions): Promise<string | undefined>;
+/**
+ * Sets the {@link BeforeSend} hook, or clears it with `undefined`. Works before the tracker has
+ * loaded, which picks the hook up when it starts, and applies from the next event once it runs.
+ * Does nothing on a server.
+ */
+export declare function setBeforeSend(beforeSend: BeforeSend | undefined): void;
 /**
  * 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 adds nothing, but its `debug` option still applies.

package/index.js

@@ -41,7 +41,7 @@ function isTrackerScript(script) {
 	}
 }
 /** The page's tracker scripts, each one listened to from now on for a failed load. */
-function findTrackerScripts() {
+function getTrackerScripts() {
 	const scripts = Array.from(document.scripts).filter(isTrackerScript);
 	for (const script of scripts) script.addEventListener("error", markFailed);
 	return scripts;
@@ -62,7 +62,7 @@ function watchTracker() {
 	const deadline = Date.now() + TRACKER_TIMEOUT;
 	function check() {
 		if (window !== page || isLive(page.highseat)) return;
-		const scripts = findTrackerScripts();
+		const scripts = getTrackerScripts();
 		if (scripts.length > 0 && scripts.every((script) => failedScripts.has(script))) {
 			console.warn(FAILED_SCRIPT_WARNING);
 			return;
@@ -135,7 +135,7 @@ async function getAttributionId(options = {}) {
 	let api = window.highseat;
 	while (!isLive(api)) {
 		if (Date.now() >= deadline) return;
-		if (findTrackerScripts().every((script) => failedScripts.has(script))) return;
+		if (getTrackerScripts().every((script) => failedScripts.has(script))) return;
 		await new Promise((resolve) => setTimeout(resolve, TRACKER_POLL_INTERVAL));
 		api = window.highseat;
 	}
@@ -146,14 +146,24 @@ async function getAttributionId(options = {}) {
 	}
 }
 /**
+* Sets the {@link BeforeSend} hook, or clears it with `undefined`. Works before the tracker has
+* loaded, which picks the hook up when it starts, and applies from the next event once it runs.
+* Does nothing on a server.
+*/
+function setBeforeSend(beforeSend) {
+	const api = findGlobal();
+	if (api) api.beforeSend = beforeSend;
+}
+/**
 * 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 adds nothing, but its `debug` option still applies.
 * Does nothing on a server.
 */
 function inject(options) {
 	if (typeof document === "undefined") return;
-	const { site, src = SCRIPT_URL, outbound, downloads, hashRouting, debug } = options;
+	const { site, src = SCRIPT_URL, outbound, downloads, hashRouting, beforeSend, debug } = options;
 	debugOption = debug;
+	if (beforeSend) setBeforeSend(beforeSend);
 	if (isDebug()) watchTracker();
 	if (Array.from(document.scripts).some((script) => script.dataset.site === site)) return;
 	const script = document.createElement("script");
@@ -167,6 +177,6 @@ function inject(options) {
 	document.head.append(script);
 }
 //#endregion
-export { SCRIPT_URL, getAttributionId, identify, inject, track };
+export { SCRIPT_URL, getAttributionId, identify, inject, setBeforeSend, track };
 
 //# sourceMappingURL=index.js.map

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { isDevelopment } from \"./env\"\n\n/**\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/**\n * A user id from your own system, as {@link identify} takes it. A string or a number identifies\n * the visitor, `null` clears the id, and `undefined` or an empty string changes nothing. Pass your\n * own database id, never an email or other personal data.\n */\nexport type UserId = string | number | null | undefined\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: UserId) => 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   * Logs every `track()` and `identify()` call to the console, and warns once when no tracker\n   * script is on the page or the script failed to load. Defaults to `true` when\n   * `process.env.NODE_ENV` is `development`, so a production build logs nothing.\n   */\n  debug?: 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 TRACKER_TIMEOUT = 3000\nconst TRACKER_POLL_INTERVAL = 50\n\nconst MISSING_SCRIPT_WARNING = [\n  \"highseat: no tracker script on this page, so no event reaches Highseat.\",\n  \"Render <Highseat />, call inject({ site }), or add the script tag from the site's Installation settings.\",\n].join(\" \")\nconst FAILED_SCRIPT_WARNING = [\n  \"highseat: the tracker script failed to load, so no event reaches Highseat.\",\n  \"An ad blocker may have stopped it: load the tracker from the site's proxy path instead.\",\n].join(\" \")\nconst SLOW_SCRIPT_WARNING = [\n  `highseat: the tracker script has not loaded after ${TRACKER_TIMEOUT / 1000} seconds,`,\n  \"so every call waits in the queue. Check the network panel for a blocked or failed request.\",\n].join(\" \")\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\n// The `debug` option of the last `inject` call. Unset falls back to the build's environment.\nlet debugOption: boolean | undefined\n// The windows whose tracker is being watched, so a page warns about its script once.\nconst watchedWindows = new WeakSet<Window>()\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\n/** The page's tracker scripts, each one listened to from now on for a failed load. */\nfunction findTrackerScripts() {\n  const scripts = Array.from(document.scripts).filter(isTrackerScript)\n  for (const script of scripts) script.addEventListener(\"error\", markFailed)\n  return scripts\n}\n\nfunction isDebug() {\n  return debugOption ?? isDevelopment()\n}\n\n/**\n * Warns once per page when the tracker cannot arrive: no tracker script, or only failed ones. A\n * missing script is judged at the timeout, because `<Highseat />` adds its tag in an effect that\n * runs after the effects of the components inside it.\n */\nfunction watchTracker() {\n  if (typeof window === \"undefined\" || typeof document === \"undefined\") return\n  if (watchedWindows.has(window)) return\n  watchedWindows.add(window)\n\n  const page = window\n  const deadline = Date.now() + TRACKER_TIMEOUT\n\n  function check() {\n    // A replaced global window, as a test sets up for each case, is another page.\n    if (window !== page || isLive(page.highseat)) return\n\n    const scripts = findTrackerScripts()\n\n    if (scripts.length > 0 && scripts.every(script => failedScripts.has(script))) {\n      console.warn(FAILED_SCRIPT_WARNING)\n      return\n    }\n    if (Date.now() < deadline) {\n      setTimeout(check, TRACKER_POLL_INTERVAL)\n      return\n    }\n    console.warn(scripts.length === 0 ? MISSING_SCRIPT_WARNING : SLOW_SCRIPT_WARNING)\n  }\n\n  setTimeout(check, TRACKER_POLL_INTERVAL)\n}\n\n/**\n * Logs a call when debugging is on. The check waits a microtask, so a `debug` option that\n * `<Highseat />` passes in its effect applies to the calls its children make in theirs.\n */\nfunction logCall(method: \"track\" | \"identify\", args: unknown[], isQueued: boolean) {\n  queueMicrotask(() => {\n    if (!isDebug()) return\n\n    const status = isQueued ? \"queued until the tracker loads\" : \"sent to the tracker\"\n    const [value, properties] = args\n    // `JSON.stringify` quotes a name or a string id, and returns `undefined` for an unset id.\n    const message = `highseat: ${method} ${String(JSON.stringify(value))}, ${status}`\n\n    if (properties === undefined) console.info(message)\n    else console.info(message, properties)\n    watchTracker()\n  })\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    logCall(method, args, true)\n    return\n  }\n\n  logCall(method, args, false)\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: UserId): 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 ?? TRACKER_TIMEOUT)\n  let api = window.highseat\n\n  while (!isLive(api)) {\n    if (Date.now() >= deadline) return\n\n    const scripts = findTrackerScripts()\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, TRACKER_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 adds nothing, but its `debug` option still applies.\n * 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, debug } = options\n  debugOption = debug\n  if (isDebug()) watchTracker()\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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"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { isDevelopment } from \"./env\"\n\n/**\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/**\n * A user id from your own system, as {@link identify} takes it. A string or a number identifies\n * the visitor, `null` clears the id, and `undefined` or an empty string changes nothing. Pass your\n * own database id, never an email or other personal data.\n */\nexport type UserId = string | number | null | undefined\n\n/**\n * The part of an event {@link BeforeSend} sees and may change. The site, the visitor's user id\n * and the attribution id are out of reach, so a hook cannot change who an event belongs to.\n */\nexport interface BeforeSendEvent {\n  /** The event's name: `pageview`, `engagement`, or a name passed to `track`. Read-only. */\n  readonly name: string\n  /** The page's full URL. The page path is read off the URL you return. */\n  url: string\n  /** The page the visitor came from, or the page left on a client-side navigation. */\n  referrer?: string\n  /** The event's properties, each value a string. */\n  properties?: Record<string, string>\n}\n\n/**\n * Runs in the browser on every event before the tracker sends it, page views from client-side\n * navigation included. Return the event, changed or not, or `null` to drop it. Any other falsy\n * answer drops it too, and so does a hook that throws: a hook that keeps a secret out of the\n * data must not leak it when it fails. The error still reaches the console.\n *\n * ```ts\n * function beforeSend(event: BeforeSendEvent) {\n *   const url = new URL(event.url)\n *   if (url.pathname.startsWith(\"/admin/\")) return null\n *   url.searchParams.delete(\"email\")\n *   return { ...event, url: url.href }\n * }\n * ```\n */\nexport type BeforeSend = (event: BeforeSendEvent) => BeforeSendEvent | null\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: UserId) => 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  /** The site's {@link BeforeSend} hook, read on every event. */\n  beforeSend?: BeforeSend\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  /** Changes or drops each event before it leaves the browser. See {@link BeforeSend}. */\n  beforeSend?: BeforeSend\n  /**\n   * Logs every `track()` and `identify()` call to the console, and warns once when no tracker\n   * script is on the page or the script failed to load. Defaults to `true` when\n   * `process.env.NODE_ENV` is `development`, so a production build logs nothing.\n   */\n  debug?: 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 TRACKER_TIMEOUT = 3000\nconst TRACKER_POLL_INTERVAL = 50\n\nconst MISSING_SCRIPT_WARNING = [\n  \"highseat: no tracker script on this page, so no event reaches Highseat.\",\n  \"Render <Highseat />, call inject({ site }), or add the script tag from the site's Installation settings.\",\n].join(\" \")\nconst FAILED_SCRIPT_WARNING = [\n  \"highseat: the tracker script failed to load, so no event reaches Highseat.\",\n  \"An ad blocker may have stopped it: load the tracker from the site's proxy path instead.\",\n].join(\" \")\nconst SLOW_SCRIPT_WARNING = [\n  `highseat: the tracker script has not loaded after ${TRACKER_TIMEOUT / 1000} seconds,`,\n  \"so every call waits in the queue. Check the network panel for a blocked or failed request.\",\n].join(\" \")\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\n// The `debug` option of the last `inject` call. Unset falls back to the build's environment.\nlet debugOption: boolean | undefined\n// The windows whose tracker is being watched, so a page warns about its script once.\nconst watchedWindows = new WeakSet<Window>()\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\n/** The page's tracker scripts, each one listened to from now on for a failed load. */\nfunction getTrackerScripts() {\n  const scripts = Array.from(document.scripts).filter(isTrackerScript)\n  for (const script of scripts) script.addEventListener(\"error\", markFailed)\n  return scripts\n}\n\nfunction isDebug() {\n  return debugOption ?? isDevelopment()\n}\n\n/**\n * Warns once per page when the tracker cannot arrive: no tracker script, or only failed ones. A\n * missing script is judged at the timeout, because `<Highseat />` adds its tag in an effect that\n * runs after the effects of the components inside it.\n */\nfunction watchTracker() {\n  if (typeof window === \"undefined\" || typeof document === \"undefined\") return\n  if (watchedWindows.has(window)) return\n  watchedWindows.add(window)\n\n  const page = window\n  const deadline = Date.now() + TRACKER_TIMEOUT\n\n  function check() {\n    // A replaced global window, as a test sets up for each case, is another page.\n    if (window !== page || isLive(page.highseat)) return\n\n    const scripts = getTrackerScripts()\n\n    if (scripts.length > 0 && scripts.every(script => failedScripts.has(script))) {\n      console.warn(FAILED_SCRIPT_WARNING)\n      return\n    }\n    if (Date.now() < deadline) {\n      setTimeout(check, TRACKER_POLL_INTERVAL)\n      return\n    }\n    console.warn(scripts.length === 0 ? MISSING_SCRIPT_WARNING : SLOW_SCRIPT_WARNING)\n  }\n\n  setTimeout(check, TRACKER_POLL_INTERVAL)\n}\n\n/**\n * Logs a call when debugging is on. The check waits a microtask, so a `debug` option that\n * `<Highseat />` passes in its effect applies to the calls its children make in theirs.\n */\nfunction logCall(method: \"track\" | \"identify\", args: unknown[], isQueued: boolean) {\n  queueMicrotask(() => {\n    if (!isDebug()) return\n\n    const status = isQueued ? \"queued until the tracker loads\" : \"sent to the tracker\"\n    const [value, properties] = args\n    // `JSON.stringify` quotes a name or a string id, and returns `undefined` for an unset id.\n    const message = `highseat: ${method} ${String(JSON.stringify(value))}, ${status}`\n\n    if (properties === undefined) console.info(message)\n    else console.info(message, properties)\n    watchTracker()\n  })\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    logCall(method, args, true)\n    return\n  }\n\n  logCall(method, args, false)\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: UserId): 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 ?? TRACKER_TIMEOUT)\n  let api = window.highseat\n\n  while (!isLive(api)) {\n    if (Date.now() >= deadline) return\n\n    const scripts = getTrackerScripts()\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, TRACKER_POLL_INTERVAL))\n    api = window.highseat\n  }\n\n  try {\n    return api.getAttributionId?.()\n  } catch {\n    return\n  }\n}\n\n/**\n * Sets the {@link BeforeSend} hook, or clears it with `undefined`. Works before the tracker has\n * loaded, which picks the hook up when it starts, and applies from the next event once it runs.\n * Does nothing on a server.\n */\nexport function setBeforeSend(beforeSend: BeforeSend | undefined): void {\n  const api = findGlobal()\n  if (api) api.beforeSend = beforeSend\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 adds nothing, but its `debug` option still applies.\n * 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, beforeSend, debug } = options\n  debugOption = debug\n  // Set before the script tag is added, so the first page view already passes through it.\n  if (beforeSend) setBeforeSend(beforeSend)\n  if (isDebug()) watchTracker()\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/ingest.d.ts

@@ -0,0 +1,14 @@
+//#region src/ingest.d.ts
+/**
+ * What `highseat/proxy` and `highseat/server` share about reaching ingest: its host, the site
+ * secret's prefixes and where the visitor's IP is read.
+ */
+/** A host whose own header carries the visitor's IP. */
+export type ClientIpPreset = "vercel" | "cloudflare" | "netlify" | "nginx";
+/**
+ * Where the visitor's IP is read: 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);
+//#endregion
+//# sourceMappingURL=ingest.d.ts.map

package/ingest.js

@@ -0,0 +1,40 @@
+import { findSecret } from "./env.js";
+//#region src/ingest.ts
+/** The ingest origin both handlers send to unless told otherwise. */
+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"
+};
+/**
+* The site secret, `option` or else `HIGHSEAT_SECRET`, or `undefined` when neither is set. Throws
+* on a value that is not one, naming the entry point that read it: that is a copying mistake.
+*/
+function findValidSecret(option, entry) {
+	const secret = option ?? findSecret();
+	if (!secret || SECRET_PREFIXES.some((prefix) => secret.startsWith(prefix))) return secret;
+	throw new Error(`${entry}: not a site secret. Copy it from the site's Installation settings; it starts with "${SECRET_PREFIXES[0]}".`);
+}
+function getClientIpReader(clientIp, entry) {
+	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(`${entry}: unknown clientIp preset "${String(clientIp)}".`);
+	return {
+		read: (request) => request.headers.get(header)?.trim() ?? "",
+		source: `the "${clientIp}" preset's ${header} header`
+	};
+}
+//#endregion
+export { DEFAULT_UPSTREAM, findValidSecret, getClientIpReader };
+
+//# sourceMappingURL=ingest.js.map

package/ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.js","names":[],"sources":["../src/ingest.ts"],"sourcesContent":["import { findSecret } from \"./env\"\n\n/**\n * What `highseat/proxy` and `highseat/server` share about reaching ingest: its host, the site\n * secret's prefixes and where the visitor's IP is read.\n */\n\n/** A host whose own header carries the visitor's IP. */\nexport type ClientIpPreset = \"vercel\" | \"cloudflare\" | \"netlify\" | \"nginx\"\n\n/**\n * Where the visitor's IP is read: a host preset, or a function for any other setup. A function\n * returns the IP, or nothing when the request carries none.\n */\nexport type ClientIp = ClientIpPreset | ((request: Request) => string | null | undefined)\n\n/** The ingest origin both handlers send to unless told otherwise. */\nexport const DEFAULT_UPSTREAM = \"https://cdn.highseat.com\"\n\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 package.\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\ninterface ClientIpReader {\n  read: (request: Request) => string\n  /** Where `read` looks, for the warning about an empty IP. */\n  source: string\n}\n\n/**\n * The site secret, `option` or else `HIGHSEAT_SECRET`, or `undefined` when neither is set. Throws\n * on a value that is not one, naming the entry point that read it: that is a copying mistake.\n */\nexport function findValidSecret(option: string | undefined, entry: string): string | undefined {\n  const secret = option ?? findSecret()\n  if (!secret || SECRET_PREFIXES.some(prefix => secret.startsWith(prefix))) return secret\n\n  throw new Error(\n    `${entry}: not a site secret. Copy it from the site's Installation settings; it starts with \"${SECRET_PREFIXES[0]}\".`,\n  )\n}\n\nexport function getClientIpReader(clientIp: ClientIp, entry: string): 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(`${entry}: 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"],"mappings":";;;AAiBA,MAAa,mBAAmB;AAIhC,MAAM,kBAAkB;CAAC;CAAc;CAAa;AAAY;AAEhE,MAAM,oBAAoD;CACxD,QAAQ;CAER,YAAY;CACZ,SAAS;CACT,OAAO;AACT;;;;;AAYA,SAAgB,gBAAgB,QAA4B,OAAmC;CAC7F,MAAM,SAAS,UAAU,WAAW;CACpC,IAAI,CAAC,UAAU,gBAAgB,MAAK,WAAU,OAAO,WAAW,MAAM,CAAC,GAAG,OAAO;CAEjF,MAAM,IAAI,MACR,GAAG,MAAM,sFAAsF,gBAAgB,GAAG,GACpH;AACF;AAEA,SAAgB,kBAAkB,UAAoB,OAA+B;CACnF,IAAI,OAAO,aAAa,YACtB,OAAO;EAAE,OAAM,YAAW,SAAS,OAAO,CAAC,EAAE,KAAK,KAAK;EAAI,QAAQ;CAAwB;CAG7F,MAAM,SAAS,kBAAkB;CACjC,IAAI,CAAC,QAAQ,MAAM,IAAI,MAAM,GAAG,MAAM,6BAA6B,OAAO,QAAQ,EAAE,GAAG;CACvF,OAAO;EACL,OAAM,YAAW,QAAQ,QAAQ,IAAI,MAAM,CAAC,EAAE,KAAK,KAAK;EACxD,QAAQ,QAAQ,SAAS,aAAa,OAAO;CAC/C;AACF"}

package/next.d.ts

@@ -1,15 +1,21 @@
-import { HighseatProps as HighseatProps$1, useIdentify } from "./react.js";
-import { ClientIp, ClientIpPreset, ProxyHandler, ProxyOptions, createProxy } from "./proxy.js";
+import { HighseatProps as HighseatProps$1, useBeforeSend, useIdentify } from "./react.js";
+import { ClientIp, ClientIpPreset } from "./ingest.js";
+import { ProxyHandler, ProxyOptions, createProxy } from "./proxy.js";
 import { ReactElement } from "react";
 //#region src/next.d.ts
-export interface HighseatProps extends Partial<HighseatProps$1> {}
+/**
+ * The props of `<Highseat />` in a server layout. `beforeSend` is left out: a server component
+ * cannot pass a function to the browser, so the hook is set with {@link useBeforeSend} in a client
+ * component instead.
+ */
+export interface HighseatProps extends Partial<Omit<HighseatProps$1, "beforeSend">> {}
 /**
  * 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.
  * `userId` takes an id the server already knows. For a session read in the browser, call
- * `useIdentify` in a client component instead.
+ * `useIdentify` in a client component instead, and set a `beforeSend` hook with `useBeforeSend`.
  */
 export declare function Highseat(props: HighseatProps): ReactElement | null;
 /** A Next.js rewrite: the subset of its fields this package writes and reads. */
@@ -60,5 +66,5 @@ export interface WithHighseatOptions {
  */
 export declare function withHighseat<Config extends object>(config: Config, options?: WithHighseatOptions): WithHighseatConfig<Config>;
 //#endregion
-export { type ClientIp, type ClientIpPreset, type ProxyHandler, type ProxyOptions, createProxy, useIdentify };
+export { type ClientIp, type ClientIpPreset, type ProxyHandler, type ProxyOptions, createProxy, useBeforeSend, useIdentify };
 //# sourceMappingURL=next.d.ts.map

package/next.js

@@ -1,5 +1,5 @@
 import { findNextSite, findProxyPath } from "./env.js";
-import { Highseat as Highseat$1, useIdentify } from "./react.js";
+import { Highseat as Highseat$1, useBeforeSend, useIdentify } from "./react.js";
 import { createProxy } from "./proxy.js";
 import { createElement } from "react";
 //#region src/next.ts
@@ -9,7 +9,7 @@ import { createElement } from "react";
 * `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.
 * `userId` takes an id the server already knows. For a session read in the browser, call
-* `useIdentify` in a client component instead.
+* `useIdentify` in a client component instead, and set a `beforeSend` hook with `useBeforeSend`.
 */
 function Highseat(props) {
 	const site = props.site ?? findNextSite();
@@ -83,6 +83,6 @@ function withHighseat(config, options = {}) {
 	};
 }
 //#endregion
-export { Highseat, createProxy, useIdentify, withHighseat };
+export { Highseat, createProxy, useBeforeSend, useIdentify, withHighseat };
 
 //# sourceMappingURL=next.js.map

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  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"}
+{"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 { useBeforeSend, useIdentify } from \"./react\"\nexport type { ClientIp, ClientIpPreset, ProxyHandler, ProxyOptions } from \"./proxy\"\n\n/**\n * The props of `<Highseat />` in a server layout. `beforeSend` is left out: a server component\n * cannot pass a function to the browser, so the hook is set with {@link useBeforeSend} in a client\n * component instead.\n */\nexport interface HighseatProps extends Partial<Omit<ReactHighseatProps, \"beforeSend\">> {}\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, and set a `beforeSend` hook with `useBeforeSend`.\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":";;;;;;;;;;;;;AAuBA,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"}