@7365admin1/layer-common 3.2.8-staging.203 → 3.2.8-staging.205

package/utils/subscription-form.test.ts

@@ -0,0 +1,284 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  BILLING_COMPLIMENTARY,
+  BILLING_PAID,
+  buildConsolePayload,
+  formValuesFrom,
+  formatMoney,
+  monthlyValue,
+  planOptionLabel,
+  readApiError,
+  todayISO,
+  validateConsoleSubscription,
+} from "./subscription-form.ts";
+
+const PLANS = [
+  { _id: "aaaaaaaaaaaaaaaaaaaaaaaa", name: "Standard Plan", price: 25, status: "active" },
+  { _id: "bbbbbbbbbbbbbbbbbbbbbbbb", name: "Retired Plan", price: 40, status: "deactive" },
+  { _id: "cccccccccccccccccccccccc", name: "Free Bundle", price: null, status: "active" },
+];
+
+const STANDARD = PLANS[0]._id;
+
+function form(overrides: Record<string, any> = {}) {
+  return {
+    plan: STANDARD,
+    billingMode: BILLING_COMPLIMENTARY,
+    startDate: "2026-09-01",
+    endDate: "2027-08-31",
+    ...overrides,
+  };
+}
+
+/* ── WHAT A CLIENT IS WORTH PER MONTH ── */
+
+test("a plan is priced per site, per month", () => {
+  assert.equal(monthlyValue(PLANS[0], 4), 100);
+  assert.equal(monthlyValue(PLANS[0], 1), 25);
+});
+
+test("no sites is worth nothing, and is not an error", () => {
+  assert.equal(monthlyValue(PLANS[0], 0), 0);
+});
+
+test("a plan with no price is worth nothing rather than NaN", () => {
+  assert.equal(monthlyValue(PLANS[2], 7), 0);
+  assert.equal(monthlyValue(undefined, 7), 0);
+  assert.equal(monthlyValue({ price: "not a number" } as any, 7), 0);
+});
+
+test("the monthly figure reads as Singapore money", () => {
+  assert.equal(formatMoney(100), "S$100.00");
+  assert.equal(formatMoney(0), "S$0.00");
+  assert.equal(formatMoney(NaN), "S$0.00");
+});
+
+test("a plan is offered with its per-site price beside its name", () => {
+  assert.equal(
+    planOptionLabel(PLANS[0]),
+    "Standard Plan - S$25.00 per site, per month",
+  );
+  assert.equal(planOptionLabel(PLANS[2]), "Free Bundle - no per-site price set");
+});
+
+/* ── WHAT GETS SENT ── */
+
+test("a complimentary subscription is sent with no price at all", () => {
+  const payload = buildConsolePayload(form(), PLANS, 4);
+  assert.equal(payload.amount, 0);
+  assert.equal(payload.billingMode, BILLING_COMPLIMENTARY);
+});
+
+test("a paying subscription is sent the plan price times the site count", () => {
+  const payload = buildConsolePayload(form({ billingMode: BILLING_PAID }), PLANS, 4);
+  assert.equal(payload.amount, 100);
+});
+
+test("an empty start date is sent as today, the same default the API uses", () => {
+  const payload = buildConsolePayload(form({ startDate: "" }), PLANS, 1);
+  assert.equal(payload.startDate, todayISO());
+});
+
+test("the payload carries nothing but the five fields the API accepts", () => {
+  const payload = buildConsolePayload(form({ billingMode: BILLING_PAID }), PLANS, 2);
+  assert.deepEqual(Object.keys(payload).sort(), [
+    "amount",
+    "billingMode",
+    "endDate",
+    "plan",
+    "startDate",
+  ]);
+});
+
+test("no status is ever sent - suspend and reactivate are Phase 3", () => {
+  const payload: Record<string, any> = buildConsolePayload(form(), PLANS, 2);
+  assert.equal(payload.status, undefined);
+});
+
+test("nothing about a card, an invoice or a gateway is ever sent", () => {
+  const sent = JSON.stringify(buildConsolePayload(form({ billingMode: BILLING_PAID }), PLANS, 3));
+  for (const forbidden of ["card", "cvv", "invoice", "reddot", "payment_method"]) {
+    assert.equal(sent.toLowerCase().includes(forbidden), false, forbidden);
+  }
+});
+
+/* ── WHAT IS REFUSED, BEFORE THE REQUEST GOES OUT ── */
+
+test("a form with everything answered is not refused", () => {
+  assert.equal(
+    validateConsoleSubscription(buildConsolePayload(form(), PLANS, 4), PLANS),
+    null,
+  );
+  assert.equal(
+    validateConsoleSubscription(
+      buildConsolePayload(form({ billingMode: BILLING_PAID }), PLANS, 4),
+      PLANS,
+    ),
+    null,
+  );
+});
+
+test("no plan chosen is refused", () => {
+  assert.equal(
+    validateConsoleSubscription(buildConsolePayload(form({ plan: "" }), PLANS, 1), PLANS),
+    "Choose a plan.",
+  );
+});
+
+test("a plan that does not exist is refused", () => {
+  assert.equal(
+    validateConsoleSubscription(
+      buildConsolePayload(form({ plan: "dddddddddddddddddddddddd" }), PLANS, 1),
+      PLANS,
+    ),
+    "That plan could not be found. Pick one from the list.",
+  );
+});
+
+test("a plan that is no longer active is refused, and named", () => {
+  assert.equal(
+    validateConsoleSubscription(
+      buildConsolePayload(form({ plan: PLANS[1]._id }), PLANS, 1),
+      PLANS,
+    ),
+    "The plan Retired Plan is no longer active, so it cannot be given to a client. Pick an active plan.",
+  );
+});
+
+test("an end date before the start date is refused", () => {
+  assert.equal(
+    validateConsoleSubscription(
+      buildConsolePayload(form({ startDate: "2026-09-01", endDate: "2026-08-31" }), PLANS, 1),
+      PLANS,
+    ),
+    "The end date must be after the start date.",
+  );
+});
+
+test("an end date equal to the start date is refused too - the API refuses it", () => {
+  assert.equal(
+    validateConsoleSubscription(
+      buildConsolePayload(form({ startDate: "2026-09-01", endDate: "2026-09-01" }), PLANS, 1),
+      PLANS,
+    ),
+    "The end date must be after the start date.",
+  );
+});
+
+test("a missing end date is refused - every client has one, free or not", () => {
+  assert.equal(
+    validateConsoleSubscription(buildConsolePayload(form({ endDate: "" }), PLANS, 1), PLANS),
+    "Enter an end date. Every client has one, free or not.",
+  );
+});
+
+test("an unreadable date is refused as a date, not as something else", () => {
+  assert.equal(
+    validateConsoleSubscription(
+      buildConsolePayload(form({ endDate: "31/08/2027" }), PLANS, 1),
+      PLANS,
+    ),
+    "The end date is not a valid date.",
+  );
+  assert.equal(
+    validateConsoleSubscription(
+      buildConsolePayload(form({ startDate: "not-a-date" }), PLANS, 1),
+      PLANS,
+    ),
+    "The start date is not a valid date.",
+  );
+});
+
+test("a complimentary subscription carrying a price is refused, not silently zeroed", () => {
+  // The form can only produce this by disagreeing with itself - which is
+  // exactly what this rule is here to catch before it reaches the API.
+  const payload = {
+    ...buildConsolePayload(form({ billingMode: BILLING_PAID }), PLANS, 4),
+    billingMode: BILLING_COMPLIMENTARY,
+  };
+  assert.equal(payload.amount, 100);
+  assert.equal(
+    validateConsoleSubscription(payload, PLANS),
+    "A complimentary subscription is not charged, so it cannot carry a price. Set the price to 0, or change this client to paying.",
+  );
+});
+
+test("a charging arrangement that is neither is refused", () => {
+  assert.equal(
+    validateConsoleSubscription(buildConsolePayload(form({ billingMode: "" }), PLANS, 1), PLANS),
+    "Choose whether this client is complimentary or paying.",
+  );
+});
+
+test("a complimentary client with no sites is allowed - most clients are exactly this", () => {
+  assert.equal(
+    validateConsoleSubscription(buildConsolePayload(form(), PLANS, 0), PLANS),
+    null,
+  );
+});
+
+/* ── PRE-FILLING THE FORM ── */
+
+test("a client with no subscription opens complimentary, starting today, with no end date", () => {
+  const values = formValuesFrom(null, new Date("2026-08-20T10:00:00"));
+  assert.equal(values.plan, "");
+  assert.equal(values.billingMode, BILLING_COMPLIMENTARY);
+  assert.equal(values.startDate, todayISO(new Date("2026-08-20T10:00:00")));
+  assert.equal(values.endDate, "");
+});
+
+test("an existing subscription opens with its own plan, mode and dates", () => {
+  const values = formValuesFrom({
+    _id: "eeeeeeeeeeeeeeeeeeeeeeee",
+    plan: STANDARD,
+    billingMode: "complimentary",
+    startDate: "2026-01-15T00:00:00.000Z",
+    endDate: "2026-12-31T00:00:00.000Z",
+  });
+  assert.equal(values.plan, STANDARD);
+  assert.equal(values.billingMode, BILLING_COMPLIMENTARY);
+  assert.equal(values.startDate, "2026-01-15");
+  assert.equal(values.endDate, "2026-12-31");
+});
+
+test("a record with no billingMode opens as paying - every one today came from the paid checkout", () => {
+  const values = formValuesFrom({
+    _id: "eeeeeeeeeeeeeeeeeeeeeeee",
+    createdAt: "2025-03-04T00:00:00.000Z",
+    nextBillingDate: "2026-04-05T00:00:00.000Z",
+  });
+  assert.equal(values.billingMode, BILLING_PAID);
+  // The dates fall back to what the record does carry, exactly as the list does.
+  assert.equal(values.startDate, "2025-03-04");
+  assert.equal(values.endDate, "2026-04-05");
+});
+
+test("a complimentary record has no nextBillingDate, so the end date comes from endDate alone", () => {
+  const values = formValuesFrom({
+    _id: "eeeeeeeeeeeeeeeeeeeeeeee",
+    billingMode: "complimentary",
+    createdAt: "2026-02-01T00:00:00.000Z",
+    endDate: "2027-02-01T00:00:00.000Z",
+  });
+  assert.equal(values.endDate, "2027-02-01");
+});
+
+/* ── WHAT A REFUSAL FROM THE SERVER SAYS ── */
+
+test("the API's own wording is what the person is shown", () => {
+  assert.equal(
+    readApiError(
+      { data: { status: "error", message: "This client already has a subscription. Edit the existing one instead of creating another." } },
+      "fallback",
+    ),
+    "This client already has a subscription. Edit the existing one instead of creating another.",
+  );
+});
+
+test("a message that says nothing to a person falls back to one that does", () => {
+  assert.equal(readApiError(new Error("fetch failed"), "Try again."), "Try again.");
+  assert.equal(readApiError(undefined, "Try again."), "Try again.");
+  assert.equal(readApiError({ data: { message: "   " } }, "Try again."), "Try again.");
+});

