@carlonicora/nextjs-jsonapi 5.5.0 → 5.7.0

package/src/features/billing/stripe-coupon/stripe-coupon-code.module.ts

@@ -0,0 +1,15 @@
+import { ModuleFactory } from "../../../permissions";
+import { StripeCouponCode } from "./data/stripe-coupon-code";
+
+/** The code endpoint's segment that returns the automatic code for a price. */
+export const STRIPE_COUPON_CODE_AUTOMATIC_SEGMENT = "automatic";
+
+export const StripeCouponCodeModule = (factory: ModuleFactory) =>
+  factory({
+    name: "stripe-coupon-codes",
+    // Codes are listed on the products page (Codes tab), same value as
+    // StripeProductModule. A code has no page of its own.
+    pageUrl: "/administration/products",
+    model: StripeCouponCode,
+    moduleId: "85feb4c7-ff22-416a-b856-8dafcf28ff26",
+  });

package/src/features/billing/stripe-coupon/stripe-coupon-offer.module.ts

@@ -0,0 +1,10 @@
+import { ModuleFactory } from "../../../permissions";
+import { StripeCouponOffer } from "./data/stripe-coupon-offer";
+
+export const StripeCouponOfferModule = (factory: ModuleFactory) =>
+  factory({
+    name: "stripe-coupon-offers",
+    pageUrl: "/pricing",
+    model: StripeCouponOffer,
+    moduleId: "6859d6cc-b94c-4cf7-8a02-b71ad59d75d2",
+  });

package/src/features/billing/stripe-coupon/stripe-coupon.module.ts

@@ -0,0 +1,25 @@
+import { TicketPercentIcon } from "lucide-react";
+import { ModuleFactory } from "../../../permissions";
+import { StripeCoupon } from "./data/stripe-coupon";
+
+/** The coupon endpoint's non-resource segment that re-reads its counts from Stripe. */
+export const STRIPE_COUPON_REFRESH_SEGMENT = "refresh";
+
+/**
+ * Route of a coupon's own page (`/administration/coupons/<id>`). It is not the
+ * module's pageUrl: there is no coupons list route, the list is the Codes tab of
+ * the products page. Links to one coupon build on this instead.
+ */
+export const STRIPE_COUPON_DETAIL_PAGE_URL = "/administration/coupons";
+
+export const StripeCouponModule = (factory: ModuleFactory) =>
+  factory({
+    name: "stripe-coupons",
+    // The coupons list lives on the products page (Codes tab), so the module
+    // points there, same value as StripeProductModule. Links to a single coupon
+    // use STRIPE_COUPON_DETAIL_PAGE_URL.
+    pageUrl: "/administration/products",
+    model: StripeCoupon,
+    moduleId: "50bdb0d2-539c-4358-b609-d6beab248bdb",
+    icon: TicketPercentIcon,
+  });

package/src/features/billing/stripe-coupon/utils/__tests__/coupon-places.spec.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { couponPlacesLeft, couponPlacesTotal } from "../coupon-places";
+
+describe("coupon places", () => {
+  it("returns null when neither limit is set", () =>
+    expect(couponPlacesLeft({ timesRedeemed: 3 }, { timesRedeemed: 3 })).toBeNull());
+  it("uses the coupon limit alone", () =>
+    expect(couponPlacesLeft({ timesRedeemed: 0 }, { maxRedemptions: 50, timesRedeemed: 13 })).toBe(37));
+  it("takes the smaller of coupon and code", () =>
+    expect(couponPlacesLeft({ maxRedemptions: 10, timesRedeemed: 8 }, { maxRedemptions: 50, timesRedeemed: 13 })).toBe(
+      2,
+    ));
+  it("never goes below zero", () =>
+    expect(couponPlacesLeft({ timesRedeemed: 0 }, { maxRedemptions: 50, timesRedeemed: 51 })).toBe(0));
+  it("placesTotal is the smaller set limit", () =>
+    expect(couponPlacesTotal({ maxRedemptions: 10, timesRedeemed: 0 }, { maxRedemptions: 50, timesRedeemed: 0 })).toBe(
+      10,
+    ));
+});

