@amos.com/amos-js 0.1.0

package/src/messaging.ts

@@ -0,0 +1,175 @@
+import type { components } from "@amos.com/node";
+import { decodeJwt } from "./jwt";
+import { type Appearance, createMessage, type Message } from "./types";
+
+type Iframe = HTMLIFrameElement | null | undefined;
+
+/**
+ * Notify the embedded iframe that the host page is ready to receive
+ * messages. The SDK calls this internally after receiving an
+ * `IFRAME_READY` event from the iframe.
+ */
+export function sendParentReadyMessage(iframe: Iframe): void {
+  iframe?.contentWindow?.postMessage(
+    createMessage({ type: "PARENT_ACKNOWLEDGED_IFRAME_READY" }),
+    "*",
+  );
+}
+
+/**
+ * Push appearance overrides into the embedded iframe.
+ *
+ * Only the provided `themeVariables` are sent; omitted variables keep
+ * their defaults.
+ */
+export function updateAppearance({
+  iframe,
+  appearance = {},
+}: {
+  iframe: Iframe;
+  appearance?: Appearance;
+}): void {
+  iframe?.contentWindow?.postMessage(
+    createMessage({ type: "UPDATE_APPEARANCE", appearance }),
+    "*",
+  );
+}
+
+/**
+ * Push the express-checkout amount into the embedded Google Pay iframe.
+ */
+export function updateAmount({
+  iframe,
+  amount,
+}: {
+  iframe: Iframe;
+  amount: string;
+}): void {
+  iframe?.contentWindow?.postMessage(
+    createMessage({ type: "UPDATE_AMOUNT", amount }),
+    "*",
+  );
+}
+
+/**
+ * Push the user-visible merchant name into the embedded Google Pay
+ * iframe.
+ */
+export function updateMerchantName({
+  iframe,
+  merchantName,
+}: {
+  iframe: Iframe;
+  merchantName: string;
+}): void {
+  iframe?.contentWindow?.postMessage(
+    createMessage({ type: "UPDATE_MERCHANT_NAME", merchantName }),
+    "*",
+  );
+}
+
+/**
+ * Ask the embedded credit-card or bank-account iframe form to validate
+ * its inputs.
+ *
+ * Resolves to `true` if the form is valid, `false` if it is not, or
+ * `false` if the iframe does not respond within 5 seconds.
+ */
+export function validateForm({ iframe }: { iframe: Iframe }): Promise<boolean> {
+  const requestId = crypto.randomUUID();
+
+  return new Promise((resolve) => {
+    iframe?.contentWindow?.postMessage(
+      createMessage({ type: "VALIDATE_FORM", requestId }),
+      "*",
+    );
+
+    const timeoutId = setTimeout(() => {
+      window.removeEventListener("message", handleMessage);
+      resolve(false);
+    }, 5000);
+
+    function handleMessage(event: MessageEvent<Message>) {
+      if (
+        event.data.type === "VALIDATE_FORM" &&
+        event.data.requestId === requestId
+      ) {
+        window.removeEventListener("message", handleMessage);
+        clearTimeout(timeoutId);
+        resolve(event.data.isValid ?? false);
+      }
+    }
+
+    window.addEventListener("message", handleMessage);
+  });
+}
+
+/**
+ * Confirm a payment intent in the embedded iframe flow.
+ *
+ * Pass the embed JWT (`token`) returned by your server's
+ * `POST /payment_intents` call. The matching `payment_intent_id` is
+ * extracted from the JWT payload and forwarded to the iframe.
+ */
+export function confirmPaymentIntent({
+  iframe,
+  token,
+}: {
+  iframe: Iframe;
+} & Pick<components["schemas"]["EmbedToken"], "token">): void {
+  const { payment_intent_id: id }: components["schemas"]["EmbedTokenJwt"] =
+    decodeJwt(token).payload;
+  iframe?.contentWindow?.postMessage(
+    createMessage({
+      type: "CONFIRM_PAYMENT_INTENT",
+      token,
+      id: id ?? undefined,
+    }),
+    "*",
+  );
+}
+
+/**
+ * Confirm a setup intent in the embedded iframe flow.
+ *
+ * Pass the embed JWT (`token`) returned by your server's
+ * `POST /setup_intents` call. The matching `setup_intent_id` is
+ * extracted from the JWT payload and forwarded to the iframe.
+ */
+export function confirmSetupIntent({
+  iframe,
+  token,
+}: {
+  iframe: Iframe;
+} & Pick<components["schemas"]["EmbedToken"], "token">): void {
+  const { setup_intent_id: id }: components["schemas"]["EmbedTokenJwt"] =
+    decodeJwt(token).payload;
+  iframe?.contentWindow?.postMessage(
+    createMessage({
+      type: "CONFIRM_SETUP_INTENT",
+      token,
+      id: id ?? undefined,
+    }),
+    "*",
+  );
+}
+
+/**
+ * Notify the iframe that confirmation failed (used by express-checkout
+ * flows after `onInitiatePaymentIntentRequest` rejects).
+ */
+export function sendConfirmationFailed({
+  iframe,
+  errorMessage,
+}: {
+  iframe: Iframe;
+  errorMessage: string;
+}): void {
+  iframe?.contentWindow?.postMessage(
+    createMessage({
+      type: "CONFIRMATION_FAILED",
+      errorMessage,
+    }),
+    "*",
+  );
+}

