@amos.com/amos-js 0.9.17 → 0.9.18

package/src/plaid-bank-ui.ts

@@ -0,0 +1,421 @@
+import { requestPlaidLinkToken } from "./messaging";
+import type { PaymentMethodFormListenerOptions } from "./payment-method-form";
+import {
+  linkedBankLabelFromMetadata,
+  majorAmountToMinorUnits,
+  openPlaidLink,
+  type PlaidCredentials,
+  plaidAccountIdFromMetadata,
+  requiresAchVerification,
+} from "./plaid";
+import { clearBankPlaidSession, setBankPlaidSession } from "./plaid-session";
+import type { Appearance, Message, ThemeVariable } from "./types";
+
+const STYLE_ID = "amos-js-plaid-bank-ui-styles";
+
+const PLAID_BANK_UI_STYLES = `
+.amos-js-plaid-panel {
+  box-sizing: border-box;
+  color: var(--foreground, oklch(0.145 0 0));
+  display: none;
+  flex-direction: column;
+  font-family: inherit;
+  gap: var(--control-gap, 0.5rem);
+  width: 100%;
+}
+.amos-js-plaid-panel[data-mode="connect"],
+.amos-js-plaid-panel[data-mode="linked"] {
+  display: flex;
+}
+.amos-js-plaid-connect {
+  align-items: center;
+  background: var(--background, oklch(1 0 0));
+  border: var(--input-border-width, 1px) solid var(--border, oklch(0.922 0 0));
+  border-radius: calc(var(--radius, 0.625rem) * 0.8);
+  box-shadow: var(--input-shadow, 0 1px 2px 0 rgb(0 0 0 / 0.05));
+  box-sizing: border-box;
+  color: var(--foreground, oklch(0.145 0 0));
+  cursor: pointer;
+  display: inline-flex;
+  flex-shrink: 0;
+  font: inherit;
+  font-size: var(--input-font-size, 0.875rem);
+  font-weight: 500;
+  height: var(--input-height, 2.25rem);
+  justify-content: center;
+  line-height: 1.25;
+  outline: none;
+  padding: 0 var(--input-padding, 0.75rem);
+  transition: color 150ms, background-color 150ms, border-color 150ms, box-shadow 150ms;
+  width: 100%;
+}
+.amos-js-plaid-panel[data-mode="linked"] .amos-js-plaid-connect {
+  display: none;
+}
+.amos-js-plaid-connect:hover:not(:disabled) {
+  background: var(--accent, oklch(0.97 0 0));
+  color: var(--accent-foreground, oklch(0.205 0 0));
+}
+.amos-js-plaid-connect:focus-visible {
+  border-color: var(--ring, oklch(0.708 0 0));
+  box-shadow:
+    var(--input-shadow, 0 1px 2px 0 rgb(0 0 0 / 0.05)),
+    0 0 0 var(--ring-width, 3px)
+      color-mix(in oklab, var(--ring, oklch(0.708 0 0)) 50%, transparent);
+}
+.amos-js-plaid-connect:disabled {
+  cursor: default;
+  opacity: 0.5;
+  pointer-events: none;
+}
+.amos-js-plaid-linked {
+  display: none;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+.amos-js-plaid-panel[data-mode="linked"] .amos-js-plaid-linked {
+  display: flex;
+}
+.amos-js-plaid-linked-name {
+  font-size: var(--input-font-size, 0.875rem);
+  font-weight: 500;
+}
+.amos-js-plaid-linked-meta {
+  color: var(--muted-foreground, oklch(0.556 0 0));
+  font-size: 0.75rem;
+}
+.amos-js-plaid-disconnect {
+  align-self: flex-start;
+  background: none;
+  border: none;
+  border-radius: calc(var(--radius, 0.625rem) * 0.8);
+  color: var(--muted-foreground, oklch(0.556 0 0));
+  cursor: pointer;
+  font: inherit;
+  font-size: var(--input-font-size, 0.875rem);
+  margin-top: 0.25rem;
+  outline: none;
+  padding: 0;
+}
+.amos-js-plaid-disconnect:hover {
+  color: var(--accent-foreground, oklch(0.205 0 0));
+}
+.amos-js-plaid-disconnect:focus-visible {
+  box-shadow:
+    0 0 0 var(--ring-width, 3px)
+      color-mix(in oklab, var(--ring, oklch(0.708 0 0)) 50%, transparent);
+}
+.amos-js-plaid-error {
+  color: var(--destructive, oklch(0.577 0.245 27.325));
+  display: none;
+  font-size: var(--error-font-size, 0.875rem);
+  margin: 0;
+}
+.amos-js-plaid-error:not(:empty) {
+  display: block;
+}
+@media (prefers-reduced-motion: reduce) {
+  .amos-js-plaid-connect {
+    transition: none;
+  }
+}
+`;
+
+function ensurePlaidBankUiStyles(): void {
+  if (document.getElementById(STYLE_ID)) {
+    return;
+  }
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = PLAID_BANK_UI_STYLES;
+  document.head.append(style);
+}
+
+function applyTheme(
+  panel: HTMLElement,
+  appearance: Appearance | undefined,
+  appliedKeys: Array<string>,
+): void {
+  for (const property of appliedKeys) {
+    panel.style.removeProperty(property);
+  }
+  appliedKeys.length = 0;
+  const themeVariables = appearance?.themeVariables;
+  if (!themeVariables) {
+    return;
+  }
+  for (const [property, value] of Object.entries(themeVariables) as Array<
+    [ThemeVariable, string | undefined]
+  >) {
+    if (typeof value === "string" && value.trim() !== "") {
+      panel.style.setProperty(property, value.trim());
+      appliedKeys.push(property);
+    }
+  }
+}
+
+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 function attachPlaidBankUi({
+  host,
+  iframe,
+  options,
+}: {
+  host: HTMLElement;
+  iframe: HTMLIFrameElement;
+  options: PlaidBankUiOptions;
+}): {
+  update: (patch: Partial<PlaidBankUiOptions>) => void;
+  destroy: () => void;
+} {
+  ensurePlaidBankUiStyles();
+
+  const current: PlaidBankUiOptions = { ...options };
+  const appliedThemeKeys: Array<string> = [];
+  let thresholdKnown = false;
+  let achThreshold: number | undefined;
+  let requireVerification = false;
+  let cachedLinkToken: string | undefined;
+  let opening = false;
+  let lastEmittedValid: boolean | undefined;
+  let destroyLink: (() => void) | undefined;
+  const abort = new AbortController();
+  let linked:
+    | { credentials: PlaidCredentials; bankName: string; last4: string }
+    | undefined;
+
+  const panel = document.createElement("div");
+  panel.className = "amos-js-plaid-panel";
+  panel.setAttribute("data-amos-plaid-panel", "true");
+  panel.dataset["mode"] = "hidden";
+  applyTheme(panel, current.appearance, appliedThemeKeys);
+
+  const connectButton = document.createElement("button");
+  connectButton.type = "button";
+  connectButton.className = "amos-js-plaid-connect";
+  connectButton.textContent = "Connect bank account";
+  connectButton.setAttribute("data-testid", "amos-plaid-connect");
+
+  const linkedEl = document.createElement("div");
+  linkedEl.className = "amos-js-plaid-linked";
+
+  const linkedName = document.createElement("span");
+  linkedName.className = "amos-js-plaid-linked-name";
+
+  const linkedMeta = document.createElement("span");
+  linkedMeta.className = "amos-js-plaid-linked-meta";
+
+  const disconnect = document.createElement("button");
+  disconnect.type = "button";
+  disconnect.className = "amos-js-plaid-disconnect";
+  disconnect.textContent = "Disconnect";
+  disconnect.setAttribute("aria-label", "Disconnect bank account");
+
+  const errorEl = document.createElement("p");
+  errorEl.className = "amos-js-plaid-error";
+  errorEl.setAttribute("role", "alert");
+
+  linkedEl.append(linkedName, linkedMeta, disconnect);
+  panel.append(connectButton, linkedEl, errorEl);
+  host.append(panel);
+  const formWrapper = iframe.parentElement;
+
+  function setError(message: string | undefined): void {
+    errorEl.textContent = message ?? "";
+  }
+
+  function requiresConnect(): boolean {
+    if (!thresholdKnown) {
+      return false;
+    }
+    if (requireVerification) {
+      return true;
+    }
+    return requiresAchVerification({
+      amount: majorAmountToMinorUnits(current.amount),
+      achThreshold,
+    });
+  }
+
+  function publishPlaidValidity(): void {
+    const isValid = Boolean(linked);
+    if (lastEmittedValid === isValid) {
+      return;
+    }
+    lastEmittedValid = isValid;
+    current.onValidityChange?.({ isValid });
+  }
+
+  function syncSession(): void {
+    const requiresVerification = requiresConnect();
+    setBankPlaidSession(iframe, {
+      requiresVerification,
+      plaid: requiresVerification ? linked?.credentials : undefined,
+      clearLinked: unlink,
+    });
+
+    if (!requiresVerification) {
+      panel.dataset["mode"] = "hidden";
+      if (formWrapper) {
+        formWrapper.style.display = "";
+      }
+      lastEmittedValid = undefined;
+      return;
+    }
+
+    panel.dataset["mode"] = linked ? "linked" : "connect";
+    if (formWrapper) {
+      formWrapper.style.display = "none";
+    }
+    if (linked) {
+      linkedName.textContent = linked.bankName;
+      linkedMeta.textContent = linked.last4
+        ? `****${linked.last4}`
+        : "Connected";
+    }
+    publishPlaidValidity();
+  }
+
+  function unlink(): void {
+    linked = undefined;
+    cachedLinkToken = undefined;
+    destroyLink?.();
+    destroyLink = undefined;
+    setError(undefined);
+    syncSession();
+  }
+
+  function handleIframeMessage(event: MessageEvent<Message>): void {
+    if (event.source !== iframe.contentWindow) {
+      return;
+    }
+    if (event.data.type !== "ACH_THRESHOLD") {
+      return;
+    }
+    thresholdKnown = true;
+    achThreshold = event.data.achThreshold ?? undefined;
+    requireVerification = event.data.requireVerification === true;
+    if (linked && !requiresConnect()) {
+      unlink();
+      return;
+    }
+    syncSession();
+  }
+
+  window.addEventListener("message", handleIframeMessage);
+  syncSession();
+
+  disconnect.addEventListener("click", () => {
+    unlink();
+  });
+
+  connectButton.addEventListener("click", () => {
+    void (async () => {
+      if (abort.signal.aborted || opening) {
+        return;
+      }
+      opening = true;
+      connectButton.disabled = true;
+      setError(undefined);
+      try {
+        if (!cachedLinkToken) {
+          cachedLinkToken = await requestPlaidLinkToken({ iframe });
+        }
+        if (abort.signal.aborted) {
+          return;
+        }
+        const token = cachedLinkToken;
+        destroyLink?.();
+        destroyLink = await openPlaidLink({
+          token,
+          signal: abort.signal,
+          onSuccess: (publicToken, metadata) => {
+            if (abort.signal.aborted) {
+              return;
+            }
+            const accountId = plaidAccountIdFromMetadata(metadata);
+            if (!accountId) {
+              setError("Select a bank account to continue.");
+              return;
+            }
+            const label = linkedBankLabelFromMetadata(metadata);
+            linked = {
+              credentials: {
+                public_token: publicToken,
+                account_id: accountId,
+              },
+              bankName: label.bankName,
+              last4: label.last4,
+            };
+            cachedLinkToken = undefined;
+            syncSession();
+          },
+          onExit: (error) => {
+            if (abort.signal.aborted) {
+              return;
+            }
+            if (error?.error_code === "INVALID_LINK_TOKEN") {
+              cachedLinkToken = undefined;
+            }
+          },
+        });
+        if (abort.signal.aborted) {
+          destroyLink();
+          destroyLink = undefined;
+        }
+      } catch (error) {
+        cachedLinkToken = undefined;
+        if (abort.signal.aborted) {
+          return;
+        }
+        setError(
+          error instanceof Error ? error.message : "Could not connect bank.",
+        );
+      } finally {
+        opening = false;
+        if (!abort.signal.aborted) {
+          connectButton.disabled = false;
+        }
+      }
+    })();
+  });
+
+  return {
+    update(patch) {
+      if ("amount" in patch) {
+        current.amount = patch.amount;
+      }
+      if ("onValidityChange" in patch) {
+        current.onValidityChange = patch.onValidityChange;
+      }
+      if ("appearance" in patch) {
+        current.appearance = patch.appearance;
+        applyTheme(panel, current.appearance, appliedThemeKeys);
+      }
+      if (linked && !requiresConnect()) {
+        unlink();
+        return;
+      }
+      syncSession();
+    },
+    destroy() {
+      abort.abort();
+      window.removeEventListener("message", handleIframeMessage);
+      destroyLink?.();
+      destroyLink = undefined;
+      clearBankPlaidSession(iframe);
+      panel.remove();
+    },
+  };
+}

