@amos.com/amos-js 0.9.16 → 0.9.18

package/dist/messaging.d.ts

@@ -68,6 +68,13 @@ export declare function updateMerchantName({ iframe, merchantName, }: {
 export declare function validateForm({ iframe }: {
     iframe: Iframe;
 }): Promise<boolean>;
+/**
+ * Ask the bank iframe to mint a Plaid Link token (`POST /plaid_link_tokens`
+ * on embed). Resolves with `link_token`, or rejects on error / timeout.
+ */
+export declare function requestPlaidLinkToken({ iframe, }: {
+    iframe: Iframe;
+}): Promise<string>;
 /**
  * Clear all field values and API errors in the embedded credit-card or
  * bank-account iframe form.

package/dist/mount.d.ts

@@ -40,6 +40,14 @@ export type AmosPaymentMethodFormMountController = PaymentMethodFormController &
      */
     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
@@ -70,20 +78,32 @@ export type AmosBankAccountPaymentMethodFormOptions = PaymentMethodFormListenerO
      * @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;
 };
 /**
  * Mount the secure bank-account payment method form into a container
  * 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
  * {@link confirmSetupIntent}.
  */
-export declare function mountAmosBankAccountPaymentMethodForm(container: Container, options: AmosBankAccountPaymentMethodFormOptions): AmosPaymentMethodFormMountController;
+export declare function mountAmosBankAccountPaymentMethodForm(container: Container, options: AmosBankAccountPaymentMethodFormOptions): AmosBankAccountPaymentMethodFormMountController;
 /**
  * Options accepted by {@link mountAmosGooglePayButton}.
  */
@@ -116,6 +136,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 declare function mountAmosGooglePayButton(container: Container, options: AmosGooglePayButtonOptions): AmosGooglePayButtonMountController;
 /**
@@ -150,6 +173,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 declare function mountAmosApplePayButton(container: Container, options: AmosApplePayButtonOptions): AmosApplePayButtonMountController;
 export {};

package/dist/plaid-bank-ui.d.ts

@@ -0,0 +1,21 @@
+import { PaymentMethodFormListenerOptions } from './payment-method-form';
+export type PlaidBankUiOptions = {
+    amount?: string;
+    appearance?: PaymentMethodFormListenerOptions["appearance"];
+    onValidityChange?: PaymentMethodFormListenerOptions["onValidityChange"];
+};
+/**
+ * Parent-page Connect bank UI. Outline/ghost controls match `@amos/ui`
+ * (including `:focus-visible` `--ring`). Unset theme variables inherit
+ * from the host document, then fall back to {@link ThemeVariable}
+ * defaults; `appearance.themeVariables` overrides with the same replace
+ * model as the iframe.
+ */
+export declare function attachPlaidBankUi({ host, iframe, options, }: {
+    host: HTMLElement;
+    iframe: HTMLIFrameElement;
+    options: PlaidBankUiOptions;
+}): {
+    update: (patch: Partial<PlaidBankUiOptions>) => void;
+    destroy: () => void;
+};

package/dist/plaid-session.d.ts

@@ -0,0 +1,12 @@
+import { PlaidCredentials } from './plaid';
+type BankPlaidSession = {
+    requiresVerification: boolean;
+    plaid?: PlaidCredentials;
+    /** Drop linked Plaid credentials and restore the Connect button. */
+    clearLinked?: () => void;
+};
+export declare function setBankPlaidSession(iframe: HTMLIFrameElement, session: BankPlaidSession): void;
+export declare function getBankPlaidSession(iframe: HTMLIFrameElement | null | undefined): BankPlaidSession | undefined;
+export declare function clearBankPlaidSession(iframe: HTMLIFrameElement | null | undefined): void;
+export declare function getBankPlaidCredentials(iframe: HTMLIFrameElement | null | undefined): PlaidCredentials | undefined;
+export {};

package/dist/plaid.d.ts

@@ -0,0 +1,82 @@
+import { components } from '@amos.com/node';
+export type PlaidCredentials = components["schemas"]["PlaidCredentialsInput"];
+export type PlaidLinkAccount = {
+    id?: string;
+    mask?: string;
+    name?: string;
+    subtype?: string | null;
+    type?: string;
+};
+export type PlaidLinkOnSuccessMetadata = {
+    institution?: {
+        name?: string;
+    } | null;
+    accounts?: Array<PlaidLinkAccount>;
+    account?: PlaidLinkAccount;
+    account_id?: string;
+};
+type PlaidLinkHandler = {
+    open: () => void;
+    exit: (options?: {
+        force?: boolean;
+    }) => void;
+    destroy: () => void;
+};
+type PlaidCreateConfig = {
+    token: string;
+    onSuccess: (publicToken: string, metadata: PlaidLinkOnSuccessMetadata) => void;
+    onExit?: (error: {
+        error_code?: string;
+        error_message?: string;
+    } | null, metadata: unknown) => void;
+};
+declare global {
+    interface Window {
+        Plaid?: {
+            create: (config: PlaidCreateConfig) => PlaidLinkHandler;
+        };
+    }
+}
+/**
+ * Whether the bank form should show Plaid Link instead of routing/account
+ * fields.
+ *
+ * - No `achThreshold`: always manual ACH (backward compatible).
+ * - `amount` omitted: Plaid (setup / unknown future charge).
+ * - Otherwise: Plaid when `amount >= achThreshold`.
+ *
+ * `amount` and `achThreshold` are integer minor units (cents).
+ */
+export declare function requiresAchVerification({ amount, achThreshold, }: {
+    amount?: number;
+    achThreshold?: number;
+}): boolean;
+/**
+ * Convert a major-currency decimal string (e.g. `"50.00"`) to integer
+ * cents. Empty / invalid values are omitted.
+ */
+export declare function majorAmountToMinorUnits(amount?: string): number | undefined;
+export declare function plaidAccountIdFromMetadata(metadata: PlaidLinkOnSuccessMetadata): string | undefined;
+export declare function linkedBankLabelFromMetadata(metadata: PlaidLinkOnSuccessMetadata): {
+    bankName: string;
+    last4: string;
+};
+export declare function loadPlaidScript(): Promise<void>;
+export type OpenPlaidLinkInput = {
+    token: string;
+    onSuccess: (publicToken: string, metadata: PlaidLinkOnSuccessMetadata) => void;
+    onExit?: (error: {
+        error_code?: string;
+    } | null) => void;
+    /**
+     * When aborted (e.g. the bank form was unmounted), skip opening Link
+     * and destroy the handler if it was already created.
+     */
+    signal?: AbortSignal;
+};
+/**
+ * Load Plaid Link (if needed) and open it with the given `link_token`.
+ * Returns a destroy function for the Link handler.
+ */
+export declare function openPlaidLink({ token, onSuccess, onExit, signal, }: OpenPlaidLinkInput): Promise<() => void>;
+export {};

package/dist/types.d.ts

@@ -185,10 +185,16 @@ export type Message = {
 } | ({
     /** Parent → embed: confirm a payment intent with an embed token. */
     type: "CONFIRM_PAYMENT_INTENT";
-} & Pick<components["schemas"]["PaymentIntent"], "id"> & Pick<components["schemas"]["EmbedToken"], "token">) | ({
+} & Pick<components["schemas"]["PaymentIntent"], "id"> & Pick<components["schemas"]["EmbedToken"], "token"> & {
+    /** Present when ACH verification completed via Plaid Link in the parent. */
+    plaid?: components["schemas"]["PlaidCredentialsInput"];
+}) | ({
     /** Parent → embed: confirm a setup intent with an embed token. */
     type: "CONFIRM_SETUP_INTENT";
-} & Pick<components["schemas"]["SetupIntent"], "id"> & Pick<components["schemas"]["EmbedToken"], "token">) | {
+} & Pick<components["schemas"]["SetupIntent"], "id"> & Pick<components["schemas"]["EmbedToken"], "token"> & {
+    /** Present when ACH verification completed via Plaid Link in the parent. */
+    plaid?: components["schemas"]["PlaidCredentialsInput"];
+}) | {
     /**
      * Embed → parent: the interactive confirmation flow finished.
      * Parent → embed: express-checkout initiation failed on the host.
@@ -220,6 +226,26 @@ export type Message = {
      */
     type: "FORM_VALIDITY_CHANGE";
     isValid: boolean;
+} | {
+    /**
+     * Embed → parent: merchant ACH verification threshold for this
+     * render token. `achThreshold` is cents, or `null` when the
+     * merchant has no threshold (manual ACH). `requireVerification`
+     * is true when the fetch failed in production (fail closed).
+     */
+    type: "ACH_THRESHOLD";
+    achThreshold?: number | null;
+    requireVerification?: boolean;
+} | {
+    /** Parent → embed: mint a Plaid Link token for Connect. */
+    type: "CREATE_PLAID_LINK_TOKEN";
+    requestId: string;
+} | {
+    /** Embed → parent: minted Plaid Link token, or `error`. */
+    type: "PLAID_LINK_TOKEN";
+    requestId: string;
+    link_token?: string;
+    error?: string;
 };
 /**
  * Identity helper that brands an object as a typed `Message`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amos.com/amos-js",
-  "version": "0.9.16",
+  "version": "0.9.18",
   "main": "dist/index.js",
   "repository": {
     "type": "git",

package/src/form-skeleton.ts

@@ -16,7 +16,7 @@ const SKELETON_THEME_DEFAULTS: Record<string, string> = {
   "--label-font-size": "0.875rem",
 };
 
-const SKELETON_STYLES = `
+export const SKELETON_STYLES = `
 .amos-js-form-skeleton {
   box-sizing: border-box;
   container-type: inline-size;
@@ -71,6 +71,10 @@ const SKELETON_STYLES = `
     gap: var(--control-gap);
   }
 }
+.amos-js-wallet-skeleton {
+  flex: none;
+  width: 100%;
+}
 @keyframes amos-js-skeleton-pulse {
   50% { opacity: 0.5; }
 }
@@ -81,7 +85,7 @@ const SKELETON_STYLES = `
 }
 `;
 
-function ensureSkeletonStyles(): void {
+export function ensureSkeletonStyles(): void {
   if (document.getElementById(STYLE_ID)) {
     return;
   }
@@ -242,3 +246,74 @@ export function createPaymentMethodFormSkeleton(
     update: render,
   };
 }
+
+export type WalletButtonSkeletonOptions = {
+  /** Painted height of the wallet button slot (CSS length). */
+  height: string;
+  /** Corner radius matching the iframe / native button. */
+  borderRadius?: string;
+};
+
+export type WalletButtonSkeleton = {
+  element: HTMLElement;
+  update: (options: WalletButtonSkeletonOptions) => void;
+};
+
+/**
+ * Host-page placeholder for Google Pay / Apple Pay: a pulsing bar at
+ * the button's height. Shown immediately while the iframe loads, then
+ * removed when appearance is ready.
+ */
+export function createWalletButtonSkeleton(
+  options: WalletButtonSkeletonOptions,
+): WalletButtonSkeleton {
+  ensureSkeletonStyles();
+  const element = div("amos-js-form-skeleton-input amos-js-wallet-skeleton");
+  element.setAttribute("aria-hidden", "true");
+
+  function render(next: WalletButtonSkeletonOptions): void {
+    applyTheme(element, undefined);
+    element.style.height = next.height;
+    element.style.borderRadius = next.borderRadius ?? "4px";
+  }
+
+  render(options);
+
+  return {
+    element,
+    update: render,
+  };
+}
+
+function cssLength(value: unknown): string | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return `${value}px`;
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    return value.trim();
+  }
+  return undefined;
+}
+
+/**
+ * Corner radius for a wallet-button skeleton. Prefers host iframe
+ * chrome, then native Google / Apple button radius, then 4px.
+ */
+export function resolveWalletButtonSkeletonBorderRadius({
+  iframeStyle,
+  buttonProps,
+}: {
+  iframeStyle?: { borderRadius?: string | number };
+  buttonProps?: {
+    buttonRadius?: number;
+    style?: Record<string, string | number | undefined>;
+  };
+}): string {
+  return (
+    cssLength(iframeStyle?.borderRadius) ??
+    cssLength(buttonProps?.buttonRadius) ??
+    cssLength(buttonProps?.style?.["borderRadius"]) ??
+    cssLength(buttonProps?.style?.["--apple-pay-button-border-radius"]) ??
+    "4px"
+  );
+}

