@7365admin1/layer-common 3.2.8-staging.208 → 3.2.8-staging.210

package/components/HidQrCodeConfiguration.vue

@@ -616,7 +616,7 @@ async function openPermissionDialog(category: THidPermissionCategory | "intercom
       page: 1,
       limit: 500,
     });
-    permissionCandidates.value = response.items || [];
+    permissionCandidates.value = response.items ?? response.data?.items ?? [];
     selectedPermissionIds.value = new Set(
       permissionCandidates.value
         .filter((candidate) => category === "intercom" ? candidate.intercom : candidate.selected)

package/components/HidUserEnrollment.vue

@@ -936,7 +936,7 @@ async function loadSubjectCandidates() {
       page: 1,
       limit: 500,
     });
-    permissionCandidates.value = response.items || [];
+    permissionCandidates.value = response.items ?? response.data?.items ?? [];
   } finally {
     loadingSubjects.value = false;
   }

package/composables/useHidAmico.ts

@@ -80,11 +80,18 @@ type HidVisitorQrData = {
 type HidVisitorQrResponse = HidVisitorQrData | { data: HidVisitorQrData };
 
 type HidPermissionListResponse = {
-  items: THidPermissionCandidate[];
-  page: number;
-  pages: number;
-  pageRange: string;
-  limit: number;
+  items?: THidPermissionCandidate[];
+  page?: number;
+  pages?: number;
+  pageRange?: string;
+  limit?: number;
+  data?: {
+    items?: THidPermissionCandidate[];
+    page?: number;
+    pages?: number;
+    pageRange?: string;
+    limit?: number;
+  };
 };
 
 type HidFacialEnrollmentResult = {

package/composables/usePromoCode.ts

@@ -28,9 +28,66 @@ export default function usePromoCode() {
     });
   }
 
+  /** One record, by its id. The console's detail screen opens on this. */
+  function getById(id: string) {
+    return useNuxtApp().$api<Record<string, any>>(
+      `/api/promo-codes/id/${id}`,
+      {
+        method: "GET",
+      }
+    );
+  }
+
+  /**
+   * Edit a code.
+   *
+   * `code` is NOT sent. It is immutable on the server - a subscription records
+   * the promo code it was bought with as text, so renaming one rewrites every
+   * invoice that already quotes it. The API accepts a `code` key and ignores
+   * it; leaving it out of the body means the screen can never look as though
+   * it changed something it did not.
+   */
+  function update(id: string, value: Partial<TPromoCode>) {
+    const { code, ...body } = value as Record<string, any>;
+
+    return useNuxtApp().$api<Record<string, any>>(`/api/promo-codes/${id}`, {
+      method: "PUT",
+      body,
+    });
+  }
+
+  /** Turn a code off, or back on. The only two states staff may set. */
+  function updateStatus(id: string, status: "active" | "disabled") {
+    return useNuxtApp().$api<Record<string, any>>(
+      `/api/promo-codes/${id}/status`,
+      {
+        method: "PATCH",
+        body: { status },
+      }
+    );
+  }
+
+  /**
+   * Remove a code from the console.
+   *
+   * A SOFT delete on the server: the record stays and is marked disabled and
+   * deleted, because subscriptions and invoices quote the code they were
+   * bought with. It leaves the list and stops being redeemable; it is not
+   * erased.
+   */
+  function remove(id: string) {
+    return useNuxtApp().$api<Record<string, any>>(`/api/promo-codes/${id}`, {
+      method: "DELETE",
+    });
+  }
+
   return {
     add,
     getPromoCodes,
     getByCode,
+    getById,
+    update,
+    updateStatus,
+    remove,
   };
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "3.2.8-staging.208",
+  "version": "3.2.8-staging.210",
   "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/promo-code-form.test.ts