package/src/plaid-session.ts

@@ -0,0 +1,41 @@
+import type { PlaidCredentials } from "./plaid";
+
+type BankPlaidSession = {
+  requiresVerification: boolean;
+  plaid?: PlaidCredentials;
+  /** Drop linked Plaid credentials and restore the Connect button. */
+  clearLinked?: () => void;
+};
+
+const sessions = new WeakMap<HTMLIFrameElement, BankPlaidSession>();
+
+export function setBankPlaidSession(
+  iframe: HTMLIFrameElement,
+  session: BankPlaidSession,
+): void {
+  sessions.set(iframe, session);
+}
+
+export function getBankPlaidSession(
+  iframe: HTMLIFrameElement | null | undefined,
+): BankPlaidSession | undefined {
+  if (!iframe) {
+    return undefined;
+  }
+  return sessions.get(iframe);
+}
+
+export function clearBankPlaidSession(
+  iframe: HTMLIFrameElement | null | undefined,
+): void {
+  if (!iframe) {
+    return;
+  }
+  sessions.delete(iframe);
+}
+
+export function getBankPlaidCredentials(
+  iframe: HTMLIFrameElement | null | undefined,
+): PlaidCredentials | undefined {
+  return getBankPlaidSession(iframe)?.plaid;
+}

