@amos.com/amos-js 0.9.9 → 0.9.11

package/dist/types.d.ts

@@ -1,4 +1,12 @@
 import { components } from '@amos.com/node';
+/**
+ * PCI-safe snapshot of card/bank form validity, posted when HTML
+ * constraint validation changes. Use this to enable or disable a host
+ * checkout button.
+ */
+export type PaymentMethodFormValidityChangeEvent = {
+    isValid: boolean;
+};
 /**
  * Why an interactive confirmation attempt ended with `status: "incomplete"`.
  *
@@ -69,6 +77,99 @@ export type Appearance = {
      */
     labels?: AppearanceLabels;
 };
+/**
+ * Inline style bag sent through `postMessage` to the wallet-button iframe.
+ *
+ * Matches the serializable subset of a CSSStyleDeclaration / React
+ * `CSSProperties` object (string or number values). Custom properties such
+ * as `--apple-pay-button-height` are allowed.
+ */
+export type WalletButtonStyle = {
+    [property: string]: string | number | undefined;
+};
+/**
+ * `buttonstyle` attribute on Apple's `<apple-pay-button>`.
+ *
+ * @see https://developer.apple.com/documentation/apple_pay_on_the_web/apple-pay-button
+ */
+export type ApplePayButtonStyle = "black" | "white" | "white-outline";
+/**
+ * `type` attribute on Apple's `<apple-pay-button>`.
+ *
+ * @see https://developer.apple.com/documentation/apple_pay_on_the_web/apple-pay-button
+ */
+export type ApplePayButtonType = "plain" | "buy" | "set-up" | "donate" | "check-out" | "book" | "subscribe" | "reload" | "add-money" | "top-up" | "order" | "rent" | "support" | "contribute" | "tip";
+/**
+ * Visual props for Apple's `<apple-pay-button>`, using Apple's attribute
+ * names. Applied inside the Amos embed iframe.
+ *
+ * @see https://developer.apple.com/documentation/apple_pay_on_the_web/apple-pay-button
+ */
+export type ApplePayButtonElementProps = {
+    /**
+     * Apple Pay button color.
+     *
+     * @default "black"
+     */
+    buttonstyle?: ApplePayButtonStyle;
+    /**
+     * Apple Pay button label / verb.
+     *
+     * @default "plain"
+     */
+    type?: ApplePayButtonType;
+    /**
+     * BCP 47 locale for the button label (e.g. `"en-US"`).
+     *
+     * @default "en-US"
+     */
+    locale?: string;
+    /**
+     * Inline style for the `<apple-pay-button>`. Height is controlled with
+     * `--apple-pay-button-height` (Apple ignores CSS `height`). Width uses
+     * `--apple-pay-button-width` or CSS `width`.
+     */
+    style?: WalletButtonStyle;
+};
+/**
+ * Visual props for Google's Pay button, using `@google-pay/button-react`
+ * / Google Pay API names. Applied inside the Amos embed iframe.
+ *
+ * @see https://developers.google.com/pay/api/web/guides/resources/customize
+ */
+export type GooglePayButtonElementProps = {
+    /**
+     * Button label / verb.
+     *
+     * @default "short"
+     */
+    buttonType?: google.payments.api.ButtonType;
+    /** Button color. */
+    buttonColor?: google.payments.api.ButtonColor;
+    /** Corner radius in pixels (0–20). */
+    buttonRadius?: number;
+    /**
+     * `"fill"` stretches the button to the container width; `"static"`
+     * uses Google's default size.
+     */
+    buttonSizeMode?: google.payments.api.ButtonSizeMode;
+    /** BCP 47 locale for the button label (e.g. `"en"`). */
+    buttonLocale?: string;
+    /** Whether the button draws a border. */
+    buttonBorderType?: google.payments.api.ButtonBorderType;
+    /**
+     * Inline style for the Google Pay button wrapper. Use `height` /
+     * `width` here (unlike Apple Pay, Google honors CSS `height`).
+     */
+    style?: WalletButtonStyle;
+};
+/**
+ * Keep only JSON-cloneable string/number declarations from a style object
+ * before sending it through `postMessage`.
+ */
+export declare function serializeWalletButtonStyle(style: WalletButtonStyle | undefined): Record<string, string | number> | undefined;
+export declare function pickApplePayButtonElementProps(options: ApplePayButtonElementProps): ApplePayButtonElementProps;
+export declare function pickGooglePayButtonElementProps(options: GooglePayButtonElementProps): GooglePayButtonElementProps;
 /**
  * Typed `postMessage` payloads exchanged between the host page and the
  * embedded Amos iframe.
@@ -95,6 +196,18 @@ export type Message = {
     /** Parent → embed: push appearance overrides into the iframe. */
     type: "UPDATE_APPEARANCE";
     appearance: Appearance;
