@carlonicora/nextjs-jsonapi 5.4.0 → 5.6.0

package/src/features/billing/stripe-coupon/data/__tests__/stripe-coupon-models.spec.ts

@@ -0,0 +1,114 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { DataClassRegistry } from "../../../../../core/registry/DataClassRegistry";
+import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
+import { ModuleFactory, ModuleWithPermissions } from "../../../../../permissions/types";
+import { StripeCouponCodeModule } from "../../stripe-coupon-code.module";
+import { StripeCouponModule } from "../../stripe-coupon.module";
+import { StripeCouponOfferModule } from "../../stripe-coupon-offer.module";
+import { StripeCoupon } from "../stripe-coupon";
+import { StripeCouponCode } from "../stripe-coupon-code";
+
+// createJsonApi reads Modules.X.name (resolved lazily via ModuleRegistry), and
+// _readIncluded rehydrates through the registered model, so the modules must be
+// registered first — mirrors email-automation-models.spec.
+const moduleFactory: ModuleFactory = (params) =>
+  ({
+    pageUrl: params.pageUrl,
+    name: params.name,
+    model: params.model,
+  }) as ModuleWithPermissions;
+
+beforeAll(() => {
+  const coupon = StripeCouponModule(moduleFactory);
+  const code = StripeCouponCodeModule(moduleFactory);
+  ModuleRegistry.register("StripeCoupon", coupon);
+  ModuleRegistry.register("StripeCouponCode", code);
+  ModuleRegistry.register("StripeCouponOffer", StripeCouponOfferModule(moduleFactory));
+  // The included code is rehydrated through the class registry (normally filled by bootstrap()).
+  DataClassRegistry.registerObjectClass(coupon, StripeCoupon);
+  DataClassRegistry.registerObjectClass(code, StripeCouponCode);
+});
+
+describe("stripe coupon models", () => {
+  it("rehydrates redeemBy into a Date and reads the included codes", () => {
+    const coupon = new StripeCoupon().rehydrate({
+      jsonApi: {
+        id: "co-1",
+        type: "stripe-coupons",
+        attributes: {
+          stripeCouponId: "co_1",
+          name: "Founding GM",
+          discountType: "percent_off",
+          percentOff: 20,
+          duration: "forever",
+          redeemBy: "2027-01-01T00:00:00.000Z",
+          maxRedemptions: 50,
+          timesRedeemed: 13,
+          valid: true,
+        },
+        relationships: { codes: { data: [{ type: "stripe-coupon-codes", id: "cc-1" }] } },
+      },
+      included: [
+        {
+          id: "cc-1",
+          type: "stripe-coupon-codes",
+          attributes: {
+            stripePromotionCodeId: "promo_1",
+            code: "FOUNDER",
+            active: true,
+            automatic: true,
+            expiresAt: "2027-02-01T00:00:00.000Z",
+            timesRedeemed: 13,
+          },
+        },
+      ],
+    } as any);
+
+    expect(coupon.redeemBy).toBeInstanceOf(Date);
+    expect(coupon.redeemBy?.toISOString()).toBe("2027-01-01T00:00:00.000Z");
+    expect(coupon.codes.length).toBe(1);
+    expect(coupon.codes[0].code).toBe("FOUNDER");
+    expect(coupon.codes[0].expiresAt).toBeInstanceOf(Date);
+    expect(coupon.timesRedeemed).toBe(13);
+  });
+
+  it("serialises the datetimes of the coupon and its first code as ISO strings", () => {
+    const body = new StripeCoupon().createJsonApi({
+      id: "co-1",
+      name: "Founding GM",
+      discountType: "percent_off",
+      percentOff: 20,
+      duration: "forever",
+      productIds: ["p1"],
+      redeemBy: new Date("2027-01-01T00:00:00.000Z"),
+      maxRedemptions: 50,
+      firstCode: { code: "FOUNDER", automatic: true, expiresAt: new Date("2027-02-01T00:00:00.000Z") },
+    });
+
+    expect(body.data.type).toBe("stripe-coupons");
+    expect(body.data.attributes.redeemBy).toBe("2027-01-01T00:00:00.000Z");
+    expect(body.data.attributes.firstCode.expiresAt).toBe("2027-02-01T00:00:00.000Z");
+    expect(body.data.attributes.firstCode.automatic).toBe(true);
+    expect(body.data.attributes.productIds).toEqual(["p1"]);
+    expect("amountOff" in body.data.attributes).toBe(false);
+  });
+
+  it("builds the rename body with the name only", () => {
+    expect(new StripeCoupon().createRenameJsonApi({ id: "co-1", name: "Renamed" })).toEqual({
+      data: { type: "stripe-coupons", id: "co-1", attributes: { name: "Renamed" } },
+    });
+  });
+
+  it("writes the code's coupon relationship", () => {
+    const body = new StripeCouponCode().createJsonApi({ id: "c1", couponId: "co-1", code: "SPRING" });
+    expect(body.data.type).toBe("stripe-coupon-codes");
+    expect(body.data.attributes).toEqual({ code: "SPRING" });
+    expect(body.data.relationships.coupon).toEqual({ data: { type: "stripe-coupons", id: "co-1" } });
+  });
+
+  it("builds the flags body with only the flags that are set", () => {
+    const body = new StripeCouponCode().createFlagsJsonApi({ id: "c1", automatic: true });
+    expect(body).toEqual({ data: { type: "stripe-coupon-codes", id: "c1", attributes: { automatic: true } } });
+    expect("active" in body.data.attributes).toBe(false);
+  });
+});