package/src/plaid.ts

@@ -0,0 +1,215 @@
+import type { components } from "@amos.com/node";
+
+const PLAID_SCRIPT_SRC =
+  "https://cdn.plaid.com/link/v2/stable/link-initialize.js";
+
+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 function requiresAchVerification({
+  amount,
+  achThreshold,
+}: {
+  amount?: number;
+  achThreshold?: number;
+}): boolean {
+  if (achThreshold == null) {
+    return false;
+  }
+  if (amount == null) {
+    return true;
+  }
+  return amount >= achThreshold;
+}
+
+/**
+ * Convert a major-currency decimal string (e.g. `"50.00"`) to integer
+ * cents. Empty / invalid values are omitted.
+ */
+export function majorAmountToMinorUnits(amount?: string): number | undefined {
+  if (amount == null) {
+    return undefined;
+  }
+  const trimmed = amount.trim();
+  if (trimmed === "") {
+    return undefined;
+  }
+  const major = Number(trimmed.replace(/[^\d.]/g, ""));
+  if (!Number.isFinite(major)) {
+    return undefined;
+  }
+  return Math.round(major * 100);
+}
+
+export function plaidAccountIdFromMetadata(
+  metadata: PlaidLinkOnSuccessMetadata,
+): string | undefined {
+  return (
+    metadata.account_id ?? metadata.account?.id ?? metadata.accounts?.[0]?.id
+  );
+}
+
+export function linkedBankLabelFromMetadata(
+  metadata: PlaidLinkOnSuccessMetadata,
+): { bankName: string; last4: string } {
+  const account = metadata.account ?? metadata.accounts?.[0];
+  const bankName = metadata.institution?.name ?? "Bank account";
+  const last4 = account?.mask ?? "";
+  return { bankName, last4 };
+}
+
+let plaidScriptPromise: Promise<void> | undefined;
+
+function removePlaidScriptTags(): void {
+  for (const node of document.querySelectorAll(
+    `script[src="${PLAID_SCRIPT_SRC}"]`,
+  )) {
+    node.remove();
+  }
+}
+
+export function loadPlaidScript(): Promise<void> {
+  if (typeof window === "undefined") {
+    return Promise.reject(new Error("Plaid Link requires a browser"));
+  }
+  if (window.Plaid) {
+    return Promise.resolve();
+  }
+  if (plaidScriptPromise) {
+    return plaidScriptPromise;
+  }
+
+  // A previous failed attempt leaves a <script> whose load/error already
+  // fired. Waiting on that tag hangs; drop it and inject a new one.
+  removePlaidScriptTags();
+
+  plaidScriptPromise = new Promise((resolve, reject) => {
+    const script = document.createElement("script");
+    script.src = PLAID_SCRIPT_SRC;
+    script.async = true;
+
+    const fail = (message: string) => {
+      script.remove();
+      plaidScriptPromise = undefined;
+      reject(new Error(message));
+    };
+
+    script.addEventListener(
+      "load",
+      () => {
+        if (window.Plaid) {
+          resolve();
+          return;
+        }
+        fail("Plaid Link failed to initialize");
+      },
+      { once: true },
+    );
+    script.addEventListener("error", () => fail("Failed to load Plaid Link"), {
+      once: true,
+    });
+    document.head.append(script);
+  });
+
+  return plaidScriptPromise;
+}
+
+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 async function openPlaidLink({
+  token,
+  onSuccess,
+  onExit,
+  signal,
+}: OpenPlaidLinkInput): Promise<() => void> {
+  await loadPlaidScript();
+  if (signal?.aborted) {
+    return () => {};
+  }
+  if (!window.Plaid) {
+    throw new Error("Plaid Link failed to initialize");
+  }
+
+  const handler = window.Plaid.create({
+    token,
+    onSuccess,
+    onExit: (error) => {
+      onExit?.(error);
+    },
+  });
+  if (signal?.aborted) {
+    handler.destroy();
+    return () => {};
+  }
+  handler.open();
+
+  return () => {
+    handler.destroy();
+  };
+}