@amos.com/react-amos-js 0.9.9 → 0.9.11

package/README.md

@@ -39,7 +39,7 @@ The render token configures the iframe's allowed origin(s), allowed payment meth
 The following flow is for credit card and bank account payment method types only.
 
 1. **Set up prerequisites**: create a `renderToken` (safe for client), and keep `apiKey` and `accountId` server-side only.
-2. **Render your checkout UI** with one of the payment method components (e.g. `AmosCreditCardPaymentMethodForm`) along with the required `onResult` prop. The iframe height is auto-managed by the SDK.
+2. **Render your checkout UI** with one of the payment method components (e.g. `AmosCreditCardPaymentMethodForm`) along with the required `onResult` prop. Card and bank forms show a field-shaped skeleton immediately (sized from `appearance`, `additionalFields`, and `billingAddressRequirement`); iframe height is auto-managed.
 3. **User clicks "Pay now" button**: call `validateForm({ iframeRef })`, which returns `Promise<true>` if the embedded form is valid and `Promise<false>` otherwise.
 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.
@@ -172,6 +172,7 @@ import type { components } from "@amos.com/node";
 
 function CheckoutForm() {
   const iframeRef = useRef<HTMLIFrameElement>(null);
+  const [isValid, setIsValid] = useState(false);
   const [isProcessing, setIsProcessing] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
@@ -222,6 +223,7 @@ function CheckoutForm() {
         ref={iframeRef}
         renderToken="the-render-token-that-you-created-on-dashboard.amos.com"
         additionalFields={{ cardholderName: true }}
+        onValidityChange={({ isValid }) => setIsValid(isValid)}
         onResult={(result) => {
           // Unlock UI. Verify settlement on your backend via webhooks.
           if (result.status === "succeeded") {
@@ -234,7 +236,7 @@ function CheckoutForm() {
         }}
       />
       {error ? <p>{error}</p> : null}
-      <button type="submit" disabled={isProcessing}>
+      <button type="submit" disabled={!isValid || isProcessing}>
         {isProcessing ? "Processing..." : "Pay Now"}
       </button>
     </form>
@@ -415,7 +417,7 @@ Clears all field values and API errors in the embedded card/bank iframe form. Ca
 
 ### `AmosCreditCardPaymentMethodForm`
 
-Renders the secure credit card iframe form.
+Renders the secure credit card iframe form. A field-shaped skeleton is shown immediately and replaced by the iframe once appearance is applied.
 
 **Required props:**
 
@@ -428,16 +430,17 @@ Renders the secure credit card iframe form.
 
 - `additionalFields` (`{ cardholderName: boolean }`) — set `additionalFields={{ cardholderName: true }}` to render the cardholder name field in the iframe (`false` by default)
 - `billingAddressRequirement` (`"country" | "full"`, defaults to `"country"`) — how much billing address the iframe collects. `country` collects country / region and, for CA / PR / GB / US, a postal code (labeled ZIP for the United States). `full` shows a full street address form with Smarty autocomplete.
+- `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.
 
 **Also accepts:** standard iframe props (`React.ComponentProps<"iframe">`), minus `src`, `title`, `name`, and `role` (which are controlled by the SDK).
 
 ### `AmosBankAccountPaymentMethodForm`
 
-Renders the secure bank account iframe form.
+Renders the secure bank account iframe form. A field-shaped skeleton is shown immediately and replaced by the iframe once appearance is applied.
 
 **Required props:** same as `AmosCreditCardPaymentMethodForm` — `renderToken`, `onResult`.
 
-**Optional props:** same as `AmosCreditCardPaymentMethodForm` — `appearance`, `billingAddressRequirement`.
+**Optional props:** same as `AmosCreditCardPaymentMethodForm` — `appearance`, `billingAddressRequirement`, `onValidityChange`.
 
 **Also accepts:** standard iframe props.
 
@@ -510,7 +513,7 @@ 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 `ConfirmationResult`, `ConfirmationIncompleteReason`, `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 `ConfirmationResult`, `ConfirmationIncompleteReason`, `PaymentMethodFormValidityChangeEvent`, `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
 

package/dist/index.d.ts

@@ -45,17 +45,31 @@ type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
     renderToken: string;
     appearance?: Appearance;
     onResult: (result: ConfirmationResult) => void;
+    /**
+     * Called when form validity changes. `isValid` is true when all
+     * required fields are present and valid. Does not include PCI data.
+     */
+    onValidityChange?: (event: {
+        isValid: boolean;
+    }) => void;
     additionalFields?: CreditCardAdditionalFields;
     billingAddressRequirement?: BillingAddressRequirement;
 };
-export declare function AmosCreditCardPaymentMethodForm({ ref, renderToken, appearance, onResult, additionalFields, billingAddressRequirement, style, ...rest }: AmosCreditCardPaymentMethodFormProps): import("react").JSX.Element;
+export declare function AmosCreditCardPaymentMethodForm({ ref, renderToken, appearance, onResult, onValidityChange, additionalFields, billingAddressRequirement, style, ...rest }: AmosCreditCardPaymentMethodFormProps): import("react").JSX.Element;
 type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
     renderToken: string;
     appearance?: Appearance;
     onResult: (result: ConfirmationResult) => void;
+    /**
+     * Called when form validity changes. `isValid` is true when all
+     * required fields are present and valid. Does not include PCI data.
+     */
+    onValidityChange?: (event: {
+        isValid: boolean;
+    }) => void;
     billingAddressRequirement?: BillingAddressRequirement;
 };
-export declare function AmosBankAccountPaymentMethodForm({ ref, renderToken, appearance, onResult, billingAddressRequirement, style, ...rest }: AmosBankAccountPaymentMethodFormProps): import("react").JSX.Element;
+export declare function AmosBankAccountPaymentMethodForm({ ref, renderToken, appearance, onResult, onValidityChange, billingAddressRequirement, style, ...rest }: AmosBankAccountPaymentMethodFormProps): import("react").JSX.Element;
 type AmosGooglePayButtonProps = Omit<IframePassthroughProps, "style"> & GooglePayButtonElementProps & {
     renderToken: string;
     amount: 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){return e?e.current??null:null}function i({iframeRef:t}){return(0,e.validateForm)({iframe:r(t)})}function a({iframeRef:t,token:n}){(0,e.confirmPaymentIntent)({iframe:r(t),token:n})}function o({iframeRef:t,token:n}){(0,e.confirmSetupIntent)({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),t!=null&&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.useEffect)(()=>{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)})}function d({ref:r,renderToken:i,appearance:a,onResult:o,additionalFields:s={cardholderName:!1},billingAddressRequirement:c=`country`,style:l,...d}){let f=(0,t.useRef)(null);return u({containerRef:f,iframeRef:r,mount:e.mountAmosCreditCardPaymentMethodForm,options:{renderToken:i,appearance:a,additionalFields:s,billingAddressRequirement:c,onResult:o},remountDeps:[i,s.cardholderName,c],iframePassthrough:{style:l,...d},updateDeps:[a,s,c,o]}),(0,n.jsx)(`div`,{ref:f})}function f({ref:r,renderToken:i,appearance:a,onResult:o,billingAddressRequirement:s=`country`,style:c,...l}){let d=(0,t.useRef)(null);return u({containerRef:d,iframeRef:r,mount:e.mountAmosBankAccountPaymentMethodForm,options:{renderToken:i,appearance:a,billingAddressRequirement:s,onResult:o},remountDeps:[i,s],iframePassthrough:{style:c,...l},updateDeps:[a,s,o]}),(0,n.jsx)(`div`,{ref:d})}function p({ref:r,renderToken:i,amount:a,merchantName:o,appearance:s,onInitiatePaymentIntentRequest:c,onResult:l,buttonType:d,buttonColor:f,buttonRadius:p,buttonSizeMode:m,buttonLocale:h,buttonBorderType:g,style:_,...v}){let y=(0,t.useRef)(null);return u({containerRef:y,iframeRef:r,mount:e.mountAmosGooglePayButton,options:{renderToken:i,amount:a,merchantName:o,appearance:s,onInitiatePaymentIntentRequest:c,onResult:l,buttonType:d,buttonColor:f,buttonRadius:p,buttonSizeMode:m,buttonLocale:h,buttonBorderType:g,style:_},remountDeps:[i],iframePassthrough:{...v},updateDeps:[a,o,s,c,l,d,f,p,m,h,g,_]}),(0,n.jsx)(`div`,{ref:y})}function m({ref:r,renderToken:i,amount:a,merchantName:o,appearance:s,onInitiatePaymentIntentRequest:c,onResult:l,buttonstyle:d,type:f,locale:p,style:m,...h}){let g=(0,t.useRef)(null);return u({containerRef:g,iframeRef:r,mount:e.mountAmosApplePayButton,options:{renderToken:i,amount:a,merchantName:o,appearance:s,onInitiatePaymentIntentRequest:c,onResult:l,buttonstyle:d,type:f,locale:p,style:m},remountDeps:[i],iframePassthrough:{...h},updateDeps:[a,o,s,c,l,d,f,p,m]}),(0,n.jsx)(`div`,{ref:g})}exports.AmosApplePayButton=m,exports.AmosBankAccountPaymentMethodForm=f,exports.AmosCreditCardPaymentMethodForm=d,exports.AmosGooglePayButton=p,exports.confirmPaymentIntent=a,exports.confirmSetupIntent=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}){(0,e.confirmPaymentIntent)({iframe:r(t),token:n})}function o({iframeRef:t,token:n}){(0,e.confirmSetupIntent)({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),t!=null&&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.useEffect)(()=>{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)})}function d({ref:r,renderToken:i,appearance:a,onResult:o,onValidityChange: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,onResult:o,onValidityChange:s},remountDeps:[i,c.cardholderName,l],iframePassthrough:{style:d,...f},updateDeps:[a,c,l,o,s]}),(0,n.jsx)(`div`,{ref:p})}function f({ref:r,renderToken:i,appearance:a,onResult:o,onValidityChange:s,billingAddressRequirement:c=`country`,style:l,...d}){let f=(0,t.useRef)(null);return u({containerRef:f,iframeRef:r,mount:e.mountAmosBankAccountPaymentMethodForm,options:{renderToken:i,appearance:a,billingAddressRequirement:c,onResult:o,onValidityChange:s},remountDeps:[i,c],iframePassthrough:{style:l,...d},updateDeps:[a,c,o,s]}),(0,n.jsx)(`div`,{ref:f})}function p({ref:r,renderToken:i,amount:a,merchantName:o,appearance:s,onInitiatePaymentIntentRequest:c,onResult:l,buttonType:d,buttonColor:f,buttonRadius:p,buttonSizeMode:m,buttonLocale:h,buttonBorderType:g,style:_,...v}){let y=(0,t.useRef)(null);return u({containerRef:y,iframeRef:r,mount:e.mountAmosGooglePayButton,options:{renderToken:i,amount:a,merchantName:o,appearance:s,onInitiatePaymentIntentRequest:c,onResult:l,buttonType:d,buttonColor:f,buttonRadius:p,buttonSizeMode:m,buttonLocale:h,buttonBorderType:g,style:_},remountDeps:[i],iframePassthrough:{...v},updateDeps:[a,o,s,c,l,d,f,p,m,h,g,_]}),(0,n.jsx)(`div`,{ref:y})}function m({ref:r,renderToken:i,amount:a,merchantName:o,appearance:s,onInitiatePaymentIntentRequest:c,onResult:l,buttonstyle:d,type:f,locale:p,style:m,...h}){let g=(0,t.useRef)(null);return u({containerRef:g,iframeRef:r,mount:e.mountAmosApplePayButton,options:{renderToken:i,amount:a,merchantName:o,appearance:s,onInitiatePaymentIntentRequest:c,onResult:l,buttonstyle:d,type:f,locale:p,style:m},remountDeps:[i],iframePassthrough:{...h},updateDeps:[a,o,s,c,l,d,f,p,m]}),(0,n.jsx)(`div`,{ref:g})}exports.AmosApplePayButton=m,exports.AmosBankAccountPaymentMethodForm=f,exports.AmosCreditCardPaymentMethodForm=d,exports.AmosGooglePayButton=p,exports.confirmPaymentIntent=a,exports.confirmSetupIntent=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]}})});

package/dist/index.mjs

@@ -47,59 +47,63 @@ function v({ containerRef: e, iframeRef: t, mount: n, options: r, remountDeps: i
 		e && _(e, a);
 	});
 }
-function y({ ref: e, renderToken: t, appearance: n, onResult: r, additionalFields: a = { cardholderName: !1 }, billingAddressRequirement: o = "country", style: s, ...c }) {
-	let d = l(null);
+function y({ ref: e, renderToken: t, appearance: n, onResult: r, onValidityChange: a, additionalFields: o = { cardholderName: !1 }, billingAddressRequirement: s = "country", style: c, ...d }) {
+	let f = l(null);
 	return v({
-		containerRef: d,
+		containerRef: f,
 		iframeRef: e,
 		mount: i,
 		options: {
 			renderToken: t,
 			appearance: n,
-			additionalFields: a,
-			billingAddressRequirement: o,
-			onResult: r
+			additionalFields: o,
+			billingAddressRequirement: s,
+			onResult: r,
+			onValidityChange: a
 		},
 		remountDeps: [
 			t,
-			a.cardholderName,
-			o
+			o.cardholderName,
+			s
 		],
 		iframePassthrough: {
-			style: s,
-			...c
+			style: c,
+			...d
 		},
 		updateDeps: [
 			n,
-			a,
 			o,
-			r
+			s,
+			r,
+			a
 		]
-	}), /* @__PURE__ */ u("div", { ref: d });
+	}), /* @__PURE__ */ u("div", { ref: f });
 }
-function b({ ref: e, renderToken: t, appearance: n, onResult: i, billingAddressRequirement: a = "country", style: o, ...s }) {
-	let c = l(null);
+function b({ ref: e, renderToken: t, appearance: n, onResult: i, onValidityChange: a, billingAddressRequirement: o = "country", style: s, ...c }) {
+	let d = l(null);
 	return v({
-		containerRef: c,
+		containerRef: d,
 		iframeRef: e,
 		mount: r,
 		options: {
 			renderToken: t,
 			appearance: n,
-			billingAddressRequirement: a,
-			onResult: i
+			billingAddressRequirement: o,
+			onResult: i,
+			onValidityChange: a
 		},
-		remountDeps: [t, a],
+		remountDeps: [t, o],
 		iframePassthrough: {
-			style: o,
-			...s
+			style: s,
+			...c
 		},
 		updateDeps: [
 			n,
-			a,
-			i
+			o,
+			i,
+			a
 		]
-	}), /* @__PURE__ */ u("div", { ref: c });
+	}), /* @__PURE__ */ u("div", { ref: d });
 }
 function x({ ref: e, renderToken: t, amount: n, merchantName: r, appearance: i, onInitiatePaymentIntentRequest: o, onResult: s, buttonType: c, buttonColor: d, buttonRadius: f, buttonSizeMode: p, buttonLocale: m, buttonBorderType: h, style: g, ..._ }) {
 	let y = l(null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amos.com/react-amos-js",
-  "version": "0.9.9",
+  "version": "0.9.11",
   "main": "dist/index.js",
   "repository": {
     "type": "git",
@@ -48,7 +48,7 @@
     "vite-plugin-dts": "5.0.3"
   },
   "dependencies": {
-    "@amos.com/amos-js": "0.9.10",
+    "@amos.com/amos-js": "0.9.12",
     "@types/googlepay": "0.7.11"
   },
   "peerDependencies": {

package/src/index.tsx

@@ -194,6 +194,11 @@ type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
   renderToken: string;
   appearance?: Appearance;
   onResult: (result: ConfirmationResult) => void;
+  /**
+   * Called when form validity changes. `isValid` is true when all
+   * required fields are present and valid. Does not include PCI data.
+   */
+  onValidityChange?: (event: { isValid: boolean }) => void;
   additionalFields?: CreditCardAdditionalFields;
   billingAddressRequirement?: BillingAddressRequirement;
 };
@@ -203,6 +208,7 @@ export function AmosCreditCardPaymentMethodForm({
   renderToken,
   appearance,
   onResult,
+  onValidityChange,
   additionalFields = { cardholderName: false },
   billingAddressRequirement = "country",
   style,
@@ -220,6 +226,7 @@ export function AmosCreditCardPaymentMethodForm({
       additionalFields,
       billingAddressRequirement,
       onResult,
+      onValidityChange,
     },
     remountDeps: [
       renderToken,
@@ -232,6 +239,7 @@ export function AmosCreditCardPaymentMethodForm({
       additionalFields,
       billingAddressRequirement,
       onResult,
+      onValidityChange,
     ],
   });
 
@@ -242,6 +250,11 @@ type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
   renderToken: string;
   appearance?: Appearance;
   onResult: (result: ConfirmationResult) => void;
+  /**
+   * Called when form validity changes. `isValid` is true when all
+   * required fields are present and valid. Does not include PCI data.
+   */
+  onValidityChange?: (event: { isValid: boolean }) => void;
   billingAddressRequirement?: BillingAddressRequirement;
 };
 
@@ -250,6 +263,7 @@ export function AmosBankAccountPaymentMethodForm({
   renderToken,
   appearance,
   onResult,
+  onValidityChange,
   billingAddressRequirement = "country",
   style,
   ...rest
@@ -265,10 +279,16 @@ export function AmosBankAccountPaymentMethodForm({
       appearance,
       billingAddressRequirement,
       onResult,
+      onValidityChange,
     },
     remountDeps: [renderToken, billingAddressRequirement],
     iframePassthrough: { style, ...rest },
-    updateDeps: [appearance, billingAddressRequirement, onResult],
+    updateDeps: [
+      appearance,
+      billingAddressRequirement,
+      onResult,
+      onValidityChange,
+    ],
   });
 
   return <div ref={containerRef} />;