package/src/features/billing/stripe-coupon/data/index.ts

@@ -0,0 +1,10 @@
+export * from "./stripe-coupon";
+export * from "./stripe-coupon.fields";
+export * from "./stripe-coupon.interface";
+export * from "./stripe-coupon.service";
+export * from "./stripe-coupon-code";
+export * from "./stripe-coupon-code.fields";
+export * from "./stripe-coupon-code.interface";
+export * from "./stripe-coupon-code.service";
+export * from "./stripe-coupon-offer";
+export * from "./stripe-coupon-offer.interface";

package/src/features/billing/stripe-coupon/data/stripe-coupon-code.fields.ts

@@ -0,0 +1,8 @@
+export enum StripeCouponCodeFields {
+  code = "code",
+  places = "places",
+  expiresAt = "expiresAt",
+  automatic = "automatic",
+  status = "status",
+  actions = "actions",
+}

package/src/features/billing/stripe-coupon/data/stripe-coupon-code.interface.ts

@@ -0,0 +1,44 @@
+import { ApiDataInterface } from "../../../../core";
+import { StripeCouponInterface } from "./stripe-coupon.interface";
+
+// ============================================================================
+// Stripe Coupon Code Interfaces (a customer-facing promotion code of a coupon)
+// ============================================================================
+
+export interface StripeCouponCodeInterface extends ApiDataInterface {
+  get stripePromotionCodeId(): string;
+  get code(): string;
+  get active(): boolean;
+  get automatic(): boolean;
+  get firstTimeTransaction(): boolean;
+  get minimumAmount(): number | undefined; // minor units
+  get minimumAmountCurrency(): string | undefined;
+  get stripeCustomerId(): string | undefined;
+  get expiresAt(): Date | undefined;
+  get maxRedemptions(): number | undefined;
+  get timesRedeemed(): number;
+  get coupon(): StripeCouponInterface | undefined;
+}
+
+// ============================================================================
+// Stripe Coupon Code Input DTOs
+// ============================================================================
+
+export type StripeCouponCodeInput = {
+  id: string;
+  couponId: string;
+  code?: string;
+  firstTimeTransaction?: boolean;
+  minimumAmount?: number;
+  minimumAmountCurrency?: string;
+  stripeCustomerId?: string;
+  expiresAt?: Date;
+  maxRedemptions?: number;
+  automatic?: boolean;
+};
+
+export type StripeCouponCodeFlagsInput = {
+  id: string;
+  active?: boolean;
+  automatic?: boolean;
+};

