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

package/components/ClientDetailForm.vue

@@ -70,177 +70,54 @@
     </section>
 
     <!-- ===== SUBSCRIPTION INFORMATION ===== -->
+    <!--
+      READ-ONLY on purpose. This section used to offer six dropdowns and two
+      date boxes that looked editable and saved nothing: the plan list was two
+      invented names, and Start / End were always blank because nothing ever
+      loaded them. It now shows what the client's record actually says, using
+      the same wording as the Client List. Setting or changing a subscription is
+      a separate piece of work with a real endpoint behind it.
+    -->
     <section class="section">
       <h3>Subscription Information</h3>
 
-      <div class="row">
-        <div class="field">
-          <label>Subscription plan type</label>
-          <div class="select-wrap">
-            <select v-model="form.planType">
-              <option v-for="opt in PLAN_TYPE_OPTIONS" :key="opt" :value="opt">
-                {{ opt }}
-              </option>
-            </select>
-            <svg class="chevron" viewBox="0 0 10 6" fill="none">
-              <path
-                d="M1 1l4 4 4-4"
-                stroke="currentColor"
-                stroke-width="1.4"
-                stroke-linecap="round"
-              />
-            </svg>
-          </div>
-        </div>
-        <div class="field">
-          <label>Auto Renewal</label>
-          <div class="select-wrap">
-            <select v-model="form.autoRenewal">
-              <option
-                v-for="opt in AUTO_RENEWAL_OPTIONS"
-                :key="opt"
-                :value="opt"
-              >
-                {{ opt }}
-              </option>
-            </select>
-            <svg class="chevron" viewBox="0 0 10 6" fill="none">
-              <path
-                d="M1 1l4 4 4-4"
-                stroke="currentColor"
-                stroke-width="1.4"
-                stroke-linecap="round"
-              />
-            </svg>
-          </div>
-        </div>
-      </div>
+      <p v-if="subscription.state === 'none'" class="sub-none">
+        No subscription set up for this client yet.
+      </p>
 
-      <div class="row">
-        <div class="field">
-          <label>Billing Cycle</label>
-          <div class="select-wrap">
-            <select v-model="form.billingCycle" @change="onBillingCycleChange">
-              <option
-                v-for="opt in BILLING_CYCLE_OPTIONS"
-                :key="opt"
-                :value="opt"
-              >
-                {{ opt }}
-              </option>
-            </select>
-            <svg class="chevron" viewBox="0 0 10 6" fill="none">
-              <path
-                d="M1 1l4 4 4-4"
-                stroke="currentColor"
-                stroke-width="1.4"
-                stroke-linecap="round"
-              />
-            </svg>
+      <template v-else>
+        <div class="row">
+          <div class="field">
+            <label>Subscription</label>
+            <p
+              class="read-value"
+              :class="{ 'needs-attention': subscription.needsAttention }"
+            >
+              {{ subscription.label }}
+            </p>
           </div>
-        </div>
-        <div class="field">
-          <label>Status</label>
-          <div class="select-wrap">
-            <select v-model="form.status">
-              <option v-for="opt in STATUS_OPTIONS" :key="opt" :value="opt">
-                {{ opt }}
-              </option>
-            </select>
-            <svg class="chevron" viewBox="0 0 10 6" fill="none">
-              <path
-                d="M1 1l4 4 4-4"
-                stroke="currentColor"
-                stroke-width="1.4"
-                stroke-linecap="round"
-              />
-            </svg>
+          <div class="field">
+            <label>Billing Cycle</label>
+            <p class="read-value">{{ subscription.billingCycle }}</p>
           </div>
         </div>
-      </div>
 
-      <div class="row row-single">
-        <div class="field">
-          <label>Subscription plan</label>
-          <div class="select-wrap">
-            <select v-model="form.subscriptionPlan">
-              <option
-                v-for="opt in subscriptionPlanOptions"
-                :key="opt"
-                :value="opt"
-              >
-                {{ opt }}
-              </option>
-            </select>
-            <svg class="chevron" viewBox="0 0 10 6" fill="none">
-              <path
-                d="M1 1l4 4 4-4"
-                stroke="currentColor"
-                stroke-width="1.4"
-                stroke-linecap="round"
-              />
-            </svg>
+        <div class="row">
+          <div class="field">
+            <label>Start Date</label>
+            <p class="read-value">{{ subscription.start }}</p>
           </div>
