@whop/elements 0.0.0 → 1.0.0-beta.0

package/websites.d.cts

@@ -0,0 +1,356 @@
+/**
+ * Options for `whop.websites.create()`: the controller's props plus its `on<Event>` callbacks. In React, these are the `<Websites>` component's props.
+ * @example
+ * ```ts
+ * import { loadWhop } from "@whop/elements";
+ * 
+ * const whop = (await loadWhop())({ locale: "en" });
+ * const websites = whop.websites.create({}); // options: props + on<Event> callbacks
+ * ```
+ * @see https://docs.whop.com/elements/latest/websites/overview
+ */
+export interface WebsitesOptions {
+	/**
+	 * How many days of traffic the table covers, from 1 to 90. @default 30
+	 * @default 30
+	 */
+	windowDays?: number;
+	/**
+	 * List websites built on whop.app from the moment they exist, with zeros until traffic arrives. Turn off to show only domains the pixel reports. @default true
+	 * @default true
+	 */
+	includeApps?: boolean;
+	/**
+	 * Websites you have just added that are not live yet — `{ domain, kind }`, where `kind` is `deploy` for a whop.app site waiting on its first deploy or `events` for a site waiting on its first pixel events. They render as waiting rows so a site never looks lost right after setup, and the table polls while any is outstanding. Sites the mounted `pixel-setup` wizard proves live are added for you, kept across a reload, and are NOT your job — this is for the waits the handle cannot see for itself, above all a whop.app site you just created, which no element here reports. Entries you add are yours to remove: a row stops being drawn once its domain reaches the table, but the list itself only changes when you change it, so drop an entry when `websitesLoaded` names its domain and give the rest a timeout of your own.
+	 * @default []
+	 */
+	pendingWebsites?: PendingWebsite[];
+	/**
+	 * Add a pixel-check button to each row. The element only reports the press through `onVerifyRequested` — opening the site and deciding the outcome is yours, because a popup opened by your own page is the one browsers trust.
+	 * @default false
+	 */
+	showVerify?: boolean;
+	/**
+	 * Add a settings button to whop.app rows. The element only reports the press through `onSettingsRequested` — the editing surface is yours.
+	 * @default false
+	 */
+	showSettings?: boolean;
+	/**
+	 * Add an edit button to whop.app rows, styled as the row’s primary action. The element only reports the press through `onEditRequested` — the editing surface is yours.
+	 * @default false
+	 */
+	showEdit?: boolean;
+	/**
+	 * Which row the check in progress belongs to — the `target` from the `verifyRequested` event you are handling.
+	 * @default ""
+	 */
+	verifyTarget?: string;
+	/**
+	 * How the check in progress is going, shown on that row’s button: `waiting`, `connected`, `not-detected`, or `blocked` when the popup was blocked.
+	 * @default "idle"
+	 */
+	verifyStatus?: "idle" | "waiting" | "connected" | "not-detected" | "blocked";
+	/**
+	 * A scoped token for the reads — stats need `stats:read`, and the whop.app website list reads apps (rows degrade to traffic-only if the token can’t). Mint it on your server with `POST /api/v1/access_tokens` and set a fresh one before it expires. `pixel-setup` is the one child this is not projected into — it authenticates its own scans from its own `accessToken` — so mint a single token carrying both sets of scopes and pass that same string to both, rather than one token per element. Omitted, the reads carry the viewer’s own session, which only answers same-origin.
+	 */
+	accessToken?: string;
+	/**
+	 * Account ID, prefixed `biz_`, whose websites these surfaces read.
+	 */
+	accountId: string;
+	/**
+	 * 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 "websites" element. Set at create (or as `<WebsitesElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/websites/websites
+ */
+export interface WebsitesElementProps {}
+
+/**
+ * The live handle for a mounted "websites" element. Returned by `create("websites")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/websites/websites
+ */
+export interface WebsitesElementHandle {
+	/**
+	 * 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<WebsitesElementProps>) => void;
+}
+
+/**
+ * Options for `create("websites")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const websites = websites.create("websites", {}); // this interface: props + on<Event> callbacks
+ * websites.mount("#websites-websites");
+ * ```
+ * @see https://docs.whop.com/elements/latest/websites/websites
+ */
+export interface WebsitesElementCreateOptions {
+	/**
+	 * A domain row was expanded or collapsed to show or hide its pages.
+	 */
+	onWebsiteToggled?: ((payload: { domain: string; expanded: boolean; }) => void);
+	/**
+	 * The table settled on a list of domains. Fires on every load, not only when the list changes, so a poll that comes back the same still reports — use it to drop any `pendingWebsites` that are now live.
+	 */
+	onWebsitesLoaded?: ((payload: { domains: string[]; }) => void);
+	/**
+	 * The pixel-check button was pressed. Open `url` and watch for pixel events on your side, then push the outcome back through the handle’s `verifyStatus` so the button reflects it.
+	 */
+	onVerifyRequested?: ((payload: { target: string; url: string; }) => void);
+	/**
+	 * The settings button on a whop.app row was pressed. The element only reports the click — open your own editing surface for the app.
+	 */
+	onSettingsRequested?: ((payload: { appId: string; route: string; domain: string; }) => void);
+	/**
+	 * The edit button on a whop.app row was pressed. The element only reports the click — open your own editing surface for the app.
+	 */
+	onEditRequested?: ((payload: { appId: string; route: string; domain: 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 "pixel-setup" element. Set at create (or as `<PixelSetupElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/websites/pixel-setup
+ */
+export interface PixelSetupElementProps {
+	/**
+	 * Account ID, prefixed `biz_`, whose pixel this is. Required; the snippet, scans, and invites all run against it.
+	 * @default ""
+	 */
+	accountId?: string;
+	/**
+	 * A scoped token for the scans and the developer invite. The scans need `company:basic:read`; “Invite a developer” additionally needs `authorized_user:create`, and the event presets read the account with `company:balance:read` (without it the wizard still works, on a generic preset list). Mint it on your server with `POST /api/v1/access_tokens` and set a fresh one before it expires. Another element that opens this wizard inside itself — the ads `campaign-creator` does — runs these calls on its own token, so add these scopes to that one token rather than minting a second: this element has no way to read a credential you set elsewhere. Omitted, the calls carry the viewer’s own session, which only answers same-origin.
+	 */
+	accessToken?: string;
+	/**
+	 * The page to check, scanned on mount. Leave it blank and the wizard asks for one. Also what gates "Verify live" on the events step — that button walks the account owner through their own funnel to catch events a server-side scan cannot see, so it only appears once a destination is known, from here or named in the wizard. Read once at boot, so `update()` will not retarget mid-flow — mint a fresh mount for a different page.
+	 * @default ""
+	 */
+	destinationUrl?: string;
+	/**
+	 * Optional. An event that must fire on that page (`lead`, `schedule`, `view_content`, …); the events step blocks until it is detected. Unset, every event is offered and none is required. Events Whop records server-side (`purchase`, `subscribe`, trials, checkout steps) are ignored. Read once at boot.
+	 * @default ""
+	 */
+	eventName?: string;
+	/**
+	 * A URL the destination redirects to, when the event fires there instead. The account owner can also set one in the wizard — listen for `redirectUrlChanged` and pass it back next time.
+	 * @default ""
+	 */
+	redirectUrl?: string;
+	/**
+	 * Where the wizard opens: the install step, or straight onto `events` when the pixel is already there and only the conversion event is missing.
+	 * @default "install"
+	 */
+	initialStep?: "events" | "install";
+	/**
+	 * Open on the "why a pixel" splash. Turn it off where the account owner already knows why they are here — a campaign flow that sends them in mid-launch — and the wizard opens straight on the install step.
+	 * @default true
+	 */
+	showIntro?: boolean;
+	/**
+	 * Offer the "Invite a developer to install it" path. Hide it where the people using your embed should not be inviting members onto the Whop team behind it.
+	 * @default true
+	 */
+	showInviteDeveloper?: boolean;
+	/**
+	 * Show the "your pixel is live" screen after a page checks out, which offers conversion events as the next thing to do. Turn it off where the account owner came for the events themselves — a passing check then goes straight to them instead of pausing on a screen they would click through.
+	 * @default true
+	 */
+	showOptimizePrompt?: boolean;
+}
+
+/**
+ * The live handle for a mounted "pixel-setup" element. Returned by `create("pixel-setup")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/websites/pixel-setup
+ */
+export interface PixelSetupElementHandle {
+	/**
+	 * 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<PixelSetupElementProps>) => void;
+}
+
+/**
+ * Options for `create("pixel-setup")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const pixel_setup = websites.create("pixel-setup", {}); // this interface: props + on<Event> callbacks
+ * pixel_setup.mount("#websites-pixel-setup");
+ * ```
+ * @see https://docs.whop.com/elements/latest/websites/pixel-setup
+ */
+export interface PixelSetupElementCreateOptions {
+	/**
+	 * Account ID, prefixed `biz_`, whose pixel this is. Required; the snippet, scans, and invites all run against it.
+	 * @default ""
+	 */
+	accountId?: string;
+	/**
+	 * A scoped token for the scans and the developer invite. The scans need `company:basic:read`; “Invite a developer” additionally needs `authorized_user:create`, and the event presets read the account with `company:balance:read` (without it the wizard still works, on a generic preset list). Mint it on your server with `POST /api/v1/access_tokens` and set a fresh one before it expires. Another element that opens this wizard inside itself — the ads `campaign-creator` does — runs these calls on its own token, so add these scopes to that one token rather than minting a second: this element has no way to read a credential you set elsewhere. Omitted, the calls carry the viewer’s own session, which only answers same-origin.
+	 */
+	accessToken?: string;
+	/**
+	 * The page to check, scanned on mount. Leave it blank and the wizard asks for one. Also what gates "Verify live" on the events step — that button walks the account owner through their own funnel to catch events a server-side scan cannot see, so it only appears once a destination is known, from here or named in the wizard. Read once at boot, so `update()` will not retarget mid-flow — mint a fresh mount for a different page.
+	 * @default ""
+	 */
+	destinationUrl?: string;
+	/**
+	 * Optional. An event that must fire on that page (`lead`, `schedule`, `view_content`, …); the events step blocks until it is detected. Unset, every event is offered and none is required. Events Whop records server-side (`purchase`, `subscribe`, trials, checkout steps) are ignored. Read once at boot.
+	 * @default ""
+	 */
+	eventName?: string;
+	/**
+	 * A URL the destination redirects to, when the event fires there instead. The account owner can also set one in the wizard — listen for `redirectUrlChanged` and pass it back next time.
+	 * @default ""
+	 */
+	redirectUrl?: string;
+	/**
+	 * Where the wizard opens: the install step, or straight onto `events` when the pixel is already there and only the conversion event is missing.
+	 * @default "install"
+	 */
+	initialStep?: "events" | "install";
+	/**
+	 * Open on the "why a pixel" splash. Turn it off where the account owner already knows why they are here — a campaign flow that sends them in mid-launch — and the wizard opens straight on the install step.
+	 * @default true
+	 */
+	showIntro?: boolean;
+	/**
+	 * Offer the "Invite a developer to install it" path. Hide it where the people using your embed should not be inviting members onto the Whop team behind it.
+	 * @default true
+	 */
+	showInviteDeveloper?: boolean;
+	/**
+	 * Show the "your pixel is live" screen after a page checks out, which offers conversion events as the next thing to do. Turn it off where the account owner came for the events themselves — a passing check then goes straight to them instead of pausing on a screen they would click through.
+	 * @default true
+	 */
+	showOptimizePrompt?: boolean;
+	/**
+	 * The account owner set or cleared a redirect URL in the wizard. Persist it and pass it back as `redirectUrl` next time.
+	 */
+	onRedirectUrlChanged?: ((payload: { url: string; }) => void);
+	/**
+	 * A pixel scan settled. Fires for every URL the wizard checks, so your own install badge can follow it. `primary` marks the page being set up: the funnel checker scans whatever else the account owner lists, other hostnames included, so gate on it before you treat a result as being about their site. You do not need this to keep a `websites` table honest — mounted under that handle, a site proven live already gets its waiting row.
+	 */
+	onScanned?: ((payload: { url: string; status: "installed" | "missing" | "unreachable"; installed: boolean; primary: boolean; }) => void);
+	/**
+	 * Done was pressed. Re-check the page yourself — this says the wizard finished, not that your requirements are met.
+	 */
+	onFinished?: ((payload: Record<string, never>) => void);
+	/**
+	 * The account owner walked their funnel with "Verify live" and this event fired — proof it is wired where a server-side scan cannot reach.
+	 */
+	onEventVerified?: ((payload: { url: string; event: 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 overlay handle for "pixel-setup". Returned by `createOverlay("pixel-setup")`; drives the modal presentation imperatively.
+ * @see https://docs.whop.com/elements/latest/websites/pixel-setup
+ */
+export interface PixelSetupElementOverlayHandle {
+	/**
+	 * 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<PixelSetupElementProps>): void;
+}
+
+/**
+ * The Websites handle, returned by `whop.websites.create()` (React: `useWebsites()`). Mounts the elements and carries the controller's actions.
+ * @see https://docs.whop.com/elements/latest/websites/overview
+ */
+export interface WebsitesHandle {
+	/**
+	 * An account's websites in one table: every site built on whop.app — listed from the moment it exists, zeros until traffic arrives — merged by hostname with every domain the Whop Pixel reports. Rows for the whop.app sites carry a Whop mark, so the two sources stay apart even when both have traffic. Each row shows a page-view trend, unique visitors, page views, attributed sales, USD revenue, and the last day an event arrived. Expanding a domain loads its most-viewed pages, and each page-view figure opens the breakdown of which events made it up. Set `showVerify` to add a per-row button that asks the page hosting this element to open the site and confirm the pixel is firing; set `showSettings` to add a settings button on whop.app rows that reports the click through `onSettingsRequested`, and `showEdit` to add a primary edit button reporting through `onEditRequested` — your page owns the actual editing.
+	 */
+	create(name: "websites", options?: WebsitesElementCreateOptions): WebsitesElementHandle;
+	/**
+	 * Installs the Whop Pixel and wires conversion events: copy the snippet, check a page for it, confirm the events fire. Mount it inline, or inside your own overlay.
+	 */
+	create(name: "pixel-setup", options?: PixelSetupElementCreateOptions): PixelSetupElementHandle;
+	/**
+	 * Installs the Whop Pixel and wires conversion events: copy the snippet, check a page for it, confirm the events fire. Mount it inline, or inside your own overlay.
+	 */
+	createOverlay(name: "pixel-setup", options?: PixelSetupElementCreateOptions): PixelSetupElementOverlayHandle;
+	/**
+	 * Merges new handle options into every mounted element. In React, change the namespace props instead.
+	 */
+	update(options: Partial<WebsitesOptions>): void;
+}
+
+/**
+ * Websites's static actions, callable with nothing mounted: `whop.websites.<method>()` (React: `useWhop().websites.<method>()`).
+ * @see https://docs.whop.com/elements/latest/websites/overview
+ */
+export interface WebsitesStatics {}
+
+/**
+ * Declared from the app's `PendingWebsite`, referenced by a host-capability surface.
+ */
+export interface PendingWebsite {
+	domain: string;
+	kind: "events" | "deploy";
+}