package/src/features/billing/stripe-coupon/data/stripe-coupon-code.service.ts

@@ -0,0 +1,92 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef, PreviousRef } from "../../../../core";
+import { STRIPE_COUPON_CODE_AUTOMATIC_SEGMENT } from "../stripe-coupon-code.module";
+import { StripeCouponCode } from "./stripe-coupon-code";
+import {
+  StripeCouponCodeFlagsInput,
+  StripeCouponCodeInput,
+  StripeCouponCodeInterface,
+} from "./stripe-coupon-code.interface";
+
+/**
+ * Billing service for the customer-facing codes of a coupon
+ */
+export class StripeCouponCodeService extends AbstractService {
+  /**
+   * List the codes of a coupon (admin)
+   */
+  static async listByCoupon(params: {
+    couponId: string;
+    next?: NextRef;
+    prev?: PreviousRef;
+  }): Promise<StripeCouponCodeInterface[]> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeCoupon,
+      id: params.couponId,
+      childEndpoint: Modules.StripeCouponCode,
+    });
+
+    return this.callApi({
+      type: Modules.StripeCouponCode,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      next: params.next,
+      previous: params.prev,
+    });
+  }
+
+  /**
+   * Create a code on an existing coupon (admin)
+   */
+  static async createCode(params: StripeCouponCodeInput): Promise<StripeCouponCodeInterface> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeCouponCode,
+    });
+
+    return this.callApi<StripeCouponCodeInterface>({
+      type: Modules.StripeCouponCode,
+      method: HttpMethod.POST,
+      endpoint: endpoint.generate(),
+      input: params,
+    });
+  }
+
+  /**
+   * Switch "Apply automatically" and / or deactivate / reactivate a code (admin)
+   */
+  static async updateFlags(params: StripeCouponCodeFlagsInput): Promise<StripeCouponCodeInterface> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeCouponCode,
+      id: params.id,
+    });
+
+    return this.callApi<StripeCouponCodeInterface>({
+      type: Modules.StripeCouponCode,
+      method: HttpMethod.PATCH,
+      endpoint: endpoint.generate(),
+      input: new StripeCouponCode().createFlagsJsonApi(params),
+      overridesJsonApiCreation: true,
+    });
+  }
+
+  /**
+   * The code the server would apply automatically for this price at a first
+   * payment, or null when none applies (logged-in company administrator)
+   */
+  static async findAutomatic(params: { priceId: string }): Promise<StripeCouponCodeInterface | null> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeCouponCode,
+      id: STRIPE_COUPON_CODE_AUTOMATIC_SEGMENT,
+    });
+    endpoint.addAdditionalParam("priceId", params.priceId);
+
+    const codes = await this.callApi<StripeCouponCodeInterface[]>({
+      type: Modules.StripeCouponCode,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      // A failed lookup must reach the wizard, which then refuses to show full price as the truth
+      suppressGlobalError: true,
+    });
+
+    return codes?.[0] ?? null;
+  }
+}

package/src/features/billing/stripe-coupon/data/stripe-coupon-code.ts

