@amos.com/amos-js 0.9.17 → 0.10.0

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}.
  */

package/dist/payment-method-form.d.ts

@@ -1,4 +1,4 @@
-import { Appearance, ConfirmationResult, PaymentMethodFormValidityChangeEvent } from './types';
+import { Appearance, ConfirmationResult, PaymentMethodFormCardBrandChangeEvent, PaymentMethodFormValidityChangeEvent } from './types';
 /**
  * The additional fields beyond the standard card number, expiration
  * date, CVV, and billing address fields that are required to be filled
@@ -65,6 +65,13 @@ export type PaymentMethodFormListenerOptions = {
      * PCI data. Use this to enable or disable a host checkout button.
      */
     onValidityChange?: (event: PaymentMethodFormValidityChangeEvent) => void;
+    /**
+     * Called when the detected card brand changes. `brand` is the matched
+     * network, or `null` when the field is empty or the digits do not
+     * match a known brand. Does not include PCI data. Credit-card form
+     * only — never fired for bank account.
+     */
+    onCardBrandChanged?: (event: PaymentMethodFormCardBrandChangeEvent) => void;
     /**
      * Called when the interactive confirmation flow finishes (success or
      * terminal failure). Not settlement proof — verify via webhooks.

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

@@ -7,6 +7,18 @@ import { components } from '@amos.com/node';
 export type PaymentMethodFormValidityChangeEvent = {
     isValid: boolean;
 };
+/**
+ * Detected card network from the PAN prefix inside the iframe.
+ * `null` when the field is empty or the digits do not match a known brand.
+ */
+export type CardBrand = "visa" | "mastercard" | "amex" | "discover" | "diners" | "jcb";
+/**
+ * PCI-safe card brand update from the credit-card iframe. Does not
+ * include the PAN, last4, or BIN.
+ */
+export type PaymentMethodFormCardBrandChangeEvent = {
+    brand: CardBrand | null;
+};
 /**
  * Why an interactive confirmation attempt ended with `status: "incomplete"`.
  *
@@ -185,10 +197,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 +238,34 @@ export type Message = {
      */
     type: "FORM_VALIDITY_CHANGE";
     isValid: boolean;
+} | {
+    /**
+     * Embed → parent: detected card brand changed. `brand` is the
+     * matched network, or `null` when the field is empty or the
+     * digits do not match a known brand. Does not include PCI data.
+     */
+    type: "CARD_BRAND_CHANGE";
+    brand: CardBrand | null;
+} | {
+    /**
+     * 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.17",
+  "version": "0.10.0",
   "main": "dist/index.js",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -52,6 +52,7 @@ export {
 export type {
   AmosApplePayButtonMountController,
   AmosApplePayButtonOptions,
+  AmosBankAccountPaymentMethodFormMountController,
   AmosBankAccountPaymentMethodFormOptions,
   AmosCreditCardPaymentMethodFormOptions,
   AmosGooglePayButtonMountController,
@@ -77,14 +78,28 @@ 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,
   ApplePayButtonElementProps,
+  CardBrand,
   ConfirmationIncompleteReason,
   ConfirmationResult,
   GooglePayButtonElementProps,
   Message,
+  PaymentMethodFormCardBrandChangeEvent,
   PaymentMethodFormValidityChangeEvent,
   ThemeVariable,
 } from "./types";

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,
+  });
 }
 
 /**

package/src/mount.ts

@@ -31,6 +31,7 @@ import {
   type PaymentMethodFormController,
   type PaymentMethodFormListenerOptions,
 } from "./payment-method-form";
+import { attachPlaidBankUi } from "./plaid-bank-ui";
 
 type Container = HTMLElement | string;
 
@@ -425,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
@@ -494,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;
   };
 
 /**
@@ -501,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
@@ -511,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;
 
@@ -526,7 +552,7 @@ export function mountAmosBankAccountPaymentMethodForm(
     height: getBankAccountFormInitialHeight(billingAddressRequirement),
   });
 
-  return mountPaymentMethodFormWithSkeleton({
+  const iframeMount = mountPaymentMethodFormWithSkeleton({
     host,
     iframe,
     listenerOptions,
@@ -536,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();
+    },
+  };
 }
 
 /**

package/src/payment-method-form.ts

@@ -3,10 +3,12 @@ import {
   sendParentReadyMessage,
   updateAppearance as sendUpdateAppearance,
 } from "./messaging";
+import { getBankPlaidSession } from "./plaid-session";
 import type {
   Appearance,
   ConfirmationResult,
   Message,
+  PaymentMethodFormCardBrandChangeEvent,
   PaymentMethodFormValidityChangeEvent,
 } from "./types";
 
@@ -137,6 +139,13 @@ export type PaymentMethodFormListenerOptions = {
    * PCI data. Use this to enable or disable a host checkout button.
    */
   onValidityChange?: (event: PaymentMethodFormValidityChangeEvent) => void;
+  /**
+   * Called when the detected card brand changes. `brand` is the matched
+   * network, or `null` when the field is empty or the digits do not
+   * match a known brand. Does not include PCI data. Credit-card form
+   * only — never fired for bank account.
+   */
+  onCardBrandChanged?: (event: PaymentMethodFormCardBrandChangeEvent) => void;
   /**
    * Called when the interactive confirmation flow finishes (success or
    * terminal failure). Not settlement proof — verify via webhooks.
@@ -203,9 +212,16 @@ export function attachPaymentMethodFormListeners(
         break;
 
       case "FORM_VALIDITY_CHANGE":
+        if (getBankPlaidSession(iframe)?.requiresVerification) {
+          break;
+        }
         current.onValidityChange?.({ isValid: event.data.isValid });
         break;
 
+      case "CARD_BRAND_CHANGE":
+        current.onCardBrandChanged?.({ brand: event.data.brand });
+        break;
+
       case "CONFIRMATION_RESULT":
         current.onResult(event.data.result);
         break;