package/src/features/billing/stripe-coupon/utils/__tests__/to-promotion-code-result.spec.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { StripeCouponCodeInterface } from "../../data/stripe-coupon-code.interface";
+import { StripeCouponInterface } from "../../data/stripe-coupon.interface";
+import { toPromotionCodeResult } from "../to-promotion-code-result";
+
+const codeWith = (coupon: Partial<StripeCouponInterface>): StripeCouponCodeInterface =>
+  ({ stripePromotionCodeId: "promo_1", code: "FOUNDER", coupon }) as unknown as StripeCouponCodeInterface;
+
+describe("toPromotionCodeResult", () => {
+  it("maps a percentage coupon", () => {
+    expect(
+      toPromotionCodeResult(codeWith({ discountType: "percent_off", percentOff: 20, duration: "forever" })),
+    ).toEqual({
+      valid: true,
+      automatic: true,
+      promotionCodeId: "promo_1",
+      code: "FOUNDER",
+      discountType: "percent_off",
+      discountValue: 20,
+      duration: "forever",
+    });
+  });
+
+  it("maps a fixed-amount coupon to amountOff and its currency", () => {
+    const result = toPromotionCodeResult(
+      codeWith({
+        discountType: "amount_off",
+        amountOff: 500,
+        currency: "eur",
+        duration: "repeating",
+        durationInMonths: 3,
+      }),
+    );
+    expect(result.discountType).toBe("amount_off");
+    expect(result.discountValue).toBe(500);
+    expect(result.currency).toBe("eur");
+    expect(result.duration).toBe("repeating");
+    expect(result.durationInMonths).toBe(3);
+    expect(result.automatic).toBe(true);
+  });
+});

package/src/features/billing/stripe-coupon/utils/coupon-places.ts

@@ -0,0 +1,23 @@
+/**
+ * Places left on a code: the smaller of (coupon limit - coupon redeemed) and
+ * (code limit - code redeemed), counting only the limits that are set, never
+ * below zero. `null` = unlimited. Same rule as the backend `placesLeft`.
+ */
+type Redeemable = { maxRedemptions?: number; timesRedeemed: number };
+
+export function couponPlacesLeft(code: Redeemable, coupon: Redeemable): number | null {
+  const remaining = [code, coupon]
+    .filter((item) => typeof item.maxRedemptions === "number")
+    .map((item) => Math.max(0, (item.maxRedemptions as number) - (item.timesRedeemed ?? 0)));
+
+  return remaining.length === 0 ? null : Math.min(...remaining);
+}
+
+/** The smaller of the set limits, or `null` when neither is set. */
+export function couponPlacesTotal(code: Redeemable, coupon: Redeemable): number | null {
+  const limits = [code.maxRedemptions, coupon.maxRedemptions].filter(
+    (limit): limit is number => typeof limit === "number",
+  );
+
+  return limits.length === 0 ? null : Math.min(...limits);
+}

package/src/features/billing/stripe-coupon/utils/format-coupon-discount.ts

@@ -0,0 +1,36 @@
+import { formatCurrency } from "../../components/utils/currency";
+import { BillingFormatOptions, BillingTranslator } from "../../components/utils/format-options";
+import { StripeCouponDiscountType, StripeCouponDurationType } from "../data/stripe-coupon.interface";
+
+export type CouponDiscountShape = {
+  discountType: StripeCouponDiscountType;
+  percentOff?: number;
+  amountOff?: number; // minor units
+  currency?: string;
+  duration: StripeCouponDurationType;
+  durationInMonths?: number;
+};
+
+/** "20% off forever", "€5.00 off for 3 months", "€5.00 off once". */
+export function formatCouponDiscount(
+  coupon: CouponDiscountShape,
+  t: BillingTranslator,
+  fmt: BillingFormatOptions = {},
+): string {
+  const amount =
+    coupon.discountType === "percent_off"
+      ? t("billing.admin.coupons.discount.percent", { value: String(coupon.percentOff ?? 0) })
+      : t("billing.admin.coupons.discount.amount", {
+          amount: formatCurrency(coupon.amountOff, coupon.currency ?? "eur", fmt),
+        });
+
+  // Literal keys (no template) so the message validator sees every one in use.
+  const duration =
+    coupon.duration === "repeating"
+      ? t("billing.admin.coupons.discount.repeating", { months: String(coupon.durationInMonths ?? 0) })
+      : coupon.duration === "once"
+        ? t("billing.admin.coupons.discount.once")
+        : t("billing.admin.coupons.discount.forever");
+
+  return `${amount} ${duration}`;
+}

