@whop/elements 0.0.0 → 1.0.0-beta.0

package/tracking.d.ts

@@ -0,0 +1,517 @@
+/**
+ * Options for `whop.tracking.create()`: the controller's props plus its `on<Event>` callbacks. In React, these are the `<Tracking>` component's props.
+ * @example
+ * ```ts
+ * import { loadWhop } from "@whop/elements";
+ * 
+ * const whop = (await loadWhop())({ locale: "en" });
+ * const tracking = whop.tracking.create({}); // options: props + on<Event> callbacks
+ * ```
+ * @see https://docs.whop.com/elements/latest/tracking/overview
+ */
+export interface TrackingOptions {
+	/**
+	 * Account ID, prefixed `biz_`, whose people and events this reads. Required.
+	 * @default ""
+	 */
+	accountId?: string;
+	/**
+	 * A scoped token both surfaces read with. Mint one token for the whole handle on your server with `POST /api/v1/access_tokens`, and set a fresh one with `update({ accessToken })` before it expires. Reading the lists needs `member:basic:read` or `company:basic:read`; the filter menus' option counts additionally use `stats:read`, and the People table's saved-audience filter uses `audience:basic:read` — without those the menus simply show fewer options. Omitted, the calls carry the viewer's own session, which only answers same-origin.
+	 */
+	accessToken?: string;
+	/**
+	 * Where person links lead on your site. `person` is an absolute-URL template with two placeholders, each replaced URL-encoded per row: `{personId}` is the stable `prsn_…` ID, identical for the same person on every surface — key your page on it; `{identifier}` is the most human-meaningful identifier the surface has (a user ID or email where known), so it can differ across surfaces. It must be absolute (`https://…`) — inside an element frame a relative URL would resolve against the frame, so one is treated as unset. Unset, a person click raises `personOpened` on its element instead. `people` and `events` base URLs are accepted for symmetry with the ads handle but nothing under this handle renders them.
+	 * @default {}
+	 */
+	links?: CrossLinksConfig;
+	/**
+	 * The window both surfaces cover: `today`, `yesterday`, `last_7_days`, `last_14_days`, `last_30_days`, `last_90_days`, `all_time`, or `custom` (pair it with `customRange`). The elements carry the picker and move this; read it back off `periodChanged`.
+	 * @default "last_14_days"
+	 */
+	period?: "today" | "yesterday" | "last_7_days" | "last_14_days" | "last_30_days" | "last_90_days" | "all_time" | "custom";
+	/**
+	 * The explicit window, as ISO 8601 instants, used when `period` is `custom`. Ignored otherwise.
+	 * @default null
+	 */
+	customRange?: { from: string; to: string; } | null;
+	/**
+	 * Which of two zones the window resolves in: `account`, the account's own scheduling zone, or `local`, whichever zone the viewer's browser is in. `account` falls back to the viewer's own when the account has set none.
+	 * @default "account"
+	 */
+	timezone?: "account" | "local";
+	/**
+	 * Which touch in a person’s journey gets the credit when filtering by source: `last_touch`, the default, or `first_touch`. The elements carry the picker and move this, so a host can drive it and read it back off `attributionModelChanged`.
+	 * @default "last_touch"
+	 */
+	attributionModel?: "last_touch" | "first_touch";
+	/**
+	 * Runs when the grouped loading state changes. The value is `true` while any mounted element is still loading.
+	 */
+	onLoadingChange?: ((loading: boolean) => void);
+	/**
+	 * Visual customization for this group's elements. Overrides the global `WhopElements({ appearance })`. Change it live with `update({ appearance })`.
+	 */
+	appearance?: import("./_framework.js").Appearance;
+	/**
+	 * Locale for this group's element UI text. Set it to one of the app's built locales to override the global configuration. Any other value falls back to the default locale.
+	 */
+	locale?: import("./_framework.js").WhopElementsLocale;
+}
+
+/**
+ * Consumer props for the "people" element. Set at create (or as `<PeopleElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/tracking/people
+ */
+export interface PeopleElementProps {
+	/**
+	 * Narrow to people acquired by a traffic source, as a source path — `whop:adcamp_…:*` for one of the account’s campaigns, `ext:*` for ads run elsewhere, `referrer:*`, `direct`. The same value the ads table’s click counts link with, so a page can hydrate this straight from its own URL.
+	 * @default ""
+	 */
+	source?: string;
+	/**
+	 * Narrow to people who performed an event, by its name — `payment.completed`, `pixel.lead`, `pixel.page`.
+	 * @default ""
+	 */
+	eventName?: string;
+	/**
+	 * Narrow to people who performed a custom pixel event, by its custom name. Pairs with an empty `eventName`.
+	 * @default ""
+	 */
+	customEvent?: string;
+	/**
+	 * Narrow by the `utm_source` their traffic carried. Comma-separate to match any of several.
+	 * @default ""
+	 */
+	utmSource?: string;
+	/**
+	 * Narrow by ISO 3166-1 alpha-2 country code, such as `US` or `GB`.
+	 * @default ""
+	 */
+	country?: string;
+	/**
+	 * Narrow by device class — `desktop`, `mobile`, `tablet`, `bot`.
+	 * @default ""
+	 */
+	device?: string;
+	/**
+	 * Narrow by browser name.
+	 * @default ""
+	 */
+	browser?: string;
+	/**
+	 * Narrow by operating system name.
+	 * @default ""
+	 */
+	os?: string;
+	/**
+	 * `true` for customers only, `false` for people who never bought, empty for everyone.
+	 * @default ""
+	 */
+	hasPurchased?: string;
+	/**
+	 * What the search box is filtered to — a name, an email, or an identifier.
+	 * @default ""
+	 */
+	query?: string;
+	/**
+	 * Narrow to a saved audience (`adaud_…`) built from people filters. The audience filter menu moves this.
+	 * @default ""
+	 */
+	audienceId?: string;
+	/**
+	 * Pin the event window for `source`/`eventName` filters to an exact ISO 8601 instant instead of the handle’s `period`. Set both `eventFrom` and `eventTo` or neither.
+	 * @default ""
+	 */
+	eventFrom?: string;
+	/**
+	 * The pinned event window’s end, as an ISO 8601 instant.
+	 * @default ""
+	 */
+	eventTo?: string;
+	/**
+	 * The sorted column: `name`, `email`, `ltv`, `purchase_count`, `event_count`, `first_seen_at`, `last_seen_at`.
+	 * @default "last_seen_at"
+	 */
+	sort?: string;
+	/**
+	 * The sort direction.
+	 * @default "desc"
+	 */
+	dir?: "asc" | "desc";
+}
+
+/**
+ * The live handle for a mounted "people" element. Returned by `create("people")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/tracking/people
+ */
+export interface PeopleElementHandle {
+	/**
+	 * Mounts the element in `target` and starts loading. React components mount themselves.
+	 */
+	mount: (target: string | HTMLElement) => void;
+	/**
+	 * Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.
+	 */
+	destroy: () => void;
+	/**
+	 * Merges new props into the mounted element. In React, change the component props instead.
+	 */
+	update: (options: Partial<PeopleElementProps>) => void;
+}
+
+/**
+ * Options for `create("people")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const people = tracking.create("people", {}); // this interface: props + on<Event> callbacks
+ * people.mount("#tracking-people");
+ * ```
+ * @see https://docs.whop.com/elements/latest/tracking/people
+ */
+export interface PeopleElementCreateOptions {
+	/**
+	 * Narrow to people acquired by a traffic source, as a source path — `whop:adcamp_…:*` for one of the account’s campaigns, `ext:*` for ads run elsewhere, `referrer:*`, `direct`. The same value the ads table’s click counts link with, so a page can hydrate this straight from its own URL.
+	 * @default ""
+	 */
+	source?: string;
+	/**
+	 * Narrow to people who performed an event, by its name — `payment.completed`, `pixel.lead`, `pixel.page`.
+	 * @default ""
+	 */
+	eventName?: string;
+	/**
+	 * Narrow to people who performed a custom pixel event, by its custom name. Pairs with an empty `eventName`.
+	 * @default ""
+	 */
+	customEvent?: string;
+	/**
+	 * Narrow by the `utm_source` their traffic carried. Comma-separate to match any of several.
+	 * @default ""
+	 */
+	utmSource?: string;
+	/**
+	 * Narrow by ISO 3166-1 alpha-2 country code, such as `US` or `GB`.
+	 * @default ""
+	 */
+	country?: string;
+	/**
+	 * Narrow by device class — `desktop`, `mobile`, `tablet`, `bot`.
+	 * @default ""
+	 */
+	device?: string;
+	/**
+	 * Narrow by browser name.
+	 * @default ""
+	 */
+	browser?: string;
+	/**
+	 * Narrow by operating system name.
+	 * @default ""
+	 */
+	os?: string;
+	/**
+	 * `true` for customers only, `false` for people who never bought, empty for everyone.
+	 * @default ""
+	 */
+	hasPurchased?: string;
+	/**
+	 * What the search box is filtered to — a name, an email, or an identifier.
+	 * @default ""
+	 */
+	query?: string;
+	/**
+	 * Narrow to a saved audience (`adaud_…`) built from people filters. The audience filter menu moves this.
+	 * @default ""
+	 */
+	audienceId?: string;
+	/**
+	 * Pin the event window for `source`/`eventName` filters to an exact ISO 8601 instant instead of the handle’s `period`. Set both `eventFrom` and `eventTo` or neither.
+	 * @default ""
+	 */
+	eventFrom?: string;
+	/**
+	 * The pinned event window’s end, as an ISO 8601 instant.
+	 * @default ""
+	 */
+	eventTo?: string;
+	/**
+	 * The sorted column: `name`, `email`, `ltv`, `purchase_count`, `event_count`, `first_seen_at`, `last_seen_at`.
+	 * @default "last_seen_at"
+	 */
+	sort?: string;
+	/**
+	 * The sort direction.
+	 * @default "desc"
+	 */
+	dir?: "asc" | "desc";
+	/**
+	 * The viewer moved the window from the period selector. Every surface under the same handle has already followed it; persist it and pass it back as `period`/`customRange` on the handle, or the window resets on the next mount.
+	 */
+	onPeriodChanged?: ((payload: { period: "today" | "yesterday" | "last_7_days" | "last_14_days" | "last_30_days" | "last_90_days" | "all_time" | "custom"; customRange: { from: string; to: string; } | null; }) => void);
+	/**
+	 * The viewer changed which touch gets the credit, from the filter row’s Attribution menu. Every surface under the same handle has already re-credited; persist it and pass it back as `attributionModel` on the handle, or it reverts on the next mount.
+	 */
+	onAttributionModelChanged?: ((payload: { attributionModel: "last_touch" | "first_touch"; }) => void);
+	/**
+	 * The viewer moved a filter, the search box, or the audience picker. Carries the entire filter state whichever moved — mirror it into your own URL and pass it back as props to make the view reproducible.
+	 */
+	onFiltersChanged?: ((payload: PeopleFilterBag) => void);
+	/**
+	 * The viewer sorted a column. Persist and pass back as `sort`/`dir`, or sorting resets on the next mount.
+	 */
+	onSortChanged?: ((payload: { sort: string; dir: "asc" | "desc"; }) => void);
+	/**
+	 * The viewer clicked a person row and the handle has no `links.person` to follow — open your own person view with it (`personId` is the stable per-person key; `identifier` is the most human-meaningful one the surface has), or pass `links.person` on the handle to turn rows into real anchors instead.
+	 */
+	onPersonOpened?: ((payload: { identifier: string; personId: string; }) => void);
+	/**
+	 * Runs after the loading skeleton first paints and before `onReady`.
+	 */
+	onLoaderStart?: (() => void);
+	/**
+	 * Runs after the element's first complete paint.
+	 */
+	onReady?: (() => void);
+	/**
+	 * Runs when the element fails to load or crashes. The fallback remains visible. Use `code` for programmatic handling. `sourceKey` identifies a failed host-state source.
+	 */
+	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
+}
+
+/**
+ * Consumer props for the "events" element. Set at create (or as `<EventsElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/tracking/events
+ */
+export interface EventsElementProps {
+	/**
+	 * Pin the window to an exact ISO 8601 instant instead of the handle’s `period` — how a deep link reproduces the precise rows behind a metric. Set both `from` and `to` or neither.
+	 * @default ""
+	 */
+	from?: string;
+	/**
+	 * The pinned window’s end, as an ISO 8601 instant.
+	 * @default ""
+	 */
+	to?: string;
+	/**
+	 * Narrow to events attributed to a traffic source, as a source path — `whop:adcamp_…:*` for one of the account’s campaigns, `ext:*`, `referrer:*`, `direct`.
+	 * @default ""
+	 */
+	source?: string;
+	/**
+	 * Narrow by the `utm_source` the traffic carried.
+	 * @default ""
+	 */
+	utmSource?: string;
+	/**
+	 * Narrow by ISO 3166-1 alpha-2 country code, such as `US` or `GB`.
+	 * @default ""
+	 */
+	country?: string;
+	/**
+	 * Narrow by device class — `desktop`, `mobile`, `tablet`, `bot`.
+	 * @default ""
+	 */
+	device?: string;
+	/**
+	 * Narrow by browser name.
+	 * @default ""
+	 */
+	browser?: string;
+	/**
+	 * Narrow by operating system name.
+	 * @default ""
+	 */
+	os?: string;
+	/**
+	 * Narrow to one person’s journey — a person ID, an email, or a visitor cookie. Set, the list ignores the window and shows their whole history. The search box moves this.
+	 * @default ""
+	 */
+	identifier?: string;
+	/**
+	 * Narrow by event name — `payment.completed`, `pixel.lead`, `pixel.page`, or `pixel.custom:<name>` for a custom event. The same value the ads table’s result counts link with.
+	 * @default ""
+	 */
+	event?: string;
+}
+
+/**
+ * The live handle for a mounted "events" element. Returned by `create("events")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/tracking/events
+ */
+export interface EventsElementHandle {
+	/**
+	 * Mounts the element in `target` and starts loading. React components mount themselves.
+	 */
+	mount: (target: string | HTMLElement) => void;
+	/**
+	 * Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.
+	 */
+	destroy: () => void;
+	/**
+	 * Merges new props into the mounted element. In React, change the component props instead.
+	 */
+	update: (options: Partial<EventsElementProps>) => void;
+}
+
+/**
+ * Options for `create("events")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const events = tracking.create("events", {}); // this interface: props + on<Event> callbacks
+ * events.mount("#tracking-events");
+ * ```
+ * @see https://docs.whop.com/elements/latest/tracking/events
+ */
+export interface EventsElementCreateOptions {
+	/**
+	 * Pin the window to an exact ISO 8601 instant instead of the handle’s `period` — how a deep link reproduces the precise rows behind a metric. Set both `from` and `to` or neither.
+	 * @default ""
+	 */
+	from?: string;
+	/**
+	 * The pinned window’s end, as an ISO 8601 instant.
+	 * @default ""
+	 */
+	to?: string;
+	/**
+	 * Narrow to events attributed to a traffic source, as a source path — `whop:adcamp_…:*` for one of the account’s campaigns, `ext:*`, `referrer:*`, `direct`.
+	 * @default ""
+	 */
+	source?: string;
+	/**
+	 * Narrow by the `utm_source` the traffic carried.
+	 * @default ""
+	 */
+	utmSource?: string;
+	/**
+	 * Narrow by ISO 3166-1 alpha-2 country code, such as `US` or `GB`.
+	 * @default ""
+	 */
+	country?: string;
+	/**
+	 * Narrow by device class — `desktop`, `mobile`, `tablet`, `bot`.
+	 * @default ""
+	 */
+	device?: string;
+	/**
+	 * Narrow by browser name.
+	 * @default ""
+	 */
+	browser?: string;
+	/**
+	 * Narrow by operating system name.
+	 * @default ""
+	 */
+	os?: string;
+	/**
+	 * Narrow to one person’s journey — a person ID, an email, or a visitor cookie. Set, the list ignores the window and shows their whole history. The search box moves this.
+	 * @default ""
+	 */
+	identifier?: string;
+	/**
+	 * Narrow by event name — `payment.completed`, `pixel.lead`, `pixel.page`, or `pixel.custom:<name>` for a custom event. The same value the ads table’s result counts link with.
+	 * @default ""
+	 */
+	event?: string;
+	/**
+	 * The viewer moved the window from the period selector. Every surface under the same handle has already followed it; persist it and pass it back as `period`/`customRange` on the handle, or the window resets on the next mount.
+	 */
+	onPeriodChanged?: ((payload: { period: "today" | "yesterday" | "last_7_days" | "last_14_days" | "last_30_days" | "last_90_days" | "all_time" | "custom"; customRange: { from: string; to: string; } | null; }) => void);
+	/**
+	 * The viewer changed which touch gets the credit, from the filter row’s Attribution menu. Every surface under the same handle has already re-credited; persist it and pass it back as `attributionModel` on the handle, or it reverts on the next mount.
+	 */
+	onAttributionModelChanged?: ((payload: { attributionModel: "last_touch" | "first_touch"; }) => void);
+	/**
+	 * The viewer moved a filter or the identifier search. Carries the entire filter state whichever moved — mirror it into your own URL and pass it back as props to make the view reproducible.
+	 */
+	onFiltersChanged?: ((payload: EventsFilterBag) => void);
+	/**
+	 * The viewer clicked a person cell and the handle has no `links.person` to follow — open your own person view with it (`personId` is the stable per-person key; `identifier` is the most human-meaningful one the surface has), or pass `links.person` on the handle to turn the cells into real anchors instead.
+	 */
+	onPersonOpened?: ((payload: { identifier: string; personId: string; }) => void);
+	/**
+	 * Runs after the loading skeleton first paints and before `onReady`.
+	 */
+	onLoaderStart?: (() => void);
+	/**
+	 * Runs after the element's first complete paint.
+	 */
+	onReady?: (() => void);
+	/**
+	 * Runs when the element fails to load or crashes. The fallback remains visible. Use `code` for programmatic handling. `sourceKey` identifies a failed host-state source.
+	 */
+	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
+}
+
+/**
+ * The Tracking handle, returned by `whop.tracking.create()` (React: `useTracking()`). Mounts the elements and carries the controller's actions.
+ * @see https://docs.whop.com/elements/latest/tracking/overview
+ */
+export interface TrackingHandle {
+	/**
+	 * Everyone the account has seen — visitors and customers resolved from pixel activity, with their source, spend, and activity counters. Search, filter by source, event, geography, or device, sort any column, and page through. A row click follows `links.person` when the handle configures it, and otherwise comes back to you as `personOpened`.
+	 */
+	create(name: "people", options?: PeopleElementCreateOptions): PeopleElementHandle;
+	/**
+	 * Every event the account measured — page views, leads, purchases, and custom pixel events — as a raw, filterable stream. The rows behind any metric: filter by event, source, geography, or device over the handle’s window, or search one person’s identifier to read their whole journey. A person cell follows `links.person` when the handle configures it, and otherwise comes back to you as `personOpened`.
+	 */
+	create(name: "events", options?: EventsElementCreateOptions): EventsElementHandle;
+	/**
+	 * Merges new handle options into every mounted element. In React, change the namespace props instead.
+	 */
+	update(options: Partial<TrackingOptions>): void;
+}
+
+/**
+ * Tracking's static actions, callable with nothing mounted: `whop.tracking.<method>()` (React: `useWhop().tracking.<method>()`).
+ * @see https://docs.whop.com/elements/latest/tracking/overview
+ */
+export interface TrackingStatics {}
+
+/**
+ * The consumer-facing shape of an element's `links` prop. `people`/`events` are base URLs the canonical query params are appended to; `person` is a template whose `{personId}` and `{identifier}` placeholders are replaced with the row's URL-encoded values.
+ * Declared from the app's `CrossLinksConfig`, referenced by a host-capability surface.
+ */
+export interface CrossLinksConfig {
+	people?: string | undefined;
+	events?: string | undefined;
+	person?: string | undefined;
+}
+
+/**
+ * Consumer-facing filters for the People element. The element maps these camelCase options to `/api/v1/people` query parameters.
+ * Declared from the app's `PeopleFilterBag`, referenced by a host-capability surface.
+ */
+export interface PeopleFilterBag {
+	source: string;
+	eventName: string;
+	customEvent: string;
+	utmSource: string;
+	country: string;
+	device: string;
+	browser: string;
+	os: string;
+	hasPurchased: string;
+	query: string;
+	audienceId: string;
+	eventFrom: string;
+	eventTo: string;
+}
+
+/**
+ * Consumer-facing filters for the Events element. The element maps these camelCase options to `/api/v1/events` query parameters.
+ * Declared from the app's `EventsFilterBag`, referenced by a host-capability surface.
+ */
+export interface EventsFilterBag {
+	identifier: string;
+	event: string;
+	source: string;
+	country: string;
+	utmSource: string;
+	device: string;
+	browser: string;
+	os: string;
+	from: string;
+	to: string;
+}