package/src/mount.ts

@@ -0,0 +1,278 @@
+import {
+  attachGooglePayButtonListeners,
+  type GooglePayButtonController,
+  type GooglePayButtonListenerOptions,
+  getGooglePayButtonInitialHeight,
+  getGooglePayButtonSrc,
+} from "./google-pay";
+import {
+  attachPaymentMethodFormListeners,
+  type CreditCardAdditionalFields,
+  getBankAccountFormInitialHeight,
+  getBankAccountFormSrc,
+  getCreditCardFormInitialHeight,
+  getCreditCardFormSrc,
+  type PaymentMethodFormController,
+  type PaymentMethodFormListenerOptions,
+} from "./payment-method-form";
+
+type Container = HTMLElement | string;
+
+function resolveContainer(container: Container): HTMLElement {
+  if (typeof container === "string") {
+    const element = document.querySelector(container);
+    if (!(element instanceof HTMLElement)) {
+      throw new Error(
+        `[amos-js] Container "${container}" did not match any HTMLElement.`,
+      );
+    }
+    return element;
+  }
+  return container;
+}
+
+const SHARED_IFRAME_STYLE: Partial<CSSStyleDeclaration> = {
+  width: "calc(100% + 8px)",
+  transition: "opacity 150ms ease-in, height 200ms ease-in-out",
+  margin: "0 -4px",
+  opacity: "0",
+  border: "0",
+};
+
+function createIframe({
+  src,
+  title,
+  name,
+  height,
+  allow,
+}: {
+  src: string;
+  title: string;
+  name: string;
+  height: string;
+  allow?: string;
+}): HTMLIFrameElement {
+  const iframe = document.createElement("iframe");
+  iframe.src = src;
+  iframe.title = title;
+  iframe.name = name;
+  iframe.setAttribute("role", "presentation");
+  iframe.scrolling = "no";
+  if (allow) {
+    iframe.allow = allow;
+  }
+  Object.assign(iframe.style, SHARED_IFRAME_STYLE, { height });
+  return iframe;
+}
+
+/**
+ * Options accepted by {@link mountAmosCreditCardPaymentMethodForm}.
+ */
+export type AmosCreditCardPaymentMethodFormOptions =
+  PaymentMethodFormListenerOptions & {
+    /**
+     * The Amos render token for the credit-card payment method form.
+     *
+     * It is safe to pass this to the client. Create this on
+     * https://dashboard.amos.com.
+     */
+    renderToken: string;
+    /**
+     * The additional fields that are required to be filled out in the
+     * form in addition to the card number, expiration date, CVV,
+     * country, and postal code.
+     *
+     * @default { cardholderName: false }
+     */
+    additionalFields?: CreditCardAdditionalFields;
+  };
+
+/**
+ * Controller returned by {@link mountAmosCreditCardPaymentMethodForm}
+ * and {@link mountAmosBankAccountPaymentMethodForm}.
+ */
+export type AmosPaymentMethodFormMountController =
+  PaymentMethodFormController & {
+    /**
+     * The underlying `<iframe>` element. Pass this as the `iframe`
+     * argument to {@link validateForm}, {@link confirmPaymentIntent}, or
+     * {@link confirmSetupIntent}.
+     */
+    iframe: HTMLIFrameElement;
+  };
+
+/**
+ * Mount the secure credit-card payment method form into a container
+ * element. Returns a controller exposing the underlying iframe, an
+ * `update()` method, and a `destroy()` method.
+ *
+ * Use the returned `controller.iframe` when calling
+ * {@link validateForm}, {@link confirmPaymentIntent}, or
+ * {@link confirmSetupIntent}.
+ */
+export function mountAmosCreditCardPaymentMethodForm(
+  container: Container,
+  options: AmosCreditCardPaymentMethodFormOptions,
+): AmosPaymentMethodFormMountController {
+  const host = resolveContainer(container);
+  const {
+    renderToken,
+    additionalFields = { cardholderName: false },
+    ...listenerOptions
+  } = options;
+
+  const iframe = createIframe({
+    src: getCreditCardFormSrc(renderToken, additionalFields),
+    title: "Secure credit card payment method form powered by Amos",
+    name: "amos-credit-card-payment-method-form",
+    height: getCreditCardFormInitialHeight(additionalFields),
+  });
+  host.appendChild(iframe);
+
+  const controller = attachPaymentMethodFormListeners(iframe, {
+    ...listenerOptions,
+    onHeightChange: (height) => {
+      iframe.style.height = height;
+      listenerOptions.onHeightChange?.(height);
+    },
+    onAppearanceReady: () => {
+      iframe.style.opacity = "1";
+      listenerOptions.onAppearanceReady?.();
+    },
+  });
+
+  return {
+    iframe,
+    update: controller.update,
+    destroy() {
+      controller.destroy();
+      iframe.remove();
+    },
+  };
+}
+
+/**
+ * Options accepted by {@link mountAmosBankAccountPaymentMethodForm}.
+ */
+export type AmosBankAccountPaymentMethodFormOptions =
+  PaymentMethodFormListenerOptions & {
+    /**
+     * The Amos render token for the bank-account payment method form.
+     *
+     * It is safe to pass this to the client. Create this on
+     * https://dashboard.amos.com.
+     */
+    renderToken: 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.
+ *
+ * Use the returned `controller.iframe` when calling
+ * {@link validateForm}, {@link confirmPaymentIntent}, or
+ * {@link confirmSetupIntent}.
+ */
+export function mountAmosBankAccountPaymentMethodForm(
+  container: Container,
+  options: AmosBankAccountPaymentMethodFormOptions,
+): AmosPaymentMethodFormMountController {
+  const host = resolveContainer(container);
+  const { renderToken, ...listenerOptions } = options;
+
+  const iframe = createIframe({
+    src: getBankAccountFormSrc(renderToken),
+    title: "Secure bank account payment method form powered by Amos",
+    name: "amos-bank-account-payment-method-form",
+    height: getBankAccountFormInitialHeight(),
+  });
+  host.appendChild(iframe);
+
+  const controller = attachPaymentMethodFormListeners(iframe, {
+    ...listenerOptions,
+    onHeightChange: (height) => {
+      iframe.style.height = height;
+      listenerOptions.onHeightChange?.(height);
+    },
+    onAppearanceReady: () => {
+      iframe.style.opacity = "1";
+      listenerOptions.onAppearanceReady?.();
+    },
+  });
+
+  return {
+    iframe,
+    update: controller.update,
+    destroy() {
+      controller.destroy();
+      iframe.remove();
+    },
+  };
+}
+
+/**
+ * Options accepted by {@link mountAmosGooglePayButton}.
+ */
+export type AmosGooglePayButtonOptions = GooglePayButtonListenerOptions & {
+  /**
+   * The Amos render token for the Google Pay button.
+   *
+   * It is safe to pass this to the client. Create this on
+   * https://dashboard.amos.com.
+   */
+  renderToken: string;
+};
+
+/**
+ * Controller returned by {@link mountAmosGooglePayButton}.
+ */
+export type AmosGooglePayButtonMountController = GooglePayButtonController & {
+  /**
+   * The underlying `<iframe>` element.
+   */
+  iframe: HTMLIFrameElement;
+};
+
+/**
+ * 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.
+ */
+export function mountAmosGooglePayButton(
+  container: Container,
+  options: AmosGooglePayButtonOptions,
+): AmosGooglePayButtonMountController {
+  const host = resolveContainer(container);
+  const { renderToken, ...listenerOptions } = options;
+
+  const iframe = createIframe({
+    src: getGooglePayButtonSrc(renderToken),
+    title: "Secure Google Pay button powered by Amos",
+    name: "amos-google-pay-button",
+    height: getGooglePayButtonInitialHeight(),
+    allow: "payment",
+  });
+  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 {
+    iframe,
+    update: controller.update,
+    destroy() {
+      controller.destroy();
+      iframe.remove();
+    },
+  };
+}

package/src/payment-method-form.ts

@@ -0,0 +1,180 @@
+import type { components } from "@amos.com/node";
+import { getEmbedOrigin } from "./jwt";
+import {
+  sendParentReadyMessage,
+  updateAppearance as sendUpdateAppearance,
+} from "./messaging";
+import type { Appearance, Message } from "./types";
+
+/**
+ * The additional fields beyond the standard card number, expiration
+ * date, CVV, country, and postal code that are required to be filled
+ * out in the embedded credit-card form.
+ */
+export type CreditCardAdditionalFields = {
+  cardholderName: boolean;
+};
+
+/**
+ * Build the iframe `src` URL for the embedded credit-card form.
+ */
+export function getCreditCardFormSrc(
+  renderToken: string,
+  additionalFields: CreditCardAdditionalFields = { cardholderName: false },
+): string {
+  const enabled = Object.entries(additionalFields)
+    .filter(([, value]) => value)
+    .map(([key]) => key)
+    .join(",");
+
+  return `${getEmbedOrigin(renderToken)}/iframe/card?token=${renderToken}&additionalFields=${enabled}`;
+}
+
+/**
+ * Build the iframe `src` URL for the embedded bank-account form.
+ */
+export function getBankAccountFormSrc(renderToken: string): string {
+  return `${getEmbedOrigin(renderToken)}/iframe/bank?token=${renderToken}`;
+}
+
+/**
+ * Default iframe pixel height for the credit-card form, taking the
+ * configured `additionalFields` into account.
+ */
+export function getCreditCardFormInitialHeight(
+  additionalFields: CreditCardAdditionalFields = { cardholderName: false },
+): string {
+  return additionalFields.cardholderName ? "292px" : "212px";
+}
+
+/**
+ * Default iframe pixel height for the bank-account form.
+ */
+export function getBankAccountFormInitialHeight(): string {
+  return "400px";
+}
+
+/**
+ * Options accepted by {@link attachPaymentMethodFormListeners}.
+ *
+ * Used by both the credit-card and bank-account forms, which share the
+ * same message protocol.
+ */
+export type PaymentMethodFormListenerOptions = {
+  /**
+   * Custom appearance to apply when the iframe first becomes ready and
+   * whenever the appearance changes. Can be updated later via the
+   * returned controller's `update({ appearance })` method.
+   */
+  appearance?: Appearance;
+  /**
+   * Called whenever the iframe asks the host page to resize it. Update
+   * the iframe's `height` style here.
+   */
+  onHeightChange?: (height: string) => void;
+  /**
+   * Called once the iframe has applied the requested appearance and is
+   * ready to be revealed. A common implementation is to set the
+   * iframe's opacity from `0` to `1` to fade it in.
+   */
+  onAppearanceReady?: () => void;
+  /**
+   * Called when payment intent confirmation succeeds.
+   */
+  onPaymentIntentConfirmationSucceeded?: (
+    paymentIntent: components["schemas"]["PaymentIntent"],
+  ) => void;
+  /**
+   * Called when setup intent confirmation succeeds.
+   */
+  onSetupIntentConfirmationSucceeded?: (
+    setupIntent: components["schemas"]["SetupIntent"],
+  ) => void;
+  /**
+   * Called when payment or setup intent confirmation fails.
+   */
+  onConfirmationFailed: (errorMessage: string) => void;
+};
+
+/**
+ * Controller returned by {@link attachPaymentMethodFormListeners} and
+ * the credit-card / bank-account `mount*` helpers.
+ */
+export type PaymentMethodFormController = {
+  /**
+   * Update one or more listener options without re-attaching the
+   * message listener. Pass `{ appearance }` to push new appearance
+   * overrides into the iframe.
+   */
+  update: (patch: Partial<PaymentMethodFormListenerOptions>) => void;
+  /**
+   * Detach the iframe message listener.
+   */
+  destroy: () => void;
+};
+
+/**
+ * Wire up the host-page side of the credit-card or bank-account iframe
+ * message protocol on an existing `<iframe>` element. Returns a
+ * controller for updating options and tearing down the listener.
+ *
+ * The iframe is expected to have already been added to the DOM with the
+ * correct `src` (see {@link getCreditCardFormSrc} /
+ * {@link getBankAccountFormSrc}).
+ */
+export function attachPaymentMethodFormListeners(
+  iframe: HTMLIFrameElement,
+  options: PaymentMethodFormListenerOptions,
+): PaymentMethodFormController {
+  let current = { ...options };
+
+  function handleMessage(event: MessageEvent<Message>) {
+    switch (event.data.type) {
+      case "IFRAME_READY":
+        sendParentReadyMessage(iframe);
+        sendUpdateAppearance({ iframe, appearance: current.appearance });
+        break;
+
+      case "UPDATE_HEIGHT":
+        current.onHeightChange?.(event.data.height);
+        break;
+
+      case "UPDATE_APPEARANCE":
+        sendUpdateAppearance({ iframe, appearance: event.data.appearance });
+        break;
+
+      case "UPDATED_APPEARANCE":
+        current.onAppearanceReady?.();
+        break;
+
+      case "PAYMENT_INTENT_CONFIRMATION_SUCCEEDED":
+        current.onPaymentIntentConfirmationSucceeded?.(
+          event.data.paymentIntent,
+        );
+        break;
+
+      case "SETUP_INTENT_CONFIRMATION_SUCCEEDED":
+        current.onSetupIntentConfirmationSucceeded?.(event.data.setupIntent);
+        break;
+
+      case "CONFIRMATION_FAILED":
+        current.onConfirmationFailed(event.data.errorMessage);
+        break;
+    }
+  }
+
+  window.addEventListener("message", handleMessage);
+
+  return {
+    update(patch) {
+      const hadAppearance = "appearance" in patch;
+      current = { ...current, ...patch };
+      if (hadAppearance) {
+        sendUpdateAppearance({ iframe, appearance: current.appearance });
+      }
+    },
+    destroy() {
+      window.removeEventListener("message", handleMessage);
+    },
+  };
+}