@amos.com/react-amos-js 0.11.20 → 0.11.22

package/README.md

@@ -60,8 +60,8 @@ The key differences between the express and non-express payment flows are:
 
 Setup intents are used to save payment methods for future use (e.g. recurring payments, subscriptions) without charging the customer immediately. The flow is identical to a payment intent, except:
 
-- On the server, call `POST /setup_intents` instead of `POST /payment_intents`.
-- On the client, `await confirmSetup({ iframeRef, token })` instead of `confirmPayment({ iframeRef, token })`.
+- On the server, call `POST /setup_intents` instead of `POST /payment_intents`. Setup intents are organization-scoped (`X-Account-Id` is ignored if sent). The embed JWT carries `organization_id` + `setup_intent_id` (`account_id` is null). Payment-intent tokens remain account-scoped (`account_id` + `payment_intent_id`).
+- On the client, `await confirmSetup({ iframeRef, token })` instead of `confirmPayment({ iframeRef, token })`. `confirmSetup` reads `setup_intent_id` from the JWT; it does not need `account_id`.
 - Both resolve with a status and the matching intent object when the confirm API returned a body (`ConfirmPaymentResult` / `ConfirmSetupResult`).
 
 The same `AmosCreditCardPaymentMethodForm` / `AmosBankAccountPaymentMethodForm` components support both payment intents and setup intents — they are differentiated by which confirmation function you call. For bank setup, pass `intent="setup"` so Plaid is always shown (unless the render token disables verification).
