@amos.com/amos-js 0.9.16 → 0.9.18

package/src/mount.ts

@@ -7,7 +7,11 @@ import {
 } from "./apple-pay";
 import {
   createPaymentMethodFormSkeleton,
+  createWalletButtonSkeleton,
   type PaymentMethodFormSkeletonOptions,
+  resolveWalletButtonSkeletonBorderRadius,
+  type WalletButtonSkeleton,
+  type WalletButtonSkeletonOptions,
 } from "./form-skeleton";
 import {
   attachGooglePayButtonListeners,
@@ -27,6 +31,7 @@ import {
   type PaymentMethodFormController,
   type PaymentMethodFormListenerOptions,
 } from "./payment-method-form";
+import { attachPlaidBankUi } from "./plaid-bank-ui";
 
 type Container = HTMLElement | string;
 
@@ -59,6 +64,19 @@ const WALLET_IFRAME_STYLE: Partial<CSSStyleDeclaration> = {
   border: "0",
 };
 
+const WALLET_SKELETON_IFRAME_STYLE: Partial<CSSStyleDeclaration> = {
+  position: "absolute",
+  top: "0",
+  left: "0",
+  width: "100%",
+  height: "100%",
+  margin: "0",
+  opacity: "0",
+  // Do not interpolate opacity while the skeleton is showing.
+  transition: "none",
+  pointerEvents: "none",
+};
+
 const SKELETON_IFRAME_STYLE: Partial<CSSStyleDeclaration> = {
   position: "absolute",
   top: "0",
@@ -231,6 +249,141 @@ function mountPaymentMethodFormWithSkeleton({
   };
 }
 
+type WalletListenerOptions = {
+  height?: string;
+  onHeightChange?: (height: string) => void;
+  onAppearanceReady?: () => void;
+  buttonProps?: {
+    buttonRadius?: number;
+    style?: Record<string, string | number | undefined>;
+  };
+};
+
+type WalletListenerController<TOptions> = {
+  update: (patch: Partial<TOptions>) => void;
+  destroy: () => void;
+};
+
+function mountWalletButtonWithSkeleton<TOptions extends WalletListenerOptions>({
+  host,
+  iframe,
+  listenerOptions,
+  iframeStyle,
+  attachListeners,
+}: {
+  host: HTMLElement;
+  iframe: HTMLIFrameElement;
+  listenerOptions: TOptions;
+  iframeStyle?: Partial<CSSStyleDeclaration>;
+  attachListeners: (
+    iframe: HTMLIFrameElement,
+    options: TOptions,
+  ) => WalletListenerController<TOptions>;
+}): {
+  iframe: HTMLIFrameElement;
+  update: (patch: Partial<TOptions>) => void;
+  destroy: () => void;
+} {
+  const initialHeight = listenerOptions.height ?? "48px";
+  let skeletonOptions: WalletButtonSkeletonOptions = {
+    height: initialHeight,
+    borderRadius: resolveWalletButtonSkeletonBorderRadius({
+      iframeStyle,
+      buttonProps: listenerOptions.buttonProps,
+    }),
+  };
+  const skeleton: WalletButtonSkeleton =
+    createWalletButtonSkeleton(skeletonOptions);
+
+  const wrapper = document.createElement("div");
+  wrapper.style.position = "relative";
+  wrapper.style.width = "100%";
+  wrapper.style.height = skeletonOptions.height;
+  wrapper.style.overflow = "hidden";
+  wrapper.setAttribute("aria-busy", "true");
+
+  Object.assign(iframe.style, WALLET_SKELETON_IFRAME_STYLE);
+  iframe.style.height = "100%";
+
+  wrapper.append(skeleton.element, iframe);
+  host.appendChild(wrapper);
+
+  let revealed = false;
+  let appearanceReady = false;
+  let fallbackRevealTimer: ReturnType<typeof setTimeout> | undefined;
+  let currentOptions = listenerOptions;
+
+  function reveal(): void {
+    if (revealed) {
+      return;
+    }
+    revealed = true;
+    if (fallbackRevealTimer !== undefined) {
+      clearTimeout(fallbackRevealTimer);
+      fallbackRevealTimer = undefined;
+    }
+
+    iframe.style.opacity = "1";
+    iframe.style.pointerEvents = "";
+    skeleton.element.remove();
+    wrapper.removeAttribute("aria-busy");
+  }
+
+  function tryReveal(): void {
+    if (revealed || !appearanceReady) {
+      return;
+    }
+    reveal();
+  }
+
+  const controller = attachListeners(iframe, {
+    ...listenerOptions,
+    onHeightChange: (height) => {
+      currentOptions.onHeightChange?.(height);
+    },
+    onAppearanceReady: () => {
+      appearanceReady = true;
+      tryReveal();
+      currentOptions.onAppearanceReady?.();
+    },
+  } as TOptions);
+
+  fallbackRevealTimer = setTimeout(() => {
+    reveal();
+  }, 1500);
+
+  return {
+    iframe,
+    update(patch) {
+      currentOptions = { ...currentOptions, ...patch };
+      // Keep the wrapped reveal listeners. Forwarding these would replace
+      // them and leave the iframe at opacity 0.
+      const rest = { ...patch };
+      delete rest.onAppearanceReady;
+      delete rest.onHeightChange;
+      controller.update(rest);
+      skeletonOptions = {
+        height: currentOptions.height ?? skeletonOptions.height,
+        borderRadius: resolveWalletButtonSkeletonBorderRadius({
+          iframeStyle,
+          buttonProps: currentOptions.buttonProps,
+        }),
+      };
+      wrapper.style.height = skeletonOptions.height;
+      if (!revealed) {
+        skeleton.update(skeletonOptions);
+      }
+    },
+    destroy() {
+      if (fallbackRevealTimer !== undefined) {
+        clearTimeout(fallbackRevealTimer);
+      }
+      controller.destroy();
+      wrapper.remove();
+    },
+  };
+}
+
 /**
  * Options accepted by {@link mountAmosCreditCardPaymentMethodForm}.
  */
@@ -273,6 +426,18 @@ export type AmosPaymentMethodFormMountController =
     iframe: HTMLIFrameElement;
   };
 
+/**
+ * Controller returned by {@link mountAmosBankAccountPaymentMethodForm}.
+ * `update()` also accepts `amount` (major-currency decimal string) when
+ * the charge changes.
+ */
+export type AmosBankAccountPaymentMethodFormMountController = Omit<
+  AmosPaymentMethodFormMountController,
+  "update"
+> & {
+  update: (patch: Partial<AmosBankAccountPaymentMethodFormOptions>) => void;
+};
+
 /**
  * Mount the secure credit-card payment method form into a container
  * element. Returns a controller exposing the underlying iframe, an
@@ -342,6 +507,14 @@ export type AmosBankAccountPaymentMethodFormOptions =
      * @default "country"
      */
     billingAddressRequirement?: BillingAddressRequirement;
+    /**
+     * 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.
+     */
+    amount?: string;
   };
 
 /**
@@ -349,8 +522,12 @@ export type AmosBankAccountPaymentMethodFormOptions =
  * element. Returns a controller exposing the underlying iframe, an
  * `update()` method, and a `destroy()` method.
  *
- * A field-shaped skeleton is shown immediately and replaced by the
- * iframe once appearance is applied.
+ * When the iframe reports an ACH threshold and `amount` meets it (or
+ * `amount` is omitted), a Connect bank button is rendered in the parent
+ * document and Plaid Link is opened on click. The button uses the same
+ * `appearance.themeVariables` as the iframe (and inherits host-page
+ * tokens when those variables are unset). Otherwise a field-shaped
+ * skeleton is shown and replaced by the iframe once appearance is applied.
  *
  * Use the returned `controller.iframe` when calling
  * {@link validateForm}, {@link confirmPaymentIntent}, or
@@ -359,11 +536,12 @@ export type AmosBankAccountPaymentMethodFormOptions =
 export function mountAmosBankAccountPaymentMethodForm(
   container: Container,
   options: AmosBankAccountPaymentMethodFormOptions,
-): AmosPaymentMethodFormMountController {
+): AmosBankAccountPaymentMethodFormMountController {
   const host = resolveContainer(container);
   const {
     renderToken,
     billingAddressRequirement = "country",
+    amount,
     ...listenerOptions
   } = options;
 
@@ -374,7 +552,7 @@ export function mountAmosBankAccountPaymentMethodForm(
     height: getBankAccountFormInitialHeight(billingAddressRequirement),
   });
 
-  return mountPaymentMethodFormWithSkeleton({
+  const iframeMount = mountPaymentMethodFormWithSkeleton({
     host,
     iframe,
     listenerOptions,
@@ -384,6 +562,28 @@ export function mountAmosBankAccountPaymentMethodForm(
       billingAddressRequirement,
     },
   });
+
+  const plaidUi = attachPlaidBankUi({
+    host,
+    iframe,
+    options: {
+      amount,
+      appearance: listenerOptions.appearance,
+      onValidityChange: listenerOptions.onValidityChange,
+    },
+  });
+
+  return {
+    iframe,
+    update(patch) {
+      iframeMount.update(patch as Partial<PaymentMethodFormListenerOptions>);
+      plaidUi.update(patch);
+    },
+    destroy() {
+      plaidUi.destroy();
+      iframeMount.destroy();
+    },
+  };
 }
 
 /**
@@ -420,6 +620,9 @@ export type AmosGooglePayButtonMountController = GooglePayButtonController & {
  * Mount the secure Google Pay button (express checkout) into a
  * container element. Returns a controller exposing the underlying
  * iframe, an `update()` method, and a `destroy()` method.
+ *
+ * A button-shaped skeleton is shown immediately and replaced by the
+ * iframe once appearance is applied.
  */
 export function mountAmosGooglePayButton(
   container: Container,
@@ -439,28 +642,14 @@ export function mountAmosGooglePayButton(
     style: WALLET_IFRAME_STYLE,
   });
   Object.assign(iframe.style, iframeStyle);
