@carlonicora/nextjs-jsonapi 5.4.0 → 5.6.0

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

@@ -0,0 +1,165 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../../core";
+import { StripeCouponCodeInput, StripeCouponCodeInterface } from "./stripe-coupon-code.interface";
+import {
+  StripeCouponDiscountType,
+  StripeCouponDurationType,
+  StripeCouponInput,
+  StripeCouponInterface,
+  StripeCouponRenameInput,
+} from "./stripe-coupon.interface";
+
+export class StripeCoupon extends AbstractApiData implements StripeCouponInterface {
+  private _stripeCouponId?: string;
+  private _name?: string;
+  private _discountType?: StripeCouponDiscountType;
+  private _percentOff?: number;
+  private _amountOff?: number;
+  private _currency?: string;
+  private _duration?: StripeCouponDurationType;
+  private _durationInMonths?: number;
+  private _stripeProductIds: string[] = [];
+  private _redeemBy?: Date;
+  private _maxRedemptions?: number;
+  private _timesRedeemed: number = 0;
+  private _valid: boolean = true;
+  private _codes: StripeCouponCodeInterface[] = [];
+
+  get stripeCouponId(): string {
+    if (!this._stripeCouponId) throw new Error("stripeCouponId is not defined");
+    return this._stripeCouponId;
+  }
+
+  get name(): string {
+    return this._name ?? "";
+  }
+
+  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 stripeProductIds(): string[] {
+    return this._stripeProductIds;
+  }
+
+  get redeemBy(): Date | undefined {
+    return this._redeemBy;
+  }
+
+  get maxRedemptions(): number | undefined {
+    return this._maxRedemptions;
+  }
+
+  get timesRedeemed(): number {
+    return this._timesRedeemed;
+  }
+
+  get valid(): boolean {
+    return this._valid;
+  }
+
+  get codes(): StripeCouponCodeInterface[] {
+    return this._codes;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes;
+
+    this._stripeCouponId = attributes.stripeCouponId;
+    this._name = attributes.name;
+    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._stripeProductIds = attributes.stripeProductIds ?? [];
+    this._redeemBy = attributes.redeemBy ? new Date(attributes.redeemBy) : undefined;
+    this._maxRedemptions = attributes.maxRedemptions ?? undefined;
+    this._timesRedeemed = attributes.timesRedeemed ?? 0;
+    this._valid = attributes.valid ?? true;
+
+    this._codes =
+      (this._readIncluded(data, "codes", Modules.StripeCouponCode) as StripeCouponCodeInterface[] | undefined) ?? [];
+
+    return this;
+  }
+
+  createJsonApi(data: StripeCouponInput): any {
+    const response: any = {
+      data: {
+        type: Modules.StripeCoupon.name,
+        id: data.id,
+        attributes: {
+          name: data.name,
+          discountType: data.discountType,
+          duration: data.duration,
+          firstCode: StripeCoupon.codeAttributes(data.firstCode),
+        },
+      },
+    };
+
+    const attributes = response.data.attributes;
+    if (data.stripeCouponId) attributes.stripeCouponId = data.stripeCouponId;
+    if (data.percentOff !== undefined) attributes.percentOff = data.percentOff;
+    if (data.amountOff !== undefined) attributes.amountOff = data.amountOff;
+    if (data.currency) attributes.currency = data.currency;
+    if (data.durationInMonths !== undefined) attributes.durationInMonths = data.durationInMonths;
+    if (data.productIds && data.productIds.length > 0) attributes.productIds = data.productIds;
+    if (data.redeemBy !== undefined) attributes.redeemBy = data.redeemBy.toISOString();
+    if (data.maxRedemptions !== undefined) attributes.maxRedemptions = data.maxRedemptions;
+
+    return response;
+  }
+
+  /**
+   * Rename is the only change Stripe allows on a coupon after creation.
+   * Dedicated method so the service never needs a generic override.
+   */
+  createRenameJsonApi(data: StripeCouponRenameInput): any {
+    return {
+      data: {
+        type: Modules.StripeCoupon.name,
+        id: data.id,
+        attributes: { name: data.name },
+      },
+    };
+  }
+
+  /** Attributes of a code, shared by the coupon's first code and StripeCouponCode.createJsonApi. */
+  static codeAttributes(code: Omit<StripeCouponCodeInput, "id" | "couponId">): Record<string, any> {
+    const attributes: Record<string, any> = {};
+    if (code.code) attributes.code = code.code;
+    if (code.firstTimeTransaction !== undefined) attributes.firstTimeTransaction = code.firstTimeTransaction;
+    if (code.minimumAmount !== undefined) attributes.minimumAmount = code.minimumAmount;
+    if (code.minimumAmountCurrency) attributes.minimumAmountCurrency = code.minimumAmountCurrency;
+    if (code.stripeCustomerId) attributes.stripeCustomerId = code.stripeCustomerId;
+    if (code.expiresAt !== undefined) attributes.expiresAt = code.expiresAt.toISOString();
+    if (code.maxRedemptions !== undefined) attributes.maxRedemptions = code.maxRedemptions;
+    if (code.automatic !== undefined) attributes.automatic = code.automatic;
+    return attributes;
+  }
+}