@@ -141,7 +141,7 @@ appearance={{
 
 Rules override `themeVariables` for the properties they set (Stripe). `--input-height` / `--floating-input-height` are a **minimum**; `.Input` `padding`, `fontSize`, and `lineHeight` can grow the field. Rule values may reference allowlisted tokens as `var(--primary)` (no fallback argument).
 
-The host skeleton (shown until `UPDATED_APPEARANCE`, or 1.5s after `IFRAME_READY` if appearance never acks) copies `themeVariables` and resting **`.Input` / `.Label`** declarations (the same allowlisted properties as iframe rules). It does not inject webfonts: it uses `--font-family` / `fontFamily` when that face is already on the host page, and falls back to `ui-sans-serif, system-ui, sans-serif`. Hover, invalid, placeholder, dropdown, and radio rules have no skeleton equivalent. Floating labels sit inside the control, so `.Label` / `.Label--floating` do not change skeleton height.
+The host skeleton (shown until `UPDATED_APPEARANCE`, or 1.5s after `IFRAME_READY` if appearance never acks) copies `themeVariables` and resting **`.Input` / `.Label`** declarations (the same allowlisted properties as iframe rules). It covers a visible iframe (`opacity: 1`) so WebKit still runs iframe JS. It does not inject webfonts: it uses `--font-family` / `fontFamily` when that face is already on the host page, and falls back to `ui-sans-serif, system-ui, sans-serif`. Hover, invalid, placeholder, dropdown, and radio rules have no skeleton equivalent. Floating labels sit inside the control, so `.Label` / `.Label--floating` do not change skeleton height.
 
 | Selector | Targets |
 | --- | --- |
@@ -560,7 +560,7 @@ Focus a named control inside the card or bank iframe. No-op if the field is not
 
 ### `AmosCreditCardPaymentMethodForm`
 
-Renders the secure credit card iframe form. A field-shaped skeleton is shown immediately (sized from `appearance`, including resting `.Input` / `.Label` rules) and replaced by the iframe once appearance is applied.
+Renders the secure credit card iframe form. A field-shaped skeleton covers a visible iframe immediately (sized from `appearance`, including resting `.Input` / `.Label` rules) and is removed once appearance is applied, or 1.5s after `IFRAME_READY` if appearance never acks.
 
 **Required props:**
 
@@ -575,6 +575,7 @@ Renders the secure credit card iframe form. A field-shaped skeleton is shown imm
 - `defaultValues` (`{ name?: string; billingAddress?: { line1?, line2?, city?, state?, postalCode?, country? } }`) — seed cardholder / account-holder name and billing address. Provided keys overwrite matching fields, including ones the customer already edited. Values are also sent on confirm even when those inputs are hidden (cardholder name off, or `country` billing mode). Never send PAN, CVC, account number, or routing number.
 - `onValidityChange` (`(event: { isValid: boolean }) => void`) — called when form validity changes. `isValid` is true when all required fields are present and valid. Does not include PCI data. Use this to enable or disable your checkout button.
 - `onCardBrandChanged` (`(event: { brand: CardBrand | null }) => void`) — called when the detected card brand changes. `brand` is `"visa"`, `"mastercard"`, `"amex"`, `"discover"`, `"diners"`, or `"jcb"`, or `null` when the field is empty or the number does not match a known brand. Does not include PCI data.
+- `onPostalCodeChange` (`(event: { postalCode: string | null; country: string }) => void`) — called when the customer commits a billing postal code, or clears one. `postalCode` is a finished code, or `null` when a finished code is deleted or the country changes. Incomplete keystrokes are not reported. US and PR commit at 5 digits (ZIP+4 is reported as the first 5). Canada commits as `A1A 1A1`. The UK commits at a full postcode. Not called for `defaultValues`, so a host can copy its own postal field into the iframe until the first callback and then stop. Debounce shipping-rate requests in the host. Card and bank forms only.
 - `onEscapeKeyPressed` (`() => void`) — called when the customer presses Escape in the iframe. PCI-safe — no field values. Use this to close a host modal that contains the iframe. Not fired while an iframe dropdown or address suggestion list is open (that Escape dismisses the overlay first), or while Plaid Embedded Institution Search is showing. The parent cannot attach a keydown listener for this itself because the iframe is cross-origin.
 
 Enter in a card or bank iframe field submits the enclosing host `<form>` via `requestSubmit()` (same as Stripe Elements). Handle that form's `onSubmit` — the parent page cannot see keys typed in the cross-origin iframe. No-op if the component is not inside a `<form>`, or while Plaid Embedded Institution Search is showing.
@@ -583,13 +584,13 @@ Enter in a card or bank iframe field submits the enclosing host `<form>` via `re
 
 ### `AmosBankAccountPaymentMethodForm`
 
-Renders the secure bank account iframe form. A field-shaped skeleton is shown immediately (sized from `appearance`, including resting `.Input` / `.Label` rules) and replaced by the iframe once appearance is applied.
+Renders the secure bank account iframe form. A field-shaped skeleton covers a visible iframe immediately (sized from `appearance`, including resting `.Input` / `.Label` rules) and is removed once appearance is applied, or 1.5s after `IFRAME_READY` if appearance never acks.
 
 When `requireAchVerification` is true (or `intent` is `"setup"`), and the render token allows verification, the SDK hides the routing/account iframe and mounts [Plaid Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/) in the parent. A **350px pulse skeleton** covers that slot until Plaid's `onLoad` (1.5s fallback). Do not overlay a host loader. Hosts do not proxy Pay API (`GET /merchants`, `POST /plaid_link_tokens`); embed does that with `PAY_API_KEY`. Do not put Plaid secrets in the browser.
 
 **Required props:** same as `AmosCreditCardPaymentMethodForm` — `renderToken`.
 
-**Optional props:** same as `AmosCreditCardPaymentMethodForm` — `appearance`, `billingAddressRequirement`, `defaultValues`, `onValidityChange` (`isValid` is also true after Plaid returns credentials), `onEscapeKeyPressed` — plus:
+**Optional props:** same as `AmosCreditCardPaymentMethodForm` — `appearance`, `billingAddressRequirement`, `defaultValues`, `onValidityChange` (`isValid` is also true after Plaid returns credentials), `onPostalCodeChange`, `onEscapeKeyPressed` — plus:
 
 - `requireAchVerification` (`boolean`, defaults to `false`) — when true, show Plaid Embedded Link instead of routing/account fields. Ignored for `intent="setup"` (always Plaid) and when the render token has bank `verification: false`. Hosts that still have an ACH threshold should compute this themselves and pass a new value when the charge changes. Changing this prop hides or shows Link; it does not remount the bank form or destroy the Embedded handler.
 - `intent` (`"payment" | "setup"`, defaults to `"payment"`) — `"setup"` always shows Plaid unless the render token disables verification. Use this when saving a bank account for later charges.
@@ -618,7 +619,7 @@ Setup (always Plaid, unless the render token disables verification):
 
 ### `AmosGooglePayButton`
 
-Renders the secure Google Pay iframe button (express checkout flow). A button-shaped skeleton is shown immediately and replaced by the iframe once appearance is applied.
+Renders the secure Google Pay iframe button (express checkout flow). A button-shaped skeleton covers a visible iframe immediately and is removed once appearance is applied, or 1.5s after `IFRAME_READY` if appearance never acks.
 
 **Required props:**
 
@@ -645,7 +646,7 @@ Renders the secure Google Pay iframe button (express checkout flow). A button-sh
 
 ### `AmosApplePayButton`
 
-Renders the secure Apple Pay iframe button (express checkout flow). Same required props and callbacks as `AmosGooglePayButton`. A button-shaped skeleton is shown immediately and replaced by the iframe once appearance is applied.
+Renders the secure Apple Pay iframe button (express checkout flow). Same required props and callbacks as `AmosGooglePayButton`. A button-shaped skeleton covers a visible iframe immediately and is removed once appearance is applied, or 1.5s after `IFRAME_READY` if appearance never acks.
 
 **Optional props:**
 
@@ -687,7 +688,7 @@ Re-exports of the same advanced helpers exposed by `@amos.com/amos-js`. Most int
 
 Re-exports from `@amos.com/amos-js`. Build the iframe `src` URL for each form type. The React components call these for you.
 
-Each URL includes the embed's canonical search params (`token`, `additionalFields`, `billingAddressRequirement`, `intent`) so the embed router does not 307 to fill in defaults. After the iframe `load` event, if `IFRAME_READY` never arrives (stale HTML, missing JS chunk), the SDK rewrites `src` once with `amosReload` so the next document is a real navigation. Appearance is applied after handshake via `UPDATE_APPEARANCE` (the iframe stays hidden until then, or for 1.5s after `IFRAME_READY` if appearance never acks).
+Each URL includes the embed's canonical search params (`token`, `additionalFields`, `billingAddressRequirement`, `intent`) so the embed router does not 307 to fill in defaults. After the iframe `load` event, if `IFRAME_READY` never arrives (stale HTML, missing JS chunk), the SDK rewrites `src` once with `amosReload` so the next document is a real navigation. Appearance is applied after handshake via `UPDATE_APPEARANCE`. A host-page skeleton covers the visible iframe until then, or for 1.5s after `IFRAME_READY` if appearance never acks.
 
 ### `updateDefaultValues({ iframe, defaultValues })`
 
@@ -708,7 +709,7 @@ Re-export from `@amos.com/amos-js`. Fills omitted Inter `fonts` / `--font-family
 - **Same components for payment vs setup intents**: `AmosCreditCardPaymentMethodForm` and `AmosBankAccountPaymentMethodForm` support both payment intents and setup intents. The flow differs only by which server call you make and which confirmation function you use (`confirmPayment` vs `confirmSetup`).
 - **Amount format**: for `AmosGooglePayButton` and `AmosApplePayButton`, `amount` is a major-currency decimal string (e.g. `"50.00"` for $50.00). For `components["schemas"]["CreatePaymentIntentInput"]` on the server (card/bank create, and the object the wallet iframe sends to `onConfirm`), `amount` is a number in cents (e.g. `5000`).
 - **Embed host / CSP**: iframes load from `https://js.amos.com` (production) and `https://js-sandbox.amos.com` (sandbox) via `getEmbedOrigin`. Parent pages that pin CSP must allow `frame-src https://js.amos.com https://js-sandbox.amos.com` (and `Permissions-Policy payment=` for those origins) **before** upgrading this package. Older SDK versions still load `embed.amos.com` / `embed-sandbox.amos.com`.
-- **Iframe handshake**: iframe URLs include canonical search params so the embed does not 307. If the document loads but never posts `IFRAME_READY`, the SDK rewrites `src` once with `amosReload`. Appearance is applied after handshake; the iframe stays hidden until `UPDATED_APPEARANCE`, or for 1.5s after `IFRAME_READY` if appearance never acks.
+- **Iframe handshake**: iframe URLs include canonical search params so the embed does not 307. If the document loads but never posts `IFRAME_READY`, the SDK rewrites `src` once with `amosReload`. Appearance is applied after handshake. The iframe stays visible under the skeleton until `UPDATED_APPEARANCE`, or for 1.5s after `IFRAME_READY` if appearance never acks. Embed messages match on origin plus `iframeName` when `contentWindow` identity changes.
 - **Plaid Embedded Link (ACH verification)**: load `cdn.plaid.com` from the **parent** document (see CSP on `AmosBankAccountPaymentMethodForm`). Merchants do not proxy Pay API; the bank iframe mints link tokens. Pass `requireAchVerification` when the host wants Plaid, or `intent="setup"` to always show it, unless the render token disables verification. Toggling that prop hides or shows the existing Embedded handler — it does not reload Institution Search. Confirm still goes through the bank iframe so Amos can attach `plaid` to the payment method. While Link loads, the SDK shows a 350px pulse skeleton until `onLoad` (1.5s fallback) — do not overlay a host loader.
 - **Apple Pay waiting overlay**: on browsers where Apple's QR handoff opens in a popup (non-Safari), `AmosApplePayButton` shows a fixed full-viewport overlay on the host page. **Cancel payment** is available until the buyer authorizes; after that the overlay shows **Completing your payment…** with no Cancel, then hides when `onConfirm` settles. Avoid stacking other fixed UI above it.
 - **Going framework-free**: if you need to use Amos outside of React (vanilla JS, another framework, etc.), use [`@amos.com/amos-js`](../amos-js) directly.

package/dist/index.d.ts

@@ -67,6 +67,10 @@ export declare function focusField({ iframeRef, field, }: {
 }): void;
 type ForwardedIframeRef = Ref<HTMLIFrameElement> | undefined;
 type IframePassthroughProps = Omit<ComponentProps<"iframe">, "src" | "title" | "name" | "role" | "allow">;
+type PostalCodeChangeHandler = (event: {
+    postalCode: string | null;
+    country: string;
+}) => void;
 type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
     renderToken: string;
     appearance?: Appearance;
@@ -85,6 +89,12 @@ type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
     onCardBrandChanged?: (event: {
         brand: "visa" | "mastercard" | "amex" | "discover" | "diners" | "jcb" | null;
     }) => void;
+    /**
+     * Called when the customer commits a billing postal code, or clears
+     * one. `postalCode` is null when a finished code becomes incomplete.
+     * Incomplete keystrokes and `defaultValues` writes are omitted.
+     */
+    onPostalCodeChange?: PostalCodeChangeHandler;
     /**
      * Called when the customer presses Escape in the iframe. PCI-safe —
      * no field values. Use this to close a host modal that contains the
@@ -102,7 +112,7 @@ type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
      */
     defaultValues?: PaymentMethodFormDefaultValues;
 };
-export declare function AmosCreditCardPaymentMethodForm({ ref, renderToken, appearance, onValidityChange, onCardBrandChanged, onEscapeKeyPressed, additionalFields, billingAddressRequirement, defaultValues, style, ...rest }: AmosCreditCardPaymentMethodFormProps): import("react").JSX.Element;
+export declare function AmosCreditCardPaymentMethodForm({ ref, renderToken, appearance, onValidityChange, onCardBrandChanged, onPostalCodeChange, onEscapeKeyPressed, additionalFields, billingAddressRequirement, defaultValues, style, ...rest }: AmosCreditCardPaymentMethodFormProps): import("react").JSX.Element;
 type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
     renderToken: string;
     appearance?: Appearance;
@@ -122,6 +132,12 @@ type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
      * showing.
      */
     onEscapeKeyPressed?: () => void;
+    /**
+     * Called when the customer commits a billing postal code, or clears
+     * one. `postalCode` is null when a finished code becomes incomplete.
+     * Incomplete keystrokes and `defaultValues` writes are omitted.
+     */
+    onPostalCodeChange?: PostalCodeChangeHandler;
     billingAddressRequirement?: BillingAddressRequirement;
     /**
      * Seed account holder name and billing address. Provided keys
@@ -151,7 +167,7 @@ type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
      */
     intent?: "payment" | "setup";
 };
