@carlonicora/nextjs-jsonapi 5.4.0 → 5.6.0

package/src/features/analytics/contexts/AnalyticsAdminContext.tsx

@@ -4,7 +4,6 @@ import { useTranslations } from "next-intl";
 import { createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useState } from "react";
 import { Modules, NextRef } from "../../../core";
 import { SharedProvider } from "../../../contexts";
-import { usePageUrlGenerator } from "../../../hooks";
 import { BreadcrumbItemData } from "../../../interfaces";
 import { AnalyticsAdminFilterBar } from "../components/AnalyticsAdminFilterBar";
 import type { AnalyticsBreakdownInterface } from "../data/analytics-breakdown.interface";
@@ -19,13 +18,6 @@ import {
 } from "../data/analytics.types";
 import { AnalyticsAdminService } from "../data/AnalyticsAdminService";
 
-/**
- * Default route the breadcrumb links back to. A host app that mounts the page
- * elsewhere overrides it with the `pageUrl` prop — the constant stays here
- * because the breadcrumb is built by this provider, not by the app.
- */
-const ANALYTICS_ADMIN_PAGE_URL = "/administration/analytics";
-
 /** Default base route of the journey page each session row links to. */
 const ANALYTICS_SESSION_PAGE_URL = "/administration/analytics/sessions";
 