-  host.appendChild(iframe);
 
-  const controller = attachGooglePayButtonListeners(iframe, {
-    ...listenerOptions,
-    onHeightChange: (height) => {
-      iframe.style.height = height;
-      listenerOptions.onHeightChange?.(height);
-    },
-    onAppearanceReady: () => {
-      iframe.style.opacity = "1";
-      listenerOptions.onAppearanceReady?.();
-    },
-  });
-
-  return {
+  return mountWalletButtonWithSkeleton({
+    host,
     iframe,
-    update: controller.update,
-    destroy() {
-      controller.destroy();
-      iframe.remove();
-    },
-  };
+    listenerOptions,
+    iframeStyle,
+    attachListeners: attachGooglePayButtonListeners,
+  });
 }
 
 /**
@@ -497,6 +686,9 @@ export type AmosApplePayButtonMountController = ApplePayButtonController & {
  * Mount the secure Apple Pay button (express checkout) into a
  * container element. Returns a controller exposing the underlying
  * iframe, an `update()` method, and a `destroy()` method.
+ *
+ * A button-shaped skeleton is shown immediately and replaced by the
+ * iframe once appearance is applied.
  */
 export function mountAmosApplePayButton(
   container: Container,
@@ -516,26 +708,12 @@ export function mountAmosApplePayButton(
     style: WALLET_IFRAME_STYLE,
   });
   Object.assign(iframe.style, iframeStyle);