-export declare function AmosBankAccountPaymentMethodForm({ ref, renderToken, appearance, onValidityChange, onEscapeKeyPressed, billingAddressRequirement, defaultValues, requireAchVerification, intent, style, ...rest }: AmosBankAccountPaymentMethodFormProps): import("react").JSX.Element;
+export declare function AmosBankAccountPaymentMethodForm({ ref, renderToken, appearance, onValidityChange, onPostalCodeChange, onEscapeKeyPressed, billingAddressRequirement, defaultValues, requireAchVerification, intent, style, ...rest }: AmosBankAccountPaymentMethodFormProps): import("react").JSX.Element;
 type AmosGooglePayButtonProps = {
     ref?: ForwardedIframeRef;
     renderToken: string;

package/dist/index.js

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@amos.com/amos-js"),t=require("react"),n=require("react/jsx-runtime");function r(e){var t;return e?(t=e.current)==null?null:t:null}function i({iframeRef:t}){return(0,e.validateForm)({iframe:r(t)})}function a({iframeRef:t,token:n,defaultValues:i}){return(0,e.confirmPayment)({iframe:r(t),token:n,defaultValues:i})}function o({iframeRef:t,token:n,defaultValues:i}){return(0,e.confirmSetup)({iframe:r(t),token:n,defaultValues:i})}function s({iframeRef:t}){(0,e.resetForm)({iframe:r(t)})}function c({iframeRef:t,field:n}){(0,e.focusField)({iframe:r(t),field:n})}function l(e,t){typeof e==`function`?e(t):e&&(e.current=t)}function u(e,{style:t,className:n,id:r,...i}){n!=null&&(e.className=n),r!=null&&(e.id=r),Object.assign(e.style,t);for(let[t,n]of Object.entries(i))n!=null&&(t in e?Reflect.set(e,t,n):e.setAttribute(t,String(n)))}function d({containerRef:e,iframeRef:n,mount:r,options:i,remountDeps:a,iframePassthrough:o,updateDeps:s}){let c=(0,t.useRef)(null);(0,t.useLayoutEffect)(()=>{let t=e.current;if(!t)return;let a=r(t,i);return c.current=a,l(n,a.iframe),u(a.iframe,o),()=>{a.destroy(),c.current=null,l(n,null)}},[...a]),(0,t.useEffect)(()=>{var e;(e=c.current)==null||e.update(i)},[...s]),(0,t.useEffect)(()=>{var e;let t=(e=c.current)==null?void 0:e.iframe;t&&u(t,o)})}var f=`oklch(0.97 0 0)`;function p({height:r,borderRadius:i,containerRef:a}){return(0,t.useLayoutEffect)(()=>{(0,e.ensureSkeletonStyles)()},[]),(0,n.jsxs)(`div`,{style:{boxSizing:`border-box`,position:`relative`,width:`100%`,height:r,minHeight:r,overflow:`hidden`},children:[(0,n.jsx)(`div`,{className:`amos-js-form-skeleton-input amos-js-wallet-skeleton`,style:{position:`absolute`,inset:0,height:r,borderRadius:i,background:f,pointerEvents:`none`,zIndex:0},"aria-hidden":!0}),(0,n.jsx)(`div`,{ref:a,style:{position:`absolute`,inset:0,zIndex:1,width:`100%`,height:`100%`}})]})}function m({ref:r,renderToken:i,appearance:a,onValidityChange:o,onCardBrandChanged:s,onEscapeKeyPressed:c,additionalFields:l={cardholderName:!1},billingAddressRequirement:u=`country`,defaultValues:f,style:p,...m}){let h=(0,t.useRef)(null);return d({containerRef:h,iframeRef:r,mount:e.mountAmosCreditCardPaymentMethodForm,options:{renderToken:i,appearance:a,additionalFields:l,billingAddressRequirement:u,defaultValues:f,onValidityChange:o,onCardBrandChanged:s,onEscapeKeyPressed:c},remountDeps:[i,l.cardholderName,u],iframePassthrough:{style:p,...m},updateDeps:[a,l,u,f,o,s,c]}),(0,n.jsx)(`div`,{ref:h})}function h({ref:r,renderToken:i,appearance:a,onValidityChange:o,onEscapeKeyPressed:s,billingAddressRequirement:c=`country`,defaultValues:l,requireAchVerification:u=!1,intent:f=`payment`,style:p,...m}){let h=(0,t.useRef)(null);return d({containerRef:h,iframeRef:r,mount:e.mountAmosBankAccountPaymentMethodForm,options:{renderToken:i,appearance:a,billingAddressRequirement:c,defaultValues:l,requireAchVerification:u,intent:f,onValidityChange:o,onEscapeKeyPressed:s},remountDeps:[i,c,f],iframePassthrough:{style:p,...m},updateDeps:[a,c,l,u,f,o,s]}),(0,n.jsx)(`div`,{ref:h})}function g({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,phoneRequired:l,shippingAddressRequired:u,iframeProps:f,onConfirm:m}){let h=(0,t.useRef)(null),g=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:f==null?void 0:f.style,buttonProps:c});return d({containerRef:h,iframeRef:r,mount:e.mountAmosGooglePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,phoneRequired:l,shippingAddressRequired:u,onConfirm:m},remountDeps:[i],iframePassthrough:f==null?{}:f,updateDeps:[a,o,s,c,l,u,m]}),(0,n.jsx)(p,{height:s,borderRadius:g,containerRef:h})}function _({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,phoneRequired:l,shippingAddressRequired:u,iframeProps:f,onConfirm:m}){let h=(0,t.useRef)(null),g=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:f==null?void 0:f.style,buttonProps:c});return d({containerRef:h,iframeRef:r,mount:e.mountAmosApplePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,phoneRequired:l,shippingAddressRequired:u,onConfirm:m},remountDeps:[i],iframePassthrough:f==null?{}:f,updateDeps:[a,o,s,c,l,u,m]}),(0,n.jsx)(p,{height:s,borderRadius:g,containerRef:h})}exports.AmosApplePayButton=_,exports.AmosBankAccountPaymentMethodForm=h,exports.AmosCreditCardPaymentMethodForm=m,exports.AmosGooglePayButton=g,exports.confirmPayment=a,exports.confirmSetup=o,exports.focusField=c,exports.resetForm=s,exports.validateForm=i,Object.keys(e).forEach(function(t){t!=="default"&&!Object.prototype.hasOwnProperty.call(exports,t)&&Object.defineProperty(exports,t,{enumerable:!0,get:function(){return e[t]}})});
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@amos.com/amos-js"),t=require("react"),n=require("react/jsx-runtime");function r(e){var t;return e?(t=e.current)==null?null:t:null}function i({iframeRef:t}){return(0,e.validateForm)({iframe:r(t)})}function a({iframeRef:t,token:n,defaultValues:i}){return(0,e.confirmPayment)({iframe:r(t),token:n,defaultValues:i})}function o({iframeRef:t,token:n,defaultValues:i}){return(0,e.confirmSetup)({iframe:r(t),token:n,defaultValues:i})}function s({iframeRef:t}){(0,e.resetForm)({iframe:r(t)})}function c({iframeRef:t,field:n}){(0,e.focusField)({iframe:r(t),field:n})}function l(e,t){typeof e==`function`?e(t):e&&(e.current=t)}function u(e,{style:t,className:n,id:r,...i}){n!=null&&(e.className=n),r!=null&&(e.id=r),Object.assign(e.style,t);for(let[t,n]of Object.entries(i))n!=null&&(t in e?Reflect.set(e,t,n):e.setAttribute(t,String(n)))}function d({containerRef:e,iframeRef:n,mount:r,options:i,remountDeps:a,iframePassthrough:o,updateDeps:s}){let c=(0,t.useRef)(null);(0,t.useLayoutEffect)(()=>{let t=e.current;if(!t)return;let a=r(t,i);return c.current=a,l(n,a.iframe),u(a.iframe,o),()=>{a.destroy(),c.current=null,l(n,null)}},[...a]),(0,t.useEffect)(()=>{var e;(e=c.current)==null||e.update(i)},[...s]),(0,t.useEffect)(()=>{var e;let t=(e=c.current)==null?void 0:e.iframe;t&&u(t,o)})}var f=`oklch(0.97 0 0)`;function p({height:r,borderRadius:i,containerRef:a}){return(0,t.useLayoutEffect)(()=>{(0,e.ensureSkeletonStyles)()},[]),(0,n.jsxs)(`div`,{style:{boxSizing:`border-box`,position:`relative`,width:`100%`,height:r,minHeight:r,overflow:`hidden`},children:[(0,n.jsx)(`div`,{className:`amos-js-form-skeleton-input amos-js-wallet-skeleton`,style:{position:`absolute`,inset:0,height:r,borderRadius:i,background:f,pointerEvents:`none`,zIndex:0},"aria-hidden":!0}),(0,n.jsx)(`div`,{ref:a,style:{position:`absolute`,inset:0,zIndex:1,width:`100%`,height:`100%`}})]})}function m(t,n){return(0,e.mountAmosCreditCardPaymentMethodForm)(t,n)}function h(t,n){return(0,e.mountAmosBankAccountPaymentMethodForm)(t,n)}function g({ref:e,renderToken:r,appearance:i,onValidityChange:a,onCardBrandChanged:o,onPostalCodeChange:s,onEscapeKeyPressed:c,additionalFields:l={cardholderName:!1},billingAddressRequirement:u=`country`,defaultValues:f,style:p,...h}){let g=(0,t.useRef)(null);return d({containerRef:g,iframeRef:e,mount:m,options:{renderToken:r,appearance:i,additionalFields:l,billingAddressRequirement:u,defaultValues:f,onValidityChange:a,onCardBrandChanged:o,onPostalCodeChange:s,onEscapeKeyPressed:c},remountDeps:[r,l.cardholderName,u],iframePassthrough:{style:p,...h},updateDeps:[i,l,u,f,a,o,s,c]}),(0,n.jsx)(`div`,{ref:g})}function _({ref:e,renderToken:r,appearance:i,onValidityChange:a,onPostalCodeChange:o,onEscapeKeyPressed:s,billingAddressRequirement:c=`country`,defaultValues:l,requireAchVerification:u=!1,intent:f=`payment`,style:p,...m}){let g=(0,t.useRef)(null);return d({containerRef:g,iframeRef:e,mount:h,options:{renderToken:r,appearance:i,billingAddressRequirement:c,defaultValues:l,requireAchVerification:u,intent:f,onValidityChange:a,onPostalCodeChange:o,onEscapeKeyPressed:s},remountDeps:[r,c,f],iframePassthrough:{style:p,...m},updateDeps:[i,c,l,u,f,a,o,s]}),(0,n.jsx)(`div`,{ref:g})}function v({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,phoneRequired:l,shippingAddressRequired:u,iframeProps:f,onConfirm:m}){let h=(0,t.useRef)(null),g=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:f==null?void 0:f.style,buttonProps:c});return d({containerRef:h,iframeRef:r,mount:e.mountAmosGooglePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,phoneRequired:l,shippingAddressRequired:u,onConfirm:m},remountDeps:[i],iframePassthrough:f==null?{}:f,updateDeps:[a,o,s,c,l,u,m]}),(0,n.jsx)(p,{height:s,borderRadius:g,containerRef:h})}function y({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,phoneRequired:l,shippingAddressRequired:u,iframeProps:f,onConfirm:m}){let h=(0,t.useRef)(null),g=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:f==null?void 0:f.style,buttonProps:c});return d({containerRef:h,iframeRef:r,mount:e.mountAmosApplePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,phoneRequired:l,shippingAddressRequired:u,onConfirm:m},remountDeps:[i],iframePassthrough:f==null?{}:f,updateDeps:[a,o,s,c,l,u,m]}),(0,n.jsx)(p,{height:s,borderRadius:g,containerRef:h})}exports.AmosApplePayButton=y,exports.AmosBankAccountPaymentMethodForm=_,exports.AmosCreditCardPaymentMethodForm=g,exports.AmosGooglePayButton=v,exports.confirmPayment=a,exports.confirmSetup=o,exports.focusField=c,exports.resetForm=s,exports.validateForm=i,Object.keys(e).forEach(function(t){t!=="default"&&!Object.prototype.hasOwnProperty.call(exports,t)&&Object.defineProperty(exports,t,{enumerable:!0,get:function(){return e[t]}})});

package/dist/index.mjs

@@ -95,12 +95,18 @@ function E({ height: e, borderRadius: t, containerRef: r }) {
 		})]
 	});
 }
