@funnelfox/payments-sdk 0.1.2-beta.9 → 0.2.0-beta.1

package/dist/index.cjs

@@ -62,7 +62,8 @@ function buildStripeCheckoutSessionBody(params) {
       }
     },
     ...params.upgrade && { upgrade: params.upgrade },
-    ...params.walletFirst && { wallet_first: params.walletFirst }
+    ...params.walletFirst && { wallet_first: params.walletFirst },
+    ...params.uiMode && { ui_mode: params.uiMode }
   };
 }
 
@@ -125,55 +126,195 @@ var StripeCheckoutService = class extends HttpService {
   }
 };
 
+// src/providers/stripe/ui/embedded-page.ts
+var StripeEmbeddedPageUi = class {
+  checkout = null;
+  async mount(stripe, container, host) {
+    try {
+      this.checkout = await stripe.createEmbeddedCheckoutPage({
+        fetchClientSecret: () => host.clientSecret(),
+        onComplete: () => host.succeeded()
+      });
+    } catch (err) {
+      host.renderFailed(err, { message: err instanceof Error ? err.message : void 0 });
+      if (err instanceof CheckoutError) throw err;
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new CheckoutError(`Stripe checkout failed: ${detail}`);
+    }
+    this.checkout.mount(container);
+  }
+  destroy() {
+    this.checkout?.destroy();
+    this.checkout = null;
+  }
+};
+
+// src/providers/stripe/ui/form.ts
+var CHECKOUT_FORM_BETA = "custom_checkout_payment_form_1";
+var StripeFormUi = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  options;
+  loadOptions = { betas: [CHECKOUT_FORM_BETA] };
+  checkout = null;
+  form = null;
+  async mount(stripe, container, host) {
+    const { appearance, fonts, loader, layout, expressCheckout } = this.options;
+    const startedAt = Date.now();
+    try {
+      if (typeof stripe.initCheckoutFormSdk !== "function") {
+        throw new CheckoutError("Stripe has not granted this account access to Checkout Form");
+      }
+      this.checkout = stripe.initCheckoutFormSdk({
+        clientSecret: host.clientSecret(),
+        ...appearance && { appearance },
+        ...fonts?.length && { fonts },
+        ...loader && { loader }
+      });
+      this.checkout.on("change", (session) => host.changed(fromSession(session)));
+      this.form = this.checkout.createForm({
+        ...layout && { layout },
+        ...expressCheckout && { expressCheckout }
+      });
+      this.form.on("ready", () => host.ready(Date.now() - startedAt));
+      this.form.on(
+        "loaderror",
+        (event) => host.renderFailed(event.error, { message: event.error.message })
+      );
+      this.form.on("change", (event) => host.changed(fromForm(event)));
+      this.form.on("cancel", () => host.cancelled());
+      this.form.mount(container);
+      const actions = await this.loadActions();
+      this.form.on("confirm", (event) => void this.confirm(actions, event, host));
+    } catch (err) {
+      host.renderFailed(err, { message: err instanceof Error ? err.message : void 0 });
+      if (err instanceof CheckoutError) throw err;
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new CheckoutError(`Stripe checkout failed: ${detail}`);
+    }
+  }
+  destroy() {
+    this.form?.destroy();
+    this.form = null;
+    this.checkout = null;
+  }
+  async loadActions() {
+    const result = await this.checkout.loadActions();
+    if (result.type !== "success") {
+      throw new CheckoutError(`Stripe checkout failed: ${result.error.message}`);
+    }
+    return result.actions;
+  }
+  async confirm(actions, event, host) {
+    const express = event.source === "checkout-form-ece";
+    const paymentMethodType = express ? void 0 : event.paymentMethodType ?? void 0;
+    host.confirmed({ paymentMethodType, express });
+    try {
+      const result = await actions.confirm({ formConfirmEvent: event, redirect: "if_required" });
+      if (result.type === "error") {
+        host.paymentFailed(result.error, {
+          declineCode: result.error.code === "paymentFailed" ? result.error.paymentFailed.declineCode : null,
+          message: result.error.message
+        });
+        return;
+      }
+      host.succeeded(fromSession(result.session));
+    } catch (err) {
+      host.paymentFailed(err, { message: err instanceof Error ? err.message : void 0 });
+    }
+  }
+};
+function fromSession(session) {
+  return {
+    email: session.email ?? void 0,
+    currency: session.currency,
+    amountTotal: session.total?.total?.minorUnitsAmount
+  };
+}
+function fromForm(event) {
+  const { payment, customerDetails, adaptivePricing } = event.value;
+  return {
+    paymentMethodType: payment?.type,
+    email: customerDetails?.email || void 0,
+    currency: adaptivePricing?.currency,
+    complete: event.complete
+  };
+}
+
+// src/providers/stripe/ui/index.ts
+function createStripeCheckoutUi(config) {
+  switch (config.uiMode) {
+    case "form":
+      return new StripeFormUi(config.form);
+    default:
+      return new StripeEmbeddedPageUi();
+  }
+}
+
 // src/providers/stripe/index.ts
 var StripeProvider = class {
   constructor(config, callbacks, baseUrl, headers) {
     this.config = config;
     this.callbacks = callbacks;
     this.service = new StripeCheckoutService(baseUrl, headers);
+    this.ui = createStripeCheckoutUi(config);
   }
   config;
   callbacks;
-  stripe = null;
-  embeddedCheckout = null;
   service;
+  ui;
+  stripe = null;
+  mounted = false;
   clientSecret = null;
+  snapshot = {};
   async init() {
-    const stripe = await (0, import_stripe_js.loadStripe)(this.config.publishableKey);
+    const stripe = await (0, import_stripe_js.loadStripe)(this.config.publishableKey, this.ui.loadOptions);
     if (!stripe) {
-      throw new CheckoutError("Failed to load Stripe.js \u2014 verify your publishableKey");
+      const error = new CheckoutError("Failed to load Stripe.js \u2014 verify your publishableKey");
+      this.emitError("init", error, { message: error.message });
+      throw error;
     }
     this.stripe = stripe;
   }
-  async render(container, options) {
+  async render(container, _options) {
     if (!this.stripe) {
       throw new CheckoutError("Provider not initialized \u2014 call init() before render()");
     }
-    if (this.embeddedCheckout) {
+    if (this.mounted) {
       throw new CheckoutError("Already rendered \u2014 call destroy() before rendering again");
     }
-    try {
-      this.embeddedCheckout = await this.stripe.createEmbeddedCheckoutPage({
-        fetchClientSecret: () => this.fetchClientSecret(),
-        onComplete: () => this.handleComplete(),
-        onAnalyticsEvent: (event) => console.log("[stripe analytics]", event.eventType, event)
-      });
-    } catch (err) {
-      this.callbacks.onError?.({ provider: "stripe", error: err });
-      if (err instanceof CheckoutError) throw err;
-      const detail = err instanceof Error ? err.message : String(err);
-      throw new CheckoutError(`Stripe checkout failed: ${detail}`);
-    }
-    this.embeddedCheckout.mount(container);
+    this.mounted = true;
+    await this.ui.mount(this.stripe, container, this.host());
   }
   async reset() {
     this.destroy();
   }
   destroy() {
-    this.embeddedCheckout?.destroy();
-    this.embeddedCheckout = null;
+    this.ui.destroy();
+    this.mounted = false;
+    this.snapshot = {};
   }
-  async fetchClientSecret() {
+  host() {
+    return {
+      clientSecret: () => this.createSession(),
+      ready: (durationMs) => this.callbacks.onReady?.({ provider: "stripe", durationMs }),
+      changed: (patch) => this.merge(patch),
+      confirmed: ({ paymentMethodType, express }) => this.callbacks.onConfirm?.({
+        provider: "stripe",
+        paymentMethodType: paymentMethodType ?? this.snapshot.paymentMethodType,
+        express
+      }),
+      cancelled: () => this.callbacks.onCancel?.({
+        provider: "stripe",
+        paymentMethodType: this.snapshot.paymentMethodType
+      }),
+      renderFailed: (error, detail) => this.emitError("render", error, detail),
+      paymentFailed: (error, detail) => this.emitError("payment", error, detail),
+      succeeded: (outcome) => void this.emitComplete(outcome)
+    };
+  }
+  async createSession() {
     const secret = await this.service.createCheckoutSession({
       ...this.config,
       returnUrl: this.config.returnUrl ?? window.location.href
@@ -182,33 +323,74 @@ var StripeProvider = class {
     return secret;
   }
   // Format: cs_test_{sessionId}_secret_{random}
-  parseSessionId(clientSecret) {
-    if (!clientSecret) return null;
-    const idx = clientSecret.indexOf("_secret_");
-    return idx !== -1 ? clientSecret.slice(0, idx) : null;
-  }
-  async handleComplete() {
-    const sessionId = this.parseSessionId(this.clientSecret);
-    if (!sessionId) {
-      this.callbacks.onComplete?.({ provider: "stripe" });
-      return;
+  sessionId() {
+    if (!this.clientSecret) {
+      return null;
     }
-    try {
-      const session = await this.service.getSession(sessionId, this.config.accountId);
-      this.callbacks.onComplete?.({
-        provider: "stripe",
-        customerId: session.customer_id ?? void 0,
-        subscriptionId: session.subscription_id ?? void 0,
-        invoiceId: session.invoice_id ?? void 0,
-        amountPaid: session.amount_total ?? void 0,
-        currency: session.currency ?? void 0,
-        email: session.email ?? void 0
-      });
-    } catch {
-      this.callbacks.onComplete?.({ provider: "stripe" });
+    const idx = this.clientSecret.indexOf("_secret_");
+    return idx !== -1 ? this.clientSecret.slice(0, idx) : null;
+  }
+  merge(patch) {
+    const next = { ...this.snapshot };
+    for (const [key, value] of Object.entries(patch)) {
+      if (value !== void 0) {
+        Object.assign(next, { [key]: value });
+      }
+    }
+    this.snapshot = next;
+    this.callbacks.onChange?.({ provider: "stripe", ...next });
+  }
+  /**
+   * Reads the session back for the ids only the backend can resolve, falling
+   * back to what the client already knows so a paid customer is never
+   * reported as a failure.
+   */
+  async emitComplete(outcome) {
+    const sessionId = this.sessionId();
+    const fallback = {
+      amount_total: outcome?.amountTotal ?? null,
+      currency: outcome?.currency ?? null,
+      email: outcome?.email ?? null
+    };
+    let session = {};
+    if (sessionId) {
+      try {
+        session = definedOnly(await this.service.getSession(sessionId, this.config.accountId));
+      } catch {
+        session = {};
+      }
     }
+    this.callbacks.onComplete?.({
+      provider: "stripe",
+      paymentMethodType: this.snapshot.paymentMethodType,
+      ...toCompleteFields({ ...fallback, ...session })
+    });
+  }
+  emitError(phase, error, detail) {
+    this.callbacks.onError?.({
+      provider: "stripe",
+      phase,
+      paymentMethodType: this.snapshot.paymentMethodType,
+      error,
+      ...detail
+    });
   }
 };
+function definedOnly(session) {
+  return Object.fromEntries(
+    Object.entries(session).filter(([, value]) => value !== null && value !== void 0)
+  );
+}
+function toCompleteFields(session) {
+  return {
+    customerId: session.customer_id ?? void 0,
+    subscriptionId: session.subscription_id ?? void 0,
+    invoiceId: session.invoice_id ?? void 0,
+    amountPaid: session.amount_total ?? void 0,
+    currency: session.currency ?? void 0,
+    email: session.email ?? void 0
+  };
+}
 
 // src/providers/fastspring/index.ts
 var FastSpringProvider = class {

package/dist/index.d.cts

@@ -1,5 +1,27 @@
-type PaymentMethodType = 'card' | 'google_pay' | 'apple_pay';
+import { Appearance, CssFontSource, CustomFontSource, StripeCheckoutFormOptions } from '@stripe/stripe-js';
 
+/**
+ * Known values are suggested; providers may report their own ids
+ * (Stripe form reports e.g. `sepa_debit`, `link`, `klarna`).
+ */
+type PaymentMethodType = 'card' | 'google_pay' | 'apple_pay' | (string & {});
+
+/**
+ * How Stripe renders checkout. Independent of `managed`, which decides
+ * merchant of record — Stripe treats them as two parameters of one session.
+ */
+type StripeUiMode = 'embedded_page' | 'form';
+/** Client-side UI options for `uiMode: 'form'`. */
+interface StripeFormOptions {
+    /** Form supports the whole Appearance API except `rules`. */
+    appearance?: Omit<Appearance, 'rules'>;
+    /** Font sources so `appearance.variables.fontFamily` resolves inside the iframe. */
+    fonts?: Array<CssFontSource | CustomFontSource>;
+    loader?: 'auto' | 'always' | 'never';
+    /** Omit to let Stripe pick the layout it expects to convert best. */
+    layout?: StripeCheckoutFormOptions['layout'];
+    expressCheckout?: StripeCheckoutFormOptions['expressCheckout'];
+}
 interface StripeCustomer {
     email?: string;
     phone?: string;
@@ -41,6 +63,10 @@ interface StripeConfig {
     upgrade?: boolean;
     /** When true, surfaces Apple Pay / Google Pay as the primary payment option (Wallet-First mode) */
     walletFirst?: boolean;
+    /** Which checkout UI Stripe renders. Defaults to `embedded_page`. */
+    uiMode?: StripeUiMode;
+    /** UI options applied only when `uiMode` is `form`. */
+    form?: StripeFormOptions;
 }
 
 interface FastSpringConfig {
@@ -79,20 +105,54 @@ interface CheckoutCompleteEvent {
     currency?: string;
     email?: string;
 }
+/**
+ * Where a checkout failed. `init`/`render` mean the UI never became usable;
+ * `payment` means the buyer's charge was declined or errored.
+ */
+type CheckoutErrorPhase = 'init' | 'render' | 'payment';
 interface CheckoutErrorEvent {
     provider: ProviderName;
     paymentMethodType?: PaymentMethodType;
+    phase: CheckoutErrorPhase;
+    /** Provider decline code when it exposes one, for mapping to a failure reason. */
+    declineCode?: string | null;
+    message?: string;
     error: unknown;
 }
 interface CheckoutCancelEvent {
     provider: ProviderName;
     paymentMethodType?: PaymentMethodType;
 }
+interface CheckoutReadyEvent {
+    provider: ProviderName;
+    /** Milliseconds from render() to the checkout UI being usable. */
+    durationMs: number;
+}
+/** The buyer authorized the payment; the charge is not confirmed yet. */
+interface CheckoutConfirmEvent {
+    provider: ProviderName;
+    paymentMethodType?: PaymentMethodType;
+    /** Authorized through a wallet button rather than the pay button. */
+    express: boolean;
+}
+/** Latest snapshot of what the buyer selected and what they will be charged. */
+interface CheckoutChangeEvent {
+    provider: ProviderName;
+    paymentMethodType?: PaymentMethodType;
+    email?: string;
+    /** Currency actually charged — Adaptive Pricing may differ from the listed one. */
+    currency?: string;
+    amountTotal?: number;
+    complete?: boolean;
+}
 
 interface CheckoutCallbacks {
     onComplete?: (event: CheckoutCompleteEvent) => void;
     onError?: (event: CheckoutErrorEvent) => void;
     onCancel?: (event: CheckoutCancelEvent) => void;
+    onReady?: (event: CheckoutReadyEvent) => void;
+    onConfirm?: (event: CheckoutConfirmEvent) => void;
+    onChange?: (event: CheckoutChangeEvent) => void;
 }
 
 interface RenderOptions {
@@ -123,9 +183,9 @@ declare class CheckoutError extends Error {
     constructor(message: string);
 }
 
-type CreateCheckoutSessionParams = Omit<StripeConfig, 'publishableKey' | 'returnUrl'> & {
+type CreateCheckoutSessionParams = Omit<StripeConfig, 'publishableKey' | 'returnUrl' | 'form'> & {
     returnUrl: string;
 };
 declare function buildStripeCheckoutSessionBody(params: CreateCheckoutSessionParams): Record<string, unknown>;
 
-export { type CheckoutCallbacks, type CheckoutCancelEvent, type CheckoutCompleteEvent, CheckoutError, type CheckoutErrorEvent, type CheckoutInstance, type CreateCheckoutSessionParams, type FastSpringConfig, type PaymentMethodType, type PaymentProvider, type ProviderConfigMap, type ProviderName, type RenderOptions, type StripeCheckoutTrial, type StripeConfig, buildStripeCheckoutSessionBody, initCheckout };
+export { type CheckoutCallbacks, type CheckoutCancelEvent, type CheckoutChangeEvent, type CheckoutCompleteEvent, type CheckoutConfirmEvent, CheckoutError, type CheckoutErrorEvent, type CheckoutErrorPhase, type CheckoutInstance, type CheckoutReadyEvent, type CreateCheckoutSessionParams, type FastSpringConfig, type PaymentMethodType, type PaymentProvider, type ProviderConfigMap, type ProviderName, type RenderOptions, type StripeCheckoutTrial, type StripeConfig, type StripeFormOptions, type StripeUiMode, buildStripeCheckoutSessionBody, initCheckout };

package/dist/index.d.ts

@@ -1,5 +1,27 @@
-type PaymentMethodType = 'card' | 'google_pay' | 'apple_pay';
+import { Appearance, CssFontSource, CustomFontSource, StripeCheckoutFormOptions } from '@stripe/stripe-js';
 
+/**
+ * Known values are suggested; providers may report their own ids
+ * (Stripe form reports e.g. `sepa_debit`, `link`, `klarna`).
+ */
+type PaymentMethodType = 'card' | 'google_pay' | 'apple_pay' | (string & {});
+
+/**
+ * How Stripe renders checkout. Independent of `managed`, which decides
+ * merchant of record — Stripe treats them as two parameters of one session.
+ */
+type StripeUiMode = 'embedded_page' | 'form';
+/** Client-side UI options for `uiMode: 'form'`. */
+interface StripeFormOptions {
+    /** Form supports the whole Appearance API except `rules`. */
+    appearance?: Omit<Appearance, 'rules'>;
+    /** Font sources so `appearance.variables.fontFamily` resolves inside the iframe. */
+    fonts?: Array<CssFontSource | CustomFontSource>;
+    loader?: 'auto' | 'always' | 'never';
+    /** Omit to let Stripe pick the layout it expects to convert best. */
+    layout?: StripeCheckoutFormOptions['layout'];
+    expressCheckout?: StripeCheckoutFormOptions['expressCheckout'];
+}
 interface StripeCustomer {
     email?: string;
     phone?: string;
@@ -41,6 +63,10 @@ interface StripeConfig {
     upgrade?: boolean;
     /** When true, surfaces Apple Pay / Google Pay as the primary payment option (Wallet-First mode) */
     walletFirst?: boolean;
+    /** Which checkout UI Stripe renders. Defaults to `embedded_page`. */
+    uiMode?: StripeUiMode;
+    /** UI options applied only when `uiMode` is `form`. */
+    form?: StripeFormOptions;
 }
 
 interface FastSpringConfig {
@@ -79,20 +105,54 @@ interface CheckoutCompleteEvent {
     currency?: string;
     email?: string;
 }
+/**
+ * Where a checkout failed. `init`/`render` mean the UI never became usable;
+ * `payment` means the buyer's charge was declined or errored.
+ */
+type CheckoutErrorPhase = 'init' | 'render' | 'payment';
 interface CheckoutErrorEvent {
     provider: ProviderName;
     paymentMethodType?: PaymentMethodType;
+    phase: CheckoutErrorPhase;
+    /** Provider decline code when it exposes one, for mapping to a failure reason. */
+    declineCode?: string | null;
+    message?: string;
     error: unknown;
 }
 interface CheckoutCancelEvent {
     provider: ProviderName;
     paymentMethodType?: PaymentMethodType;
 }
+interface CheckoutReadyEvent {
+    provider: ProviderName;
+    /** Milliseconds from render() to the checkout UI being usable. */
+    durationMs: number;
+}
+/** The buyer authorized the payment; the charge is not confirmed yet. */
+interface CheckoutConfirmEvent {
+    provider: ProviderName;
+    paymentMethodType?: PaymentMethodType;
+    /** Authorized through a wallet button rather than the pay button. */
+    express: boolean;
+}
+/** Latest snapshot of what the buyer selected and what they will be charged. */
+interface CheckoutChangeEvent {
+    provider: ProviderName;
+    paymentMethodType?: PaymentMethodType;
+    email?: string;
+    /** Currency actually charged — Adaptive Pricing may differ from the listed one. */
+    currency?: string;
+    amountTotal?: number;
+    complete?: boolean;
+}
 
 interface CheckoutCallbacks {
     onComplete?: (event: CheckoutCompleteEvent) => void;
     onError?: (event: CheckoutErrorEvent) => void;
     onCancel?: (event: CheckoutCancelEvent) => void;
+    onReady?: (event: CheckoutReadyEvent) => void;
+    onConfirm?: (event: CheckoutConfirmEvent) => void;
+    onChange?: (event: CheckoutChangeEvent) => void;
 }
 
 interface RenderOptions {
@@ -123,9 +183,9 @@ declare class CheckoutError extends Error {
     constructor(message: string);
 }
 
-type CreateCheckoutSessionParams = Omit<StripeConfig, 'publishableKey' | 'returnUrl'> & {
+type CreateCheckoutSessionParams = Omit<StripeConfig, 'publishableKey' | 'returnUrl' | 'form'> & {
     returnUrl: string;
 };
 declare function buildStripeCheckoutSessionBody(params: CreateCheckoutSessionParams): Record<string, unknown>;
 
-export { type CheckoutCallbacks, type CheckoutCancelEvent, type CheckoutCompleteEvent, CheckoutError, type CheckoutErrorEvent, type CheckoutInstance, type CreateCheckoutSessionParams, type FastSpringConfig, type PaymentMethodType, type PaymentProvider, type ProviderConfigMap, type ProviderName, type RenderOptions, type StripeCheckoutTrial, type StripeConfig, buildStripeCheckoutSessionBody, initCheckout };
+export { type CheckoutCallbacks, type CheckoutCancelEvent, type CheckoutChangeEvent, type CheckoutCompleteEvent, type CheckoutConfirmEvent, CheckoutError, type CheckoutErrorEvent, type CheckoutErrorPhase, type CheckoutInstance, type CheckoutReadyEvent, type CreateCheckoutSessionParams, type FastSpringConfig, type PaymentMethodType, type PaymentProvider, type ProviderConfigMap, type ProviderName, type RenderOptions, type StripeCheckoutTrial, type StripeConfig, type StripeFormOptions, type StripeUiMode, buildStripeCheckoutSessionBody, initCheckout };

package/dist/index.js

@@ -34,7 +34,8 @@ function buildStripeCheckoutSessionBody(params) {
       }
     },
     ...params.upgrade && { upgrade: params.upgrade },
-    ...params.walletFirst && { wallet_first: params.walletFirst }
+    ...params.walletFirst && { wallet_first: params.walletFirst },
+    ...params.uiMode && { ui_mode: params.uiMode }
   };
 }
 
@@ -97,55 +98,195 @@ var StripeCheckoutService = class extends HttpService {
   }
 };
 
+// src/providers/stripe/ui/embedded-page.ts
+var StripeEmbeddedPageUi = class {
+  checkout = null;
+  async mount(stripe, container, host) {
+    try {
+      this.checkout = await stripe.createEmbeddedCheckoutPage({
+        fetchClientSecret: () => host.clientSecret(),
+        onComplete: () => host.succeeded()
+      });
+    } catch (err) {
+      host.renderFailed(err, { message: err instanceof Error ? err.message : void 0 });
+      if (err instanceof CheckoutError) throw err;
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new CheckoutError(`Stripe checkout failed: ${detail}`);
+    }
+    this.checkout.mount(container);
+  }
+  destroy() {
+    this.checkout?.destroy();
+    this.checkout = null;
+  }
+};
+
+// src/providers/stripe/ui/form.ts
+var CHECKOUT_FORM_BETA = "custom_checkout_payment_form_1";
+var StripeFormUi = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  options;
+  loadOptions = { betas: [CHECKOUT_FORM_BETA] };
+  checkout = null;
+  form = null;
+  async mount(stripe, container, host) {
+    const { appearance, fonts, loader, layout, expressCheckout } = this.options;
+    const startedAt = Date.now();
+    try {
+      if (typeof stripe.initCheckoutFormSdk !== "function") {
+        throw new CheckoutError("Stripe has not granted this account access to Checkout Form");
+      }
+      this.checkout = stripe.initCheckoutFormSdk({
+        clientSecret: host.clientSecret(),
+        ...appearance && { appearance },
+        ...fonts?.length && { fonts },
+        ...loader && { loader }
+      });
+      this.checkout.on("change", (session) => host.changed(fromSession(session)));
+      this.form = this.checkout.createForm({
+        ...layout && { layout },
+        ...expressCheckout && { expressCheckout }
+      });
+      this.form.on("ready", () => host.ready(Date.now() - startedAt));
+      this.form.on(
+        "loaderror",
+        (event) => host.renderFailed(event.error, { message: event.error.message })
+      );
+      this.form.on("change", (event) => host.changed(fromForm(event)));
+      this.form.on("cancel", () => host.cancelled());
+      this.form.mount(container);
+      const actions = await this.loadActions();
+      this.form.on("confirm", (event) => void this.confirm(actions, event, host));
+    } catch (err) {
+      host.renderFailed(err, { message: err instanceof Error ? err.message : void 0 });
+      if (err instanceof CheckoutError) throw err;
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new CheckoutError(`Stripe checkout failed: ${detail}`);
+    }
+  }
+  destroy() {
+    this.form?.destroy();
+    this.form = null;
+    this.checkout = null;
+  }
+  async loadActions() {
+    const result = await this.checkout.loadActions();
+    if (result.type !== "success") {
+      throw new CheckoutError(`Stripe checkout failed: ${result.error.message}`);
+    }
+    return result.actions;
+  }
+  async confirm(actions, event, host) {
+    const express = event.source === "checkout-form-ece";
+    const paymentMethodType = express ? void 0 : event.paymentMethodType ?? void 0;
+    host.confirmed({ paymentMethodType, express });
+    try {
+      const result = await actions.confirm({ formConfirmEvent: event, redirect: "if_required" });
+      if (result.type === "error") {
+        host.paymentFailed(result.error, {
+          declineCode: result.error.code === "paymentFailed" ? result.error.paymentFailed.declineCode : null,
+          message: result.error.message
+        });
+        return;
+      }
+      host.succeeded(fromSession(result.session));
+    } catch (err) {
+      host.paymentFailed(err, { message: err instanceof Error ? err.message : void 0 });
+    }
+  }
+};
+function fromSession(session) {
+  return {
+    email: session.email ?? void 0,
+    currency: session.currency,
+    amountTotal: session.total?.total?.minorUnitsAmount
+  };
+}
+function fromForm(event) {
+  const { payment, customerDetails, adaptivePricing } = event.value;
+  return {
+    paymentMethodType: payment?.type,
+    email: customerDetails?.email || void 0,
+    currency: adaptivePricing?.currency,
+    complete: event.complete
+  };
+}
+
+// src/providers/stripe/ui/index.ts
+function createStripeCheckoutUi(config) {
+  switch (config.uiMode) {
+    case "form":
+      return new StripeFormUi(config.form);
+    default:
+      return new StripeEmbeddedPageUi();
+  }
+}
+
 // src/providers/stripe/index.ts
 var StripeProvider = class {
   constructor(config, callbacks, baseUrl, headers) {
     this.config = config;
     this.callbacks = callbacks;
     this.service = new StripeCheckoutService(baseUrl, headers);
+    this.ui = createStripeCheckoutUi(config);
   }
   config;
   callbacks;
-  stripe = null;
-  embeddedCheckout = null;
   service;
+  ui;
+  stripe = null;
+  mounted = false;
   clientSecret = null;
+  snapshot = {};
   async init() {
-    const stripe = await loadStripe(this.config.publishableKey);
+    const stripe = await loadStripe(this.config.publishableKey, this.ui.loadOptions);
     if (!stripe) {
-      throw new CheckoutError("Failed to load Stripe.js \u2014 verify your publishableKey");
+      const error = new CheckoutError("Failed to load Stripe.js \u2014 verify your publishableKey");
+      this.emitError("init", error, { message: error.message });
+      throw error;
     }
     this.stripe = stripe;
   }
-  async render(container, options) {
+  async render(container, _options) {
     if (!this.stripe) {
       throw new CheckoutError("Provider not initialized \u2014 call init() before render()");
     }
-    if (this.embeddedCheckout) {
+    if (this.mounted) {
       throw new CheckoutError("Already rendered \u2014 call destroy() before rendering again");
     }
-    try {
-      this.embeddedCheckout = await this.stripe.createEmbeddedCheckoutPage({
-        fetchClientSecret: () => this.fetchClientSecret(),
-        onComplete: () => this.handleComplete(),
-        onAnalyticsEvent: (event) => console.log("[stripe analytics]", event.eventType, event)
-      });
-    } catch (err) {
-      this.callbacks.onError?.({ provider: "stripe", error: err });
-      if (err instanceof CheckoutError) throw err;
-      const detail = err instanceof Error ? err.message : String(err);
-      throw new CheckoutError(`Stripe checkout failed: ${detail}`);
-    }
-    this.embeddedCheckout.mount(container);
+    this.mounted = true;
+    await this.ui.mount(this.stripe, container, this.host());
   }
   async reset() {
     this.destroy();
   }
   destroy() {
-    this.embeddedCheckout?.destroy();
-    this.embeddedCheckout = null;
+    this.ui.destroy();
+    this.mounted = false;
+    this.snapshot = {};
   }
-  async fetchClientSecret() {
+  host() {
+    return {
+      clientSecret: () => this.createSession(),
+      ready: (durationMs) => this.callbacks.onReady?.({ provider: "stripe", durationMs }),
+      changed: (patch) => this.merge(patch),
+      confirmed: ({ paymentMethodType, express }) => this.callbacks.onConfirm?.({
+        provider: "stripe",
+        paymentMethodType: paymentMethodType ?? this.snapshot.paymentMethodType,
+        express
+      }),
+      cancelled: () => this.callbacks.onCancel?.({
+        provider: "stripe",
+        paymentMethodType: this.snapshot.paymentMethodType
+      }),
+      renderFailed: (error, detail) => this.emitError("render", error, detail),
+      paymentFailed: (error, detail) => this.emitError("payment", error, detail),
+      succeeded: (outcome) => void this.emitComplete(outcome)
+    };
+  }
+  async createSession() {
     const secret = await this.service.createCheckoutSession({
       ...this.config,
       returnUrl: this.config.returnUrl ?? window.location.href
@@ -154,33 +295,74 @@ var StripeProvider = class {
     return secret;
   }
   // Format: cs_test_{sessionId}_secret_{random}
-  parseSessionId(clientSecret) {
-    if (!clientSecret) return null;
-    const idx = clientSecret.indexOf("_secret_");
-    return idx !== -1 ? clientSecret.slice(0, idx) : null;
-  }
-  async handleComplete() {
-    const sessionId = this.parseSessionId(this.clientSecret);
-    if (!sessionId) {
-      this.callbacks.onComplete?.({ provider: "stripe" });
-      return;
+  sessionId() {
+    if (!this.clientSecret) {
+      return null;
     }
-    try {
-      const session = await this.service.getSession(sessionId, this.config.accountId);
-      this.callbacks.onComplete?.({
-        provider: "stripe",
-        customerId: session.customer_id ?? void 0,
-        subscriptionId: session.subscription_id ?? void 0,
-        invoiceId: session.invoice_id ?? void 0,
-        amountPaid: session.amount_total ?? void 0,
-        currency: session.currency ?? void 0,
-        email: session.email ?? void 0
-      });
-    } catch {
-      this.callbacks.onComplete?.({ provider: "stripe" });
+    const idx = this.clientSecret.indexOf("_secret_");
+    return idx !== -1 ? this.clientSecret.slice(0, idx) : null;
+  }
+  merge(patch) {
+    const next = { ...this.snapshot };
+    for (const [key, value] of Object.entries(patch)) {
+      if (value !== void 0) {
+        Object.assign(next, { [key]: value });
+      }
+    }
+    this.snapshot = next;
+    this.callbacks.onChange?.({ provider: "stripe", ...next });
+  }
+  /**
+   * Reads the session back for the ids only the backend can resolve, falling
+   * back to what the client already knows so a paid customer is never
+   * reported as a failure.
+   */
+  async emitComplete(outcome) {
+    const sessionId = this.sessionId();
+    const fallback = {
+      amount_total: outcome?.amountTotal ?? null,
+      currency: outcome?.currency ?? null,
+      email: outcome?.email ?? null
+    };
+    let session = {};
+    if (sessionId) {
+      try {
+        session = definedOnly(await this.service.getSession(sessionId, this.config.accountId));
+      } catch {
+        session = {};
+      }
     }
+    this.callbacks.onComplete?.({
+      provider: "stripe",
+      paymentMethodType: this.snapshot.paymentMethodType,
+      ...toCompleteFields({ ...fallback, ...session })
+    });
+  }
+  emitError(phase, error, detail) {
+    this.callbacks.onError?.({
+      provider: "stripe",
+      phase,
+      paymentMethodType: this.snapshot.paymentMethodType,
+      error,
+      ...detail
+    });
   }
 };
+function definedOnly(session) {
+  return Object.fromEntries(
+    Object.entries(session).filter(([, value]) => value !== null && value !== void 0)
+  );
+}
+function toCompleteFields(session) {
+  return {
+    customerId: session.customer_id ?? void 0,
+    subscriptionId: session.subscription_id ?? void 0,
+    invoiceId: session.invoice_id ?? void 0,
+    amountPaid: session.amount_total ?? void 0,
+    currency: session.currency ?? void 0,
+    email: session.email ?? void 0
+  };
+}
 
 // src/providers/fastspring/index.ts
 var FastSpringProvider = class {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelfox/payments-sdk",
-  "version": "0.1.2-beta.9",
+  "version": "0.2.0-beta.1",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",