highseat 0.2.0 → 0.3.1

package/README.md

@@ -23,14 +23,7 @@ The package loads the tracker from Highseat, or from your site's proxy path, rat
 
 ## Next.js
 
-Set the site id from your site's Installation settings, and the proxy path for first-party delivery:
-
-```bash
-NEXT_PUBLIC_HIGHSEAT_SITE=site_…
-HIGHSEAT_PATH=/3f9a0c1e2b
-```
-
-Then render `<Highseat />` once, in the root layout:
+Render `<Highseat />` once, in the root layout, with the site id from your site's Installation settings:
 
 ```tsx
 // app/layout.tsx
@@ -41,27 +34,72 @@ export default function RootLayout({ children }: { children: React.ReactNode })
     <html lang="en">
       <body>
         {children}
-        <Highseat />
+        <Highseat site="site_…" />
       </body>
     </html>
   )
 }
 ```
 
-Without `HIGHSEAT_PATH`, `<Highseat />` loads the tracker from Highseat's host. The tracker counts each client-side navigation as one page view on its own.
+To keep the site id out of the code, leave `site` out and set it for the build, with the proxy path for first-party delivery:
+
+```bash
+NEXT_PUBLIC_HIGHSEAT_SITE=site_…
+HIGHSEAT_PATH=/3f9a0c1e2b
+```
+
+Without `HIGHSEAT_PATH`, `<Highseat />` loads the tracker from Highseat's host. The tracker counts each client-side navigation as one page view on its own. With the Pages Router, render it in `pages/_app.tsx` instead.
 
 ## React
 
+Render `<Highseat />` once, beside your root component:
+
 ```tsx
 import { Highseat } from "highseat/react"
 
 <Highseat site="site_…" />
 ```
 
-`src` takes the site's proxy path (`/3f9a0c1e2b`) for first-party delivery. `outbound={false}` and `downloads={false}` turn off the automatic link and download events, and `hashRouting` counts `#/route` changes as page views.
+With Vite, `site={import.meta.env.VITE_HIGHSEAT_SITE}` reads the site id from the environment instead; with another bundler, read it from that bundler's public variable. `src` takes the site's proxy path (`/3f9a0c1e2b`) for first-party delivery. `outbound={false}` and `downloads={false}` turn off the automatic link and download events, and `hashRouting` counts `#/route` changes as page views.
 
 Without React, `inject({ site })` from `highseat` adds the same script tag.
 
