@amos.com/react-amos-js 0.11.3 → 0.11.5

package/README.md

@@ -16,7 +16,7 @@ npm install @amos.com/react-amos-js @amos.com/node
 
 - React components for the iframe payment method forms: `AmosCreditCardPaymentMethodForm`, `AmosBankAccountPaymentMethodForm`, `AmosGooglePayButton`, `AmosApplePayButton`.
 - React-flavoured iframe message helpers that accept a React `ref`: `validateForm({ iframeRef })`, `confirmPayment({ iframeRef, token })`, `confirmSetup({ iframeRef, token })`, `resetForm({ iframeRef })`.
-- Re-exports of the `@amos.com/amos-js` helpers and types that come up in client code: `createMessage`, `decodeJwt`, `getEmbedOrigin`, `formatGooglePayPaymentData`, `resetForm`, `ConfirmResult`, `FormattedGooglePayPaymentData`, `Appearance`, `Message`, etc.
+- Re-exports of the `@amos.com/amos-js` helpers and types that come up in client code: `createMessage`, `decodeJwt`, `getEmbedOrigin`, `formatGooglePayPaymentData`, `resetForm`, `ConfirmPaymentResult`, `ConfirmSetupResult`, `FormattedGooglePayPaymentData`, `Appearance`, `Message`, etc.
 
 > **Note:** `@amos.com/react-amos-js` is the client-side half of the Amos integration. For end-to-end payment processing you also need `@amos.com/node` on your server (creating payment intents, handling webhooks, etc.). The same `@amos.com/node` package is listed as a peer dependency so you can import its OpenAPI types in client-side TypeScript code.
 
@@ -44,7 +44,7 @@ The following flow is for credit card and bank account payment method types only
 4. **Create payment intent on your server**: use your server-side Amos client to call `POST /payment_intents`. You may also associate this payment intent with a new or existing customer via `POST /customers`. This must be server-side because it uses your private API key.
 5. **Return the payment intent token to the browser**: your backend responds with the embed token (`components["schemas"]["EmbedToken"]`) needed for confirmation.
 6. **Confirm the payment intent from the client**: `await confirmPayment({ iframeRef, token })`.
-7. **Handle UX**: show the user a "processing" state while awaiting `confirmPayment`. Do not treat `{ status: "succeeded" }` as settlement proof — verify payment success on your backend via webhooks. Recoverable field errors stay in the iframe; `confirmPayment` still resolves `{ status: "failed" }`.
+7. **Handle UX**: show the user a "processing" state while awaiting `confirmPayment`. Do not treat `{ status: "succeeded" }` as settlement proof — verify payment success on your backend via webhooks. Recoverable field errors stay in the iframe; `confirmPayment` still resolves `{ status: "failed" }` (with `paymentIntent` when the confirm API returned a body, including `last_payment_error` on declines).
 
 ### Google Pay & Apple Pay
 
@@ -62,7 +62,7 @@ Setup intents are used to save payment methods for future use (e.g. recurring pa
 
 - On the server, call `POST /setup_intents` instead of `POST /payment_intents`.
 - On the client, `await confirmSetup({ iframeRef, token })` instead of `confirmPayment({ iframeRef, token })`.
-- Both resolve `{ status: "succeeded" | "failed" }`.
+- 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).
 
@@ -243,7 +243,7 @@ import { useState } from "react";
 import {
   AmosApplePayButton,
   AmosGooglePayButton,
-  type ConfirmResult,
+  type ConfirmPaymentResult,
 } from "@amos.com/react-amos-js";
 import type { components } from "@amos.com/node";
 
