@7365admin1/layer-common 3.2.8-staging.202 → 3.2.8-staging.204

package/utils/client-subscription.test.ts

@@ -0,0 +1,145 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  NOT_SET,
+  describeClientSubscription,
+  formatDate,
+} from "./client-subscription.ts";
+
+/** What the list endpoint really returns for an org that HAS a subscription. */
+function orgWithSub(sub: Record<string, any>) {
+  return {
+    _id: "org1",
+    name: "A Client",
+    status: "active",
+    subscription: {
+      _id: "sub1",
+      org: "org1",
+      type: "organization",
+      billingCycle: "monthly",
+      createdAt: "2026-01-01T00:00:00.000Z",
+      nextBillingDate: "2027-01-01T00:00:00.000Z",
+      status: "active",
+      ...sub,
+    },
+  };
+}
+
+const NOW = new Date("2026-08-20T00:00:00.000Z");
+
+test("no subscription document is a state, not a broken row", () => {
+  // The left join collapses a missing subscription to `{}` - this is the shape
+  // 11 production clients are in, and it used to render as four dashes.
+  for (const org of [{ subscription: {} }, { subscription: null }, {}, null, undefined]) {
+    const v = describeClientSubscription(org as any, NOW);
+    assert.equal(v.state, "none", JSON.stringify(org));
+    assert.equal(v.label, "No subscription set up");
+    assert.equal(v.billingCycle, NOT_SET);
+    assert.equal(v.start, NOT_SET);
+    assert.equal(v.end, NOT_SET);
+    assert.equal(v.needsAttention, false);
+  }
+});
+
+test("a running record with nothing else proven is plain Active, never 'paying'", () => {
+  // Nothing the endpoint sends proves anybody is paying, so it must not say so.
+  const v = describeClientSubscription(orgWithSub({}), NOW);
+  assert.equal(v.state, "active");
+  assert.equal(v.label, "Active");
+  assert.equal(v.billingCycle, "Monthly");
+  assert.equal(v.needsAttention, false);
+});
+
+test("complimentary is only claimed when the record says so", () => {
+  const v = describeClientSubscription(
+    orgWithSub({ billingMode: "complimentary" }),
+    NOW,
+  );
+  assert.equal(v.state, "complimentary");
+  assert.equal(v.label, "Complimentary (not charged)");
+
+  // and the opposite claim needs the same proof
+  assert.equal(
+    describeClientSubscription(orgWithSub({ billingMode: "paid" }), NOW).label,
+    "Active (paying)",
+  );
+});
+
+test("suspended and ended come from the record's own status", () => {
+  assert.equal(
+    describeClientSubscription(orgWithSub({ status: "suspended" }), NOW).state,
+    "suspended",
+  );
+
+  for (const s of ["ended", "canceled", "cancelled", "expired", "TERMINATED", " Ended "]) {
+    const v = describeClientSubscription(orgWithSub({ status: s }), NOW);
+    assert.equal(v.state, "ended", s);
+    assert.equal(v.label, "Ended");
+    assert.equal(v.needsAttention, false);
+  }
+});
+
+test("owner decision 8: a passed end date is flagged, not silently left as Active", () => {
+  const v = describeClientSubscription(
+    orgWithSub({ nextBillingDate: "2026-08-01T00:00:00.000Z" }),
+    NOW,
+  );
+  assert.equal(v.state, "ended");
+  assert.equal(v.label, "Ended (needs attention)");
+  assert.equal(v.needsAttention, true);
+});
+
+test("a suspended record is not re-labelled by its dates", () => {
+  // Status wins: a client already suspended does not need flagging again.
+  const v = describeClientSubscription(
+    orgWithSub({ status: "suspended", nextBillingDate: "2026-08-01T00:00:00.000Z" }),
+    NOW,
+  );
+  assert.equal(v.state, "suspended");
+  assert.equal(v.needsAttention, false);
+});
+
+test("Phase 2's startDate / endDate win over the fallbacks when they arrive", () => {
+  const v = describeClientSubscription(
+    orgWithSub({
+      startDate: "2026-03-05T00:00:00.000Z",
+      endDate: "2027-03-05T00:00:00.000Z",
+      createdAt: "2020-01-01T00:00:00.000Z",
+      nextBillingDate: "2020-02-01T00:00:00.000Z",
+    }),
+    NOW,
+  );
+  // The stale fallbacks are both in the past; if they had won, this row would
+  // have been flagged. It is not, so the real dates were used.
+  assert.equal(v.state, "active");
+  assert.equal(v.start, formatDate("2026-03-05T00:00:00.000Z"));
+  assert.equal(v.end, formatDate("2027-03-05T00:00:00.000Z"));
+});
+
+test("a missing or unreadable value says 'Not set', not a dash", () => {
+  assert.equal(formatDate(null), NOT_SET);
+  assert.equal(formatDate(""), NOT_SET);
+  assert.equal(formatDate("not a date"), NOT_SET);
+  assert.notEqual(formatDate("2026-08-20T00:00:00.000Z"), NOT_SET);
+
+  const v = describeClientSubscription(
+    orgWithSub({ billingCycle: "", createdAt: null, nextBillingDate: null }),
+    NOW,
+  );
+  assert.equal(v.billingCycle, NOT_SET);
+  assert.equal(v.start, NOT_SET);
+  assert.equal(v.end, NOT_SET);
+  assert.equal(v.state, "active");
+});
+
+test("a billing cycle the screen does not know is shown, not swallowed", () => {
+  assert.equal(
+    describeClientSubscription(orgWithSub({ billingCycle: "quarterly" }), NOW).billingCycle,
+    "quarterly",
+  );
+  assert.equal(
+    describeClientSubscription(orgWithSub({ billingCycle: "YEARLY" }), NOW).billingCycle,
+    "Yearly",
+  );
+});