@@ -0,0 +1,132 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../../core";
+import {
+  StripeCouponCodeFlagsInput,
+  StripeCouponCodeInput,
+  StripeCouponCodeInterface,
+} from "./stripe-coupon-code.interface";
+import { StripeCouponInterface } from "./stripe-coupon.interface";
+import { StripeCoupon } from "./stripe-coupon";
+
+export class StripeCouponCode extends AbstractApiData implements StripeCouponCodeInterface {
+  private _stripePromotionCodeId?: string;
+  private _code: string = "";
+  private _active: boolean = true;
+  private _automatic: boolean = false;
+  private _firstTimeTransaction: boolean = false;
+  private _minimumAmount?: number;
+  private _minimumAmountCurrency?: string;
+  private _stripeCustomerId?: string;
+  private _expiresAt?: Date;
+  private _maxRedemptions?: number;
+  private _timesRedeemed: number = 0;
+  private _coupon?: StripeCouponInterface;
+
+  get stripePromotionCodeId(): string {
+    if (!this._stripePromotionCodeId) throw new Error("stripePromotionCodeId is not defined");
+    return this._stripePromotionCodeId;
+  }
+
+  get code(): string {
+    return this._code;
+  }
+
+  get active(): boolean {
+    return this._active;
+  }
+
+  get automatic(): boolean {
+    return this._automatic;
+  }
+
+  get firstTimeTransaction(): boolean {
+    return this._firstTimeTransaction;
+  }
+
+  get minimumAmount(): number | undefined {
+    return this._minimumAmount;
+  }
+
+  get minimumAmountCurrency(): string | undefined {
+    return this._minimumAmountCurrency;
+  }
+
+  get stripeCustomerId(): string | undefined {
+    return this._stripeCustomerId;
+  }
+
+  get expiresAt(): Date | undefined {
+    return this._expiresAt;
+  }
+
+  get maxRedemptions(): number | undefined {
+    return this._maxRedemptions;
+  }
+
+  get timesRedeemed(): number {
+    return this._timesRedeemed;
+  }
+
+  get coupon(): StripeCouponInterface | undefined {
+    return this._coupon;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes;
+
+    this._stripePromotionCodeId = attributes.stripePromotionCodeId;
+    this._code = attributes.code ?? "";
+    this._active = attributes.active ?? true;
+    this._automatic = attributes.automatic ?? false;
+    this._firstTimeTransaction = attributes.firstTimeTransaction ?? false;
+    this._minimumAmount = attributes.minimumAmount ?? undefined;
+    this._minimumAmountCurrency = attributes.minimumAmountCurrency ?? undefined;
+    this._stripeCustomerId = attributes.stripeCustomerId ?? undefined;
+    this._expiresAt = attributes.expiresAt ? new Date(attributes.expiresAt) : undefined;
+    this._maxRedemptions = attributes.maxRedemptions ?? undefined;
+    this._timesRedeemed = attributes.timesRedeemed ?? 0;
+
+    this._coupon = this._readIncluded(data, "coupon", Modules.StripeCoupon) as StripeCouponInterface | undefined;
+
+    return this;
+  }
+
+  createJsonApi(data: StripeCouponCodeInput): any {
+    const { id, couponId, ...code } = data;
+
+    return {
+      data: {
+        type: Modules.StripeCouponCode.name,
+        id,
+        attributes: StripeCoupon.codeAttributes(code),
+        relationships: {
+          coupon: {
+            data: {
+              type: Modules.StripeCoupon.name,
+              id: couponId,
+            },
+          },
+        },
+      },
+    };
+  }
+
+  /**
+   * PATCH body for the flags a code can still change after creation.
+   * Only the flags that are set are sent, so switching one never touches the other.
+   */
+  createFlagsJsonApi(data: StripeCouponCodeFlagsInput): any {
+    const attributes: Record<string, boolean> = {};
+    if (data.active !== undefined) attributes.active = data.active;
+    if (data.automatic !== undefined) attributes.automatic = data.automatic;
+
+    return {
+      data: {
+        type: Modules.StripeCouponCode.name,
+        id: data.id,
+        attributes,
+      },
+    };
+  }
+}

package/src/features/billing/stripe-coupon/data/stripe-coupon-offer.interface.ts

