highseat 0.1.0-alpha.2 → 0.2.0

package/README.md

@@ -2,12 +2,10 @@
 
 Highseat analytics for JavaScript: typed tracking, a first-party proxy and framework components.
 
-> **Pre-release.** The `alpha` versions can change shape between releases.
-
 ## Install
 
 ```bash
-npm install highseat@alpha
+npm install highseat
 ```
 
 ## Entry points
@@ -15,8 +13,8 @@ npm install highseat@alpha
 | Import | Contents | Needs |
 | --- | --- | --- |
 | `highseat` | `track()`, `identify()`, `getAttributionId()` and `inject()` | Nothing |
-| `highseat/react` | `<Highseat />` | React |
-| `highseat/next` | `<Highseat />`, `createProxy()` and `withHighseat()` for Next.js | Next.js |
+| `highseat/react` | `<Highseat />` and `useIdentify()` | React |
+| `highseat/next` | `<Highseat />`, `useIdentify()`, `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.
@@ -92,6 +90,43 @@ declare module "highseat" {
 
 Without `strict: true`, any other name still compiles as a custom event. The declarations are types only and add nothing to your bundle.
 
+### Identify users
+
+`identify()` links the visitor to a user id from your own system, on every later event and across visits. Pass your own database id, never an email or other personal data. `identify(null)` clears the id, and an empty or `undefined` id changes nothing.
+
+Most sites never call `identify()` directly. They pass the signed-in user's id instead, and the package calls `identify()` each time the value changes. A string or a number identifies the visitor. `null` means signed out, so a sign-out or an expired session clears the id. A sign-out in another tab clears it too once your auth library updates the session in this tab. `undefined` means the session is still loading, and changes nothing. The same id on every render calls `identify()` once.
+
+When the server already knows the user, pass the id to `<Highseat />`:
+
+```tsx
+<Highseat site="site_…" userId={user?.id ?? null} />
+```
+
+When the session comes from a client hook, call `useIdentify()` in any client component. It needs no `<Highseat />` nearby, so a Next.js App Router site keeps `<Highseat />` in its server layout and every page static. `highseat/next` and `highseat/react` both export it:
+
+```tsx
+"use client"
+
+import { useIdentify } from "highseat/next"
+import { useSession } from "~/lib/auth-client"
+
+export function IdentifyUser() {
+  const { data, isPending } = useSession()
+  useIdentify(isPending ? undefined : (data?.user.id ?? null))
+  return null
+}
+```
+
+The value has to tell loading apart from signed out. `useIdentify(session?.user.id)` passes `undefined` after sign-out too, so it never clears the id. `useIdentify(session?.user.id ?? null)` clears the id while the session loads, so the first page view has no user. Each auth library marks loading its own way:
+
+| Library | Hook | Value |
+| --- | --- | --- |
+| Better Auth | `const { data, isPending } = useSession()` | `isPending ? undefined : (data?.user.id ?? null)` |
+| Auth.js (NextAuth) | `const { data, status } = useSession()` | `status === "loading" ? undefined : (data?.user?.id ?? null)` |
+| Clerk | `const { user, isLoaded } = useUser()` | `isLoaded ? (user?.id ?? null) : undefined` |
+
+Without React, call `identify()` from `highseat` after each sign-in and sign-out.
+
 ## 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.
@@ -154,6 +189,54 @@ Next.js loads `next.config.ts` with `require`, and the package is ES modules onl
 
 `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.
 