-function D({ ref: e, renderToken: t, appearance: n, onValidityChange: r, onCardBrandChanged: i, onEscapeKeyPressed: a, additionalFields: s = { cardholderName: !1 }, billingAddressRequirement: c = "country", defaultValues: l, style: u, ...d }) {
+function D(e, t) {
+	return o(e, t);
+}
+function O(e, t) {
+	return a(e, t);
+}
+function k({ ref: e, renderToken: t, appearance: n, onValidityChange: r, onCardBrandChanged: i, onPostalCodeChange: a, onEscapeKeyPressed: o, additionalFields: s = { cardholderName: !1 }, billingAddressRequirement: c = "country", defaultValues: l, style: u, ...d }) {
 	let f = p(null);
 	return w({
 		containerRef: f,
 		iframeRef: e,
-		mount: o,
+		mount: D,
 		options: {
 			renderToken: t,
 			appearance: n,
@@ -109,7 +115,8 @@ function D({ ref: e, renderToken: t, appearance: n, onValidityChange: r, onCardB
 			defaultValues: l,
 			onValidityChange: r,
 			onCardBrandChanged: i,
-			onEscapeKeyPressed: a
+			onPostalCodeChange: a,
+			onEscapeKeyPressed: o
 		},
 		remountDeps: [
 			t,
@@ -127,16 +134,17 @@ function D({ ref: e, renderToken: t, appearance: n, onValidityChange: r, onCardB
 			l,
 			r,
 			i,
-			a
+			a,
+			o
 		]
 	}), /* @__PURE__ */ m("div", { ref: f });
 }
-function O({ ref: e, renderToken: t, appearance: n, onValidityChange: r, onEscapeKeyPressed: i, billingAddressRequirement: o = "country", defaultValues: s, requireAchVerification: c = !1, intent: l = "payment", style: u, ...d }) {
+function A({ ref: e, renderToken: t, appearance: n, onValidityChange: r, onPostalCodeChange: i, onEscapeKeyPressed: a, billingAddressRequirement: o = "country", defaultValues: s, requireAchVerification: c = !1, intent: l = "payment", style: u, ...d }) {
 	let f = p(null);
 	return w({
 		containerRef: f,
 		iframeRef: e,
-		mount: a,
+		mount: O,
 		options: {
 			renderToken: t,
 			appearance: n,
@@ -145,7 +153,8 @@ function O({ ref: e, renderToken: t, appearance: n, onValidityChange: r, onEscap
 			requireAchVerification: c,
 			intent: l,
 			onValidityChange: r,
-			onEscapeKeyPressed: i
+			onPostalCodeChange: i,
+			onEscapeKeyPressed: a
 		},
 		remountDeps: [
 			t,
@@ -163,11 +172,12 @@ function O({ ref: e, renderToken: t, appearance: n, onValidityChange: r, onEscap
 			c,
 			l,
 			r,
-			i
+			i,
+			a
 		]
 	}), /* @__PURE__ */ m("div", { ref: f });
 }
-function k({ ref: e, renderToken: t, amount: n, merchantName: r, height: i = "48px", buttonProps: a, phoneRequired: o, shippingAddressRequired: c, iframeProps: u, onConfirm: d }) {
+function j({ ref: e, renderToken: t, amount: n, merchantName: r, height: i = "48px", buttonProps: a, phoneRequired: o, shippingAddressRequired: c, iframeProps: u, onConfirm: d }) {
 	let f = p(null), h = l({
 		iframeStyle: u == null ? void 0 : u.style,
 		buttonProps: a
@@ -203,7 +213,7 @@ function k({ ref: e, renderToken: t, amount: n, merchantName: r, height: i = "48
 		containerRef: f
 	});
 }
-function A({ ref: e, renderToken: t, amount: n, merchantName: r, height: a = "48px", buttonProps: o, phoneRequired: s, shippingAddressRequired: c, iframeProps: u, onConfirm: d }) {
+function M({ ref: e, renderToken: t, amount: n, merchantName: r, height: a = "48px", buttonProps: o, phoneRequired: s, shippingAddressRequired: c, iframeProps: u, onConfirm: d }) {
 	let f = p(null), h = l({
 		iframeStyle: u == null ? void 0 : u.style,
 		buttonProps: o
@@ -240,4 +250,4 @@ function A({ ref: e, renderToken: t, amount: n, merchantName: r, height: a = "48
 	});
 }
 //#endregion
-export { A as AmosApplePayButton, O as AmosBankAccountPaymentMethodForm, D as AmosCreditCardPaymentMethodForm, k as AmosGooglePayButton, v as confirmPayment, y as confirmSetup, x as focusField, b as resetForm, _ as validateForm };
+export { M as AmosApplePayButton, A as AmosBankAccountPaymentMethodForm, k as AmosCreditCardPaymentMethodForm, j as AmosGooglePayButton, v as confirmPayment, y as confirmSetup, x as focusField, b as resetForm, _ as validateForm };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amos.com/react-amos-js",
-  "version": "0.11.20",
+  "version": "0.11.22",
   "main": "dist/index.js",
   "repository": {
     "type": "git",
@@ -46,7 +46,7 @@
   ],
   "description": "React SDK for embedding Amos payment methods via iframes. Wraps @amos.com/amos-js.",
   "devDependencies": {
-    "@amos.com/node": "0.1.57",
+    "@amos.com/node": "0.1.64",
     "@biomejs/biome": "2.5.11",
     "@changesets/cli": "2.31.1",
     "@types/node": "26.4.0",
@@ -57,11 +57,11 @@
     "vite-plugin-dts": "5.0.3"
   },
   "dependencies": {
-    "@amos.com/amos-js": "0.11.21",
+    "@amos.com/amos-js": "0.11.24",
     "@types/googlepay": "0.7.12"
   },
   "peerDependencies": {
     "react": "^17 || ^18 || ^19",
-    "@amos.com/node": ">=0.1.57"
+    "@amos.com/node": ">=0.1.64"
   }
 }

package/src/index.tsx

@@ -296,6 +296,35 @@ function WalletButtonSlot({
   );
 }
 
+type PostalCodeChangeHandler = (event: {
+  postalCode: string | null;
+  country: string;
+}) => void;
+
+/**
+ * The installed `@amos.com/amos-js` types may not include
+ * `onPostalCodeChange` until that package is published. The mount
+ * parameter accepts the extra field; the runtime object still carries
+ * it into `attachPaymentMethodFormListeners`.
+ */
+function mountCreditCardPaymentMethodForm(
+  container: HTMLElement,
+  options: Parameters<typeof mountAmosCreditCardPaymentMethodForm>[1] & {
+    onPostalCodeChange?: PostalCodeChangeHandler;
+  },
+) {
+  return mountAmosCreditCardPaymentMethodForm(container, options);
+}
+
+function mountBankAccountPaymentMethodForm(
+  container: HTMLElement,
+  options: Parameters<typeof mountAmosBankAccountPaymentMethodForm>[1] & {
+    onPostalCodeChange?: PostalCodeChangeHandler;
+  },
+) {
+  return mountAmosBankAccountPaymentMethodForm(container, options);
+}
+
 type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
   renderToken: string;
   appearance?: Appearance;
@@ -319,6 +348,12 @@ type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
       | "jcb"
       | null;
   }) => void;
+  /**
+   * Called when the customer commits a billing postal code, or clears
+   * one. `postalCode` is null when a finished code becomes incomplete.
+   * Incomplete keystrokes and `defaultValues` writes are omitted.
+   */
+  onPostalCodeChange?: PostalCodeChangeHandler;
   /**
    * Called when the customer presses Escape in the iframe. PCI-safe —
    * no field values. Use this to close a host modal that contains the
@@ -343,6 +378,7 @@ export function AmosCreditCardPaymentMethodForm({
   appearance,
   onValidityChange,
   onCardBrandChanged,
+  onPostalCodeChange,
   onEscapeKeyPressed,
   additionalFields = { cardholderName: false },
   billingAddressRequirement = "country",
@@ -355,7 +391,7 @@ export function AmosCreditCardPaymentMethodForm({
   useAmosEmbed({
     containerRef,
     iframeRef: ref as ForwardedIframeRef,
-    mount: mountAmosCreditCardPaymentMethodForm,
+    mount: mountCreditCardPaymentMethodForm,
     options: {
       renderToken,
       appearance,
@@ -364,6 +400,7 @@ export function AmosCreditCardPaymentMethodForm({
       defaultValues,
       onValidityChange,
       onCardBrandChanged,
+      onPostalCodeChange,
       onEscapeKeyPressed,
     },
     remountDeps: [
@@ -379,6 +416,7 @@ export function AmosCreditCardPaymentMethodForm({
       defaultValues,
       onValidityChange,
       onCardBrandChanged,
+      onPostalCodeChange,
       onEscapeKeyPressed,
     ],
   });
@@ -403,6 +441,12 @@ type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
    * showing.
    */
   onEscapeKeyPressed?: () => void;
+  /**
+   * Called when the customer commits a billing postal code, or clears
+   * one. `postalCode` is null when a finished code becomes incomplete.
+   * Incomplete keystrokes and `defaultValues` writes are omitted.
+   */
+  onPostalCodeChange?: PostalCodeChangeHandler;
   billingAddressRequirement?: BillingAddressRequirement;
   /**
    * Seed account holder name and billing address. Provided keys
@@ -438,6 +482,7 @@ export function AmosBankAccountPaymentMethodForm({
   renderToken,
   appearance,
   onValidityChange,
+  onPostalCodeChange,
   onEscapeKeyPressed,
   billingAddressRequirement = "country",
   defaultValues,
@@ -451,7 +496,7 @@ export function AmosBankAccountPaymentMethodForm({
   useAmosEmbed({
     containerRef,
     iframeRef: ref as ForwardedIframeRef,
-    mount: mountAmosBankAccountPaymentMethodForm,
+    mount: mountBankAccountPaymentMethodForm,
     options: {
       renderToken,
       appearance,
@@ -460,6 +505,7 @@ export function AmosBankAccountPaymentMethodForm({
       requireAchVerification,
       intent,
       onValidityChange,
+      onPostalCodeChange,
       onEscapeKeyPressed,
     },
     // `requireAchVerification` is an update, not a remount: amos-js hides
@@ -473,6 +519,7 @@ export function AmosBankAccountPaymentMethodForm({
       requireAchVerification,
       intent,
       onValidityChange,
+      onPostalCodeChange,
       onEscapeKeyPressed,
     ],
   });