@carlonicora/nextjs-jsonapi 5.5.0 → 5.7.0

package/messages/it.json

@@ -297,6 +297,118 @@
   },
   "billing": {
     "admin": {
+      "coupons": {
+        "all_products": "Tutti i prodotti",
+        "codes": {
+          "automatic": "Automatico",
+          "deactivate": {
+            "confirm": "Disattiva",
+            "description": "Nessuno potrà usare \"{code}\" finché non lo riattivi. Gli abbonamenti che lo hanno già mantengono lo sconto.",
+            "title": "Disattiva codice"
+          },
+          "empty": {
+            "description": "Aggiungi un codice che i clienti possono usare per avere lo sconto di questo coupon.",
+            "title": "Ancora nessun codice"
+          },
+          "entity": "codice",
+          "never": "Mai",
+          "reactivate": {
+            "confirm": "Riattiva",
+            "description": "\"{code}\" potrà essere usato di nuovo.",
+            "title": "Riattiva codice"
+          },
+          "status": {
+            "active": "Attivo",
+            "expired": "Scaduto",
+            "inactive": "Inattivo",
+            "used_up": "Esaurito"
+          },
+          "title": "Codici"
+        },
+        "discount": {
+          "amount": "{amount} di sconto",
+          "forever": "per sempre",
+          "once": "una volta",
+          "percent": "{value}% di sconto",
+          "repeating": "per {months} mesi"
+        },
+        "duration": {
+          "forever": "Per sempre",
+          "once": "Una volta",
+          "repeating": "Per un numero di mesi"
+        },
+        "empty": {
+          "description": "Crea un coupon per offrire uno sconto al pagamento.",
+          "title": "Ancora nessun coupon"
+        },
+        "entity": "coupon",
+        "errors": {
+          "amountOff": "Inserisci un importo maggiore di zero",
+          "durationInMonths": "Inserisci almeno un mese",
+          "minimumAmount": "Inserisci un importo maggiore di zero, o lascia vuoto",
+          "name": "Il nome del coupon è obbligatorio",
+          "percentOff": "Inserisci una percentuale tra 0,01 e 100"
+        },
+        "fields": {
+          "amountOff": "Importo dello sconto",
+          "automatic": "Applica automaticamente",
+          "code": "Codice",
+          "codeMaxRedemptions": "Limite di utilizzo per questo codice",
+          "codes": "Codici",
+          "currency": "Valuta",
+          "discount": "Sconto",
+          "discountType": "Tipo",
+          "duration": "Durata",
+          "durationInMonths": "Mesi",
+          "expiresAt": "Scadenza",
+          "firstTimeTransaction": "Solo nuovi clienti",
+          "first_time_warning": "Un GM che arriva da una prova conta come cliente esistente, quindi lascia disattivato per i codici pensati per i GM in prova.",
+          "maxRedemptions": "Limite di utilizzo totale",
+          "minimumAmount": "Importo minimo dell'ordine",
+          "name": "Nome",
+          "percentOff": "Percentuale di sconto",
+          "places": "Posti",
+          "products": "Applica a prodotti specifici",
+          "redeemBy": "Utilizzabile fino al",
+          "status": "Stato",
+          "stripeCouponId": "ID",
+          "stripeCustomerId": "Limita a un solo cliente",
+          "stripeId": "ID coupon Stripe"
+        },
+        "first_code": "Primo codice",
+        "fixed_notice": "Stripe non permette di cambiare sconto, durata o limiti di un coupon. Crea un nuovo coupon.",
+        "help": {
+          "automatic": "Si applica da solo quando un GM paga la prima volta. Solo un codice può averlo: attivarlo qui lo disattiva sul codice che lo aveva.",
+          "products": "Lascia vuoto per applicare il coupon a tutti i prodotti."
+        },
+        "placeholders": {
+          "amountOff": "5,00",
+          "code": "Lascia vuoto per farlo generare a Stripe",
+          "durationInMonths": "3",
+          "maxRedemptions": "Nessun limite",
+          "minimumAmount": "0,00",
+          "name": "es. GM fondatore",
+          "percentOff": "20",
+          "stripeCouponId": "Lascia vuoto per farlo generare a Stripe"
+        },
+        "places": {
+          "limited": "{used} / {limit}",
+          "no_limit": "Nessun limite",
+          "unlimited": "{used} / nessun limite"
+        },
+        "refresh": {
+          "title": "Aggiorna conteggi"
+        },
+        "status": {
+          "active": "Attivo",
+          "ended": "Terminato"
+        },
+        "title": "Coupon",
+        "type": {
+          "amount_off": "Importo fisso",
+          "percent_off": "Percentuale"
+        }
+      },
       "prices": {
         "actions": {
           "addFeature": "Aggiungi caratteristica",
@@ -430,7 +542,9 @@
           "archived": "Archiviato"
         },
         "tabs": {
-          "details": "Dettagli"
+          "codes": "Codici",
+          "details": "Dettagli",
+          "products": "Prodotti"
         },
         "title": "Prodotti"
       }
@@ -626,10 +740,12 @@
       },
       "promo_code": {
         "apply": "Applica",
+        "automatic_label": "Applicato automaticamente",
         "duration_forever": "Applicato a tutti i pagamenti",
         "duration_once": "Applicato solo al primo pagamento",
         "duration_repeating": "Applicato per {months} mesi",
-        "placeholder": "Inserisci il codice promozionale"
+        "placeholder": "Inserisci il codice promozionale",
+        "use_different": "Hai un altro codice?"
       },
       "proration": {
         "net_due_today": "Netto dovuto oggi",
@@ -698,8 +814,10 @@
         "change_title": "Cambia piano di abbonamento",
         "errors": {
           "already_subscribed": "Hai già un abbonamento attivo. Cambia invece il piano attuale.",
+          "discount_unavailable": "Questo sconto non è più disponibile. Non ti è stato addebitato nulla.",
           "invalid_promo_code": "Codice promozionale non valido",
           "payment_method_required": "Per passare dalla prova a un piano a pagamento serve un metodo di pagamento.",
+          "payment_not_confirmed": "Il pagamento non è stato completato. {reason} Non ti è stato addebitato nulla: riprova o aggiungi un'altra carta.",
           "prepare_review": "Impossibile preparare il riepilogo",
           "process_subscription": "Impossibile elaborare l'abbonamento",
           "validate_promo_code": "Impossibile verificare il codice promozionale"
@@ -708,6 +826,7 @@
         "payment_description": "Inserisci i dati della carta per completare l'abbonamento",
         "review": {
           "amount_off": "{amount} di sconto",
+          "card_on_file": "{brand} che termina con {last4}",
           "charge_now": "Importo da addebitare ora:",
           "confirm_change": "Conferma il cambio di piano",
           "due_now": "Importo dovuto ora:",
@@ -725,7 +844,10 @@
           "selected_plan": "Piano selezionato",
           "subscribe_now": "Abbonati ora",
           "trial_upgrade": "Passaggio dalla prova",
-          "trial_upgrade_description": "La tua prova terminerà subito e ti verrà addebitato il prezzo pieno."
+          "trial_upgrade_description": "La tua prova terminerà subito e ti verrà addebitato il prezzo pieno.",
+          "trial_upgrade_description_discounted": "La tua prova terminerà subito e ti verrà addebitato il prezzo scontato.",
+          "use_another_card": "Usa un'altra carta",
+          "discount_carries_over": "Il tuo sconto attuale resta valido anche sul nuovo piano."
         },
         "steps": {
           "payment": "Pagamento",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "5.5.0",
+  "version": "5.7.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",

package/scripts/validate-messages.mjs

@@ -28,6 +28,7 @@ export const APP_PROVIDED_KEYS = [
   /^features\.assistant\.starters\./, // example questions about the app's own domain
   /^features\.assistant\.empty_state\.subtitle$/, // says what the app's assistant knows about
   /^auth\.gdpr\.marketing_consent$/, // a consent must name who sends the news: the app
+  /^billing\.ui\.wizard\.errors\.discount_sold_out$/, // names who to contact: the app
   // The app's own entities (CommonDeleter / RecentPagesNavigator render
   // `entities.${type}` for any module). Only the library's own entities ship.
   /^entities\.(?!(?:assistants|companies|howtos|rbac|roles|users)(?:\.|$))/,

package/src/billing/index.ts

@@ -5,6 +5,7 @@ export * from "../features/billing/stripe-customer/components";
 export * from "../features/billing/stripe-invoice/components";
 export * from "../features/billing/stripe-price/components";
 export * from "../features/billing/stripe-product/components";
+export * from "../features/billing/stripe-coupon/components";
 export * from "../features/billing/stripe-subscription/components";
 export * from "../features/billing/stripe-usage/components";
 export * from "../features/billing/stripe-promotion-code/components";

package/src/client/index.ts

@@ -21,6 +21,8 @@ import { useRoleTableStructure } from "../features/role/hooks";
 import { useUserTableStructure } from "../features/user/hooks";
 import { useStripePriceTableStructure } from "../features/billing/stripe-price/hooks/useStripePriceTableStructure";
 import { useStripeProductTableStructure } from "../features/billing/stripe-product/hooks/useStripeProductTableStructure";
+import { useStripeCouponTableStructure } from "../features/billing/stripe-coupon/hooks/useStripeCouponTableStructure";
+import { useStripeCouponCodeTableStructure } from "../features/billing/stripe-coupon/hooks/useStripeCouponCodeTableStructure";
 import { useWaitlistTableStructure } from "../features/waitlist/hooks/useWaitlistTableStructure";
 import { registerTableGenerator } from "../hooks";
 
@@ -35,5 +37,7 @@ registerTableGenerator("users", useUserTableStructure);
 registerTableGenerator("companies", useCompanyTableStructure);
 registerTableGenerator("stripe-products", useStripeProductTableStructure);
 registerTableGenerator("stripe-prices", useStripePriceTableStructure);
+registerTableGenerator("stripe-coupons", useStripeCouponTableStructure);
+registerTableGenerator("stripe-coupon-codes", useStripeCouponCodeTableStructure);
 registerTableGenerator("waitlists", useWaitlistTableStructure);
 // Note: Content registration moved to app-level to support app-specific cellTopic

package/src/core/index.ts

@@ -56,6 +56,10 @@ export * from "../features/billing/stripe-product";
 export * from "../features/billing/stripe-subscription";
 export * from "../features/billing/stripe-usage";
 export * from "../features/billing/stripe-promotion-code";
+export * from "../features/billing/stripe-coupon";
+// Billing formatters: plain functions, no React, so a server component can format
+// a price. The client-marked ./billing entry exports them too.
+export * from "../features/billing/components/utils/currency";
 // AI connection administration: data + module only, NOT the feature barrel —
 // that one also re-exports the feature's client components, and core must stay
 // importable from the server (same rationale as the tokenusage entries below).

package/src/core/registry/ModuleRegistry.ts

@@ -34,6 +34,9 @@ export interface FoundationModuleDefinitions {
   StripePrice: ModuleWithPermissions;
   StripeUsage: ModuleWithPermissions;
   StripePromotionCode: ModuleWithPermissions;
+  StripeCoupon: ModuleWithPermissions;
+  StripeCouponCode: ModuleWithPermissions;
+  StripeCouponOffer: ModuleWithPermissions;
   // AI connection administration
   AiConnection: ModuleWithPermissions;
   // OAuth modules

package/src/features/billing/components/cards/InvoicesSummaryCard.tsx

@@ -71,8 +71,9 @@ export function InvoicesSummaryCard({ invoices, loading, error, onViewAllClick }
     );
   }
 
-  // Get the most recent invoice
-  const latestInvoice = invoices[0];
+  // The most recent invoice that could charge something: a void one is an unpaid first-payment
+  // attempt that was replaced, which never charged the GM (fall back to it only when nothing else exists)
+  const latestInvoice = invoices.find((inv) => inv.status !== InvoiceStatus.VOID) ?? invoices[0];
   const paidInvoices = invoices.filter((inv) => inv.status === InvoiceStatus.PAID);
   const openInvoices = invoices.filter((inv) => inv.status === InvoiceStatus.OPEN);
 

package/src/features/billing/components/cards/SubscriptionSummaryCard.tsx

@@ -91,7 +91,8 @@ export function SubscriptionSummaryCard({
         <CreditCard className="h-4 w-4 text-muted-foreground" />
       </CardHeader>
       <CardContent>
-        {subscriptions.length === 0 ? (
+        {/* No active or trialing plan (none at all, or only unpaid / ended ones): offer the plans */}
+        {!primarySubscription ? (
           <div className="space-y-2">
             <p className="text-xl font-bold text-muted-foreground">{t("billing.ui.cards.subscriptions.empty_title")}</p>
             <p className="text-xs text-muted-foreground">{t("billing.ui.cards.subscriptions.empty_description")}</p>
@@ -108,7 +109,7 @@ export function SubscriptionSummaryCard({
               <ChevronRight className="h-4 w-4 ms-1 rtl:rotate-180" />
             </Button>
           </div>
-        ) : primarySubscription ? (
+        ) : (
           <div className="space-y-2">
             <div className="flex items-center gap-2">
               <p className="text-xl font-bold">
@@ -147,7 +148,7 @@ export function SubscriptionSummaryCard({
               </p>
             )}
           </div>
-        ) : null}
+        )}
       </CardContent>
     </Card>
   );

package/src/features/billing/components/containers/BillingDashboardContainer.tsx

@@ -22,6 +22,7 @@ import {
   SubscriptionSummaryCard,
 } from "../cards";
 import { BillingDetailModal } from "../modals/BillingDetailModal";
+import { urlWithoutParam } from "../utils/url";
 import { BillingAlertBanner } from "../widgets/BillingAlertBanner";
 
 type ModalType = "subscriptions" | "payment-methods" | "invoices" | "usage" | null;
@@ -282,14 +283,27 @@ export function BillingDashboardContainer() {
     fetchAllData();
   }, [fetchAllData]);
 
-  // Handle URL action parameter for deep linking
+  // Handle URL action parameter for deep linking. `?action=subscribe` records the
+  // intent to subscribe; the wizard itself only renders once a customer exists, so a
+  // company without one sees the setup card first and the wizard opens right after
+  // "Set Up Billing Account" succeeds.
   useEffect(() => {
     const action = searchParams.get("action");
     if (action === "subscribe") {
-      // Open wizard directly (no wrapper modal)
       setShowWizard(true);
-      // Clear the URL param to prevent re-triggering on refresh
-      window.history.replaceState({}, "", window.location.pathname);
+      // Drop only `action`, so a refresh does not re-trigger it. Every other parameter
+      // must survive: a host page (the settings hub) selects this dashboard through
+      // `?section=`, and losing it switches the page away and unmounts this component.
+      window.history.replaceState(
+        window.history.state,
+        "",
+        urlWithoutParam({
+          pathname: window.location.pathname,
+          search: window.location.search,
+          hash: window.location.hash,
+          param: "action",
+        }),
+      );
     }
   }, [searchParams]);
 
@@ -445,9 +459,12 @@ export function BillingDashboardContainer() {
             onOpenChange={handleModalClose}
             title={getModalTitle("subscriptions")}
           >
+            {/* The dashboard's list, so a wizard success (refreshData) refreshes the dialog too */}
             <SubscriptionsContainer
               onOpenWizard={handleOpenWizard}
               hasActiveRecurringSubscription={hasActiveRecurringSubscription}
+              subscriptions={data.subscriptions}
+              onSubscriptionsChange={refreshData}
             />
           </BillingDetailModal>
 
@@ -477,7 +494,7 @@ export function BillingDashboardContainer() {
 
           {/* Subscription Wizard - rendered at dashboard level to avoid nested dialogs */}
           <SubscriptionWizard
-            open={showWizard}
+            open={showWizard && !!data.customer}
             onOpenChange={(open) => !open && handleWizardClose()}
             onSuccess={refreshData}
             hasActiveRecurringSubscription={hasActiveRecurringSubscription}

package/src/features/billing/components/utils/__tests__/discount.spec.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { StripeSubscriptionInterface } from "../../../stripe-subscription/data/stripe-subscription.interface";
+import { applyDiscount, promotionCodeDiscount, subscriptionDiscount } from "../discount";
+
+const subscription = (discount: StripeSubscriptionInterface["discount"]) =>
+  ({ discount }) as unknown as StripeSubscriptionInterface;
+
+describe("applyDiscount", () => {
+  it("takes a percentage off", () => {
+    expect(applyDiscount(999, { discountType: "percent_off", discountValue: 20 })).toBeCloseTo(799.2);
+  });
+
+  it("takes an amount off without going below zero", () => {
+    expect(applyDiscount(499, { discountType: "amount_off", discountValue: 100 })).toBe(399);
+    expect(applyDiscount(499, { discountType: "amount_off", discountValue: 1000 })).toBe(0);
+  });
+
+  it("returns null without a discount or an amount", () => {
+    expect(applyDiscount(999, null)).toBeNull();
+    expect(applyDiscount(undefined, { discountType: "percent_off", discountValue: 20 })).toBeNull();
+  });
+});
+
+describe("promotionCodeDiscount", () => {
+  it("reads a valid code", () => {
+    expect(
+      promotionCodeDiscount({ valid: true, code: "FOUNDER", discountType: "percent_off", discountValue: 20 }),
+    ).toEqual({ discountType: "percent_off", discountValue: 20, currency: undefined });
+  });
+
+  it("ignores an invalid or missing code", () => {
+    expect(
+      promotionCodeDiscount({ valid: false, code: "X", discountType: "percent_off", discountValue: 20 }),
+    ).toBeNull();
+    expect(promotionCodeDiscount(null)).toBeNull();
+  });
+});
+
+describe("subscriptionDiscount", () => {
+  it("reads a percentage discount", () => {
+    expect(subscriptionDiscount(subscription({ percentOff: 20, duration: "forever" }))).toEqual({
+      discountType: "percent_off",
+      discountValue: 20,
+    });
+  });
+
+  it("reads an amount discount with its currency", () => {
+    expect(subscriptionDiscount(subscription({ amountOff: 200, currency: "eur", duration: "once" }))).toEqual({
+      discountType: "amount_off",
+      discountValue: 200,
+      currency: "eur",
+    });
+  });
+
+  it("returns null when the subscription has no discount", () => {
+    expect(subscriptionDiscount(subscription(undefined))).toBeNull();
+    expect(subscriptionDiscount(undefined)).toBeNull();
+  });
+});

package/src/features/billing/components/utils/__tests__/url.spec.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { urlWithoutParam } from "../url";
+
+describe("urlWithoutParam", () => {
+  it("keeps the section when it drops the action", () => {
+    expect(
+      urlWithoutParam({ pathname: "/settings", search: "?section=billing&action=subscribe", param: "action" }),
+    ).toBe("/settings?section=billing");
+  });
+
+  it("keeps the section when the action comes first", () => {
+    expect(
+      urlWithoutParam({ pathname: "/it/settings", search: "?action=subscribe&section=billing", param: "action" }),
+    ).toBe("/it/settings?section=billing");
+  });
+
+  it("returns the bare path when the action was the only parameter", () => {
+    expect(urlWithoutParam({ pathname: "/billing", search: "?action=subscribe", param: "action" })).toBe("/billing");
+  });
+
+  it("leaves a URL without the parameter unchanged, hash included", () => {
+    expect(
+      urlWithoutParam({ pathname: "/settings", search: "?section=billing", hash: "#plans", param: "action" }),
+    ).toBe("/settings?section=billing#plans");
+  });
+
+  it("accepts a search string without the leading question mark", () => {
+    expect(
+      urlWithoutParam({ pathname: "/settings", search: "section=billing&action=subscribe", param: "action" }),
+    ).toBe("/settings?section=billing");
+  });
+});

package/src/features/billing/components/utils/discount.ts

@@ -0,0 +1,38 @@
+import { PromotionCodeValidationResult } from "../../stripe-promotion-code/data/stripe-promotion-code.interface";
+import { StripeSubscriptionInterface } from "../../stripe-subscription/data/stripe-subscription.interface";
+
+/** A discount as the billing screens apply it: a percentage, or an amount in minor units. */
+export type BillingDiscount = {
+  discountType: "percent_off" | "amount_off";
+  discountValue: number;
+  currency?: string;
+};
+
+/** The discount a valid promotion code (typed or automatic) gives, or null. */
+export function promotionCodeDiscount(code: PromotionCodeValidationResult | null | undefined): BillingDiscount | null {
+  if (!code?.valid || !code.discountType || !code.discountValue) return null;
+  return { discountType: code.discountType, discountValue: code.discountValue, currency: code.currency };
+}
+
+/** The discount a subscription already carries in Stripe, or null. */
+export function subscriptionDiscount(
+  subscription: StripeSubscriptionInterface | null | undefined,
+): BillingDiscount | null {
+  const discount = subscription?.discount;
+  if (!discount) return null;
+  if (discount.percentOff) return { discountType: "percent_off", discountValue: discount.percentOff };
+  if (discount.amountOff) {
+    return { discountType: "amount_off", discountValue: discount.amountOff, currency: discount.currency };
+  }
+  return null;
+}
+
+/**
+ * The amount after the discount, in the same minor units; null when there is no
+ * discount or nothing to discount. An amount discount never goes below zero.
+ */
+export function applyDiscount(amount: number | undefined, discount: BillingDiscount | null): number | null {
+  if (!discount || !amount) return null;
+  if (discount.discountType === "percent_off") return amount * (1 - discount.discountValue / 100);
+  return Math.max(0, amount - discount.discountValue);
+}

package/src/features/billing/components/utils/index.ts

@@ -2,3 +2,5 @@ export { formatCurrency, formatFixed, formatInterval } from "./currency";
 export { formatDate } from "./date";
 export type { BillingFormatOptions, BillingTranslator } from "./format-options";
 export { useBillingFormatOptions } from "./useBillingFormatOptions";
+export { applyDiscount, promotionCodeDiscount, subscriptionDiscount } from "./discount";
+export type { BillingDiscount } from "./discount";

package/src/features/billing/components/utils/url.ts

@@ -0,0 +1,12 @@
+/**
+ * The URL to write back after consuming a one-shot query parameter (a deep-link
+ * `?action=`). Drops only `param`; every other parameter and the hash stay, so a
+ * host page that keys its state on the URL (the settings hub's `?section=`) keeps
+ * showing the same place.
+ */
+export function urlWithoutParam(params: { pathname: string; search: string; hash?: string; param: string }): string {
+  const query = new URLSearchParams(params.search);
+  query.delete(params.param);
+  const remaining = query.toString();
+  return `${params.pathname}${remaining ? `?${remaining}` : ""}${params.hash ?? ""}`;
+}