@@ -0,0 +1,17 @@
+import { ApiDataInterface } from "../../../../core";
+import { StripeCouponDiscountType, StripeCouponDurationType } from "./stripe-coupon.interface";
+
+// ============================================================================
+// Stripe Coupon Offer Interface (public, synthetic: the automatic code's places left)
+// ============================================================================
+
+export interface StripeCouponOfferInterface extends ApiDataInterface {
+  get discountType(): StripeCouponDiscountType;
+  get percentOff(): number | undefined;
+  get amountOff(): number | undefined; // minor units
+  get currency(): string | undefined;
+  get duration(): StripeCouponDurationType;
+  get durationInMonths(): number | undefined;
+  get placesLeft(): number;
+  get placesTotal(): number;
+}

package/src/features/billing/stripe-coupon/data/stripe-coupon-offer.ts

@@ -0,0 +1,70 @@
+import { AbstractApiData, JsonApiHydratedDataInterface } from "../../../../core";
+import { StripeCouponOfferInterface } from "./stripe-coupon-offer.interface";
+import { StripeCouponDiscountType, StripeCouponDurationType } from "./stripe-coupon.interface";
+
+/** Read-only public resource: never created or updated from the frontend. */
+export class StripeCouponOffer extends AbstractApiData implements StripeCouponOfferInterface {
+  private _discountType?: StripeCouponDiscountType;
+  private _percentOff?: number;
+  private _amountOff?: number;
+  private _currency?: string;
+  private _duration?: StripeCouponDurationType;
+  private _durationInMonths?: number;
+  private _placesLeft: number = 0;
+  private _placesTotal: number = 0;
+
+  get discountType(): StripeCouponDiscountType {
+    if (!this._discountType) throw new Error("discountType is not defined");
+    return this._discountType;
+  }
+
+  get percentOff(): number | undefined {
+    return this._percentOff;
+  }
+
+  get amountOff(): number | undefined {
+    return this._amountOff;
+  }
+
+  get currency(): string | undefined {
+    return this._currency;
+  }
+
+  get duration(): StripeCouponDurationType {
+    if (!this._duration) throw new Error("duration is not defined");
+    return this._duration;
+  }
+
+  get durationInMonths(): number | undefined {
+    return this._durationInMonths;
+  }
+
+  get placesLeft(): number {
+    return this._placesLeft;
+  }
+
+  get placesTotal(): number {
+    return this._placesTotal;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes;
+
+    this._discountType = attributes.discountType;
+    this._percentOff = attributes.percentOff ?? undefined;
+    this._amountOff = attributes.amountOff ?? undefined;
+    this._currency = attributes.currency ?? undefined;
+    this._duration = attributes.duration;
+    this._durationInMonths = attributes.durationInMonths ?? undefined;
+    this._placesLeft = attributes.placesLeft ?? 0;
+    this._placesTotal = attributes.placesTotal ?? 0;
+
+    return this;
+  }
+
+  createJsonApi(_data?: any): any {
+    throw new Error("StripeCouponOffer is declared by the API and is read-only");
+  }
+}

package/src/features/billing/stripe-coupon/data/stripe-coupon.fields.ts

@@ -0,0 +1,7 @@
+export enum StripeCouponFields {
+  name = "name",
+  discount = "discount",
+  places = "places",
+  codes = "codes",
+  status = "status",
+}

package/src/features/billing/stripe-coupon/data/stripe-coupon.interface.ts

