@amos.com/react-amos-js 0.9.4 → 0.9.6

package/README.md

@@ -7,16 +7,18 @@ It is a thin wrapper around [`@amos.com/amos-js`](../amos-js) that adapts the fr
 ## Installation
 
 ```bash
-npm install @amos.com/react-amos-js
+npm install @amos.com/react-amos-js @amos.com/node
 ```
 
+`@amos.com/node` is a **peer dependency** (requires `>=0.1.37`). Install it in your app for OpenAPI schema types (for example `components["schemas"]["CreatePaymentIntentInput"]`) used in the examples below, and for your server-side Amos API client. React (`^17`, `^18`, or `^19`) is also a peer dependency.
+
 ## What it gives you
 
 - React components for the iframe payment method forms: `AmosCreditCardPaymentMethodForm`, `AmosBankAccountPaymentMethodForm`, `AmosGooglePayButton`, `AmosApplePayButton`.
-- React-flavoured iframe message helpers that accept a React `ref`: `validateForm({ iframeRef })`, `confirmPaymentIntent({ iframeRef, token })`, `confirmSetupIntent({ iframeRef, token })`.
-- Re-exports of the `@amos.com/amos-js` helpers and types that come up in client code: `createMessage`, `decodeJwt`, `getEmbedOrigin`, `formatGooglePayPaymentData`, `ConfirmationResult`, `ConfirmationIncompleteReason`, `FormattedGooglePayPaymentData`, `Appearance`, `Message`, etc.
+- React-flavoured iframe message helpers that accept a React `ref`: `validateForm({ iframeRef })`, `confirmPaymentIntent({ iframeRef, token })`, `confirmSetupIntent({ 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`, `ConfirmationResult`, `ConfirmationIncompleteReason`, `FormattedGooglePayPaymentData`, `Appearance`, `Message`, etc.
 
-> **Note:** A server-side SDK (for example `@amos.com/node`) must be used alongside `@amos.com/react-amos-js` for end-to-end payment processing. `@amos.com/react-amos-js` is the client-side half.
+> **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.
 
 ## Requirements
 
@@ -381,6 +383,16 @@ Confirms a setup intent in the embedded iframe flow. Use this when saving a paym
 
 **Returns:** `void`
 
+### `resetForm({ iframeRef })`
+
+Clears all field values and API errors in the embedded card/bank iframe form. Call after `onResult` when the customer wants to try again (for example, after a successful payment when starting a new one).
+
+**Parameters:**
+
+- `iframeRef` (`React.RefObject<HTMLIFrameElement | null> | undefined`, required)
+
+**Returns:** `void`
+
 ### `AmosCreditCardPaymentMethodForm`
 
 Renders the secure credit card iframe form.
@@ -454,7 +466,7 @@ Re-exports of the same advanced helpers exposed by `@amos.com/amos-js`. Most int
 
 ## 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`, `confirmPaymentIntent`, or `confirmSetupIntent`. The component forwards the ref to the inner iframe.
+- **`ref` / `iframeRef`**: for card and bank forms, pass `ref={iframeRef}` to the form component. The same `iframeRef` must be used when calling `validateForm`, `confirmPaymentIntent`, `confirmSetupIntent`, or `resetForm`. The component forwards the ref to the inner iframe.
 - **`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` and `AmosApplePayButton`, `amount` is a string (e.g. `"5000"` for $50.00). For `components["schemas"]["CreatePaymentIntentInput"]` on the server, `amount` is a number in cents (e.g. `5000`).

package/dist/index.d.ts