-  host.appendChild(iframe);
-
-  const controller = attachApplePayButtonListeners(iframe, {
-    ...listenerOptions,
-    onHeightChange: (height) => {
-      iframe.style.height = height;
-      listenerOptions.onHeightChange?.(height);
-    },
-    onAppearanceReady: () => {
-      iframe.style.opacity = "1";
-      listenerOptions.onAppearanceReady?.();
-    },
-  });
 
-  return {
+  return mountWalletButtonWithSkeleton({
+    host,
     iframe,
-    update: controller.update,
-    destroy() {
-      controller.destroy();
-      iframe.remove();
-    },
-  };
+    listenerOptions,
+    iframeStyle,
+    attachListeners: attachApplePayButtonListeners,
+  });
 }

package/src/payment-method-form.ts

@@ -3,6 +3,7 @@ import {
   sendParentReadyMessage,
   updateAppearance as sendUpdateAppearance,
 } from "./messaging";
+import { getBankPlaidSession } from "./plaid-session";
 import type {
   Appearance,
   ConfirmationResult,
@@ -203,6 +204,9 @@ export function attachPaymentMethodFormListeners(
         break;
 
       case "FORM_VALIDITY_CHANGE":
+        if (getBankPlaidSession(iframe)?.requiresVerification) {
+          break;
+        }
         current.onValidityChange?.({ isValid: event.data.isValid });
         break;