package/src/index.ts

@@ -9,7 +9,20 @@ export {
   getApplePayButtonInitialHeight,
   getApplePayButtonSrc,
 } from "./apple-pay";
-
+export type {
+  PaymentMethodFormSkeleton,
+  PaymentMethodFormSkeletonKind,
+  PaymentMethodFormSkeletonOptions,
+  WalletButtonSkeleton,
+  WalletButtonSkeletonOptions,
+} from "./form-skeleton";
+export {
+  createPaymentMethodFormSkeleton,
+  createWalletButtonSkeleton,
+  ensureSkeletonStyles,
+  resolveWalletButtonSkeletonBorderRadius,
+  SKELETON_STYLES,
+} from "./form-skeleton";
 export type {
   FormattedGooglePayPaymentData,
   GooglePayButtonController,
@@ -21,7 +34,6 @@ export {
   getGooglePayButtonInitialHeight,
   getGooglePayButtonSrc,
 } from "./google-pay";
-
 export { decodeJwt, getEmbedOrigin } from "./jwt";
 
 export {
@@ -40,6 +52,7 @@ export {
 export type {
   AmosApplePayButtonMountController,
   AmosApplePayButtonOptions,
+  AmosBankAccountPaymentMethodFormMountController,
   AmosBankAccountPaymentMethodFormOptions,
   AmosCreditCardPaymentMethodFormOptions,
   AmosGooglePayButtonMountController,
@@ -65,6 +78,18 @@ export {
   getCreditCardFormInitialHeight,
   getCreditCardFormSrc,
 } from "./payment-method-form";
+export type {
+  OpenPlaidLinkInput,
+  PlaidCredentials,
+  PlaidLinkOnSuccessMetadata,
+} from "./plaid";
+export {
+  linkedBankLabelFromMetadata,
+  loadPlaidScript,
+  openPlaidLink,
+  plaidAccountIdFromMetadata,
+  requiresAchVerification,
+} from "./plaid";
 export type {
   Appearance,
   AppearanceLabels,

package/src/messaging.ts

@@ -1,5 +1,6 @@
 import type { components } from "@amos.com/node";
 import { decodeJwt } from "./jwt";
+import { getBankPlaidSession } from "./plaid-session";
 import {
   type Appearance,
   type ApplePayButtonElementProps,
@@ -163,6 +164,11 @@ export function updateMerchantName({
  * `false` if the iframe does not respond within 5 seconds.
  */
 export function validateForm({ iframe }: { iframe: Iframe }): Promise<boolean> {
+  const session = getBankPlaidSession(iframe);
+  if (session?.requiresVerification) {
+    return Promise.resolve(Boolean(session.plaid));
+  }
+
   const requestId = crypto.randomUUID();
 
   return new Promise((resolve) => {
@@ -193,11 +199,71 @@ export function validateForm({ iframe }: { iframe: Iframe }): Promise<boolean> {
   });
 }
 
+const PLAID_LINK_TOKEN_TIMEOUT_MS = 10_000;
+
+/**
+ * Ask the bank iframe to mint a Plaid Link token (`POST /plaid_link_tokens`
+ * on embed). Resolves with `link_token`, or rejects on error / timeout.
+ */
+export function requestPlaidLinkToken({
+  iframe,
+}: {
+  iframe: Iframe;
+}): Promise<string> {
+  const requestId = crypto.randomUUID();
+
+  return new Promise((resolve, reject) => {
+    if (!iframe?.contentWindow) {
+      reject(new Error("Bank form is not ready."));
+      return;
+    }
+
+    const contentWindow = iframe.contentWindow;
+    contentWindow.postMessage(
+      createMessage({ type: "CREATE_PLAID_LINK_TOKEN", requestId }),
+      getIframeTargetOrigin(iframe),
+    );
+
+    const timeoutId = setTimeout(() => {
+      window.removeEventListener("message", handleMessage);
+      reject(new Error("Timed out waiting for Plaid Link token."));
+    }, PLAID_LINK_TOKEN_TIMEOUT_MS);
+
+    function handleMessage(event: MessageEvent<Message>) {
+      if (event.source !== contentWindow) {
+        return;
+      }
+      if (
+        event.data.type !== "PLAID_LINK_TOKEN" ||
+        event.data.requestId !== requestId
+      ) {
+        return;
+      }
+      window.removeEventListener("message", handleMessage);
+      clearTimeout(timeoutId);
+      if (event.data.link_token) {
+        resolve(event.data.link_token);
+        return;
+      }
+      reject(
+        new Error(event.data.error ?? "Could not create Plaid Link token."),
+      );
+    }
+
+    window.addEventListener("message", handleMessage);
+  });
+}
+
 /**
  * Clear all field values and API errors in the embedded credit-card or
  * bank-account iframe form.
  */
 export function resetForm({ iframe }: { iframe: Iframe }): void {
+  getBankPlaidSession(iframe)?.clearLinked?.();
+  resetIframeFields(iframe);
+}
+
+function resetIframeFields(iframe: Iframe): void {
   if (!iframe?.contentWindow) {
     return;
   }
@@ -208,6 +274,35 @@ export function resetForm({ iframe }: { iframe: Iframe }): void {
   );
 }
 
+function postConfirmIntent({
+  iframe,
+  type,
+  token,
+  id,
+}: {
+  iframe: HTMLIFrameElement;
+  type: "CONFIRM_PAYMENT_INTENT" | "CONFIRM_SETUP_INTENT";
+  token: string | undefined;
+  id: string | undefined;
+}): void {
+  const session = getBankPlaidSession(iframe);
+  const plaid = session?.plaid;
+  // Plaid mode: do not confirm leftover routing/account numbers.
+  if (session?.requiresVerification && !plaid) {
+    resetIframeFields(iframe);
+  }
+
+  iframe.contentWindow?.postMessage(
+    createMessage({
+      type,
+      token,
+      id,
+      ...(plaid ? { plaid } : {}),
+    }),
+    getIframeTargetOrigin(iframe),
+  );
+}
+
 /**
  * Confirm a payment intent in the embedded iframe flow.
  *
@@ -227,14 +322,12 @@ export function confirmPaymentIntent({
 
   const { payment_intent_id: id }: components["schemas"]["EmbedTokenJwt"] =
     decodeJwt(token).payload;
-  iframe.contentWindow.postMessage(
-    createMessage({
-      type: "CONFIRM_PAYMENT_INTENT",
-      token,
-      id: id ?? undefined,
-    }),
-    getIframeTargetOrigin(iframe),
-  );
+  postConfirmIntent({
+    iframe,
+    type: "CONFIRM_PAYMENT_INTENT",
+    token,
+    id: id ?? undefined,
+  });
 }
 
 /**
@@ -256,14 +349,12 @@ export function confirmSetupIntent({
 
   const { setup_intent_id: id }: components["schemas"]["EmbedTokenJwt"] =
     decodeJwt(token).payload;
-  iframe.contentWindow.postMessage(
-    createMessage({
-      type: "CONFIRM_SETUP_INTENT",
-      token,
-      id: id ?? undefined,
-    }),
-    getIframeTargetOrigin(iframe),
-  );
+  postConfirmIntent({
+    iframe,
+    type: "CONFIRM_SETUP_INTENT",
+    token,
+    id: id ?? undefined,
+  });
 }
 
 /**