@@ -33,6 +33,13 @@ export declare function confirmPaymentIntent({ iframeRef, token, }: {
 export declare function confirmSetupIntent({ iframeRef, token, }: {
     iframeRef: IframeRef;
 } & Pick<components["schemas"]["EmbedToken"], "token">): void;
+/**
+ * Clear all field values and API errors in the embedded card/bank iframe
+ * form. Call after `onResult` when the customer wants to try again.
+ */
+export declare function resetForm({ iframeRef }: {
+    iframeRef: IframeRef;
+}): void;
 type IframePassthroughProps = Omit<ComponentProps<"iframe">, "src" | "title" | "name" | "role" | "allow">;
 type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
     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(e,t){typeof e==`function`?e(t):e&&(e.current=t)}function c(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 l({containerRef:e,iframeRef:n,mount:r,options:i,remountDeps:a,iframePassthrough:o,updateDeps:l}){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,s(n,a.iframe),c(a.iframe,o),()=>{a.destroy(),u.current=null,s(n,null)}},[...a]),(0,t.useEffect)(()=>{u.current?.update(i)},[...l]),(0,t.useEffect)(()=>{let e=u.current?.iframe;e&&c(e,o)})}function u({ref:r,renderToken:i,appearance:a,onResult:o,additionalFields:s={cardholderName:!1},billingAddressRequirement:c=`country`,style:u,...d}){let f=(0,t.useRef)(null);return l({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:u,...d},updateDeps:[a,s,c,o]}),(0,n.jsx)(`div`,{ref:f})}function d({ref:r,renderToken:i,appearance:a,onResult:o,billingAddressRequirement:s=`country`,style:c,...u}){let d=(0,t.useRef)(null);return l({containerRef:d,iframeRef:r,mount:e.mountAmosBankAccountPaymentMethodForm,options:{renderToken:i,appearance:a,billingAddressRequirement:s,onResult:o},remountDeps:[i,s],iframePassthrough:{style:c,...u},updateDeps:[a,s,o]}),(0,n.jsx)(`div`,{ref:d})}function f({ref:r,renderToken:i,amount:a,merchantName:o,appearance:s,onInitiatePaymentIntentRequest:c,onResult:u,style:d,...f}){let p=(0,t.useRef)(null);return l({containerRef:p,iframeRef:r,mount:e.mountAmosGooglePayButton,options:{renderToken:i,amount:a,merchantName:o,appearance:s,onInitiatePaymentIntentRequest:c,onResult:u},remountDeps:[i],iframePassthrough:{style:d,...f},updateDeps:[a,o,s,c,u]}),(0,n.jsx)(`div`,{ref:p})}function p({ref:r,renderToken:i,amount:a,merchantName:o,appearance:s,onInitiatePaymentIntentRequest:c,onResult:u,style:d,...f}){let p=(0,t.useRef)(null);return l({containerRef:p,iframeRef:r,mount:e.mountAmosApplePayButton,options:{renderToken:i,amount:a,merchantName:o,appearance:s,onInitiatePaymentIntentRequest:c,onResult:u},remountDeps:[i],iframePassthrough:{style:d,...f},updateDeps:[a,o,s,c,u]}),(0,n.jsx)(`div`,{ref:p})}exports.AmosApplePayButton=p,exports.AmosBankAccountPaymentMethodForm=d,exports.AmosCreditCardPaymentMethodForm=u,exports.AmosGooglePayButton=f,exports.confirmPaymentIntent=a,exports.confirmSetupIntent=o,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,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,style:d,...f}){let p=(0,t.useRef)(null);return u({containerRef:p,iframeRef:r,mount:e.mountAmosGooglePayButton,options:{renderToken:i,amount:a,merchantName:o,appearance:s,onInitiatePaymentIntentRequest:c,onResult:l},remountDeps:[i],iframePassthrough:{style:d,...f},updateDeps:[a,o,s,c,l]}),(0,n.jsx)(`div`,{ref:p})}function m({ref:r,renderToken:i,amount:a,merchantName:o,appearance:s,onInitiatePaymentIntentRequest:c,onResult:l,style:d,...f}){let p=(0,t.useRef)(null);return u({containerRef:p,iframeRef:r,mount:e.mountAmosApplePayButton,options:{renderToken:i,amount:a,merchantName:o,appearance:s,onInitiatePaymentIntentRequest:c,onResult:l},remountDeps:[i],iframePassthrough:{style:d,...f},updateDeps:[a,o,s,c,l]}),(0,n.jsx)(`div`,{ref:p})}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

@@ -1,52 +1,55 @@
-import { confirmPaymentIntent as e, confirmSetupIntent as t, mountAmosApplePayButton as n, mountAmosBankAccountPaymentMethodForm as r, mountAmosCreditCardPaymentMethodForm as i, mountAmosGooglePayButton as a, validateForm as o } from "@amos.com/amos-js";
-import { useEffect as s, useRef as c } from "react";
-import { jsx as l } from "react/jsx-runtime";
+import { confirmPaymentIntent as e, confirmSetupIntent as t, mountAmosApplePayButton as n, mountAmosBankAccountPaymentMethodForm as r, mountAmosCreditCardPaymentMethodForm as i, mountAmosGooglePayButton as a, resetForm as o, validateForm as s } from "@amos.com/amos-js";
+import { useEffect as c, useRef as l } from "react";
+import { jsx as u } from "react/jsx-runtime";
 export * from "@amos.com/amos-js";
 //#region src/index.tsx