+## TanStack Start
+
+Render `<Highseat />` once, inside `<body>` in the root route's component:
+
+```tsx
+// src/routes/__root.tsx
+import { Highseat } from "highseat/react"
+
+<Highseat site="site_…" />
+```
+
+To serve the tracker from your own domain, see TanStack Start under [First-party proxy](#first-party-proxy).
+
+## Astro
+
+Add the tracker's tag to the `<head>` of your layout. `is:inline` keeps Astro from bundling it, so the tracker starts before any page script:
+
+```astro
+<!-- src/layouts/Layout.astro -->
+<script is:inline defer src="https://cdn.highseat.com/script.js" data-site="site_…"></script>
+```
+
+## Any other site
+
+A site without a bundler, or a website builder such as Webflow or Shopify, needs no package. Add the tag to the `<head>` of every page, in the builder's head code field:
+
+```html
+<script defer src="https://cdn.highseat.com/script.js" data-site="site_…"></script>
+```
+
+## Debugging
+
+In development, the package logs every `track()` and `identify()` call to the console, with its properties or id, and says whether the call went to the tracker or waits in the queue for it to load. It also warns once per page when nothing can reach Highseat: the page has no tracker script, or the script failed to load, as one an ad blocker stopped does.
+
+Logging is on when `process.env.NODE_ENV` is `development`, so a production build logs nothing. Pass `debug={false}` to `<Highseat />` to turn it off, or `debug` to turn it on in any build. `inject({ site, debug })` takes the same option.
+
 ## Events
 
 ```ts
@@ -149,7 +187,11 @@ HIGHSEAT_SECRET=hs_secret_...    # the site secret
 
 A missing variable never stops the site. Without the secret, or without the path on a handler with a `fallback`, `createProxy()` warns once and turns the proxy off: with a `fallback`, every request goes to it, and without one the proxy path answers `503` with a JSON `error` naming the variable. A local server without the variables therefore still starts and serves the site.
 
-Then load the tracker from the path. In Next.js, `<Highseat />` reads `HIGHSEAT_PATH` itself. Elsewhere, pass `src="/3f9a0c1e2b"` to `<Highseat />` or `inject()`, or use the script tag from Installation settings.
+Then load the tracker from the path. In Next.js, `<Highseat />` reads `HIGHSEAT_PATH` itself. Elsewhere, pass `src="/3f9a0c1e2b"` to `<Highseat />` or `inject()`, or load it with a script tag in the `<head>` of every page:
+
+```html
+<script defer src="/3f9a0c1e2b" data-site="site_…"></script>
+```
 
 To rotate the path, rotate it in Installation settings, update `HIGHSEAT_PATH` and the snippet, and redeploy. On a host whose route is a file or a config entry (Netlify, Vercel without Next.js, Astro), move that route too.
 
@@ -185,9 +227,27 @@ export default withHighseat({
 })
 ```
 
+Then render `<Highseat />` in the root layout without `site` or `src`, in place of whatever loads the tracker now. It reads the site id from `NEXT_PUBLIC_HIGHSEAT_SITE` and the path from `HIGHSEAT_PATH`, and a `src` prop would outrank the path:
+
+```tsx
+// app/layout.tsx
+import { Highseat } from "highseat/next"
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <Highseat />
+      </body>
+    </html>
+  )
+}
+```
+
 Next.js loads `next.config.ts` with `require`, and the package is ES modules only, so the config needs Node 20.19 or 22.12 and later, the versions that `require` an ES module without a flag.
 
-`withHighseat()` rewrites `HIGHSEAT_PATH` to the route handler inside the app, so the visitor's IP survives and the route file never moves. Pass `{ route: "/stats" }` for a handler elsewhere. Without `HIGHSEAT_PATH`, `next dev` and `next build` warn once and leave the rewrite out, and `next typegen` runs as usual. Set the variable for the build as well as the server: the rewrite is written at build time. Off Vercel, the outermost proxy that sets the header decides the preset: `"cloudflare"` behind a proxied Cloudflare record, even with nginx or Traefik in between, and `"nginx"` behind nginx alone.
+`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 a build argument in a Docker build. `withHighseat()` writes the build's value into the rewrite and into the bundled code of `<Highseat />` and `createProxy()`, so the running App Router server needs only `HIGHSEAT_SECRET`. 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
 
@@ -262,6 +322,8 @@ export default {
 
 Route the Worker on `yoursite.com/*`: `fallback: fetch` passes every other request on to your origin. Set the secret with `wrangler secret put HIGHSEAT_SECRET`.
 
+A Worker that serves the site's static assets has no origin: pass `fallback: request => env.ASSETS.fetch(request)`, and leave `not_found_handling` out of your Wrangler config. With `not_found_handling` set, the assets answer every path that has no file, the proxy path included, so list the path in `run_worker_first`.
+
 ### Cloudflare Pages
 
 ```ts
@@ -284,7 +346,14 @@ export const onRequest: PagesFunction<Env> = ({ request, env, next }) => {
 }
 ```
 
-The function sees each one-segment path, and `next` serves your site for every path but the proxy's. Add both variables in the Pages project's settings.
+```json
+// public/_routes.json
+{ "version": 1, "include": ["/3f9a0c1e2b"], "exclude": [] }
+```
+
+`_routes.json` runs the function on the proxy path alone, so every page stays a static asset; without it the function runs on every one-segment path, and `next` serves your site for each one but the proxy's. Put it in the folder your build copies to its output as is, such as `public/`. Add both variables in the Pages project's settings.
+
+Pages ignores `functions/` when the build ships a `_worker.js`, as the Astro, SvelteKit and Remix adapters do, and the proxy path then answers with your site's 404. Remove the adapter from a static site, or use the adapter's own endpoint instead.
 
 ### Netlify
 
@@ -330,7 +399,14 @@ export const ALL: APIRoute = ({ request, clientAddress }) =>
   createProxy({ clientIp: () => clientAddress })(request)
 ```
 
-Needs a server adapter. The file name carries the path, so set only `HIGHSEAT_SECRET`. On the Cloudflare adapter, pass `secret: locals.runtime.env.HIGHSEAT_SECRET`.
+Then load the tracker from the path in your layout:
+
+```astro
+<!-- src/layouts/Layout.astro -->
+<script is:inline defer src="/3f9a0c1e2b" data-site={import.meta.env.PUBLIC_HIGHSEAT_SITE}></script>
+```
+
+Needs a server adapter. The file name carries the path, so set only `HIGHSEAT_SECRET`, and `PUBLIC_HIGHSEAT_SITE` for the site id. On the Cloudflare adapter, pass `secret: locals.runtime.env.HIGHSEAT_SECRET`. `clientAddress` is the address that connected, so behind a proxied Cloudflare record, use `"cloudflare"` instead.
 
 ### Hono
 

package/env.js

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

package/env.js.map

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

package/identity.js

@@ -0,0 +1,16 @@
+import { identify } from "./index.js";
+//#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
+export { syncIdentity };
+
+//# sourceMappingURL=identity.js.map

package/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","names":[],"sources":["../src/identity.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"],"mappings":";;;;;;;AAOA,SAAgB,aAAa,UAAkB,QAAwB;CACrE,IAAI,WAAW,KAAA,KAAa,WAAW,UAAU,OAAO;CACxD,SAAS,MAAM;CACf,OAAO;AACT"}

package/index.d.ts

@@ -1,2 +1,181 @@
-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 };
+//#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];
+/**
+ * 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.
+ */
+export type UserId = string | number | null | undefined;
+/** 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: 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. */
+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;
+  /**
+   * 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
+   * `process.env.NODE_ENV` is `development`, so a production build logs nothing.
+   */
+  debug?: 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: 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.
+ */
+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 adds nothing, but its `debug` option still applies.
+ * Does nothing on a server.
+ */
+export declare function inject(options: InjectOptions): void;
+//#endregion
+export {};
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,13 +1,19 @@
+import { isDevelopment } from "./env.js";
 //#region src/index.ts
 /** Where the tracker loads from when the site has no proxy path. */
 const SCRIPT_URL = "https://cdn.highseat.com/script.js";
 const LIVE = Symbol.for("highseat");
 const SCRIPT_HOST = new URL(SCRIPT_URL).host;
 const PROXY_PATH = /^\/[0-9a-f]{10}$/;
-const ATTRIBUTION_TIMEOUT = 3e3;
-const ATTRIBUTION_POLL_INTERVAL = 50;
+const TRACKER_TIMEOUT = 3e3;
+const TRACKER_POLL_INTERVAL = 50;
+const MISSING_SCRIPT_WARNING = ["highseat: no tracker script on this page, so no event reaches Highseat.", "Render <Highseat />, call inject({ site }), or add the script tag from the site's Installation settings."].join(" ");
+const FAILED_SCRIPT_WARNING = ["highseat: the tracker script failed to load, so no event reaches Highseat.", "An ad blocker may have stopped it: load the tracker from the site's proxy path instead."].join(" ");
+const SLOW_SCRIPT_WARNING = [`highseat: the tracker script has not loaded after ${TRACKER_TIMEOUT / 1e3} seconds,`, "so every call waits in the queue. Check the network panel for a blocked or failed request."].join(" ");
 const injectedScripts = /* @__PURE__ */ new WeakSet();
 const failedScripts = /* @__PURE__ */ new WeakSet();
+let debugOption;
+const watchedWindows = /* @__PURE__ */ new WeakSet();
 function findGlobal() {
 	if (typeof window === "undefined") return;
 	return window.highseat ??= {};
@@ -34,8 +40,55 @@ function isTrackerScript(script) {
 		return false;
 	}
 }
+/** The page's tracker scripts, each one listened to from now on for a failed load. */
 function findTrackerScripts() {
-	return Array.from(document.scripts).filter(isTrackerScript);
+	const scripts = Array.from(document.scripts).filter(isTrackerScript);
+	for (const script of scripts) script.addEventListener("error", markFailed);
+	return scripts;
+}
+function isDebug() {
+	return debugOption ?? isDevelopment();
+}
+/**
+* Warns once per page when the tracker cannot arrive: no tracker script, or only failed ones. A
+* missing script is judged at the timeout, because `<Highseat />` adds its tag in an effect that
+* runs after the effects of the components inside it.
+*/
+function watchTracker() {
+	if (typeof window === "undefined" || typeof document === "undefined") return;
+	if (watchedWindows.has(window)) return;
+	watchedWindows.add(window);
+	const page = window;
+	const deadline = Date.now() + TRACKER_TIMEOUT;
+	function check() {
+		if (window !== page || isLive(page.highseat)) return;
+		const scripts = findTrackerScripts();
+		if (scripts.length > 0 && scripts.every((script) => failedScripts.has(script))) {
+			console.warn(FAILED_SCRIPT_WARNING);
+			return;
+		}
+		if (Date.now() < deadline) {
+			setTimeout(check, TRACKER_POLL_INTERVAL);
+			return;
+		}
+		console.warn(scripts.length === 0 ? MISSING_SCRIPT_WARNING : SLOW_SCRIPT_WARNING);
+	}
+	setTimeout(check, TRACKER_POLL_INTERVAL);
+}
+/**
+* Logs a call when debugging is on. The check waits a microtask, so a `debug` option that
+* `<Highseat />` passes in its effect applies to the calls its children make in theirs.
+*/
+function logCall(method, args, isQueued) {
+	queueMicrotask(() => {
+		if (!isDebug()) return;
+		const status = isQueued ? "queued until the tracker loads" : "sent to the tracker";
+		const [value, properties] = args;
+		const message = `highseat: ${method} ${String(JSON.stringify(value))}, ${status}`;
+		if (properties === void 0) console.info(message);
+		else console.info(message, properties);
+		watchTracker();
+	});
 }
 function call(method, args) {
 	const api = findGlobal();
@@ -44,8 +97,10 @@ function call(method, args) {
 	if (typeof handler !== "function") {
 		api.q ??= [];
 		api.q.push([method, args]);
+		logCall(method, args, true);
 		return;
 	}
+	logCall(method, args, false);
 	try {
 		handler(...args);
 	} catch {}
@@ -76,14 +131,12 @@ function identify(id) {
 */
 async function getAttributionId(options = {}) {
 	if (typeof window === "undefined" || typeof document === "undefined") return;
-	const deadline = Date.now() + (options.timeout ?? ATTRIBUTION_TIMEOUT);
+	const deadline = Date.now() + (options.timeout ?? TRACKER_TIMEOUT);
 	let api = window.highseat;
 	while (!isLive(api)) {
 		if (Date.now() >= deadline) return;
-		const scripts = findTrackerScripts();
-		for (const script of scripts) script.addEventListener("error", markFailed);
-		if (scripts.every((script) => failedScripts.has(script))) return;
-		await new Promise((resolve) => setTimeout(resolve, ATTRIBUTION_POLL_INTERVAL));
+		if (findTrackerScripts().every((script) => failedScripts.has(script))) return;
+		await new Promise((resolve) => setTimeout(resolve, TRACKER_POLL_INTERVAL));
 		api = window.highseat;
 	}
 	try {
@@ -94,11 +147,14 @@ async function getAttributionId(options = {}) {
 }
 /**
 * 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.
+* 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 } = options;
+	const { site, src = SCRIPT_URL, outbound, downloads, hashRouting, debug } = options;
+	debugOption = debug;
+	if (isDebug()) watchTracker();
 	if (Array.from(document.scripts).some((script) => script.dataset.site === site)) return;
 	const script = document.createElement("script");
 	script.addEventListener("error", markFailed);

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/**\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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"}
+{"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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"}