@whop/elements 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@whop/elements",
-	"version": "1.4.0",
+	"version": "1.5.0",
 	"description": "Whop Elements — vanilla-js loader + types. Loads the hosted SDK and exposes the typed WhopElements factory.",
 	"keywords": [
 		"checkout",
@@ -97,5 +97,5 @@
 			}
 		}
 	},
-	"whopElementsApiHash": "597d8fc784a33c8b760b0afab305d906f9d79cdaa04ebc7f7b3fc2f4de73400c"
+	"whopElementsApiHash": "2d44149b4b1cc46471d6832a16569c9c60c12e412816bac29665345584162ce2"
 }

package/payments.d.cts

@@ -354,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"
@@ -450,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"
@@ -575,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;
@@ -621,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;
@@ -997,6 +1017,7 @@ export interface PaymentRequestResourceOptions {
 	currency: string;
 	/**
 	 * Payment amount in minor units.
+	 * Change it later with `update()`.
 	 */
 	amount: number;
 	/**
@@ -1018,16 +1039,31 @@ export interface PaymentRequestResourceOptions {
 	 * @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[];
 }
@@ -1038,14 +1074,18 @@ export interface PaymentRequestResourceOptions {
  */
 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, 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`. 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 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.
+	 * 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" | "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. 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.
@@ -1064,6 +1104,12 @@ export interface PaymentRequestResource {
 	 * 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.
@@ -1144,6 +1190,30 @@ export interface PaymentsStatics {
 	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.
@@ -1156,6 +1226,10 @@ export interface WalletAvailability {
 	 * 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;
+	/**
+	 * Each available wallet's details, keyed by wallet type. Absent on consumer-stated availability (previews).
+	 */
+	wallets?: { apple_pay?: WalletDetails | undefined; google_pay?: WalletDetails | undefined; paypal_express?: WalletDetails | undefined; } | undefined;
 }
 
 /**
@@ -1274,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;
+}

package/payments.d.ts

@@ -354,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"
@@ -450,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"
@@ -575,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;
@@ -621,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;
@@ -997,6 +1017,7 @@ export interface PaymentRequestResourceOptions {
 	currency: string;
 	/**
 	 * Payment amount in minor units.
+	 * Change it later with `update()`.
 	 */
 	amount: number;
 	/**
@@ -1018,16 +1039,31 @@ export interface PaymentRequestResourceOptions {
 	 * @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[];
 }
@@ -1038,14 +1074,18 @@ export interface PaymentRequestResourceOptions {
  */
 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, 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`. 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 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.
+	 * 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" | "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. 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.
@@ -1064,6 +1104,12 @@ export interface PaymentRequestResource {
 	 * 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.
@@ -1144,6 +1190,30 @@ export interface PaymentsStatics {
 	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.
@@ -1156,6 +1226,10 @@ export interface WalletAvailability {
 	 * 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;
+	/**
+	 * Each available wallet's details, keyed by wallet type. Absent on consumer-stated availability (previews).
+	 */
+	wallets?: { apple_pay?: WalletDetails | undefined; google_pay?: WalletDetails | undefined; paypal_express?: WalletDetails | undefined; } | undefined;
 }
 
 /**
@@ -1274,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;
+}