+} | {
+    /**
+     * Parent → embed: visual options for the Apple Pay button. Nested
+     * under `props` so Apple's `type` attribute does not collide with
+     * this message discriminant.
+     */
+    type: "UPDATE_APPLE_PAY_BUTTON";
+    props: ApplePayButtonElementProps;
+} | {
+    /** Parent → embed: visual options for the Google Pay button. */
+    type: "UPDATE_GOOGLE_PAY_BUTTON";
+    props: GooglePayButtonElementProps;
 } | {
     /**
      * Parent → embed: validate form inputs (`requestId` only).
@@ -138,6 +251,14 @@ export type Message = {
 } | {
     /** Parent → embed: clear all form field values and API errors. */
     type: "RESET_FORM";
+} | {
+    /**
+     * Embed → parent: card/bank form validity changed.
+     * `isValid` is true when all required fields are present and
+     * valid. Does not include PCI data.
+     */
+    type: "FORM_VALIDITY_CHANGE";
+    isValid: boolean;
 };
 /**
  * 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.9",
+  "version": "0.9.11",
   "main": "dist/index.js",
   "repository": {
     "type": "git",

package/src/apple-pay.ts

@@ -10,10 +10,12 @@ import {
   sendParentReadyMessage,
   updateAmount as sendUpdateAmount,
   updateAppearance as sendUpdateAppearance,
+  updateApplePayButton as sendUpdateApplePayButton,
   updateMerchantName as sendUpdateMerchantName,
 } from "./messaging";
 import {
   type Appearance,
+  type ApplePayButtonElementProps,
   type ConfirmationResult,
   createMessage,
   type Message,
@@ -36,7 +38,7 @@ export function getApplePayButtonInitialHeight(): string {
 /**
  * Options accepted by {@link attachApplePayButtonListeners}.
  */
