@funnelfox/payments-sdk 0.2.0-beta.1 → 0.2.0-beta.3

package/dist/index.cjs

@@ -33,10 +33,44 @@ var CheckoutError = class extends Error {
     this.name = "CheckoutError";
   }
 };
+var CHECKOUT_BLOCK_REASONS = ["duplicated_subscription", "duplicated_payment"];
+function isCheckoutBlockReason(reason) {
+  return CHECKOUT_BLOCK_REASONS.some((known) => known === reason);
+}
+var CheckoutBlockedError = class extends CheckoutError {
+  constructor(reason, buyerMessage) {
+    super(`Checkout blocked: ${reason}`);
+    this.reason = reason;
+    this.buyerMessage = buyerMessage;
+    this.name = "CheckoutBlockedError";
+  }
+  reason;
+  buyerMessage;
+};
 
 // src/providers/stripe/index.ts
 var import_stripe_js = require("@stripe/stripe-js");
 
+// src/providers/stripe/return-url.ts
+var RETURNED_SESSION_PARAM = "ff_checkout_session";
+var SESSION_ID_PLACEHOLDER = "{CHECKOUT_SESSION_ID}";
+var SESSION_ID = /^cs_\w+$/;
+function withReturnedSessionParam(href) {
+  const url = new URL(href);
+  url.searchParams.set(RETURNED_SESSION_PARAM, SESSION_ID_PLACEHOLDER);
+  return url.href.replace(encodeURIComponent(SESSION_ID_PLACEHOLDER), SESSION_ID_PLACEHOLDER);
+}
+function popSessionIdFromUrl() {
+  const url = new URL(window.location.href);
+  const sessionId = url.searchParams.get(RETURNED_SESSION_PARAM);
+  if (sessionId === null) {
+    return null;
+  }
+  url.searchParams.delete(RETURNED_SESSION_PARAM);
+  window.history.replaceState(window.history.state, "", url.href);
+  return SESSION_ID.test(sessionId) ? sessionId : null;
+}
+
 // src/providers/stripe/helpers.ts
 function buildStripeCheckoutSessionBody(params) {
   return {
@@ -62,6 +96,7 @@ function buildStripeCheckoutSessionBody(params) {
       }
     },
     ...params.upgrade && { upgrade: params.upgrade },
+    ...params.isSubscription !== void 0 && { is_subscription: params.isSubscription },
     ...params.walletFirst && { wallet_first: params.walletFirst },
     ...params.uiMode && { ui_mode: params.uiMode }
   };
@@ -119,6 +154,12 @@ var StripeCheckoutService = class extends HttpService {
       `/stripe/purchase${query}`,
       buildStripeCheckoutSessionBody(params)
     );
+    if (data.status === "failed") {
+      if (isCheckoutBlockReason(data.reason)) {
+        throw new CheckoutBlockedError(data.reason, data.message || void 0);
+      }
+      throw new CheckoutError(`Checkout session refused: ${data.reason}`);
+    }
     if (!data.client_secret) {
       throw new CheckoutError("Backend returned no client_secret");
     }
