@carlonicora/nextjs-jsonapi 6.1.0 → 6.3.0

package/dist/stripe-price.interface-DGqcklFJ.d.ts

@@ -0,0 +1,132 @@
+import { A as ApiDataInterface } from './ApiDataInterface-BcZeXy5X.js';
+
+interface ModuleInterface extends ApiDataInterface {
+    get name(): string;
+    get permissions(): {
+        create: boolean | string;
+        read: boolean | string;
+        update: boolean | string;
+        delete: boolean | string;
+    };
+}
+
+interface FeatureInterface extends ApiDataInterface {
+    get name(): string;
+    get isCore(): boolean;
+    get modules(): ModuleInterface[];
+}
+
+declare enum SubscriptionStatus {
+    ACTIVE = "active",
+    PAST_DUE = "past_due",
+    UNPAID = "unpaid",
+    CANCELED = "canceled",
+    INCOMPLETE = "incomplete",
+    INCOMPLETE_EXPIRED = "incomplete_expired",
+    TRIALING = "trialing",
+    PAUSED = "paused"
+}
+/**
+ * The discount Stripe applies to the subscription (read-only, synced from Stripe).
+ * Exactly one of percentOff / amountOff is set.
+ */
+type StripeSubscriptionDiscount = {
+    percentOff?: number;
+    amountOff?: number;
+    currency?: string;
+    duration: "forever" | "once" | "repeating";
+    durationInMonths?: number;
+    end?: Date;
+};
+interface StripeSubscriptionInterface extends ApiDataInterface {
+    get stripeSubscriptionId(): string;
+    get status(): SubscriptionStatus;
+    get currentPeriodStart(): Date;
+    get currentPeriodEnd(): Date;
+    get cancelAtPeriodEnd(): boolean;
+    get canceledAt(): Date | undefined;
+    get trialStart(): Date | undefined;
+    get trialEnd(): Date | undefined;
+    get price(): StripePriceInterface | undefined;
+    get discount(): StripeSubscriptionDiscount | undefined;
+}
+type StripeSubscriptionInput = {
+    id: string;
+    priceId?: string;
+    newPriceId?: string;
+    cancelImmediately?: boolean;
+    quantity?: number;
+    trialPeriodDays?: number;
+    paymentMethodId?: string;
+    metadata?: Record<string, any>;
+    promotionCode?: string;
+};
+interface StripeSubscriptionCreateMeta {
+    clientSecret: string | null;
+    paymentIntentId: string | null;
+    requiresAction: boolean;
+}
+interface StripeSubscriptionCreateResponse {
+    subscription: StripeSubscriptionInterface;
+    meta: StripeSubscriptionCreateMeta;
+}
+
+interface StripeProductInterface extends ApiDataInterface {
+    get stripeProductId(): string;
+    get name(): string;
+    get description(): string | undefined;
+    get active(): boolean;
+    get metadata(): Record<string, any> | undefined;
+    get stripePrices(): StripePriceInterface[];
+}
+type StripeProductInput = {
+    id: string;
+    name?: string;
+    description?: string;
+    active?: boolean;
+    metadata?: Record<string, any>;
+};
+
+interface StripePriceInterface extends ApiDataInterface {
+    get stripePriceId(): string;
+    get productId(): string;
+    get product(): StripeProductInterface | undefined;
+    get active(): boolean;
+    get currency(): string;
+    get unitAmount(): number | undefined;
+    get recurring(): PriceRecurring | undefined;
+    get priceType(): "one_time" | "recurring";
+    get nickname(): string | undefined;
+    get lookupKey(): string | undefined;
+    get metadata(): Record<string, any> | undefined;
+    get description(): string | undefined;
+    get features(): string[] | undefined;
+    get token(): number | undefined;
+    get isTrial(): boolean | undefined;
+    get priceFeatures(): FeatureInterface[];
+}
+interface PriceRecurring {
+    interval: "day" | "week" | "month" | "year";
+    intervalCount: number;
+    usageType?: "metered" | "licensed";
+}
+type StripePriceInput = {
+    id: string;
+    productId?: string;
+    currency?: string;
+    unitAmount?: number;
+    nickname?: string;
+    recurring?: {
+        interval: "day" | "week" | "month" | "year";
+        intervalCount?: number;
+        usageType?: "metered" | "licensed";
+    };
+    metadata?: Record<string, any>;
+    description?: string;
+    features?: string[];
+    token?: number;
+    isTrial?: boolean;
+    featureIds?: string[];
+};
+
+export { type FeatureInterface as F, type ModuleInterface as M, type PriceRecurring as P, type StripeSubscriptionInterface as S, type StripePriceInterface as a, type StripePriceInput as b, type StripeProductInterface as c, type StripeProductInput as d, SubscriptionStatus as e, type StripeSubscriptionDiscount as f, type StripeSubscriptionInput as g, type StripeSubscriptionCreateMeta as h, type StripeSubscriptionCreateResponse as i };

