highseat 0.6.0 → 0.8.0

package/README.md

@@ -13,8 +13,8 @@ npm install highseat
 | Import | Contents | Needs |
 | --- | --- | --- |
 | `highseat` | `track()`, `identify()`, `getAttributionId()`, `inject()` and `setBeforeSend()` | Nothing |
-| `highseat/react` | `<Highseat />`, `useIdentify()` and `useBeforeSend()` | React |
-| `highseat/next` | `<Highseat />`, `useIdentify()`, `useBeforeSend()`, `createProxy()` and `withHighseat()` for Next.js | Next.js |
+| `highseat/react` | `<Highseat />`, `<Embed />`, `useIdentify()` and `useBeforeSend()` | React |
+| `highseat/next` | `<Highseat />`, `<Embed />`, `useIdentify()`, `useBeforeSend()`, `createProxy()` and `withHighseat()` for Next.js | Next.js |
 | `highseat/proxy` | `createProxy()`, a first-party proxy for any runtime with `fetch` | Nothing |
 | `highseat/server` | `track()`, `flush()`, `close()` and `createTracker()`, for events sent from your backend | Nothing |
 | `highseat/mcp` | `trackToolCalls()` and `mcpLink()`, for the tool calls AI assistants make to your MCP server | The MCP TypeScript SDK v2 |
@@ -96,6 +96,47 @@ A site without a bundler, or a website builder such as Webflow or Shopify, needs
 <script defer src="https://cdn.highseat.com/script.js" data-site="site_…"></script>
 ```
 
+## Embeds
+
+`<Embed />` shows a share link or a widget on your page. Its `token` is the last part of the `/share/` address in the embed code, and `title` names the frame for screen readers. It needs no script tag: the component fits the frame to the embed and follows it as it resizes.
+
+Pass your page's theme when the page has its own switch, so the frame's colours match the page:
+
+```tsx
+"use client"
+
+import { Embed } from "highseat/react"
+import { useTheme } from "next-themes"
+
+export function VisitorsChart() {
+  const { resolvedTheme } = useTheme()
+
+  return (
+    <Embed
+      token="YOUR_WIDGET_TOKEN"
+      title="Visitors in the last 30 days"
+      widget="chart"
+      theme={resolvedTheme === "dark" ? "dark" : "light"}
+    />
+  )
+}
+```
+
+The server renders an empty box at the frame's height, and the frame replaces it after mount. So a theme known only in the browser needs no mounted check of your own and causes no hydration mismatch. If the theme is still unknown after mount, pass `theme={null}`: the box stays empty until you pass a theme, and the frame loads once. Leave `theme` out to follow the reader's own light or dark setting.
+
+| Prop | Default | Does |
+| --- | --- | --- |
+| `token` | Required | The share link or widget to show |
+| `title` | Required | The frame's accessible name |
+| `theme` | `"system"` | `"system"`, `"light"`, `"dark"`, or `null` while your page's theme is unknown |
+| `widget` | None, for a whole board | `"chart"` or `"figure"`, which sets the height held before the frame loads: 360px, 80px, or 1600px for a board |
+| `background` | `"transparent"` for a widget, otherwise `"default"` | `"transparent"` lets your page's background show through |
+| `height` | Set by `widget` | The height in pixels to hold until the embed reports its own |
+| `credit` | `true` | Shows the "Analytics by Highseat" link under the frame |
+| `creditClassName` | None | A class for the credit link, which replaces its default spacing and size |
+
+`className` and `style` go to the box around the frame and the credit link. Other attributes, such as `id` or `loading`, go to the frame. The credit link is a plain, followed link in the server's HTML, and it is yours to remove: pass `credit={false}`.
+
 ## 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.
@@ -400,7 +441,7 @@ To rotate the path, rotate it in Installation settings, update `HIGHSEAT_PATH` a
 | --- | --- | --- |
 | `clientIp` | Required | Where the visitor's IP comes from: `"vercel"`, `"cloudflare"`, `"netlify"`, `"nginx"` (the `X-Real-IP` header your nginx sets), or a function `(request) => string`. The outermost proxy that sets the header decides the preset: behind a proxied Cloudflare record, use `"cloudflare"` on any origin (Next.js, TanStack Start, a Node server, with or without Traefik or nginx in between), whose `X-Real-IP` holds a Cloudflare edge address. A visitor can write any header the host does not overwrite, so there is no default and no fallback to `X-Forwarded-For`. |
 | `path` | `HIGHSEAT_PATH` | The proxy path. Any other path answers 404, or goes to `fallback`. Leave it unset where your router already sends only the proxy path to the handler. |
-| `secret` | `HIGHSEAT_SECRET` | The site secret. An older secret that starts `hs_proxy_` or `ana_proxy_` works too. A value with neither prefix throws. |
+| `secret` | `HIGHSEAT_SECRET` | The site secret. A value that does not start with `hs_secret_` throws. |
 | `upstream` | `https://cdn.highseat.com` | The Highseat ingest origin. |
 | `fallback` | None | Answers every other path, for a handler that sees every request on the site. Needs `path`. |
 