@@ -151,6 +192,7 @@ var StripeEmbeddedPageUi = class {
 
 // src/providers/stripe/ui/form.ts
 var CHECKOUT_FORM_BETA = "custom_checkout_payment_form_1";
+var EXPRESS_CHECKOUT_SOURCE = "checkout-form-ece";
 var StripeFormUi = class {
   constructor(options = {}) {
     this.options = options;
@@ -206,17 +248,30 @@ var StripeFormUi = class {
     }
     return result.actions;
   }
+  async isFormValid(actions) {
+    try {
+      const validation = await actions.validateElements();
+      return validation.type !== "error";
+    } catch {
+      return true;
+    }
+  }
   async confirm(actions, event, host) {
-    const express = event.source === "checkout-form-ece";
+    const express = event.source === EXPRESS_CHECKOUT_SOURCE;
     const paymentMethodType = express ? void 0 : event.paymentMethodType ?? void 0;
-    host.confirmed({ paymentMethodType, express });
     try {
+      const attempted = express || await this.isFormValid(actions);
+      if (attempted) {
+        host.confirmed({ paymentMethodType, express });
+      }
       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
-        });
+        if (result.error.code === "paymentFailed") {
+          host.paymentFailed(result.error, {
+            declineCode: result.error.paymentFailed.declineCode,
+            message: result.error.message
+          });
+        }
         return;
       }
       host.succeeded(fromSession(result.session));
@@ -266,6 +321,7 @@ var StripeProvider = class {
   ui;
   stripe = null;
   mounted = false;
+  blocked = false;
   clientSecret = null;
   snapshot = {};
   async init() {
@@ -285,7 +341,17 @@ var StripeProvider = class {
       throw new CheckoutError("Already rendered \u2014 call destroy() before rendering again");
     }
     this.mounted = true;
-    await this.ui.mount(this.stripe, container, this.host());
+    this.blocked = false;
+    const returned = await this.takeReturnedSession();
+    if (returned) {
+      this.reportComplete(returned);
+      return;
+    }
+    try {
+      await this.ui.mount(this.stripe, container, this.host());
+    } catch (err) {
+      if (!this.blocked) throw err;
+    }
   }
   async reset() {
     this.destroy();
@@ -309,18 +375,42 @@ var StripeProvider = class {
         provider: "stripe",
         paymentMethodType: this.snapshot.paymentMethodType
       }),
-      renderFailed: (error, detail) => this.emitError("render", error, detail),
+      renderFailed: (error, detail) => {
+        if (!this.blocked) 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
-    });
-    this.clientSecret = secret;
-    return secret;
+    try {
+      const secret = await this.service.createCheckoutSession({
+        ...this.config,
+        returnUrl: this.config.returnUrl || withReturnedSessionParam(window.location.href)
+      });
+      this.clientSecret = secret;
+      return secret;
+    } catch (err) {
+      if (err instanceof CheckoutBlockedError && this.callbacks.onBlocked && this.mounted) {
+        this.blocked = true;
+        this.ui.destroy();
+        this.callbacks.onBlocked({
+          provider: "stripe",
+          reason: err.reason,
+          message: err.buyerMessage
+        });
+      }
+      throw err;
+    }
+  }
+  async takeReturnedSession() {
+    const sessionId = this.config.returnUrl ? null : popSessionIdFromUrl();
+    if (!sessionId) {
+      return null;
+    }
+    const lookup = () => this.service.getSession(sessionId, this.config.accountId);
+    const session = await lookup().catch(lookup).catch(() => null);
+    return session?.status === "complete" ? definedOnly(session) : null;
   }
   // Format: cs_test_{sessionId}_secret_{random}
   sessionId() {
@@ -360,10 +450,13 @@ var StripeProvider = class {
         session = {};
       }
     }
