@amos.com/amos-js 0.1.0

package/dist/src/mount.d.ts

@@ -0,0 +1,95 @@
+import { GooglePayButtonController, GooglePayButtonListenerOptions } from './google-pay';
+import { CreditCardAdditionalFields, PaymentMethodFormController, PaymentMethodFormListenerOptions } from './payment-method-form';
+type Container = HTMLElement | string;
+/**
+ * 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 declare function mountAmosCreditCardPaymentMethodForm(container: Container, options: AmosCreditCardPaymentMethodFormOptions): AmosPaymentMethodFormMountController;
+/**
+ * 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 declare function mountAmosBankAccountPaymentMethodForm(container: Container, options: AmosBankAccountPaymentMethodFormOptions): AmosPaymentMethodFormMountController;
+/**
+ * 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 declare function mountAmosGooglePayButton(container: Container, options: AmosGooglePayButtonOptions): AmosGooglePayButtonMountController;
+export {};

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

@@ -0,0 +1,90 @@
+import { components } from '@amos.com/node';
+import { Appearance } 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 declare function getCreditCardFormSrc(renderToken: string, additionalFields?: CreditCardAdditionalFields): string;
+/**
+ * Build the iframe `src` URL for the embedded bank-account form.
+ */
+export declare function getBankAccountFormSrc(renderToken: string): string;
+/**
+ * Default iframe pixel height for the credit-card form, taking the
+ * configured `additionalFields` into account.
+ */
+export declare function getCreditCardFormInitialHeight(additionalFields?: CreditCardAdditionalFields): string;
+/**
+ * Default iframe pixel height for the bank-account form.
+ */
+export declare function getBankAccountFormInitialHeight(): string;
+/**
+ * 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 declare function attachPaymentMethodFormListeners(iframe: HTMLIFrameElement, options: PaymentMethodFormListenerOptions): PaymentMethodFormController;

package/dist/src/types.d.ts

@@ -0,0 +1,64 @@
+import { components } from '@amos.com/node';
+/**
+ * CSS custom properties that control the appearance of the embedded
+ * Amos iframe UI. Only the variables you provide are sent; omitted
+ * variables keep their defaults.
+ */
+export type ThemeVariable = "--background" | "--foreground" | "--primary" | "--primary-foreground" | "--secondary" | "--secondary-foreground" | "--muted-foreground" | "--accent" | "--accent-foreground" | "--destructive" | "--border" | "--input" | "--ring" | "--radius";
+/**
+ * Appearance overrides for the embedded Amos iframe UI.
+ */
+export type Appearance = {
+    themeVariables?: Partial<Record<ThemeVariable, string>>;
+};
+/**
+ * Typed `postMessage` payloads exchanged between the host page and the
+ * embedded Amos iframe.
+ */
+export type Message = {
+    type: "IFRAME_READY";
+} | {
+    type: "PARENT_ACKNOWLEDGED_IFRAME_READY";
+} | {
+    type: "UPDATE_HEIGHT";
+    height: string;
+} | {
+    type: "UPDATE_AMOUNT";
+    amount: string;
+} | {
+    type: "UPDATE_MERCHANT_NAME";
+    merchantName: string;
+} | {
+    type: "UPDATE_APPEARANCE";
+    appearance: Appearance;
+} | {
+    type: "VALIDATE_FORM";
+    requestId: string;
+    isValid?: boolean;
+} | {
+    type: "CREATE_PAYMENT_INTENT";
+    paymentIntentCreateAttributes: components["schemas"]["CreatePaymentIntentInput"];
+    customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
+} | ({
+    type: "CONFIRM_PAYMENT_INTENT";
+} & Pick<components["schemas"]["PaymentIntent"], "id"> & Pick<components["schemas"]["EmbedToken"], "token">) | ({
+    type: "CONFIRM_SETUP_INTENT";
+} & Pick<components["schemas"]["SetupIntent"], "id"> & Pick<components["schemas"]["EmbedToken"], "token">) | {
+    type: "PAYMENT_INTENT_CONFIRMATION_SUCCEEDED";
+    paymentIntent: components["schemas"]["PaymentIntent"];
+} | {
+    type: "SETUP_INTENT_CONFIRMATION_SUCCEEDED";
+    setupIntent: components["schemas"]["SetupIntent"];
+} | {
+    type: "CONFIRMATION_FAILED";
+    errorMessage: string;
+} | {
+    type: "UPDATED_APPEARANCE";
+};
+/**
+ * Identity helper that brands an object as a typed `Message`.
+ *
+ * Useful when constructing `postMessage` payloads to ensure they conform
+ * to the schema understood by the embedded Amos iframe.
+ */
+export declare function createMessage(message: Message): Message;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@amos.com/amos-js",
+  "version": "0.1.0",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "biome": "biome check --write",
+    "dev": "vite",
+    "prebuild": "npm run typecheck",
+    "build": "vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "npm run build && changeset publish"
+  },
+  "author": "Amos",
+  "description": "Amos JavaScript SDK for embedding payment methods via iframes.",
+  "devDependencies": {
+    "@changesets/cli": "2.31.0",
+    "@biomejs/biome": "2.4.15",
+    "@types/node": "25.9.1",
+    "typescript": "6.0.3",
+    "vite": "7.3.3",
+    "vite-plugin-dts": "4.5.4"
+  },
+  "dependencies": {
+    "@amos.com/node": "0.1.6",
+    "@types/googlepay": "0.7.10"
+  },
+  "peerDependencies": {
+    "openapi-fetch": "^0 || ^1"
+  }
+}