package/src/features/billing/stripe-coupon/utils/index.ts

@@ -0,0 +1,3 @@
+export * from "./coupon-places";
+export * from "./format-coupon-discount";
+export * from "./to-promotion-code-result";

package/src/features/billing/stripe-coupon/utils/to-promotion-code-result.ts

@@ -0,0 +1,23 @@
+import { PromotionCodeValidationResult } from "../../stripe-promotion-code/data/stripe-promotion-code.interface";
+import { StripeCouponCodeInterface } from "../data/stripe-coupon-code.interface";
+
+/**
+ * The automatic code as the wizard's promotion-code state, exactly as if the
+ * GM had typed and validated it.
+ */
+export function toPromotionCodeResult(code: StripeCouponCodeInterface): PromotionCodeValidationResult {
+  const coupon = code.coupon;
+  const discountType = coupon?.discountType;
+
+  return {
+    valid: true,
+    automatic: true,
+    promotionCodeId: code.stripePromotionCodeId,
+    code: code.code,
+    discountType,
+    discountValue: discountType === "amount_off" ? coupon?.amountOff : coupon?.percentOff,
+    currency: discountType === "amount_off" ? coupon?.currency : undefined,
+    duration: coupon?.duration,
+    durationInMonths: coupon?.durationInMonths,
+  };
+}

package/src/features/billing/stripe-customer/components/forms/PaymentMethodForm.tsx

@@ -10,9 +10,19 @@ type PaymentMethodFormProps = {
   onSuccess: () => void;
   onCancel: () => void;
   isLoading?: boolean;
+  /**
+   * Always make the new card the customer's default and hide the checkbox. The
+   * subscription wizard needs this: the next attempt must charge the card just added.
+   */
+  alwaysSetDefault?: boolean;
 };
 