package/utils/subscription-form.ts

@@ -0,0 +1,265 @@
+/**
+ * THE STAFF CONSOLE'S SUBSCRIPTION FORM, DECIDED IN ONE PLACE.
+ *
+ * A Seven365 staff member sets a client up, or changes what the client is on.
+ * They pick four things - a plan, whether the client is complimentary or
+ * paying, a start date and an end date - and nothing else. Everything else on
+ * that screen is worked out here so nobody has to do arithmetic in their head:
+ *
+ *   - a plan is priced PER SITE, PER MONTH (owner decision 3), so what the
+ *     client is worth per month is the plan's price times how many sites they
+ *     have - a number the Client List already knows;
+ *   - a complimentary client is worth nothing per month, because nobody is
+ *     charging them - but the arrangement is still real, still dated, and
+ *     still monitored.
+ *
+ * WHY THE REFUSALS LIVE HERE AND NOT ONLY IN THE COMPONENT. The API refuses
+ * the same four things (core `subscription.controller.ts`, `readConsoleForm`)
+ * and answers with a sentence written to be shown to a person. Repeating those
+ * checks in front of the request is not a second opinion - it is the same
+ * answer, delivered before a person has waited for a round trip, in the same
+ * words, so the two can never disagree about what is wrong. When the server
+ * still refuses, its message is what the screen shows.
+ *
+ * Nothing here takes a card, quotes a total to charge, or moves any money.
+ * Red Dot is the payment provider (owner decision 1). The monthly figure is an
+ * indication of what a client is worth, shown to a member of staff.
+ */
+
+/** The two charging arrangements, spelled the way the API stores them. */
+export const BILLING_COMPLIMENTARY = "complimentary";
+export const BILLING_PAID = "paid";
+
+export interface TPlanOption {
+  _id?: string;
+  name?: string;
+  price?: number | null;
+  status?: string;
+  [key: string]: any;
+}
+
+/** What the person has filled in. Dates are what `<input type="date">` gives. */
+export interface TSubscriptionFormValues {
+  plan: string;
+  billingMode: string;
+  startDate: string;
+  endDate: string;
+}
+
+/** What `POST`/`PUT /api/subscriptions/console/:id` accepts. Nothing else. */
+export interface TConsolePayload {
+  plan: string;
+  billingMode: string;
+  startDate: string;
+  endDate: string;
+  amount: number;
+}
+
+/** Today, as `<input type="date">` wants it. Local, not UTC - a person in
+ * Singapore choosing "today" means their today. */
+export function todayISO(now: Date = new Date()): string {
+  const local = new Date(now.getTime() - now.getTimezoneOffset() * 60000);
+  return local.toISOString().slice(0, 10);
+}
+
+const money = new Intl.NumberFormat("en-US", {
+  minimumFractionDigits: 2,
+  maximumFractionDigits: 2,
+});
+
+/**
+ * "S$250.00". One currency, because the console only ever writes SGD.
+ *
+ * The symbol is written rather than asked for: `Intl`'s currency style answers
+ * a bare "$" under `en-SG` and "SGD 250.00" under `en-US`, and which one a
+ * person sees would then depend on where their browser thinks it is. On a
+ * screen about money that is not a difference worth leaving to chance.
+ */
+export function formatMoney(value: number): string {
+  return `S$${money.format(Number.isFinite(value) ? value : 0)}`;
+}
+
+/**
+ * What this client is worth per month on this plan: the per-site monthly price
+ * times their live site count. A plan with no price (a free bundle) is 0, and
+ * so is a client with no sites yet - neither is an error.
+ */
+export function monthlyValue(
+  plan: TPlanOption | null | undefined,
+  siteCount: number,
+): number {
+  const price = Number(plan?.price ?? 0);
+  const sites = Number(siteCount ?? 0);
+  if (!Number.isFinite(price) || !Number.isFinite(sites)) return 0;
+  return Math.max(0, price) * Math.max(0, sites);
+}
+
+/** "Standard Plan - S$25.00 per site, per month". The price belongs beside the
+ * name; without it the person is picking a plan blind. */
+export function planOptionLabel(plan: TPlanOption): string {
+  const price = Number(plan?.price ?? 0);
+  const name = plan?.name ?? "Unnamed plan";
+  return price > 0
+    ? `${name} - ${formatMoney(price)} per site, per month`
+    : `${name} - no per-site price set`;
+}
+
+function isValidISODate(value: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value ?? "")) return false;
+  const d = new Date(`${value}T00:00:00`);
+  return !isNaN(d.getTime());
+}
+
+/**
+ * Everything that must be true before the request goes out, in the order the
+ * API checks it, worded the way the API words it.
+ *
+ * It reads the PAYLOAD rather than the four fields, so the price it judges is
+ * the price that would actually be sent - a rule that read the form instead
+ * could only ever agree with itself.
+ *
+ * Returns the ONE thing to tell the person, or `null` when there is nothing to
+ * tell them. One message at a time on purpose: a list of five complaints about
+ * a four-field form is harder to act on than the first thing to fix.
+ */
+export function validateConsoleSubscription(
+  payload: TConsolePayload,
+  plans: TPlanOption[],
+): string | null {
+  if (!payload?.plan) return "Choose a plan.";
+
+  if (
+    payload.billingMode !== BILLING_COMPLIMENTARY &&
+    payload.billingMode !== BILLING_PAID
+  ) {
+    return "Choose whether this client is complimentary or paying.";
+  }
+
+  if (payload.startDate && !isValidISODate(payload.startDate)) {
+    return "The start date is not a valid date.";
+  }
+
+  if (!payload.endDate) {
+    return "Enter an end date. Every client has one, free or not.";
+  }
+
+  if (!isValidISODate(payload.endDate)) {
+    return "The end date is not a valid date.";
+  }
+
+  // A start date is optional and defaults to today, exactly as the API does -
+  // so the comparison has to use the same date the API would have used.
+  // Both are `YYYY-MM-DD`, which sorts as text in date order, so this is the
+  // same comparison the API makes without dragging a timezone into it.
+  if (payload.endDate <= (payload.startDate || todayISO())) {
+    return "The end date must be after the start date.";
+  }
+
+  const plan = plans?.find((p) => String(p?._id) === String(payload.plan));
+  if (!plan) return "That plan could not be found. Pick one from the list.";
+
+  if (plan.status && plan.status !== "active") {
+    return (
+      "The plan " +
+      (plan.name ?? "you picked") +
+      " is no longer active, so it cannot be given to a client. Pick an active plan."
+    );
+  }
+
+  // A complimentary client is not charged, so a price against one is a
+  // contradiction worth saying out loud rather than quietly storing as zero -
+  // otherwise the person walks away believing they set a price that is not
+  // there. This is the check that the charging mode and the figure agree.
+  if (payload.billingMode === BILLING_COMPLIMENTARY && Number(payload.amount) > 0) {
+    return "A complimentary subscription is not charged, so it cannot carry a price. Set the price to 0, or change this client to paying.";
+  }
+
+  if (Number(payload.amount) < 0) return "The price cannot be negative.";
+
+  return null;
+}
+
+/**
+ * The body the console endpoints take, and nothing more.
+ *
+ * `status` is deliberately absent: suspending and reactivating a client is
+ * Phase 3 and the edit endpoint does not accept a status, so this form cannot
+ * change one by accident. No card field, no invoice, no gateway.
+ */
+export function buildConsolePayload(
+  values: TSubscriptionFormValues,
+  plans: TPlanOption[],
+  siteCount = 0,
+): TConsolePayload {
+  const plan = plans?.find((p) => String(p?._id) === String(values.plan));
+  const complimentary = values.billingMode === BILLING_COMPLIMENTARY;
+
+  return {
+    plan: values.plan,
+    billingMode: values.billingMode,
+    startDate: values.startDate || todayISO(),
+    endDate: values.endDate,
+    amount: complimentary ? 0 : monthlyValue(plan, siteCount),
+  };
+}
+
+/**
+ * Turn a failed request into something a person can act on.
+ *
+ * The API answers `{ status: "error", message: "..." }` and its console
+ * messages are already written for a person to read, so the message is what
+ * the screen shows. Only when there is nothing readable does this fall back to
+ * wording of its own - a raw dump of a fetch error tells the person nothing
+ * they can do.
+ */
+export function readApiError(error: any, fallback: string): string {
+  const message =
+    error?.data?.message ??
+    error?.response?._data?.message ??
+    error?.data?.error ??
+    (typeof error?.message === "string" && !/fetch failed|^\[/i.test(error.message)
+      ? error.message
+      : "");
+
+  return typeof message === "string" && message.trim() ? message : fallback;
+}
+
+/**
+ * Pre-fill the form from what the client already has.
+ *
+ * The subscription the API sends back carries dates as ISO timestamps; the
+ * date inputs want `YYYY-MM-DD`, which is the front of one. An absent
+ * `billingMode` reads as paid - every subscription that exists today came from
+ * the paid checkout, which is the same rule the model states.
+ */
+export function formValuesFrom(
+  subscription: Record<string, any> | null | undefined,
+  now: Date = new Date(),
+): TSubscriptionFormValues {
+  const sub = subscription ?? {};
+
+  const dateOnly = (value: any) => {
+    if (!value) return "";
+    const d = value instanceof Date ? value : new Date(String(value));
+    return isNaN(d.getTime()) ? "" : todayISO(d);
+  };
+
+  if (!sub._id) {
+    return {
+      plan: "",
+      billingMode: BILLING_COMPLIMENTARY,
+      startDate: todayISO(now),
+      endDate: "",
+    };
+  }
+
+  return {
+    plan: sub.plan ? String(sub.plan) : "",
+    billingMode:
+      String(sub.billingMode ?? "").trim().toLowerCase() === BILLING_COMPLIMENTARY
+        ? BILLING_COMPLIMENTARY
+        : BILLING_PAID,
+    startDate: dateOnly(sub.startDate ?? sub.createdAt) || todayISO(now),
+    endDate: dateOnly(sub.endDate ?? sub.nextBillingDate),
+  };
+}