+### TanStack Start
+
+```ts
+// src/server.ts
+import handler, { createServerEntry } from "@tanstack/react-start/server-entry"
+import { createProxy } from "highseat/proxy"
+
+const proxy = createProxy({
+  clientIp: "cloudflare",
+  fallback: request => handler.fetch(request),
+})
+
+export default createServerEntry({ fetch: request => proxy(request) })
+```
+
+```ts
+// vite.config.ts
+import { defineConfig, loadEnv } from "vite"
+
+export default defineConfig(({ mode }) => ({
+  // Loads HIGHSEAT_PATH alone, so the site secret beside it never reaches the bundle.
+  define: {
+    "import.meta.env.HIGHSEAT_PATH": JSON.stringify(
+      loadEnv(mode, process.cwd(), "HIGHSEAT_PATH").HIGHSEAT_PATH,
+    ),
+  },
+  // Your own config.
+}))
+```
+
+```tsx
+// src/routes/__root.tsx
+<Highseat site={import.meta.env.VITE_HIGHSEAT_SITE} src={import.meta.env.HIGHSEAT_PATH} />
+```
+
+The server entry answers `HIGHSEAT_PATH` with the proxy and hands every other request to the app. A file route named after the path does not work: a catch-all route such as `$id` matches it first. The `define` gives the browser the same path, so set `HIGHSEAT_PATH` for the build as well as the server, as a build argument in a Docker build. Pick the preset for the outermost proxy that sets the header, as for Next.js.
+
+`fallback` receives the request alone, so the app loses the options the server entry was called with. An app that reads them routes the path itself, with a proxy created without `fallback`:
+
+```ts
+export default createServerEntry({
+  fetch: (request, options) =>
+    new URL(request.url).pathname === process.env.HIGHSEAT_PATH
+      ? proxy(request)
+      : handler.fetch(request, options),
+})
+```
+
 ### Cloudflare Worker
 
 ```ts

package/index.d.ts

@@ -1,168 +1,2 @@
-//#region src/index.d.ts
-/**
- * The browser client. Every call goes to the hosted tracker on `window.highseat`; before the
- * tracker has loaded, calls wait in a queue the tracker drains on startup. Nothing here throws:
- * on a server, with the tracker blocked, or with tracking off, a call does nothing.
- */
-/** A value an event property can hold. A `null` or `undefined` value is left out of the event. */
-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
+import { _ as track, a as InjectOptions, c as Register, d as TrackArgs, f as TrackName, g as inject, h as identify, i as HighseatGlobal, l as Revenue, m as getAttributionId, n as BuiltInEvents, o as Properties, p as UserId, r as EventName, s as PropertyValue, t as AttributionOptions, u as SCRIPT_URL } from "./index2.js";
+export { AttributionOptions, BuiltInEvents, EventName, HighseatGlobal, InjectOptions, Properties, PropertyValue, Register, Revenue, SCRIPT_URL, TrackArgs, TrackName, UserId, getAttributionId, identify, inject, track };

package/index.js.map

@@ -1 +1 @@
-{"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":";;AA0JA,MAAa,aAAa;AAI1B,MAAM,OAAO,OAAO,IAAI,UAAU;AAElC,MAAM,cAAc,IAAI,IAAI,UAAU,CAAC,CAAC;AAExC,MAAM,aAAa;AAEnB,MAAM,sBAAsB;AAC5B,MAAM,4BAA4B;AAKlC,MAAM,kCAAkB,IAAI,QAA2B;AACvD,MAAM,gCAAgB,IAAI,QAA2B;AAErD,SAAS,aAAyC;CAChD,IAAI,OAAO,WAAW,aAAa;CACnC,OAAQ,OAAO,aAAa,CAAC;AAC/B;AAEA,SAAS,OAAO,KAAwD;CACtE,OAAO,CAAC,CAAC,OAAQ,IAAgC,UAAU;AAC7D;AAGA,SAAS,WAAW,OAAc;CAChC,cAAc,IAAI,MAAM,aAAkC;AAC5D;;;;;;AAOA,SAAS,gBAAgB,QAA2B;CAClD,MAAM,EAAE,SAAS,OAAO;CACxB,IAAI,gBAAgB,IAAI,MAAM,KAAK,MAAM,WAAW,OAAO,GAAG,OAAO;CACrE,IAAI,SAAS,KAAA,GAAW,OAAO;CAE/B,IAAI;EAEF,MAAM,MAAM,IAAI,IAAI,OAAO,KAAK,kBAAkB;EAClD,OAAO,IAAI,SAAS,eAAe,WAAW,KAAK,IAAI,QAAQ;CACjE,QAAQ;EACN,OAAO;CACT;AACF;AAEA,SAAS,qBAAqB;CAC5B,OAAO,MAAM,KAAK,SAAS,OAAO,CAAC,CAAC,OAAO,eAAe;AAC5D;AAEA,SAAS,KAAK,QAA8B,MAAiB;CAC3D,MAAM,MAAM,WAAW;CACvB,IAAI,CAAC,KAAK;CAEV,MAAM,UAAU,IAAI;CACpB,IAAI,OAAO,YAAY,YAAY;EACjC,IAAI,MAAM,CAAC;EACX,IAAI,EAAE,KAAK,CAAC,QAAQ,IAAI,CAAC;EACzB;CACF;CAEA,IAAI;EACF,QAAQ,GAAG,IAAI;CACjB,QAAQ,CAAC;AACX;;;;;;AAOA,SAAgB,MAA8B,MAAY,GAAG,MAA6B;CACxF,MAAM,CAAC,cAAc;CACrB,KAAK,SAAS,eAAe,KAAA,IAAY,CAAC,IAAI,IAAI,CAAC,MAAM,UAAU,CAAC;AACtE;;;;;;AAOA,SAAgB,SAAS,IAA8C;CACrE,KAAK,YAAY,CAAC,EAAE,CAAC;AACvB;;;;;;;;AASA,eAAsB,iBACpB,UAA8B,CAAC,GACF;CAC7B,IAAI,OAAO,WAAW,eAAe,OAAO,aAAa,aAAa;CAEtE,MAAM,WAAW,KAAK,IAAI,KAAK,QAAQ,WAAW;CAClD,IAAI,MAAM,OAAO;CAEjB,OAAO,CAAC,OAAO,GAAG,GAAG;EACnB,IAAI,KAAK,IAAI,KAAK,UAAU;EAE5B,MAAM,UAAU,mBAAmB;EACnC,KAAK,MAAM,UAAU,SAAS,OAAO,iBAAiB,SAAS,UAAU;EAEzE,IAAI,QAAQ,OAAM,WAAU,cAAc,IAAI,MAAM,CAAC,GAAG;EAExD,MAAM,IAAI,SAAQ,YAAW,WAAW,SAAS,yBAAyB,CAAC;EAC3E,MAAM,OAAO;CACf;CAEA,IAAI;EACF,OAAO,IAAI,mBAAmB;CAChC,QAAQ;EACN;CACF;AACF;;;;;AAMA,SAAgB,OAAO,SAA8B;CACnD,IAAI,OAAO,aAAa,aAAa;CAErC,MAAM,EAAE,MAAM,MAAM,YAAY,UAAU,WAAW,gBAAgB;CACrE,IAAI,MAAM,KAAK,SAAS,OAAO,CAAC,CAAC,MAAK,WAAU,OAAO,QAAQ,SAAS,IAAI,GAAG;CAE/E,MAAM,SAAS,SAAS,cAAc,QAAQ;CAC9C,OAAO,iBAAiB,SAAS,UAAU;CAC3C,gBAAgB,IAAI,MAAM;CAC1B,OAAO,MAAM;CACb,OAAO,QAAQ,OAAO;CACtB,IAAI,aAAa,OAAO,OAAO,QAAQ,WAAW;CAClD,IAAI,cAAc,OAAO,OAAO,QAAQ,YAAY;CACpD,IAAI,aAAa,OAAO,QAAQ,cAAc;CAC9C,SAAS,KAAK,OAAO,MAAM;AAC7B"}
+{"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/**\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\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: 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 ?? 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/index2.d.ts

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

package/next.d.ts

@@ -1,13 +1,15 @@
-import { InjectOptions } from "./index.js";
+import { HighseatProps as HighseatProps$1, useIdentify } from "./react.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> {}
+export interface HighseatProps extends Partial<HighseatProps$1> {}
 /**
  * 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.
  */
 export declare function Highseat(props: HighseatProps): ReactElement | null;
 /** A Next.js rewrite: the subset of its fields this package writes and reads. */
@@ -56,5 +58,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 };
+export { type ClientIp, type ClientIpPreset, type ProxyHandler, type ProxyOptions, createProxy, useIdentify };
 //# sourceMappingURL=next.d.ts.map

package/next.js

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

package/package.json

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

package/react.d.ts

@@ -1,11 +1,34 @@
-import { InjectOptions } from "./index.js";
+import { a as InjectOptions, p as UserId } from "./index2.js";
 //#region src/react.d.ts
-export interface HighseatProps extends InjectOptions {}
+export interface HighseatProps extends InjectOptions {
+  /**
+   * The signed-in user's id from your own system, never an email or other personal data. Pass
+   * `null` once the visitor is signed out, and `undefined` while the session is still loading.
+   * See {@link useIdentify}.
+   */
+  userId?: UserId;
+}
+/**
+ * Keeps the visitor's user id in step with a session. Each new value is passed to `identify`
+ * once: an id identifies the visitor, `null` clears the id at sign-out or session expiry, and
+ * `undefined`, a session still loading, changes nothing. Works in any client component, with or
+ * without `<Highseat />` on the page, and before the tracker has loaded.
+ *
+ * Tell loading apart from signed out: `useIdentify(session?.user.id)` passes `undefined` after
+ * sign-out too, so it never clears the id.
+ *
+ * ```tsx
+ * const { data, isPending } = useSession()
+ * useIdentify(isPending ? undefined : (data?.user.id ?? null))
+ * ```
+ */
+export declare function useIdentify(userId: UserId): void;
 /**
  * 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.
+ * counts client-side navigation on its own. With `userId`, it also identifies the visitor, as
+ * {@link useIdentify} does.
  */
-export declare function Highseat({ site, src, outbound, downloads, hashRouting }: HighseatProps): null;
+export declare function Highseat({ site, src, outbound, downloads, hashRouting, userId }: HighseatProps): null;
 //#endregion
 //# sourceMappingURL=react.d.ts.map

package/react.js

@@ -1,31 +1,2 @@
 "use client";
-import { inject } from "./index.js";
-import { useEffect } from "react";
-//#region src/react.ts
-/**
-* 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
-export { Highseat };
-
-//# sourceMappingURL=react.js.map
+export { t as Highseat, n as useIdentify } from "./react2.js";

package/react2.js

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

package/react2.js.map

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

package/react.js.map

@@ -1 +0,0 @@
-{"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"}