package/api.d.ts

@@ -0,0 +1,123 @@
+import { paths } from "./api.gen.js";
+//#region src/api.d.ts
+type Method = "get" | "post" | "patch" | "delete";
+/** A path of the API that answers a method. */
+type PathOf<Name extends Method> = { [Path in keyof paths]: paths[Path] extends Record<Name, object> ? Path : never; }[keyof paths];
+type Operation<Path extends keyof paths, Name extends Method> = paths[Path][Name & keyof paths[Path]];
+type PathOptions<Route> = Route extends {
+  parameters: {
+    path: infer Values;
+  };
+} ? {
+  path: Values;
+} : {
+  path?: undefined;
+};
+type QueryOptions<Route> = Route extends {
+  parameters: {
+    query: infer Values;
+  };
+} ? {
+  query: Values;
+} : Route extends {
+  parameters: {
+    query?: infer Values;
+  };
+} ? {
+  query?: Values;
+} : {
+  query?: undefined;
+};
+type BodyOptions<Route> = Route extends {
+  requestBody: {
+    content: {
+      "application/json": infer Body;
+    };
+  };
+} ? {
+  body: Body;
+} : {
+  body?: undefined;
+};
+/** What every call may add. */
+interface CallOptions {
+  /** Makes a `POST` safe to retry: a repeat within 24 hours replays the first answer. */
+  idempotencyKey?: string;
+  /** Cancels the call. */
+  signal?: AbortSignal;
+}
+type Options<Route> = PathOptions<Route> & QueryOptions<Route> & BodyOptions<Route> & CallOptions;
+type Arguments<Route> = object extends Options<Route> ? [options?: Options<Route>] : [options: Options<Route>];
+type JsonOf<Response> = Response extends {
+  content: {
+    "application/json": infer Body;
+  };
+} ? Body : undefined;
+type ResultOf<Route> = Route extends {
+  responses: infer Responses;
+} ? JsonOf<Responses[Extract<keyof Responses, 200 | 201 | 202 | 204>]> : never;
+type Call<Name extends Method> = <Path extends PathOf<Name>>(path: Path, ...options: Arguments<Operation<Path, Name>>) => Promise<ResultOf<Operation<Path, Name>>>;
+/** What a call to a path answers, for naming it in your own code. */
+export type ApiResult<Path extends keyof paths, Name extends Method = "get"> = ResultOf<Operation<Path, Name>>;
+/** A client of the Highseat API, with one typed function per HTTP method. */
+export interface HighseatApi {
+  get: Call<"get">;
+  post: Call<"post">;
+  patch: Call<"patch">;
+  delete: Call<"delete">;
+}
+/** How to reach the API. */
+export interface ApiOptions {
+  /**
+   * An API key or an OAuth access token. Pass a function when the token changes, as an OAuth
+   * token does when it is refreshed: it runs before every call.
+   */
+  token: string | (() => string | Promise<string>);
+  /** The API's address, with its version. Defaults to `https://api.highseat.com/v1`. */
+  baseUrl?: string;
+  /** Replaces the global `fetch`. */
+  fetch?: typeof globalThis.fetch;
+}
+/** One invalid parameter of a refused call. */
+export interface ApiIssue {
+  /** The parameter at fault, such as `["filter", 1]` for the second filter. */
+  path: (string | number)[];
+  message: string;
+}
+interface ApiFailure {
+  code?: string;
+  message?: string;
+  requestId?: string;
+  id?: string;
+  issues?: ApiIssue[];
+}
+/** A call the API refused. Branch on `code`, which is stable. */
+export declare class HighseatApiError extends Error {
+  /** The HTTP status. */
+  readonly status: number;
+  /** Stable and machine-readable, such as `RATE_LIMITED`. */
+  readonly code: string;
+  /** Names the request. Quote it to support. */
+  readonly requestId?: string;
+  /** On a conflict, the existing row's id. */
+  readonly id?: string;
+  /** One entry per invalid parameter. */
+  readonly issues?: ApiIssue[];
+  constructor(status: number, failure: ApiFailure);
+}
+/**
+ * Creates a client of the Highseat API. Paths, parameters and answers are typed from the API's
+ * OpenAPI document, and a refused call throws {@link HighseatApiError}.
+ *
+ * @example
+ * ```ts
+ * import { createApi } from "highseat/api"
+ *
+ * const api = createApi({ token: process.env.HIGHSEAT_API_KEY })
+ * const { data } = await api.get("/sites/{site}/realtime", { path: { site: "example.com" } })
+ * ```
+ */
+export declare function createApi({ token, baseUrl, fetch }: ApiOptions): HighseatApi;
+//#endregion
+export {};
+//# sourceMappingURL=api.d.ts.map