@carlonicora/nextjs-jsonapi 6.1.0 → 6.3.0

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;

package/src/features/company/data/company.interface.ts

@@ -1,6 +1,7 @@
 import { ApiDataInterface } from "../../../core";
 import { FeatureInterface } from "../../feature/data/feature.interface";
 import { ModuleInterface } from "../../module/data/module.interface";
+import type { CreditWarningOffer } from "../../billing/data/credit-warning";
 
 export type CompanyInput = {
   id: string;
@@ -45,6 +46,16 @@ export interface CompanyInterface extends ApiDataInterface {
    */
   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;

package/src/features/company/data/company.service.ts

@@ -1,4 +1,5 @@
 import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef } from "../../../core";
+import { CREDIT_WARNING_DISMISS_SEGMENT } from "../../billing/data/credit-warning";
 import { CompanyInput, CompanyInterface } from "./company.interface";
 
 export class CompanyService extends AbstractService {
@@ -82,4 +83,20 @@ export class CompanyService extends AbstractService {
       input: params,
     });
   }
+
+  /**
+   * Dismisses this period's credit warning for the company. The request has no
+   * body: the server stamps the dismissal itself and answers 204.
+   */
+  static async dismissCreditWarning(params: { companyId: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.Company,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.Company,
+        id: params.companyId,
+        childEndpoint: CREDIT_WARNING_DISMISS_SEGMENT,
+      }).generate(),
+    });
+  }
 }

package/src/features/company/data/company.spec.ts

@@ -38,3 +38,32 @@ describe("Company.aiEnabled", () => {
     expect(company.aiEnabled).toBe(true);
   });
 });
+
+describe("Company credit-warning fields", () => {
+  it("rehydrates credit-warning fields", () => {
+    const company = new Company().rehydrate({
+      jsonApi: {
+        attributes: {
+          creditsGrantedThisPeriod: 200,
+          creditWarningSentAt: "2026-10-25T10:00:00.000Z",
+          creditWarningOffer: "pack",
+        },
+      },
+    } as any);
+
+    expect(company.creditsGrantedThisPeriod).toBe(200);
+    expect(company.creditWarningSentAt).toBeInstanceOf(Date);
+    expect(company.creditWarningSentAt?.toISOString()).toBe("2026-10-25T10:00:00.000Z");
+    expect(company.creditWarningDismissedAt).toBeUndefined();
+    expect(company.creditWarningOffer).toBe("pack");
+  });
+
+  it("leaves every credit-warning getter undefined when the attributes are absent", () => {
+    const company = new Company().rehydrate({ jsonApi: { attributes: {} } } as any);
+
+    expect(company.creditsGrantedThisPeriod).toBeUndefined();
+    expect(company.creditWarningSentAt).toBeUndefined();
+    expect(company.creditWarningDismissedAt).toBeUndefined();
+    expect(company.creditWarningOffer).toBeUndefined();
+  });
+});

package/src/features/company/data/company.ts

@@ -1,6 +1,7 @@
 import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
 import { FeatureInterface } from "../../feature";
 import { ModuleInterface } from "../../module";
+import type { CreditWarningOffer } from "../../billing/data/credit-warning";
 import { CompanyInput, CompanyInterface } from "./company.interface";
 
 export class Company extends AbstractApiData implements CompanyInterface {
@@ -16,6 +17,11 @@ export class Company extends AbstractApiData implements CompanyInterface {
   private _availableExtraCredits: number = 0;
   private _aiEnabled?: boolean;
 
+  private _creditsGrantedThisPeriod?: number;
+  private _creditWarningSentAt?: Date;
+  private _creditWarningDismissedAt?: Date;
+  private _creditWarningOffer?: CreditWarningOffer;
+
   private _features?: FeatureInterface[];
   private _modules?: ModuleInterface[];
 
@@ -63,6 +69,22 @@ export class Company extends AbstractApiData implements CompanyInterface {
     return this._aiEnabled ?? true;
   }
 
+  get creditsGrantedThisPeriod(): number | undefined {
+    return this._creditsGrantedThisPeriod;
+  }
+
+  get creditWarningSentAt(): Date | undefined {
+    return this._creditWarningSentAt;
+  }
+
+  get creditWarningDismissedAt(): Date | undefined {
+    return this._creditWarningDismissedAt;
+  }
+
+  get creditWarningOffer(): CreditWarningOffer | undefined {
+    return this._creditWarningOffer;
+  }
+
   get features(): FeatureInterface[] {
     return this._features ?? [];
   }
@@ -130,6 +152,15 @@ export class Company extends AbstractApiData implements CompanyInterface {
     this._availableExtraCredits = data.jsonApi.attributes.availableExtraCredits ?? 0;
     this._aiEnabled = data.jsonApi.attributes.aiEnabled ?? true;
 
+    this._creditsGrantedThisPeriod = data.jsonApi.attributes.creditsGrantedThisPeriod ?? undefined;
+    this._creditWarningSentAt = data.jsonApi.attributes.creditWarningSentAt
+      ? new Date(data.jsonApi.attributes.creditWarningSentAt)
+      : undefined;
+    this._creditWarningDismissedAt = data.jsonApi.attributes.creditWarningDismissedAt
+      ? new Date(data.jsonApi.attributes.creditWarningDismissedAt)
+      : undefined;
+    this._creditWarningOffer = data.jsonApi.attributes.creditWarningOffer ?? undefined;
+
     this._legal_address = data.jsonApi.attributes.legal_address;
     this._street_number = data.jsonApi.attributes.street_number;
     this._street = data.jsonApi.attributes.street;