@@ -0,0 +1,437 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  promoExpiryDate,
+  promoCodeFormValues,
+  promoCodeUpdatePayload,
+  validatePromoCodeEdit,
+  promoCodeApiError,
+} from "./promo-code-form.ts";
+
+/**
+ * THE PROMO CODE EDITOR AND THE THREE WRITE CALLS BEHIND IT.
+ *
+ * Two halves, both pinned here:
+ *
+ *  1. the rules the edit form applies before it sends anything - taken from
+ *     the MERGED backend (`promoCodeUpdateSchema` in `@7365admin1/core`), not
+ *     from a guess about it;
+ *  2. what `usePromoCode()` actually puts on the wire. The composable is three
+ *     `$api` calls, and the thing that can silently be wrong about it is the
+ *     verb, the path or the body - a `PUT` to the wrong path, or a body that
+ *     carries `code` and so looks as though it renamed a code it cannot.
+ *
+ * The composable reaches for `useNuxtApp()`, which only exists inside a Nuxt
+ * app, so one stub stands in for it and records the call.
+ */
+
+const NOW = new Date(2026, 7, 20, 12, 0, 0); // 20 Aug 2026, midday
+
+// ---------------------------------------------------------------------------
+// The expiry rule
+// ---------------------------------------------------------------------------
+
+test("an expiry date is read as the END of its day, in both stored formats", () => {
+  // A code dated today is good for all of today, so a check at midday passes.
+  const usFormat = promoExpiryDate("08/20/2026");
+  assert.ok(usFormat);
+  assert.equal(usFormat!.getHours(), 23);
+  assert.ok(usFormat!.getTime() > NOW.getTime());
+
+  const iso = promoExpiryDate("2026-08-20");
+  assert.ok(iso);
+  assert.equal(iso!.getTime(), usFormat!.getTime());
+});
+
+test("a date that is not a date is no expiry at all, never an Invalid Date", () => {
+  assert.equal(promoExpiryDate(""), null);
+  assert.equal(promoExpiryDate(null), null);
+  assert.equal(promoExpiryDate("whenever"), null);
+  // Month 13 rolls into the next year in JavaScript rather than failing, so
+  // it is caught explicitly - otherwise 13/01/2026 would read as Jan 2027.
+  assert.equal(promoExpiryDate("13/01/2026"), null);
+});
+
+// ---------------------------------------------------------------------------
+// Loading a record into the form, and building the body back out
+// ---------------------------------------------------------------------------
+
+test("the form loads from the record and does NOT carry the code", () => {
+  const values = promoCodeFormValues({
+    _id: "652f1a2b3c4d5e6f70819293",
+    code: "WELCOME2026",
+    description: "Launch offer",
+    type: "fixed",
+    fixed_rate: 12,
+    expiresAt: "12/31/2026",
+    status: "active",
+  });
+
+  assert.equal((values as any).code, undefined);
+  assert.deepEqual(values, {
+    description: "Launch offer",
+    type: "fixed",
+    fixed_rate: 12,
+    expiresAt: "12/31/2026",
+    tiers: [],
+  });
+});
+
+test("a tiered record keeps its bands; a fixed one is given none", () => {
+  const tiered = promoCodeFormValues({
+    type: "tiered",
+    tiers: [{ min: 1, max: 10, price: 9 }, { min: 11, max: 0, price: 7 }],
+  });
+  assert.equal(tiered.tiers.length, 2);
+  assert.deepEqual(tiered.tiers[1], { min: 11, max: 0, price: 7 });
+
+  // A code stored as fixed but carrying leftover bands must not send them:
+  // `promoCodeUpdateSchema` FORBIDS `tiers` on a fixed code and would 400.
+  const fixed = promoCodeFormValues({
+    type: "fixed",
+    fixed_rate: 5,
+    tiers: [{ min: 1, max: 10, price: 9 }],
+  });
+  assert.deepEqual(fixed.tiers, []);
+});
+
+test("an empty record gives a usable, valid, fixed-price form", () => {
+  const values = promoCodeFormValues(null);
+  assert.deepEqual(values, {
+    description: "",
+    type: "fixed",
+    fixed_rate: 0,
+    expiresAt: "",
+    tiers: [],
+  });
+  assert.equal(validatePromoCodeEdit(promoCodeUpdatePayload(values), NOW), null);
+});
+
+test("the payload never contains code, _id or status", () => {
+  const payload = promoCodeUpdatePayload({
+    description: "Launch offer",
+    type: "fixed",
+    fixed_rate: 12,
+    expiresAt: "12/31/2026",
+    tiers: [],
+  });
+
+  assert.deepEqual(Object.keys(payload).sort(), [
+    "description",
+    "expiresAt",
+    "fixed_rate",
+    "type",
+  ]);
+});
+
+test("a tiered payload sends bands and no fixed_rate, and the reverse", () => {
+  const tiered = promoCodeUpdatePayload({
+    description: "",
+    type: "tiered",
+    fixed_rate: 99,
+    expiresAt: "",
+    tiers: [{ min: 1, max: 10, price: 9 }],
+  });
+  assert.deepEqual(tiered.tiers, [{ min: 1, max: 10, price: 9 }]);
+  assert.equal("fixed_rate" in tiered, false);
+
+  const fixed = promoCodeUpdatePayload({
+    description: "",
+    type: "fixed",
+    fixed_rate: 9,
+    expiresAt: "",
+    tiers: [{ min: 1, max: 10, price: 9 }],
+  });
+  assert.equal("tiers" in fixed, false);
+  assert.equal(fixed.fixed_rate, 9);
+});
+
+test("a price nobody has typed is NOT quietly saved as free", () => {
+  // `Number("")` is 0. Coercing a blank field would turn "not filled in" into
+  // "every seat is free" - a real price, saved without anyone choosing it.
+  const payload = promoCodeUpdatePayload({
+    description: "",
+    type: "fixed",
+    fixed_rate: "" as any,
+    expiresAt: "",
+    tiers: [],
+  });
+  assert.equal(payload.fixed_rate, "");
+  assert.match(
+    String(validatePromoCodeEdit(payload, NOW)),
+    /Enter a price per seat/
+  );
+
+  // A deliberate 0, however, is a real answer and goes through.
+  const free = promoCodeUpdatePayload({
+    description: "",
+    type: "fixed",
+    fixed_rate: 0,
+    expiresAt: "",
+    tiers: [],
+  });
+  assert.equal(free.fixed_rate, 0);
+  assert.equal(validatePromoCodeEdit(free, NOW), null);
+});
+
+test("band numbers typed as text reach the API as numbers", () => {
+  const payload = promoCodeUpdatePayload({
+    description: "",
+    type: "tiered",
+    fixed_rate: 0,
+    expiresAt: "",
+    tiers: [{ min: "1", max: "10", price: "9.5" } as any],
+  });
+  assert.deepEqual(payload.tiers, [{ min: 1, max: 10, price: 9.5 }]);
+});
+
+// ---------------------------------------------------------------------------
+// What the form refuses, in the API's terms
+// ---------------------------------------------------------------------------
+
+test("a valid edit is refused nothing", () => {
+  assert.equal(
+    validatePromoCodeEdit(
+      { type: "fixed", fixed_rate: 0, expiresAt: "", description: "" },
+      NOW
+    ),
+    null
+  );
+  assert.equal(
+    validatePromoCodeEdit(
+      {
+        type: "tiered",
+        tiers: [{ min: 1, max: 10, price: 9 }, { min: 11, max: 0, price: 7 }],
+        expiresAt: "12/31/2026",
+      },
+      NOW
+    ),
+    null
+  );
+});
+
+test("an expiry already in the past is refused, and says what to do", () => {
+  const message = validatePromoCodeEdit(
+    { type: "fixed", fixed_rate: 5, expiresAt: "01/01/2020" },
+    NOW
+  );
+  assert.match(String(message), /already passed/);
+  assert.match(String(message), /clear the date/);
+});
+
+test("TODAY is not in the past - a code expiring today is still savable", () => {
+  assert.equal(
+    validatePromoCodeEdit(
+      { type: "fixed", fixed_rate: 5, expiresAt: "08/20/2026" },
+      NOW
+    ),
+    null
+  );
+});
+
+test("no expiry at all is allowed - that is a code with no end date", () => {
+  assert.equal(
+    validatePromoCodeEdit({ type: "fixed", fixed_rate: 5, expiresAt: "" }, NOW),
+    null
+  );
+});
+
+test("an unreadable expiry names the format instead of guessing", () => {
+  assert.match(
+    String(
+      validatePromoCodeEdit(
+        { type: "fixed", fixed_rate: 5, expiresAt: "next Tuesday" },
+        NOW
+      )
+    ),
+    /MM\/DD\/YYYY/
+  );
+});
+
+test("a free BAND is refused, because Joi's positive() refuses it", () => {
+  const message = validatePromoCodeEdit(
+    { type: "tiered", tiers: [{ min: 1, max: 10, price: 0 }] },
+    NOW
+  );
+  assert.match(String(message), /^Band 1: /);
+  assert.match(String(message), /above 0/);
+  // ...and it says the way to actually make seats free, which is the other
+  // pricing shape. `fixed_rate` is `min(0)`, not `positive()`.
+  assert.equal(
+    validatePromoCodeEdit({ type: "fixed", fixed_rate: 0 }, NOW),
+    null
+  );
+});
+
+test("the refused band is named, not just 'a band'", () => {
+  assert.match(
+    String(
+      validatePromoCodeEdit(
+        {
+          type: "tiered",
+          tiers: [
+            { min: 1, max: 10, price: 9 },
+            { min: 11, max: 5, price: 7 },
+          ],
+        },
+        NOW
+      )
+    ),
+    /^Band 2: /
+  );
+});
+
+test("a band with no upper limit is allowed - 0 means 'and above'", () => {
+  assert.equal(
+    validatePromoCodeEdit(
+      { type: "tiered", tiers: [{ min: 5, max: 0, price: 7 }] },
+      NOW
+    ),
+    null
+  );
+});
+
+test("a tiered code with no bands is refused, and offers the other shape", () => {
+  assert.match(
+    String(validatePromoCodeEdit({ type: "tiered", tiers: [] }, NOW)),
+    /at least one quantity band/
+  );
+});
+
+test("a negative fixed price is refused; a missing one is refused too", () => {
+  assert.match(
+    String(validatePromoCodeEdit({ type: "fixed", fixed_rate: -1 }, NOW)),
+    /cannot be less than 0/
+  );
+  assert.match(
+    String(validatePromoCodeEdit({ type: "fixed", fixed_rate: "" }, NOW)),
+    /Enter a price per seat/
+  );
+});
+
+test("a code with no pricing shape is refused first, before anything else", () => {
+  assert.equal(
+    validatePromoCodeEdit({ expiresAt: "01/01/2020" }, NOW),
+    "Choose how this code prices seats."
+  );
+});
+
+// ---------------------------------------------------------------------------
+// What a refusal from the server reads like
+// ---------------------------------------------------------------------------
+
+test("the API's own wording is what the screen shows", () => {
+  assert.equal(
+    promoCodeApiError(
+      { response: { _data: { message: "Promo code not found." } } },
+      "Could not save."
+    ),
+    "Promo code not found."
+  );
+});
+
+test("'Not authorized.' is replaced with something a person can act on", () => {
+  const message = promoCodeApiError(
+    { data: { message: "Not authorized." } },
+    "Could not save."
+  );
+  assert.match(message, /Seven365 staff account/);
+  assert.match(message, /Ask a Seven365 administrator/);
+});
+
+test("an unreadable failure falls back rather than dumping the error", () => {
+  assert.equal(
+    promoCodeApiError(new Error("fetch failed"), "Could not save the changes."),
+    "Could not save the changes."
+  );
+});
+
+// ---------------------------------------------------------------------------
+// The composable: verb, path and body of every write
+// ---------------------------------------------------------------------------
+
+const calls: Array<{ path: string; options: any }> = [];
+
+(globalThis as any).useNuxtApp = () => ({
+  $api: (path: string, options: any = {}) => {
+    calls.push({ path, options });
+    return Promise.resolve({ message: "ok" });
+  },
+});
+
+const promoCodeApi = (await import("../composables/usePromoCode.ts")).default();
+
+function lastCall() {
+  return calls[calls.length - 1];
+}
+
+const ID = "652f1a2b3c4d5e6f70819293";
+
+test("getById reads the one record, from the path the API mounts", async () => {
+  await promoCodeApi.getById(ID);
+  assert.equal(lastCall().path, `/api/promo-codes/id/${ID}`);
+  assert.equal(lastCall().options.method, "GET");
+});
+
+test("update is a PUT to /api/promo-codes/:id", async () => {
+  await promoCodeApi.update(ID, {
+    description: "Launch offer",
+    type: "fixed",
+    fixed_rate: 12,
+    expiresAt: "12/31/2026",
+  } as any);
+
+  assert.equal(lastCall().path, `/api/promo-codes/${ID}`);
+  assert.equal(lastCall().options.method, "PUT");
+  assert.equal(lastCall().options.body.description, "Launch offer");
+});
+
+test("update NEVER sends code, however it is called", async () => {
+  // The screen loads a record and could easily send it back whole. `code` is
+  // immutable on the server; sending it would be accepted and dropped, and
+  // the person would watch a rename succeed and change nothing.
+  await promoCodeApi.update(ID, {
+    code: "RENAMED",
+    type: "fixed",
+    fixed_rate: 1,
+  } as any);
+
+  assert.equal("code" in lastCall().options.body, false);
+  assert.equal(lastCall().options.body.type, "fixed");
+});
+
+test("updateStatus is a PATCH carrying only the new status", async () => {
+  await promoCodeApi.updateStatus(ID, "disabled");
+  assert.equal(lastCall().path, `/api/promo-codes/${ID}/status`);
+  assert.equal(lastCall().options.method, "PATCH");
+  assert.deepEqual(lastCall().options.body, { status: "disabled" });
+
+  await promoCodeApi.updateStatus(ID, "active");
+  assert.deepEqual(lastCall().options.body, { status: "active" });
+});
+
+test("remove is a DELETE, with no body to get wrong", async () => {
+  await promoCodeApi.remove(ID);
+  assert.equal(lastCall().path, `/api/promo-codes/${ID}`);
+  assert.equal(lastCall().options.method, "DELETE");
+  assert.equal(lastCall().options.body, undefined);
+});
+
+test("the four reads and writes are all on the composable", () => {
+  for (const name of [
+    "add",
+    "getPromoCodes",
+    "getByCode",
+    "getById",
+    "update",
+    "updateStatus",
+    "remove",
+  ]) {
+    assert.equal(
+      typeof (promoCodeApi as any)[name],
+      "function",
+      `usePromoCode() is missing ${name}`
+    );
+  }
+});