@@ -279,8 +279,8 @@ function CheckoutWallets({ renderToken }: { renderToken: string }) {
   }: {
     paymentIntentCreateAttributes: components["schemas"]["CreatePaymentIntentInput"];
     customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
-    confirmPayment: (token: string) => Promise<ConfirmResult>;
-  }): Promise<ConfirmResult> {
+    confirmPayment: (token: string) => Promise<ConfirmPaymentResult>;
+  }): Promise<ConfirmPaymentResult> {
     try {
       const token = await createPaymentIntentToken({
         paymentIntentCreateAttributes,
@@ -433,14 +433,14 @@ Validates the embedded card/bank iframe form before payment confirmation.
 
 ### `confirmPayment({ iframeRef, token })`
 
-Confirms a payment intent in the embedded iframe flow. Resolves `{ status: "succeeded" }` or `{ status: "failed" }`.
+Confirms a payment intent in the embedded iframe flow. Resolves `{ status: "succeeded", paymentIntent }` or `{ status: "failed", paymentIntent? }`.
 
 **Parameters:**
 
 - `iframeRef` (`React.RefObject<HTMLIFrameElement | null> | undefined`, required)
 - `token` (typed as `Pick<components["schemas"]["EmbedToken"], "token">` — the embed JWT string returned by your server)
 
-**Returns:** `Promise<ConfirmResult>`
+**Returns:** `Promise<ConfirmPaymentResult>`
 
 ### `confirmSetup({ iframeRef, token })`
 
@@ -451,7 +451,7 @@ Confirms a setup intent in the embedded iframe flow. Use this when saving a paym
 - `iframeRef` (`React.RefObject<HTMLIFrameElement | null> | undefined`, required)
 - `token` (same `Pick<components["schemas"]["EmbedToken"], "token">` embed JWT string as for payment confirmation)
 
-**Returns:** `Promise<ConfirmResult>`
+**Returns:** `Promise<ConfirmSetupResult>`
 
 ### `resetForm({ iframeRef })`
 
@@ -526,7 +526,7 @@ Renders the secure Google Pay iframe button (express checkout flow). A button-sh
 - `renderToken` (`string`)
 - `amount` (`string`) — major-currency decimal string shown in the wallet sheet (e.g. `"50.00"` for $50.00). The iframe converts this to cents in `paymentIntentCreateAttributes.amount`.
 - `merchantName` (`string`)
-- `onConfirm` (callback receiving `{ paymentIntentCreateAttributes, customerCreateAttributes, confirmPayment }`. Create a payment intent, then `return confirmPayment(token)` — `Promise<ConfirmResult>`)
+- `onConfirm` (callback receiving `{ paymentIntentCreateAttributes, customerCreateAttributes, confirmPayment }`. Create a payment intent, then `return confirmPayment(token)` — `Promise<ConfirmPaymentResult>`)
 
 **Optional props:**
 
@@ -582,12 +582,12 @@ Re-exports of the same advanced helpers exposed by `@amos.com/amos-js`. Most int
 
 ### Exported types
 
-`@amos.com/react-amos-js` re-exports everything from `@amos.com/amos-js`, including `ConfirmResult`, `PaymentMethodFormValidityChangeEvent`, `CardBrand`, `PaymentMethodFormCardBrandChangeEvent`, `FormattedGooglePayPaymentData`, `Message`, `Appearance`, `ThemeVariable`, and the per-form `*Options` / `*Controller` types. For OpenAPI schema types (e.g. `PaymentIntent`, `CreatePaymentIntentInput`), import `components` from `@amos.com/node`.
+`@amos.com/react-amos-js` re-exports everything from `@amos.com/amos-js`, including `ConfirmPaymentResult`, `ConfirmSetupResult`, `PaymentMethodFormValidityChangeEvent`, `CardBrand`, `PaymentMethodFormCardBrandChangeEvent`, `FormattedGooglePayPaymentData`, `Message`, `Appearance`, `ThemeVariable`, and the per-form `*Options` / `*Controller` types. For OpenAPI schema types (e.g. `PaymentIntent`, `CreatePaymentIntentInput`), import `components` from `@amos.com/node`.
 
 ## Notes and potential gotchas
 
 - **`ref` / `iframeRef`**: for card and bank forms, pass `ref={iframeRef}` to the form component. The same `iframeRef` must be used when calling `validateForm`, `confirmPayment`, `confirmSetup`, or `resetForm`. The component forwards the ref to the inner iframe.
-- **`confirmPayment` / `confirmSetup` are not settlement proof**: `{ status: "succeeded" }` means authorization succeeded (capture may still finish asynchronously). Verify payment or setup success on your backend via webhooks. Recoverable field errors stay in the iframe; the Promise still resolves `{ status: "failed" }`.
+- **`confirmPayment` / `confirmSetup` are not settlement proof**: `{ status: "succeeded" }` means authorization succeeded (capture may still finish asynchronously). Verify payment or setup success on your backend via webhooks. Recoverable field errors stay in the iframe; the Promise still resolves `{ status: "failed" }`. Declined confirms include the intent so you can read `last_payment_error` without a follow-up GET.
 - **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`).
 - **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. Confirm still goes through the bank iframe so Amos can attach `plaid` to the payment method.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="googlepay" />
-import { Appearance, ApplePayButtonElementProps, BillingAddressRequirement, ConfirmResult, CreditCardAdditionalFields, GooglePayButtonElementProps } from '@amos.com/amos-js';
+import { Appearance, ApplePayButtonElementProps, BillingAddressRequirement, ConfirmPaymentResult, ConfirmSetupResult, CreditCardAdditionalFields, GooglePayButtonElementProps, PaymentMethodFormDefaultValues, PaymentMethodFormField } from '@amos.com/amos-js';
 import { components } from '@amos.com/node';
 import { ComponentProps, Ref, RefObject } from 'react';
 export * from '@amos.com/amos-js';
@@ -20,9 +20,10 @@ export declare function validateForm({ iframeRef, }: {
  * Pass the embed JWT (`token`) returned by your server's
  * `POST /payment_intents` call.
  */
-export declare function confirmPayment({ iframeRef, token, }: {
+export declare function confirmPayment({ iframeRef, token, defaultValues, }: {
     iframeRef: IframeRef;
-} & Pick<components["schemas"]["EmbedToken"], "token">): Promise<ConfirmResult>;
+    defaultValues?: PaymentMethodFormDefaultValues;
+} & Pick<components["schemas"]["EmbedToken"], "token">): Promise<ConfirmPaymentResult>;
 /**
  * Confirm a setup intent in the embedded iframe flow. Use this when
  * saving a payment method for future use.
@@ -30,9 +31,10 @@ export declare function confirmPayment({ iframeRef, token, }: {
  * Pass the embed JWT (`token`) returned by your server's
  * `POST /setup_intents` call.
  */
-export declare function confirmSetup({ iframeRef, token, }: {
+export declare function confirmSetup({ iframeRef, token, defaultValues, }: {
     iframeRef: IframeRef;
-} & Pick<components["schemas"]["EmbedToken"], "token">): Promise<ConfirmResult>;
+    defaultValues?: PaymentMethodFormDefaultValues;
+} & Pick<components["schemas"]["EmbedToken"], "token">): Promise<ConfirmSetupResult>;
 /**
  * Clear all field values and API errors in the embedded card/bank iframe
  * form. Call after a failed confirm when the customer wants to try again.
@@ -40,6 +42,15 @@ export declare function confirmSetup({ iframeRef, token, }: {
 export declare function resetForm({ iframeRef }: {
     iframeRef: IframeRef;
 }): void;
+/**
+ * Focus a named control inside the embedded card/bank iframe. No-op if
+ * the field is not rendered, or while Plaid Embedded Institution Search
+ * is showing. Call from a click or keydown handler.
+ */
+export declare function focusField({ iframeRef, field, }: {
+    iframeRef: IframeRef;
+    field: PaymentMethodFormField;
+}): void;
 type ForwardedIframeRef = Ref<HTMLIFrameElement> | undefined;
 type IframePassthroughProps = Omit<ComponentProps<"iframe">, "src" | "title" | "name" | "role" | "allow">;
 type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
@@ -62,8 +73,14 @@ type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
     }) => void;
     additionalFields?: CreditCardAdditionalFields;
     billingAddressRequirement?: BillingAddressRequirement;
+    /**
+     * Seed cardholder name and billing address. Provided keys overwrite
+     * matching fields, including ones the customer already edited. Values
+     * are sent on confirm even when those inputs are hidden.
+     */
+    defaultValues?: PaymentMethodFormDefaultValues;
 };
-export declare function AmosCreditCardPaymentMethodForm({ ref, renderToken, appearance, onValidityChange, onCardBrandChanged, additionalFields, billingAddressRequirement, style, ...rest }: AmosCreditCardPaymentMethodFormProps): import("react").JSX.Element;
+export declare function AmosCreditCardPaymentMethodForm({ ref, renderToken, appearance, onValidityChange, onCardBrandChanged, additionalFields, billingAddressRequirement, defaultValues, style, ...rest }: AmosCreditCardPaymentMethodFormProps): import("react").JSX.Element;
 type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
     renderToken: string;
     appearance?: Appearance;
@@ -76,6 +93,12 @@ type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
         isValid: boolean;
     }) => void;
     billingAddressRequirement?: BillingAddressRequirement;
+    /**
+     * Seed account holder name and billing address. Provided keys
+     * overwrite matching fields, including ones the customer already
+     * edited.
+     */
+    defaultValues?: PaymentMethodFormDefaultValues;
     /**
      * When true, hide the routing/account iframe and mount Plaid Embedded
      * Institution Search in the parent. Ignored when `intent` is `"setup"`
@@ -94,7 +117,7 @@ type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
      */
     intent?: "payment" | "setup";
 };
-export declare function AmosBankAccountPaymentMethodForm({ ref, renderToken, appearance, onValidityChange, billingAddressRequirement, requireAchVerification, intent, style, ...rest }: AmosBankAccountPaymentMethodFormProps): import("react").JSX.Element;
+export declare function AmosBankAccountPaymentMethodForm({ ref, renderToken, appearance, onValidityChange, billingAddressRequirement, defaultValues, requireAchVerification, intent, style, ...rest }: AmosBankAccountPaymentMethodFormProps): import("react").JSX.Element;
 type AmosGooglePayButtonProps = {
     ref?: ForwardedIframeRef;
     renderToken: string;
@@ -126,8 +149,8 @@ type AmosGooglePayButtonProps = {
     onConfirm: ({ paymentIntentCreateAttributes, customerCreateAttributes, confirmPayment, }: {
         paymentIntentCreateAttributes: components["schemas"]["CreatePaymentIntentInput"];
         customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
-        confirmPayment: (token: string) => Promise<ConfirmResult>;
-    }) => Promise<ConfirmResult>;
+        confirmPayment: (token: string) => Promise<ConfirmPaymentResult>;
+    }) => Promise<ConfirmPaymentResult>;
 };
 /**
  * Renders the secure Google Pay iframe button. A button-shaped
@@ -166,8 +189,8 @@ type AmosApplePayButtonProps = {
     onConfirm: ({ paymentIntentCreateAttributes, customerCreateAttributes, confirmPayment, }: {
         paymentIntentCreateAttributes: components["schemas"]["CreatePaymentIntentInput"];
         customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
-        confirmPayment: (token: string) => Promise<ConfirmResult>;
-    }) => Promise<ConfirmResult>;
+        confirmPayment: (token: string) => Promise<ConfirmPaymentResult>;
+    }) => Promise<ConfirmPaymentResult>;
 };
 /**
  * Renders the secure Apple Pay iframe button. A button-shaped

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){return e?e.current??null:null}function i({iframeRef:t}){return(0,e.validateForm)({iframe:r(t)})}function a({iframeRef:t,token:n}){return(0,e.confirmPayment)({iframe:r(t),token:n})}function o({iframeRef:t,token:n}){return(0,e.confirmSetup)({iframe:r(t),token:n})}function s({iframeRef:t}){(0,e.resetForm)({iframe:r(t)})}function c(e,t){typeof e==`function`?e(t):e&&(e.current=t)}function l(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 u({containerRef:e,iframeRef:n,mount:r,options:i,remountDeps:a,iframePassthrough:o,updateDeps:s}){let u=(0,t.useRef)(null);(0,t.useLayoutEffect)(()=>{let t=e.current;if(!t)return;let a=r(t,i);return u.current=a,c(n,a.iframe),l(a.iframe,o),()=>{a.destroy(),u.current=null,c(n,null)}},[...a]),(0,t.useEffect)(()=>{u.current?.update(i)},[...s]),(0,t.useEffect)(()=>{let e=u.current?.iframe;e&&l(e,o)})}var d=`oklch(0.97 0 0)`;function f({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:d,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 p({ref:r,renderToken:i,appearance:a,onValidityChange:o,onCardBrandChanged:s,additionalFields:c={cardholderName:!1},billingAddressRequirement:l=`country`,style:d,...f}){let p=(0,t.useRef)(null);return u({containerRef:p,iframeRef:r,mount:e.mountAmosCreditCardPaymentMethodForm,options:{renderToken:i,appearance:a,additionalFields:c,billingAddressRequirement:l,onValidityChange:o,onCardBrandChanged:s},remountDeps:[i,c.cardholderName,l],iframePassthrough:{style:d,...f},updateDeps:[a,c,l,o,s]}),(0,n.jsx)(`div`,{ref:p})}function m({ref:r,renderToken:i,appearance:a,onValidityChange:o,billingAddressRequirement:s=`country`,requireAchVerification:c=!1,intent:l=`payment`,style:d,...f}){let p=(0,t.useRef)(null);return u({containerRef:p,iframeRef:r,mount:e.mountAmosBankAccountPaymentMethodForm,options:{renderToken:i,appearance:a,billingAddressRequirement:s,requireAchVerification:c,intent:l,onValidityChange:o},remountDeps:[i,s,l],iframePassthrough:{style:d,...f},updateDeps:[a,s,c,l,o]}),(0,n.jsx)(`div`,{ref:p})}function h({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onConfirm:d}){let p=(0,t.useRef)(null),m=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return u({containerRef:p,iframeRef:r,mount:e.mountAmosGooglePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,onConfirm:d},remountDeps:[i],iframePassthrough:l??{},updateDeps:[a,o,s,c,d]}),(0,n.jsx)(f,{height:s,borderRadius:m,containerRef:p})}function g({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onConfirm:d}){let p=(0,t.useRef)(null),m=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return u({containerRef:p,iframeRef:r,mount:e.mountAmosApplePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,onConfirm:d},remountDeps:[i],iframePassthrough:l??{},updateDeps:[a,o,s,c,d]}),(0,n.jsx)(f,{height:s,borderRadius:m,containerRef:p})}exports.AmosApplePayButton=g,exports.AmosBankAccountPaymentMethodForm=m,exports.AmosCreditCardPaymentMethodForm=p,exports.AmosGooglePayButton=h,exports.confirmPayment=a,exports.confirmSetup=o,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){return e?e.current??null: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)(()=>{c.current?.update(i)},[...s]),(0,t.useEffect)(()=>{let e=c.current?.iframe;e&&u(e,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,additionalFields:c={cardholderName:!1},billingAddressRequirement:l=`country`,defaultValues:u,style:f,...p}){let m=(0,t.useRef)(null);return d({containerRef:m,iframeRef:r,mount:e.mountAmosCreditCardPaymentMethodForm,options:{renderToken:i,appearance:a,additionalFields:c,billingAddressRequirement:l,defaultValues:u,onValidityChange:o,onCardBrandChanged:s},remountDeps:[i,c.cardholderName,l],iframePassthrough:{style:f,...p},updateDeps:[a,c,l,u,o,s]}),(0,n.jsx)(`div`,{ref:m})}function h({ref:r,renderToken:i,appearance:a,onValidityChange:o,billingAddressRequirement:s=`country`,defaultValues:c,requireAchVerification:l=!1,intent:u=`payment`,style:f,...p}){let m=(0,t.useRef)(null);return d({containerRef:m,iframeRef:r,mount:e.mountAmosBankAccountPaymentMethodForm,options:{renderToken:i,appearance:a,billingAddressRequirement:s,defaultValues:c,requireAchVerification:l,intent:u,onValidityChange:o},remountDeps:[i,s,u],iframePassthrough:{style:f,...p},updateDeps:[a,s,c,l,u,o]}),(0,n.jsx)(`div`,{ref:m})}function g({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onConfirm:u}){let f=(0,t.useRef)(null),m=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return d({containerRef:f,iframeRef:r,mount:e.mountAmosGooglePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,onConfirm:u},remountDeps:[i],iframePassthrough:l??{},updateDeps:[a,o,s,c,u]}),(0,n.jsx)(p,{height:s,borderRadius:m,containerRef:f})}function _({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onConfirm:u}){let f=(0,t.useRef)(null),m=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return d({containerRef:f,iframeRef:r,mount:e.mountAmosApplePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,onConfirm:u},remountDeps:[i],iframePassthrough:l??{},updateDeps:[a,o,s,c,u]}),(0,n.jsx)(p,{height:s,borderRadius:m,containerRef:f})}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]}})});

package/dist/index.mjs

@@ -1,57 +1,65 @@
-import { confirmPayment as e, confirmSetup as t, ensureSkeletonStyles as n, mountAmosApplePayButton as r, mountAmosBankAccountPaymentMethodForm as i, mountAmosCreditCardPaymentMethodForm as a, mountAmosGooglePayButton as o, resetForm as s, resolveWalletButtonSkeletonBorderRadius as c, validateForm as l } from "@amos.com/amos-js";
-import { useEffect as u, useLayoutEffect as d, useRef as f } from "react";
-import { jsx as p, jsxs as m } from "react/jsx-runtime";
+import { confirmPayment as e, confirmSetup as t, ensureSkeletonStyles as n, focusField as r, mountAmosApplePayButton as i, mountAmosBankAccountPaymentMethodForm as a, mountAmosCreditCardPaymentMethodForm as o, mountAmosGooglePayButton as s, resetForm as c, resolveWalletButtonSkeletonBorderRadius as l, validateForm as u } from "@amos.com/amos-js";
+import { useEffect as d, useLayoutEffect as f, useRef as p } from "react";
+import { jsx as m, jsxs as h } from "react/jsx-runtime";
 export * from "@amos.com/amos-js";
 //#region src/index.tsx
-function h(e) {
+function g(e) {
 	return e ? e.current ?? null : null;
 }
-function g({ iframeRef: e }) {
-	return l({ iframe: h(e) });
+function _({ iframeRef: e }) {
+	return u({ iframe: g(e) });
 }
-function _({ iframeRef: t, token: n }) {
+function v({ iframeRef: t, token: n, defaultValues: r }) {
 	return e({
-		iframe: h(t),
-		token: n
+		iframe: g(t),
+		token: n,
+		defaultValues: r
 	});
 }
-function v({ iframeRef: e, token: n }) {
+function y({ iframeRef: e, token: n, defaultValues: r }) {
 	return t({
-		iframe: h(e),
-		token: n
+		iframe: g(e),
+		token: n,
+		defaultValues: r
 	});
 }
-function y({ iframeRef: e }) {
-	s({ iframe: h(e) });
+function b({ iframeRef: e }) {
+	c({ iframe: g(e) });
 }
-function b(e, t) {
+function x({ iframeRef: e, field: t }) {
+	r({
+		iframe: g(e),
+		field: t
+	});
+}
+function S(e, t) {
 	typeof e == "function" ? e(t) : e && (e.current = t);
 }
-function x(e, { style: t, className: n, id: r, ...i }) {
+function C(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 S({ containerRef: e, iframeRef: t, mount: n, options: r, remountDeps: i, iframePassthrough: a, updateDeps: o }) {
-	let s = f(null);
-	d(() => {
+function w({ containerRef: e, iframeRef: t, mount: n, options: r, remountDeps: i, iframePassthrough: a, updateDeps: o }) {
+	let s = p(null);
+	f(() => {
 		let i = e.current;
 		if (!i) return;
 		let o = n(i, r);
-		return s.current = o, b(t, o.iframe), x(o.iframe, a), () => {
-			o.destroy(), s.current = null, b(t, null);
+		return s.current = o, S(t, o.iframe), C(o.iframe, a), () => {
+			o.destroy(), s.current = null, S(t, null);
 		};
-	}, [...i]), u(() => {
+	}, [...i]), d(() => {
 		s.current?.update(r);
-	}, [...o]), u(() => {
+	}, [...o]), d(() => {
 		let e = s.current?.iframe;
-		e && x(e, a);
+		e && C(e, a);
 	});
 }
-var C = "oklch(0.97 0 0)";
-function w({ height: e, borderRadius: t, containerRef: r }) {
-	return d(() => {
+var T = "oklch(0.97 0 0)";
+function E({ height: e, borderRadius: t, containerRef: r }) {
+	return f(() => {
 		n();
-	}, []), /* @__PURE__ */ m("div", {
+	}, []), /* @__PURE__ */ h("div", {
 		style: {
 			boxSizing: "border-box",
 			position: "relative",
@@ -60,19 +68,19 @@ function w({ height: e, borderRadius: t, containerRef: r }) {
 			minHeight: e,
 			overflow: "hidden"
 		},
-		children: [/* @__PURE__ */ p("div", {
+		children: [/* @__PURE__ */ m("div", {
 			className: "amos-js-form-skeleton-input amos-js-wallet-skeleton",
 			style: {
 				position: "absolute",
 				inset: 0,
 				height: e,
 				borderRadius: t,
-				background: C,
+				background: T,
 				pointerEvents: "none",
 				zIndex: 0
 			},
 			"aria-hidden": !0
-		}), /* @__PURE__ */ p("div", {
+		}), /* @__PURE__ */ m("div", {
 			ref: r,
 			style: {
 				position: "absolute",
@@ -84,133 +92,137 @@ function w({ height: e, borderRadius: t, containerRef: r }) {
 		})]
 	});
 }
-function T({ ref: e, renderToken: t, appearance: n, onValidityChange: r, onCardBrandChanged: i, additionalFields: o = { cardholderName: !1 }, billingAddressRequirement: s = "country", style: c, ...l }) {
-	let u = f(null);
-	return S({
-		containerRef: u,
+function D({ ref: e, renderToken: t, appearance: n, onValidityChange: r, onCardBrandChanged: i, additionalFields: a = { cardholderName: !1 }, billingAddressRequirement: s = "country", defaultValues: c, style: l, ...u }) {
+	let d = p(null);
+	return w({
+		containerRef: d,
 		iframeRef: e,
-		mount: a,
+		mount: o,
 		options: {
 			renderToken: t,
 			appearance: n,
-			additionalFields: o,
+			additionalFields: a,
 			billingAddressRequirement: s,
+			defaultValues: c,
 			onValidityChange: r,
 			onCardBrandChanged: i
 		},
 		remountDeps: [
 			t,
-			o.cardholderName,
+			a.cardholderName,
 			s
 		],
 		iframePassthrough: {
-			style: c,
-			...l
+			style: l,
+			...u
 		},
 		updateDeps: [
 			n,
-			o,
+			a,
 			s,
+			c,
 			r,
 			i
 		]
-	}), /* @__PURE__ */ p("div", { ref: u });
+	}), /* @__PURE__ */ m("div", { ref: d });
 }
-function E({ ref: e, renderToken: t, appearance: n, onValidityChange: r, billingAddressRequirement: a = "country", requireAchVerification: o = !1, intent: s = "payment", style: c, ...l }) {
-	let u = f(null);
-	return S({
-		containerRef: u,
+function O({ ref: e, renderToken: t, appearance: n, onValidityChange: r, billingAddressRequirement: i = "country", defaultValues: o, requireAchVerification: s = !1, intent: c = "payment", style: l, ...u }) {
+	let d = p(null);
+	return w({
+		containerRef: d,
 		iframeRef: e,
-		mount: i,
+		mount: a,
 		options: {
 			renderToken: t,
 			appearance: n,
-			billingAddressRequirement: a,
-			requireAchVerification: o,
-			intent: s,
+			billingAddressRequirement: i,
+			defaultValues: o,
+			requireAchVerification: s,
+			intent: c,
 			onValidityChange: r
 		},
 		remountDeps: [
 			t,
-			a,
-			s
+			i,
+			c
 		],
 		iframePassthrough: {
-			style: c,
-			...l
+			style: l,
+			...u
 		},
 		updateDeps: [
 			n,
-			a,
+			i,
 			o,
 			s,
+			c,
 			r
 		]
-	}), /* @__PURE__ */ p("div", { ref: u });
+	}), /* @__PURE__ */ m("div", { ref: d });
 }
-function D({ ref: e, renderToken: t, amount: n, merchantName: r, height: i = "48px", buttonProps: a, iframeProps: s, onConfirm: l }) {
-	let u = f(null), d = c({
-		iframeStyle: s?.style,
+function k({ ref: e, renderToken: t, amount: n, merchantName: r, height: i = "48px", buttonProps: a, iframeProps: o, onConfirm: c }) {
+	let u = p(null), d = l({
+		iframeStyle: o?.style,
 		buttonProps: a
 	});
-	return S({
+	return w({
 		containerRef: u,
 		iframeRef: e,
-		mount: o,
+		mount: s,
 		options: {
 			renderToken: t,
 			amount: n,
 			merchantName: r,
 			height: i,
 			buttonProps: a,
-			onConfirm: l
+			onConfirm: c
 		},
 		remountDeps: [t],
-		iframePassthrough: s ?? {},
+		iframePassthrough: o ?? {},
 		updateDeps: [
 			n,
 			r,
 			i,
 			a,
-			l
+			c
 		]
-	}), /* @__PURE__ */ p(w, {
+	}), /* @__PURE__ */ m(E, {
 		height: i,
 		borderRadius: d,
 		containerRef: u
 	});
 }
-function O({ ref: e, renderToken: t, amount: n, merchantName: i, height: a = "48px", buttonProps: o, iframeProps: s, onConfirm: l }) {
-	let u = f(null), d = c({
+function A({ ref: e, renderToken: t, amount: n, merchantName: r, height: a = "48px", buttonProps: o, iframeProps: s, onConfirm: c }) {
+	let u = p(null), d = l({
 		iframeStyle: s?.style,
 		buttonProps: o
 	});
-	return S({
+	return w({
 		containerRef: u,
 		iframeRef: e,
-		mount: r,
+		mount: i,
 		options: {
 			renderToken: t,
 			amount: n,
-			merchantName: i,
+			merchantName: r,
 			height: a,
 			buttonProps: o,
-			onConfirm: l
+			onConfirm: c
 		},
 		remountDeps: [t],
 		iframePassthrough: s ?? {},
 		updateDeps: [
 			n,
-			i,
+			r,
 			a,
 			o,
-			l
+			c
 		]
-	}), /* @__PURE__ */ p(w, {
+	}), /* @__PURE__ */ m(E, {
 		height: a,
 		borderRadius: d,
 		containerRef: u
 	});
 }
 //#endregion
-export { O as AmosApplePayButton, E as AmosBankAccountPaymentMethodForm, T as AmosCreditCardPaymentMethodForm, D as AmosGooglePayButton, _ as confirmPayment, v as confirmSetup, y as resetForm, g as validateForm };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amos.com/react-amos-js",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "main": "dist/index.js",
   "repository": {
     "type": "git",
@@ -48,7 +48,7 @@
     "vite-plugin-dts": "5.0.3"
   },
   "dependencies": {
-    "@amos.com/amos-js": "0.11.4",
+    "@amos.com/amos-js": "0.11.6",
     "@types/googlepay": "0.7.12"
   },
   "peerDependencies": {

package/src/index.tsx

@@ -5,10 +5,12 @@ import {
   type ApplePayButtonElementProps,
   confirmPayment as amosConfirmPayment,
   confirmSetup as amosConfirmSetup,
+  focusField as amosFocusField,
   resetForm as amosResetForm,
   validateForm as amosValidateForm,
   type BillingAddressRequirement,
-  type ConfirmResult,
+  type ConfirmPaymentResult,
+  type ConfirmSetupResult,
   type CreditCardAdditionalFields,
   ensureSkeletonStyles,
   type GooglePayButtonElementProps,
@@ -16,6 +18,8 @@ import {
   mountAmosBankAccountPaymentMethodForm,
   mountAmosCreditCardPaymentMethodForm,
   mountAmosGooglePayButton,
+  type PaymentMethodFormDefaultValues,
+  type PaymentMethodFormField,
   resolveWalletButtonSkeletonBorderRadius,
 } from "@amos.com/amos-js";
 import type { components } from "@amos.com/node";
@@ -63,13 +67,19 @@ export function validateForm({
 export function confirmPayment({
   iframeRef,
   token,
+  defaultValues,
 }: {
   iframeRef: IframeRef;
+  defaultValues?: PaymentMethodFormDefaultValues;
 } & Pick<
   components["schemas"]["EmbedToken"],
   "token"
->): Promise<ConfirmResult> {
-  return amosConfirmPayment({ iframe: resolveIframe(iframeRef), token });
+>): Promise<ConfirmPaymentResult> {
+  return amosConfirmPayment({
+    iframe: resolveIframe(iframeRef),
+    token,
+    defaultValues,
+  });
 }
 
 /**
@@ -82,13 +92,19 @@ export function confirmPayment({
 export function confirmSetup({
   iframeRef,
   token,
+  defaultValues,
 }: {
   iframeRef: IframeRef;
+  defaultValues?: PaymentMethodFormDefaultValues;
 } & Pick<
   components["schemas"]["EmbedToken"],
   "token"
->): Promise<ConfirmResult> {
-  return amosConfirmSetup({ iframe: resolveIframe(iframeRef), token });
+>): Promise<ConfirmSetupResult> {
+  return amosConfirmSetup({
+    iframe: resolveIframe(iframeRef),
+    token,
+    defaultValues,
+  });
 }
 
 /**
@@ -99,6 +115,21 @@ export function resetForm({ iframeRef }: { iframeRef: IframeRef }): void {
   amosResetForm({ iframe: resolveIframe(iframeRef) });
 }
 
+/**
+ * Focus a named control inside the embedded card/bank iframe. No-op if
+ * the field is not rendered, or while Plaid Embedded Institution Search
+ * is showing. Call from a click or keydown handler.
+ */
+export function focusField({
+  iframeRef,
+  field,
+}: {
+  iframeRef: IframeRef;
+  field: PaymentMethodFormField;
+}): void {
+  amosFocusField({ iframe: resolveIframe(iframeRef), field });
+}
+
 type ForwardedIframeRef = Ref<HTMLIFrameElement> | undefined;
 
 function setForwardedRef(
@@ -275,6 +306,12 @@ type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
   }) => void;
   additionalFields?: CreditCardAdditionalFields;
   billingAddressRequirement?: BillingAddressRequirement;
+  /**
+   * Seed cardholder name and billing address. Provided keys overwrite
+   * matching fields, including ones the customer already edited. Values
+   * are sent on confirm even when those inputs are hidden.
+   */
+  defaultValues?: PaymentMethodFormDefaultValues;
 };
 
 export function AmosCreditCardPaymentMethodForm({
@@ -285,6 +322,7 @@ export function AmosCreditCardPaymentMethodForm({
   onCardBrandChanged,
   additionalFields = { cardholderName: false },
   billingAddressRequirement = "country",
+  defaultValues,
   style,
   ...rest
 }: AmosCreditCardPaymentMethodFormProps) {
@@ -299,6 +337,7 @@ export function AmosCreditCardPaymentMethodForm({
       appearance,
       additionalFields,
       billingAddressRequirement,
+      defaultValues,
       onValidityChange,
       onCardBrandChanged,
     },
@@ -312,6 +351,7 @@ export function AmosCreditCardPaymentMethodForm({
       appearance,
       additionalFields,
       billingAddressRequirement,
+      defaultValues,
       onValidityChange,
       onCardBrandChanged,
     ],
@@ -330,6 +370,12 @@ type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
    */
   onValidityChange?: (event: { isValid: boolean }) => void;
   billingAddressRequirement?: BillingAddressRequirement;
+  /**
+   * Seed account holder name and billing address. Provided keys
+   * overwrite matching fields, including ones the customer already
+   * edited.
+   */
+  defaultValues?: PaymentMethodFormDefaultValues;
   /**
    * When true, hide the routing/account iframe and mount Plaid Embedded
    * Institution Search in the parent. Ignored when `intent` is `"setup"`
@@ -355,6 +401,7 @@ export function AmosBankAccountPaymentMethodForm({
   appearance,
   onValidityChange,
   billingAddressRequirement = "country",
+  defaultValues,
   requireAchVerification = false,
   intent = "payment",
   style,
@@ -370,6 +417,7 @@ export function AmosBankAccountPaymentMethodForm({
       renderToken,
       appearance,
       billingAddressRequirement,
+      defaultValues,
       requireAchVerification,
       intent,
       onValidityChange,
@@ -379,6 +427,7 @@ export function AmosBankAccountPaymentMethodForm({
     updateDeps: [
       appearance,
       billingAddressRequirement,
+      defaultValues,
       requireAchVerification,
       intent,
       onValidityChange,
@@ -423,8 +472,8 @@ type AmosGooglePayButtonProps = {
   }: {
     paymentIntentCreateAttributes: components["schemas"]["CreatePaymentIntentInput"];
     customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
-    confirmPayment: (token: string) => Promise<ConfirmResult>;
-  }) => Promise<ConfirmResult>;
+    confirmPayment: (token: string) => Promise<ConfirmPaymentResult>;
+  }) => Promise<ConfirmPaymentResult>;
 };
 
 /**
@@ -509,8 +558,8 @@ type AmosApplePayButtonProps = {
   }: {
     paymentIntentCreateAttributes: components["schemas"]["CreatePaymentIntentInput"];
     customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
-    confirmPayment: (token: string) => Promise<ConfirmResult>;
-  }) => Promise<ConfirmResult>;
+    confirmPayment: (token: string) => Promise<ConfirmPaymentResult>;
+  }) => Promise<ConfirmPaymentResult>;
 };
 
 /**