@@ -86,7 +78,11 @@ type AnalyticsAdminProviderProps = {
   initialFrom?: string;
   /** ISO 8601 instant. Defaults to now. */
   initialTo?: string;
-  /** Route the breadcrumb links back to. */
+  /**
+   * @deprecated No longer read. This provider only serves the dashboard, which
+   * is the current page, so its breadcrumb is not linked. Kept so existing
+   * callers still compile.
+   */
   pageUrl?: string;
   /** Base route of the journey page each session row links to. */
   sessionPageUrl?: string;
@@ -105,11 +101,9 @@ export const AnalyticsAdminProvider = ({
   children,
   initialFrom,
   initialTo,
-  pageUrl = ANALYTICS_ADMIN_PAGE_URL,
   sessionPageUrl = ANALYTICS_SESSION_PAGE_URL,
 }: AnalyticsAdminProviderProps) => {
   const t = useTranslations();
-  const generateUrl = usePageUrlGenerator();
 
   const [filters, setFilterState] = useState<AnalyticsAdminFilterState>(() => {
     const range = defaultRange();
@@ -205,12 +199,9 @@ export const AnalyticsAdminProvider = ({
     }
   }, [sessionsNextPage]);
 
-  const breadcrumb = (): BreadcrumbItemData[] => [
-    {
-      name: t("analytics.admin.title"),
-      href: generateUrl({ page: pageUrl }),
-    },
-  ];
+  // Unlinked: this provider only serves the dashboard, so the root is always
+  // the current page. The journey page publishes its own linked breadcrumb.
+  const breadcrumb = (): BreadcrumbItemData[] => [{ name: t("analytics.admin.title") }];
 
   const title = () => ({
     type: t("analytics.admin.title"),

package/src/features/analytics/contexts/__tests__/AnalyticsAdminContext.spec.tsx

@@ -1,5 +1,6 @@
 import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { useSharedContext } from "../../../../contexts/SharedContext";
 import { AnalyticsAdminService } from "../../data/AnalyticsAdminService";
 import { AnalyticsAdminProvider, useAnalyticsAdmin } from "../AnalyticsAdminContext";
 
@@ -40,6 +41,11 @@ function Probe() {
   );
 }
 
+function BreadcrumbProbe() {
+  const { breadcrumbs } = useSharedContext();
+  return <span data-testid="breadcrumbs">{JSON.stringify(breadcrumbs)}</span>;
+}
+
 describe("AnalyticsAdminContext", () => {
   // The mocked service is module-level, so its call counts survive across tests.
   beforeEach(() => {
@@ -137,4 +143,15 @@ describe("AnalyticsAdminContext", () => {
     );
     expect(screen.getByTestId("has-more")).toHaveTextContent("false");
   });
+
+  it("publishes the dashboard as an unlinked breadcrumb, since it is the current page", async () => {
+    render(
+      <AnalyticsAdminProvider>
+        <BreadcrumbProbe />
+      </AnalyticsAdminProvider>,
+    );
+
+    await waitFor(() => expect(AnalyticsAdminService.getSessions).toHaveBeenCalled());
+    expect(screen.getByTestId("breadcrumbs")).toHaveTextContent(JSON.stringify([{ name: "analytics.admin.title" }]));
+  });
 });

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 ?? ""}`;
+}

package/src/features/billing/contexts/CouponContext.tsx

@@ -0,0 +1,211 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { createContext, ReactNode, useCallback, useContext, useMemo, useState } from "react";
+import { SharedProvider } from "../../../contexts/SharedContext";
+import { JsonApiHydratedDataInterface, Modules, rehydrate } from "../../../core";
+import { usePageUrlGenerator } from "../../../hooks";
+import { BreadcrumbItemData } from "../../../interfaces";
+import { getRoleId } from "../../../roles";
+import { useCurrentUserContext } from "../../user/contexts";
+import { CouponRefresher } from "../stripe-coupon/components/forms/CouponRefresher";
+import CouponEditor from "../stripe-coupon/components/forms/CouponEditor";
+import {
+  StripeCouponCodeFlagsInput,
+  StripeCouponCodeInput,
+  StripeCouponCodeInterface,
+} from "../stripe-coupon/data/stripe-coupon-code.interface";
+import { StripeCouponCodeService } from "../stripe-coupon/data/stripe-coupon-code.service";
+import {
+  StripeCouponInput,
+  StripeCouponInterface,
+  StripeCouponRenameInput,
+} from "../stripe-coupon/data/stripe-coupon.interface";
+import { StripeCouponService } from "../stripe-coupon/data/stripe-coupon.service";
+
+export interface CouponContextType {
+  coupon: StripeCouponInterface | undefined;
+  setCoupon: (value: StripeCouponInterface | undefined) => void;
+  reloadCoupon: () => Promise<void>;
+  createCoupon: (input: StripeCouponInput) => Promise<StripeCouponInterface>;
+  renameCoupon: (input: StripeCouponRenameInput) => Promise<StripeCouponInterface>;
+  refreshCounts: (id?: string) => Promise<void>;
+  createCode: (input: StripeCouponCodeInput) => Promise<StripeCouponCodeInterface>;
+  updateCodeFlags: (input: StripeCouponCodeFlagsInput) => Promise<StripeCouponCodeInterface>;
+  /** Bumped by every mutation. Mounted lists re-fetch on it. */
+  catalogueVersion: number;
+  refreshCatalogue: () => void;
+}
+
+const CouponContext = createContext<CouponContextType | undefined>(undefined);
+
+export type CouponProviderProps = {
+  children: ReactNode;
+  dehydratedCoupon?: JsonApiHydratedDataInterface;
+  /**
+   * Publish breadcrumbs + title into SharedProvider. Pass `false` when this
+   * provider is mounted INSIDE another entity's page (the Codes tab of the
+   * products page mounts CouponProvider that way): SharedProvider replaces its
+   * value for the subtree rather than merging (SharedContext.tsx:35-37), so a
+   * nested provider that publishes chrome would blank the host page's title.
+   */
+  publishChrome?: boolean;
+};
+
+const defaultContextValue: CouponContextType = {
+  coupon: undefined,
+  setCoupon: () => {},
+  reloadCoupon: async () => {},
+  createCoupon: async () => {
+    throw new Error("createCoupon requires a CouponProvider");
+  },
+  renameCoupon: async () => {
+    throw new Error("renameCoupon requires a CouponProvider");
+  },
+  refreshCounts: async () => {},
+  createCode: async () => {
+    throw new Error("createCode requires a CouponProvider");
+  },
+  updateCodeFlags: async () => {
+    throw new Error("updateCodeFlags requires a CouponProvider");
+  },
+  catalogueVersion: 0,
+  refreshCatalogue: () => {},
+};
+
+export const CouponProvider = ({ children, dehydratedCoupon, publishChrome = true }: CouponProviderProps) => {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+  const { hasRole } = useCurrentUserContext();
+
+  const [coupon, setCoupon] = useState<StripeCouponInterface | undefined>(
+    dehydratedCoupon ? rehydrate<StripeCouponInterface>(Modules.StripeCoupon, dehydratedCoupon) : undefined,
+  );
+  const [catalogueVersion, setCatalogueVersion] = useState<number>(0);
+
+  const refreshCatalogue = useCallback(() => setCatalogueVersion((value) => value + 1), []);
+
+  const reloadCoupon = useCallback(async () => {
+    if (!coupon?.id) return;
+    setCoupon(await StripeCouponService.getCoupon({ id: coupon.id }));
+  }, [coupon?.id]);
+
+  const createCoupon = useCallback(
+    async (input: StripeCouponInput) => {
+      const saved = await StripeCouponService.createCoupon(input);
+      refreshCatalogue();
+      return saved;
+    },
+    [refreshCatalogue],
+  );
+
+  const renameCoupon = useCallback(
+    async (input: StripeCouponRenameInput) => {
+      const saved = await StripeCouponService.renameCoupon(input);
+      setCoupon(saved);
+      refreshCatalogue();
+      return saved;
+    },
+    [refreshCatalogue],
+  );
+
+  const refreshCounts = useCallback(
+    async (id?: string) => {
+      const target = id ?? coupon?.id;
+      if (!target) return;
+      const saved = await StripeCouponService.refreshCounts({ id: target });
+      if (coupon?.id === target) setCoupon(saved);
+      refreshCatalogue();
+    },
+    [coupon?.id, refreshCatalogue],
+  );
+
+  const createCode = useCallback(
+    async (input: StripeCouponCodeInput) => {
+      const saved = await StripeCouponCodeService.createCode(input);
+      await reloadCoupon();
+      refreshCatalogue();
+      return saved;
+    },
+    [reloadCoupon, refreshCatalogue],
+  );
+
+  const updateCodeFlags = useCallback(
+    async (input: StripeCouponCodeFlagsInput) => {
+      const saved = await StripeCouponCodeService.updateFlags(input);
+      await reloadCoupon();
+      refreshCatalogue();
+      return saved;
+    },
+    [reloadCoupon, refreshCatalogue],
+  );
+
+  const value = useMemo<CouponContextType>(
+    () => ({
+      coupon,
+      setCoupon,
+      reloadCoupon,
+      createCoupon,
+      renameCoupon,
+      refreshCounts,
+      createCode,
+      updateCodeFlags,
+      catalogueVersion,
+      refreshCatalogue,
+    }),
+    [
+      coupon,
+      reloadCoupon,
+      createCoupon,
+      renameCoupon,
+      refreshCounts,
+      createCode,
+      updateCodeFlags,
+      catalogueVersion,
+      refreshCatalogue,
+    ],
+  );
+
+  if (!publishChrome) return <CouponContext.Provider value={value}>{children}</CouponContext.Provider>;
+
+  const breadcrumb = (): BreadcrumbItemData[] => {
+    const items: BreadcrumbItemData[] = [
+      {
+        name: t("billing.admin.products.tabs.codes"),
+        // Linked only when it is NOT the current page. The Codes list is a tab
+        // of the products page, so the link carries its `?section=`.
+        ...(coupon
+          ? { href: generateUrl({ page: Modules.StripeProduct, additionalParameters: { section: "codes" } }) }
+          : {}),
+      },
+    ];
+    if (coupon) items.push({ name: coupon.name });
+    return items;
+  };
+
+  const title = () => {
+    const response: any = { type: t("billing.admin.coupons.title") };
+    if (!coupon) return response;
+
+    response.element = coupon.name;
+
+    // narr8 note: gate on hasRole ONLY. hasPermissionToModule always returns
+    // false in this app, so gating an editor on it hides the editor outright.
+    if (hasRole(getRoleId().Administrator)) {
+      response.functions = [
+        <CouponRefresher key="couponRefresher" coupon={coupon} />,
+        <CouponEditor key="couponEditor" coupon={coupon} propagateChanges={setCoupon} />,
+      ];
+    }
+
+    return response;
+  };
+
+  return (
+    <SharedProvider value={{ breadcrumbs: breadcrumb(), title: title() }}>
+      <CouponContext.Provider value={value}>{children}</CouponContext.Provider>
+    </SharedProvider>
+  );
+};
+
+export const useCouponContext = (): CouponContextType => useContext(CouponContext) ?? defaultContextValue;

package/src/features/billing/contexts/index.ts

@@ -1,2 +1,3 @@
+export * from "./CouponContext";
 export * from "./PriceContext";
 export * from "./ProductContext";