@carlonicora/nextjs-jsonapi 6.2.0 → 6.4.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.2.0",
+  "version": "6.4.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/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>
+  );
+}

package/src/features/billing/data/credit-warning.spec.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import type { CompanyInterface } from "../../company/data/company.interface";
+import { SubscriptionStatus } from "../stripe-subscription/data/stripe-subscription.interface";
+import type { StripeSubscriptionInterface } from "../stripe-subscription/data/stripe-subscription.interface";
+import { CREDIT_WARNING_DISMISS_SEGMENT, isCreditWarningActive, resolveChangePlanTarget } from "./credit-warning";
+
+const makeCompany = (overrides: Record<string, unknown> = {}): CompanyInterface =>
+  ({
+    aiEnabled: true,
+    isActiveSubscription: true,
+    creditsGrantedThisPeriod: 200,
+    creditWarningSentAt: new Date("2026-10-25T10:00:00.000Z"),
+    creditWarningDismissedAt: undefined,
+    availableMonthlyCredits: 30,
+    availableExtraCredits: 0,
+    ...overrides,
+  }) as unknown as CompanyInterface;
+
+const makeSubscription = (
+  id: string,
+  status: SubscriptionStatus,
+  priceType: "one_time" | "recurring",
+): StripeSubscriptionInterface => ({ id, status, price: { priceType } }) as unknown as StripeSubscriptionInterface;
+
+describe("isCreditWarningActive (threshold 80)", () => {
+  it("is true with 30 of 200 left", () => {
+    expect(isCreditWarningActive(makeCompany({ availableMonthlyCredits: 30 }), 80)).toBe(true);
+  });
+
+  it("is true at exactly 80% used (40 of 200 left)", () => {
+    expect(isCreditWarningActive(makeCompany({ availableMonthlyCredits: 40 }), 80)).toBe(true);
+  });
+
+  it("is false at 0 credits, which is the out-of-credits banner's job", () => {
+    expect(isCreditWarningActive(makeCompany({ availableMonthlyCredits: 0, availableExtraCredits: 0 }), 80)).toBe(
+      false,
+    );
+    expect(isCreditWarningActive(makeCompany({ availableMonthlyCredits: 0, availableExtraCredits: -0.3 }), 80)).toBe(
+      false,
+    );
+  });
+
+  it("is false when monthly plus extra is above the threshold (50 > 40)", () => {
+    expect(isCreditWarningActive(makeCompany({ availableMonthlyCredits: 30, availableExtraCredits: 20 }), 80)).toBe(
+      false,
+    );
+  });
+
+  it("is false once dismissed", () => {
+    expect(isCreditWarningActive(makeCompany({ creditWarningDismissedAt: new Date() }), 80)).toBe(false);
+  });
+
+  it("is false when the warning was never sent", () => {
+    expect(isCreditWarningActive(makeCompany({ creditWarningSentAt: undefined }), 80)).toBe(false);
+  });
+
+  it("is false without an active subscription", () => {
+    expect(isCreditWarningActive(makeCompany({ isActiveSubscription: false }), 80)).toBe(false);
+  });
+
+  it("is false when AI is off", () => {
+    expect(isCreditWarningActive(makeCompany({ aiEnabled: false }), 80)).toBe(false);
+  });
+
+  it("is false when nothing was granted this period", () => {
+    expect(isCreditWarningActive(makeCompany({ creditsGrantedThisPeriod: undefined }), 80)).toBe(false);
+  });
+});
+
+describe("CREDIT_WARNING_DISMISS_SEGMENT", () => {
+  it("matches the backend segment", () => {
+    expect(CREDIT_WARNING_DISMISS_SEGMENT).toBe("credit-warning/dismiss");
+  });
+});
+
+describe("resolveChangePlanTarget", () => {
+  it("picks the trialing recurring subscription over a one-time one", () => {
+    const oneTime = makeSubscription("one-time", SubscriptionStatus.ACTIVE, "one_time");
+    const trialing = makeSubscription("trialing", SubscriptionStatus.TRIALING, "recurring");
+
+    expect(resolveChangePlanTarget([oneTime, trialing])).toBe(trialing);
+  });
+
+  it("returns undefined when the only recurring subscription is canceled", () => {
+    const canceled = makeSubscription("canceled", SubscriptionStatus.CANCELED, "recurring");
+
+    expect(resolveChangePlanTarget([canceled])).toBeUndefined();
+  });
+
+  it("returns the first active recurring subscription in array order", () => {
+    const first = makeSubscription("first", SubscriptionStatus.ACTIVE, "recurring");
+    const second = makeSubscription("second", SubscriptionStatus.ACTIVE, "recurring");
+
+    expect(resolveChangePlanTarget([first, second])).toBe(first);
+  });
+});

package/src/features/billing/data/credit-warning.ts

@@ -0,0 +1,57 @@
+// Credit warning: shared contract with the backend and pure helpers.
+// Keep this file free of any `@stripe/*` import: it is re-exported from the
+// Stripe-free `components` entry, because the banner mounts on every page.
+
+import type { CompanyInterface } from "../../company/data/company.interface";
+import { SubscriptionStatus } from "../stripe-subscription/data/stripe-subscription.interface";
+import type { StripeSubscriptionInterface } from "../stripe-subscription/data/stripe-subscription.interface";
+
+/**
+ * The offer the server chose when it sent this period's warning.
+ * Mirrors the backend `CreditWarningOffer`.
+ */
+export 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`.
+ */
+export 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.
+ */
+export function isCreditWarningActive(company: CompanyInterface, thresholdPercent: number): boolean {
+  if (!company.aiEnabled || !company.isActiveSubscription) return false;
+  if (!company.creditWarningSentAt || company.creditWarningDismissedAt) return false;
+
+  const granted = company.creditsGrantedThisPeriod;
+  if (granted === undefined || granted <= 0) return false;
+
+  const monthly = company.availableMonthlyCredits;
+  const extra = company.availableExtraCredits;
+  // Same "has credits" test as useHasCredits / CompanyService.hasAvailableCredits.
+  if (!(monthly > 0 || extra > 0)) return false;
+
+  return monthly + extra <= (granted * (100 - thresholdPercent)) / 100;
+}
+
+/**
+ * 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.
+ */
+export function resolveChangePlanTarget(
+  subscriptions: StripeSubscriptionInterface[],
+): StripeSubscriptionInterface | undefined {
+  return subscriptions.find(
+    (sub) =>
+      (sub.status === SubscriptionStatus.ACTIVE || sub.status === SubscriptionStatus.TRIALING) &&
+      sub.price?.priceType === "recurring",
+  );
+}

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

@@ -3,3 +3,6 @@ export { BillingService } from "./billing.service";
 
 // Data classes
 export { Billing } from "./Billing";
+
+// Credit warning (Stripe-free)
+export * from "./credit-warning";

package/src/features/billing/i18n-keys.ts

@@ -397,4 +397,10 @@ export const BILLING_UI_I18N_KEYS = [
   "billing.ui.wizard.review.use_another_card",
   "billing.ui.wizard.steps.select_plan",
   "billing.ui.wizard.subscribe_description",
+  "billing.ui.credit_warning.title",
+  "billing.ui.credit_warning.body",
+  "billing.ui.credit_warning.subscribe",
+  "billing.ui.credit_warning.upgrade",
+  "billing.ui.credit_warning.add_pack",
+  "billing.ui.credit_warning.dismiss",
 ] as const;