package/src/features/billing/stripe-coupon/hooks/useStripeCouponCodeTableStructure.tsx

@@ -0,0 +1,154 @@
+"use client";
+
+import { ColumnDef } from "@tanstack/react-table";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+import { Badge } from "../../../../shadcnui";
+import { registerTableGenerator, TableContent, UseTableStructureHook } from "../../../../hooks";
+import { formatDate, useBillingFormatOptions } from "../../components/utils";
+import { useCouponContext } from "../../contexts/CouponContext";
+import { CouponCodeActions } from "../components/widgets/CouponCodeActions";
+import { StripeCouponCodeFields } from "../data/stripe-coupon-code.fields";
+import { StripeCouponCodeInterface } from "../data/stripe-coupon-code.interface";
+import { StripeCouponInterface } from "../data/stripe-coupon.interface";
+import { couponPlacesLeft } from "../utils/coupon-places";
+
+export type CouponCodeStatus = "active" | "inactive" | "expired" | "used_up";
+
+/**
+ * Expired and used-up codes are dead for good (Stripe never revives them), so
+ * they win over a plain inactive flag. Places follow the same rule as the
+ * backend: the smaller of the code's and the coupon's remaining limits.
+ */
+export function couponCodeStatus(code: StripeCouponCodeInterface, coupon?: StripeCouponInterface): CouponCodeStatus {
+  if (code.expiresAt && code.expiresAt.getTime() <= Date.now()) return "expired";
+  const left = couponPlacesLeft(code, coupon ?? { maxRedemptions: undefined, timesRedeemed: 0 });
+  if (left === 0) return "used_up";
+  return code.active ? "active" : "inactive";
+}
+
+const STATUS_VARIANT: Record<CouponCodeStatus, "softGreen" | "softGray" | "softAmber" | "softRed"> = {
+  active: "softGreen",
+  inactive: "softGray",
+  expired: "softAmber",
+  used_up: "softRed",
+};
+
+export const useStripeCouponCodeTableStructure: UseTableStructureHook<
+  StripeCouponCodeInterface,
+  StripeCouponCodeFields
+> = (params) => {
+  const t = useTranslations();
+  const fmt = useBillingFormatOptions();
+  // The codes list is mounted on the coupon's own page, so the coupon whose
+  // limits share the places is the context's, not whatever the code includes.
+  const { coupon } = useCouponContext();
+
+  const tableData = useMemo(() => {
+    return params.data.map((code: StripeCouponCodeInterface) => {
+      const entry: TableContent<StripeCouponCodeInterface> = { jsonApiData: code };
+      params.fields.forEach((field) => {
+        entry[field] = (code as any)[field as keyof StripeCouponCodeInterface];
+      });
+      return entry;
+    });
+  }, [params.data, params.fields]);
+
+  const fieldColumnMap: Partial<Record<StripeCouponCodeFields, () => any>> = {
+    [StripeCouponCodeFields.code]: () => ({
+      id: "code",
+      accessorKey: "code",
+      header: t("billing.admin.coupons.fields.code"),
+      cell: ({ row }: { row: TableContent<StripeCouponCodeInterface> }) => {
+        const code: StripeCouponCodeInterface = row.original.jsonApiData;
+        return <span className="text-xs font-medium">{code.code}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [StripeCouponCodeFields.places]: () => ({
+      id: "places",
+      accessorKey: "places",
+      header: t("billing.admin.coupons.fields.places"),
+      cell: ({ row }: { row: TableContent<StripeCouponCodeInterface> }) => {
+        const code: StripeCouponCodeInterface = row.original.jsonApiData;
+        // Typography role 15 (numeric): tabular-nums, end-aligned.
+        return (
+          <span className="block text-xs tabular-nums text-end">
+            {code.maxRedemptions !== undefined
+              ? t("billing.admin.coupons.places.limited", {
+                  used: String(code.timesRedeemed),
+                  limit: String(code.maxRedemptions),
+                })
+              : t("billing.admin.coupons.places.unlimited", { used: String(code.timesRedeemed) })}
+          </span>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [StripeCouponCodeFields.expiresAt]: () => ({
+      id: "expiresAt",
+      accessorKey: "expiresAt",
+      header: t("billing.admin.coupons.fields.expiresAt"),
+      cell: ({ row }: { row: TableContent<StripeCouponCodeInterface> }) => {
+        const code: StripeCouponCodeInterface = row.original.jsonApiData;
+        return (
+          <span className="text-xs tabular-nums">
+            {code.expiresAt ? formatDate(code.expiresAt, fmt) : t("billing.admin.coupons.codes.never")}
+          </span>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [StripeCouponCodeFields.automatic]: () => ({
+      id: "automatic",
+      accessorKey: "automatic",
+      header: t("billing.admin.coupons.fields.automatic"),
+      cell: ({ row }: { row: TableContent<StripeCouponCodeInterface> }) => {
+        const code: StripeCouponCodeInterface = row.original.jsonApiData;
+        return code.automatic ? (
+          <Badge variant="softBlue">{t("billing.admin.coupons.codes.automatic")}</Badge>
+        ) : (
+          <span className="text-muted-foreground text-xs">—</span>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [StripeCouponCodeFields.status]: () => ({
+      id: "status",
+      accessorKey: "status",
+      header: t("billing.admin.coupons.fields.status"),
+      cell: ({ row }: { row: TableContent<StripeCouponCodeInterface> }) => {
+        const code: StripeCouponCodeInterface = row.original.jsonApiData;
+        const status = couponCodeStatus(code, code.coupon ?? coupon);
+        return <Badge variant={STATUS_VARIANT[status]}>{t(`billing.admin.coupons.codes.status.${status}`)}</Badge>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [StripeCouponCodeFields.actions]: () => ({
+      id: "actions",
+      accessorKey: "actions",
+      header: "",
+      cell: ({ row }: { row: TableContent<StripeCouponCodeInterface> }) => {
+        const code: StripeCouponCodeInterface = row.original.jsonApiData;
+        return <CouponCodeActions code={code} status={couponCodeStatus(code, code.coupon ?? coupon)} />;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+  };
+
+  const columns = useMemo(() => {
+    return params.fields.map((field) => fieldColumnMap[field]?.()).filter((col) => col !== undefined) as ColumnDef<
+      TableContent<StripeCouponCodeInterface>
+    >[];
+  }, [params.fields, fieldColumnMap, t, coupon]);
+
+  return useMemo(() => ({ data: tableData, columns: columns }), [tableData, columns]);
+};
+
+registerTableGenerator("stripe-coupon-codes", useStripeCouponCodeTableStructure);

package/src/features/billing/stripe-coupon/hooks/useStripeCouponTableStructure.tsx

@@ -0,0 +1,113 @@
+"use client";
+
+import { ColumnDef } from "@tanstack/react-table";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+import { Badge, Link } from "../../../../shadcnui";
+import { Modules } from "../../../../core";
+import { registerTableGenerator, TableContent, usePageUrlGenerator, UseTableStructureHook } from "../../../../hooks";
+import { useBillingFormatOptions } from "../../components/utils";
+import { StripeCouponFields } from "../data/stripe-coupon.fields";
+import { StripeCouponInterface } from "../data/stripe-coupon.interface";
+import { formatCouponDiscount } from "../utils/format-coupon-discount";
+
+export const useStripeCouponTableStructure: UseTableStructureHook<StripeCouponInterface, StripeCouponFields> = (
+  params,
+) => {
+  const t = useTranslations();
+  const fmt = useBillingFormatOptions();
+  const generateUrl = usePageUrlGenerator();
+
+  const tableData = useMemo(() => {
+    return params.data.map((coupon: StripeCouponInterface) => {
+      const entry: TableContent<StripeCouponInterface> = { jsonApiData: coupon };
+      params.fields.forEach((field) => {
+        entry[field] = (coupon as any)[field as keyof StripeCouponInterface];
+      });
+      return entry;
+    });
+  }, [params.data, params.fields]);
+
+  const fieldColumnMap: Partial<Record<StripeCouponFields, () => any>> = {
+    [StripeCouponFields.name]: () => ({
+      id: "name",
+      accessorKey: "name",
+      header: t("billing.admin.coupons.fields.name"),
+      cell: ({ row }: { row: TableContent<StripeCouponInterface> }) => {
+        const coupon: StripeCouponInterface = row.original.jsonApiData;
+        return <Link href={generateUrl({ page: Modules.StripeCoupon, id: coupon.id })}>{coupon.name}</Link>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [StripeCouponFields.discount]: () => ({
+      id: "discount",
+      accessorKey: "discount",
+      header: t("billing.admin.coupons.fields.discount"),
+      cell: ({ row }: { row: TableContent<StripeCouponInterface> }) => {
+        const coupon: StripeCouponInterface = row.original.jsonApiData;
+        return <span className="text-xs">{formatCouponDiscount(coupon, t, fmt)}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [StripeCouponFields.places]: () => ({
+      id: "places",
+      accessorKey: "places",
+      header: t("billing.admin.coupons.fields.places"),
+      cell: ({ row }: { row: TableContent<StripeCouponInterface> }) => {
+        const coupon: StripeCouponInterface = row.original.jsonApiData;
+        // Typography role 15 (numeric): tabular-nums, end-aligned. NEVER
+        // font-mono — no monospace font is loaded in these apps.
+        return (
+          <span className="block text-xs tabular-nums text-end">
+            {coupon.maxRedemptions !== undefined
+              ? t("billing.admin.coupons.places.limited", {
+                  used: String(coupon.timesRedeemed),
+                  limit: String(coupon.maxRedemptions),
+                })
+              : t("billing.admin.coupons.places.unlimited", { used: String(coupon.timesRedeemed) })}
+          </span>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [StripeCouponFields.codes]: () => ({
+      id: "codes",
+      accessorKey: "codes",
+      header: t("billing.admin.coupons.fields.codes"),
+      cell: ({ row }: { row: TableContent<StripeCouponInterface> }) => {
+        const coupon: StripeCouponInterface = row.original.jsonApiData;
+        return <span className="block text-xs tabular-nums text-end">{coupon.codes.length}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [StripeCouponFields.status]: () => ({
+      id: "status",
+      accessorKey: "status",
+      header: t("billing.admin.coupons.fields.status"),
+      cell: ({ row }: { row: TableContent<StripeCouponInterface> }) => {
+        const coupon: StripeCouponInterface = row.original.jsonApiData;
+        return coupon.valid ? (
+          <Badge variant="softGreen">{t("billing.admin.coupons.status.active")}</Badge>
+        ) : (
+          <Badge variant="softGray">{t("billing.admin.coupons.status.ended")}</Badge>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+  };
+
+  const columns = useMemo(() => {
+    return params.fields.map((field) => fieldColumnMap[field]?.()).filter((col) => col !== undefined) as ColumnDef<
+      TableContent<StripeCouponInterface>
+    >[];
+  }, [params.fields, fieldColumnMap, t, generateUrl]);
+
+  return useMemo(() => ({ data: tableData, columns: columns }), [tableData, columns]);
+};
+
+registerTableGenerator("stripe-coupons", useStripeCouponTableStructure);

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

@@ -0,0 +1,5 @@
+export * from "./data";
+export * from "./utils";
+export * from "./stripe-coupon.module";
+export * from "./stripe-coupon-code.module";
+export * from "./stripe-coupon-offer.module";

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

@@ -0,0 +1,14 @@
+import { ModuleFactory } from "../../../permissions";
+import { StripeCouponCode } from "./data/stripe-coupon-code";
+
+/** The code endpoint's segment that returns the automatic code for a price. */
+export const STRIPE_COUPON_CODE_AUTOMATIC_SEGMENT = "automatic";
+
+export const StripeCouponCodeModule = (factory: ModuleFactory) =>
+  factory({
+    name: "stripe-coupon-codes",
+    // Codes are managed on their coupon's page.
+    pageUrl: "/administration/coupons",
+    model: StripeCouponCode,
+    moduleId: "85feb4c7-ff22-416a-b856-8dafcf28ff26",
+  });

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

@@ -0,0 +1,10 @@
+import { ModuleFactory } from "../../../permissions";
+import { StripeCouponOffer } from "./data/stripe-coupon-offer";
+
+export const StripeCouponOfferModule = (factory: ModuleFactory) =>
+  factory({
+    name: "stripe-coupon-offers",
+    pageUrl: "/pricing",
+    model: StripeCouponOffer,
+    moduleId: "6859d6cc-b94c-4cf7-8a02-b71ad59d75d2",
+  });

package/src/features/billing/stripe-coupon/stripe-coupon.module.ts

@@ -0,0 +1,18 @@
+import { TicketPercentIcon } from "lucide-react";
+import { ModuleFactory } from "../../../permissions";
+import { StripeCoupon } from "./data/stripe-coupon";
+
+/** The coupon endpoint's non-resource segment that re-reads its counts from Stripe. */
+export const STRIPE_COUPON_REFRESH_SEGMENT = "refresh";
+
+export const StripeCouponModule = (factory: ModuleFactory) =>
+  factory({
+    name: "stripe-coupons",
+    // The administration route this entity is served at. `name` above stays the
+    // API endpoint; this drives generateUrl / rewriteUrl / EditorSheet
+    // navigation, so it must match the real Next.js route.
+    pageUrl: "/administration/coupons",
+    model: StripeCoupon,
+    moduleId: "50bdb0d2-539c-4358-b609-d6beab248bdb",
+    icon: TicketPercentIcon,
+  });

package/src/features/billing/stripe-coupon/utils/__tests__/coupon-places.spec.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { couponPlacesLeft, couponPlacesTotal } from "../coupon-places";
+
+describe("coupon places", () => {
+  it("returns null when neither limit is set", () =>
+    expect(couponPlacesLeft({ timesRedeemed: 3 }, { timesRedeemed: 3 })).toBeNull());
+  it("uses the coupon limit alone", () =>
+    expect(couponPlacesLeft({ timesRedeemed: 0 }, { maxRedemptions: 50, timesRedeemed: 13 })).toBe(37));
+  it("takes the smaller of coupon and code", () =>
+    expect(couponPlacesLeft({ maxRedemptions: 10, timesRedeemed: 8 }, { maxRedemptions: 50, timesRedeemed: 13 })).toBe(
+      2,
+    ));
+  it("never goes below zero", () =>
+    expect(couponPlacesLeft({ timesRedeemed: 0 }, { maxRedemptions: 50, timesRedeemed: 51 })).toBe(0));
+  it("placesTotal is the smaller set limit", () =>
+    expect(couponPlacesTotal({ maxRedemptions: 10, timesRedeemed: 0 }, { maxRedemptions: 50, timesRedeemed: 0 })).toBe(
+      10,
+    ));
+});

package/src/features/billing/stripe-coupon/utils/__tests__/to-promotion-code-result.spec.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { StripeCouponCodeInterface } from "../../data/stripe-coupon-code.interface";
+import { StripeCouponInterface } from "../../data/stripe-coupon.interface";
+import { toPromotionCodeResult } from "../to-promotion-code-result";
+
+const codeWith = (coupon: Partial<StripeCouponInterface>): StripeCouponCodeInterface =>
+  ({ stripePromotionCodeId: "promo_1", code: "FOUNDER", coupon }) as unknown as StripeCouponCodeInterface;
+
+describe("toPromotionCodeResult", () => {
+  it("maps a percentage coupon", () => {
+    expect(
+      toPromotionCodeResult(codeWith({ discountType: "percent_off", percentOff: 20, duration: "forever" })),
+    ).toEqual({
+      valid: true,
+      automatic: true,
+      promotionCodeId: "promo_1",
+      code: "FOUNDER",
+      discountType: "percent_off",
+      discountValue: 20,
+      duration: "forever",
+    });
+  });
+
+  it("maps a fixed-amount coupon to amountOff and its currency", () => {
+    const result = toPromotionCodeResult(
+      codeWith({
+        discountType: "amount_off",
+        amountOff: 500,
+        currency: "eur",
+        duration: "repeating",
+        durationInMonths: 3,
+      }),
+    );
+    expect(result.discountType).toBe("amount_off");
+    expect(result.discountValue).toBe(500);
+    expect(result.currency).toBe("eur");
+    expect(result.duration).toBe("repeating");
+    expect(result.durationInMonths).toBe(3);
+    expect(result.automatic).toBe(true);
+  });
+});

package/src/features/billing/stripe-coupon/utils/coupon-places.ts

@@ -0,0 +1,23 @@
+/**
+ * Places left on a code: the smaller of (coupon limit - coupon redeemed) and
+ * (code limit - code redeemed), counting only the limits that are set, never
+ * below zero. `null` = unlimited. Same rule as the backend `placesLeft`.
+ */
+type Redeemable = { maxRedemptions?: number; timesRedeemed: number };
+
+export function couponPlacesLeft(code: Redeemable, coupon: Redeemable): number | null {
+  const remaining = [code, coupon]
+    .filter((item) => typeof item.maxRedemptions === "number")
+    .map((item) => Math.max(0, (item.maxRedemptions as number) - (item.timesRedeemed ?? 0)));
+
+  return remaining.length === 0 ? null : Math.min(...remaining);
+}
+
+/** The smaller of the set limits, or `null` when neither is set. */
+export function couponPlacesTotal(code: Redeemable, coupon: Redeemable): number | null {
+  const limits = [code.maxRedemptions, coupon.maxRedemptions].filter(
+    (limit): limit is number => typeof limit === "number",
+  );
+
+  return limits.length === 0 ? null : Math.min(...limits);
+}

package/src/features/billing/stripe-coupon/utils/format-coupon-discount.ts

@@ -0,0 +1,36 @@
+import { formatCurrency } from "../../components/utils/currency";
+import { BillingFormatOptions, BillingTranslator } from "../../components/utils/format-options";
+import { StripeCouponDiscountType, StripeCouponDurationType } from "../data/stripe-coupon.interface";
+
+export type CouponDiscountShape = {
+  discountType: StripeCouponDiscountType;
+  percentOff?: number;
+  amountOff?: number; // minor units
+  currency?: string;
+  duration: StripeCouponDurationType;
+  durationInMonths?: number;
+};
+
+/** "20% off forever", "€5.00 off for 3 months", "€5.00 off once". */
+export function formatCouponDiscount(
+  coupon: CouponDiscountShape,
+  t: BillingTranslator,
+  fmt: BillingFormatOptions = {},
+): string {
+  const amount =
+    coupon.discountType === "percent_off"
+      ? t("billing.admin.coupons.discount.percent", { value: String(coupon.percentOff ?? 0) })
+      : t("billing.admin.coupons.discount.amount", {
+          amount: formatCurrency(coupon.amountOff, coupon.currency ?? "eur", fmt),
+        });
+
+  // Literal keys (no template) so the message validator sees every one in use.
+  const duration =
+    coupon.duration === "repeating"
+      ? t("billing.admin.coupons.discount.repeating", { months: String(coupon.durationInMonths ?? 0) })
+      : coupon.duration === "once"
+        ? t("billing.admin.coupons.discount.once")
+        : t("billing.admin.coupons.discount.forever");
+
+  return `${amount} ${duration}`;
+}

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

@@ -0,0 +1,3 @@
+export * from "./coupon-places";
+export * from "./format-coupon-discount";
+export * from "./to-promotion-code-result";

package/src/features/billing/stripe-coupon/utils/to-promotion-code-result.ts

@@ -0,0 +1,23 @@
+import { PromotionCodeValidationResult } from "../../stripe-promotion-code/data/stripe-promotion-code.interface";
+import { StripeCouponCodeInterface } from "../data/stripe-coupon-code.interface";
+
+/**
+ * The automatic code as the wizard's promotion-code state, exactly as if the
+ * GM had typed and validated it.
+ */
+export function toPromotionCodeResult(code: StripeCouponCodeInterface): PromotionCodeValidationResult {
+  const coupon = code.coupon;
+  const discountType = coupon?.discountType;
+
+  return {
+    valid: true,
+    automatic: true,
+    promotionCodeId: code.stripePromotionCodeId,
+    code: code.code,
+    discountType,
+    discountValue: discountType === "amount_off" ? coupon?.amountOff : coupon?.percentOff,
+    currency: discountType === "amount_off" ? coupon?.currency : undefined,
+    duration: coupon?.duration,
+    durationInMonths: coupon?.durationInMonths,
+  };
+}