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

package/components/ClientDetailForm.vue

@@ -79,7 +79,17 @@
       a separate piece of work with a real endpoint behind it.
     -->
     <section class="section">
-      <h3>Subscription Information</h3>
+      <div class="section-head">
+        <h3>Subscription Information</h3>
+        <!--
+          The values stay read-only - they are what the client's record says.
+          Changing them is a real form with real rules behind it, so this opens
+          that rather than pretending a dropdown here would save anything.
+        -->
+        <button class="btn-manage-sub" @click="$emit('manage-subscription')">
+          {{ subscription.state === 'none' ? 'Set up subscription' : 'Edit subscription' }}
+        </button>
+      </div>
 
       <p v-if="subscription.state === 'none'" class="sub-none">
         No subscription set up for this client yet.
@@ -234,6 +244,7 @@ const props = defineProps<{
 const emit = defineEmits<{
   (e: 'cancel'): void
   (e: 'submit', payload: Record<string, any>): void
+  (e: 'manage-subscription'): void
 }>()
 
 /* ── CONSTANTS ── */
@@ -490,6 +501,29 @@ watch(
 .section {
   margin-bottom: 26px;
 }
+.section-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.section-head h3 {
+  margin-bottom: 0;
+}
+.btn-manage-sub {
+  padding: 6px 14px;
+  font-size: 12px;
+  font-weight: 600;
+  border: 1px solid var(--border);
+  border-radius: var(--r-pill);
+  background: var(--card);
+  color: var(--accent-text);
+  cursor: pointer;
+  white-space: nowrap;
+  margin-bottom: 14px;
+}
+.btn-manage-sub:hover { background: var(--hover); }
 .section h3 {
   font-size: 15px;
   font-weight: 700;

package/components/ClientMain.vue

@@ -56,6 +56,11 @@
       <div class="table-card">
 
         <!-- Toolbar row -->
+        <div v-if="savedNote" class="saved-note" role="status">
+          {{ savedNote }}
+          <button class="saved-note-close" @click="savedNote = ''">&times;</button>
+        </div>
+
         <div class="toolbar">
           <div class="toolbar-left">
             <button class="refresh-btn" :class="{ spinning: loading }" @click="handleRefresh">
@@ -123,6 +128,9 @@
                 -->
                 <td v-if="item.sub.state === 'none'" colspan="4" class="sub-none">
                   No subscription set up
+                  <button class="sub-setup-btn" @click="openSubscription(item)">
+                    Set up subscription
+                  </button>
                 </td>
 
                 <template v-else>
@@ -212,9 +220,24 @@
         :client="selectedClient"
         @cancel="cancelView"
         @submit="submitClient"
+        @manage-subscription="openSubscription(selectedClient)"
       />
     </div>
 
+    <!--
+      SET UP OR CHANGE A CLIENT'S SUBSCRIPTION. Opened from the row that has
+      none, from the row menu, or from the client's own drawer - all three land
+      here, so there is one form and one set of rules behind them.
+    -->
+    <ClientSubscriptionForm
+      v-if="subscriptionClient"
+      :org-id="subscriptionClient._id"
+      :client-name="subscriptionClient.name"
+      :site-count="subscriptionClient.sites"
+      @cancel="subscriptionClient = null"
+      @saved="onSubscriptionSaved"
+    />
+
     <div v-if="dialog" class="overlay" @click.self="dialog = false">
       <div class="dialog-box">
         <InvitationClientForm title="Invite Client" @success="handleSuccess" @cancel="dialog = false" />
@@ -247,6 +270,9 @@
         <button class="dd-item" @click="viewClient(activeMenuItem)">
           View Organization
         </button>
+        <button class="dd-item" @click="openSubscription(activeMenuItem)">
+          {{ activeMenuItem?.sub?.state === 'none' ? 'Set up subscription' : 'Edit subscription' }}
+        </button>
         <button
           v-if="activeMenuItem?.status === 'suspended'"
           class="dd-item"
@@ -273,6 +299,7 @@ import useVerification from '../composables/useVerification'
 import useRole from '../composables/useRole'
 import InvitationClientForm from './InvitationClientForm.vue'
 import ClientDetailForm from './ClientDetailForm.vue'
+import ClientSubscriptionForm from './ClientSubscriptionForm.vue'
 import useCustomerSite from '../composables/useCustomerSite'
 import { describeClientSubscription } from '../utils/client-subscription'
 
@@ -321,6 +348,10 @@ const roleCache       = ref<Record<string, string>>({})
 const viewMode        = ref<'table' | 'detail'>('table')
 const selectedClient  = ref<any>(null)
 
+/* subscription set-up / edit */
+const subscriptionClient = ref<any>(null)
+const savedNote          = ref('')
+
 /* suspend confirmation */
 const confirmSuspendItem    = ref<any>(null)
 const confirmSuspendLoading = ref(false)
@@ -372,6 +403,30 @@ async function activateClient(item: any) {
   }
 }
 
+/* ── SUBSCRIPTION ── */
+function openSubscription(item: any) {
+  if (!item?._id) return
+  savedNote.value = ''
+  subscriptionClient.value = item
+  closeMenu()
+}
+
+async function onSubscriptionSaved(message: string) {
+  subscriptionClient.value = null
+  savedNote.value = message
+  // The list derives every subscription state from the record itself, so
+  // re-reading it is all that is needed for the row to tell the truth again.
+  await fetchData()
+
+  // The drawer reads the same row, so if it is open it has to be handed the
+  // refreshed one - otherwise it would still be showing what was true before
+  // the save.
+  if (selectedClient.value?._id) {
+    selectedClient.value =
+      items.value.find(i => i._id === selectedClient.value._id) ?? selectedClient.value
+  }
+}
+
 /* ── SUSPEND CONFIRMATION ── */
 function askSuspend(item: any) {
   confirmSuspendItem.value = item
@@ -850,6 +905,44 @@ tbody td { vertical-align: middle; }
 
 /* A client nobody has set up yet: plainly stated, not shouted, not a dash. */
 .sub-none { color: var(--text2); font-size: 13px; }
+/* The way in, said next to the state it fixes. It sits in a cell that already
+   spans four columns, so it adds no width to the table. */
+.sub-setup-btn {
+  margin-left: 10px;
+  padding: 3px 10px;
+  font-size: 12px;
+  font-weight: 600;
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  background: var(--card);
+  color: var(--accent-text);
+  cursor: pointer;
+  white-space: nowrap;
+}
+.sub-setup-btn:hover { background: var(--hover); }
+
+.saved-note {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  margin: 12px 16px 0;
+  padding: 9px 12px;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  background: var(--ok-bg);
+  color: var(--text);
+  font-size: 13px;
+  font-weight: 600;
+}
+.saved-note-close {
+  border: none;
+  background: none;
+  color: var(--text2);
+  font-size: 16px;
+  line-height: 1;
+  cursor: pointer;
+}
 .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; }

package/components/ClientSubscriptionForm.vue

@@ -0,0 +1,527 @@
+<template>
+  <div class="overlay" @click.self="close">
+    <div class="sub-dialog" role="dialog" aria-modal="true" aria-labelledby="sub-dialog-title">
+
+      <!-- ===== HEADER ===== -->
+      <div class="sub-head">
+        <h3 id="sub-dialog-title">
+          {{ isEdit ? 'Edit subscription' : 'Set up subscription' }}
+        </h3>
+        <p class="sub-sub">{{ clientName }}</p>
+      </div>
+
+      <!-- ===== BODY ===== -->
+      <div class="sub-body">
+
+        <p v-if="loading" class="sub-loading">Loading this client's subscription…</p>
+
+        <template v-else>
+          <!--
+            One message at a time, and always a sentence a person can act on.
+            The API's own refusals are written for a reader, so when the server
+            says no this is exactly what the server said.
+          -->
+          <p v-if="problem" class="sub-error" role="alert">{{ problem }}</p>
+
+          <!-- Plan -->
+          <div class="sub-field">
+            <label for="sub-plan">Plan</label>
+            <select id="sub-plan" v-model="values.plan" :disabled="saving">
+              <option value="">Choose a plan</option>
+              <option v-for="p in plans" :key="p._id" :value="p._id">
+                {{ planOptionLabel(p) }}
+              </option>
+            </select>
+            <span v-if="!plansLoading && plans.length === 0" class="sub-hint">
+              No active plans exist yet, so there is nothing to put this client on.
+            </span>
+          </div>
+
+          <!-- Charging -->
+          <fieldset class="sub-field">
+            <legend>Charging</legend>
+            <label class="sub-radio">
+              <input
+                type="radio"
+                name="billingMode"
+                :value="BILLING_COMPLIMENTARY"
+                v-model="values.billingMode"
+                :disabled="saving"
+              />
+              <span>
+                <strong>Complimentary (not charged)</strong>
+                <em>Free use, with a real start and end date Seven365 monitors.</em>
+              </span>
+            </label>
+            <label class="sub-radio">
+              <input
+                type="radio"
+                name="billingMode"
+                :value="BILLING_PAID"
+                v-model="values.billingMode"
+                :disabled="saving"
+              />
+              <span>
+                <strong>Paying</strong>
+                <em>Charged the monthly value below. Payment is taken by Red Dot, not here.</em>
+              </span>
+            </label>
+          </fieldset>
+
+          <!-- Dates: native pickers, because the browser already has one -->
+          <div class="sub-row">
+            <div class="sub-field">
+              <label for="sub-start">Start date</label>
+              <input id="sub-start" v-model="values.startDate" type="date" :disabled="saving" />
+            </div>
+            <div class="sub-field">
+              <label for="sub-end">End date</label>
+              <input id="sub-end" v-model="values.endDate" type="date" :disabled="saving" />
+              <span class="sub-hint">Required. Every client has one, free or not.</span>
+            </div>
+          </div>
+
+          <!--
+            WHAT THIS MEANS FOR THIS CLIENT. A plan is priced per site, per
+            month, so the person is shown the arithmetic already done: the
+            per-site price, this client's live site count, and the monthly
+            value that comes out of the two.
+          -->
+          <div class="sub-value">
+            <div class="sub-value-line">
+              <span class="sub-value-label">Monthly value</span>
+              <span class="sub-value-figure" :class="{ 'is-free': isComplimentary }">
+                {{ formatMoney(monthly) }}
+                <span v-if="isComplimentary" class="sub-free-badge">not charged — complimentary</span>
+              </span>
+            </div>
+            <p class="sub-value-working">
+              {{ workingLine }}
+            </p>
+            <p v-if="siteCount === 0" class="sub-hint">
+              This client has no sites yet, so the monthly value is
+              {{ formatMoney(0) }} until sites are added.
+            </p>
+            <!-- Owner decision 5: switching a client from free to paying is an
+                 ordinary change of state, so it is worth naming when it is
+                 about to happen rather than letting it pass silently. -->
+            <p v-if="wasComplimentary && !isComplimentary" class="sub-hint sub-hint-strong">
+              This changes {{ clientName }} from complimentary to paying.
+            </p>
+            <p v-if="isEdit && changedValue" class="sub-hint sub-hint-strong">
+              Monthly value changes from {{ formatMoney(originalMonthly) }} to
+              {{ formatMoney(monthly) }}.
+            </p>
+          </div>
+        </template>
+      </div>
+
+      <!-- ===== FOOTER ===== -->
+      <div class="sub-actions">
+        <button class="btn-cancel" :disabled="saving" @click="close">Cancel</button>
+        <button class="btn-save" :disabled="saving || loading" @click="save">
+          <span v-if="saving" class="spinner spinner-light" />
+          <span v-else>{{ isEdit ? 'Save changes' : 'Set up subscription' }}</span>
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+/**
+ * SET UP A CLIENT'S SUBSCRIPTION, OR CHANGE THE ONE THEY HAVE.
+ *
+ * The same four questions either way, so there is one form and not two: which
+ * plan, complimentary or paying, from when, until when. Editing simply arrives
+ * with the answers already filled in.
+ *
+ * It talks to the three staff-only console endpoints
+ * (`/api/subscriptions/console/:id`, where `:id` is the CLIENT'S organisation).
+ * It cannot suspend or reactivate anybody - that is Phase 3, and the edit
+ * endpoint does not accept a status, so there is deliberately no control here
+ * that could set one. It takes no card details and calls no payment gateway:
+ * Red Dot is the payment provider and none of that belongs on a staff screen.
+ */
+import { computed, onMounted, reactive, ref } from 'vue'
+import useSubscription from '../composables/useSubscription'
+import useSubscriptionPlan from '../composables/useSubscriptionPlan'
+import {
+  BILLING_COMPLIMENTARY,
+  BILLING_PAID,
+  buildConsolePayload,
+  formatMoney,
+  formValuesFrom,
+  monthlyValue,
+  planOptionLabel,
+  readApiError,
+  validateConsoleSubscription,
+  type TPlanOption,
+} from '../utils/subscription-form'
+
+const props = defineProps<{
+  /** The client's organisation id - what `:id` on the console routes means. */
+  orgId: string
+  clientName?: string
+  /** The live site count the Client List already fetched. Never typed in. */
+  siteCount?: number
+}>()
+
+const emit = defineEmits<{
+  (e: 'cancel'): void
+  (e: 'saved', message: string): void
+}>()
+
+const {
+  getConsoleSubscriptionByOrgId,
+  setUpConsoleSubscription,
+  updateConsoleSubscription,
+} = useSubscription()
+const { getAll: getPlans } = useSubscriptionPlan()
+
+const plans = ref<TPlanOption[]>([])
+const plansLoading = ref(true)
+const loading = ref(true)
+const saving = ref(false)
+const problem = ref('')
+
+const existing = ref<Record<string, any> | null>(null)
+const values = reactive(formValuesFrom(null))
+const originalValues = reactive(formValuesFrom(null))
+
+const clientName = computed(() => props.clientName || 'this client')
+const siteCount = computed(() => Number(props.siteCount ?? 0))
+const isEdit = computed(() => Boolean(existing.value?._id))
+const isComplimentary = computed(() => values.billingMode === BILLING_COMPLIMENTARY)
+const wasComplimentary = computed(
+  () => isEdit.value && originalValues.billingMode === BILLING_COMPLIMENTARY,
+)
+
+const selectedPlan = computed(
+  () => plans.value.find(p => String(p._id) === String(values.plan)) ?? null,
+)
+const monthly = computed(() =>
+  isComplimentary.value ? 0 : monthlyValue(selectedPlan.value, siteCount.value),
+)
+const originalMonthly = computed(() => {
+  if (originalValues.billingMode === BILLING_COMPLIMENTARY) return 0
+  const plan = plans.value.find(p => String(p._id) === String(originalValues.plan))
+  return monthlyValue(plan, siteCount.value)
+})
+const changedValue = computed(() => originalMonthly.value !== monthly.value)
+
+/** The arithmetic, spelled out, so nobody has to work it out or trust it blind. */
+const workingLine = computed(() => {
+  const sites = siteCount.value
+  const plural = sites === 1 ? 'site' : 'sites'
+  if (!selectedPlan.value) return `${sites} ${plural}. Choose a plan to see the monthly value.`
+
+  const price = formatMoney(Number(selectedPlan.value.price ?? 0))
+  const gross = formatMoney(monthlyValue(selectedPlan.value, sites))
+
+  return isComplimentary.value
+    ? `${price} per site, per month x ${sites} ${plural} = ${gross} - waived while this client is complimentary.`
+    : `${price} per site, per month x ${sites} ${plural} = ${gross}.`
+})
+
+async function load() {
+  // The plan list and the client's current record are independent reads, so
+  // they go together rather than one after the other.
+  const [planResult, subResult] = await Promise.allSettled([
+    getPlans({ limit: 100, status: 'active' }),
+    getConsoleSubscriptionByOrgId(props.orgId),
+  ])
+
+  if (planResult.status === 'fulfilled') {
+    const res: any = planResult.value
+    plans.value = res?.items ?? res?.data?.items ?? []
+  } else {
+    problem.value = readApiError(
+      planResult.reason,
+      'The plan list could not be loaded, so there is nothing to choose from yet. Try again in a moment.',
+    )
+  }
+  plansLoading.value = false
+
+  if (subResult.status === 'fulfilled') {
+    // A client with no subscription is answered as 200 with null. That is the
+    // state most clients are in, not an error - it just means "set one up".
+    existing.value = (subResult.value as any) ?? null
+  } else {
+    problem.value = readApiError(
+      subResult.reason,
+      'This client\'s subscription could not be read. Try again in a moment.',
+    )
+  }
+
+  Object.assign(values, formValuesFrom(existing.value))
+  Object.assign(originalValues, formValuesFrom(existing.value))
+  loading.value = false
+}
+
+async function save() {
+  problem.value = ''
+
+  const payload = buildConsolePayload(values, plans.value, siteCount.value)
+  const refusal = validateConsoleSubscription(payload, plans.value)
+  if (refusal) {
+    problem.value = refusal
+    return
+  }
+
+  saving.value = true
+  try {
+    if (isEdit.value) {
+      await updateConsoleSubscription(props.orgId, payload)
+      emit('saved', 'Subscription updated.')
+    } else {
+      await setUpConsoleSubscription(props.orgId, payload)
+      emit('saved', 'Subscription set up.')
+    }
+  } catch (error: any) {
+    problem.value = readApiError(
+      error,
+      'That could not be saved. Check the details and try again.',
+    )
+  } finally {
+    saving.value = false
+  }
+}
+
+function close() {
+  if (saving.value) return
+  emit('cancel')
+}
+
+onMounted(load)
+</script>
+
+<style scoped>
+.overlay {
+  position: fixed;
+  inset: 0;
+  background: var(--scrim);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+  padding: 16px;
+}
+
+.sub-dialog {
+  background: var(--card);
+  border-radius: 12px;
+  width: 100%;
+  max-width: 520px;
+  max-height: 90vh;
+  overflow-y: auto;
+  box-shadow: var(--shadow-modal);
+}
+
+.sub-head {
+  padding: 20px 24px 12px;
+  border-bottom: 1px solid var(--border);
+}
+.sub-head h3 {
+  font-size: 16px;
+  font-weight: 700;
+  color: var(--text);
+  margin: 0;
+}
+.sub-sub {
+  font-size: 13px;
+  color: var(--text2);
+  margin: 4px 0 0;
+}
+
+.sub-body {
+  padding: 18px 24px 4px;
+}
+.sub-loading {
+  font-size: 13px;
+  color: var(--text2);
+  margin: 8px 0 18px;
+}
+
+.sub-error {
+  font-size: 13px;
+  line-height: 1.45;
+  color: var(--err);
+  background: var(--err-bg);
+  border: 1px solid var(--err-border);
+  border-radius: 8px;
+  padding: 10px 12px;
+  margin: 0 0 16px;
+}
+
+.sub-field {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  margin-bottom: 16px;
+  border: none;
+  padding: 0;
+  min-width: 0;
+}
+.sub-field label,
+.sub-field legend {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--text2);
+  padding: 0;
+}
+.sub-field select,
+.sub-field input[type="date"] {
+  height: 38px;
+  width: 100%;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  background: var(--card);
+  color: var(--text);
+  font-size: 13px;
+  padding: 0 10px;
+}
+.sub-field select:disabled,
+.sub-field input:disabled {
+  opacity: 0.6;
+}
+
+.sub-hint {
+  font-size: 12px;
+  line-height: 1.4;
+  color: var(--text2);
+}
+.sub-hint-strong {
+  color: var(--text);
+  font-weight: 600;
+}
+
+.sub-radio {
+  display: flex;
+  align-items: flex-start;
+  gap: 9px;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 10px 12px;
+  cursor: pointer;
+}
+.sub-radio input {
+  margin-top: 2px;
+  flex-shrink: 0;
+}
+.sub-radio strong {
+  display: block;
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--text);
+}
+.sub-radio em {
+  display: block;
+  font-style: normal;
+  font-size: 12px;
+  line-height: 1.4;
+  color: var(--text2);
+  margin-top: 2px;
+}
+
+.sub-row {
+  display: flex;
+  gap: 14px;
+}
+.sub-row .sub-field {
+  flex: 1 1 0;
+}
+
+.sub-value {
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 12px 14px;
+  margin-bottom: 18px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+.sub-value-line {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 12px;
+}
+.sub-value-label {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--text2);
+}
+.sub-value-figure {
+  font-size: 18px;
+  font-weight: 800;
+  color: var(--text);
+  text-align: right;
+}
+.sub-value-figure.is-free {
+  color: var(--text2);
+}
+.sub-free-badge {
+  display: block;
+  font-size: 11px;
+  font-weight: 700;
+  color: var(--text2);
+  margin-top: 2px;
+}
+.sub-value-working {
+  font-size: 12px;
+  line-height: 1.4;
+  color: var(--text2);
+  margin: 0;
+}
+
+.sub-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 10px;
+  padding: 14px 24px 20px;
+}
+.btn-cancel {
+  padding: 9px 18px;
+  font-size: 13px;
+  font-weight: 600;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  background: var(--card);
+  color: var(--text2);
+  cursor: pointer;
+}
+.btn-cancel:hover:not(:disabled) { background: var(--hover); }
+.btn-save {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 150px;
+  padding: 9px 18px;
+  font-size: 13px;
+  font-weight: 600;
+  border: none;
+  border-radius: 8px;
+  background: var(--accent-strong);
+  color: var(--on-accent-strong);
+  cursor: pointer;
+}
+.btn-save:hover:not(:disabled) { opacity: 0.88; }
+.btn-cancel:disabled,
+.btn-save:disabled { opacity: 0.7; cursor: not-allowed; }
+
+.spinner {
+  display: inline-block;
+  width: 12px;
+  height: 12px;
+  border: 1.5px solid rgba(255,255,255,0.5);
+  border-top-color: var(--card);
+  border-radius: 50%;
+  animation: spin 0.7s linear infinite;
+}
+@keyframes spin { to { transform: rotate(360deg); } }
+
+@media (max-width: 520px) {
+  .sub-row { flex-direction: column; gap: 0; }
+}
+</style>