-          <p class="hint">
-            Values of dropdown are determined by the list under selected billing
-            cycle.
-          </p>
-        </div>
-      </div>
-
-      <div class="row">
-        <div class="field">
-          <label>Start Date</label>
-          <div class="date-input">
-            <input type="text" :value="form.startDate" disabled />
-            <svg viewBox="0 0 16 16" fill="none" width="14" height="14">
-              <rect
-                x="1"
-                y="3"
-                width="14"
-                height="12"
-                rx="2"
-                stroke="currentColor"
-                stroke-width="1.3"
-              />
-              <path d="M1 7h14" stroke="currentColor" stroke-width="1.3" />
-              <path
-                d="M5 1v3M11 1v3"
-                stroke="currentColor"
-                stroke-width="1.3"
-                stroke-linecap="round"
-              />
-            </svg>
-          </div>
-        </div>
-        <div class="field">
-          <label>End Date</label>
-          <div class="date-input">
-            <input type="text" :value="form.endDate" disabled />
-            <svg viewBox="0 0 16 16" fill="none" width="14" height="14">
-              <rect
-                x="1"
-                y="3"
-                width="14"
-                height="12"
-                rx="2"
-                stroke="currentColor"
-                stroke-width="1.3"
-              />
-              <path d="M1 7h14" stroke="currentColor" stroke-width="1.3" />
-              <path
-                d="M5 1v3M11 1v3"
-                stroke="currentColor"
-                stroke-width="1.3"
-                stroke-linecap="round"
-              />
-            </svg>
+          <div class="field">
+            <label>End Date</label>
+            <p
+              class="read-value"
+              :class="{ 'needs-attention': subscription.needsAttention }"
+            >
+              {{ subscription.end }}
+            </p>
           </div>
         </div>
-      </div>
-      <p class="hint hint-below">
-        Start and end date depend on the billing cycle, and cannot be edited.
-      </p>
+      </template>
     </section>
 
     <!-- ===== INCLUDED APPLICATION ===== -->
@@ -281,6 +158,7 @@
 import { reactive, computed, watch } from 'vue'
 import useOrg from '../composables/useOrg'
 import useCustomerSite from '../composables/useCustomerSite'
