@carlonicora/nextjs-jsonapi 1.28.0 → 1.29.1

package/src/features/billing/stripe-subscription/components/widgets/index.ts

@@ -1,4 +1,7 @@
+export * from "./IntervalToggle";
 export * from "./PricingCard";
-export * from "./PricingCardsGrid";
+export * from "./ProductPricingList";
+export * from "./ProductPricingRow";
 export * from "./ProrationPreview";
 export * from "./SubscriptionStatusBadge";
+export * from "./SubscriptionConfirmation";

package/src/features/billing/stripe-subscription/components/wizards/SubscriptionWizard.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "../../../../../shadcnui";
+import { StripeSubscriptionInterface } from "../../data";
+import { useSubscriptionWizard } from "../../hooks/useSubscriptionWizard";
+import { WizardProgressIndicator } from "./WizardProgressIndicator";
+import { WizardStepPlanSelection } from "./WizardStepPlanSelection";
+import { WizardStepReview } from "./WizardStepReview";
+import { WizardStepPaymentMethod } from "./WizardStepPaymentMethod";
+
+export type SubscriptionWizardProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onSuccess: () => void;
+  hasActiveRecurringSubscription: boolean;
+  subscription?: StripeSubscriptionInterface;
+};
+
+export function SubscriptionWizard({
+  open,
+  onOpenChange,
+  onSuccess,
+  hasActiveRecurringSubscription,
+  subscription,
+}: SubscriptionWizardProps) {
+  const handleClose = useCallback(() => onOpenChange(false), [onOpenChange]);
+
+  const { state, actions } = useSubscriptionWizard({
+    subscription,
+    onSuccess,
+    onClose: handleClose,
+  });
+
+  // Track if we've already checked payment method for this open state
+  const hasCheckedRef = useRef(false);
+
+  // Check payment method on mount
+  useEffect(() => {
+    if (open && !hasCheckedRef.current) {
+      hasCheckedRef.current = true;
+      actions.checkPaymentMethod();
+    }
+    if (!open) {
+      hasCheckedRef.current = false;
+    }
+  }, [open, actions.checkPaymentMethod]);
+
+  // Reset state when dialog closes
+  useEffect(() => {
+    if (!open) {
+      actions.reset();
+    }
+  }, [open, actions.reset]);
+
+  const dialogTitle = subscription ? "Change Subscription Plan" : "Subscribe to a Plan";
+  const dialogDescription = subscription
+    ? "Select a new plan for your subscription"
+    : "Choose a subscription plan to get started";
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-2xl">
+        <DialogHeader>
+          <DialogTitle>{dialogTitle}</DialogTitle>
+          <DialogDescription>{dialogDescription}</DialogDescription>
+        </DialogHeader>
+
+        <WizardProgressIndicator currentStep={state.step} />
+
+        {state.step === "plan-selection" && (
+          <WizardStepPlanSelection
+            selectedPrice={state.selectedPrice}
+            selectedInterval={state.selectedInterval}
+            currentPriceId={subscription?.price?.id}
+            hideRecurringPrices={hasActiveRecurringSubscription && !subscription}
+            onSelectPrice={actions.selectPrice}
+            onIntervalChange={actions.setInterval}
+            onNext={actions.goToReview}
+            isProcessing={state.isProcessing}
+          />
+        )}
+
+        {state.step === "review" && (
+          <WizardStepReview
+            selectedPrice={state.selectedPrice}
+            subscription={subscription}
+            prorationPreview={state.prorationPreview}
+            hasPaymentMethod={state.hasPaymentMethod}
+            error={state.error}
+            isProcessing={state.isProcessing}
+            onBack={() => actions.goToStep("plan-selection")}
+            onAddPaymentMethod={() => actions.goToStep("payment-method")}
+            onConfirm={actions.confirmSubscription}
+          />
+        )}
+
+        {state.step === "payment-method" && (
+          <WizardStepPaymentMethod
+            onBack={() => actions.goToStep("review")}
+            onSuccess={actions.handlePaymentMethodSuccess}
+            isProcessing={state.isProcessing}
+          />
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/features/billing/stripe-subscription/components/wizards/WizardProgressIndicator.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import { Check } from "lucide-react";
+import { WizardStep } from "../../hooks/useSubscriptionWizard";
+
+type WizardProgressIndicatorProps = {
+  currentStep: WizardStep;
+};
+
+const STEPS: { key: WizardStep; label: string }[] = [
+  { key: "plan-selection", label: "Select Plan" },
+  { key: "review", label: "Review" },
+  { key: "payment-method", label: "Payment" },
+];
+
+function getStepIndex(step: WizardStep): number {
+  return STEPS.findIndex((s) => s.key === step);
+}
+
+export function WizardProgressIndicator({ currentStep }: WizardProgressIndicatorProps) {
+  const currentIndex = getStepIndex(currentStep);
+
+  return (
+    <div className="flex items-center justify-center gap-x-2 py-4">
+      {STEPS.map((step, index) => {
+        const isCompleted = index < currentIndex;
+        const isCurrent = index === currentIndex;
+
+        return (
+          <div key={step.key} className="flex items-center gap-x-2">
+            {/* Step Indicator */}
+            <div
+              className={`flex h-8 w-8 items-center justify-center rounded-full text-sm font-medium ${
+                isCompleted
+                  ? "bg-primary text-primary-foreground"
+                  : isCurrent
+                    ? "bg-primary text-primary-foreground"
+                    : "bg-muted text-muted-foreground"
+              }`}
+            >
+              {isCompleted ? <Check className="h-4 w-4" /> : index + 1}
+            </div>
+
+            {/* Step Label */}
+            <span
+              className={`text-sm ${
+                isCurrent ? "font-medium text-foreground" : "text-muted-foreground"
+              }`}
+            >
+              {step.label}
+            </span>
+
+            {/* Connector */}
+            {index < STEPS.length - 1 && (
+              <div
+                className={`h-0.5 w-8 ${
+                  index < currentIndex ? "bg-primary" : "bg-muted"
+                }`}
+              />
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/features/billing/stripe-subscription/components/wizards/WizardStepPaymentMethod.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+import { PaymentMethodForm } from "../../../stripe-customer/components/forms/PaymentMethodForm";
+
+type WizardStepPaymentMethodProps = {
+  onBack: () => void;
+  onSuccess: () => void;
+  isProcessing: boolean;
+};
+
+export function WizardStepPaymentMethod({
+  onBack,
+  onSuccess,
+  isProcessing,
+}: WizardStepPaymentMethodProps) {
+  return (
+    <div className="space-y-6">
+      <div className="text-center">
+        <h3 className="font-semibold text-lg">Add Payment Method</h3>
+        <p className="text-sm text-muted-foreground">
+          Enter your card details to complete your subscription
+        </p>
+      </div>
+
+      <PaymentMethodForm
+        onSuccess={onSuccess}
+        onCancel={onBack}
+        isLoading={isProcessing}
+      />
+    </div>
+  );
+}

package/src/features/billing/stripe-subscription/components/wizards/WizardStepPlanSelection.tsx

@@ -0,0 +1,103 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import { Button } from "../../../../../shadcnui";
+import { StripeProductInterface, StripeProductService } from "../../../stripe-product";
+import { StripePriceInterface } from "../../../stripe-price/data/stripe-price.interface";
+import { BillingInterval, IntervalToggle } from "../widgets/IntervalToggle";
+import { ProductPricingList } from "../widgets/ProductPricingList";
+
+type WizardStepPlanSelectionProps = {
+  selectedPrice: StripePriceInterface | null;
+  selectedInterval: BillingInterval;
+  currentPriceId?: string;
+  hideRecurringPrices: boolean;
+  onSelectPrice: (price: StripePriceInterface) => void;
+  onIntervalChange: (interval: BillingInterval) => void;
+  onNext: () => void;
+  isProcessing: boolean;
+};
+
+export function WizardStepPlanSelection({
+  selectedPrice,
+  selectedInterval,
+  currentPriceId,
+  hideRecurringPrices,
+  onSelectPrice,
+  onIntervalChange,
+  onNext,
+  isProcessing,
+}: WizardStepPlanSelectionProps) {
+  const [products, setProducts] = useState<StripeProductInterface[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const loadProducts = async () => {
+      try {
+        const fetchedProducts = await StripeProductService.listProducts({ active: true });
+        setProducts(fetchedProducts);
+      } catch (error) {
+        console.error("[WizardStepPlanSelection] Failed to load products:", error);
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    loadProducts();
+  }, []);
+
+  // Compute available intervals from products
+  const { hasMonthly, hasYearly } = useMemo(() => {
+    let hasMonthly = false;
+    let hasYearly = false;
+
+    for (const product of products) {
+      for (const price of product.stripePrices || []) {
+        if (price.priceType === "recurring" && price.recurring?.interval === "month") {
+          hasMonthly = true;
+        }
+        if (price.priceType === "recurring" && price.recurring?.interval === "year") {
+          hasYearly = true;
+        }
+      }
+    }
+
+    return { hasMonthly, hasYearly };
+  }, [products]);
+
+  const handleSelectPrice = (price: StripePriceInterface) => {
+    onSelectPrice(price);
+  };
+
+  return (
+    <div className="space-y-6">
+      {/* Interval Toggle */}
+      <div className="flex justify-center">
+        <IntervalToggle
+          value={selectedInterval}
+          onChange={onIntervalChange}
+          hasMonthly={hasMonthly}
+          hasYearly={hasYearly}
+        />
+      </div>
+
+      {/* Product Pricing List */}
+      <ProductPricingList
+        products={products}
+        selectedInterval={selectedInterval}
+        currentPriceId={currentPriceId}
+        selectedPriceId={selectedPrice?.id}
+        loading={loading}
+        hideRecurringPrices={hideRecurringPrices}
+        onSelectPrice={handleSelectPrice}
+      />
+
+      {/* Action Buttons */}
+      <div className="flex justify-end pt-4 border-t">
+        <Button onClick={onNext} disabled={!selectedPrice || isProcessing}>
+          {isProcessing ? "Loading..." : "Next: Review"}
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/features/billing/stripe-subscription/components/wizards/WizardStepReview.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+import { AlertCircle } from "lucide-react";
+import { Alert, AlertDescription, Button } from "../../../../../shadcnui";
+import { formatCurrency } from "../../../components/utils/currency";
+import { StripePriceInterface } from "../../../stripe-price/data/stripe-price.interface";
+import { ProrationPreviewInterface } from "../../../stripe-invoice/data/stripe-invoice.interface";
+import { StripeSubscriptionInterface } from "../../data";
+
+type WizardStepReviewProps = {
+  selectedPrice: StripePriceInterface | null;
+  subscription?: StripeSubscriptionInterface;
+  prorationPreview: ProrationPreviewInterface | null;
+  hasPaymentMethod: boolean;
+  error: string | null;
+  isProcessing: boolean;
+  onBack: () => void;
+  onAddPaymentMethod: () => void;
+  onConfirm: () => void;
+};
+
+export function WizardStepReview({
+  selectedPrice,
+  subscription,
+  prorationPreview,
+  hasPaymentMethod,
+  error,
+  isProcessing,
+  onBack,
+  onAddPaymentMethod,
+  onConfirm,
+}: WizardStepReviewProps) {
+  if (!selectedPrice) {
+    return (
+      <div className="text-center py-8 text-muted-foreground">
+        No plan selected. Please go back and select a plan.
+      </div>
+    );
+  }
+
+  const isChangingPlan = subscription && subscription.price?.id !== selectedPrice.id;
+
+  const formatInterval = (price: StripePriceInterface) => {
+    if (price.priceType === "one_time") return "one-time";
+    const interval = price.recurring?.interval || "month";
+    return interval === "year" ? "yearly" : "monthly";
+  };
+
+  return (
+    <div className="space-y-6">
+      {/* Selected Plan Summary */}
+      <div className="bg-muted/50 rounded-lg p-4 space-y-3">
+        <h3 className="font-semibold text-lg">Selected Plan</h3>
+        <div className="flex justify-between items-center">
+          <div>
+            <p className="font-medium">{selectedPrice.product?.name}</p>
+            {selectedPrice.nickname && (
+              <p className="text-sm text-muted-foreground">{selectedPrice.nickname}</p>
+            )}
+          </div>
+          <div className="text-right">
+            <p className="font-semibold text-lg">
+              {formatCurrency(selectedPrice.unitAmount || 0, selectedPrice.currency)}
+            </p>
+            <p className="text-sm text-muted-foreground">{formatInterval(selectedPrice)}</p>
+          </div>
+        </div>
+      </div>
+
+      {/* Proration Preview (for plan changes) */}
+      {isChangingPlan && prorationPreview && (
+        <div className="bg-blue-50 border border-blue-200 rounded-lg p-4 space-y-2">
+          <h4 className="font-medium text-blue-800">Proration Summary</h4>
+          <p className="text-sm text-blue-700">
+            Your next charge will be adjusted to account for the plan change.
+          </p>
+          <div className="flex justify-between text-sm">
+            <span className="text-blue-600">Amount due now:</span>
+            <span className="font-medium text-blue-800">
+              {formatCurrency(prorationPreview.amountDue, prorationPreview.currency)}
+            </span>
+          </div>
+        </div>
+      )}
+
+      {/* Payment Method Status */}
+      <div className="border rounded-lg p-4">
+        <div className="flex justify-between items-center">
+          <div>
+            <h4 className="font-medium">Payment Method</h4>
+            <p className="text-sm text-muted-foreground">
+              {hasPaymentMethod
+                ? "A payment method is on file"
+                : "No payment method on file"}
+            </p>
+          </div>
+          {!hasPaymentMethod && (
+            <Button variant="outline" onClick={onAddPaymentMethod}>
+              Add Payment Method
+            </Button>
+          )}
+        </div>
+      </div>
+
+      {/* Error Display */}
+      {error && (
+        <Alert variant="destructive">
+          <AlertCircle className="h-4 w-4" />
+          <AlertDescription>{error}</AlertDescription>
+        </Alert>
+      )}
+
+      {/* Action Buttons */}
+      <div className="flex justify-between pt-4 border-t">
+        <Button variant="outline" onClick={onBack} disabled={isProcessing}>
+          Back
+        </Button>
+        <Button
+          onClick={hasPaymentMethod ? onConfirm : onAddPaymentMethod}
+          disabled={isProcessing}
+        >
+          {isProcessing
+            ? "Processing..."
+            : hasPaymentMethod
+              ? isChangingPlan
+                ? "Confirm Plan Change"
+                : "Subscribe Now"
+              : "Add Payment Method"}
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/features/billing/stripe-subscription/components/wizards/index.ts

@@ -0,0 +1,6 @@
+export { SubscriptionWizard } from "./SubscriptionWizard";
+export type { SubscriptionWizardProps } from "./SubscriptionWizard";
+export { WizardProgressIndicator } from "./WizardProgressIndicator";
+export { WizardStepPlanSelection } from "./WizardStepPlanSelection";
+export { WizardStepReview } from "./WizardStepReview";
+export { WizardStepPaymentMethod } from "./WizardStepPaymentMethod";

package/src/features/billing/stripe-subscription/hooks/useSubscriptionWizard.ts

@@ -0,0 +1,217 @@
+"use client";
+
+import { useCallback, useMemo, useReducer, useRef } from "react";
+import { StripeSubscriptionInterface, StripeSubscriptionService } from "../data";
+import { StripePriceInterface } from "../../stripe-price/data/stripe-price.interface";
+import { BillingInterval } from "../components/widgets/IntervalToggle";
+import { StripeCustomerService } from "../../stripe-customer/data/stripe-customer.service";
+import { ProrationPreviewInterface } from "../../stripe-invoice/data/stripe-invoice.interface";
+
+export type WizardStep = "plan-selection" | "review" | "payment-method";
+
+export type WizardState = {
+  step: WizardStep;
+  selectedPrice: StripePriceInterface | null;
+  selectedInterval: BillingInterval;
+  hasPaymentMethod: boolean;
+  isProcessing: boolean;
+  error: string | null;
+  prorationPreview: ProrationPreviewInterface | null;
+};
+
+type WizardAction =
+  | { type: "SET_STEP"; step: WizardStep }
+  | { type: "SELECT_PRICE"; price: StripePriceInterface }
+  | { type: "SET_INTERVAL"; interval: BillingInterval }
+  | { type: "SET_HAS_PAYMENT_METHOD"; hasMethod: boolean }
+  | { type: "SET_PROCESSING"; isProcessing: boolean }
+  | { type: "SET_ERROR"; error: string | null }
+  | { type: "SET_PRORATION_PREVIEW"; preview: ProrationPreviewInterface | null }
+  | { type: "RESET" };
+
+const initialState: WizardState = {
+  step: "plan-selection",
+  selectedPrice: null,
+  selectedInterval: "month",
+  hasPaymentMethod: false,
+  isProcessing: false,
+  error: null,
+  prorationPreview: null,
+};
+
+function wizardReducer(state: WizardState, action: WizardAction): WizardState {
+  switch (action.type) {
+    case "SET_STEP":
+      return { ...state, step: action.step, error: null };
+    case "SELECT_PRICE":
+      return { ...state, selectedPrice: action.price };
+    case "SET_INTERVAL":
+      return { ...state, selectedInterval: action.interval };
+    case "SET_HAS_PAYMENT_METHOD":
+      return { ...state, hasPaymentMethod: action.hasMethod };
+    case "SET_PROCESSING":
+      return { ...state, isProcessing: action.isProcessing };
+    case "SET_ERROR":
+      return { ...state, error: action.error };
+    case "SET_PRORATION_PREVIEW":
+      return { ...state, prorationPreview: action.preview };
+    case "RESET":
+      return initialState;
+    default:
+      return state;
+  }
+}
+
+export type UseSubscriptionWizardOptions = {
+  subscription?: StripeSubscriptionInterface;
+  onSuccess: () => void;
+  onClose: () => void;
+};
+
+export function useSubscriptionWizard({ subscription, onSuccess, onClose }: UseSubscriptionWizardOptions) {
+  const [state, dispatch] = useReducer(wizardReducer, {
+    ...initialState,
+    selectedPrice: subscription?.price || null,
+  });
+
+  // Use refs for callbacks to avoid dependency changes
+  const onSuccessRef = useRef(onSuccess);
+  const onCloseRef = useRef(onClose);
+  onSuccessRef.current = onSuccess;
+  onCloseRef.current = onClose;
+
+  const checkPaymentMethod = useCallback(async () => {
+    try {
+      const methods = await StripeCustomerService.listPaymentMethods();
+      dispatch({ type: "SET_HAS_PAYMENT_METHOD", hasMethod: methods.length > 0 });
+    } catch (error) {
+      console.error("[useSubscriptionWizard] Failed to check payment methods:", error);
+      dispatch({ type: "SET_HAS_PAYMENT_METHOD", hasMethod: false });
+    }
+  }, []);
+
+  const selectPrice = useCallback((price: StripePriceInterface) => {
+    dispatch({ type: "SELECT_PRICE", price });
+  }, []);
+
+  const setInterval = useCallback((interval: BillingInterval) => {
+    dispatch({ type: "SET_INTERVAL", interval });
+  }, []);
+
+  const goToStep = useCallback((step: WizardStep) => {
+    dispatch({ type: "SET_STEP", step });
+  }, []);
+
+  const goToReview = useCallback(async () => {
+    if (!state.selectedPrice) return;
+
+    dispatch({ type: "SET_PROCESSING", isProcessing: true });
+
+    try {
+      // Check payment method first
+      await checkPaymentMethod();
+
+      // If editing subscription, get proration preview
+      if (subscription && state.selectedPrice.id !== subscription.price?.id) {
+        const preview = await StripeSubscriptionService.getProrationPreview({
+          subscriptionId: subscription.id,
+          newPriceId: state.selectedPrice.id,
+        });
+        dispatch({ type: "SET_PRORATION_PREVIEW", preview });
+      }
+
+      dispatch({ type: "SET_STEP", step: "review" });
+    } catch (error: any) {
+      console.error("[useSubscriptionWizard] Error preparing review:", error);
+      dispatch({ type: "SET_ERROR", error: error?.message || "Failed to prepare review" });
+    } finally {
+      dispatch({ type: "SET_PROCESSING", isProcessing: false });
+    }
+  }, [state.selectedPrice, subscription, checkPaymentMethod]);
+
+  const confirmSubscription = useCallback(async () => {
+    if (!state.selectedPrice) return;
+
+    dispatch({ type: "SET_PROCESSING", isProcessing: true });
+    dispatch({ type: "SET_ERROR", error: null });
+
+    try {
+      if (subscription) {
+        // Change existing subscription
+        await StripeSubscriptionService.changePlan({
+          id: subscription.id,
+          newPriceId: state.selectedPrice.id,
+        });
+      } else {
+        // Create new subscription
+        await StripeSubscriptionService.createSubscription({
+          id: crypto.randomUUID(),
+          priceId: state.selectedPrice.id,
+        });
+      }
+
+      onSuccessRef.current();
+      onCloseRef.current();
+    } catch (error: any) {
+      console.error("[useSubscriptionWizard] Subscription error:", error);
+
+      // Handle 409 Conflict - duplicate recurring subscription
+      if (error?.status === 409 || error?.response?.status === 409) {
+        dispatch({
+          type: "SET_ERROR",
+          error: "You already have an active subscription. Please change your existing plan instead.",
+        });
+        return;
+      }
+
+      // Handle 402 - payment method required
+      if (error?.status === 402 || error?.response?.status === 402) {
+        dispatch({ type: "SET_HAS_PAYMENT_METHOD", hasMethod: false });
+        dispatch({ type: "SET_STEP", step: "payment-method" });
+        return;
+      }
+
+      dispatch({ type: "SET_ERROR", error: error?.message || "Failed to process subscription" });
+    } finally {
+      dispatch({ type: "SET_PROCESSING", isProcessing: false });
+    }
+  }, [state.selectedPrice, subscription]);
+
+  const handlePaymentMethodSuccess = useCallback(async () => {
+    dispatch({ type: "SET_HAS_PAYMENT_METHOD", hasMethod: true });
+    // Go back to review to confirm subscription
+    dispatch({ type: "SET_STEP", step: "review" });
+  }, []);
+
+  const reset = useCallback(() => {
+    dispatch({ type: "RESET" });
+  }, []);
+
+  const actions = useMemo(
+    () => ({
+      selectPrice,
+      setInterval,
+      goToStep,
+      goToReview,
+      confirmSubscription,
+      handlePaymentMethodSuccess,
+      checkPaymentMethod,
+      reset,
+    }),
+    [
+      selectPrice,
+      setInterval,
+      goToStep,
+      goToReview,
+      confirmSubscription,
+      handlePaymentMethodSuccess,
+      checkPaymentMethod,
+      reset,
+    ],
+  );
+
+  return {
+    state,
+    actions,
+  };
+}

package/src/features/billing/stripe-subscription/index.ts

@@ -1,5 +1,6 @@
 export * from "./data";
 export * from "./stripe-subscription.module";
 
-// Note: hooks are not exported from barrel to avoid bundling client code into server components.
-// Import hooks directly: import { useConfirmSubscriptionPayment } from "./hooks";
+// Note: Client components (wizards, hooks) are not exported here to avoid bundling
+// client code into server contexts. Import them from the /billing entry point:
+// import { SubscriptionWizard } from "@carlonicora/nextjs-jsonapi/billing";