-export function PaymentMethodForm({ onSuccess, onCancel, isLoading = false }: PaymentMethodFormProps) {
+export function PaymentMethodForm({
+  onSuccess,
+  onCancel,
+  isLoading = false,
+  alwaysSetDefault = false,
+}: PaymentMethodFormProps) {
   const t = useTranslations();
   const stripe = useStripe();
   const elements = useElements();
@@ -75,7 +85,7 @@ export function PaymentMethodForm({ onSuccess, onCancel, isLoading = false }: Pa
       }
 
       // Set as default if checkbox is checked
-      if (setAsDefault && confirmedSetupIntent?.payment_method) {
+      if ((alwaysSetDefault || setAsDefault) && confirmedSetupIntent?.payment_method) {
         await StripeCustomerService.setDefaultPaymentMethod({
           paymentMethodId:
             typeof confirmedSetupIntent.payment_method === "string"
@@ -132,12 +142,18 @@ export function PaymentMethodForm({ onSuccess, onCancel, isLoading = false }: Pa
       </div>
 
       {/* Set as Default Checkbox */}
-      <div className="flex items-center gap-x-2">
-        <Checkbox id="setAsDefault" checked={setAsDefault} onCheckedChange={(checked) => setSetAsDefault(!!checked)} />
-        <Label htmlFor="setAsDefault" className="cursor-pointer font-normal">
-          {t("billing.ui.payment_form.set_default")}
-        </Label>
-      </div>
+      {!alwaysSetDefault && (
+        <div className="flex items-center gap-x-2">
+          <Checkbox
+            id="setAsDefault"
+            checked={setAsDefault}
+            onCheckedChange={(checked) => setSetAsDefault(!!checked)}
+          />
+          <Label htmlFor="setAsDefault" className="cursor-pointer font-normal">
+            {t("billing.ui.payment_form.set_default")}
+          </Label>
+        </div>
+      )}
 
       {/* Error Alert */}
       {error && (

package/src/features/billing/stripe-product/components/containers/ProductsListContainer.tsx

@@ -1,27 +1,42 @@
 "use client";
 
+import { useTranslations } from "next-intl";
 import { RoundPageContainer } from "../../../../../components";
 import { Modules } from "../../../../../core";
+import { CouponProvider } from "../../../contexts/CouponContext";
 import { ProductProvider } from "../../../contexts/ProductContext";
+import { CouponsList } from "../../../stripe-coupon/components/lists/CouponsList";
 import { ProductsList } from "../lists/ProductsList";
 
 /**
- * Page container for the administrative product list.
+ * Page container for the administrative products page: two tabs, Products and
+ * Codes, with `sectionKey`s so the URL keeps the tab (`?section=codes`).
  *
  * Client component by necessity: `module={Modules.StripeProduct}` is a registry
  * entry carrying an icon component and methods, which a Server Component cannot
  * pass across the boundary. Routes mount this container instead — the same
  * shape as every other list page.
  *
- * No `forceHeader`: ContentListTable draws its own header row with the title
- * and the create action, exactly as the company and user list pages do.
+ * No `fullWidth`, on the page or the lists: the page keeps its title bar and
+ * each ContentListTable keeps its own bordered card in the tab (see ProductContainer). CouponProvider
+ * is nested with `publishChrome={false}`: SharedProvider REPLACES its value for
+ * the subtree (SharedContext.tsx:35-37), so a nested provider publishing chrome
+ * would blank the products page's own title.
  */
 export function ProductsListContainer() {
+  const t = useTranslations();
+
   return (
     <ProductProvider>
-      <RoundPageContainer module={Modules.StripeProduct} fullWidth>
-        <ProductsList fullWidth />
-      </RoundPageContainer>
+      <CouponProvider publishChrome={false}>
+        <RoundPageContainer
+          module={Modules.StripeProduct}
+          tabs={[
+            { sectionKey: "products", label: t("billing.admin.products.tabs.products"), content: <ProductsList /> },
+            { sectionKey: "codes", label: t("billing.admin.products.tabs.codes"), content: <CouponsList /> },
+          ]}
+        />
+      </CouponProvider>
     </ProductProvider>
   );
 }

package/src/features/billing/stripe-promotion-code/components/PromoCodeInput.tsx

@@ -29,6 +29,25 @@ export function PromoCodeInput({
   const locale = useI18nLocale();
   const [code, setCode] = useState("");
 
+  // Clear the typed text whenever a code becomes applied (typed or automatic):
+  // the box then reads empty after the applied code is removed, instead of
+  // still holding the removed code. Adjusting state during render on a prop
+  // change (React's "storing information from previous renders" pattern) —
+  // a failed validation keeps the text so the user can fix a typo.
+  const appliedKey = appliedCode?.valid
+    ? `${appliedCode.automatic ? "auto" : "typed"}:${appliedCode.code ?? ""}`
+    : null;
+  const [previousAppliedKey, setPreviousAppliedKey] = useState(appliedKey);
+  if (appliedKey !== previousAppliedKey) {
+    setPreviousAppliedKey(appliedKey);
+    if (appliedKey !== null) setCode("");
+  }
+
+  const handleRemove = () => {
+    setCode("");
+    onRemove();
+  };
+
   const handleApply = () => {
     if (code.trim()) {
       onApply(code.trim().toUpperCase());
@@ -67,6 +86,45 @@ export function PromoCodeInput({
     }
   };
 
+  const codeInput = (
+    <div className="space-y-2">
+      <div className="flex gap-2">
+        <Input
+          placeholder={t("billing.ui.promo_code.placeholder")}
+          value={code}
+          onChange={(e) => setCode(e.target.value.toUpperCase())}
+          onKeyDown={handleKeyDown}
+          disabled={disabled || isValidating}
+          className="flex-1"
+        />
+        <Button variant="outline" onClick={handleApply} disabled={disabled || isValidating || !code.trim()}>
+          {isValidating ? <Loader2 className="h-4 w-4 animate-spin" /> : t("billing.ui.promo_code.apply")}
+        </Button>
+      </div>
+      {error && <p className="text-destructive text-xs/relaxed">{error}</p>}
+    </div>
+  );
+
+  // Show the automatic code as applied, with the option to type a different one
+  if (appliedCode?.valid && appliedCode.automatic) {
+    return (
+      <div className="space-y-3">
+        <div className="space-y-2">
+          <div className="bg-success/15 border-success/30 flex items-center gap-2 rounded-lg border p-3">
+            <Check className="text-success h-4 w-4" />
+            <span className="text-success font-medium">{t("billing.ui.promo_code.automatic_label")}</span>
+            <span className="text-success text-sm">{formatDiscount(appliedCode)}</span>
+          </div>
+          <p className="text-success text-sm">{formatDuration(appliedCode)}</p>
+        </div>
+        <div className="space-y-2">
+          <p className="text-muted-foreground text-xs/relaxed">{t("billing.ui.promo_code.use_different")}</p>
+          {codeInput}
+        </div>
+      </div>
+    );
+  }
+
   // Show applied code state
   if (appliedCode?.valid) {
     return (
@@ -80,7 +138,7 @@ export function PromoCodeInput({
           <Button
             variant="ghost"
             size="sm"
-            onClick={onRemove}
+            onClick={handleRemove}
             disabled={disabled}
             className="text-success hover:bg-success/25 hover:text-success"
           >
@@ -92,22 +150,5 @@ export function PromoCodeInput({
     );
   }
 
-  return (
-    <div className="space-y-2">
-      <div className="flex gap-2">
-        <Input
-          placeholder={t("billing.ui.promo_code.placeholder")}
-          value={code}
-          onChange={(e) => setCode(e.target.value.toUpperCase())}
-          onKeyDown={handleKeyDown}
-          disabled={disabled || isValidating}
-          className="flex-1"
-        />
-        <Button variant="outline" onClick={handleApply} disabled={disabled || isValidating || !code.trim()}>
-          {isValidating ? <Loader2 className="h-4 w-4 animate-spin" /> : t("billing.ui.promo_code.apply")}
-        </Button>
-      </div>
-      {error && <p className="text-destructive text-xs/relaxed">{error}</p>}
-    </div>
-  );
+  return codeInput;
 }

package/src/features/billing/stripe-promotion-code/data/stripe-promotion-code.interface.ts

@@ -11,4 +11,6 @@ export interface PromotionCodeValidationResult {
   duration?: "forever" | "once" | "repeating";
   durationInMonths?: number;
   errorMessage?: string;
+  /** True when the server applies this code by itself (no code typed by the GM). */
+  automatic?: boolean;
 }

package/src/features/billing/stripe-subscription/components/containers/SubscriptionsContainer.tsx

@@ -11,14 +11,33 @@ import { SubscriptionsList } from "../lists";
 type SubscriptionsContainerProps = {
   onOpenWizard?: (subscription?: StripeSubscriptionInterface) => void;
   hasActiveRecurringSubscription?: boolean;
+  /**
+   * The list a parent already holds (the billing dashboard). When given, the container
+   * shows it instead of loading its own, and a change asks the parent to refresh through
+   * `onSubscriptionsChange`, so the dialog and the cards behind it never disagree.
+   */
+  subscriptions?: StripeSubscriptionInterface[];
+  onSubscriptionsChange?: () => void;
 };
 
-export function SubscriptionsContainer({ onOpenWizard, hasActiveRecurringSubscription }: SubscriptionsContainerProps) {
+export function SubscriptionsContainer({
+  onOpenWizard,
+  hasActiveRecurringSubscription,
+  subscriptions: parentSubscriptions,
+  onSubscriptionsChange,
+}: SubscriptionsContainerProps) {
   const t = useTranslations();
-  const [subscriptions, setSubscriptions] = useState<StripeSubscriptionInterface[]>([]);
-  const [loading, setLoading] = useState<boolean>(true);
+  const isControlled = parentSubscriptions !== undefined;
+  const [ownSubscriptions, setSubscriptions] = useState<StripeSubscriptionInterface[]>([]);
+  const [ownLoading, setLoading] = useState<boolean>(!isControlled);
+  const subscriptions = parentSubscriptions ?? ownSubscriptions;
+  const loading = isControlled ? false : ownLoading;
 
   const loadSubscriptions = useCallback(async () => {
+    if (isControlled) {
+      onSubscriptionsChange?.();
+      return;
+    }
     setLoading(true);
     try {
       const fetchedSubscriptions = await StripeSubscriptionService.listSubscriptions();
@@ -28,10 +47,10 @@ export function SubscriptionsContainer({ onOpenWizard, hasActiveRecurringSubscri
     } finally {
       setLoading(false);
     }
-  }, []);
+  }, [isControlled, onSubscriptionsChange]);
 
   useEffect(() => {
-    loadSubscriptions();
+    if (!isControlled) loadSubscriptions();
   }, []);
 
   // Detect critical subscriptions

package/src/features/billing/stripe-subscription/components/lists/SubscriptionsList.tsx

@@ -3,7 +3,13 @@
 import { useTranslations } from "next-intl";
 import { useState } from "react";
 import { Button, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "../../../../../shadcnui";
-import { formatCurrency, formatDate, useBillingFormatOptions } from "../../../components/utils";
+import {
+  applyDiscount,
+  formatCurrency,
+  formatDate,
+  subscriptionDiscount,
+  useBillingFormatOptions,
+} from "../../../components/utils";
 import { StripePriceInterface } from "../../../stripe-price/data/stripe-price.interface";
 import { StripeSubscriptionInterface, SubscriptionStatus } from "../../data";
 import { SubscriptionDetails } from "../details/SubscriptionDetails";
@@ -71,6 +77,10 @@ export function SubscriptionsList({ subscriptions, onSubscriptionsChange, onChan
             {subscriptions.map((subscription) => {
               const price = subscription.price;
               const amount = price?.unitAmount ? formatCurrency(price.unitAmount, price.currency, fmt) : "0";
+              // What Stripe bills: the price after the discount the subscription carries.
+              const discountedAmount = price
+                ? applyDiscount(price.unitAmount, subscriptionDiscount(subscription))
+                : null;
               const period = `${formatDate(subscription.currentPeriodStart, fmt)} - ${formatDate(subscription.currentPeriodEnd, fmt)}`;
 
               return (
@@ -87,7 +97,16 @@ export function SubscriptionsList({ subscriptions, onSubscriptionsChange, onChan
                   </TableCell>
                   <TableCell className="font-medium">{formatPlanName(price, t)}</TableCell>
                   <TableCell className="text-muted-foreground text-sm">{period}</TableCell>
-                  <TableCell className="text-end font-medium">{amount}</TableCell>
+                  <TableCell className="text-end font-medium">
+                    {discountedAmount !== null && price ? (
+                      <>
+                        <span className="line-through text-muted-foreground me-2">{amount}</span>
+                        <span className="text-success">{formatCurrency(discountedAmount, price.currency, fmt)}</span>
+                      </>
+                    ) : (
+                      amount
+                    )}
+                  </TableCell>
                   <TableCell className="text-end">
                     {(subscription.status === SubscriptionStatus.ACTIVE ||
                       subscription.status === SubscriptionStatus.TRIALING) &&

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

@@ -72,7 +72,7 @@ export function SubscriptionWizard({
 
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
-      <DialogContent className="max-w-2xl">
+      <DialogContent className="max-w-2xl max-h-[90vh] overflow-y-auto">
         <DialogHeader>
           <DialogTitle>{dialogTitle}</DialogTitle>
           <DialogDescription>{dialogDescription}</DialogDescription>

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

@@ -19,7 +19,7 @@ export function WizardStepPaymentMethod({ onBack, onSuccess, isProcessing }: Wiz
         <p className="text-sm text-muted-foreground">{t("billing.ui.wizard.payment_description")}</p>
       </div>
 
-      <PaymentMethodForm onSuccess={onSuccess} onCancel={onBack} isLoading={isProcessing} />
+      <PaymentMethodForm onSuccess={onSuccess} onCancel={onBack} isLoading={isProcessing} alwaysSetDefault />
     </div>
   );
 }