+    this.reportComplete({ ...fallback, ...session });
+  }
+  reportComplete(session) {
     this.callbacks.onComplete?.({
       provider: "stripe",
       paymentMethodType: this.snapshot.paymentMethodType,
-      ...toCompleteFields({ ...fallback, ...session })
+      ...toCompleteFields(session)
     });
   }
   emitError(phase, error, detail) {

package/dist/index.d.cts

@@ -49,7 +49,7 @@ interface StripeConfig {
     customerId?: string;
     /** New customer details — required when customerId is not provided */
     customer?: StripeCustomer;
-    /** URL to redirect to after payment completes. Defaults to window.location.href for embedded checkout. */
+    /** Where redirect-based methods return the buyer. A custom URL completes the session itself. */
     returnUrl?: string;
     /** When true, Stripe displays a promotional code input field in the embedded checkout */
     allowPromoCodes?: boolean;
@@ -61,6 +61,8 @@ interface StripeConfig {
     trial?: StripeCheckoutTrial;
     /** When true, treats this as a subscription upgrade — requires customerId to be set */
     upgrade?: boolean;
+    /** Enables the backend's one-subscription-per-email limit. */
+    isSubscription?: 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`. */
@@ -94,6 +96,12 @@ type ProviderConfigMap = {
     fastspring: FastSpringConfig;
 };
 
+declare class CheckoutError extends Error {
+    constructor(message: string);
+}
+declare const CHECKOUT_BLOCK_REASONS: readonly ["duplicated_subscription", "duplicated_payment"];
+type CheckoutBlockReason = (typeof CHECKOUT_BLOCK_REASONS)[number];
+
 interface CheckoutCompleteEvent {
     provider: ProviderName;
     paymentMethodType?: PaymentMethodType;
@@ -119,6 +127,12 @@ interface CheckoutErrorEvent {
     message?: string;
     error: unknown;
 }
+/** The backend refused to open checkout for a repeat purchase. */
+interface CheckoutBlockedEvent {
+    provider: ProviderName;
+    reason: CheckoutBlockReason;
+    message?: string;
+}
 interface CheckoutCancelEvent {
     provider: ProviderName;
     paymentMethodType?: PaymentMethodType;
@@ -153,6 +167,7 @@ interface CheckoutCallbacks {
     onReady?: (event: CheckoutReadyEvent) => void;
     onConfirm?: (event: CheckoutConfirmEvent) => void;
     onChange?: (event: CheckoutChangeEvent) => void;
+    onBlocked?: (event: CheckoutBlockedEvent) => void;
 }
 
 interface RenderOptions {
@@ -179,13 +194,9 @@ type InitCheckoutConfig<T extends ProviderName> = {
 } & CheckoutCallbacks;
 declare function initCheckout<T extends ProviderName>(options: InitCheckoutConfig<T>): Promise<CheckoutInstance>;
 
-declare class CheckoutError extends Error {
-    constructor(message: string);
-}
-
 type CreateCheckoutSessionParams = Omit<StripeConfig, 'publishableKey' | 'returnUrl' | 'form'> & {
     returnUrl: string;
 };
 declare function buildStripeCheckoutSessionBody(params: CreateCheckoutSessionParams): Record<string, unknown>;
 
-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 };
+export { type CheckoutBlockReason, type CheckoutBlockedEvent, 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

@@ -49,7 +49,7 @@ interface StripeConfig {
     customerId?: string;
     /** New customer details — required when customerId is not provided */
     customer?: StripeCustomer;
-    /** URL to redirect to after payment completes. Defaults to window.location.href for embedded checkout. */
+    /** Where redirect-based methods return the buyer. A custom URL completes the session itself. */
     returnUrl?: string;
     /** When true, Stripe displays a promotional code input field in the embedded checkout */
     allowPromoCodes?: boolean;
@@ -61,6 +61,8 @@ interface StripeConfig {
     trial?: StripeCheckoutTrial;
     /** When true, treats this as a subscription upgrade — requires customerId to be set */
     upgrade?: boolean;
+    /** Enables the backend's one-subscription-per-email limit. */
+    isSubscription?: 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`. */
@@ -94,6 +96,12 @@ type ProviderConfigMap = {
     fastspring: FastSpringConfig;
 };
 
+declare class CheckoutError extends Error {
+    constructor(message: string);
+}
+declare const CHECKOUT_BLOCK_REASONS: readonly ["duplicated_subscription", "duplicated_payment"];
+type CheckoutBlockReason = (typeof CHECKOUT_BLOCK_REASONS)[number];
+
 interface CheckoutCompleteEvent {
     provider: ProviderName;
     paymentMethodType?: PaymentMethodType;
@@ -119,6 +127,12 @@ interface CheckoutErrorEvent {
     message?: string;
     error: unknown;
 }
+/** The backend refused to open checkout for a repeat purchase. */
+interface CheckoutBlockedEvent {
+    provider: ProviderName;
+    reason: CheckoutBlockReason;
+    message?: string;
+}
 interface CheckoutCancelEvent {
     provider: ProviderName;
     paymentMethodType?: PaymentMethodType;
@@ -153,6 +167,7 @@ interface CheckoutCallbacks {
     onReady?: (event: CheckoutReadyEvent) => void;
     onConfirm?: (event: CheckoutConfirmEvent) => void;
     onChange?: (event: CheckoutChangeEvent) => void;
+    onBlocked?: (event: CheckoutBlockedEvent) => void;
 }
 
 interface RenderOptions {
@@ -179,13 +194,9 @@ type InitCheckoutConfig<T extends ProviderName> = {
 } & CheckoutCallbacks;
 declare function initCheckout<T extends ProviderName>(options: InitCheckoutConfig<T>): Promise<CheckoutInstance>;
 
-declare class CheckoutError extends Error {
-    constructor(message: string);
-}
-
 type CreateCheckoutSessionParams = Omit<StripeConfig, 'publishableKey' | 'returnUrl' | 'form'> & {
     returnUrl: string;
 };
 declare function buildStripeCheckoutSessionBody(params: CreateCheckoutSessionParams): Record<string, unknown>;
 
-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 };
+export { type CheckoutBlockReason, type CheckoutBlockedEvent, 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

@@ -5,10 +5,44 @@ var CheckoutError = class extends Error {
     this.name = "CheckoutError";
   }
 };
+var CHECKOUT_BLOCK_REASONS = ["duplicated_subscription", "duplicated_payment"];
+function isCheckoutBlockReason(reason) {
+  return CHECKOUT_BLOCK_REASONS.some((known) => known === reason);
+}
+var CheckoutBlockedError = class extends CheckoutError {
+  constructor(reason, buyerMessage) {
+    super(`Checkout blocked: ${reason}`);
+    this.reason = reason;
+    this.buyerMessage = buyerMessage;
+    this.name = "CheckoutBlockedError";
+  }
+  reason;
+  buyerMessage;
+};
 
 // src/providers/stripe/index.ts
 import { loadStripe } from "@stripe/stripe-js";
 
+// src/providers/stripe/return-url.ts
+var RETURNED_SESSION_PARAM = "ff_checkout_session";
+var SESSION_ID_PLACEHOLDER = "{CHECKOUT_SESSION_ID}";
+var SESSION_ID = /^cs_\w+$/;
+function withReturnedSessionParam(href) {
+  const url = new URL(href);
+  url.searchParams.set(RETURNED_SESSION_PARAM, SESSION_ID_PLACEHOLDER);
+  return url.href.replace(encodeURIComponent(SESSION_ID_PLACEHOLDER), SESSION_ID_PLACEHOLDER);
+}
+function popSessionIdFromUrl() {
+  const url = new URL(window.location.href);
+  const sessionId = url.searchParams.get(RETURNED_SESSION_PARAM);
+  if (sessionId === null) {
+    return null;
+  }
+  url.searchParams.delete(RETURNED_SESSION_PARAM);
+  window.history.replaceState(window.history.state, "", url.href);
+  return SESSION_ID.test(sessionId) ? sessionId : null;
+}
+
 // src/providers/stripe/helpers.ts
 function buildStripeCheckoutSessionBody(params) {
   return {
@@ -34,6 +68,7 @@ function buildStripeCheckoutSessionBody(params) {
       }
     },
     ...params.upgrade && { upgrade: params.upgrade },
+    ...params.isSubscription !== void 0 && { is_subscription: params.isSubscription },
     ...params.walletFirst && { wallet_first: params.walletFirst },
     ...params.uiMode && { ui_mode: params.uiMode }
   };
@@ -91,6 +126,12 @@ var StripeCheckoutService = class extends HttpService {
       `/stripe/purchase${query}`,
       buildStripeCheckoutSessionBody(params)
     );
+    if (data.status === "failed") {
+      if (isCheckoutBlockReason(data.reason)) {
+        throw new CheckoutBlockedError(data.reason, data.message || void 0);
+      }
+      throw new CheckoutError(`Checkout session refused: ${data.reason}`);
+    }
     if (!data.client_secret) {
       throw new CheckoutError("Backend returned no client_secret");
     }
@@ -123,6 +164,7 @@ var StripeEmbeddedPageUi = class {
 
 // src/providers/stripe/ui/form.ts
 var CHECKOUT_FORM_BETA = "custom_checkout_payment_form_1";
+var EXPRESS_CHECKOUT_SOURCE = "checkout-form-ece";
 var StripeFormUi = class {
   constructor(options = {}) {
     this.options = options;
@@ -178,17 +220,30 @@ var StripeFormUi = class {
     }
     return result.actions;
   }
+  async isFormValid(actions) {
+    try {
+      const validation = await actions.validateElements();
+      return validation.type !== "error";
+    } catch {
+      return true;
+    }
+  }
   async confirm(actions, event, host) {
-    const express = event.source === "checkout-form-ece";
+    const express = event.source === EXPRESS_CHECKOUT_SOURCE;
     const paymentMethodType = express ? void 0 : event.paymentMethodType ?? void 0;
-    host.confirmed({ paymentMethodType, express });
     try {
+      const attempted = express || await this.isFormValid(actions);
+      if (attempted) {
+        host.confirmed({ paymentMethodType, express });
+      }
       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
-        });
+        if (result.error.code === "paymentFailed") {
+          host.paymentFailed(result.error, {
+            declineCode: result.error.paymentFailed.declineCode,
+            message: result.error.message
+          });
+        }
         return;
       }
       host.succeeded(fromSession(result.session));
@@ -238,6 +293,7 @@ var StripeProvider = class {
   ui;
   stripe = null;
   mounted = false;
+  blocked = false;
   clientSecret = null;
   snapshot = {};
   async init() {
@@ -257,7 +313,17 @@ var StripeProvider = class {
       throw new CheckoutError("Already rendered \u2014 call destroy() before rendering again");
     }
     this.mounted = true;
-    await this.ui.mount(this.stripe, container, this.host());
+    this.blocked = false;
+    const returned = await this.takeReturnedSession();
+    if (returned) {
+      this.reportComplete(returned);
+      return;
+    }
+    try {
+      await this.ui.mount(this.stripe, container, this.host());
+    } catch (err) {
+      if (!this.blocked) throw err;
+    }
   }
   async reset() {
     this.destroy();
@@ -281,18 +347,42 @@ var StripeProvider = class {
         provider: "stripe",
         paymentMethodType: this.snapshot.paymentMethodType
       }),
-      renderFailed: (error, detail) => this.emitError("render", error, detail),
+      renderFailed: (error, detail) => {
+        if (!this.blocked) 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
-    });
-    this.clientSecret = secret;
-    return secret;
+    try {
+      const secret = await this.service.createCheckoutSession({
+        ...this.config,
+        returnUrl: this.config.returnUrl || withReturnedSessionParam(window.location.href)
+      });
+      this.clientSecret = secret;
+      return secret;
+    } catch (err) {
+      if (err instanceof CheckoutBlockedError && this.callbacks.onBlocked && this.mounted) {
+        this.blocked = true;
+        this.ui.destroy();
+        this.callbacks.onBlocked({
+          provider: "stripe",
+          reason: err.reason,
+          message: err.buyerMessage
+        });
+      }
+      throw err;
+    }
+  }
+  async takeReturnedSession() {
+    const sessionId = this.config.returnUrl ? null : popSessionIdFromUrl();
+    if (!sessionId) {
+      return null;
+    }
+    const lookup = () => this.service.getSession(sessionId, this.config.accountId);
+    const session = await lookup().catch(lookup).catch(() => null);
+    return session?.status === "complete" ? definedOnly(session) : null;
   }
   // Format: cs_test_{sessionId}_secret_{random}
   sessionId() {
@@ -332,10 +422,13 @@ var StripeProvider = class {
         session = {};
       }
     }
+    this.reportComplete({ ...fallback, ...session });
+  }
+  reportComplete(session) {
     this.callbacks.onComplete?.({
       provider: "stripe",
       paymentMethodType: this.snapshot.paymentMethodType,
-      ...toCompleteFields({ ...fallback, ...session })
+      ...toCompleteFields(session)
     });
   }
   emitError(phase, error, detail) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelfox/payments-sdk",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.3",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -21,7 +21,7 @@
     "dev": "tsup --watch"
   },
   "dependencies": {
-    "@stripe/stripe-js": "^9.1.0"
+    "@stripe/stripe-js": "^9.14.0"
   },
   "devDependencies": {
     "tsup": "^8.4.0",