package/dist/{useSocket-B0H9pmmH.d.ts → useSocket-BM3q9A0C.d.ts}

@@ -1,4 +1,4 @@
-import { N as NotificationInterface } from './notification.interface-CmAGrijJ.js';
+import { N as NotificationInterface } from './notification.interface-DQReXAD7.js';
 
 interface UseSocketOptions {
     token: string;

package/dist/{useSocket-B5RQb6v2.d.mts → useSocket-CwSoq6VS.d.mts}

@@ -1,4 +1,4 @@
-import { N as NotificationInterface } from './notification.interface-BB6GPpZY.mjs';
+import { N as NotificationInterface } from './notification.interface-CF5h90U2.mjs';
 
 interface UseSocketOptions {
     token: string;

package/dist/{user.interface-CIWGlbqM.d.mts → user.interface-BYnGJ7ss.d.mts}

@@ -1,5 +1,31 @@
 import { A as ApiDataInterface } from './ApiDataInterface-BcZeXy5X.mjs';
-import { F as FeatureInterface, M as ModuleInterface } from './feature.interface-CXb1-vNq.mjs';
+import { S as StripeSubscriptionInterface, F as FeatureInterface, M as ModuleInterface } from './stripe-price.interface-D6mKjAdr.mjs';
+
+/**
+ * The offer the server chose when it sent this period's warning.
+ * Mirrors the backend `CreditWarningOffer`.
+ */
+type CreditWarningOffer = "subscribe" | "upgrade-or-pack" | "pack";
+/**
+ * Child segment of the dismiss route: `POST companies/:companyId/credit-warning/dismiss`.
+ * Must match the backend `CREDIT_WARNING_DISMISS_SEGMENT`.
+ */
+declare const CREDIT_WARNING_DISMISS_SEGMENT = "credit-warning/dismiss";
+/**
+ * Whether the in-app credit warning should show for this company.
+ *
+ * True only when the server sent the warning this period and nobody dismissed it,
+ * the company has AI and an active subscription, and the credits left are at or
+ * below `100 - thresholdPercent` percent of this period's grant. At 0 credits
+ * (or below) it is false: `OutOfCreditsBanner` owns that state.
+ */
+declare function isCreditWarningActive(company: CompanyInterface, thresholdPercent: number): boolean;
+/**
+ * The subscription the `?action=change-plan` deep link opens the wizard on: the
+ * first active or trialing recurring subscription, in the dashboard's own order.
+ * `undefined` means there is none, and the subscribe wizard opens instead.
+ */
+declare function resolveChangePlanTarget(subscriptions: StripeSubscriptionInterface[]): StripeSubscriptionInterface | undefined;
 
 type CompanyInput = {
     id: string;
@@ -37,6 +63,15 @@ interface CompanyInterface extends ApiDataInterface {
      * defaults an absent attribute to `true`, so the getter always has a value.
      */
     get aiEnabled(): boolean;
+    /**
+     * Credit-warning state, written by the server only (never sent by
+     * `createJsonApi()`). All four are absent until the feature is on and the
+     * company has received a monthly grant.
+     */
+    get creditsGrantedThisPeriod(): number | undefined;
+    get creditWarningSentAt(): Date | undefined;
+    get creditWarningDismissedAt(): Date | undefined;
+    get creditWarningOffer(): CreditWarningOffer | undefined;
     get features(): FeatureInterface[];
     get modules(): ModuleInterface[];
     get legal_address(): string | undefined;
@@ -99,4 +134,4 @@ interface UserInterface extends ApiDataInterface {
     get modules(): ModuleInterface[];
 }
 
-export type { CompanyInput as C, RoleInput as R, UserInterface as U, CompanyInterface as a, RoleInterface as b, UserInput as c };
+export { type CreditWarningOffer as C, type RoleInput as R, type UserInterface as U, CREDIT_WARNING_DISMISS_SEGMENT as a, type CompanyInput as b, type CompanyInterface as c, type RoleInterface as d, type UserInput as e, isCreditWarningActive as i, resolveChangePlanTarget as r };

package/dist/{user.interface-C0ZdsBZj.d.ts → user.interface-BqPjVyJI.d.ts}

@@ -1,5 +1,31 @@
 import { A as ApiDataInterface } from './ApiDataInterface-BcZeXy5X.js';
-import { F as FeatureInterface, M as ModuleInterface } from './feature.interface-BO25VLlx.js';
+import { S as StripeSubscriptionInterface, F as FeatureInterface, M as ModuleInterface } from './stripe-price.interface-DGqcklFJ.js';
+
+/**
+ * The offer the server chose when it sent this period's warning.
+ * Mirrors the backend `CreditWarningOffer`.
+ */
+type CreditWarningOffer = "subscribe" | "upgrade-or-pack" | "pack";
+/**
+ * Child segment of the dismiss route: `POST companies/:companyId/credit-warning/dismiss`.
+ * Must match the backend `CREDIT_WARNING_DISMISS_SEGMENT`.
+ */
+declare const CREDIT_WARNING_DISMISS_SEGMENT = "credit-warning/dismiss";
+/**
+ * Whether the in-app credit warning should show for this company.
+ *
+ * True only when the server sent the warning this period and nobody dismissed it,
+ * the company has AI and an active subscription, and the credits left are at or
+ * below `100 - thresholdPercent` percent of this period's grant. At 0 credits
+ * (or below) it is false: `OutOfCreditsBanner` owns that state.
+ */
+declare function isCreditWarningActive(company: CompanyInterface, thresholdPercent: number): boolean;
+/**
+ * The subscription the `?action=change-plan` deep link opens the wizard on: the
+ * first active or trialing recurring subscription, in the dashboard's own order.
+ * `undefined` means there is none, and the subscribe wizard opens instead.
+ */
+declare function resolveChangePlanTarget(subscriptions: StripeSubscriptionInterface[]): StripeSubscriptionInterface | undefined;
 
 type CompanyInput = {
     id: string;
@@ -37,6 +63,15 @@ interface CompanyInterface extends ApiDataInterface {
      * defaults an absent attribute to `true`, so the getter always has a value.
      */
     get aiEnabled(): boolean;
+    /**
+     * Credit-warning state, written by the server only (never sent by
+     * `createJsonApi()`). All four are absent until the feature is on and the
+     * company has received a monthly grant.
+     */
+    get creditsGrantedThisPeriod(): number | undefined;
+    get creditWarningSentAt(): Date | undefined;
+    get creditWarningDismissedAt(): Date | undefined;
+    get creditWarningOffer(): CreditWarningOffer | undefined;
     get features(): FeatureInterface[];
     get modules(): ModuleInterface[];
     get legal_address(): string | undefined;
@@ -99,4 +134,4 @@ interface UserInterface extends ApiDataInterface {
     get modules(): ModuleInterface[];
 }
 
-export type { CompanyInput as C, RoleInput as R, UserInterface as U, CompanyInterface as a, RoleInterface as b, UserInput as c };
+export { type CreditWarningOffer as C, type RoleInput as R, type UserInterface as U, CREDIT_WARNING_DISMISS_SEGMENT as a, type CompanyInput as b, type CompanyInterface as c, type RoleInterface as d, type UserInput as e, isCreditWarningActive as i, resolveChangePlanTarget as r };

package/messages/en.json

@@ -628,6 +628,14 @@
         "subscribe": "Subscribe",
         "title": "Confirm Your Subscription"
       },
+      "credit_warning": {
+        "title": "You've used {percent}% of your AI credits.",
+        "body": "Everything except AI keeps working when they run out.",
+        "subscribe": "Subscribe",
+        "upgrade": "Upgrade your plan",
+        "add_pack": "Add a credit pack",
+        "dismiss": "Dismiss"
+      },
       "dashboard": {
         "errors": {
           "load_customer": "Failed to load billing account",

package/messages/it.json

@@ -628,6 +628,14 @@
         "subscribe": "Abbonati",
         "title": "Conferma il tuo abbonamento"
       },
+      "credit_warning": {
+        "title": "Hai usato l'{percent}% dei tuoi crediti IA.",
+        "body": "Quando finiscono, tutto continua a funzionare tranne l'IA.",
+        "subscribe": "Abbonati",
+        "upgrade": "Passa a un piano superiore",
+        "add_pack": "Aggiungi un pacchetto di crediti",
+        "dismiss": "Chiudi"
+      },
       "dashboard": {
         "errors": {
           "load_customer": "Impossibile caricare l'account di fatturazione",

package/package.json

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

package/src/components/containers/RoundPageContainer.tsx

@@ -239,9 +239,14 @@ export function RoundPageContainer({
   // between the shell and the content is dropped so the document is the only
   // scroller; leaving a single `overflow-hidden` in that chain silently
   // truncates the page instead of letting it grow.
+  //
+  // `--app-banner-h` is the height of an app banner drawn above the header (a
+  // demo bar, a credit warning). Unset, it is 0 and the height is unchanged; an
+  // app that renders such a banner publishes its live height on <html>, or the
+  // banner pushes the page past the viewport and the document scrolls it away.
   const shellHeight = isFixed
-    ? `h-[calc(100svh-var(--app-header-h,3rem))]`
-    : `min-h-[calc(100svh-var(--app-header-h,3rem))]`;
+    ? `h-[calc(100svh-var(--app-header-h,3rem)-var(--app-banner-h,0px))]`
+    : `min-h-[calc(100svh-var(--app-header-h,3rem)-var(--app-banner-h,0px))]`;
   const clip = isFixed ? `overflow-hidden` : ``;
   const scrollY = isFixed ? `overflow-y-auto` : ``;
   // The bar is an in-flow sibling of the content (see MobileNavigationBar's own

package/src/components/index.ts

@@ -24,6 +24,11 @@ export * from "../features/auth/components";
 export * from "../features/administration";
 export * from "../features/ai-connection";
 // Billing components moved to separate entry point: @carlonicora/nextjs-jsonapi/billing
+// Exception: the credit warning banner mounts on every page, so it ships from this
+// Stripe-free entry. Its import chain must never reach `@stripe/*`.
+export { CreditWarningBanner } from "../features/billing/components/widgets/CreditWarningBanner";
+export type { CreditWarningBannerProps } from "../features/billing/components/widgets/CreditWarningBanner";
+export { isCreditWarningActive, CREDIT_WARNING_DISMISS_SEGMENT } from "../features/billing/data/credit-warning";
 export * from "../features/company/components";
 export * from "../features/content/components";
 export * from "../features/how-to/components";

package/src/features/analytics/components/AnalyticsTracker.tsx

@@ -20,7 +20,13 @@ type Attribution = Pick<
 >;
 
 type AnalyticsTrackerProps = {
-  hasConsent: boolean;
+  /**
+   * `undefined` while the app has not read its consent store yet: the tracker sends
+   * nothing and leaves the visitor cookie alone. `false` when there is no consent
+   * (refused or not chosen yet): the cookie is cleared and page views go out without
+   * an id. Never pass `false` as a placeholder for "not read yet".
+   */
+  hasConsent?: boolean;
   resolveSection: (pathname: string) => "public" | "app";
   sensitivePrefixes?: string[];
 };
@@ -63,11 +69,16 @@ function maskSensitivePath(path: string, sensitivePrefixes: string[] | undefined
 export function AnalyticsTracker({ hasConsent, resolveSection, sensitivePrefixes }: AnalyticsTrackerProps): null {
   const pathname = usePathname();
   const lastPath = useRef<string | null>(null);
-  const lastConsent = useRef<boolean>(false);
+  // The last consent value the app actually read. `undefined` until then, so a page
+  // load with consent already stored is never mistaken for the Accept click.
+  const lastKnownConsent = useRef<boolean | undefined>(undefined);
   const attribution = useRef<Attribution | null>(null);
 
   useEffect(() => {
-    if (!hasConsent) clearVisitorCookie();
+    // Consent not read yet: send nothing and keep the cookie, or a visitor who
+    // already accepted would lose their id on every tracker mount.
+    if (hasConsent === undefined) return;
+    if (hasConsent === false) clearVisitorCookie();
 
     if (!pathname) return;
     if (typeof navigator !== "undefined" && navigator.webdriver) return;
@@ -75,12 +86,13 @@ export function AnalyticsTracker({ hasConsent, resolveSection, sensitivePrefixes
     const path = pathname.split(/[?#]/)[0] || "/";
     if (path.startsWith(EXCLUDED_PREFIX)) return;
 
-    // One event per distinct path. The same path is sent again only when consent
-    // was just granted, so the processor starts a new visitor on the cookie id.
+    // One event per distinct path. The same path is sent again only when the
+    // visitor clicks Accept (a known `false` turning `true`), flagged so the API
+    // moves the open cookieless session onto the cookie id.
     const isNewPath = lastPath.current !== path;
-    const consentJustGranted = hasConsent && !lastConsent.current;
-    lastConsent.current = hasConsent;
-    if (!isNewPath && !consentJustGranted) return;
+    const consentGranted = hasConsent === true && lastKnownConsent.current === false;
+    lastKnownConsent.current = hasConsent;
+    if (!isNewPath && !consentGranted) return;
     lastPath.current = path;
 
     const sentPath = maskSensitivePath(path, sensitivePrefixes);
@@ -93,6 +105,7 @@ export function AnalyticsTracker({ hasConsent, resolveSection, sensitivePrefixes
     };
 
     if (hasConsent) input.visitorId = ensureVisitorCookie();
+    if (consentGranted) input.consentGranted = true;
 
     // The first event of the page load carries the attribution. The event sent
     // because consent was just granted carries it again, so the session opened
@@ -102,7 +115,7 @@ export function AnalyticsTracker({ hasConsent, resolveSection, sensitivePrefixes
       const referrer = readExternalReferrer();
       attribution.current = { ...(referrer ? { referrer } : {}), ...readUtm(window.location.search) };
     }
-    if (isFirstEvent || consentJustGranted) Object.assign(input, attribution.current);
+    if (isFirstEvent || consentGranted) Object.assign(input, attribution.current);
 
     // AnalyticsService.track never rejects: it logs and swallows its own failures.
     void AnalyticsService.track(input);

package/src/features/analytics/components/__tests__/AnalyticsTracker.spec.tsx

@@ -215,6 +215,73 @@ describe("AnalyticsTracker", () => {
     expect(eventAt(1)).toEqual(expect.objectContaining({ path: "/pricing", visitorId: expect.stringMatching(UUID) }));
   });
 
+  it("sends nothing and keeps the cookie while consent is unknown", () => {
+    document.cookie = "analytics_visitor=keep-me; path=/";
+    mocks.pathname = "/";
+    const { rerender } = render(<AnalyticsTracker hasConsent={undefined} resolveSection={publicSection} />);
+
+    mocks.pathname = "/pricing";
+    rerender(<AnalyticsTracker hasConsent={undefined} resolveSection={publicSection} />);
+
+    expect(mocks.track).not.toHaveBeenCalled();
+    expect(document.cookie).toContain("analytics_visitor=keep-me");
+
+    rerender(<AnalyticsTracker hasConsent={true} resolveSection={publicSection} />);
+
+    expect(mocks.track).toHaveBeenCalledTimes(1);
+    expect(eventAt(0).path).toBe("/pricing");
+  });
+
+  it("keeps the existing cookie id when unknown consent resolves to accepted", () => {
+    document.cookie = "analytics_visitor=keep-me; path=/";
+    mocks.pathname = "/pricing";
+    const { rerender } = render(<AnalyticsTracker hasConsent={undefined} resolveSection={publicSection} />);
+    rerender(<AnalyticsTracker hasConsent={true} resolveSection={publicSection} />);
+
+    expect(mocks.track).toHaveBeenCalledTimes(1);
+    expect(eventAt(0)).toEqual(expect.objectContaining({ visitorId: "keep-me" }));
+    expect(eventAt(0)).not.toHaveProperty("consentGranted");
+  });
+
+  it("clears the cookie once unknown consent resolves to refused", () => {
+    document.cookie = "analytics_visitor=keep-me; path=/";
+    mocks.pathname = "/pricing";
+    const { rerender } = render(<AnalyticsTracker hasConsent={undefined} resolveSection={publicSection} />);
+
+    expect(mocks.track).not.toHaveBeenCalled();
+    expect(document.cookie).toContain("analytics_visitor=keep-me");
+
+    rerender(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} />);
+
+    expect(mocks.track).toHaveBeenCalledTimes(1);
+    expect(eventAt(0).visitorId).toBeUndefined();
+    expect(document.cookie).not.toContain("analytics_visitor");
+  });
+
+  it("carries attribution on the first known event", () => {
+    setReferrer("https://elsewhere.example/");
+    mocks.pathname = "/pricing";
+    const { rerender } = render(<AnalyticsTracker hasConsent={undefined} resolveSection={publicSection} />);
+    rerender(<AnalyticsTracker hasConsent={true} resolveSection={publicSection} />);
+
+    expect(mocks.track).toHaveBeenCalledTimes(1);
+    expect(eventAt(0)).toEqual(
+      expect.objectContaining({ referrer: "https://elsewhere.example/", visitorId: expect.stringMatching(UUID) }),
+    );
+  });
+
+  it("flags the accept click", () => {
+    mocks.pathname = "/pricing";
+    const { rerender } = render(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} />);
+    rerender(<AnalyticsTracker hasConsent={true} resolveSection={publicSection} />);
+
+    expect(mocks.track).toHaveBeenCalledTimes(2);
+    expect(eventAt(0)).not.toHaveProperty("consentGranted");
+    expect(eventAt(1)).toEqual(
+      expect.objectContaining({ consentGranted: true, visitorId: expect.stringMatching(UUID) }),
+    );
+  });
+
   it("skips automated browsers and the analytics admin pages", () => {
     setWebdriver(true);
     mocks.pathname = "/pricing";

package/src/features/analytics/data/__tests__/models.spec.ts

@@ -212,6 +212,19 @@ describe("analytics models — createJsonApi", () => {
     expect(Object.keys(doc.data.relationships ?? {})).toHaveLength(0);
   });
 
+  it("serialises consentGranted only when given", () => {
+    const flagged = new AnalyticsEvent().createJsonApi({
+      id: "e2",
+      path: "/",
+      section: "public",
+      consentGranted: true,
+    });
+    const plain = new AnalyticsEvent().createJsonApi({ id: "e3", path: "/", section: "public" });
+
+    expect(flagged.data.attributes.consentGranted).toBe(true);
+    expect(plain.data.attributes).not.toHaveProperty("consentGranted");
+  });
+
   it("serialises a summary back to a JSON:API resource object", () => {
     const doc = new AnalyticsSummary().createJsonApi({
       id: "all|current",

package/src/features/analytics/data/analytics-event.ts

@@ -57,6 +57,7 @@ export class AnalyticsEvent extends AbstractApiData implements AnalyticsEventInt
     if (data.utmContent !== undefined) response.data.attributes.utmContent = data.utmContent;
     if (data.visitorId !== undefined) response.data.attributes.visitorId = data.visitorId;
     if (data.screenWidth !== undefined) response.data.attributes.screenWidth = data.screenWidth;
+    if (data.consentGranted !== undefined) response.data.attributes.consentGranted = data.consentGranted;
 
     return response;
   }

package/src/features/analytics/data/analytics.types.ts

@@ -31,6 +31,8 @@ export type AnalyticsEventInput = {
   utmContent?: string;
   visitorId?: string;
   screenWidth?: number;
+  /** True only on the event sent by the Accept click: the API adopts the open cookieless session. */
+  consentGranted?: boolean;
 };
 
 // Input types for the read-only models' createJsonApi(). `id` is always

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

@@ -14,6 +14,7 @@ import { SubscriptionsContainer } from "../../stripe-subscription/components";
 import { SubscriptionWizard } from "../../stripe-subscription/components/wizards";
 import { MeterInterface, MeterSummaryInterface, StripeUsageService } from "../../stripe-usage";
 import { UsageContainer } from "../../stripe-usage/components";
+import { resolveChangePlanTarget } from "../../data/credit-warning";
 import {
   BillingUsageSummaryCard,
   CustomerInfoCard,
@@ -89,6 +90,10 @@ export function BillingDashboardContainer() {
   const [showWizard, setShowWizard] = useState(false);
   const [editingSubscription, setEditingSubscription] = useState<StripeSubscriptionInterface | null>(null);
 
+  // `?action=change-plan` needs the subscriptions to pick the wizard's target, so the
+  // URL effect only records the intent and a second effect acts on it once they load.
+  const [pendingChangePlan, setPendingChangePlan] = useState(false);
+
   // Check if company has metered subscriptions
   const hasMeteredSubscriptions = useCallback((): boolean => {
     return data.subscriptions.some((sub) => sub.price?.recurring?.usageType === "metered");
@@ -286,11 +291,13 @@ export function BillingDashboardContainer() {
   // 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.
+  // "Set Up Billing Account" succeeds. `?action=change-plan` records a pending intent
+  // that the effect below resolves once the subscriptions have loaded.
   useEffect(() => {
     const action = searchParams.get("action");
-    if (action === "subscribe") {
-      setShowWizard(true);
+    if (action === "subscribe" || action === "change-plan") {
+      if (action === "subscribe") setShowWizard(true);
+      else setPendingChangePlan(true);
       // 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.
@@ -307,6 +314,16 @@ export function BillingDashboardContainer() {
     }
   }, [searchParams]);
 
+  // Act on a pending `?action=change-plan` once the subscriptions fetch has finished:
+  // open the wizard on the active or trialing recurring subscription, or the subscribe
+  // wizard when there is none. The intent is cleared in the same step, so the reload
+  // after the wizard closes does not open it again.
+  useEffect(() => {
+    if (!pendingChangePlan || loading.subscriptions) return;
+    setPendingChangePlan(false);
+    handleOpenWizard(resolveChangePlanTarget(data.subscriptions));
+  }, [pendingChangePlan, loading.subscriptions, data.subscriptions, handleOpenWizard]);
+
   // Detect critical subscriptions for alert banners
   const criticalSubscriptions = data.subscriptions.filter(
     (sub) =>

package/src/features/billing/components/widgets/CreditWarningBanner.tsx

@@ -0,0 +1,93 @@
+"use client";
+
+// Exported from the Stripe-free `components` entry, because the banner mounts on
+// every page. Keep every import here (and everything they import) free of `@stripe/*`.
+
+import { XIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useState } from "react";
+import { Alert, AlertAction, AlertDescription, AlertTitle } from "../../../../shadcnui/ui/alert";
+import { Button } from "../../../../shadcnui/ui/button";
+import { Link } from "../../../../shadcnui/custom/link";
+import { CompanyService } from "../../../company/data/company.service";
+import { useCurrentUserContext } from "../../../user/contexts/CurrentUserContext";
+import { isCreditWarningActive } from "../../data/credit-warning";
+
+export type CreditWarningBannerProps = {
+  /** Only company administrators see the banner and can dismiss it. */
+  canManageBilling: boolean;
+  /** Must match the API's `billing.creditWarning.thresholdPercent`. Defaults to 80. */
+  thresholdPercent?: number;
+  changePlanHref?: string;
+  buyCreditsHref?: string;
+};
+
+/**
+ * Shown once per billing period when the credits left fall to `100 - thresholdPercent`
+ * percent of this period's grant. Hidden at 0 credits, where the app's out-of-credits
+ * banner takes over. The offer the server picked decides which links show.
+ */
+export function CreditWarningBanner({
+  canManageBilling,
+  thresholdPercent = 80,
+  changePlanHref = "/settings/billing?action=change-plan",
+  buyCreditsHref = "/settings/billing?action=subscribe",
+}: CreditWarningBannerProps) {
+  const t = useTranslations();
+  // `company` is the live one, with the `company:credits_updated` balances applied.
+  const { company, refreshUser } = useCurrentUserContext();
+  const [dismissing, setDismissing] = useState(false);
+
+  // Checked after every hook, so the hook count never changes between renders.
+  if (!company || !canManageBilling || !isCreditWarningActive(company, thresholdPercent)) return null;
+
+  const offer = company.creditWarningOffer;
+
+  const handleDismiss = async () => {
+    setDismissing(true);
+    try {
+      await CompanyService.dismissCreditWarning({ companyId: company.id });
+      await refreshUser({ skipCookieUpdate: true });
+    } finally {
+      setDismissing(false);
+    }
+  };
+
+  return (
+    <Alert className="mb-4">
+      <AlertTitle>{t("billing.ui.credit_warning.title", { percent: thresholdPercent })}</AlertTitle>
+      <AlertDescription>
+        <p>{t("billing.ui.credit_warning.body")}</p>
+        {/* Never underlined: colour and weight carry the affordance. */}
+        <div className="mt-1 flex flex-wrap items-center gap-x-4 gap-y-1">
+          {offer === "subscribe" && (
+            <Link href={changePlanHref} className="text-primary font-medium">
+              {t("billing.ui.credit_warning.subscribe")}
+            </Link>
+          )}
+          {offer === "upgrade-or-pack" && (
+            <Link href={changePlanHref} className="text-primary font-medium">
+              {t("billing.ui.credit_warning.upgrade")}
+            </Link>
+          )}
+          {(offer === "upgrade-or-pack" || offer === "pack") && (
+            <Link href={buyCreditsHref} className="text-primary font-medium">
+              {t("billing.ui.credit_warning.add_pack")}
+            </Link>
+          )}
+        </div>
+      </AlertDescription>
+      <AlertAction>
+        <Button
+          variant="ghost"
+          size="icon-xs"
+          aria-label={t("billing.ui.credit_warning.dismiss")}
+          disabled={dismissing}
+          onClick={handleDismiss}
+        >
+          <XIcon />
+        </Button>
+      </AlertAction>
+    </Alert>
+  );
+}