@antelopejs/dms-saas 0.3.9 → 0.3.11

package/frontend-vue/app/components/PendingCheckoutModal.vue

@@ -0,0 +1,78 @@
+<script setup lang="ts">
+import { computed, ref } from "vue";
+
+const KEY_PREFIX = "saas.workspace.plan.checkout_pending";
+
+const toast = useToast();
+const { resolveApiError } = useApiErrorMessage();
+const { prompt, resume, startOver } = usePendingCheckout();
+
+const isRestarting = ref(false);
+
+const open = computed({
+  get: () => prompt.value !== null,
+  set: (isOpen: boolean) => {
+    if (!isOpen) prompt.value = null;
+  },
+});
+
+const pending = computed(() => prompt.value?.pending ?? null);
+const canResume = computed(() => !!pending.value?.checkoutUrl);
+
+/** A paid checkout only waits for Stripe; one still opening only for time. */
+const descriptionKey = computed(() => {
+  if (pending.value?.isPaid) return `${KEY_PREFIX}.description_paid`;
+  return canResume.value
+    ? `${KEY_PREFIX}.description`
+    : `${KEY_PREFIX}.description_opening`;
+});
+
+async function restart(): Promise<void> {
+  isRestarting.value = true;
+  try {
+    await startOver();
+  } catch (error) {
+    toast.add({
+      title: resolveApiError(error, `${KEY_PREFIX}.restart_error`),
+      color: "error",
+      icon: "i-ph-warning-circle",
+    });
+    isRestarting.value = false;
+  }
+}
+</script>
+
+<template>
+  <UModal
+    v-model:open="open"
+    :title="$t(`${KEY_PREFIX}.title`)"
+    :description="$t(descriptionKey)"
+  >
+    <template #footer>
+      <div class="flex w-full flex-wrap justify-end gap-2">
+        <UButton color="neutral" variant="subtle" @click="open = false">
+          {{ $t(`${KEY_PREFIX}.close`) }}
+        </UButton>
+        <UButton
+          v-if="canResume"
+          color="neutral"
+          variant="outline"
+          icon="i-ph-arrow-counter-clockwise"
+          :loading="isRestarting"
+          @click="restart"
+        >
+          {{ $t(`${KEY_PREFIX}.restart`) }}
+        </UButton>
+        <UButton
+          v-if="canResume"
+          color="primary"
+          icon="i-ph-lock-simple"
+          :disabled="isRestarting"
+          @click="resume"
+        >
+          {{ $t(`${KEY_PREFIX}.resume`) }}
+        </UButton>
+      </div>
+    </template>
+  </UModal>
+</template>

package/frontend-vue/app/components/PlanComparisonModal.vue

@@ -20,6 +20,7 @@ const { t } = useI18n();
 const toast = useToast();
 const { resolveApiError } = useApiErrorMessage();
 const { changePlan } = useTenantPlan();
+const { offerFor: offerPendingCheckout } = usePendingCheckout();
 const { formatFeatureValue } = usePlanFeatureFormat();
 const { featureLabel, featureTooltip } = usePlanFeatureLabel();
 const { formatMajorUnits } = useMoneyFormat();