package/utils/promo-code-form.ts

@@ -0,0 +1,246 @@
+/**
+ * THE STAFF CONSOLE'S PROMO CODE EDITOR, DECIDED IN ONE PLACE.
+ *
+ * A Seven365 staff member opens a code, changes what it prices or when it
+ * stops, turns it off, turns it back on, or removes it. Everything the screen
+ * has to be sure of before it sends the request is worked out here, so the
+ * form and the API can never disagree about what is wrong.
+ *
+ * WHAT THE SERVER ACTUALLY ENFORCES, read from the merged backend rather than
+ * assumed (`@7365admin1/core` `models/promo-code.model.ts` `promoCodeUpdate` /
+ * `promoCodeUpdateSchema`, mounted by `API-core` as `PUT /api/promo-codes/:id`,
+ * `PATCH /api/promo-codes/:id/status`, `DELETE /api/promo-codes/:id`):
+ *
+ *   - `code` is IMMUTABLE. The update schema accepts the key and drops it,
+ *     because a subscription records the promo code it was bought with as
+ *     text. The form must not offer to change it, or a person would watch a
+ *     save succeed and the code stay as it was.
+ *   - `type` is required and is "fixed" or "tiered".
+ *   - a tiered code needs at least one band; every band starts at 1 or more,
+ *     ends at or after where it starts (0 means "and above"), and is priced at
+ *     MORE than 0 - Joi's `positive()`, so a free band is refused.
+ *   - a fixed code needs a price of 0 or more; 0 is legal and means free.
+ *   - `expiresAt` is free text to the server. It refuses nothing, which is
+ *     exactly why a date already in the past is caught HERE: saving one is not
+ *     an error, it is a code that silently stops working. Since core #1885 the
+ *     shared lookup DOES refuse an expired or disabled code at checkout, so a
+ *     past date is now a real off-switch rather than a decoration.
+ *
+ * Refusals are returned one at a time and in the API's order. A list of five
+ * complaints about one form is harder to act on than the first thing to fix.
+ *
+ * Nothing here takes a card, quotes a total, or moves money. Red Dot is the
+ * payment provider (owner decision 1); a promo code sets a price per seat.
+ */
+
+// Imported rather than left to Nuxt's auto-import so this file also loads
+// under plain `node --test`, the same way `theme-aa-ledger.ts` imports
+// `theme.ts`. One reader of a failed request for the whole console.
+import { readApiError } from "./subscription-form.ts";
+
+/**
+ * `expiresAt` is stored as free text and this console writes MM/DD/YYYY, but
+ * nothing has ever stopped another caller storing ISO - so both are read.
+ * Returns the END of the expiry day: a code dated today is good all of today.
+ *
+ * Deliberately the same rule as the org app's `utils/promo-code.js` and core's
+ * `promo-code-currency.util.ts`. The three are separate copies on purpose -
+ * the org app's is plain JS so `node --test` loads it directly, and core's
+ * runs on the server - but they must never disagree in front of a customer,
+ * so any change to one belongs in all three.
+ */
+export function promoExpiryDate(value: any): Date | null {
+  if (!value) return null;
+  const raw = String(value).trim();
+  if (!raw) return null;
+
+  const parts = raw.match(/^(\d{1,2})\/(\d{1,2})\/(\d{4})$/);
+  if (parts) {
+    const [, m, d, y] = parts;
+    const date = new Date(Number(y), Number(m) - 1, Number(d), 23, 59, 59, 999);
+    // `new Date(2026, 12, ...)` rolls into the next year rather than failing.
+    return date.getMonth() === Number(m) - 1 ? date : null;
+  }
+
+  const iso = raw.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (iso) {
+    const [, y, m, d] = iso;
+    const date = new Date(Number(y), Number(m) - 1, Number(d), 23, 59, 59, 999);
+    return date.getMonth() === Number(m) - 1 ? date : null;
+  }
+
+  const parsed = new Date(raw);
+  return isNaN(parsed.getTime()) ? null : parsed;
+}
+
+/** Nothing typed yet. Not the same thing as a zero, which is a real price. */
+function isBlank(value: any): boolean {
+  return value === "" || value === null || value === undefined;
+}
+
+/** What the edit form holds while a person is filling it in. */
+export interface TPromoCodeFormValues {
+  description: string;
+  type: "fixed" | "tiered";
+  fixed_rate: number;
+  expiresAt: string;
+  tiers: Array<{ min: number; max: number; price: number }>;
+}
+
+/**
+ * Pre-fill the form from the record the API sent back.
+ *
+ * `code` is not a form value - it is not editable, so it is displayed from the
+ * record and never carried through the form where a change could reach it.
+ */
+export function promoCodeFormValues(
+  record: Record<string, any> | null | undefined
+): TPromoCodeFormValues {
+  const promo = record ?? {};
+  const type = promo.type === "tiered" ? "tiered" : "fixed";
+
+  return {
+    description: String(promo.description ?? ""),
+    type,
+    fixed_rate: Number(promo.fixed_rate ?? 0),
+    expiresAt: String(promo.expiresAt ?? ""),
+    tiers:
+      type === "tiered" && Array.isArray(promo.tiers)
+        ? promo.tiers.map((tier: any) => ({
+            min: Number(tier?.min ?? 1),
+            max: Number(tier?.max ?? 0),
+            price: Number(tier?.price ?? 0),
+          }))
+        : [],
+  };
+}
+
+/**
+ * The body `PUT /api/promo-codes/:id` takes, and nothing more.
+ *
+ * No `code`, no `_id`, no `status`. The API would accept and ignore all three;
+ * not sending them means this screen cannot appear to change something it
+ * cannot. `status` in particular has its own endpoint - folding it in here
+ * would give two answers to "is this code on".
+ */
+export function promoCodeUpdatePayload(
+  values: TPromoCodeFormValues
+): Record<string, any> {
+  const payload: Record<string, any> = {
+    description: values.description ?? "",
+    type: values.type,
+    expiresAt: values.expiresAt ?? "",
+  };
+
+  // The schema FORBIDS `tiers` on a fixed code, so each shape sends only the
+  // half that applies to it. `fixed_rate` is allowed either way but means
+  // nothing on a tiered code, and the server zeroes it there regardless.
+  if (values.type === "tiered") {
+    payload.tiers = (values.tiers ?? []).map((tier) => ({
+      min: Number(tier.min),
+      max: Number(tier.max),
+      price: Number(tier.price),
+    }));
+  } else {
+    // A blank price is passed through blank rather than quietly becoming 0.
+    // `Number("")` is 0, so coercing here would turn "they have not typed a
+    // price yet" into "every seat is free" - a real price, silently saved.
+    // The API refuses a blank `fixed_rate` too, so the two agree.
+    payload.fixed_rate = isBlank(values.fixed_rate)
+      ? ""
+      : Number(values.fixed_rate);
+  }
+
+  return payload;
+}
+
+/**
+ * Everything that must be true before the request goes out. Returns the ONE
+ * thing to tell the person, or `null` when there is nothing to tell them.
+ */
+export function validatePromoCodeEdit(
+  payload: Record<string, any>,
+  now: Date = new Date()
+): string | null {
+  if (payload?.type !== "fixed" && payload?.type !== "tiered") {
+    return "Choose how this code prices seats.";
+  }
+
+  if (payload.type === "fixed") {
+    const rate = Number(payload.fixed_rate);
+    if (isBlank(payload.fixed_rate) || !Number.isFinite(rate)) {
+      return "Enter a price per seat. Use 0 to make every seat free.";
+    }
+    if (rate < 0) {
+      return "The price per seat cannot be less than 0.";
+    }
+  }
+
+  if (payload.type === "tiered") {
+    const tiers = Array.isArray(payload.tiers) ? payload.tiers : [];
+    if (!tiers.length) {
+      return "Add at least one quantity band, or switch this code to one price for every seat.";
+    }
+
+    for (let i = 0; i < tiers.length; i++) {
+      const band = tiers[i] ?? {};
+      const where = "Band " + (i + 1) + ": ";
+      const min = Number(band.min);
+      const max = Number(band.max);
+      const price = Number(band.price);
+
+      if (!Number.isInteger(min) || min < 1) {
+        return where + "a band has to start at 1 seat or more.";
+      }
+      if (!Number.isInteger(max) || max < 0) {
+        return (
+          where +
+          "the upper limit has to be a whole number of seats, or no limit."
+        );
+      }
+      // `max: 0` is how the band editor stores "and above" - not a band that
+      // ends at zero seats, which is why the API allows it.
+      if (max !== 0 && max < min) {
+        return (
+          where + "the upper limit cannot be lower than where the band starts."
+        );
+      }
+      if (!Number.isFinite(price) || price <= 0) {
+        return (
+          where +
+          "every band needs a price above 0. To make seats free, use one price for every seat and set it to 0."
+        );
+      }
+    }
+  }
+
+  if (payload.expiresAt) {
+    const expiry = promoExpiryDate(payload.expiresAt);
+    if (!expiry) {
+      return "The expiry date is not a date we can read. Use MM/DD/YYYY.";
+    }
+    if (expiry.getTime() < now.getTime()) {
+      return "That expiry date has already passed, so the code would stop working the moment it is saved. Pick a date in the future, or clear the date to remove the expiry.";
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Turn a refused request into something a person can act on.
+ *
+ * `readApiError` is what every other console screen uses, and the API's promo
+ * messages are already written to be read - "Promo code not found.", "This
+ * promo code has expired." Only one answer needs rewording: the staff guard
+ * says "Not authorized.", which is true and tells nobody what to do next.
+ */
+export function promoCodeApiError(error: any, fallback: string): string {
+  const message = readApiError(error, fallback);
+
+  if (/^not authorized\.?$/i.test(String(message).trim())) {
+    return "Your account is not a Seven365 staff account, so it cannot change promo codes. Ask a Seven365 administrator to make the change.";
+  }
+
+  return message;
+}