@@ -0,0 +1,51 @@
+import { ApiDataInterface } from "../../../../core";
+import { StripeCouponCodeInput, StripeCouponCodeInterface } from "./stripe-coupon-code.interface";
+
+// ============================================================================
+// Stripe Coupon Interfaces
+// ============================================================================
+
+export type StripeCouponDiscountType = "percent_off" | "amount_off";
+export type StripeCouponDurationType = "once" | "repeating" | "forever";
+
+export interface StripeCouponInterface extends ApiDataInterface {
+  get stripeCouponId(): string;
+  get name(): string;
+  get discountType(): StripeCouponDiscountType;
+  get percentOff(): number | undefined;
+  get amountOff(): number | undefined; // minor units (cents)
+  get currency(): string | undefined;
+  get duration(): StripeCouponDurationType;
+  get durationInMonths(): number | undefined;
+  get stripeProductIds(): string[]; // empty = every product
+  get redeemBy(): Date | undefined;
+  get maxRedemptions(): number | undefined;
+  get timesRedeemed(): number;
+  get valid(): boolean;
+  get codes(): StripeCouponCodeInterface[];
+}
+
+// ============================================================================
+// Stripe Coupon Input DTOs
+// ============================================================================
+
+export type StripeCouponInput = {
+  id: string;
+  name: string;
+  stripeCouponId?: string;
+  discountType: StripeCouponDiscountType;
+  percentOff?: number;
+  amountOff?: number;
+  currency?: string;
+  duration: StripeCouponDurationType;
+  durationInMonths?: number;
+  productIds?: string[]; // our StripeProduct ids
+  redeemBy?: Date;
+  maxRedemptions?: number;
+  firstCode: Omit<StripeCouponCodeInput, "id" | "couponId">;
+};
+
+export type StripeCouponRenameInput = {
+  id: string;
+  name: string;
+};

package/src/features/billing/stripe-coupon/data/stripe-coupon.service.ts

@@ -0,0 +1,93 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef, PreviousRef } from "../../../../core";
+import { STRIPE_COUPON_REFRESH_SEGMENT } from "../stripe-coupon.module";
+import { StripeCoupon } from "./stripe-coupon";
+import { StripeCouponInput, StripeCouponInterface, StripeCouponRenameInput } from "./stripe-coupon.interface";
+
+/**
+ * Admin billing service for managing coupons
+ */
+export class StripeCouponService extends AbstractService {
+  /**
+   * List all coupons with their codes (admin)
+   */
+  static async listCoupons(params?: { next?: NextRef; prev?: PreviousRef }): Promise<StripeCouponInterface[]> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeCoupon,
+    });
+
+    return this.callApi({
+      type: Modules.StripeCoupon,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      next: params?.next,
+      previous: params?.prev,
+    });
+  }
+
+  /**
+   * Get a specific coupon by ID (admin)
+   */
+  static async getCoupon(params: { id: string }): Promise<StripeCouponInterface> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeCoupon,
+      id: params.id,
+    });
+
+    return this.callApi<StripeCouponInterface>({
+      type: Modules.StripeCoupon,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  /**
+   * Create a coupon and its first code (admin)
+   */
+  static async createCoupon(params: StripeCouponInput): Promise<StripeCouponInterface> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeCoupon,
+    });
+
+    return this.callApi<StripeCouponInterface>({
+      type: Modules.StripeCoupon,
+      method: HttpMethod.POST,
+      endpoint: endpoint.generate(),
+      input: params,
+    });
+  }
+
+  /**
+   * Rename a coupon (admin). The only coupon field Stripe allows to change.
+   */
+  static async renameCoupon(params: StripeCouponRenameInput): Promise<StripeCouponInterface> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeCoupon,
+      id: params.id,
+    });
+
+    return this.callApi<StripeCouponInterface>({
+      type: Modules.StripeCoupon,
+      method: HttpMethod.PATCH,
+      endpoint: endpoint.generate(),
+      input: new StripeCoupon().createRenameJsonApi(params),
+      overridesJsonApiCreation: true,
+    });
+  }
+
+  /**
+   * Re-read the coupon and its codes from Stripe and store the counts (admin)
+   */
+  static async refreshCounts(params: { id: string }): Promise<StripeCouponInterface> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeCoupon,
+      id: params.id,
+      childEndpoint: STRIPE_COUPON_REFRESH_SEGMENT,
+    });
+
+    return this.callApi<StripeCouponInterface>({
+      type: Modules.StripeCoupon,
+      method: HttpMethod.POST,
+      endpoint: endpoint.generate(),
+    });
+  }
+}