@whop/elements 1.3.0 → 1.5.0

package/payments.d.ts

@@ -39,10 +39,6 @@ export type PaymentsOptions = (
 		 * Wallet availability override for deterministic previews. Live checkouts probe the host.
 		 */
 		previewWalletAvailability?: WalletAvailability;
-		/**
-		 * Checkout session updated when a buyer signs in. Pass its `chs_`-prefixed `id` and `client_secret`. Without them, sign-in succeeds but the session does not record the buyer.
-		 */
-		checkoutSession?: { id: string; clientSecret: string; };
 		/**
 		 * Runs when the grouped loading state changes. The value is `true` while any mounted element is still loading.
 		 */
@@ -89,10 +85,6 @@ export type PaymentsOptions = (
 		 * Wallet availability override for deterministic previews. Live checkouts probe the host.
 		 */
 		previewWalletAvailability?: WalletAvailability;
-		/**
-		 * Checkout session updated when a buyer signs in. Pass its `chs_`-prefixed `id` and `client_secret`. Without them, sign-in succeeds but the session does not record the buyer.
-		 */
-		checkoutSession?: { id: string; clientSecret: string; };
 		/**
 		 * Runs when the grouped loading state changes. The value is `true` while any mounted element is still loading.
 		 */
@@ -143,10 +135,6 @@ export type PaymentsOptions = (
 		 * Wallet availability override for deterministic previews. Live checkouts probe the host.
 		 */
 		previewWalletAvailability?: WalletAvailability;
-		/**
-		 * Checkout session updated when a buyer signs in. Pass its `chs_`-prefixed `id` and `client_secret`. Without them, sign-in succeeds but the session does not record the buyer.
-		 */
-		checkoutSession?: { id: string; clientSecret: string; };
 		/**
 		 * Runs when the grouped loading state changes. The value is `true` while any mounted element is still loading.
 		 */
@@ -197,10 +185,6 @@ export type PaymentsOptions = (
 		 * Wallet availability override for deterministic previews. Live checkouts probe the host.
 		 */
 		previewWalletAvailability?: WalletAvailability;
-		/**
-		 * Checkout session updated when a buyer signs in. Pass its `chs_`-prefixed `id` and `client_secret`. Without them, sign-in succeeds but the session does not record the buyer.
-		 */
-		checkoutSession?: { id: string; clientSecret: string; };
 		/**
 		 * Runs when the grouped loading state changes. The value is `true` while any mounted element is still loading.
 		 */
@@ -370,6 +354,11 @@ export interface AddressElementProps {
 	 * @default "full"
 	 */
 	layout?: "full" | "compact";
+	/**
+	 * `above` (default) keeps each label outside its field: above it in the `full` layout, as its placeholder in `compact`. `floating` uses each label as the placeholder of its field, in either layout, then shows a small label above the typed text once the field has a value.
+	 * @default "above"
+	 */
+	labelMode?: "above" | "floating";
 	/**
 	 * `full` (default) follows the selected country's complete address format. `minimal` collects only country and postal code. `name` independently adds required name fields. Set `name` to `none` to omit them. This element does not add fields required by a payment method. Card confirmation requires a name, country, and postal code, so keep `name` enabled or pass `billingDetails.name`.
 	 * @default "full"
@@ -466,6 +455,11 @@ export interface AddressElementCreateOptions {
 	 * @default "full"
 	 */
 	layout?: "full" | "compact";
+	/**
+	 * `above` (default) keeps each label outside its field: above it in the `full` layout, as its placeholder in `compact`. `floating` uses each label as the placeholder of its field, in either layout, then shows a small label above the typed text once the field has a value.
+	 * @default "above"
+	 */
+	labelMode?: "above" | "floating";
 	/**
 	 * `full` (default) follows the selected country's complete address format. `minimal` collects only country and postal code. `name` independently adds required name fields. Set `name` to `none` to omit them. This element does not add fields required by a payment method. Card confirmation requires a name, country, and postal code, so keep `name` enabled or pass `billingDetails.name`.
 	 * @default "full"
@@ -591,13 +585,18 @@ export interface EmailElementProps {
 	 * @default true
 	 */
 	label?: boolean;
+	/**
+	 * `above` (default) shows the label above the input. `floating` uses the label text as the placeholder, then shows a small label above the typed text once the input has a value. Ignored when `label` is `false`.
+	 * @default "above"
+	 */
+	labelMode?: "above" | "floating";
 	/**
 	 * Seed value applied once at mount.
 	 * @default ""
 	 */
 	defaultValue?: string;
 	/**
-	 * Placeholder text for the email input. Empty (default) renders `you@example.com`.
+	 * Placeholder text for the email input. Empty (default) renders `you@example.com`. With floating labels the label text is the placeholder instead.
 	 * @default ""
 	 */
 	placeholder?: string;
@@ -637,13 +636,18 @@ export interface EmailElementCreateOptions {
 	 * @default true
 	 */
 	label?: boolean;
+	/**
+	 * `above` (default) shows the label above the input. `floating` uses the label text as the placeholder, then shows a small label above the typed text once the input has a value. Ignored when `label` is `false`.
+	 * @default "above"
+	 */
+	labelMode?: "above" | "floating";
 	/**
 	 * Seed value applied once at mount.
 	 * @default ""
 	 */
 	defaultValue?: string;
 	/**
-	 * Placeholder text for the email input. Empty (default) renders `you@example.com`.
+	 * Placeholder text for the email input. Empty (default) renders `you@example.com`. With floating labels the label text is the placeholder instead.
 	 * @default ""
 	 */
 	placeholder?: string;
@@ -1013,6 +1017,7 @@ export interface PaymentRequestResourceOptions {
 	currency: string;
 	/**
 	 * Payment amount in minor units.
+	 * Change it later with `update()`.
 	 */
 	amount: number;
 	/**
@@ -1030,63 +1035,88 @@ export interface PaymentRequestResourceOptions {
 	 */
 	requestPayerPhone?: boolean;
 	/**
-	 * Ask the sheet for a shipping address (and offer `shippingOptions` when given).
+	 * Ask the sheet for a shipping address (and offer `shippingOptions` when given). PayPal always asks for an address, since it is the address tax is computed on, and returns it as `shipping` only when this is set.
 	 * @default false
 	 */
 	requestShipping?: boolean;
+	/**
+	 * Offer the sheet's own promo code field and answer `onPromoCodeChange`. Apple Pay shows the field on devices that support Apple Pay version 12 (iOS 15 and macOS 12); Google Pay shows it where the account's Google Pay setup allows offers. Other devices open the sheet without it.
+	 * @default false
+	 */
+	requestPromoCode?: boolean;
+	/**
+	 * A promo code already applied to the charge, prefilled into the sheet so the buyer can see or remove it.
+	 */
+	appliedPromoCode?: string;
+	/**
+	 * What `appliedPromoCode` does, shown next to the code where the sheet captions applied codes (Google Pay).
+	 */
+	appliedPromoDescription?: string;
 	/**
 	 * Account ISO 3166-1 alpha-2 country code for the Apple Pay sheet. Omit it to use the account's published registration country. The sheet defaults to `US` when neither is available.
 	 */
 	countryCode?: string;
 	/**
 	 * Line items the sheet lists under the total.
+	 * Change it later with `update()`.
 	 */
 	lineItems?: PaymentRequestLineItem[];
 	/**
 	 * Shipping options the sheet offers when `requestShipping` is set. Display-only — update `amount` from your change handler.
+	 * Change it later with `update()`.
 	 */
 	shippingOptions?: PaymentRequestShippingOption[];
 }
 
 /**
- * A minted "paymentRequest" resource — returned by `whop.payments.paymentRequest.create()`. Low-level Apple Pay or Google Pay sheet for custom buttons, express checkout, and shipping callbacks. Wallet tiles automate this flow through `payments.createConfirmationToken`. Await `canMakePayment()` to check availability and prime the sheet, then call `show(type)` synchronously in the user-interaction handler. The resolved `ctok` is a `ctok_`-prefixed confirmation token. Confirm it server-side like an element-minted token.
+ * A minted "paymentRequest" resource — returned by `whop.payments.paymentRequest.create()`. Low-level Apple Pay, Google Pay, or PayPal sheet for custom buttons, express checkout, and shipping callbacks. Wallet tiles automate this flow through `payments.createConfirmationToken`. Await `canMakePayment()` to check availability and prime the wallet, then call `show(type)` synchronously in the user-interaction handler. The resolved `ctok` is a `ctok_`-prefixed confirmation token. Confirm it server-side like an element-minted token. A PayPal token charges at most the total PayPal showed the buyer.
  * @see https://docs.whop.com/elements/latest/payments/paymentRequest
  */
 export interface PaymentRequestResource {
 	/**
-	 * Returns availability for each wallet when the account offers it, the device supports it, and this page's origin is approved for the account (first-party whop.com pages are pre-approved; a merchant page needs its domain registered and verified as a [payment method domain](/api-reference/beta/payment-method-domains/payment-method-domain), and offering Google Pay there is subject to the [Google Pay API Terms of Service](https://payments.developers.google.com/terms/sellertos)). Apple Pay on non-WebKit browsers is the desktop iPhone-handoff flow, so mobile devices there report it unavailable — native Apple Pay on iOS browsers is unaffected. `order` ranks the wallets by which sheet is native to the browser — Apple Pay first on Safari, Google Pay first elsewhere — so express buttons can stack best-first. This primes `show()`. Always await it first.
+	 * Returns availability for each wallet when the account offers it, the device supports it, and this page's origin is approved for the account (first-party whop.com pages are pre-approved; a merchant page needs its domain registered and verified as a [payment method domain](/api-reference/beta/payment-method-domains/payment-method-domain), and offering Google Pay there is subject to the [Google Pay API Terms of Service](https://payments.developers.google.com/terms/sellertos)). On a page that is itself inside an iframe, Apple Pay checks the top-level page's domain instead when the browser exposes it. Apple Pay on non-WebKit browsers is the desktop iPhone-handoff flow, so mobile devices there report it unavailable — native Apple Pay on iOS browsers is unaffected. `order` ranks the wallets by which sheet is native to the browser — Apple Pay first on Safari, Google Pay first elsewhere, PayPal last — so express buttons can stack best-first. `payPal` reports PayPal where the account offers it in this currency, the amount is within PayPal's limits, the request neither sets `setupFutureUsage` nor asks for the payer's phone, PayPal's scripts load on this page, and this page's origin is approved for the account like the other wallets'. A page with a Content Security Policy must allow PayPal's hosts, which `contentSecurityPolicy()` includes. A page that already loads PayPal's own v5 JavaScript SDK reports `payPal: false`. Pass `types` to check only the wallets you list; `show(type)` needs that wallet checked. `wallets` carries each available wallet's official button art (`light` and `dark` color and image). This primes `show()`. Always await it first.
 	 */
-	canMakePayment: () => Promise<WalletAvailability>;
+	canMakePayment: (filter?: { types?: ("apple_pay" | "google_pay" | "paypal_express")[] | undefined; } | undefined) => Promise<WalletAvailability>;
 	/**
-	 * Open the selected wallet sheet after awaiting `canMakePayment()`. Apple requires session creation within the gesture stack. Pass `email` when your page already collected one — the sheet takes it and never asks for a second. With `requestPayerEmail: false`, passing one is required, and the sheet refuses to open without it because confirmation tokens require an email.
+	 * Open the selected wallet after awaiting `canMakePayment()`, synchronously in the press: Apple requires session creation within the gesture stack, and PayPal opens its window there — a pop-up on desktop, PayPal's in-page window when the pop-up is blocked and on mobile. Pass `email` when your page already collected one — the wallet takes it and never asks for a second. With `requestPayerEmail: false`, passing one is required, and the wallet refuses to open without it because confirmation tokens require an email. While the sheet is open, `update()` throws: answer the change events to change it.
 	 * Call synchronously during user activation. Await prerequisites first because browsers revoke activation across asynchronous steps.
 	 */
-	show: (type: "apple_pay" | "google_pay", provided?: { email?: string | undefined; } | undefined) => Promise<PaymentRequestResult>;
+	show: (type: "apple_pay" | "google_pay" | "paypal_express", provided?: { email?: string | undefined; } | undefined) => Promise<PaymentRequestResult>;
+	/**
+	 * Change `amount`, `lineItems` and `shippingOptions` on this instance. Every other option is fixed at `create()`: create a new instance to change it.
+	 */
+	update: (patch: { amount?: number | undefined; lineItems?: PaymentRequestLineItem[] | undefined; shippingOptions?: PaymentRequestShippingOption[] | undefined; }) => void;
 	/**
-	 * The sheet's shipping address changed (redacted pre-authorization: city/state/postal/country only). An error in the answer that names a `field` (`city`, `state`, `postal_code`, `country`) marks that field in Apple Pay; Google Pay shows the message alone.
-	 * Call `updateWith(…)` exactly once per event or the flow waits until the vendor times out.
+	 * The sheet's shipping address changed (redacted pre-authorization: city/state/postal/country only). An error in the answer that names a `field` (`city`, `state`, `postal_code`, `country`) marks that field in Apple Pay; Google Pay shows the message alone. PayPal fires it with the address the buyer picks, and an error naming a `field` refuses that part of the address inside PayPal.
+	 * Call `updateWith(…)` exactly once per event. A handler that throws or rejects before calling it fails that update right away.
 	 * Returns the unsubscribe function.
 	 */
 	onShippingAddressChange(handler: (ev: ShippingAddressChangeEvent) => void): () => void;
 	/**
-	 * The buyer picked a shipping option. Amount-only contract: `updateWith` carries amount/lineItems/shippingOptions/errors.
-	 * Call `updateWith(…)` exactly once per event or the flow waits until the vendor times out.
+	 * The buyer picked a shipping option. Amount-only contract: `updateWith` carries amount/lineItems/shippingOptions/errors. Apple Pay has no error slot for a shipping option: an answer with `errors` keeps the last accepted total, and the first error's message shows when the buyer taps Pay, until they pick an option your handler accepts. Google Pay shows the message when the option is picked.
+	 * Call `updateWith(…)` exactly once per event. A handler that throws or rejects before calling it fails that update right away.
 	 * Returns the unsubscribe function.
 	 */
 	onShippingOptionChange(handler: (ev: ShippingOptionChangeEvent) => void): () => void;
 	/**
-	 * Fires at sheet open and on card switches with the selected card's redacted billing address (city/state/postal/country only) — reprice the total for the address the charge taxes off. Answer `updateWith({ amount })` in minor units, or `updateWith({})` to keep the current total. Every event is answered exactly once: a slow, thrown, or superseded handler answers keep-current.
-	 * Call `updateWith(…)` exactly once per event or the flow waits until the vendor times out.
+	 * Fires at sheet open and on card switches with the selected card's redacted billing address (city/state/postal/country only) — reprice the total for the address the charge taxes off. Answer `updateWith({ amount })` in minor units, `updateWith({})` to keep the current total, or `updateWith({ errors })` to refuse the card. Every event is answered exactly once: a handler that throws, rejects, or doesn't answer within 10 seconds refuses the card, so the buyer picks another one. PayPal fires it with each shipping address the buyer picks in PayPal, which is the address its token bills and taxes on, and a refusal there refuses that address inside PayPal.
+	 * Call `updateWith(…)` exactly once per event. A handler that throws or rejects before calling it fails that update right away.
 	 * Returns the unsubscribe function.
 	 */
 	onBillingAddressChange(handler: (ev: BillingAddressChangeEvent) => void): () => void;
+	/**
+	 * The buyer typed, changed, or removed a code in the sheet's promo field (`requestPromoCode`). Answer `updateWith({ amount })` to apply the code at a new total, `updateWith({})` to apply it at the current total, or `updateWith({ error })` to refuse it in place. A removal arrives with `code` null and is answered the same way. A handler that throws, rejects, or doesn't answer within 10 seconds refuses the code.
+	 * Call `updateWith(…)` exactly once per event. A handler that throws or rejects before calling it fails that update right away.
+	 * Returns the unsubscribe function.
+	 */
+	onPromoCodeChange(handler: (ev: PromoCodeChangeEvent) => void): () => void;
 	/**
 	 * The sheet created a confirmation token. This is the same result that `show()` returns.
 	 * Returns the unsubscribe function.
 	 */
 	onConfirmationToken(handler: (ev: PaymentRequestResult) => void): () => void;
 	/**
-	 * The buyer dismissed the sheet.
+	 * The buyer dismissed the sheet or closed PayPal.
 	 * Returns the unsubscribe function.
 	 */
 	onCancel(handler: () => void): () => void;
@@ -1154,12 +1184,36 @@ export interface PaymentsStatics {
 	 */
 	handleNextAction: (input: { clientSecret: string; returnUrl?: string | undefined; pollIntervalMs?: number | undefined; }) => Promise<{ status: string; redirected: boolean; lastPaymentError: { code?: string | null | undefined; decline_code?: string | null | undefined; message?: string | null | undefined; } | null; }>;
 	/**
-	 * Low-level Apple Pay or Google Pay sheet for custom buttons, express checkout, and shipping callbacks. Wallet tiles automate this flow through `payments.createConfirmationToken`. Await `canMakePayment()` to check availability and prime the sheet, then call `show(type)` synchronously in the user-interaction handler. The resolved `ctok` is a `ctok_`-prefixed confirmation token. Confirm it server-side like an element-minted token.
+	 * Low-level Apple Pay, Google Pay, or PayPal sheet for custom buttons, express checkout, and shipping callbacks. Wallet tiles automate this flow through `payments.createConfirmationToken`. Await `canMakePayment()` to check availability and prime the wallet, then call `show(type)` synchronously in the user-interaction handler. The resolved `ctok` is a `ctok_`-prefixed confirmation token. Confirm it server-side like an element-minted token. A PayPal token charges at most the total PayPal showed the buyer.
 	 * Mint with `whop.payments.paymentRequest.create(options)` — nothing needs to be mounted.
 	 */
 	paymentRequest: { create(options: PaymentRequestResourceOptions): PaymentRequestResource };
 }
 
+/**
+ * Declared from the app's `WalletButtonArt`, referenced by a host-capability surface.
+ */
+export interface WalletButtonArt {
+	/**
+	 * For light pages.
+	 */
+	light: { color: string; image: string; };
+	/**
+	 * For dark pages.
+	 */
+	dark: { color: string; image: string; };
+}
+
+/**
+ * Declared from the app's `WalletDetails`, referenced by a host-capability surface.
+ */
+export interface WalletDetails {
+	/**
+	 * The wallet's official button art. Absent when none is published.
+	 */
+	button?: WalletButtonArt | undefined;
+}
+
 /**
  * Host-probed wallet availability after checking offered methods, device capability, and Google Pay origin approval.
  * Declared from the app's `WalletAvailability`, referenced by a host-capability surface.
@@ -1167,10 +1221,15 @@ export interface PaymentsStatics {
 export interface WalletAvailability {
 	applePay: boolean;
 	googlePay: boolean;
+	payPal?: boolean | undefined;
+	/**
+	 * The wallets ranked by which sheet is native to this browser — Apple Pay first on WebKit, Google Pay first everywhere else, PayPal last — so express buttons can stack best-first. Absent on consumer-stated availability (previews) and on wires that predate it. An inline union, not payment-request's WalletSheetType: that module already imports this one.
+	 */
+	order?: ("apple_pay" | "google_pay" | "paypal_express")[] | undefined;
 	/**
-	 * The wallets ranked by which sheet is native to this browser — Apple Pay first on WebKit, Google Pay first everywhere else — so express buttons can stack best-first. Absent on consumer-stated availability (previews) and on wires that predate it. An inline union, not payment-request's WalletSheetType: that module already imports this one.
+	 * Each available wallet's details, keyed by wallet type. Absent on consumer-stated availability (previews).
 	 */
-	order?: ("apple_pay" | "google_pay")[] | undefined;
+	wallets?: { apple_pay?: WalletDetails | undefined; google_pay?: WalletDetails | undefined; paypal_express?: WalletDetails | undefined; } | undefined;
 }
 
 /**
@@ -1228,7 +1287,7 @@ export interface PaymentRequestResult {
 	 * Confirmation token ID, prefixed `ctok_`. Confirm it server-side with your secret key.
 	 */
 	ctok: string;
-	type: "apple_pay" | "google_pay";
+	type: "apple_pay" | "google_pay" | "paypal_express";
 	payer: { email?: string | undefined; name?: string | undefined; phone?: string | undefined; country?: string | undefined; };
 	shipping: { address?: PaymentRequestAddress | undefined; option?: PaymentRequestShippingOption | undefined; } | null;
 }
@@ -1289,7 +1348,39 @@ export interface BillingAddressChangeEvent {
 	 */
 	address: PaymentRequestAddress;
 	/**
-	 * Call this exactly once. An event left unanswered keeps the current total when the reply deadline passes.
+	 * Call this exactly once. An event left unanswered for 10 seconds refuses the card, and the buyer picks another one.
 	 */
 	updateWith: (update: PaymentRequestUpdate) => void;
 }
+
+/**
+ * Declared from the app's `PromoCodeUpdate`, referenced by a host-capability surface.
+ */
+export interface PromoCodeUpdate {
+	/**
+	 * The total under the code, in minor units.
+	 */
+	amount?: number | undefined;
+	/**
+	 * A caption for the applied code, where the sheet captions codes (Google Pay).
+	 */
+	appliedDescription?: string | undefined;
+	/**
+	 * Refuses the code. The sheet shows `message` next to its promo field.
+	 */
+	error?: { message: string; } | undefined;
+}
+
+/**
+ * Declared from the app's `PromoCodeChangeEvent`, referenced by a host-capability surface.
+ */
+export interface PromoCodeChangeEvent {
+	/**
+	 * The code now in the sheet's promo field, or null when the buyer removed it.
+	 */
+	code: string | null;
+	/**
+	 * Answer exactly once: `error` refuses the code and keeps the totals, and any other answer applies it. `amount` reprices the sheet under the code, and `appliedDescription` captions the applied code where the sheet shows one (Google Pay). `updateWith({})` applies the code at the current total.
+	 */
+	updateWith: (update: PromoCodeUpdate) => void;
+}