@@ -102,6 +103,10 @@ async function select(plan: TenantPlanView): Promise<void> {
     open.value = false;
     emit("changed");
   } catch (error) {
+    if (await offerPendingCheckout(error, plan._id)) {
+      open.value = false;
+      return;
+    }
     toast.add({
       title: resolveApiError(error, "saas.workspace.plan.change_error"),
       color: "error",

package/frontend-vue/app/components/PlanUpgradeModal.vue

@@ -16,6 +16,7 @@ const { t } = useI18n();
 const { resolveApiError } = useApiErrorMessage();
 const identity = useBillingIdentity();
 const { changePlan } = useTenantPlan();
+const { offerFor: offerPendingCheckout } = usePendingCheckout();
 const { formatMajorUnits } = useMoneyFormat();
 const planIntervalLabel = usePlanIntervalLabel("saas.workspace.plan.interval");
 
@@ -87,6 +88,10 @@ async function confirm(): Promise<void> {
     open.value = false;
     emit("changed");
   } catch (error) {
+    if (await offerPendingCheckout(error, plan._id)) {
+      open.value = false;
+      return;
+    }
     notifyError(resolveApiError(error, "saas.workspace.plan.change_error"));
   } finally {
     isSubmitting.value = false;

package/frontend-vue/app/components/TenantPlanCard.vue

@@ -25,6 +25,7 @@ const { featureLabel } = usePlanFeatureLabel();
 const planDescription = usePlanDescription();
 const { workspace, load: loadWorkspace } = useCurrentWorkspace();
 const { isOpen: isComparisonOpen } = usePlanComparison();
+const { consumeCancelledCheckout } = usePendingCheckout();
 const planIntervalLabel = usePlanIntervalLabel("saas.workspace.plan.interval");
 
 const data = ref<TenantPlanResponse | null>(null);
@@ -164,8 +165,32 @@ async function loadWorkspaceForOwner(): Promise<void> {
   if (status?.isTenantOwner) await loadWorkspace().catch(() => undefined);
 }
 
-onMounted(() => {
+/** Back from Stripe's cancel link: the checkout left behind is released
+ * before the card loads, so the plan buttons work straight away. */
+async function releaseCancelledCheckout(): Promise<void> {
+  try {
+    const { released } = await consumeCancelledCheckout();
+    if (!released) return;
+    toast.add({
+      title: t("saas.workspace.plan.checkout_pending.cancelled"),
+      color: "info",
+      icon: "i-ph-info",
+    });
+  } catch (error) {
+    toast.add({
+      title: resolveApiError(
+        error,
+        "saas.workspace.plan.checkout_pending.restart_error",
+      ),
+      color: "error",
+      icon: "i-ph-warning-circle",
+    });
+  }
+}
+
+onMounted(async () => {
   void loadWorkspaceForOwner();
+  await releaseCancelledCheckout();
   return fetchPlan(false);
 });
 </script>
@@ -279,6 +304,7 @@ onMounted(() => {
         :plan="upgradeTarget"
         @changed="refresh"
       />
+      <DmsSaasPendingCheckoutModal />
     </div>
   </UCard>
 </template>

package/frontend-vue/app/components/WorkspaceCreateModal.vue

@@ -39,6 +39,7 @@ const planIntervalLabel = usePlanIntervalLabel(
 );
 const planDescription = usePlanDescription();
 const config = useDmsRuntimeConfig();
+const { user } = useCurrentUser();
 
 const stripePublishableKey = computed<string>(
   () => (config.public.dmsSaas as any)?.stripePublishableKey ?? "",
@@ -121,6 +122,7 @@ async function initStripeElement(): Promise<void> {
     publishableKey: stripePublishableKey.value,
     clientSecret: setup.clientSecret,
     containerId: PAYMENT_ELEMENT_ID,
+    billingEmail: () => user.value?.email ?? "",
   });
 }
 

package/frontend-vue/app/composables/useApiErrorMessage.ts

@@ -1,3 +1,11 @@
+/** The i18n key the server answered a failed `$authFetch` with, if any. */
+export function readApiErrorKey(error: unknown): string | undefined {
+  const data = (error as { data?: unknown } | undefined)?.data;
+  if (typeof data === "string") return data;
+  const message = (data as { message?: unknown } | undefined)?.message;
+  return typeof message === "string" ? message : undefined;
+}
+
 /**
  * Resolves an unknown error thrown by `$authFetch` into a human-readable,
  * translated message.
@@ -12,17 +20,10 @@
 export function useApiErrorMessage() {
   const nuxtApp = useDmsApp();
 
-  function extractServerKey(error: unknown): string | undefined {
-    const data = (error as { data?: unknown } | undefined)?.data;
-    if (typeof data === "string") return data;
-    const message = (data as { message?: unknown } | undefined)?.message;
-    return typeof message === "string" ? message : undefined;
-  }
-
   /** Translated server message, or `undefined` when the server sent no usable key. */
   function resolveServerMessage(error: unknown): string | undefined {
     const { t, te } = nuxtApp.$i18n;
-    const key = extractServerKey(error);
+    const key = readApiErrorKey(error);
     return key && te(key) ? t(key) : undefined;
   }
 

package/frontend-vue/app/composables/usePendingCheckout.ts

@@ -0,0 +1,88 @@
+const CHECKOUT_IN_PROGRESS_KEY = "saas.errors.plan.checkout_in_progress";
+const PROMPT_STATE_KEY = "saas-pending-checkout-prompt";
+const CHECKOUT_CANCELLED_PARAM = "checkout";
+const CHECKOUT_CANCELLED_VALUE = "cancelled";
+
+/** A plan change refused because an earlier checkout is still pending. */
+export interface PendingCheckoutPrompt {
+  /** The plan the owner just chose, which starting over checks out. */
+  planId: string;
+  pending: PendingCheckout | null;
+}
+
+export function isCheckoutInProgressError(error: unknown): boolean {
+  return readApiErrorKey(error) === CHECKOUT_IN_PROGRESS_KEY;
+}
+
+/**
+ * The owner's way out of a checkout they left unpaid: resume it, or give it
+ * up and start over. The prompt state is shared so the plan modals can raise
+ * it and the plan card, which outlives them, can host it.
+ */
+export function usePendingCheckout() {
+  const prompt = useDmsState<PendingCheckoutPrompt | null>(
+    PROMPT_STATE_KEY,
+    () => null,
+  );
+  const route = useDmsRoute();
+  const router = useDmsRouter();
+  const { loadPendingCheckout, cancelCheckout, changePlan } = useTenantPlan();
+
+  /** Raises the prompt when `error` is a pending-checkout refusal. */
+  async function offerFor(error: unknown, planId: string): Promise<boolean> {
+    if (!isCheckoutInProgressError(error)) return false;
+    const { pending } = await loadPendingCheckout().catch(() => ({
+      pending: null,
+    }));
+    prompt.value = { planId, pending };
+    return true;
+  }
+
+  function resume(): void {
+    const url = prompt.value?.pending?.checkoutUrl;
+    if (url && typeof window !== "undefined") window.location.href = url;
+  }
+
+  /** Gives up the pending checkout, then opens one for the chosen plan. */
+  async function startOver(): Promise<void> {
+    const planId = prompt.value?.planId;
+    if (!planId) return;
+    await cancelCheckout();
+    const result = await changePlan(planId);
+    if (result.checkoutUrl && typeof window !== "undefined") {
+      window.location.href = result.checkoutUrl;
+    }
+  }
+
+  /** The operation named by the Stripe cancel link the page was opened from. */
+  function cancelledOperationId(): string | null {
+    const { query } = route;
+    const operationId = query[CHECKOUT_OPERATION_PARAM];
+    if (query[CHECKOUT_CANCELLED_PARAM] !== CHECKOUT_CANCELLED_VALUE) {
+      return null;
+    }
+    return typeof operationId === "string" && operationId ? operationId : null;
+  }
+
+  /**
+   * Stripe's cancel link lands back on the billing page naming the checkout
+   * the owner walked out of; releasing it here lets them choose again at
+   * once. The marker is dropped either way, so a reload does not replay it.
+   */
+  async function consumeCancelledCheckout(): Promise<CancelCheckoutResult> {
+    const operationId = cancelledOperationId();
+    if (!operationId) return { released: false };
+    const {
+      [CHECKOUT_CANCELLED_PARAM]: _cancelled,
+      [CHECKOUT_OPERATION_PARAM]: _operation,
+      ...query
+    } = route.query;
+    try {
+      return await cancelCheckout(operationId);
+    } finally {
+      await router.replace({ query });
+    }
+  }
+
+  return { prompt, offerFor, resume, startOver, consumeCancelledCheckout };
+}

package/frontend-vue/app/composables/useSaasRegistration.ts

@@ -293,6 +293,7 @@ export function useSaasRegistration(options: UseSaasRegistrationOptions = {}) {
       publishableKey,
       clientSecret: setup.clientSecret,
       containerId: paymentElementId,
+      billingEmail: () => form.email,
     });
   }
 

package/frontend-vue/app/composables/useStripePaymentElement.ts

@@ -1,14 +1,55 @@
-import { onUnmounted } from "vue";
+import { type MaybeRefOrGetter, onUnmounted, toValue } from "vue";
 
 interface UseStripePaymentElementOptions {
   publishableKey: string;
   clientSecret: string;
   containerId: string;
+  /**
+   * The payer's email, sent with the card: the Payment Element does not ask
+   * for it, since every caller already knows who is paying. Read at confirm
+   * time, so a form field may be passed as a getter.
+   */
+  billingEmail: MaybeRefOrGetter<string>;
+}
+
+interface ConfirmError {
+  message: string;
 }
 
 interface ConfirmResult {
   paymentMethodId?: string;
-  error?: { message: string };
+  error?: ConfirmError;
+}
+
+interface SetupIntentSnapshot {
+  payment_method?: unknown;
+}
+
+interface StripeErrorSnapshot {
+  message?: string;
+}
+
+interface SetupIntentResult {
+  setupIntent?: SetupIntentSnapshot;
+  error?: StripeErrorSnapshot;
+}
+
+interface BillingDetails {
+  email: string;
+}
+
+interface PaymentMethodData {
+  billing_details: BillingDetails;
+}
+
+interface SetupConfirmParams {
+  payment_method_data: PaymentMethodData;
+}
+
+interface SetupConfirmation {
+  elements: unknown;
+  redirect: "if_required";
+  confirmParams: SetupConfirmParams;
 }
 
 interface StripePaymentElementHandle {
@@ -19,6 +60,43 @@ interface StripePaymentElementHandle {
 // rejects `paymentMethodTypes` next to a `clientSecret`, since it only applies
 // to an Elements instance created in deferred-intent `mode`.
 const ALLOWED_CARD_BRANDS = ["visa", "mastercard"];
+const UNKNOWN_STRIPE_ERROR = "Stripe could not confirm the card";
+
+/**
+ * The `confirmSetup` parameters. The element hides the email field, and
+ * Stripe then refuses any confirmation that does not carry the email itself.
+ */
+export function buildSetupConfirmation(
+  elements: unknown,
+  email: string,
+): SetupConfirmation {
+  return {
+    elements,
+    redirect: "if_required",
+    confirmParams: {
+      payment_method_data: { billing_details: { email } },
+    },
+  };
+}
+
+/** Maps a `confirmSetup` outcome to the confirmed card, or Stripe's reason. */
+export function toConfirmResult(result: SetupIntentResult): ConfirmResult {
+  if (result.error) {
+    return { error: { message: result.error.message ?? UNKNOWN_STRIPE_ERROR } };
+  }
+  const paymentMethodId = result.setupIntent?.payment_method;
+  if (typeof paymentMethodId !== "string") {
+    return { error: { message: "No payment method returned" } };
+  }
+  return { paymentMethodId };
+}
+
+// Stripe.js throws, rather than returns, integration errors: without this
+// the caller only sees its own generic failure and the cause is lost.
+function toThrownConfirmResult(error: unknown): ConfirmResult {
+  const message = error instanceof Error ? error.message : "";
+  return { error: { message: message || UNKNOWN_STRIPE_ERROR } };
+}
 
 export function useStripePaymentElement(
   options: UseStripePaymentElementOptions,
@@ -49,18 +127,17 @@ export function useStripePaymentElement(
     if (!stripeInstance || !elementsInstance) {
       return { error: { message: "Stripe not initialized" } };
     }
-    const result = await stripeInstance.confirmSetup({
-      elements: elementsInstance,
-      redirect: "if_required",
-    });
-    if (result.error) {
-      return { error: { message: result.error.message } };
-    }
-    const paymentMethodId = result.setupIntent?.payment_method;
-    if (typeof paymentMethodId !== "string") {
-      return { error: { message: "No payment method returned" } };
+    try {
+      const result: SetupIntentResult = await stripeInstance.confirmSetup(
+        buildSetupConfirmation(
+          elementsInstance,
+          toValue(options.billingEmail),
+        ),
+      );
+      return toConfirmResult(result);
+    } catch (error) {
+      return toThrownConfirmResult(error);
     }
-    return { paymentMethodId };
   }
 
   onUnmounted(() => {

package/frontend-vue/app/composables/useTenantPlan.ts

@@ -2,6 +2,10 @@ import type { PlanInterval } from "./usePlanIntervalLabel";
 
 const TENANT_PLAN_ENDPOINT = "/api/saas/tenant/plan";
 const TENANT_PLAN_STATE_KEY = "saas-tenant-plan";
+const TENANT_CHECKOUT_ENDPOINT = `${TENANT_PLAN_ENDPOINT}/checkout`;
+
+/** Query parameter naming the checkout a Stripe cancel link belongs to. */
+export const CHECKOUT_OPERATION_PARAM = "checkoutOperation";
 
 export interface TenantPlanFeature {
   featureId: string;
@@ -68,6 +72,24 @@ export interface ChangePlanResult {
   checkoutUrl: string | null;
 }
 
+/** The Stripe Checkout a workspace is waiting on. */
+export interface PendingCheckout {
+  targetPlanId: string | null;
+  /** Where the owner resumes paying; null once nothing is left to pay. */
+  checkoutUrl: string | null;
+  expiresAt: string | null;
+  /** Paid, and waiting for Stripe to confirm it. */
+  isPaid: boolean;
+}
+
+export interface PendingCheckoutResult {
+  pending: PendingCheckout | null;
+}
+
+export interface CancelCheckoutResult {
+  released: boolean;
+}
+
 /** The payload resolves inheritance for every public plan and carries the
  * features catalogue, so the plan card and the free-access banner share it. */
 export function useTenantPlan() {
@@ -91,5 +113,23 @@ export function useTenantPlan() {
     });
   }
 
-  return { ...shared, changePlan, cancelPendingChange };
+  function loadPendingCheckout(): Promise<PendingCheckoutResult> {
+    return $authFetch<PendingCheckoutResult>(TENANT_CHECKOUT_ENDPOINT);
+  }
+
+  /** Without an operation id, gives up on whatever checkout is pending. */
+  function cancelCheckout(operationId?: string): Promise<CancelCheckoutResult> {
+    return $authFetch<CancelCheckoutResult>(TENANT_CHECKOUT_ENDPOINT, {
+      method: "DELETE",
+      query: operationId ? { [CHECKOUT_OPERATION_PARAM]: operationId } : {},
+    });
+  }
+
+  return {
+    ...shared,
+    changePlan,
+    cancelPendingChange,
+    loadPendingCheckout,
+    cancelCheckout,
+  };
 }

package/frontend-vue/app/custom-pages/auth/no-workspace.vue

@@ -130,6 +130,7 @@ async function initStripeElement(): Promise<void> {
     publishableKey,
     clientSecret: setup.clientSecret,
     containerId: PAYMENT_ELEMENT_ID,
+    billingEmail: () => pendingRegistration.value?.email ?? "",
   });
 }
 

package/frontend-vue/i18n/locales/saas-en-GB.json

@@ -45,6 +45,7 @@
         "unpaid_invoice_blocks_downgrade": "An invoice is unpaid. Settle it before changing to a cheaper plan.",
         "no_free_plan": "No free plan is available for sign-up right now.",
         "checkout_in_progress": "A payment for a plan change is already open. Complete it, or wait for it to expire, before choosing another plan.",
+        "checkout_already_paid": "This payment has already been made and is being confirmed. Your plan will update in a moment.",
         "change_in_progress": "A plan change is already being processed. Try again in a few minutes."
       },
       "workspace": {
@@ -1081,6 +1082,17 @@
         "change_applied": "Plan changed.",
         "change_scheduled": "Downgrade scheduled for the end of the current cycle.",
         "change_error": "Failed to change plan",
+        "checkout_pending": {
+          "title": "A payment is already open",
+          "description": "You opened the secure Stripe payment page without completing it. Resume that payment, or cancel it and start over.",
+          "description_paid": "Your payment has been received and is being confirmed. Your plan will update in a moment.",
+          "description_opening": "A payment page is still being opened for this workspace. Try again in a few minutes.",
+          "resume": "Resume payment",
+          "restart": "Cancel and start over",
+          "close": "Close",
+          "cancelled": "Payment cancelled. Nothing was charged and your plan is unchanged.",
+          "restart_error": "The pending payment could not be cancelled. Try again in a moment."
+        },
         "interval": {
           "month": "month",
           "year": "year"

package/frontend-vue/i18n/locales/saas-fr-FR.json

@@ -45,6 +45,7 @@
         "unpaid_invoice_blocks_downgrade": "Une facture est impayée. Réglez-la avant de passer à un plan moins cher.",
         "no_free_plan": "Aucun plan gratuit n'est disponible pour l'inscription pour le moment.",
         "checkout_in_progress": "Un paiement de changement de plan est déjà ouvert. Terminez-le, ou attendez son expiration, avant de choisir un autre plan.",
+        "checkout_already_paid": "Ce paiement a déjà été effectué et est en cours de confirmation. Votre plan sera mis à jour dans un instant.",
         "change_in_progress": "Un changement de plan est déjà en cours. Réessayez dans quelques minutes."
       },
       "workspace": {
@@ -1081,6 +1082,17 @@
         "change_applied": "Plan modifié.",
         "change_scheduled": "Downgrade programmé pour la fin du cycle en cours.",
         "change_error": "Échec du changement de plan",
+        "checkout_pending": {
+          "title": "Un paiement est déjà en cours",
+          "description": "Vous avez ouvert la page de paiement sécurisée de Stripe sans la terminer. Reprenez ce paiement, ou annulez-le pour recommencer.",
+          "description_paid": "Votre paiement a été reçu et est en cours de confirmation. Votre plan sera mis à jour dans un instant.",
+          "description_opening": "Une page de paiement est encore en cours d'ouverture pour cet espace de travail. Réessayez dans quelques minutes.",
+          "resume": "Reprendre le paiement",
+          "restart": "Annuler et recommencer",
+          "close": "Fermer",
+          "cancelled": "Paiement annulé. Rien n'a été débité et votre plan est inchangé.",
+          "restart_error": "Le paiement en cours n'a pas pu être annulé. Réessayez dans un instant."
+        },
         "interval": {
           "month": "mois",
           "year": "an"

package/frontend-vue/package.json

@@ -5,6 +5,9 @@
 	"type": "module",
 	"license": "Apache-2.0",
 	"packageManager": "pnpm@10.6.5",
+	"engines": {
+		"@antelopejs/dms-frontend": ">=0.3.1 <0.4.0"
+	},
 	"scripts": {
 		"format": "prettier --write .",
 		"lint": "eslint .",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-saas",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -38,7 +38,7 @@
     "@antelopejs/interface-dms": ">=0.3.2 <1.0.0",
     "@antelopejs/interface-dms-saas": ">=0.2.3 <0.3.0",
     "node-cron": "^4.2.1",
-    "stripe": "^18.5.0",
+    "stripe": "^22.6.2",
     "zod": "^3.24.4"
   },
   "devDependencies": {