-export type ApplePayButtonListenerOptions = {
+export type ApplePayButtonListenerOptions = ApplePayButtonElementProps & {
   /** The amount of the payment, in the same format passed in props. */
   amount: string;
   /** A user-visible merchant name. */
@@ -83,7 +85,9 @@ export type ApplePayButtonController = {
   /**
    * Update one or more listener options without re-attaching the
    * message listener. Pass `amount` or `merchantName` to push the new
-   * value into the iframe; pass `appearance` to update theme variables.
+   * value into the iframe; pass `appearance` to update theme variables;
+   * pass `buttonstyle`, `type`, `locale`, or `style` to restyle the
+   * Apple Pay button.
    */
   update: (patch: Partial<ApplePayButtonListenerOptions>) => void;
   /**
@@ -126,6 +130,10 @@ export function attachApplePayButtonListeners(
     sendUpdateMerchantName({ iframe, merchantName: current.merchantName });
   }
 
+  function pushButtonProps() {
+    sendUpdateApplePayButton({ iframe, props: current });
+  }
+
   function handleMessage(event: MessageEvent<Message>) {
     // Ignore messages from other frames / windows.
     if (event.source !== iframe.contentWindow) {
@@ -138,6 +146,7 @@ export function attachApplePayButtonListeners(
         sendUpdateAppearance({ iframe, appearance: current.appearance });
         pushAmount();
         pushMerchantName();
+        pushButtonProps();
         break;
 
       case "UPDATE_HEIGHT":
@@ -199,6 +208,11 @@ export function attachApplePayButtonListeners(
       const hadAppearance = "appearance" in patch;
       const hadAmount = "amount" in patch;
       const hadMerchantName = "merchantName" in patch;
+      const hadButtonProps =
+        "buttonstyle" in patch ||
+        "type" in patch ||
+        "locale" in patch ||
+        "style" in patch;
       current = { ...current, ...patch };
       if (hadAppearance) {
         sendUpdateAppearance({ iframe, appearance: current.appearance });
@@ -209,6 +223,9 @@ export function attachApplePayButtonListeners(
       if (hadMerchantName) {
         pushMerchantName();
       }
+      if (hadButtonProps) {
+        pushButtonProps();
+      }
     },
     destroy() {
       window.removeEventListener("message", handleMessage);

package/src/google-pay.ts

@@ -7,9 +7,15 @@ import {
   sendParentReadyMessage,
   updateAmount as sendUpdateAmount,
   updateAppearance as sendUpdateAppearance,
+  updateGooglePayButton as sendUpdateGooglePayButton,
   updateMerchantName as sendUpdateMerchantName,
 } from "./messaging";
-import type { Appearance, ConfirmationResult, Message } from "./types";
+import type {
+  Appearance,
+  ConfirmationResult,
+  GooglePayButtonElementProps,
+  Message,
+} from "./types";
 
 /**
  * Build the iframe `src` URL for the embedded Google Pay button.
@@ -28,7 +34,7 @@ export function getGooglePayButtonInitialHeight(): string {
 /**
  * Options accepted by {@link attachGooglePayButtonListeners}.
  */
-export type GooglePayButtonListenerOptions = {
+export type GooglePayButtonListenerOptions = GooglePayButtonElementProps & {
   /** The amount of the payment, in the same format passed in props. */
   amount: string;
   /** A user-visible merchant name. */
@@ -75,7 +81,10 @@ export type GooglePayButtonController = {
   /**
    * Update one or more listener options without re-attaching the
    * message listener. Pass `amount` or `merchantName` to push the new
-   * value into the iframe; pass `appearance` to update theme variables.
+   * value into the iframe; pass `appearance` to update theme variables;
+   * pass `buttonType`, `buttonColor`, `buttonRadius`, `buttonSizeMode`,
+   * `buttonLocale`, `buttonBorderType`, or `style` to restyle the
+   * Google Pay button.
    */
   update: (patch: Partial<GooglePayButtonListenerOptions>) => void;
   /**
@@ -106,6 +115,10 @@ export function attachGooglePayButtonListeners(
     sendUpdateMerchantName({ iframe, merchantName: current.merchantName });
   }
 
+  function pushButtonProps() {
+    sendUpdateGooglePayButton({ iframe, props: current });
+  }
+
   function handleMessage(event: MessageEvent<Message>) {
     if (event.source !== iframe.contentWindow) {
       return;
@@ -117,6 +130,7 @@ export function attachGooglePayButtonListeners(
         sendUpdateAppearance({ iframe, appearance: current.appearance });
         pushAmount();
         pushMerchantName();
+        pushButtonProps();
         break;
 
       case "UPDATE_HEIGHT":
@@ -163,6 +177,14 @@ export function attachGooglePayButtonListeners(
       const hadAppearance = "appearance" in patch;
       const hadAmount = "amount" in patch;
       const hadMerchantName = "merchantName" in patch;
+      const hadButtonProps =
+        "buttonType" in patch ||
+        "buttonColor" in patch ||
+        "buttonRadius" in patch ||
+        "buttonSizeMode" in patch ||
+        "buttonLocale" in patch ||
+        "buttonBorderType" in patch ||
+        "style" in patch;
       current = { ...current, ...patch };
       if (hadAppearance) {
         sendUpdateAppearance({ iframe, appearance: current.appearance });
@@ -173,6 +195,9 @@ export function attachGooglePayButtonListeners(
       if (hadMerchantName) {
         pushMerchantName();
       }
+      if (hadButtonProps) {
+        pushButtonProps();
+      }
     },
     destroy() {
       window.removeEventListener("message", handleMessage);

package/src/index.ts

@@ -32,6 +32,8 @@ export {
   sendParentReadyMessage,
   updateAmount,
   updateAppearance,
+  updateApplePayButton,
+  updateGooglePayButton,
   updateMerchantName,
   validateForm,
 } from "./messaging";
@@ -66,9 +68,20 @@ export {
 export type {
   Appearance,
   AppearanceLabels,
+  ApplePayButtonElementProps,
+  ApplePayButtonStyle,
+  ApplePayButtonType,
   ConfirmationIncompleteReason,
   ConfirmationResult,
+  GooglePayButtonElementProps,
   Message,
+  PaymentMethodFormValidityChangeEvent,
   ThemeVariable,
+  WalletButtonStyle,
+} from "./types";
+export {
+  createMessage,
+  pickApplePayButtonElementProps,
+  pickGooglePayButtonElementProps,
+  serializeWalletButtonStyle,
 } from "./types";
-export { createMessage } from "./types";

package/src/messaging.ts

@@ -1,6 +1,14 @@
 import type { components } from "@amos.com/node";
 import { decodeJwt } from "./jwt";
-import { type Appearance, createMessage, type Message } from "./types";
+import {
+  type Appearance,
+  type ApplePayButtonElementProps,
+  createMessage,
+  type GooglePayButtonElementProps,
+  type Message,
+  pickApplePayButtonElementProps,
+  pickGooglePayButtonElementProps,
+} from "./types";
 
 type Iframe = HTMLIFrameElement | null | undefined;
 
@@ -55,6 +63,52 @@ export function updateAppearance({
   );
 }
 
+/**
+ * Push Apple Pay button visual options into the embedded iframe.
+ */
+export function updateApplePayButton({
+  iframe,
+  props,
+}: {
+  iframe: Iframe;
+  props: ApplePayButtonElementProps;
+}): void {
+  if (!iframe?.contentWindow) {
+    return;
+  }
+
+  iframe.contentWindow.postMessage(
+    createMessage({
+      type: "UPDATE_APPLE_PAY_BUTTON",
+      props: pickApplePayButtonElementProps(props),
+    }),
+    getIframeTargetOrigin(iframe),
+  );
+}
+
+/**
+ * Push Google Pay button visual options into the embedded iframe.
+ */
+export function updateGooglePayButton({
+  iframe,
+  props,
+}: {
+  iframe: Iframe;
+  props: GooglePayButtonElementProps;
+}): void {
+  if (!iframe?.contentWindow) {
+    return;
+  }
+
+  iframe.contentWindow.postMessage(
+    createMessage({
+      type: "UPDATE_GOOGLE_PAY_BUTTON",
+      props: pickGooglePayButtonElementProps(props),
+    }),
+    getIframeTargetOrigin(iframe),
+  );
+}
+
 /**
  * Push the express-checkout amount into the embedded Google Pay iframe.
  */

package/src/payment-method-form.ts

@@ -3,7 +3,12 @@ import {
   sendParentReadyMessage,
   updateAppearance as sendUpdateAppearance,
 } from "./messaging";
-import type { Appearance, ConfirmationResult, Message } from "./types";
+import type {
+  Appearance,
+  ConfirmationResult,
+  Message,
+  PaymentMethodFormValidityChangeEvent,
+} from "./types";
 
 /**
  * The additional fields beyond the standard card number, expiration
@@ -126,6 +131,12 @@ export type PaymentMethodFormListenerOptions = {
    * iframe's opacity from `0` to `1` to fade it in.
    */
   onAppearanceReady?: () => void;
+  /**
+   * Called when card/bank form validity changes. `isValid` is true
+   * when all required fields are present and valid. Does not include
+   * PCI data. Use this to enable or disable a host checkout button.
+   */
+  onValidityChange?: (event: PaymentMethodFormValidityChangeEvent) => void;
   /**
    * Called when the interactive confirmation flow finishes (success or
    * terminal failure). Not settlement proof — verify via webhooks.
@@ -191,6 +202,10 @@ export function attachPaymentMethodFormListeners(
         current.onAppearanceReady?.();
         break;
 
+      case "FORM_VALIDITY_CHANGE":
+        current.onValidityChange?.({ isValid: event.data.isValid });
+        break;
+
       case "CONFIRMATION_RESULT":
         current.onResult(event.data.result);
         break;

package/src/types.ts

@@ -1,5 +1,16 @@
+/// <reference types="googlepay" />
+
 import type { components } from "@amos.com/node";
 
+/**
+ * PCI-safe snapshot of card/bank form validity, posted when HTML
+ * constraint validation changes. Use this to enable or disable a host
+ * checkout button.
+ */
+export type PaymentMethodFormValidityChangeEvent = {
+  isValid: boolean;
+};
+
 /**
  * Why an interactive confirmation attempt ended with `status: "incomplete"`.
  *
@@ -303,6 +314,193 @@ export type Appearance = {
   labels?: AppearanceLabels;
 };
 
+/**
+ * Inline style bag sent through `postMessage` to the wallet-button iframe.
+ *
+ * Matches the serializable subset of a CSSStyleDeclaration / React
+ * `CSSProperties` object (string or number values). Custom properties such
+ * as `--apple-pay-button-height` are allowed.
+ */
+export type WalletButtonStyle = {
+  [property: string]: string | number | undefined;
+};
+
+/**
+ * `buttonstyle` attribute on Apple's `<apple-pay-button>`.
+ *
+ * @see https://developer.apple.com/documentation/apple_pay_on_the_web/apple-pay-button
+ */
+export type ApplePayButtonStyle = "black" | "white" | "white-outline";
+
+/**
+ * `type` attribute on Apple's `<apple-pay-button>`.
+ *
+ * @see https://developer.apple.com/documentation/apple_pay_on_the_web/apple-pay-button
+ */
+export type ApplePayButtonType =
+  | "plain"
+  | "buy"
+  | "set-up"
+  | "donate"
+  | "check-out"
+  | "book"
+  | "subscribe"
+  | "reload"
+  | "add-money"
+  | "top-up"
+  | "order"
+  | "rent"
+  | "support"
+  | "contribute"
+  | "tip";
+
+/**
+ * Visual props for Apple's `<apple-pay-button>`, using Apple's attribute
+ * names. Applied inside the Amos embed iframe.
+ *
+ * @see https://developer.apple.com/documentation/apple_pay_on_the_web/apple-pay-button
+ */
+export type ApplePayButtonElementProps = {
+  /**
+   * Apple Pay button color.
+   *
+   * @default "black"
+   */
+  buttonstyle?: ApplePayButtonStyle;
+  /**
+   * Apple Pay button label / verb.
+   *
+   * @default "plain"
+   */
+  type?: ApplePayButtonType;
+  /**
+   * BCP 47 locale for the button label (e.g. `"en-US"`).
+   *
+   * @default "en-US"
+   */
+  locale?: string;
+  /**
+   * Inline style for the `<apple-pay-button>`. Height is controlled with
+   * `--apple-pay-button-height` (Apple ignores CSS `height`). Width uses
+   * `--apple-pay-button-width` or CSS `width`.
+   */
+  style?: WalletButtonStyle;
+};
+
+/**
+ * Visual props for Google's Pay button, using `@google-pay/button-react`
+ * / Google Pay API names. Applied inside the Amos embed iframe.
+ *
+ * @see https://developers.google.com/pay/api/web/guides/resources/customize
+ */
+export type GooglePayButtonElementProps = {
+  /**
+   * Button label / verb.
+   *
+   * @default "short"
+   */
+  buttonType?: google.payments.api.ButtonType;
+  /** Button color. */
+  buttonColor?: google.payments.api.ButtonColor;
+  /** Corner radius in pixels (0–20). */
+  buttonRadius?: number;
+  /**
+   * `"fill"` stretches the button to the container width; `"static"`
+   * uses Google's default size.
+   */
+  buttonSizeMode?: google.payments.api.ButtonSizeMode;
+  /** BCP 47 locale for the button label (e.g. `"en"`). */
+  buttonLocale?: string;
+  /** Whether the button draws a border. */
+  buttonBorderType?: google.payments.api.ButtonBorderType;
+  /**
+   * Inline style for the Google Pay button wrapper. Use `height` /
+   * `width` here (unlike Apple Pay, Google honors CSS `height`).
+   */
+  style?: WalletButtonStyle;
+};
+
+/**
+ * Keep only JSON-cloneable string/number declarations from a style object
+ * before sending it through `postMessage`.
+ */
+export function serializeWalletButtonStyle(
+  style: WalletButtonStyle | undefined,
+): Record<string, string | number> | undefined {
+  if (!style || typeof style !== "object") {
+    return undefined;
+  }
+
+  const result: Record<string, string | number> = {};
+  for (const [key, value] of Object.entries(style)) {
+    if (typeof value === "string") {
+      if (value.length === 0) {
+        continue;
+      }
+      result[key] = value;
+      continue;
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+      result[key] = value;
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+export function pickApplePayButtonElementProps(
+  options: ApplePayButtonElementProps,
+): ApplePayButtonElementProps {
+  const props: ApplePayButtonElementProps = {};
+  if (options.buttonstyle !== undefined) {
+    props.buttonstyle = options.buttonstyle;
+  }
+  if (options.type !== undefined) {
+    props.type = options.type;
+  }
+  if (options.locale !== undefined) {
+    props.locale = options.locale;
+  }
+  if (options.style !== undefined) {
+    const style = serializeWalletButtonStyle(options.style);
+    if (style) {
+      props.style = style;
+    }
+  }
+  return props;
+}
+
+export function pickGooglePayButtonElementProps(
+  options: GooglePayButtonElementProps,
+): GooglePayButtonElementProps {
+  const props: GooglePayButtonElementProps = {};
+  if (options.buttonType !== undefined) {
+    props.buttonType = options.buttonType;
+  }
+  if (options.buttonColor !== undefined) {
+    props.buttonColor = options.buttonColor;
+  }
+  if (options.buttonRadius !== undefined) {
+    props.buttonRadius = options.buttonRadius;
+  }
+  if (options.buttonSizeMode !== undefined) {
+    props.buttonSizeMode = options.buttonSizeMode;
+  }
+  if (options.buttonLocale !== undefined) {
+    props.buttonLocale = options.buttonLocale;
+  }
+  if (options.buttonBorderType !== undefined) {
+    props.buttonBorderType = options.buttonBorderType;
+  }
+  if (options.style !== undefined) {
+    const style = serializeWalletButtonStyle(options.style);
+    if (style) {
+      props.style = style;
+    }
+  }
+  return props;
+}
+
 /**
  * Typed `postMessage` payloads exchanged between the host page and the
  * embedded Amos iframe.
@@ -336,6 +534,20 @@ export type Message =
       type: "UPDATE_APPEARANCE";
       appearance: Appearance;
     }
+  | {
+      /**
+       * Parent → embed: visual options for the Apple Pay button. Nested
+       * under `props` so Apple's `type` attribute does not collide with
+       * this message discriminant.
+       */
+      type: "UPDATE_APPLE_PAY_BUTTON";
+      props: ApplePayButtonElementProps;
+    }
+  | {
+      /** Parent → embed: visual options for the Google Pay button. */
+      type: "UPDATE_GOOGLE_PAY_BUTTON";
+      props: GooglePayButtonElementProps;
+    }
   | {
       /**
        * Parent → embed: validate form inputs (`requestId` only).
@@ -390,6 +602,15 @@ export type Message =
   | {
       /** Parent → embed: clear all form field values and API errors. */
       type: "RESET_FORM";
+    }
+  | {
+      /**
+       * Embed → parent: card/bank form validity changed.
+       * `isValid` is true when all required fields are present and
+       * valid. Does not include PCI data.
+       */
+      type: "FORM_VALIDITY_CHANGE";
+      isValid: boolean;
     };
 
 /**