@whop/elements 0.0.0 → 1.0.0-beta.1

package/ads.d.cts

@@ -0,0 +1,585 @@
+/**
+ * Options for `whop.ads.create()`: the controller's props plus its `on<Event>` callbacks. In React, these are the `<Ads>` component's props.
+ * @example
+ * ```ts
+ * import { loadWhop } from "@whop/elements";
+ * 
+ * const whop = (await loadWhop())({ locale: "en" });
+ * const ads = whop.ads.create({}); // options: props + on<Event> callbacks
+ * ```
+ * @see https://docs.whop.com/elements/latest/ads/overview
+ */
+export interface AdsOptions {
+	/**
+	 * Whop account ID, prefixed `biz_`, whose advertising this reads. Required; this is not an ad account ID.
+	 * @default ""
+	 */
+	accountId?: string;
+	/**
+	 * A scoped token every surface under this handle reads and writes with. **Mint one token for the whole handle, not one per element.** Work out the scopes of every element you are going to mount, request them on a single token, and set it here — the handle projects that one credential into each element's frame, so a second token per surface buys nothing and leaves you several expiration dates to track instead of one. Mint it on your server with `POST /api/v1/access_tokens` and set a fresh one with `update({ accessToken })` before it expires. Mounting everything needs `ad_campaign:read`/`:create`, `ad_group:read`, `ad:read`, `stats:read`, the `:update`/`:delete` scopes the table's row actions use, `company:basic:read` for the pixel checks `campaign-creator` runs, and `payment:charge` plus `user:email:read` to add an ad-spend card. Mounting fewer surfaces can ask for fewer scopes — still on the one token. Omitted, the calls carry the viewer's own session, which only answers same-origin.
+	 */
+	accessToken?: string;
+	/**
+	 * Where the reporting `table`’s click and result counts link on your site — typically the pages where you mounted the `tracking` namespace’s `people` and `events` elements. `people` and `events` are absolute base URLs (`https://…`); the table appends the same query params those elements take as props (`?source=whop:adcamp_…:*&event=…&from=…&to=…`), so the target page can hydrate its element straight from its URL. A relative URL would resolve against the element frame, so one is treated as unset; unset links render the counts as plain figures.
+	 * @default {}
+	 */
+	links?: CrossLinksConfig;
+	/**
+	 * The account's ad-spend payment methods changed and the change is saved. Slot values are the method IDs themselves — `payt_…` for a card, `ldgr_…` for a balance; an empty `backup` means none is set.
+	 */
+	onBillingChanged?: ((payload: { primary: string; backup: string; }) => void);
+	/**
+	 * Runs when the grouped loading state changes. The value is `true` while any mounted element is still loading.
+	 */
+	onLoadingChange?: ((loading: boolean) => void);
+	/**
+	 * Set `false` to turn off Whop's built-in usage analytics for this handle and its elements. The analytics identity is never threaded to its frames. A reserved option, not element data.
+	 */
+	analytics?: false;
+	/**
+	 * 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 "billing-setup" element. Set at create (or as `<BillingSetupElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/ads/billing-setup
+ */
+export interface BillingSetupElementProps {}
+
+/**
+ * The live handle for a mounted "billing-setup" element. Returned by `create("billing-setup")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/ads/billing-setup
+ */
+export interface BillingSetupElementHandle {
+	/**
+	 * 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<BillingSetupElementProps>) => void;
+}
+
+/**
+ * Options for `create("billing-setup")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const billing_setup = ads.create("billing-setup", {}); // this interface: props + on<Event> callbacks
+ * billing_setup.mount("#ads-billing-setup");
+ * ```
+ * @see https://docs.whop.com/elements/latest/ads/billing-setup
+ */
+export interface BillingSetupElementCreateOptions {
+	/**
+	 * 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 "campaign-creator" element. Set at create (or as `<CampaignCreatorElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/ads/campaign-creator
+ */
+export interface CampaignCreatorElementProps {
+	/**
+	 * The campaign (`adcamp_…`) to open. Empty builds a new one. A draft opens where it was left off; a launched campaign opens in edit mode.
+	 * @default ""
+	 */
+	campaignId?: string;
+	/**
+	 * The ad group (`adgrp_…`) to open in focus, within `campaignId`. Ignored when the campaign has no such group, and when `campaignId` is empty.
+	 * @default ""
+	 */
+	adGroupId?: string;
+	/**
+	 * The ad (`ad_…`) to open in focus, within `adGroupId`. Ignored when that group has no such ad, and when `adGroupId` is empty.
+	 * @default ""
+	 */
+	adId?: string;
+	/**
+	 * Which step to open on: `campaign-settings`, `ad-groups`, or `ads`. The dashboard deep-links this off its own URL; pass it to drop an account owner straight onto the part they came to change. Read once at mount — moving it later will not walk them between steps.
+	 * @default "campaign-settings"
+	 */
+	initialStep?: "ads" | "ad-groups" | "campaign-settings";
+}
+
+/**
+ * The live handle for a mounted "campaign-creator" element. Returned by `create("campaign-creator")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/ads/campaign-creator
+ */
+export interface CampaignCreatorElementHandle {
+	/**
+	 * 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<CampaignCreatorElementProps>) => void;
+}
+
+/**
+ * Options for `create("campaign-creator")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const campaign_creator = ads.createOverlay("campaign-creator", {}); // this interface: props + on<Event> callbacks
+ * campaign_creator.open();
+ * ```
+ * @see https://docs.whop.com/elements/latest/ads/campaign-creator
+ */
+export interface CampaignCreatorElementCreateOptions {
+	/**
+	 * The campaign (`adcamp_…`) to open. Empty builds a new one. A draft opens where it was left off; a launched campaign opens in edit mode.
+	 * @default ""
+	 */
+	campaignId?: string;
+	/**
+	 * The ad group (`adgrp_…`) to open in focus, within `campaignId`. Ignored when the campaign has no such group, and when `campaignId` is empty.
+	 * @default ""
+	 */
+	adGroupId?: string;
+	/**
+	 * The ad (`ad_…`) to open in focus, within `adGroupId`. Ignored when that group has no such ad, and when `adGroupId` is empty.
+	 * @default ""
+	 */
+	adId?: string;
+	/**
+	 * Which step to open on: `campaign-settings`, `ad-groups`, or `ads`. The dashboard deep-links this off its own URL; pass it to drop an account owner straight onto the part they came to change. Read once at mount — moving it later will not walk them between steps.
+	 * @default "campaign-settings"
+	 */
+	initialStep?: "ads" | "ad-groups" | "campaign-settings";
+	/**
+	 * The account owner backed out of the builder without launching. Nothing has been discarded — a draft campaign, if one was started, is already saved. An overlay has already closed itself by the time this fires; react to it if your page needs to.
+	 */
+	onExited?: ((payload: Record<string, never>) => void);
+	/**
+	 * A campaign went live. `firstLaunch` marks the account’s first ever launched campaign, which is what the dashboard uses to show its welcome state. An overlay has already closed itself; this is where you route onward.
+	 */
+	onLaunched?: ((payload: { campaignId: string; firstLaunch: boolean; }) => 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 overlay handle for "campaign-creator". Returned by `createOverlay("campaign-creator")`; drives the modal presentation imperatively.
+ * @see https://docs.whop.com/elements/latest/ads/campaign-creator
+ */
+export interface CampaignCreatorElementOverlayHandle {
+	/**
+	 * Open the overlay. The first call mounts the element. Later calls reuse it.
+	 */
+	open(): void;
+	/**
+	 * Close the overlay without destroying it. Keep the handle and `open()` again.
+	 */
+	close(): 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<CampaignCreatorElementProps>): void;
+}
+
+/**
+ * Consumer props for the "reporting" sub-controller: the `create("reporting")` options and the minted sub handle's `update()` payload (React: `<Reporting>` props). Parent-injected props never appear here.
+ * @see https://docs.whop.com/elements/latest/ads/overview
+ */
+export interface ReportingSubOptions {
+	/**
+	 * The window every surface reports on: `today`, `yesterday`, `last_7_days`, `last_14_days`, `last_30_days`, `last_90_days`, `all_time`, or `custom` (pair it with `customRange`). The chart carries the picker, and it moves this — so a host can drive the window and 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;
+	/**
+	 * Timezone choice for every reported figure. Use `account` for the account's `preferences.ads_scheduling_timezone` or `local` for the viewer's browser timezone. These are the only choices the chart offers. A free-form IANA timezone could make the picker label data incorrectly and would be lost when the viewer changes the selection. To report in another timezone, change the account setting. `account` falls back to the viewer's timezone when the account has no setting.
+	 * @default "account"
+	 */
+	timezone?: "account" | "local";
+	/**
+	 * Lowercase three-letter ISO 4217 currency code for converted amounts, such as `usd` or `eur`. Unset, it defaults to the account's `preferences.ads_reporting_currency`.
+	 * @default ""
+	 */
+	currency?: string;
+	/**
+	 * Which touch in a buyer’s journey gets the credit: `last_touch`, the default, or `first_touch`. Under both, a Whop touch anywhere in the journey wins the Whop bucket — the model only picks the endpoints. The table carries the picker and moves this, so a host can drive it and read it back off `attributionModelChanged`.
+	 * @default "last_touch"
+	 */
+	attributionModel?: "last_touch" | "first_touch";
+	/**
+	 * Narrow reporting to these ad campaigns (`adcamp_…`). Empty reports on the whole account. Overridden by `adGroupIds` or `adIds` when either is set. **Pass one ID for an exact figure:** the reporting API scopes by a single source path, so where more than one is given the chart reports on the first alone.
+	 * @default []
+	 */
+	campaignIds?: string[];
+	/**
+	 * Narrow reporting to these ad groups (`adgrp_…`). Takes precedence over `campaignIds`. Same single-ID caveat.
+	 * @default []
+	 */
+	adGroupIds?: string[];
+	/**
+	 * Narrow reporting to these ads (`ad_…`). The narrowest filter — takes precedence over both others. Same single-ID caveat.
+	 * @default []
+	 */
+	adIds?: string[];
+	/**
+	 * Which table the `table` element opens on: `campaigns`, `ad-groups`, `ads`, or `all` for the traffic-source view. `all` always reports account-wide — the source series exists only at that level — so a filter set alongside it narrows the table but not the chart.
+	 * @default "campaigns"
+	 */
+	tab?: "ads" | "all" | "campaigns" | "ad-groups";
+	/**
+	 * Which traffic the chart reports on, as source paths — `whop:*` for advertising bought through Whop, `ext:*` and `ext:<platform>:*` for ads run elsewhere, `referrer:*` for organic, `direct`, `other`. `null`, the default, reports on Whop advertising alone; `[]` reports on every source; a non-empty array reports on those. A DIFFERENT axis to `campaignIds` and friends, which narrow within Whop advertising — spend-derived ratios stay Whop-attributed whatever this is set to, because spend only ever bought Whop ads. The `table` element’s All tab moves it.
+	 * @default null
+	 */
+	sources?: string[] | null;
+	/**
+	 * The viewer asked to edit something — a row menu, a draft row, or Edit ad in the details overlay. `campaignId` is always there; `adGroupId` and `adId` narrow it to what they clicked. Only raised when `useCampaignCreator` is off; on, the builder opens over the page instead and this stays quiet.
+	 */
+	onEditRequested?: ((payload: AdsEditTarget) => void);
+}
+
+/**
+ * Consumer props for the "reporting" sub-controller's "chart" element.
+ * @see https://docs.whop.com/elements/latest/ads/overview
+ */
+export interface ChartElementProps {
+	/**
+	 * What the chart plots — `spend`, `impressions`, `clicks`, or a conversion. The picker moves it; set it to open on something else. For `conversions`, `conversion_value` and `cost_per_conversion`, name the conversion in `metricEvent`.
+	 * @default "spend"
+	 */
+	metric?: "funnel" | "spend" | "impressions" | "clicks" | "cost_per_1k_impressions" | "cost_per_click" | "conversions" | "conversion_value" | "cost_per_conversion";
+	/**
+	 * The conversion `metric` refers to when it is a per-conversion one — `payment.completed`, `pixel.lead`, or a custom event the account names itself. Ignored by every other metric.
+	 * @default ""
+	 */
+	metricEvent?: string;
+}
+
+/**
+ * The live handle for a mounted "chart" element. Returned by the "reporting" sub handle's `create("chart")`.
+ * @see https://docs.whop.com/elements/latest/ads/overview
+ */
+export interface ChartElementHandle {
+	/**
+	 * 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<ChartElementProps>) => void;
+}
+
+/**
+ * Options for the "reporting" sub handle's `create("chart")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @see https://docs.whop.com/elements/latest/ads/overview
+ */
+export interface ChartElementCreateOptions {
+	/**
+	 * What the chart plots — `spend`, `impressions`, `clicks`, or a conversion. The picker moves it; set it to open on something else. For `conversions`, `conversion_value` and `cost_per_conversion`, name the conversion in `metricEvent`.
+	 * @default "spend"
+	 */
+	metric?: "funnel" | "spend" | "impressions" | "clicks" | "cost_per_1k_impressions" | "cost_per_click" | "conversions" | "conversion_value" | "cost_per_conversion";
+	/**
+	 * The conversion `metric` refers to when it is a per-conversion one — `payment.completed`, `pixel.lead`, or a custom event the account names itself. Ignored by every other metric.
+	 * @default ""
+	 */
+	metricEvent?: string;
+	/**
+	 * The viewer picked a different result to plot. `metric` is what is being plotted; `event` names the conversion it refers to, and is present only for `conversions`, `conversion_value` and `cost_per_conversion` — the account decides what those are called, so it is a string rather than a member. Mirror it into your own URL and hand it back as `metric`/`metricEvent` if you want the choice to survive a reload; the element holds it for the life of the mount either way.
+	 */
+	onMetricChanged?: ((payload: { metric: "funnel" | "spend" | "impressions" | "clicks" | "cost_per_1k_impressions" | "cost_per_click" | "conversions" | "conversion_value" | "cost_per_conversion"; event?: string | undefined; }) => void);
+	/**
+	 * The viewer switched which zone the figures are reported in: the choice they made AND the IANA zone it resolves to. The choice is the half that survives a reload — persist it and pass it back as `timezone`, which is what the Whop dashboard does with its own copy; the element holds it for the life of the mount either way. `resolved` comes along so a host can label its own figures without repeating the account-preference lookup, and is the viewer's own zone whenever the account has set none.
+	 */
+	onTimezoneChanged?: ((payload: { timezone: "account" | "local"; resolved: string; }) => void);
+	/**
+	 * The viewer moved the reporting window: the period they picked AND the window it resolves to, as ISO 8601 instants. The dates come resolved because a period name alone would leave you redoing the day-boundary and account-timezone arithmetic to act on it; the period comes too because only it survives a reload as a ROLLING window — stored dates would pin it. Every surface under the same handle has already followed the move.
+	 */
+	onPeriodChanged?: ((payload: { period: "today" | "yesterday" | "last_7_days" | "last_14_days" | "last_30_days" | "last_90_days" | "all_time" | "custom"; from: string; to: 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 "reporting" sub-controller's "table" element.
+ * @see https://docs.whop.com/elements/latest/ads/overview
+ */
+export interface TableElementProps {
+	/**
+	 * What happens when a viewer asks to edit — from a row menu, a draft row, or Edit ad in the details overlay. On by default: the campaign builder opens over the page, on the campaign and step they asked for, so editing works with nothing wired up. Turn it off to handle campaign editing yourself — nothing opens, and the request comes back on `editRequested`.
+	 * @default true
+	 */
+	useCampaignCreator?: boolean;
+	/**
+	 * How rows are broken down — by country, platform, placement — or `null` for whole rows.
+	 * @default null
+	 */
+	breakdown?: "age" | "gender" | "age_gender" | "placement" | "publisher_platform" | "device_platform" | "impression_device" | "country" | "region" | "hour" | null;
+	/**
+	 * The columns on show, by name — standard ones like `impressions` and `roas`, and any pixel events the viewer added. Unset, the table opens on its own defaults. Comes back whole on `columnsChanged`; store the list and pass it here to have the layout stick.
+	 * @default null
+	 */
+	columns?: string[] | null;
+	/**
+	 * Columns computed from the figures already in the table — a formula that you name and format. The table can edit them, and every change comes back on `customMetricsChanged` as the whole new list; persist it and pass it here to have it stick.
+	 * @default []
+	 */
+	customMetrics?: CustomMetricDefinition[];
+	/**
+	 * What the All tab is drilled into, as a source path: `null` for the roots, `ext:*` for a platform list, `ext:<platform>:*` for that platform’s campaigns. Comes back on `viewChanged`.
+	 * @default null
+	 */
+	sourcesDrill?: string | null;
+	/**
+	 * What the Ads tab’s search box is filtered to.
+	 * @default ""
+	 */
+	query?: string;
+	/**
+	 * Whether paused campaigns are listed.
+	 * @default true
+	 */
+	showPausedCampaigns?: boolean;
+}
+
+/**
+ * The live handle for a mounted "table" element. Returned by the "reporting" sub handle's `create("table")`.
+ * @see https://docs.whop.com/elements/latest/ads/overview
+ */
+export interface TableElementHandle {
+	/**
+	 * 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<TableElementProps>) => void;
+}
+
+/**
+ * Options for the "reporting" sub handle's `create("table")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @see https://docs.whop.com/elements/latest/ads/overview
+ */
+export interface TableElementCreateOptions {
+	/**
+	 * What happens when a viewer asks to edit — from a row menu, a draft row, or Edit ad in the details overlay. On by default: the campaign builder opens over the page, on the campaign and step they asked for, so editing works with nothing wired up. Turn it off to handle campaign editing yourself — nothing opens, and the request comes back on `editRequested`.
+	 * @default true
+	 */
+	useCampaignCreator?: boolean;
+	/**
+	 * How rows are broken down — by country, platform, placement — or `null` for whole rows.
+	 * @default null
+	 */
+	breakdown?: "age" | "gender" | "age_gender" | "placement" | "publisher_platform" | "device_platform" | "impression_device" | "country" | "region" | "hour" | null;
+	/**
+	 * The columns on show, by name — standard ones like `impressions` and `roas`, and any pixel events the viewer added. Unset, the table opens on its own defaults. Comes back whole on `columnsChanged`; store the list and pass it here to have the layout stick.
+	 * @default null
+	 */
+	columns?: string[] | null;
+	/**
+	 * Columns computed from the figures already in the table — a formula that you name and format. The table can edit them, and every change comes back on `customMetricsChanged` as the whole new list; persist it and pass it here to have it stick.
+	 * @default []
+	 */
+	customMetrics?: CustomMetricDefinition[];
+	/**
+	 * What the All tab is drilled into, as a source path: `null` for the roots, `ext:*` for a platform list, `ext:<platform>:*` for that platform’s campaigns. Comes back on `viewChanged`.
+	 * @default null
+	 */
+	sourcesDrill?: string | null;
+	/**
+	 * What the Ads tab’s search box is filtered to.
+	 * @default ""
+	 */
+	query?: string;
+	/**
+	 * Whether paused campaigns are listed.
+	 * @default true
+	 */
+	showPausedCampaigns?: boolean;
+	/**
+	 * The open tab changed. Mirror it into your own URL if you want it to survive a reload.
+	 */
+	onTabChanged?: ((payload: { tab: "ads" | "all" | "campaigns" | "ad-groups"; }) => void);
+	/**
+	 * The viewer narrowed the view — by ticking rows, or by clicking through a campaign to its ad groups. Every surface under the same handle has already followed it.
+	 */
+	onFilterChanged?: ((payload: { campaignIds: string[]; adGroupIds: string[]; adIds: string[]; }) => void);
+	/**
+	 * The viewer showed or hid a column. Carries every column now on show, standard and pixel-event alike — store the list and pass it straight back as `columns`, or the layout resets on the next mount.
+	 */
+	onColumnsChanged?: ((payload: { columns: string[]; }) => void);
+	/**
+	 * The viewer added, edited, or removed a computed column. Carries the entire list either way — store it as given and pass it back as `customMetrics`, or they are gone on the next mount.
+	 */
+	onCustomMetricsChanged?: ((payload: { customMetrics: CustomMetricDefinition[]; }) => void);
+	/**
+	 * The viewer moved one of the table’s own controls — the All tab’s drill, the breakdown, the search box, the paused toggle. Carries all four whichever moved; store them and pass them back as props, or they reset on the next mount.
+	 */
+	onViewChanged?: ((payload: { sourcesDrill: string | null; breakdown: "age" | "gender" | "age_gender" | "placement" | "publisher_platform" | "device_platform" | "impression_device" | "country" | "region" | "hour" | null; query: string; showPausedCampaigns: boolean; }) => void);
+	/**
+	 * What the All tab is now looking at, as source paths ready to hand to a chart: `null` off the All tab (Whop advertising alone), `[]` for every source, otherwise the ticked rows or the drilled-into group. Every surface under the same handle has already followed it.
+	 */
+	onSourcesChanged?: ((payload: { sources: string[] | null; }) => void);
+	/**
+	 * The viewer changed which touch gets the credit, from the picker on the All tab. Every surface under the same handle has already re-credited; persist it and pass it back as `attributionModel`, or it reverts to last touch on the next mount.
+	 */
+	onAttributionModelChanged?: ((payload: { attributionModel: "last_touch" | "first_touch"; }) => 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 "reporting" sub-handle, minted by `handle.create("reporting", …)`. Mounts the sub-controller's elements and carries its actions.
+ * @see https://docs.whop.com/elements/latest/ads/overview
+ */
+export interface ReportingSubHandle {
+	/**
+	 * An account’s performance over a window, with a picker for what to plot — spend, impressions, clicks, or any conversion the account records. Read-only.
+	 */
+	create(name: "chart", options?: ChartElementCreateOptions): ChartElementHandle;
+	/**
+	 * An advertising account's campaigns, ad groups, and ads in one table, with the tabs that move between them: pick rows to narrow the level below, search, sort, break the numbers down, choose your columns, and pause, resume, duplicate, or delete straight from a row. The window it reports on and the rows it is filtered to live on the handle, so a chart mounted beside it reports on exactly the same thing.
+	 */
+	create(name: "table", options?: TableElementCreateOptions): TableElementHandle;
+	/**
+	 * Merges new props and callbacks into the sub-controller.
+	 */
+	update(options: Partial<ReportingSubOptions>): void;
+	/**
+	 * Destroys the sub-controller and its elements, then frees its exclusive slot. A later `create("reporting")` starts fresh.
+	 */
+	destroy(): void;
+}
+
+/**
+ * The Ads handle, returned by `whop.ads.create()` (React: `useAds()`). Mounts the elements and carries the controller's actions.
+ * @see https://docs.whop.com/elements/latest/ads/overview
+ */
+export interface AdsHandle {
+	/**
+	 * Which payment methods ad spend bills against: a primary used first, and an optional backup for when it fails. Both are chosen from the methods already saved on the account, and picking one saves it immediately — there is no separate submit. Adding a card opens a card form over your page and returns to the slot that asked for it. The account's own balance appears alongside its cards wherever the account has one.
+	 */
+	create(name: "billing-setup", options?: BillingSetupElementCreateOptions): BillingSetupElementHandle;
+	/**
+	 * The advertising campaign builder: objective and budget, ad groups with their targeting and schedule, and the ads themselves with their creative — the whole flow through to launch. Opens empty to build a new campaign, or on an existing one when you pass `campaignId`. It runs the pixel checker too: a launch is gated on the ad group’s conversion event being live on the destination URL, and the `pixel-setup` wizard opens inside this element to fix an install that is missing. The one token you set on the `ads` handle must carry the pixel scopes alongside the campaign scopes — `ad_campaign:create` and `company:basic:read` — rather than using a separate token per element.
+	 */
+	createOverlay(name: "campaign-creator", options?: CampaignCreatorElementCreateOptions): CampaignCreatorElementOverlayHandle;
+	/**
+	 * An advertising account's reporting: what it spent and what came back, over a window, at whatever level you narrow to. Mount `chart`, `table`, or both — they read the same window, the same credit rule, and the same selection, so two surfaces side by side can never disagree about what they are showing. The `ads` handle's `links` configuration wires the table's click and result counts to your own pages — the ones where you mounted the `tracking` namespace's `people` and `events`.
+	 */
+	create(name: "reporting", options?: ReportingSubOptions): ReportingSubHandle;
+	/**
+	 * Merges new handle options into every mounted element. In React, change the namespace props instead.
+	 */
+	update(options: Partial<AdsOptions>): void;
+	/**
+	 * Destroys every element and sub-controller this handle created, removes the controller frame, and releases its subscriptions. You can call it more than once, but a destroyed handle refuses any other call — create a new handle to start over. React removes the group automatically when the provider unmounts.
+	 */
+	destroy(): void;
+}
+
+/**
+ * Ads's static actions, callable with nothing mounted: `whop.ads.<method>()` (React: `useWhop().ads.<method>()`).
+ * @see https://docs.whop.com/elements/latest/ads/overview
+ */
+export interface AdsStatics {}
+
+/**
+ * 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;
+}
+
+/**
+ * What a builder href asks to edit, once it has been read back out of the route.
+ * Declared from the app's `AdsEditTarget`, referenced by a host-capability surface.
+ */
+export interface AdsEditTarget {
+	campaignId: string;
+	adGroupId?: string | undefined;
+	adId?: string | undefined;
+}
+
+/**
+ * A computed column as anyone outside this module needs it. `id` is deliberately absent — it is a within-render column key (`customMetricColumnVisibility`), never persisted and never meaningful to a caller, so it is minted on the way in rather than carried around.
+ * Declared from the app's `CustomMetricDefinition`, referenced by a host-capability surface.
+ */
+export interface CustomMetricDefinition {
+	name: string;
+	formula: string;
+	format: "number" | "currency" | "percent";
+	enabled: boolean;
+}