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

package/dashboard.d.cts

@@ -0,0 +1,490 @@
+/**
+ * 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`. The banners need `payout:account:read`, and starting verification from the action bar `identity:write`. Omitted, the reads carry the viewer's own session, which only answers same-origin.
+	 */
+	accessToken?: string;
+	/**
+	 * Account or user ID whose records these surfaces read. Account IDs are prefixed `biz_`; user IDs are prefixed `user_`, can read only the viewer's own outstanding actions, and have no payments.
+	 */
+	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 "required-actions" element. Set at create (or as `<RequiredActionsElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/dashboard/required-actions
+ */
+export interface RequiredActionsElementProps {
+	/**
+	 * Which verification the Verify button starts. `individual` (KYC) is what unlocks payouts and a Whop card. `business` (KYB) covers that and additionally unlocks financing and business cards — use it for a company that will need those.
+	 * @default "individual"
+	 */
+	kind?: "individual" | "business";
+}
+
+/**
+ * The live handle for a mounted "required-actions" element. Returned by `create("required-actions")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/dashboard/required-actions
+ */
+export interface RequiredActionsElementHandle {
+	/**
+	 * Re-read the account. Call it when the viewer returns from verifying or depositing so the banners reflect the new state without waiting for the cache to expire.
+	 */
+	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<RequiredActionsElementProps>) => void;
+}
+
+/**
+ * Options for `create("required-actions")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const required_actions = dashboard.create("required-actions", {}); // this interface: props + on<Event> callbacks
+ * required_actions.mount("#dashboard-required-actions");
+ * ```
+ * @see https://docs.whop.com/elements/latest/dashboard/required-actions
+ */
+export interface RequiredActionsElementCreateOptions {
+	/**
+	 * Which verification the Verify button starts. `individual` (KYC) is what unlocks payouts and a Whop card. `business` (KYB) covers that and additionally unlocks financing and business cards — use it for a company that will need those.
+	 * @default "individual"
+	 */
+	kind?: "individual" | "business";
+	/**
+	 * The viewer pressed a banner button. Fires for every action, including ones the element also handles itself.
+	 */
+	onActionRequested?: ((payload: { action: "deposit_funds" | "review_held_payments" | "accept_airwallex_terms" | "submit_information_request" | "update_automatic_withdrawal_method" | "reauthorize_payout_methods" | "update_payout_profile" | "card_usage_review" | "verify_identity" | "verify_airwallex_account" | "sign_formation_documents" | "connect_fulfillment_tracker" | "setup_apple_pay_domains" | "configure_tax_remitter" | "add_vat_registration" | "enable_two_factor_authentication"; accountId: string; }) => void);
+	/**
+	 * The viewer pressed Verify on a `verify_identity` action the element can start. The element opens identity verification itself — this fires alongside, so a host can record the trip.
+	 */
+	onIdentityVerificationRequested?: ((payload: { accountId: string; }) => void);
+	/**
+	 * The viewer pressed Add money. The element never opens a deposit flow itself — mount your own, such as the `wallet` controller’s `deposit` element, in answer to this.
+	 */
+	onDepositRequested?: ((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 "verification" element. Set at create (or as `<VerificationElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/dashboard/verification
+ */
+export interface VerificationElementProps {
+	/**
+	 * Which verification the button starts. `individual` (KYC) is what unlocks payouts and a Whop card. `business` (KYB) covers that and additionally unlocks financing and business cards — use it for a company that will need those.
+	 * @default "individual"
+	 */
+	kind?: "individual" | "business";
+	/**
+	 * Show a compact inline prompt without the supporting description.
+	 * @default false
+	 */
+	compact?: boolean;
+}
+
+/**
+ * The live handle for a mounted "verification" element. Returned by `create("verification")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/dashboard/verification
+ */
+export interface VerificationElementHandle {
+	/**
+	 * Re-read the account. Call it when the viewer returns from verifying so the banner reflects the new state without waiting for the cache to expire.
+	 */
+	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<VerificationElementProps>) => void;
+}
+
+/**
+ * Options for `create("verification")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const verification = dashboard.create("verification", {}); // this interface: props + on<Event> callbacks
+ * verification.mount("#dashboard-verification");
+ * ```
+ * @see https://docs.whop.com/elements/latest/dashboard/verification
+ */
+export interface VerificationElementCreateOptions {
+	/**
+	 * Which verification the button starts. `individual` (KYC) is what unlocks payouts and a Whop card. `business` (KYB) covers that and additionally unlocks financing and business cards — use it for a company that will need those.
+	 * @default "individual"
+	 */
+	kind?: "individual" | "business";
+	/**
+	 * Show a compact inline prompt without the supporting description.
+	 * @default false
+	 */
+	compact?: boolean;
+	/**
+	 * The viewer pressed the verify button. The element never navigates — mount your own verification, such as the `verifications` controller, in answer to this.
+	 */
+	onVerificationRequested?: ((payload: { accountId: 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 "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 outstanding-action banners from Whop's balance dashboard — identity verification, deposits, tax, and the rest — in the same order the API returns them. An account with nothing outstanding renders nothing at all, so the element can sit permanently in a layout. Copy comes from the API. Pressing Verify starts a hosted identity session and leaves for it; Add money reports `depositRequested` and stays put, so the host mounts its own deposit flow — the `wallet` controller's `deposit` element, say; every other button follows the action's own link. Reads with the Dashboard handle's `accessToken`, which needs `payout:account:read`, plus `identity:write` to start verification. A failed read renders nothing rather than an error — a banner should never become the loudest thing on someone else's page.
+	 */
+	create(name: "required-actions", options?: RequiredActionsElementCreateOptions): RequiredActionsElementHandle;
+	/**
+	 * A banner asking the account holder to verify their identity, shown only while verification is outstanding — an account that has already verified renders nothing at all, so the element can sit permanently in a layout. The headline and status messages come from the API, with a shorter description when inviting the account holder to start verification, so they track the account's actual state: an unstarted account is invited to unlock cards and payouts, one under review reads as pending, and a failed or flagged one says so. Pressing the button reports `verificationRequested` and stays put, so the host mounts its own verification — the `verifications` controller's `kyc` element, say. Reads with the Dashboard handle's `accessToken`, which needs `payout:account:read`. A failed read renders nothing rather than an error — a nudge should never become the loudest thing on the page.
+	 */
+	create(name: "verification", options?: VerificationElementCreateOptions): VerificationElementHandle;
+	/**
+	 * 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 {}