+import { describeClientSubscription } from '../utils/client-subscription'
 import useUser from '../composables/useUser'
 
 const {
@@ -359,21 +237,6 @@ const emit = defineEmits<{
 }>()
 
 /* ── CONSTANTS ── */
-const PLAN_TYPE_OPTIONS = [
-  'Free (Bundle)',
-  'Paid (Bundle)',
-  'Paid (Custom App)'
-]
-const AUTO_RENEWAL_OPTIONS = ['No', 'Yes']
-const BILLING_CYCLE_OPTIONS = ['Monthly', 'Annually']
-const STATUS_OPTIONS = ['Active', 'Suspend']
-
-// Subscription plan options keyed by billing cycle (annotation from mockup)
-const SUBSCRIPTION_PLAN_BY_CYCLE: Record<string, string[]> = {
-  Monthly: ['Standard Plan', 'Premium Plan'],
-  Annually: ['Standard Plan', 'Premium Plan']
-}
-
 const PHONE_RULES: Record<string, number> = {
   '+60': 9,
   '+61': 9,
@@ -399,31 +262,15 @@ const form = reactive({
   organizationName: '',
   phone: '',
 
-  planType: 'Paid (Bundle)',
-  autoRenewal: 'Yes',
-  billingCycle: 'Monthly',
-  status: 'Active',
-  subscriptionPlan: 'Standard Plan',
-
-  startDate: '',
-  endDate: '',
-
   includedApps: [] as string[],
 
   sites: [] as SiteRow[]
 })
 
 /* ── COMPUTED ── */
-const subscriptionPlanOptions = computed(
-  () => SUBSCRIPTION_PLAN_BY_CYCLE[form.billingCycle] ?? []
-)
-
-/* ── WATCH: keep subscription plan valid when billing cycle changes ── */
-watch(subscriptionPlanOptions, options => {
-  if (!options.includes(form.subscriptionPlan)) {
-    form.subscriptionPlan = options[0] ?? ''
-  }
-})
+// The row the Client List already fetched carries the subscription sub-document,
+// so the drawer says exactly what the list says - no second, disagreeing source.
+const subscription = computed(() => describeClientSubscription(props.client))
 
 watch(
   () => form.name,
@@ -454,10 +301,6 @@ watch([phonePrefix, phoneNumber], ([prefix, value]) => {
 })
 
 /* ── EVENTS ── */
-function onBillingCycleChange() {
-  // Start / End date are derived from billing cycle and are not editable.
-  // Recompute or refetch here as needed once wired to a real API.
-}
 function validateForm() {
   errors.name = ''
   errors.organizationName = ''
@@ -660,10 +503,6 @@ watch(
   gap: 20px;
   margin-bottom: 14px;
 }
-.row-single {
-  grid-template-columns: 1fr;
-}
-
 .field {
   display: flex;
   flex-direction: column;
@@ -697,68 +536,17 @@ watch(
   color: var(--text2);
 }
 
-/* ===== SELECT ===== */
-.select-wrap {
-  position: relative;
-}
-.select-wrap select {
-  width: 100%;
-  height: 38px;
-  border: 1px solid var(--border);
-  border-radius: var(--r-inner);
-  padding: 0 30px 0 12px;
-  font-size: 13px;
+/* ===== READ-ONLY VALUES ===== */
+/* A value the staff member reads rather than edits. */
+.read-value {
+  font-size: 14px;
   color: var(--text);
-  background: var(--card);
-  appearance: none;
-  cursor: pointer;
-  outline: none;
-}
-.select-wrap select:focus {
-  border-color: var(--muted);
-}
-.select-wrap .chevron {
-  position: absolute;
-  right: 11px;
-  top: 50%;
-  transform: translateY(-50%);
-  width: 10px;
-  height: 6px;
-  pointer-events: none;
-}
-
-/* ===== DATE ===== */
-.date-input {
-  position: relative;
-  display: flex;
-  align-items: center;
-}
-.date-input input {
-  width: 100%;
-  height: 38px;
-  border: 1px solid var(--border);
-  border-radius: var(--r-inner);
-  padding: 0 34px 0 12px;
-  font-size: 13px;
-  color: var(--text2);
-  background: var(--bg);
-  outline: none;
-}
-.date-input svg {
-  position: absolute;
-  right: 12px;
-  pointer-events: none;
-}
-
-/* ===== HINT ===== */
-.hint {
-  font-size: 11px;
-  color: var(--text2);
-  line-height: 1.4;
-}
-.hint-below {
-  margin-top: 4px;
+  padding: 10px 0;
+  min-height: 20px;
 }
+.sub-none { font-size: 14px; color: var(--text2); }
+/* Owner decision 8: an end date has passed and somebody has to look at it. */
+.needs-attention { color: var(--warn); font-weight: 500; }
 
 /* ===== INCLUDED APPS ===== */
 .app-list {

package/components/ClientMain.vue

@@ -37,19 +37,6 @@
               </svg>
             </div>
 
-            <div class="filter-field">
-              <label>Filter by plan type</label>
-              <select v-model="filterPlan" @change="handleFilterChange">
-                <option value="">All</option>
-                <option v-for="app in APP_LIST" :key="app.value" :value="app.value">
-                  {{ app.title }}
-                </option>
-              </select>
-              <svg class="chevron" viewBox="0 0 10 6" fill="none">
-                <path d="M1 1l4 4 4-4" stroke="#6B7280" stroke-width="1.4" stroke-linecap="round"/>
-              </svg>
-            </div>
-
             <div class="filter-field">
               <label>Filter by billing cycle</label>
               <select v-model="filterBilling" @change="handleFilterChange">
@@ -111,10 +98,10 @@
                 <th>Organization Name</th>
                 <th>Email</th>
                 <th>Sites</th>
-                <th>Plan Type</th>
+                <th>Subscription</th>
                 <th>Billing Cycle</th>
-                <th>Subscription Start</th>
-                <th>Subscription End</th>
+                <th>Start Date</th>
+                <th>End Date</th>
                 <th>Status</th>
                 <th>Actions</th>
               </tr>
@@ -129,28 +116,43 @@
                 <td>
                   <span class="sites-badge">{{ item.sites }}</span>
                 </td>
-                <td>{{ item.planType }}</td>
-                <td class="td-muted">{{ item.billingCycle }}</td>
-                <td>
-                  <span class="date-cell">
-                    <svg viewBox="0 0 16 16" fill="none" width="13" height="13">
-                      <rect x="1" y="3" width="14" height="12" rx="2" stroke="#9CA3AF" stroke-width="1.3"/>
-                      <path d="M1 7h14" stroke="#9CA3AF" stroke-width="1.3"/>
-                      <path d="M5 1v3M11 1v3" stroke="#9CA3AF" stroke-width="1.3" stroke-linecap="round"/>
-                    </svg>
-                    {{ item.subscriptionStart }}
-                  </span>
-                </td>
-                <td>
-                  <span class="date-cell">
-                    <svg viewBox="0 0 16 16" fill="none" width="13" height="13">
-                      <rect x="1" y="3" width="14" height="12" rx="2" stroke="#9CA3AF" stroke-width="1.3"/>
-                      <path d="M1 7h14" stroke="#9CA3AF" stroke-width="1.3"/>
-                      <path d="M5 1v3M11 1v3" stroke="#9CA3AF" stroke-width="1.3" stroke-linecap="round"/>
-                    </svg>
-                    {{ item.subscriptionEnd }}
-                  </span>
+                <!--
+                  A client nobody has set up yet used to print four dashes here,
+                  which reads as a broken screen. It is one ordinary state, so it
+                  is said once, in words.
+                -->
+                <td v-if="item.sub.state === 'none'" colspan="4" class="sub-none">
+                  No subscription set up
                 </td>
+
+                <template v-else>
+                  <td>
+                    <span class="sub-label" :class="{ 'needs-attention': item.sub.needsAttention }">
+                      {{ item.sub.label }}
+                    </span>
+                  </td>
+                  <td class="td-muted">{{ item.sub.billingCycle }}</td>
+                  <td>
+                    <span class="date-cell">
+                      <svg viewBox="0 0 16 16" fill="none" width="13" height="13">
+                        <rect x="1" y="3" width="14" height="12" rx="2" stroke="#9CA3AF" stroke-width="1.3"/>
+                        <path d="M1 7h14" stroke="#9CA3AF" stroke-width="1.3"/>
+                        <path d="M5 1v3M11 1v3" stroke="#9CA3AF" stroke-width="1.3" stroke-linecap="round"/>
+                      </svg>
+                      {{ item.sub.start }}
+                    </span>
+                  </td>
+                  <td>
+                    <span class="date-cell" :class="{ 'needs-attention': item.sub.needsAttention }">
+                      <svg viewBox="0 0 16 16" fill="none" width="13" height="13">
+                        <rect x="1" y="3" width="14" height="12" rx="2" stroke="#9CA3AF" stroke-width="1.3"/>
+                        <path d="M1 7h14" stroke="#9CA3AF" stroke-width="1.3"/>
+                        <path d="M5 1v3M11 1v3" stroke="#9CA3AF" stroke-width="1.3" stroke-linecap="round"/>
+                      </svg>
+                      {{ item.sub.end }}
+                    </span>
+                  </td>
+                </template>
                 <td>
                   <span :class="['status-chip', item.status]">{{ item.status }}</span>
                 </td>
@@ -272,7 +274,7 @@ import useRole from '../composables/useRole'
 import InvitationClientForm from './InvitationClientForm.vue'
 import ClientDetailForm from './ClientDetailForm.vue'
 import useCustomerSite from '../composables/useCustomerSite'
-import useSubscription from '../composables/useSubscription'
+import { describeClientSubscription } from '../utils/client-subscription'
 
 
 /* ── TYPES ── */
@@ -282,7 +284,6 @@ type TabStatus = 'active' | 'suspended' | 'pending'
 const { getOrganizationsWithSubscription, updateStatus } = useOrg()
 const { getVerifications, cancelUserInvitation } = useVerification()
 const { getCustomerSites: getCustomerSitesByOrgId } = useCustomerSite()
-const { getByOrgId: getSubscriptionByOrgId } = useSubscription()
 const { getRoleById } = useRole()
 
 /* ── CONSTANTS ── */
@@ -306,7 +307,6 @@ const tableScrollEl   = ref<HTMLElement | null>(null)
 
 // filterStatus
 const filterStatus    = ref<'active' | 'suspended'>('active')
-const filterPlan      = ref('')   // '' = All | any APP_LIST value
 const filterBilling   = ref('')   // '' = All | 'monthly' | 'yearly'
 
 const items           = ref<any[]>([])
@@ -338,21 +338,6 @@ const activeMenuItem = computed(() =>
 )
 
 /* ── HELPERS ── */
-function formatDate(date?: string | Date) {
-  if (date == null || date === '') return '-'
-  const d = date instanceof Date ? date : new Date(date as string)
-  return isNaN(d.getTime()) ? '-' : d.toLocaleDateString('en-US')
-}
-
-function planTypeLabel(sub: Record<string, any>) {
-  if (!sub) return '-'
-  if (sub.paidType) return String(sub.paidType)
-  if (sub.type === 'organization') return 'Organization'
-  if (sub.type === 'affiliate')    return 'Affiliate'
-  const desc = String(sub.description || '').trim()
-  return desc ? (desc.length > 48 ? `${desc.slice(0, 45)}…` : desc) : '-'
-}
-
 async function resolveRoleName(id: string) {
   if (!id) return '-'
   if (roleCache.value[id]) return roleCache.value[id]
@@ -418,7 +403,6 @@ async function fetchOrgs(status: 'active' | 'suspended') {
       search: search.value,
       limit: limit.value,
       status,
-      type: filterPlan.value,
       billingCycle: filterBilling.value,
     })
 
@@ -428,8 +412,6 @@ async function fetchOrgs(status: 'active' | 'suspended') {
 
     items.value = await Promise.all(
       orgs.map(async (org: any) => {
-        const sub = org?.subscription ?? {}
-
         let siteCount = siteCache[org._id]
 
         if (siteCount === undefined) {
@@ -444,18 +426,14 @@ async function fetchOrgs(status: 'active' | 'suspended') {
         }
 
         return {
-  ...org,
-
-  planType: planTypeLabel(sub),
+          ...org,
 
-  billingCycle: sub?.billingCycle ?? "-",
+          sub: describeClientSubscription(org),
 
-  subscriptionStart: formatDate(sub?.createdAt),
-
-  subscriptionEnd: formatDate(sub?.nextBillingDate),
-
-  sites: `${siteCount} Sites`,
-}
+          // The column header already says Sites, so the badge is the number.
+          // (It also used to read "1 Sites".)
+          sites: siteCount,
+        }
       })
     )
 
@@ -869,6 +847,12 @@ tbody tr:hover { background: var(--thead); }
 tbody td { vertical-align: middle; }
 
 .empty { text-align: center; color: var(--muted); padding: 48px 0 !important; }
+
+/* A client nobody has set up yet: plainly stated, not shouted, not a dash. */
+.sub-none { color: var(--text2); font-size: 13px; }
+.sub-label { font-size: 13px; }
+/* Owner decision 8: an end date has passed and somebody has to look at it. */
+.needs-attention { color: var(--warn); font-weight: 500; }
 .td-name { font-weight: 500; color: var(--text); }
 .td-muted { color: var(--muted); font-size: 13px; }
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "3.2.8-staging.202",
+  "version": "3.2.8-staging.203",
   "author": "7365admin1",
   "main": "./nuxt.config.ts",
   "//files": "What a consumer extending this layer actually loads. Without this npm ships the whole working tree - the changesets, the CI workflows, the render harness in tools/ and any scratch directory that happened to exist at publish time. Nuxt resolves a layer by directory, so every runtime directory below has to stay listed; adding a new top-level runtime directory means adding it here too.",

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,
+  };
+}