-function u(e) {
+function d(e) {
 	return e ? e.current ?? null : null;
 }
-function d({ iframeRef: e }) {
-	return o({ iframe: u(e) });
+function f({ iframeRef: e }) {
+	return s({ iframe: d(e) });
 }
-function f({ iframeRef: t, token: n }) {
+function p({ iframeRef: t, token: n }) {
 	e({
-		iframe: u(t),
+		iframe: d(t),
 		token: n
 	});
 }
-function p({ iframeRef: e, token: n }) {
+function m({ iframeRef: e, token: n }) {
 	t({
-		iframe: u(e),
+		iframe: d(e),
 		token: n
 	});
 }
-function m(e, t) {
+function h({ iframeRef: e }) {
+	o({ iframe: d(e) });
+}
+function g(e, t) {
 	typeof e == "function" ? e(t) : e && (e.current = t);
 }
-function h(e, { style: t, className: n, id: r, ...i }) {
+function _(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 g({ containerRef: e, iframeRef: t, mount: n, options: r, remountDeps: i, iframePassthrough: a, updateDeps: o }) {
-	let l = c(null);
-	s(() => {
+function v({ containerRef: e, iframeRef: t, mount: n, options: r, remountDeps: i, iframePassthrough: a, updateDeps: o }) {
+	let s = l(null);
+	c(() => {
 		let i = e.current;
 		if (!i) return;
 		let o = n(i, r);
-		return l.current = o, m(t, o.iframe), h(o.iframe, a), () => {
-			o.destroy(), l.current = null, m(t, null);
+		return s.current = o, g(t, o.iframe), _(o.iframe, a), () => {
+			o.destroy(), s.current = null, g(t, null);
 		};
-	}, [...i]), s(() => {
-		l.current?.update(r);
-	}, [...o]), s(() => {
-		let e = l.current?.iframe;
-		e && h(e, a);
+	}, [...i]), c(() => {
+		s.current?.update(r);
+	}, [...o]), c(() => {
+		let e = s.current?.iframe;
+		e && _(e, a);
 	});
 }
-function _({ ref: e, renderToken: t, appearance: n, onResult: r, additionalFields: a = { cardholderName: !1 }, billingAddressRequirement: o = "country", style: s, ...u }) {
-	let d = c(null);
-	return g({
+function y({ ref: e, renderToken: t, appearance: n, onResult: r, additionalFields: a = { cardholderName: !1 }, billingAddressRequirement: o = "country", style: s, ...c }) {
+	let d = l(null);
+	return v({
 		containerRef: d,
 		iframeRef: e,
 		mount: i,
@@ -64,7 +67,7 @@ function _({ ref: e, renderToken: t, appearance: n, onResult: r, additionalField
 		],
 		iframePassthrough: {
 			style: s,
-			...u
+			...c
 		},
 		updateDeps: [
 			n,
@@ -72,12 +75,12 @@ function _({ ref: e, renderToken: t, appearance: n, onResult: r, additionalField
 			o,
 			r
 		]
-	}), /* @__PURE__ */ l("div", { ref: d });
+	}), /* @__PURE__ */ u("div", { ref: d });
 }
-function v({ ref: e, renderToken: t, appearance: n, onResult: i, billingAddressRequirement: a = "country", style: o, ...s }) {
-	let u = c(null);
-	return g({
-		containerRef: u,
+function b({ ref: e, renderToken: t, appearance: n, onResult: i, billingAddressRequirement: a = "country", style: o, ...s }) {
+	let c = l(null);
+	return v({
+		containerRef: c,
 		iframeRef: e,
 		mount: r,
 		options: {
@@ -96,11 +99,11 @@ function v({ ref: e, renderToken: t, appearance: n, onResult: i, billingAddressR
 			a,
 			i
 		]
-	}), /* @__PURE__ */ l("div", { ref: u });
+	}), /* @__PURE__ */ u("div", { ref: c });
 }
-function y({ ref: e, renderToken: t, amount: n, merchantName: r, appearance: i, onInitiatePaymentIntentRequest: o, onResult: s, style: u, ...d }) {
-	let f = c(null);
-	return g({
+function x({ ref: e, renderToken: t, amount: n, merchantName: r, appearance: i, onInitiatePaymentIntentRequest: o, onResult: s, style: c, ...d }) {
+	let f = l(null);
+	return v({
 		containerRef: f,
 		iframeRef: e,
 		mount: a,
@@ -114,7 +117,7 @@ function y({ ref: e, renderToken: t, amount: n, merchantName: r, appearance: i,
 		},
 		remountDeps: [t],
 		iframePassthrough: {
-			style: u,
+			style: c,
 			...d
 		},
 		updateDeps: [
@@ -124,11 +127,11 @@ function y({ ref: e, renderToken: t, amount: n, merchantName: r, appearance: i,
 			o,
 			s
 		]
-	}), /* @__PURE__ */ l("div", { ref: f });
+	}), /* @__PURE__ */ u("div", { ref: f });
 }
-function b({ ref: e, renderToken: t, amount: r, merchantName: i, appearance: a, onInitiatePaymentIntentRequest: o, onResult: s, style: u, ...d }) {
-	let f = c(null);
-	return g({
+function S({ ref: e, renderToken: t, amount: r, merchantName: i, appearance: a, onInitiatePaymentIntentRequest: o, onResult: s, style: c, ...d }) {
+	let f = l(null);
+	return v({
 		containerRef: f,
 		iframeRef: e,
 		mount: n,
@@ -142,7 +145,7 @@ function b({ ref: e, renderToken: t, amount: r, merchantName: i, appearance: a,
 		},
 		remountDeps: [t],
 		iframePassthrough: {
-			style: u,
+			style: c,
 			...d
 		},
 		updateDeps: [
@@ -152,7 +155,7 @@ function b({ ref: e, renderToken: t, amount: r, merchantName: i, appearance: a,
 			o,
 			s
 		]
-	}), /* @__PURE__ */ l("div", { ref: f });
+	}), /* @__PURE__ */ u("div", { ref: f });
 }
 //#endregion
-export { b as AmosApplePayButton, v as AmosBankAccountPaymentMethodForm, _ as AmosCreditCardPaymentMethodForm, y as AmosGooglePayButton, f as confirmPaymentIntent, p as confirmSetupIntent, d as validateForm };
+export { S as AmosApplePayButton, b as AmosBankAccountPaymentMethodForm, y as AmosCreditCardPaymentMethodForm, x as AmosGooglePayButton, p as confirmPaymentIntent, m as confirmSetupIntent, h as resetForm, f as validateForm };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amos.com/react-amos-js",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "main": "dist/index.js",
   "repository": {
     "type": "git",
@@ -37,6 +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",
     "@biomejs/biome": "2.5.7",
     "@changesets/cli": "2.31.1",
     "@types/node": "26.1.2",
@@ -47,11 +48,11 @@
     "vite-plugin-dts": "5.0.3"
   },
   "dependencies": {
-    "@amos.com/amos-js": "0.9.3",
-    "@amos.com/node": "0.1.36",
+    "@amos.com/amos-js": "0.9.7",
     "@types/googlepay": "0.7.11"
   },
   "peerDependencies": {
-    "react": "^17 || ^18 || ^19"
+    "react": "^17 || ^18 || ^19",
+    "@amos.com/node": ">=0.1.39"
   }
 }

package/src/index.tsx

@@ -4,6 +4,7 @@ import {
   type Appearance,
   confirmPaymentIntent as amosConfirmPaymentIntent,
   confirmSetupIntent as amosConfirmSetupIntent,
+  resetForm as amosResetForm,
   validateForm as amosValidateForm,
   type BillingAddressRequirement,
   type ConfirmationResult,
@@ -79,6 +80,14 @@ export function confirmSetupIntent({
   amosConfirmSetupIntent({ iframe: resolveIframe(iframeRef), token });
 }
 
+/**
+ * Clear all field values and API errors in the embedded card/bank iframe
+ * form. Call after `onResult` when the customer wants to try again.
+ */
+export function resetForm({ iframeRef }: { iframeRef: IframeRef }): void {
+  amosResetForm({ iframe: resolveIframe(iframeRef) });
+}
+
 type ForwardedIframeRef = Ref<HTMLIFrameElement> | undefined;
 
 function setForwardedRef(