@amos.com/react-amos-js 0.10.0 → 0.10.2

package/README.md

@@ -64,7 +64,7 @@ Setup intents are used to save payment methods for future use (e.g. recurring pa
 - On the client, call `confirmSetupIntent({ iframeRef, token })` instead of `confirmPaymentIntent({ iframeRef, token })`.
 - The same `onResult` callback is used; succeeded setup intents arrive as `{ status: "succeeded", intent: "setup", setupIntent }`.
 
-The same `AmosCreditCardPaymentMethodForm` / `AmosBankAccountPaymentMethodForm` components support both payment intents and setup intents — they are differentiated by which confirmation function you call.
+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 Connect / Plaid is always shown (no merchant ACH threshold lookup).
 
 ## Understanding PCI DSS compliance requirements
 
@@ -495,18 +495,29 @@ Renders the secure bank account iframe form. A field-shaped skeleton is shown im
 
 When the charge meets the merchant’s ACH verification threshold, the SDK hides the routing/account iframe and renders a **Connect bank account** button in the parent page. The button follows the same outline/focus defaults as Amos UI (`--ring`, `--border`, `--radius`, `--input-height`, …): it inherits those CSS variables from the host page when present, and `appearance.themeVariables` overrides them the same way as the iframe. Clicking it asks the iframe to mint a Plaid Link token, then opens [Plaid Link](https://plaid.com/docs/link/web/). 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`, `onResult`.
+**Required props:** same as `AmosCreditCardPaymentMethodForm` — `renderToken`, `onResult` — plus:
 
-**Optional props:** same as `AmosCreditCardPaymentMethodForm` — `appearance`, `billingAddressRequirement`, `onValidityChange` (`isValid` is also true after Plaid Link returns credentials), plus:
+- `amount` (`string`, major-currency decimal, e.g. `"50.00"`, defaults to `"0"`) — same format as Google Pay / Apple Pay. Compared to the threshold the iframe fetches (cents). Pass `"0"` (the default) on open-amount forms until the customer enters a charge — 0 is typically under the threshold, so Connect stays hidden. Pass a new `amount` when the customer changes the charge.
+- `intent` (`"payment" | "setup"`, defaults to `"payment"`) — `"setup"` always shows Connect / Plaid (no merchant ACH threshold lookup), unless the render token disables verification. Use this when saving a bank account for later charges.
 
-- `amount` (`string`, major-currency decimal, e.g. `"50.00"`) — same format as Google Pay / Apple Pay. Compared to the threshold the iframe fetches (cents). Omit to always Connect once a threshold exists (setup-intent save, or when you do not know the charge yet). Pass a new `amount` when the customer changes the charge if small charges should stay on the manual form.
+**Optional props:** same as `AmosCreditCardPaymentMethodForm` — `appearance`, `billingAddressRequirement`, `onValidityChange` (`isValid` is also true after Plaid Link returns credentials).
 
-Compare locally once the iframe posts `ACH_THRESHOLD`: Plaid when the amount (converted to cents) is `>= achThreshold`, or when `amount` is omitted and a threshold is set. No threshold (or `null`) keeps the manual bank form. If `amount` later drops under the threshold, Plaid credentials are dropped and the iframe form is shown again.
+Compare locally once the iframe posts `ACH_THRESHOLD`: Plaid when `requireVerification` is true (setup intents), or when the amount (converted to cents, default `0`) is `>= achThreshold`. No threshold (or `null`) keeps the manual bank form. Render tokens with Plaid verification disabled never require Connect. If `amount` later drops under the threshold, Plaid credentials are dropped and the iframe form is shown again.
 
 ```tsx
 <AmosBankAccountPaymentMethodForm
   renderToken={renderToken}
-  amount="50.00" // omit to always Connect
+  amount="50.00" // defaults to "0" (manual form until the charge meets the threshold)
+  onResult={onResult}
+/>
+```
+
+Setup (always Connect, no merchant lookup):
+
+```tsx
+<AmosBankAccountPaymentMethodForm
+  renderToken={renderToken}
+  intent="setup"
   onResult={onResult}
 />
 ```
@@ -592,7 +603,7 @@ Re-exports of the same advanced helpers exposed by `@amos.com/amos-js`. Most int
 - **`onResult` is not settlement proof**: `onResult` tells you when to stop waiting (e.g. dismiss a spinner). Verify payment or setup success on your backend via webhooks. On `status: "incomplete"`, unlock your UI — the customer can fix fields in the iframe and retry. Use `result.reason` (`"field_errors"` or `"validation_failed"`) to distinguish recoverable states.
 - **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 (`confirmPaymentIntent` vs `confirmSetupIntent`). Handle both payment and setup outcomes via `onResult`.
 - **Amount format**: for `AmosGooglePayButton`, `AmosApplePayButton`, and `AmosBankAccountPaymentMethodForm`, `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 `onInitiatePaymentIntentRequest`), `amount` is a number in cents (e.g. `5000`).
-- **Plaid Link (ACH verification)**: load `cdn.plaid.com` from the **parent** document (see CSP on `AmosBankAccountPaymentMethodForm`). Merchants do not proxy Pay API; the bank iframe fetches the ACH threshold and mints link tokens. Confirm still goes through the bank iframe so Amos can attach `plaid` to the payment method.
+- **Plaid Link (ACH verification)**: load `cdn.plaid.com` from the **parent** document (see CSP on `AmosBankAccountPaymentMethodForm`). Merchants do not proxy Pay API; the bank iframe fetches the ACH threshold for payment intents and mints link tokens. Setup intents skip the merchant lookup and always require Plaid unless the render token disables verification. Confirm still goes through the bank iframe so Amos can attach `plaid` to the payment method.
 - **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 until payment completes, the popup closes, or the user clicks **Cancel payment**. 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

@@ -81,13 +81,27 @@ type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
     /**
      * Charge amount as a major-currency decimal string (e.g. `"50.00"`
      * for $50.00), the same format as Google Pay / Apple Pay. Compared
-     * to the merchant ACH threshold fetched by the iframe. Omit for
-     * setup intents or when the charge is unknown — if a threshold is
-     * set, Plaid is required.
+     * to the merchant ACH threshold fetched by the iframe. Defaults to
+     * `"0"`, which is typically under the threshold so Connect / Plaid
+     * stays hidden until the host passes a real charge.
+     *
+     * Ignored when {@link AmosBankAccountPaymentMethodFormProps.intent} is
+     * `"setup"`.
+     *
+     * @default "0"
      */
     amount?: string;
+    /**
+     * `"setup"` saves a bank account for later charges and always shows
+     * Connect / Plaid (no merchant threshold lookup). `"payment"`
+     * compares {@link AmosBankAccountPaymentMethodFormProps.amount} to the
+     * merchant ACH threshold.
+     *
+     * @default "payment"
+     */
+    intent?: "payment" | "setup";
 };
-export declare function AmosBankAccountPaymentMethodForm({ ref, renderToken, appearance, onResult, onValidityChange, billingAddressRequirement, amount, style, ...rest }: AmosBankAccountPaymentMethodFormProps): import("react").JSX.Element;
+export declare function AmosBankAccountPaymentMethodForm({ ref, renderToken, appearance, onResult, onValidityChange, billingAddressRequirement, amount, 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){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),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,onResult:o,onValidityChange:s,onCardBrandChanged:c,additionalFields:l={cardholderName:!1},billingAddressRequirement:d=`country`,style:f,...p}){let m=(0,t.useRef)(null);return u({containerRef:m,iframeRef:r,mount:e.mountAmosCreditCardPaymentMethodForm,options:{renderToken:i,appearance:a,additionalFields:l,billingAddressRequirement:d,onResult:o,onValidityChange:s,onCardBrandChanged:c},remountDeps:[i,l.cardholderName,d],iframePassthrough:{style:f,...p},updateDeps:[a,l,d,o,s,c]}),(0,n.jsx)(`div`,{ref:m})}function m({ref:r,renderToken:i,appearance:a,onResult:o,onValidityChange:s,billingAddressRequirement:c=`country`,amount:l,style:d,...f}){let p=(0,t.useRef)(null);return u({containerRef:p,iframeRef:r,mount:e.mountAmosBankAccountPaymentMethodForm,options:{renderToken:i,appearance:a,billingAddressRequirement:c,amount:l,onResult:o,onValidityChange:s},remountDeps:[i,c],iframePassthrough:{style:d,...f},updateDeps:[a,c,l,o,s]}),(0,n.jsx)(`div`,{ref:p})}function h({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onInitiatePaymentIntentRequest:d,onResult:p}){let m=(0,t.useRef)(null),h=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return u({containerRef:m,iframeRef:r,mount:e.mountAmosGooglePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,onInitiatePaymentIntentRequest:d,onResult:p},remountDeps:[i],iframePassthrough:l??{},updateDeps:[a,o,s,c,d,p]}),(0,n.jsx)(f,{height:s,borderRadius:h,containerRef:m})}function g({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onInitiatePaymentIntentRequest:d,onResult:p}){let m=(0,t.useRef)(null),h=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return u({containerRef:m,iframeRef:r,mount:e.mountAmosApplePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,onInitiatePaymentIntentRequest:d,onResult:p},remountDeps:[i],iframePassthrough:l??{},updateDeps:[a,o,s,c,d,p]}),(0,n.jsx)(f,{height:s,borderRadius:h,containerRef:m})}exports.AmosApplePayButton=g,exports.AmosBankAccountPaymentMethodForm=m,exports.AmosCreditCardPaymentMethodForm=p,exports.AmosGooglePayButton=h,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),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,onResult:o,onValidityChange:s,onCardBrandChanged:c,additionalFields:l={cardholderName:!1},billingAddressRequirement:d=`country`,style:f,...p}){let m=(0,t.useRef)(null);return u({containerRef:m,iframeRef:r,mount:e.mountAmosCreditCardPaymentMethodForm,options:{renderToken:i,appearance:a,additionalFields:l,billingAddressRequirement:d,onResult:o,onValidityChange:s,onCardBrandChanged:c},remountDeps:[i,l.cardholderName,d],iframePassthrough:{style:f,...p},updateDeps:[a,l,d,o,s,c]}),(0,n.jsx)(`div`,{ref:m})}function m({ref:r,renderToken:i,appearance:a,onResult:o,onValidityChange:s,billingAddressRequirement:c=`country`,amount:l=`0`,intent:d=`payment`,style:f,...p}){let m=(0,t.useRef)(null);return u({containerRef:m,iframeRef:r,mount:e.mountAmosBankAccountPaymentMethodForm,options:{renderToken:i,appearance:a,billingAddressRequirement:c,amount:l,intent:d,onResult:o,onValidityChange:s},remountDeps:[i,c,d],iframePassthrough:{style:f,...p},updateDeps:[a,c,l,d,o,s]}),(0,n.jsx)(`div`,{ref:m})}function h({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onInitiatePaymentIntentRequest:d,onResult:p}){let m=(0,t.useRef)(null),h=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return u({containerRef:m,iframeRef:r,mount:e.mountAmosGooglePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,onInitiatePaymentIntentRequest:d,onResult:p},remountDeps:[i],iframePassthrough:l??{},updateDeps:[a,o,s,c,d,p]}),(0,n.jsx)(f,{height:s,borderRadius:h,containerRef:m})}function g({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onInitiatePaymentIntentRequest:d,onResult:p}){let m=(0,t.useRef)(null),h=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return u({containerRef:m,iframeRef:r,mount:e.mountAmosApplePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,onInitiatePaymentIntentRequest:d,onResult:p},remountDeps:[i],iframePassthrough:l??{},updateDeps:[a,o,s,c,d,p]}),(0,n.jsx)(f,{height:s,borderRadius:h,containerRef:m})}exports.AmosApplePayButton=g,exports.AmosBankAccountPaymentMethodForm=m,exports.AmosCreditCardPaymentMethodForm=p,exports.AmosGooglePayButton=h,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

@@ -118,10 +118,10 @@ function T({ ref: e, renderToken: t, appearance: n, onResult: r, onValidityChang
 		]
 	}), /* @__PURE__ */ p("div", { ref: d });
 }
-function E({ ref: e, renderToken: t, appearance: n, onResult: r, onValidityChange: a, billingAddressRequirement: o = "country", amount: s, style: c, ...l }) {
-	let u = f(null);
+function E({ ref: e, renderToken: t, appearance: n, onResult: r, onValidityChange: a, billingAddressRequirement: o = "country", amount: s = "0", intent: c = "payment", style: l, ...u }) {
+	let d = f(null);
 	return S({
-		containerRef: u,
+		containerRef: d,
 		iframeRef: e,
 		mount: i,
 		options: {
@@ -129,22 +129,28 @@ function E({ ref: e, renderToken: t, appearance: n, onResult: r, onValidityChang
 			appearance: n,
 			billingAddressRequirement: o,
 			amount: s,
+			intent: c,
 			onResult: r,
 			onValidityChange: a
 		},
-		remountDeps: [t, o],
+		remountDeps: [
+			t,
+			o,
+			c
+		],
 		iframePassthrough: {
-			style: c,
-			...l
+			style: l,
+			...u
 		},
 		updateDeps: [
 			n,
 			o,
 			s,
+			c,
 			r,
 			a
 		]
-	}), /* @__PURE__ */ p("div", { ref: u });
+	}), /* @__PURE__ */ p("div", { ref: d });
 }
 function D({ ref: e, renderToken: t, amount: n, merchantName: r, height: i = "48px", buttonProps: a, iframeProps: s, onInitiatePaymentIntentRequest: l, onResult: u }) {
 	let d = f(null), m = c({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amos.com/react-amos-js",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "main": "dist/index.js",
   "repository": {
     "type": "git",
@@ -37,7 +37,7 @@
   "license": "MIT",
   "description": "React SDK for embedding Amos payment methods via iframes. Wraps @amos.com/amos-js.",
   "devDependencies": {
-    "@amos.com/node": "0.1.39",
+    "@amos.com/node": "0.1.50",
     "@biomejs/biome": "2.5.7",
     "@changesets/cli": "2.31.1",
     "@types/node": "26.1.2",
@@ -48,11 +48,11 @@
     "vite-plugin-dts": "5.0.3"
   },
   "dependencies": {
-    "@amos.com/amos-js": "0.10.0",
+    "@amos.com/amos-js": "0.10.2",
     "@types/googlepay": "0.7.11"
   },
   "peerDependencies": {
     "react": "^17 || ^18 || ^19",
-    "@amos.com/node": ">=0.1.39"
+    "@amos.com/node": ">=0.1.50"
   }
 }

package/src/index.tsx

@@ -332,11 +332,25 @@ type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
   /**
    * Charge amount as a major-currency decimal string (e.g. `"50.00"`
    * for $50.00), the same format as Google Pay / Apple Pay. Compared
-   * to the merchant ACH threshold fetched by the iframe. Omit for
-   * setup intents or when the charge is unknown — if a threshold is
-   * set, Plaid is required.
+   * to the merchant ACH threshold fetched by the iframe. Defaults to
+   * `"0"`, which is typically under the threshold so Connect / Plaid
+   * stays hidden until the host passes a real charge.
+   *
+   * Ignored when {@link AmosBankAccountPaymentMethodFormProps.intent} is
+   * `"setup"`.
+   *
+   * @default "0"
    */
   amount?: string;
+  /**
+   * `"setup"` saves a bank account for later charges and always shows
+   * Connect / Plaid (no merchant threshold lookup). `"payment"`
+   * compares {@link AmosBankAccountPaymentMethodFormProps.amount} to the
+   * merchant ACH threshold.
+   *
+   * @default "payment"
+   */
+  intent?: "payment" | "setup";
 };
 
 export function AmosBankAccountPaymentMethodForm({
@@ -346,7 +360,8 @@ export function AmosBankAccountPaymentMethodForm({
   onResult,
   onValidityChange,
   billingAddressRequirement = "country",
-  amount,
+  amount = "0",
+  intent = "payment",
   style,
   ...rest
 }: AmosBankAccountPaymentMethodFormProps) {
@@ -361,15 +376,17 @@ export function AmosBankAccountPaymentMethodForm({
       appearance,
       billingAddressRequirement,
       amount,
+      intent,
       onResult,
       onValidityChange,
     },
-    remountDeps: [renderToken, billingAddressRequirement],
+    remountDeps: [renderToken, billingAddressRequirement, intent],
     iframePassthrough: { style, ...rest },
     updateDeps: [
       appearance,
       billingAddressRequirement,
       amount,
+      intent,
       onResult,
       onValidityChange,
     ],