@whop/elements 0.0.0 → 1.0.0-beta.0

package/checkout.d.cts

@@ -0,0 +1,139 @@
+/**
+ * Options for `whop.checkout.create()`: the controller's props plus its `on<Event>` callbacks. In React, these are the `<Checkout>` component's props.
+ * @example
+ * ```ts
+ * import { loadWhop } from "@whop/elements";
+ * 
+ * const whop = (await loadWhop())({ locale: "en" });
+ * const checkout = whop.checkout.create({}); // options: props + on<Event> callbacks
+ * ```
+ * @see https://docs.whop.com/elements/latest/checkout/overview
+ */
+export interface CheckoutOptions {
+	/**
+	 * Existing plan ID, prefixed `plan_`. The element creates a checkout session for it, and the plan defines the price; nothing about amounts can be asserted client-side. Every checkout names one — omitting it refuses loudly at mount. Set at create only: the session is minted from it, and changing it later refuses.
+	 */
+	plan?: string;
+	/**
+	 * How many units to purchase. Plans that disallow multiples refuse values above 1. Set at create only: the session is minted with it, and changing it later refuses. @default 1
+	 */
+	quantity?: number;
+	/**
+	 * A promo code to apply before the buyer ever sees the price — the discount is on the first quote, and the buyer can still change or remove it. Pass the code a marketing link carried: a code that has expired or was never valid opens the checkout at full price with the reason on the promo row, never a checkout that will not open. Set at create only.
+	 */
+	promoCode?: string;
+	/**
+	 * The affiliate this checkout is attributed to. Set at create only.
+	 */
+	affiliateCode?: string;
+	/**
+	 * Where this sale came from, for the account's reporting: the campaign parameters of the link the buyer arrived on (`utmSource`, `utmMedium`, `utmCampaign`, `utmTerm`, `utmContent`, a Whop `trackingLinkId`, a `funnelId`, and your own `source`). Everything here is recorded against the order and is never shown to the buyer. Set at create only.
+	 */
+	attribution?: CheckoutAttributionInput;
+	/**
+	 * Your own key/value pairs to record against the order and read back on the payment — order IDs, cart IDs, or anything you reconcile against. Up to 40 string pairs. Set at create only.
+	 */
+	metadata?: Record<string, string>;
+	/**
+	 * Where the buyer lands after an off-site payment step. Https-only (http for localhost). Set at create only.
+	 */
+	returnUrl?: 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 "checkout" element. Set at create (or as `<CheckoutElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/checkout/checkout
+ */
+export interface CheckoutElementProps {}
+
+/**
+ * The live handle for a mounted "checkout" element. Returned by `create("checkout")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/checkout/checkout
+ */
+export interface CheckoutElementHandle {
+	/**
+	 * 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<CheckoutElementProps>) => void;
+}
+
+/**
+ * Options for `create("checkout")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const checkout = checkout.create("checkout", {}); // this interface: props + on<Event> callbacks
+ * checkout.mount("#checkout-checkout");
+ * ```
+ * @see https://docs.whop.com/elements/latest/checkout/checkout
+ */
+export interface CheckoutElementCreateOptions {
+	/**
+	 * 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 Checkout handle, returned by `whop.checkout.create()` (React: `useCheckout()`). Mounts the elements and carries the controller's actions.
+ * @see https://docs.whop.com/elements/latest/checkout/overview
+ */
+export interface CheckoutHandle {
+	/**
+	 * The full checkout surface — order summary with the live quote, promo code entry, the currency the buyer pays in, everything this checkout has to collect from the buyer, the composed payment methods surface, and the pay flow. What it collects is whatever the account owner set up (email, their own questions, a phone number, a shipping address for physical goods, an explicit agreement to their terms), rendered together on one screen in the order they chose — so an account owner who starts asking for something new needs no change here. Renders the whole purchase; the checkout controller owns the session and the credential. After a payment that needs an off-site step, this same surface renders the outcome the server reports when the buyer comes back.
+	 * Exclusive slot `entry`. Mount exactly one of: checkout.
+	 */
+	create(name: "checkout", options?: CheckoutElementCreateOptions): CheckoutElementHandle;
+	/**
+	 * Merges new handle options into every mounted element. In React, change the namespace props instead.
+	 */
+	update(options: Partial<CheckoutOptions>): void;
+}
+
+/**
+ * Checkout's static actions, callable with nothing mounted: `whop.checkout.<method>()` (React: `useWhop().checkout.<method>()`).
+ * @see https://docs.whop.com/elements/latest/checkout/overview
+ */
+export interface CheckoutStatics {}
+
+/**
+ * Checkout attribution recorded with the session. The element maps these fields to `POST /api/v1/checkout_sessions`; empty values are omitted, and `country` is resolved by the API.
+ * Declared from the app's `CheckoutAttributionInput`, referenced by a host-capability surface.
+ */
+export interface CheckoutAttributionInput {
+	utmSource?: string | undefined;
+	utmMedium?: string | undefined;
+	utmCampaign?: string | undefined;
+	utmTerm?: string | undefined;
+	utmContent?: string | undefined;
+	trackingLinkId?: string | undefined;
+	funnelId?: string | undefined;
+	source?: string | undefined;
+}

package/checkout.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Options for `whop.checkout.create()`: the controller's props plus its `on<Event>` callbacks. In React, these are the `<Checkout>` component's props.
+ * @example
+ * ```ts
+ * import { loadWhop } from "@whop/elements";
+ * 
+ * const whop = (await loadWhop())({ locale: "en" });
+ * const checkout = whop.checkout.create({}); // options: props + on<Event> callbacks
+ * ```
+ * @see https://docs.whop.com/elements/latest/checkout/overview
+ */
+export interface CheckoutOptions {
+	/**
+	 * Existing plan ID, prefixed `plan_`. The element creates a checkout session for it, and the plan defines the price; nothing about amounts can be asserted client-side. Every checkout names one — omitting it refuses loudly at mount. Set at create only: the session is minted from it, and changing it later refuses.
+	 */
+	plan?: string;
+	/**
+	 * How many units to purchase. Plans that disallow multiples refuse values above 1. Set at create only: the session is minted with it, and changing it later refuses. @default 1
+	 */
+	quantity?: number;
+	/**
+	 * A promo code to apply before the buyer ever sees the price — the discount is on the first quote, and the buyer can still change or remove it. Pass the code a marketing link carried: a code that has expired or was never valid opens the checkout at full price with the reason on the promo row, never a checkout that will not open. Set at create only.
+	 */
+	promoCode?: string;
+	/**
+	 * The affiliate this checkout is attributed to. Set at create only.
+	 */
+	affiliateCode?: string;
+	/**
+	 * Where this sale came from, for the account's reporting: the campaign parameters of the link the buyer arrived on (`utmSource`, `utmMedium`, `utmCampaign`, `utmTerm`, `utmContent`, a Whop `trackingLinkId`, a `funnelId`, and your own `source`). Everything here is recorded against the order and is never shown to the buyer. Set at create only.
+	 */
+	attribution?: CheckoutAttributionInput;
+	/**
+	 * Your own key/value pairs to record against the order and read back on the payment — order IDs, cart IDs, or anything you reconcile against. Up to 40 string pairs. Set at create only.
+	 */
+	metadata?: Record<string, string>;
+	/**
+	 * Where the buyer lands after an off-site payment step. Https-only (http for localhost). Set at create only.
+	 */
+	returnUrl?: 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 "checkout" element. Set at create (or as `<CheckoutElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/checkout/checkout
+ */
+export interface CheckoutElementProps {}
+
+/**
+ * The live handle for a mounted "checkout" element. Returned by `create("checkout")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/checkout/checkout
+ */
+export interface CheckoutElementHandle {
+	/**
+	 * 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<CheckoutElementProps>) => void;
+}
+
+/**
+ * Options for `create("checkout")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const checkout = checkout.create("checkout", {}); // this interface: props + on<Event> callbacks
+ * checkout.mount("#checkout-checkout");
+ * ```
+ * @see https://docs.whop.com/elements/latest/checkout/checkout
+ */
+export interface CheckoutElementCreateOptions {
+	/**
+	 * 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 Checkout handle, returned by `whop.checkout.create()` (React: `useCheckout()`). Mounts the elements and carries the controller's actions.
+ * @see https://docs.whop.com/elements/latest/checkout/overview
+ */
+export interface CheckoutHandle {
+	/**
+	 * The full checkout surface — order summary with the live quote, promo code entry, the currency the buyer pays in, everything this checkout has to collect from the buyer, the composed payment methods surface, and the pay flow. What it collects is whatever the account owner set up (email, their own questions, a phone number, a shipping address for physical goods, an explicit agreement to their terms), rendered together on one screen in the order they chose — so an account owner who starts asking for something new needs no change here. Renders the whole purchase; the checkout controller owns the session and the credential. After a payment that needs an off-site step, this same surface renders the outcome the server reports when the buyer comes back.
+	 * Exclusive slot `entry`. Mount exactly one of: checkout.
+	 */
+	create(name: "checkout", options?: CheckoutElementCreateOptions): CheckoutElementHandle;
+	/**
+	 * Merges new handle options into every mounted element. In React, change the namespace props instead.
+	 */
+	update(options: Partial<CheckoutOptions>): void;
+}
+
+/**
+ * Checkout's static actions, callable with nothing mounted: `whop.checkout.<method>()` (React: `useWhop().checkout.<method>()`).
+ * @see https://docs.whop.com/elements/latest/checkout/overview
+ */
+export interface CheckoutStatics {}
+
+/**
+ * Checkout attribution recorded with the session. The element maps these fields to `POST /api/v1/checkout_sessions`; empty values are omitted, and `country` is resolved by the API.
+ * Declared from the app's `CheckoutAttributionInput`, referenced by a host-capability surface.
+ */
+export interface CheckoutAttributionInput {
+	utmSource?: string | undefined;
+	utmMedium?: string | undefined;
+	utmCampaign?: string | undefined;
+	utmTerm?: string | undefined;
+	utmContent?: string | undefined;
+	trackingLinkId?: string | undefined;
+	funnelId?: string | undefined;
+	source?: string | undefined;
+}

package/index.cjs

@@ -0,0 +1,86 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// ../../packages/elements-codegen/src/cli/build/npm-loader.ts
+var npm_loader_exports = {};
+__export(npm_loader_exports, {
+  SDK_URL: () => SDK_URL,
+  WHOP_ELEMENTS_LOCALES: () => WHOP_ELEMENTS_LOCALES,
+  loadWhop: () => loadWhop,
+  preloadHints: () => preloadHints
+});
+module.exports = __toCommonJS(npm_loader_exports);
+
+// <define:__WHOP_ELEMENTS_LOCALES__>
+var define_WHOP_ELEMENTS_LOCALES_default = ["en", "es", "zh", "nl", "pt", "de", "it", "fr", "ja", "pl", "tr"];
+
+// ../../packages/elements-codegen/src/cli/build/npm-loader.ts
+var ORIGIN = "https://js.whop.cloud";
+var SDK_URL = "https://js.whop.cloud/elements/amber/elements.js";
+var WHOP_ELEMENTS_LOCALES = define_WHOP_ELEMENTS_LOCALES_default;
+function loadWhop() {
+  if (typeof window === "undefined") return Promise.reject(new Error("WhopElements requires a browser environment"));
+  const w = window;
+  if (w.WhopElements) return Promise.resolve(w.WhopElements);
+  let s = document.querySelector("script[data-whop-elements]");
+  const created = !s;
+  if (!s) {
+    s = document.createElement("script");
+    s.src = SDK_URL;
+    s.async = true;
+    s.setAttribute("data-whop-elements", "");
+    document.head.appendChild(s);
+  }
+  const script = s;
+  if (!script.__whopReady) {
+    script.__whopReady = new Promise((resolve, reject) => {
+      let timer = null;
+      function settle(fn, v) {
+        if (timer !== null) {
+          clearInterval(timer);
+          timer = null;
+        }
+        fn(v);
+      }
+      script.addEventListener("load", () => {
+        if (w.WhopElements) settle(resolve, w.WhopElements);
+        else settle(reject, new Error("WhopElements loaded but did not initialize"));
+      });
+      script.addEventListener("error", () => settle(reject, new Error("Failed to load " + SDK_URL)));
+      if (!created) {
+        let waited = 0;
+        timer = setInterval(() => {
+          if (w.WhopElements) {
+            settle(resolve, w.WhopElements);
+            return;
+          }
+          waited += 200;
+          if (waited >= 1e4) settle(reject, new Error("existing data-whop-elements script did not initialize within 10s \u2014 if its network load already failed before loadWhop() ran (check the console/CSP), no load/error event will ever fire on it"));
+        }, 200);
+      }
+    });
+  }
+  return script.__whopReady;
+}
+function preloadHints() {
+  return [
+    { rel: "preconnect", href: ORIGIN },
+    { rel: "preload", href: SDK_URL, as: "script" }
+  ];
+}

package/index.d.cts

@@ -0,0 +1,61 @@
+import type { FrameworkGlobals, WhopElementsLocale } from "./_framework.js";
+import type { PaymentsHandle, PaymentsOptions, PaymentsStatics } from "./payments.js";
+import type { CheckoutHandle, CheckoutOptions, CheckoutStatics } from "./checkout.js";
+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";
+
+/** Global configuration for `WhopElements(config)`, inherited by every namespace handle (`appearance`, `locale`, …). */
+export interface WhopGlobalConfig extends FrameworkGlobals {}
+
+/** The configured instance: one accessor per namespace, each carrying `create()` plus that namespace's static actions. */
+export interface Whop {
+	/**
+	 * Collect a payment from a `plan_` ID or inline currency and amount. 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 `client_secret` to `handleNextAction` for any pending step.
+	 */
+	payments: { create(options: PaymentsOptions): PaymentsHandle } & PaymentsStatics;
+	/**
+	 * 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` and the element opens the checkout session itself; the session credential never leaves the element. 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.
+	 */
+	checkout: { create(options: CheckoutOptions): CheckoutHandle } & CheckoutStatics;
+	/**
+	 * An advertising account. Scope it to a Whop account with `accountId` — the ad account underneath is assigned server-side and never surfaces here — then mount `reporting` for what the account spent and what came back, or `campaign-creator` to build a campaign.
+	 */
+	ads: { create(options: AdsOptions): AdsHandle } & AdsStatics;
+	/**
+	 * An account's tracked audience: everyone its pixel has seen, and every event they performed. Scope it to an account with `accountId`, then mount `people`, `events`, or both — they read the same window and the same credit rule, so two surfaces side by side can never disagree about what they are showing. `links` wires their person links to your own pages.
+	 */
+	tracking: { create(options: TrackingOptions): TrackingHandle } & TrackingStatics;
+	/**
+	 * Drives an account's money surfaces. `deposit` returns live funding rails; `send` moves money to a recipient or creates a public claim link; `withdraw` collects a payout request; `balances` holds two faces — the holdings list, and the balance block drawing value over a window; `cards` lists issued cards; and `activity` lists ledger movements. Every surface but `deposit` can use the viewer's session when no token is provided.
+	 */
+	wallet: { create(options: WalletOptions): WalletHandle } & WalletStatics;
+	/**
+	 * An account's websites: every site built on whop.app 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;
+}
+
+/** The global `window.WhopElements`. Call it with the global config to get a `Whop` instance. */
+export interface WhopConstructor {
+	(config?: WhopGlobalConfig): Whop;
+}
+
+/** The hosted SDK bundle `loadWhop()` loads. The URL carries the release train, so it follows this package's major. */
+export declare const SDK_URL: string;
+
+/** Load the hosted SDK: injects the `<script data-whop-elements>` tag once and resolves the global constructor. Safe to call any number of times: one script, one shared promise. */
+export declare function loadWhop(): Promise<WhopConstructor>;
+
+/** Resource hints (preconnect/preload) for the hosted SDK. Render them into `<head>` to start the fetch before `loadWhop()` runs. */
+export declare function preloadHints(): { rel: string; href: string; as?: string }[];
+
+/** The locales this app's elements are built with, the default locale first: exactly the values `locale` accepts. `includes()` accepts any string and narrows it to `WhopElementsLocale`, so use it to validate dynamic values; anything unlisted falls back to the default locale. */
+export declare const WHOP_ELEMENTS_LOCALES: readonly WhopElementsLocale[] & {
+	includes(value: string, fromIndex?: number): value is WhopElementsLocale;
+};
+
+export type { WhopElementsLocale };
+
+export type { Appearance, Theme, AccentColor, Classes, Variables, CSSProps, CSSValue, FrameworkGlobals } from "./_framework.js";

package/index.d.ts

@@ -0,0 +1,61 @@
+import type { FrameworkGlobals, WhopElementsLocale } from "./_framework.js";
+import type { PaymentsHandle, PaymentsOptions, PaymentsStatics } from "./payments.js";
+import type { CheckoutHandle, CheckoutOptions, CheckoutStatics } from "./checkout.js";
+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";
+
+/** Global configuration for `WhopElements(config)`, inherited by every namespace handle (`appearance`, `locale`, …). */
+export interface WhopGlobalConfig extends FrameworkGlobals {}
+
+/** The configured instance: one accessor per namespace, each carrying `create()` plus that namespace's static actions. */
+export interface Whop {
+	/**
+	 * Collect a payment from a `plan_` ID or inline currency and amount. 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 `client_secret` to `handleNextAction` for any pending step.
+	 */
+	payments: { create(options: PaymentsOptions): PaymentsHandle } & PaymentsStatics;
+	/**
+	 * 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` and the element opens the checkout session itself; the session credential never leaves the element. 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.
+	 */
+	checkout: { create(options: CheckoutOptions): CheckoutHandle } & CheckoutStatics;
+	/**
+	 * An advertising account. Scope it to a Whop account with `accountId` — the ad account underneath is assigned server-side and never surfaces here — then mount `reporting` for what the account spent and what came back, or `campaign-creator` to build a campaign.
+	 */
+	ads: { create(options: AdsOptions): AdsHandle } & AdsStatics;
+	/**
+	 * An account's tracked audience: everyone its pixel has seen, and every event they performed. Scope it to an account with `accountId`, then mount `people`, `events`, or both — they read the same window and the same credit rule, so two surfaces side by side can never disagree about what they are showing. `links` wires their person links to your own pages.
+	 */
+	tracking: { create(options: TrackingOptions): TrackingHandle } & TrackingStatics;
+	/**
+	 * Drives an account's money surfaces. `deposit` returns live funding rails; `send` moves money to a recipient or creates a public claim link; `withdraw` collects a payout request; `balances` holds two faces — the holdings list, and the balance block drawing value over a window; `cards` lists issued cards; and `activity` lists ledger movements. Every surface but `deposit` can use the viewer's session when no token is provided.
+	 */
+	wallet: { create(options: WalletOptions): WalletHandle } & WalletStatics;
+	/**
+	 * An account's websites: every site built on whop.app 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;
+}
+
+/** The global `window.WhopElements`. Call it with the global config to get a `Whop` instance. */
+export interface WhopConstructor {
+	(config?: WhopGlobalConfig): Whop;
+}
+
+/** The hosted SDK bundle `loadWhop()` loads. The URL carries the release train, so it follows this package's major. */
+export declare const SDK_URL: string;
+
+/** Load the hosted SDK: injects the `<script data-whop-elements>` tag once and resolves the global constructor. Safe to call any number of times: one script, one shared promise. */
+export declare function loadWhop(): Promise<WhopConstructor>;
+
+/** Resource hints (preconnect/preload) for the hosted SDK. Render them into `<head>` to start the fetch before `loadWhop()` runs. */
+export declare function preloadHints(): { rel: string; href: string; as?: string }[];
+
+/** The locales this app's elements are built with, the default locale first: exactly the values `locale` accepts. `includes()` accepts any string and narrows it to `WhopElementsLocale`, so use it to validate dynamic values; anything unlisted falls back to the default locale. */
+export declare const WHOP_ELEMENTS_LOCALES: readonly WhopElementsLocale[] & {
+	includes(value: string, fromIndex?: number): value is WhopElementsLocale;
+};
+
+export type { WhopElementsLocale };
+
+export type { Appearance, Theme, AccentColor, Classes, Variables, CSSProps, CSSValue, FrameworkGlobals } from "./_framework.js";

package/index.js

@@ -0,0 +1,63 @@
+// <define:__WHOP_ELEMENTS_LOCALES__>
+var define_WHOP_ELEMENTS_LOCALES_default = ["en", "es", "zh", "nl", "pt", "de", "it", "fr", "ja", "pl", "tr"];
+
+// ../../packages/elements-codegen/src/cli/build/npm-loader.ts
+var ORIGIN = "https://js.whop.cloud";
+var SDK_URL = "https://js.whop.cloud/elements/amber/elements.js";
+var WHOP_ELEMENTS_LOCALES = define_WHOP_ELEMENTS_LOCALES_default;
+function loadWhop() {
+  if (typeof window === "undefined") return Promise.reject(new Error("WhopElements requires a browser environment"));
+  const w = window;
+  if (w.WhopElements) return Promise.resolve(w.WhopElements);
+  let s = document.querySelector("script[data-whop-elements]");
+  const created = !s;
+  if (!s) {
+    s = document.createElement("script");
+    s.src = SDK_URL;
+    s.async = true;
+    s.setAttribute("data-whop-elements", "");
+    document.head.appendChild(s);
+  }
+  const script = s;
+  if (!script.__whopReady) {
+    script.__whopReady = new Promise((resolve, reject) => {
+      let timer = null;
+      function settle(fn, v) {
+        if (timer !== null) {
+          clearInterval(timer);
+          timer = null;
+        }
+        fn(v);
+      }
+      script.addEventListener("load", () => {
+        if (w.WhopElements) settle(resolve, w.WhopElements);
+        else settle(reject, new Error("WhopElements loaded but did not initialize"));
+      });
+      script.addEventListener("error", () => settle(reject, new Error("Failed to load " + SDK_URL)));
+      if (!created) {
+        let waited = 0;
+        timer = setInterval(() => {
+          if (w.WhopElements) {
+            settle(resolve, w.WhopElements);
+            return;
+          }
+          waited += 200;
+          if (waited >= 1e4) settle(reject, new Error("existing data-whop-elements script did not initialize within 10s \u2014 if its network load already failed before loadWhop() ran (check the console/CSP), no load/error event will ever fire on it"));
+        }, 200);
+      }
+    });
+  }
+  return script.__whopReady;
+}
+function preloadHints() {
+  return [
+    { rel: "preconnect", href: ORIGIN },
+    { rel: "preload", href: SDK_URL, as: "script" }
+  ];
+}
+export {
+  SDK_URL,
+  WHOP_ELEMENTS_LOCALES,
+  loadWhop,
+  preloadHints
+};

package/package.json

@@ -1,10 +1,85 @@
 {
 	"name": "@whop/elements",
-	"version": "0.0.0",
+	"version": "1.0.0-beta.0",
 	"description": "Whop Elements — vanilla-js loader + types. Loads the hosted SDK and exposes the typed WhopElements factory.",
+	"keywords": [
+		"checkout",
+		"elements",
+		"embed",
+		"payments",
+		"whop"
+	],
+	"homepage": "https://docs.whop.com/elements/latest",
+	"bugs": "https://github.com/whopio/elements/issues",
 	"license": "MIT",
-	"publishConfig": {
-		"access": "public",
-		"tag": "stub"
-	}
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/whopio/elements.git"
+	},
+	"type": "module",
+	"sideEffects": false,
+	"main": "./index.cjs",
+	"module": "./index.js",
+	"types": "./index.d.ts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./index.d.ts",
+				"default": "./index.js"
+			},
+			"require": {
+				"types": "./index.d.cts",
+				"default": "./index.cjs"
+			}
+		},
+		"./payments": {
+			"import": {
+				"types": "./payments.d.ts"
+			},
+			"require": {
+				"types": "./payments.d.cts"
+			}
+		},
+		"./checkout": {
+			"import": {
+				"types": "./checkout.d.ts"
+			},
+			"require": {
+				"types": "./checkout.d.cts"
+			}
+		},
+		"./ads": {
+			"import": {
+				"types": "./ads.d.ts"
+			},
+			"require": {
+				"types": "./ads.d.cts"
+			}
+		},
+		"./tracking": {
+			"import": {
+				"types": "./tracking.d.ts"
+			},
+			"require": {
+				"types": "./tracking.d.cts"
+			}
+		},
+		"./wallet": {
+			"import": {
+				"types": "./wallet.d.ts"
+			},
+			"require": {
+				"types": "./wallet.d.cts"
+			}
+		},
+		"./websites": {
+			"import": {
+				"types": "./websites.d.ts"
+			},
+			"require": {
+				"types": "./websites.d.cts"
+			}
+		}
+	},
+	"whopElementsApiHash": "6f00c3f1ef717575e3e56a392ace6dafc99c13d33b1dea86f12206ccdd4496a6"
 }