package/src/google-pay.ts

@@ -0,0 +1,234 @@
+/// <reference types="googlepay" />
+
+import type { components } from "@amos.com/node";
+import { getEmbedOrigin } from "./jwt";
+import {
+  confirmPaymentIntent,
+  sendConfirmationFailed,
+  sendParentReadyMessage,
+  updateAmount as sendUpdateAmount,
+  updateAppearance as sendUpdateAppearance,
+  updateMerchantName as sendUpdateMerchantName,
+} from "./messaging";
+import type { Appearance, Message } from "./types";
+
+/**
+ * Build the iframe `src` URL for the embedded Google Pay button.
+ */
+export function getGooglePayButtonSrc(renderToken: string): string {
+  return `${getEmbedOrigin(renderToken)}/iframe/google-pay?token=${renderToken}`;
+}
+
+/**
+ * Default iframe pixel height for the Google Pay button.
+ */
+export function getGooglePayButtonInitialHeight(): string {
+  return "40px";
+}
+
+/**
+ * Options accepted by {@link attachGooglePayButtonListeners}.
+ */
+export type GooglePayButtonListenerOptions = {
+  /** The amount of the payment, in the same format passed in props. */
+  amount: string;
+  /** A user-visible merchant name. */
+  merchantName: string;
+  /**
+   * Custom appearance to apply when the iframe first becomes ready and
+   * whenever the appearance changes.
+   */
+  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.
+   */
+  onAppearanceReady?: () => void;
+  /**
+   * Called when the user initiates a payment intent request via the
+   * Google Pay button. Your implementation should create a payment
+   * intent on your server and resolve with the resulting embed token.
+   */
+  onInitiatePaymentIntentRequest: ({
+    paymentIntentCreateAttributes,
+    customerCreateAttributes,
+  }: {
+    paymentIntentCreateAttributes: components["schemas"]["CreatePaymentIntentInput"];
+    customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
+  }) => Promise<components["schemas"]["EmbedToken"]["token"]>;
+  /**
+   * Called when payment intent confirmation succeeds.
+   */
+  onPaymentIntentConfirmationSucceeded: (
+    paymentIntent: components["schemas"]["PaymentIntent"],
+  ) => void;
+  /**
+   * Called when payment intent confirmation fails.
+   */
+  onConfirmationFailed: (errorMessage: string) => void;
+};
+
+/**
+ * Controller returned by {@link attachGooglePayButtonListeners} and
+ * {@link mountAmosGooglePayButton}.
+ */
+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.
+   */
+  update: (patch: Partial<GooglePayButtonListenerOptions>) => void;
+  /**
+   * Detach the iframe message listener.
+   */
+  destroy: () => void;
+};
+
+/**
+ * Wire up the host-page side of the Google Pay 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 getGooglePayButtonSrc}).
+ */
+export function attachGooglePayButtonListeners(
+  iframe: HTMLIFrameElement,
+  options: GooglePayButtonListenerOptions,
+): GooglePayButtonController {
+  let current = { ...options };
+
+  function pushAmount() {
+    sendUpdateAmount({ iframe, amount: current.amount });
+  }
+
+  function pushMerchantName() {
+    sendUpdateMerchantName({ iframe, merchantName: current.merchantName });
+  }
+
+  function handleMessage(event: MessageEvent<Message>) {
+    switch (event.data.type) {
+      case "IFRAME_READY":
+        sendParentReadyMessage(iframe);
+        sendUpdateAppearance({ iframe, appearance: current.appearance });
+        pushAmount();
+        pushMerchantName();
+        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 "CREATE_PAYMENT_INTENT":
+        current
+          .onInitiatePaymentIntentRequest({
+            paymentIntentCreateAttributes:
+              event.data.paymentIntentCreateAttributes,
+            customerCreateAttributes: event.data.customerCreateAttributes,
+          })
+          .then((token) => {
+            confirmPaymentIntent({ iframe, token });
+          })
+          .catch((error: unknown) => {
+            sendConfirmationFailed({
+              iframe,
+              errorMessage:
+                error instanceof Error ? error.message : "Unknown error",
+            });
+          });
+        break;
+
+      case "PAYMENT_INTENT_CONFIRMATION_SUCCEEDED":
+        current.onPaymentIntentConfirmationSucceeded(event.data.paymentIntent);
+        break;
+
+      case "CONFIRMATION_FAILED":
+        current.onConfirmationFailed(event.data.errorMessage);
+        break;
+    }
+  }
+
+  window.addEventListener("message", handleMessage);
+
+  return {
+    update(patch) {
+      const hadAppearance = "appearance" in patch;
+      const hadAmount = "amount" in patch;
+      const hadMerchantName = "merchantName" in patch;
+      current = { ...current, ...patch };
+      if (hadAppearance) {
+        sendUpdateAppearance({ iframe, appearance: current.appearance });
+      }
+      if (hadAmount) {
+        pushAmount();
+      }
+      if (hadMerchantName) {
+        pushMerchantName();
+      }
+    },
+    destroy() {
+      window.removeEventListener("message", handleMessage);
+    },
+  };
+}
+
+/**
+ * Transform raw Google Pay payment data into an Amos-compatible
+ * `paymentMethod` payload. Use this when integrating with the raw
+ * Google Pay API directly instead of through
+ * {@link mountAmosGooglePayButton} (or the React equivalent).
+ */
+export function formatGooglePayPaymentData({
+  paymentData,
+}: {
+  paymentData: google.payments.api.PaymentData;
+}) {
+  return {
+    paymentMethod: {
+      billing_address_attributes: {
+        name: paymentData.shippingAddress?.name,
+        address_line1: paymentData.shippingAddress?.address1,
+        address_line2: paymentData.shippingAddress?.address2,
+        city: paymentData.shippingAddress?.locality,
+        state: paymentData.shippingAddress?.administrativeArea,
+        postal_code: paymentData.shippingAddress?.postalCode,
+        country: paymentData.shippingAddress?.countryCode,
+        email: paymentData.email,
+        phone: paymentData.shippingAddress?.phoneNumber,
+      },
+      card_profile_attributes: {
+        wallet_provider: "googlepay",
+        wallet_payload: paymentData.paymentMethodData.tokenizationData.token,
+        wallet_last4: paymentData.paymentMethodData.info?.cardDetails,
+        wallet_brand: (() => {
+          switch (paymentData.paymentMethodData.info?.cardNetwork) {
+            case "AMEX":
+              return "american_express";
+            case "VISA":
+              return "visa";
+            case "MASTERCARD":
+              return "master";
+            case "DISCOVER":
+              return "discover";
+            default:
+              return undefined;
+          }
+        })(),
+      },
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,101 @@
+/// <reference types="googlepay" />
+
+import type { components } from "@amos.com/node";
+
+export type {
+  GooglePayButtonController,
+  GooglePayButtonListenerOptions,
+} from "./google-pay";
+export {
+  attachGooglePayButtonListeners,
+  formatGooglePayPaymentData,
+  getGooglePayButtonInitialHeight,
+  getGooglePayButtonSrc,
+} from "./google-pay";
+
+export { decodeJwt, getEmbedOrigin } from "./jwt";
+
+export {
+  confirmPaymentIntent,
+  confirmSetupIntent,
+  sendConfirmationFailed,
+  sendParentReadyMessage,
+  updateAmount,
+  updateAppearance,
+  updateMerchantName,
+  validateForm,
+} from "./messaging";
+export type {
+  AmosBankAccountPaymentMethodFormOptions,
+  AmosCreditCardPaymentMethodFormOptions,
+  AmosGooglePayButtonMountController,
+  AmosGooglePayButtonOptions,
+  AmosPaymentMethodFormMountController,
+} from "./mount";
+export {
+  mountAmosBankAccountPaymentMethodForm,
+  mountAmosCreditCardPaymentMethodForm,
+  mountAmosGooglePayButton,
+} from "./mount";
+export type {
+  CreditCardAdditionalFields,
+  PaymentMethodFormController,
+  PaymentMethodFormListenerOptions,
+} from "./payment-method-form";
+export {
+  attachPaymentMethodFormListeners,
+  getBankAccountFormInitialHeight,
+  getBankAccountFormSrc,
+  getCreditCardFormInitialHeight,
+  getCreditCardFormSrc,
+} from "./payment-method-form";
+export type {
+  Appearance,
+  Message,
+  ThemeVariable,
+} from "./types";
+export { createMessage } from "./types";
+
+/**
+ * Convenience alias for `components["schemas"]["CreateCustomerInput"]`.
+ */
+export type CreateCustomerInput = components["schemas"]["CreateCustomerInput"];
+/**
+ * Convenience alias for
+ * `components["schemas"]["CreatePaymentIntentInput"]`.
+ */
+export type CreatePaymentIntentInput =
+  components["schemas"]["CreatePaymentIntentInput"];
+/**
+ * Convenience alias for
+ * `components["schemas"]["CreateSetupIntentInput"]`.
+ */
+export type CreateSetupIntentInput =
+  components["schemas"]["CreateSetupIntentInput"];
+/**
+ * Convenience alias for `components["schemas"]["PaymentIntent"]`.
+ */
+export type PaymentIntent = components["schemas"]["PaymentIntent"];
+/**
+ * Convenience alias for `components["schemas"]["SetupIntent"]`.
+ */
+export type SetupIntent = components["schemas"]["SetupIntent"];
+/**
+ * API envelope `{ token?, ttl? }` for a minted embed JWT.
+ *
+ * `POST /payment_intents` and `POST /setup_intents` resolve to this
+ * shape. {@link confirmPaymentIntent}, {@link confirmSetupIntent}, and
+ * the Google Pay `onInitiatePaymentIntentRequest` return type use
+ * `Pick<EmbedToken, "token">` (the JWT string returned by your server).
+ */
+export type EmbedToken = components["schemas"]["EmbedToken"];
+/**
+ * Decoded JWT payload for an embed token (`account_id`,
+ * `payment_intent_id`, `setup_intent_id`, etc.).
+ */
+export type EmbedTokenJwt = components["schemas"]["EmbedTokenJwt"];
+/**
+ * Decoded JWT payload for the dashboard render token (`env`, `origins`,
+ * `allowed_payment_method_types`, `render_template_id`, etc.).
+ */
+export type RenderTokenJwt = components["schemas"]["RenderTokenJwt"];

package/src/jwt.ts

@@ -0,0 +1,44 @@
+import type { components } from "@amos.com/node";
+
+/**
+ * Decode a JWT into its `{ header, payload, signature }` parts without
+ * verifying the signature.
+ *
+ * Works in both browser (`atob`) and Node (`Buffer`) environments.
+ */
+export function decodeJwt(token: string | undefined): {
+  header: Record<string, unknown>;
+  payload: Record<string, unknown>;
+  signature: string;
+} {
+  const [header = "", payload = "", signature = ""] = token?.split(".") ?? [];
+
+  const decoder =
+    typeof atob === "function"
+      ? atob
+      : (encoded: string) => Buffer.from(encoded, "base64").toString("utf8");
+
+  return {
+    header: JSON.parse(decoder(header)),
+    payload: JSON.parse(decoder(payload)),
+    signature,
+  };
+}
+
+/**
+ * Resolve the Amos embed origin (production vs. sandbox) from a render
+ * token's decoded payload.
+ */
+export function getEmbedOrigin(renderToken: string): string {
+  const { env = "sandbox" }: components["schemas"]["RenderTokenJwt"] =
+    decodeJwt(renderToken).payload;
+
+  switch (env) {
+    case "production":
+      return "https://embed.amos.com";
+    case "sandbox":
+      return "https://embed-sandbox.amos.com";
+    default:
+      return "https://embed-sandbox.amos.com";
+  }
+}