package/composables/useSubscription.ts

@@ -112,6 +112,43 @@ export default function useSubscription() {
     );
   }
 
+  /**
+   * THE SEVEN365 STAFF CONSOLE. `:id` is the CLIENT'S ORGANISATION id, never a
+   * subscription id - the API reads the organisation from the URL and never
+   * from the body, so these cannot be pointed at another client by accident.
+   *
+   * A separate path from `/api/subscriptions/org/:id` on purpose: that one is
+   * what a client's own subscription screen calls, and locking it to Seven365
+   * staff would have broken them. These three are staff-only on the server.
+   *
+   * No card field, no gateway, no money - Red Dot handles payment.
+   */
+  function getConsoleSubscriptionByOrgId(orgId: string) {
+    return useNuxtApp().$api<Record<string, any> | null>(
+      `/api/subscriptions/console/${orgId}`
+    );
+  }
+
+  function setUpConsoleSubscription(orgId: string, value: Record<string, any>) {
+    return useNuxtApp().$api<Record<string, any>>(
+      `/api/subscriptions/console/${orgId}`,
+      {
+        method: "POST",
+        body: value,
+      }
+    );
+  }
+
+  function updateConsoleSubscription(orgId: string, value: Record<string, any>) {
+    return useNuxtApp().$api<Record<string, any>>(
+      `/api/subscriptions/console/${orgId}`,
+      {
+        method: "PUT",
+        body: value,
+      }
+    );
+  }
+
   function updateSeatsById({
     subscriptionId = "",
     seats = 0,
@@ -146,5 +183,8 @@ export default function useSubscription() {
     initOrgSubscription,
     getByAffiliateId,
     updateSeatsById,
+    getConsoleSubscriptionByOrgId,
+    setUpConsoleSubscription,
+    updateConsoleSubscription,
   };
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "3.2.8-staging.203",
+  "version": "3.2.8-staging.204",
   "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/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),
+  };
+}