@whop/elements 1.0.0-beta.4 → 1.0.0-beta.5

package/dashboard.d.ts

@@ -0,0 +1,328 @@
+/**
+ * Options for `whop.dashboard.create()`: the controller's props plus its `on<Event>` callbacks. In React, these are the `<Dashboard>` component's props.
+ * @example
+ * ```ts
+ * import { loadWhop } from "@whop/elements";
+ * 
+ * const whop = (await loadWhop())({ locale: "en" });
+ * const dashboard = whop.dashboard.create({}); // options: props + on<Event> callbacks
+ * ```
+ * @see https://docs.whop.com/elements/latest/dashboard/overview
+ */
+export interface DashboardOptions {
+	/**
+	 * A scoped token every surface under this handle reads 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 payments needs `payment:basic:read`; buyer emails additionally need `member:email:read`, the customer journey `member:basic:read`, the tracking column `shipment:basic:read`, and the product and plan names on a payment `access_pass:basic:read` and `plan:basic:read`. Omitted, the reads carry the viewer's own session, which only answers same-origin.
+	 */
+	accessToken?: string;
+	/**
+	 * Account ID, prefixed `biz_`, whose payments 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);
+	/**
+	 * 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 "paymentsTable" element. Set at create (or as `<PaymentsTableElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/dashboard/paymentsTable
+ */
+export interface PaymentsTableElementProps {
+	/**
+	 * Show the header action menu, Export button, and table settings button.
+	 * @default true
+	 */
+	showActions?: boolean;
+	/**
+	 * Show the three-dot action menu on each payment row.
+	 * @default true
+	 */
+	showRowActions?: boolean;
+	/**
+	 * Show the six payment status boxes above the filters.
+	 * @default true
+	 */
+	showStatusTabs?: boolean;
+	/**
+	 * Show the tracking column and filter for physical-product accounts. Tracking data requires `shipment:basic:read`.
+	 * @default true
+	 */
+	showTracking?: boolean;
+}
+
+/**
+ * The live handle for a mounted "paymentsTable" element. Returned by `create("paymentsTable")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/dashboard/paymentsTable
+ */
+export interface PaymentsTableElementHandle {
+	/**
+	 * Reload payments after a refund or another change.
+	 */
+	refresh: () => Promise<void>;
+	/**
+	 * 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<PaymentsTableElementProps>) => void;
+}
+
+/**
+ * Options for `create("paymentsTable")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const paymentsTable = dashboard.create("paymentsTable", {}); // this interface: props + on<Event> callbacks
+ * paymentsTable.mount("#dashboard-paymentsTable");
+ * ```
+ * @see https://docs.whop.com/elements/latest/dashboard/paymentsTable
+ */
+export interface PaymentsTableElementCreateOptions {
+	/**
+	 * Show the header action menu, Export button, and table settings button.
+	 * @default true
+	 */
+	showActions?: boolean;
+	/**
+	 * Show the three-dot action menu on each payment row.
+	 * @default true
+	 */
+	showRowActions?: boolean;
+	/**
+	 * Show the six payment status boxes above the filters.
+	 * @default true
+	 */
+	showStatusTabs?: boolean;
+	/**
+	 * Show the tracking column and filter for physical-product accounts. Tracking data requires `shipment:basic:read`.
+	 * @default true
+	 */
+	showTracking?: boolean;
+	/**
+	 * Open payment details in your application.
+	 */
+	onPaymentSelected?: ((payload: { paymentId: string; }) => void);
+	/**
+	 * Open the invoice in your application.
+	 */
+	onInvoiceRequested?: ((payload: { paymentId: string; }) => void);
+	/**
+	 * Open the buyer in your application.
+	 */
+	onUserSelected?: ((payload: { userId: string; }) => void);
+	/**
+	 * The viewer requested a refund. Your application must confirm and authorize it server-side. Refund controls are enabled only when this callback is provided.
+	 */
+	onRefundRequested?: ((payload: { paymentIds: string[]; }) => void);
+	/**
+	 * Open the account’s payment settings in your application.
+	 */
+	onSettingsRequested?: ((payload: Record<string, never>) => 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 "paymentDetail" element. Set at create (or as `<PaymentDetailElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/dashboard/paymentDetail
+ */
+export interface PaymentDetailElementProps {
+	/**
+	 * Show the top-right Refund button and action menu. Mutating actions require event handlers.
+	 * @default true
+	 */
+	showActions?: boolean;
+	/**
+	 * The payment to display, prefixed pay_. Required to load a payment.
+	 * @default ""
+	 */
+	paymentId?: string;
+	/**
+	 * Show the payment amount, fees, and net amount.
+	 * @default true
+	 */
+	showBreakdown?: boolean;
+	/**
+	 * Show the payment activity timeline.
+	 * @default true
+	 */
+	showActivity?: boolean;
+	/**
+	 * Show customer name, username, email, phone, and billing address when permitted.
+	 * @default true
+	 */
+	showCustomer?: boolean;
+	/**
+	 * Show product, plan, payment method, and payment identifiers.
+	 * @default true
+	 */
+	showDetails?: boolean;
+	/**
+	 * Show the customer journey. Reads the account-scoped Events API only while visible.
+	 * @default true
+	 */
+	showJourney?: boolean;
+}
+
+/**
+ * The live handle for a mounted "paymentDetail" element. Returned by `create("paymentDetail")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/dashboard/paymentDetail
+ */
+export interface PaymentDetailElementHandle {
+	/**
+	 * Reload the payment and its fees after a host action completes.
+	 */
+	refresh: () => Promise<void>;
+	/**
+	 * 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<PaymentDetailElementProps>) => void;
+}
+
+/**
+ * Options for `create("paymentDetail")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const paymentDetail = dashboard.create("paymentDetail", {}); // this interface: props + on<Event> callbacks
+ * paymentDetail.mount("#dashboard-paymentDetail");
+ * ```
+ * @see https://docs.whop.com/elements/latest/dashboard/paymentDetail
+ */
+export interface PaymentDetailElementCreateOptions {
+	/**
+	 * Show the top-right Refund button and action menu. Mutating actions require event handlers.
+	 * @default true
+	 */
+	showActions?: boolean;
+	/**
+	 * The payment to display, prefixed pay_. Required to load a payment.
+	 * @default ""
+	 */
+	paymentId?: string;
+	/**
+	 * Show the payment amount, fees, and net amount.
+	 * @default true
+	 */
+	showBreakdown?: boolean;
+	/**
+	 * Show the payment activity timeline.
+	 * @default true
+	 */
+	showActivity?: boolean;
+	/**
+	 * Show customer name, username, email, phone, and billing address when permitted.
+	 * @default true
+	 */
+	showCustomer?: boolean;
+	/**
+	 * Show product, plan, payment method, and payment identifiers.
+	 * @default true
+	 */
+	showDetails?: boolean;
+	/**
+	 * Show the customer journey. Reads the account-scoped Events API only while visible.
+	 * @default true
+	 */
+	showJourney?: boolean;
+	/**
+	 * Confirm and authorize a refund in your application. Enabled only when refundable and a handler is provided.
+	 */
+	onRefundRequested?: ((payload: { paymentId: string; }) => void);
+	/**
+	 * Confirm and authorize another charge attempt in your application.
+	 */
+	onRetryRequested?: ((payload: { paymentId: string; }) => void);
+	/**
+	 * Confirm and authorize voiding this payment in your application.
+	 */
+	onVoidRequested?: ((payload: { paymentId: string; }) => void);
+	/**
+	 * View or download the invoice in your application.
+	 */
+	onInvoiceRequested?: ((payload: { paymentId: string; }) => void);
+	/**
+	 * Open the customer in your application.
+	 */
+	onCustomerSelected?: ((payload: { userId: string; memberId: string | null; }) => void);
+	/**
+	 * Open your customer messaging UI.
+	 */
+	onMessageRequested?: ((payload: { userId: 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 Dashboard handle, returned by `whop.dashboard.create()` (React: `useDashboard()`). Mounts the elements and carries the controller's actions.
+ * @see https://docs.whop.com/elements/latest/dashboard/overview
+ */
+export interface DashboardHandle {
+	/**
+	 * The dashboard payments table with status cards, search, filters, sorting, row selection, CSV export, column settings, and pagination. Reads all payment pages to compute complete counts and filter locally; intended for accounts with modest payment histories. Customer details and refunds are handed to your application through events.
+	 */
+	create(name: "paymentsTable", options?: PaymentsTableElementCreateOptions): PaymentsTableElementHandle;
+	/**
+	 * A payment detail page with the dashboard breakdown, activity, customer, details, and customer journey. Each section can be hidden. Reads payment:basic:read; customer email needs member:email:read and journey needs member:basic:read. Action events let your application confirm and authorize changes; this element never refunds, retries, or voids a payment itself.
+	 */
+	create(name: "paymentDetail", options?: PaymentDetailElementCreateOptions): PaymentDetailElementHandle;
+	/**
+	 * Merges new handle options into every mounted element. In React, change the namespace props instead.
+	 */
+	update(options: Partial<DashboardOptions>): 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;
+}
+
+/**
+ * Dashboard's static actions, callable with nothing mounted: `whop.dashboard.<method>()` (React: `useWhop().dashboard.<method>()`).
+ * @see https://docs.whop.com/elements/latest/dashboard/overview
+ */
+export interface DashboardStatics {}

package/index.d.cts

@@ -6,6 +6,7 @@ import type { AdsHandle, AdsOptions, AdsStatics } from "./ads.js";
 import type { TrackingHandle, TrackingOptions, TrackingStatics } from "./tracking.js";
 import type { WalletHandle, WalletOptions, WalletStatics } from "./wallet.js";
 import type { WebsitesHandle, WebsitesOptions, WebsitesStatics } from "./websites.js";
+import type { DashboardHandle, DashboardOptions, DashboardStatics } from "./dashboard.js";
 
 /** Global configuration for `WhopElements(config)`, inherited by every namespace handle (`appearance`, `locale`, …). */
 export interface WhopGlobalConfig extends FrameworkGlobals {}
@@ -13,7 +14,7 @@ export interface WhopGlobalConfig extends FrameworkGlobals {}
 /** The configured instance: one accessor per namespace, each carrying `create()` plus that namespace's static actions. */
 export interface Whop {
 	/**
-	 * Browse account payments with PaymentsElement, collect a payment from a `plan_` ID or inline currency and amount, or save a payment method without charging with `mode: "setup"`. Mount PaymentElement, CardElement, or CardFields, then call `payments.createConfirmationToken` with billing details. Wallet selections open their sheet automatically. Confirm the token server-side, then pass the payment's or setup intent's `client_secret` to `handleNextAction` for any pending step.
+	 * Collect a payment from a `plan_` ID or inline currency and amount, or save a payment method without charging with `mode: "setup"`. Mount PaymentElement, CardElement, or CardFields, then call `payments.createConfirmationToken` with billing details. Wallet selections open their sheet automatically. Confirm the token server-side, then pass the payment's or setup intent's `client_secret` to `handleNextAction` for any pending step.
 	 */
 	payments: { create(options: PaymentsOptions): PaymentsHandle } & PaymentsStatics;
 	/**
@@ -21,7 +22,7 @@ export interface Whop {
 	 */
 	verifications: { create(options: VerificationsOptions): VerificationsHandle } & VerificationsStatics;
 	/**
-	 * Drives a full hosted checkout for one plan — price summary, promo codes, the currency the buyer pays in, and the whole payment collection surface (the payments elements, composed inside) — against the Whop checkout sessions API. Mount it with a `plan` (or a `checkoutConfiguration` you authored) and the element opens the checkout session itself; the session credential never leaves the element. A setup-mode checkout configuration mounts the same element as a payment-method save: nothing is charged, the buyer’s method is stored for you to charge later, and the finished checkout redirects with `setup_intent_id`. The buyer pays inside the element, and a finished checkout redirects the current tab to `returnUrl`, including the page that contains the element. Fulfill from webhooks rather than a browser callback. Without a `returnUrl`, the buyer rests on the element’s own success face. The element automatically drives an off-site payment step, such as 3DS or a bank page. On whop.com, it brings the buyer back into the restored checkout; in an embed, the buyer returns to the same `returnUrl`. A failed payment reopens the same checkout with the reason shown, so the buyer can pay again. Every option is set at creation: the element mints a checkout session from these values when it mounts. Changing one later with `update()` or new React props fails instead of changing the existing order. Mount a new checkout to change the purchase.
+	 * Drives a full hosted checkout for one or more plans — itemized price summary, promo codes, the currency the buyer pays in, and the whole payment collection surface (the payments elements, composed inside) — against the Whop checkout sessions API. Mount it with `items`, a single `plan`, or a `checkoutConfiguration` you authored and the element opens the checkout session itself; the session credential never leaves the element. A setup-mode checkout configuration mounts the same element as a payment-method save: nothing is charged, the buyer’s method is stored for you to charge later, and the finished checkout redirects with `setup_intent_id`. The buyer pays inside the element, and a finished checkout redirects the current tab to `returnUrl`, including the page that contains the element. Fulfill from webhooks rather than a browser callback. Without a `returnUrl`, the buyer rests on the element’s own success face. The element automatically drives an off-site payment step, such as 3DS or a bank page. On whop.com, it brings the buyer back into the restored checkout; in an embed, the buyer returns to the same `returnUrl`. A failed payment reopens the same checkout with the reason shown, so the buyer can pay again. Every option is set at creation: the element mints a checkout session from these values when it mounts. Changing one later with `update()` or new React props fails instead of changing the existing order. Mount a new checkout to change what is being purchased.
 	 */
 	checkout: { create(options: CheckoutOptions): CheckoutHandle } & CheckoutStatics;
 	/**
@@ -40,6 +41,10 @@ export interface Whop {
 	 * An account's websites: every site built on whop.site plus every domain the Whop Pixel reports, with traffic and attributed revenue per domain. Mount `websites` and it lists them with visitors, page views, sales, revenue, trend, and most-viewed pages. Mount `pixel-setup` alongside it and a site whose pixel the wizard just proved live gets a waiting row automatically, because its first events take a few minutes to reach the stats API and the site would otherwise look lost — you wire nothing up for that, and the row is kept on your page so it is still there if the merchant reloads. Reading stats is privileged, so it needs an `accessToken` — except inside Whop's own app, where the viewer's session carries the read.
 	 */
 	websites: { create(options: WebsitesOptions): WebsitesHandle } & WebsitesStatics;
+	/**
+	 * An account's own payment records, embedded on your site. Scope it to an account with `accountId`, then mount `paymentsTable` for the account's payments and `paymentDetail` for one payment. Both read with the same credential, so two surfaces side by side always show the same account.
+	 */
+	dashboard: { create(options: DashboardOptions): DashboardHandle } & DashboardStatics;
 }
 
 /** The global `window.WhopElements`. Call it with the global config to get a `Whop` instance. */

package/index.d.ts

@@ -6,6 +6,7 @@ import type { AdsHandle, AdsOptions, AdsStatics } from "./ads.js";
 import type { TrackingHandle, TrackingOptions, TrackingStatics } from "./tracking.js";
 import type { WalletHandle, WalletOptions, WalletStatics } from "./wallet.js";
 import type { WebsitesHandle, WebsitesOptions, WebsitesStatics } from "./websites.js";
+import type { DashboardHandle, DashboardOptions, DashboardStatics } from "./dashboard.js";
 
 /** Global configuration for `WhopElements(config)`, inherited by every namespace handle (`appearance`, `locale`, …). */
 export interface WhopGlobalConfig extends FrameworkGlobals {}
@@ -13,7 +14,7 @@ export interface WhopGlobalConfig extends FrameworkGlobals {}
 /** The configured instance: one accessor per namespace, each carrying `create()` plus that namespace's static actions. */
 export interface Whop {
 	/**
-	 * Browse account payments with PaymentsElement, collect a payment from a `plan_` ID or inline currency and amount, or save a payment method without charging with `mode: "setup"`. Mount PaymentElement, CardElement, or CardFields, then call `payments.createConfirmationToken` with billing details. Wallet selections open their sheet automatically. Confirm the token server-side, then pass the payment's or setup intent's `client_secret` to `handleNextAction` for any pending step.
+	 * Collect a payment from a `plan_` ID or inline currency and amount, or save a payment method without charging with `mode: "setup"`. Mount PaymentElement, CardElement, or CardFields, then call `payments.createConfirmationToken` with billing details. Wallet selections open their sheet automatically. Confirm the token server-side, then pass the payment's or setup intent's `client_secret` to `handleNextAction` for any pending step.
 	 */
 	payments: { create(options: PaymentsOptions): PaymentsHandle } & PaymentsStatics;
 	/**
@@ -21,7 +22,7 @@ export interface Whop {
 	 */
 	verifications: { create(options: VerificationsOptions): VerificationsHandle } & VerificationsStatics;
 	/**
-	 * Drives a full hosted checkout for one plan — price summary, promo codes, the currency the buyer pays in, and the whole payment collection surface (the payments elements, composed inside) — against the Whop checkout sessions API. Mount it with a `plan` (or a `checkoutConfiguration` you authored) and the element opens the checkout session itself; the session credential never leaves the element. A setup-mode checkout configuration mounts the same element as a payment-method save: nothing is charged, the buyer’s method is stored for you to charge later, and the finished checkout redirects with `setup_intent_id`. The buyer pays inside the element, and a finished checkout redirects the current tab to `returnUrl`, including the page that contains the element. Fulfill from webhooks rather than a browser callback. Without a `returnUrl`, the buyer rests on the element’s own success face. The element automatically drives an off-site payment step, such as 3DS or a bank page. On whop.com, it brings the buyer back into the restored checkout; in an embed, the buyer returns to the same `returnUrl`. A failed payment reopens the same checkout with the reason shown, so the buyer can pay again. Every option is set at creation: the element mints a checkout session from these values when it mounts. Changing one later with `update()` or new React props fails instead of changing the existing order. Mount a new checkout to change the purchase.
+	 * Drives a full hosted checkout for one or more plans — itemized price summary, promo codes, the currency the buyer pays in, and the whole payment collection surface (the payments elements, composed inside) — against the Whop checkout sessions API. Mount it with `items`, a single `plan`, or a `checkoutConfiguration` you authored and the element opens the checkout session itself; the session credential never leaves the element. A setup-mode checkout configuration mounts the same element as a payment-method save: nothing is charged, the buyer’s method is stored for you to charge later, and the finished checkout redirects with `setup_intent_id`. The buyer pays inside the element, and a finished checkout redirects the current tab to `returnUrl`, including the page that contains the element. Fulfill from webhooks rather than a browser callback. Without a `returnUrl`, the buyer rests on the element’s own success face. The element automatically drives an off-site payment step, such as 3DS or a bank page. On whop.com, it brings the buyer back into the restored checkout; in an embed, the buyer returns to the same `returnUrl`. A failed payment reopens the same checkout with the reason shown, so the buyer can pay again. Every option is set at creation: the element mints a checkout session from these values when it mounts. Changing one later with `update()` or new React props fails instead of changing the existing order. Mount a new checkout to change what is being purchased.
 	 */
 	checkout: { create(options: CheckoutOptions): CheckoutHandle } & CheckoutStatics;
 	/**
@@ -40,6 +41,10 @@ export interface Whop {
 	 * An account's websites: every site built on whop.site plus every domain the Whop Pixel reports, with traffic and attributed revenue per domain. Mount `websites` and it lists them with visitors, page views, sales, revenue, trend, and most-viewed pages. Mount `pixel-setup` alongside it and a site whose pixel the wizard just proved live gets a waiting row automatically, because its first events take a few minutes to reach the stats API and the site would otherwise look lost — you wire nothing up for that, and the row is kept on your page so it is still there if the merchant reloads. Reading stats is privileged, so it needs an `accessToken` — except inside Whop's own app, where the viewer's session carries the read.
 	 */
 	websites: { create(options: WebsitesOptions): WebsitesHandle } & WebsitesStatics;
+	/**
+	 * An account's own payment records, embedded on your site. Scope it to an account with `accountId`, then mount `paymentsTable` for the account's payments and `paymentDetail` for one payment. Both read with the same credential, so two surfaces side by side always show the same account.
+	 */
+	dashboard: { create(options: DashboardOptions): DashboardHandle } & DashboardStatics;
 }
 
 /** The global `window.WhopElements`. Call it with the global config to get a `Whop` instance. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@whop/elements",
-	"version": "1.0.0-beta.4",
+	"version": "1.0.0-beta.5",
 	"description": "Whop Elements — vanilla-js loader + types. Loads the hosted SDK and exposes the typed WhopElements factory.",
 	"keywords": [
 		"checkout",
@@ -87,7 +87,15 @@
 			"require": {
 				"types": "./websites.d.cts"
 			}
+		},
+		"./dashboard": {
+			"import": {
+				"types": "./dashboard.d.ts"
+			},
+			"require": {
+				"types": "./dashboard.d.cts"
+			}
 		}
 	},
-	"whopElementsApiHash": "643973a360d415d99bd6cf95211709b03ca2dc4b79002d7cd3539f367cd4ca71"
+	"whopElementsApiHash": "b06bb1fdc85f1e9ccbd1186c186a6a1b106a8f59293e7ee7a7f6275f81ba3cd0"
 }