package/utils/client-subscription.ts

@@ -0,0 +1,157 @@
+/**
+ * WHAT A CLIENT'S SUBSCRIPTION ROW HONESTLY SAYS, IN ONE PLACE.
+ *
+ * The super-admin Client List used to print "-" in Plan Type, Billing Cycle,
+ * Subscription Start and Subscription End for every client that has no
+ * subscription document. Four dashes read as a broken screen. They are not:
+ * they are a real, ordinary state - nobody has set that client up yet.
+ *
+ * This file turns the row the API actually returns into words a Seven365 staff
+ * member can act on without being told how the data is stored underneath.
+ *
+ * THE RULE THIS FILE OBEYS: never claim more than the record proves.
+ * The projection behind `GET /api/organizations/v2/orgs/subscriptions`
+ * (core `organization.repo.ts`, `$project`) sends exactly:
+ *
+ *   _id, org, type, paidSeats, currentSeats, maxSeats,
+ *   billingCycle, nextBillingDate, createdAt, status
+ *
+ * It does NOT send a plan, a price, or - today - a charging arrangement. So a
+ * client whose record exists and is running is called "Active", never
+ * "Active - paying", because nothing in the data proves anybody is paying.
+ * Where two states cannot yet be told apart, the lesser claim wins.
+ */
+
+/** The five states a client's subscription can be in, as a person would say them. */
+export type TClientSubscriptionState =
+  | "none"
+  | "complimentary"
+  | "active"
+  | "suspended"
+  | "ended";
+
+export interface TClientSubscriptionView {
+  state: TClientSubscriptionState;
+  /** The one line the "Subscription" column shows. */
+  label: string;
+  /** True when somebody has to do something about this client. */
+  needsAttention: boolean;
+  /** "Monthly" / "Yearly" / "Not set". */
+  billingCycle: string;
+  /** A date, or "Not set". */
+  start: string;
+  /** A date, or "Not set". */
+  end: string;
+}
+
+export const NOT_SET = "Not set";
+
+/**
+ * A status the record can carry that means the arrangement is over. `canceled`
+ * is the spelling the hourly billing job writes, so it has to be here; the
+ * other spellings cost nothing and stop a one-letter difference showing a
+ * finished client as running.
+ */
+const ENDED_STATUSES = new Set([
+  "ended",
+  "canceled",
+  "cancelled",
+  "expired",
+  "terminated",
+]);
+
+const BILLING_CYCLE_LABELS: Record<string, string> = {
+  monthly: "Monthly",
+  yearly: "Yearly",
+  annually: "Yearly",
+};
+
+/** Same behaviour the screen already had, with wording instead of a dash. */
+export function formatDate(value?: string | Date | null): string {
+  if (value == null || value === "") return NOT_SET;
+  const d = value instanceof Date ? value : new Date(value);
+  return isNaN(d.getTime()) ? NOT_SET : d.toLocaleDateString("en-US");
+}
+
+function isPast(value: unknown, now: Date): boolean {
+  if (value == null || value === "") return false;
+  const d = value instanceof Date ? value : new Date(String(value));
+  return !isNaN(d.getTime()) && d.getTime() < now.getTime();
+}
+
+/**
+ * Read one organisation row from the list endpoint and say what it means.
+ *
+ * `org.subscription` is a LEFT join: an organisation with no subscription
+ * document still comes back as a row, with the sub-document collapsed to `{}`.
+ * That empty object - specifically, the absence of `_id` - is what "nobody has
+ * set this client up" looks like on the wire, and it is the state most clients
+ * are in right now.
+ */
+export function describeClientSubscription(
+  org: Record<string, any> | null | undefined,
+  now: Date = new Date(),
+): TClientSubscriptionView {
+  const sub = org?.subscription ?? {};
+
+  if (!sub._id) {
+    return {
+      state: "none",
+      label: "No subscription set up",
+      needsAttention: false,
+      billingCycle: NOT_SET,
+      start: NOT_SET,
+      end: NOT_SET,
+    };
+  }
+
+  const cycleKey = String(sub.billingCycle ?? "").trim().toLowerCase();
+
+  // `startDate` / `endDate` are the fields the build spec adds in Phase 2. Until
+  // then the endpoint sends neither, so both fall through to what it does send -
+  // which is what this screen has always displayed.
+  const view = {
+    billingCycle: BILLING_CYCLE_LABELS[cycleKey] ?? (cycleKey ? String(sub.billingCycle) : NOT_SET),
+    start: formatDate(sub.startDate ?? sub.createdAt),
+    end: formatDate(sub.endDate ?? sub.nextBillingDate),
+  };
+
+  const status = String(sub.status ?? "").trim().toLowerCase();
+
+  if (status === "suspended") {
+    return { ...view, state: "suspended", label: "Suspended", needsAttention: false };
+  }
+
+  if (ENDED_STATUSES.has(status)) {
+    return { ...view, state: "ended", label: "Ended", needsAttention: false };
+  }
+
+  // Owner decision 8: when an end date passes, the client is flagged here FIRST.
+  // The record still says it is running, so the honest line is that the dates
+  // and the status disagree and a person has to settle it. Nothing on this
+  // screen suspends anybody - that is the job Phase 3 builds.
+  if (isPast(sub.endDate ?? sub.nextBillingDate, now)) {
+    return { ...view, state: "ended", label: "Ended (needs attention)", needsAttention: true };
+  }
+
+  // ponytail: dormant until Phase 2 writes `billingMode`. Nothing sends it
+  // today, so today every live record falls through to plain "Active" - which
+  // is the honest answer, because nothing in the data proves anybody is paying.
+  const billingMode = String(sub.billingMode ?? "").trim().toLowerCase();
+
+  if (billingMode === "complimentary") {
+    return {
+      ...view,
+      state: "complimentary",
+      label: "Complimentary (not charged)",
+      needsAttention: false,
+    };
+  }
+
+  return {
+    ...view,
+    state: "active",
+    label: billingMode === "paid" ? "Active (paying)" : "Active",
+    needsAttention: false,
+  };
+}

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.");
+});