fenne 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,97 @@
+# fenne
+
+Zero-dependency CommonJS helpers for appointment-studio floor operations: station time blocks, walk-in queues, booking packs, operator skill matching, paced async lanes, cash-drawer ledgers, and overlapping booking scans.
+
+## Install
+
+```bash
+npm install fenne
+```
+
+## Usage
+
+```js
+const {
+  coalesceStationBlocks,
+  rankFloorQueue,
+  packStationBookings,
+  matchOperatorSkills,
+  runStationLanes,
+  foldDrawerEvents,
+  detectBookingCollisions,
+} = require("fenne");
+
+const now = Date.now();
+
+const blocks = coalesceStationBlocks([
+  { stationId: "chair-a", operatorId: "op-1", start: now, end: now + 1_800_000, serviceId: "cut" },
+  { stationId: "chair-a", operatorId: "op-1", start: now + 1_800_000, end: now + 3_600_000, serviceId: "style" },
+]);
+
+const queue = rankFloorQueue(
+  [
+    { id: "t-12", kind: "walkin", joinedAt: now - 20_000, slaMinutes: 10, serviceMin: 45, visits: 4 },
+    { id: "t-13", kind: "consult", joinedAt: now, slaMinutes: 30, serviceMin: 15, visits: 0 },
+  ],
+  now
+);
+
+const packed = packStationBookings(
+  [{ id: "b-1", stationId: "chair-a", durationMin: 30, earliest: now, latest: now + 3_600_000, bufferMin: 5 }],
+  [{ id: "chair-a", open: now, close: now + 8 * 3_600_000 }]
+);
+
+const roster = matchOperatorSkills(
+  { skills: ["cut"], languages: ["en"], durationMin: 30 },
+  [{ id: "op-1", skills: ["cut", "color"], languages: ["en"], open: true, load: 1 }]
+);
+
+runStationLanes([() => Promise.resolve("notify-1"), () => Promise.resolve("notify-2")], { width: 2 }).then((lane) => {
+  const drawer = foldDrawerEvents([
+    { type: "open", drawerId: "front", at: now, amount: 120, actorId: "op-1" },
+    { type: "sale", drawerId: "front", at: now + 1, amount: 48 },
+    { type: "tip", drawerId: "front", at: now + 2, amount: 8 },
+  ]);
+  const clashes = detectBookingCollisions([
+    { id: "x", stationId: "chair-a", operatorId: "op-1", start: now, end: now + 1_800_000 },
+    { id: "y", stationId: "chair-a", operatorId: "op-2", start: now + 600_000, end: now + 2_400_000 },
+  ]);
+  console.log(blocks, queue[0].id, packed.assigned, roster[0].operatorId, lane.ok, drawer, clashes);
+});
+```
+
+## API
+
+All times are finite epoch milliseconds. Invalid input throws `TypeError` or `RangeError`. Objects and arrays passed in are not mutated.
+
+### `coalesceStationBlocks(blocks)`
+
+Collapse overlapping or adjacent station blocks that share `stationId` and `operatorId`. Optional `serviceId` values are collected without duplicates.
+
+### `rankFloorQueue(tickets, now)`
+
+Score floor tickets from `booked|walkin|waitlist|consult` kind, remaining wait SLA, service minutes, visit count, and overdue penalty. Returns a new array sorted by score descending.
+
+### `packStationBookings(requests, stations)`
+
+Greedy-pack bookings onto stations with an open/close window. Optional `bufferMin` keeps a gap after each assigned booking. Returns `{ assigned, rejected }`.
+
+### `matchOperatorSkills(request, operators)`
+
+Score operators against required `skills` and optional `languages`. Any missing required skill yields score `0`. Results are sorted by score descending.
+
+### `runStationLanes(tasks, options?)`
+
+Run promise factories with a bounded `width` (default `2`). Resolves `{ ok, failed }` in original index order. A rejected task does not abort the rest.
+
+### `foldDrawerEvents(events)`
+
+Fold `open|sale|tip|payout|close` events into per-drawer balances. A later `open` after `close` resets sales, tips, and payouts for that drawer.
+
+### `detectBookingCollisions(bookings)`
+
+Find pairs that overlap on the same station, the same operator, or both. Touching edges are not collisions.
+
+## License
+
+ISC

package/index.js

@@ -0,0 +1,684 @@
+"use strict";
+
+/**
+ * Appointment studio helpers: station time blocks, floor queues,
+ * booking packs, operator skill matching, paced lanes, drawer ledgers,
+ * and overlapping booking scans.
+ */
+
+/**
+ * @param {string} name
+ * @param {*} value
+ * @param {string} expected
+ * @returns {never}
+ */
+function failType(name, value, expected) {
+  const actual = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+  throw new TypeError(name + " must be " + expected + ", got " + actual);
+}
+
+/**
+ * @param {string} name
+ * @param {*} value
+ */
+function assertArray(name, value) {
+  if (!Array.isArray(value)) {
+    failType(name, value, "an array");
+  }
+}
+
+/**
+ * @param {*} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * @param {string} name
+ * @param {*} value
+ */
+function assertPlainObject(name, value) {
+  if (!isPlainObject(value)) {
+    failType(name, value, "a plain object");
+  }
+}
+
+/**
+ * @param {string} name
+ * @param {*} value
+ */
+function assertFunction(name, value) {
+  if (typeof value !== "function") {
+    failType(name, value, "a function");
+  }
+}
+
+/**
+ * @param {string} name
+ * @param {*} value
+ * @returns {number}
+ */
+function assertEpoch(name, value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    failType(name, value, "a finite epoch millisecond");
+  }
+  return value;
+}
+
+/**
+ * @param {string} name
+ * @param {*} value
+ * @param {number} min
+ * @returns {number}
+ */
+function assertFiniteNumber(name, value, min) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    failType(name, value, "a finite number");
+  }
+  if (value < min) {
+    throw new RangeError(name + " must be >= " + min + ", got " + value);
+  }
+  return value;
+}
+
+/**
+ * @param {string} name
+ * @param {*} value
+ * @returns {string}
+ */
+function assertNonEmptyString(name, value) {
+  if (typeof value !== "string" || value.trim() === "") {
+    failType(name, value, "a non-empty string");
+  }
+  return value.trim();
+}
+
+/**
+ * @param {string} name
+ * @param {*} value
+ * @returns {string[]}
+ */
+function optionalStringList(name, value) {
+  if (value == null) {
+    return [];
+  }
+  assertArray(name, value);
+  const out = [];
+  const seen = Object.create(null);
+  for (let i = 0; i < value.length; i += 1) {
+    const item = assertNonEmptyString(name + "[" + i + "]", value[i]);
+    if (!seen[item]) {
+      seen[item] = true;
+      out.push(item);
+    }
+  }
+  return out;
+}
+
+/**
+ * Merge overlapping or touching station blocks that share station and operator.
+ * Adjacent edges (end === next.start) collapse. Input is copied, never mutated.
+ *
+ * @param {Array<{ stationId: string, operatorId: string, start: number, end: number, serviceId?: string }>} blocks
+ * @returns {Array<{ stationId: string, operatorId: string, start: number, end: number, serviceIds: string[] }>}
+ */
+function coalesceStationBlocks(blocks) {
+  assertArray("blocks", blocks);
+
+  /** @type {Record<string, Array<{ stationId: string, operatorId: string, start: number, end: number, serviceIds: string[] }>>} */
+  const groups = Object.create(null);
+
+  for (let i = 0; i < blocks.length; i += 1) {
+    const row = blocks[i];
+    assertPlainObject("blocks[" + i + "]", row);
+    const stationId = assertNonEmptyString("blocks[" + i + "].stationId", row.stationId);
+    const operatorId = assertNonEmptyString("blocks[" + i + "].operatorId", row.operatorId);
+    const start = assertEpoch("blocks[" + i + "].start", row.start);
+    const end = assertEpoch("blocks[" + i + "].end", row.end);
+    if (end <= start) {
+      throw new RangeError("blocks[" + i + "].end must be greater than start");
+    }
+    const serviceIds = [];
+    if (row.serviceId != null) {
+      serviceIds.push(assertNonEmptyString("blocks[" + i + "].serviceId", row.serviceId));
+    }
+    const key = stationId + "\0" + operatorId;
+    if (!groups[key]) {
+      groups[key] = [];
+    }
+    groups[key].push({ stationId, operatorId, start, end, serviceIds });
+  }
+
+  const merged = [];
+  const keys = Object.keys(groups);
+  for (let g = 0; g < keys.length; g += 1) {
+    const list = groups[keys[g]];
+    list.sort(function (a, b) {
+      return a.start - b.start || a.end - b.end;
+    });
+    let current = null;
+    for (let i = 0; i < list.length; i += 1) {
+      const next = list[i];
+      if (current === null || next.start > current.end) {
+        current = {
+          stationId: next.stationId,
+          operatorId: next.operatorId,
+          start: next.start,
+          end: next.end,
+          serviceIds: next.serviceIds.slice(),
+        };
+        merged.push(current);
+      } else {
+        if (next.end > current.end) {
+          current.end = next.end;
+        }
+        for (let s = 0; s < next.serviceIds.length; s += 1) {
+          if (current.serviceIds.indexOf(next.serviceIds[s]) === -1) {
+            current.serviceIds.push(next.serviceIds[s]);
+          }
+        }
+      }
+    }
+  }
+
+  merged.sort(function (a, b) {
+    return a.start - b.start || a.stationId.localeCompare(b.stationId) || a.operatorId.localeCompare(b.operatorId);
+  });
+  return merged;
+}
+
+const QUEUE_KIND_WEIGHT = {
+  booked: 80,
+  walkin: 45,
+  waitlist: 25,
+  consult: 15,
+};
+
+/**
+ * Rank floor tickets by remaining wait SLA, kind, service minutes, and visit count.
+ * Overdue tickets receive a growing penalty. Returns a new array sorted by score desc.
+ *
+ * @param {Array<{ id: string, kind: "booked"|"walkin"|"waitlist"|"consult", joinedAt: number, slaMinutes: number, serviceMin?: number, visits?: number, stationId?: string }>} tickets
+ * @param {number} now
+ * @returns {Array<{ id: string, score: number, overdueMs: number, remainingMs: number, kind: string, stationId: string|null }>}
+ */
+function rankFloorQueue(tickets, now) {
+  assertArray("tickets", tickets);
+  assertEpoch("now", now);
+
+  const ranked = [];
+  for (let i = 0; i < tickets.length; i += 1) {
+    const row = tickets[i];
+    assertPlainObject("tickets[" + i + "]", row);
+    const id = assertNonEmptyString("tickets[" + i + "].id", row.id);
+    const kind = assertNonEmptyString("tickets[" + i + "].kind", row.kind);
+    if (!Object.prototype.hasOwnProperty.call(QUEUE_KIND_WEIGHT, kind)) {
+      throw new RangeError("tickets[" + i + "].kind must be booked|walkin|waitlist|consult");
+    }
+    const joinedAt = assertEpoch("tickets[" + i + "].joinedAt", row.joinedAt);
+    const slaMinutes = assertFiniteNumber("tickets[" + i + "].slaMinutes", row.slaMinutes, 1);
+    const serviceMin =
+      row.serviceMin == null ? 30 : assertFiniteNumber("tickets[" + i + "].serviceMin", row.serviceMin, 1);
+    const visits = row.visits == null ? 0 : assertFiniteNumber("tickets[" + i + "].visits", row.visits, 0);
+    const slaMs = slaMinutes * 60 * 1000;
+    const dueAt = joinedAt + slaMs;
+    const remainingMs = dueAt - now;
+    const overdueMs = remainingMs < 0 ? -remainingMs : 0;
+    const waitPressure = (now - joinedAt) / slaMs;
+    const durationLoad = Math.log(serviceMin) / Math.LN10 + 1;
+    const loyalty = Math.min(20, visits * 2);
+    const overdueBonus = overdueMs > 0 ? 30 + Math.min(40, overdueMs / 60000) : 0;
+    const score = QUEUE_KIND_WEIGHT[kind] + waitPressure * 35 + durationLoad * 8 + loyalty + overdueBonus;
+    ranked.push({
+      id: id,
+      score: Math.round(score * 1000) / 1000,
+      overdueMs: overdueMs,
+      remainingMs: remainingMs,
+      kind: kind,
+      stationId: row.stationId == null ? null : assertNonEmptyString("tickets[" + i + "].stationId", row.stationId),
+    });
+  }
+
+  ranked.sort(function (a, b) {
+    return b.score - a.score || a.remainingMs - b.remainingMs || a.id.localeCompare(b.id);
+  });
+  return ranked;
+}
+
+/**
+ * Greedy-pack service bookings onto stations with open/close windows and a buffer.
+ * Occupancy never exceeds one active booking per station after the buffer gap.
+ *
+ * @param {Array<{ id: string, stationId: string, durationMin: number, earliest: number, latest: number, bufferMin?: number }>} requests
+ * @param {Array<{ id: string, open: number, close: number }>} stations
+ * @returns {{ assigned: Array<{ requestId: string, stationId: string, start: number, end: number }>, rejected: Array<{ requestId: string, reason: string }> }}
+ */
+function packStationBookings(requests, stations) {
+  assertArray("requests", requests);
+  assertArray("stations", stations);
+
+  /** @type {Record<string, { id: string, open: number, close: number, occupied: Array<{ start: number, end: number }> }>} */
+  const floor = Object.create(null);
+  for (let i = 0; i < stations.length; i += 1) {
+    const row = stations[i];
+    assertPlainObject("stations[" + i + "]", row);
+    const id = assertNonEmptyString("stations[" + i + "].id", row.id);
+    if (floor[id]) {
+      throw new RangeError("duplicate station id " + id);
+    }
+    const open = assertEpoch("stations[" + i + "].open", row.open);
+    const close = assertEpoch("stations[" + i + "].close", row.close);
+    if (close <= open) {
+      throw new RangeError("stations[" + i + "].close must be greater than open");
+    }
+    floor[id] = { id: id, open: open, close: close, occupied: [] };
+  }
+
+  const assigned = [];
+  const rejected = [];
+
+  const ordered = requests.map(function (row, index) {
+    assertPlainObject("requests[" + index + "]", row);
+    const id = assertNonEmptyString("requests[" + index + "].id", row.id);
+    const stationId = assertNonEmptyString("requests[" + index + "].stationId", row.stationId);
+    const durationMin = assertFiniteNumber("requests[" + index + "].durationMin", row.durationMin, 1);
+    const earliest = assertEpoch("requests[" + index + "].earliest", row.earliest);
+    const latest = assertEpoch("requests[" + index + "].latest", row.latest);
+    if (latest <= earliest) {
+      throw new RangeError("requests[" + index + "].latest must be greater than earliest");
+    }
+    const bufferMin =
+      row.bufferMin == null ? 0 : assertFiniteNumber("requests[" + index + "].bufferMin", row.bufferMin, 0);
+    return {
+      id: id,
+      stationId: stationId,
+      durationMs: durationMin * 60 * 1000,
+      earliest: earliest,
+      latest: latest,
+      bufferMs: bufferMin * 60 * 1000,
+      index: index,
+    };
+  });
+
+  ordered.sort(function (a, b) {
+    return a.earliest - b.earliest || a.durationMs - b.durationMs || a.id.localeCompare(b.id);
+  });
+
+  for (let i = 0; i < ordered.length; i += 1) {
+    const req = ordered[i];
+    const station = floor[req.stationId];
+    if (!station) {
+      rejected.push({ requestId: req.id, reason: "unknown-station" });
+      continue;
+    }
+    const durationEndLimit = req.latest;
+    let placed = false;
+    let cursor = Math.max(req.earliest, station.open);
+    station.occupied.sort(function (a, b) {
+      return a.start - b.start;
+    });
+    const gaps = [];
+    let probe = station.open;
+    for (let o = 0; o < station.occupied.length; o += 1) {
+      const occ = station.occupied[o];
+      if (occ.start > probe) {
+        gaps.push({ start: probe, end: occ.start });
+      }
+      probe = Math.max(probe, occ.end);
+    }
+    if (probe < station.close) {
+      gaps.push({ start: probe, end: station.close });
+    }
+    for (let g = 0; g < gaps.length && !placed; g += 1) {
+      const gap = gaps[g];
+      const start = Math.max(cursor, gap.start);
+      const end = start + req.durationMs;
+      const paddedEnd = end + req.bufferMs;
+      if (end <= durationEndLimit && paddedEnd <= gap.end && end <= station.close && start >= station.open) {
+        station.occupied.push({ start: start, end: paddedEnd });
+        assigned.push({
+          requestId: req.id,
+          stationId: station.id,
+          start: start,
+          end: end,
+        });
+        placed = true;
+      }
+    }
+    if (!placed) {
+      rejected.push({ requestId: req.id, reason: "no-fit" });
+    }
+  }
+
+  assigned.sort(function (a, b) {
+    return a.start - b.start || a.requestId.localeCompare(b.requestId);
+  });
+  return { assigned: assigned, rejected: rejected };
+}
+
+/**
+ * Score operators against a service request by required skills, languages, and open flag.
+ * Missing required skills zero the match. Returns a new array sorted by score desc.
+ *
+ * @param {{ skills: string[], languages?: string[], durationMin?: number }} request
+ * @param {Array<{ id: string, skills: string[], languages?: string[], open?: boolean, load?: number }>} operators
+ * @returns {Array<{ operatorId: string, score: number, missing: string[], open: boolean }>}
+ */
+function matchOperatorSkills(request, operators) {
+  assertPlainObject("request", request);
+  assertArray("operators", operators);
+  const required = optionalStringList("request.skills", request.skills);
+  if (required.length === 0) {
+    throw new RangeError("request.skills must contain at least one skill");
+  }
+  const wantLang = optionalStringList("request.languages", request.languages);
+  const durationMin =
+    request.durationMin == null ? 30 : assertFiniteNumber("request.durationMin", request.durationMin, 1);
+
+  const scored = [];
+  for (let i = 0; i < operators.length; i += 1) {
+    const row = operators[i];
+    assertPlainObject("operators[" + i + "]", row);
+    const id = assertNonEmptyString("operators[" + i + "].id", row.id);
+    const skills = optionalStringList("operators[" + i + "].skills", row.skills);
+    const languages = optionalStringList("operators[" + i + "].languages", row.languages);
+    const open = row.open == null ? true : row.open === true;
+    const load = row.load == null ? 0 : assertFiniteNumber("operators[" + i + "].load", row.load, 0);
+    const skillSet = Object.create(null);
+    for (let s = 0; s < skills.length; s += 1) {
+      skillSet[skills[s]] = true;
+    }
+    const missing = [];
+    let hit = 0;
+    for (let r = 0; r < required.length; r += 1) {
+      if (skillSet[required[r]]) {
+        hit += 1;
+      } else {
+        missing.push(required[r]);
+      }
+    }
+    let langHit = 0;
+    if (wantLang.length > 0) {
+      const langSet = Object.create(null);
+      for (let l = 0; l < languages.length; l += 1) {
+        langSet[languages[l]] = true;
+      }
+      for (let w = 0; w < wantLang.length; w += 1) {
+        if (langSet[wantLang[w]]) {
+          langHit += 1;
+        }
+      }
+    }
+    const coverage = hit / required.length;
+    const langBonus = wantLang.length === 0 ? 8 : (langHit / wantLang.length) * 20;
+    const loadPenalty = Math.min(25, load * 5);
+    const durationBias = Math.min(10, durationMin / 15);
+    const score =
+      missing.length > 0 ? 0 : Math.round((coverage * 70 + langBonus + (open ? 12 : 0) + durationBias - loadPenalty) * 1000) / 1000;
+    scored.push({
+      operatorId: id,
+      score: score,
+      missing: missing,
+      open: open,
+    });
+  }
+
+  scored.sort(function (a, b) {
+    return b.score - a.score || a.operatorId.localeCompare(b.operatorId);
+  });
+  return scored;
+}
+
+/**
+ * Run async station-side tasks with a bounded lane width.
+ * Settled results keep input order. Does not mutate the task list.
+ *
+ * @param {Array<() => Promise<*>>} tasks
+ * @param {{ width?: number }} [options]
+ * @returns {Promise<{ ok: Array<{ index: number, value: * }>, failed: Array<{ index: number, error: Error }> }>}
+ */
+function runStationLanes(tasks, options) {
+  assertArray("tasks", tasks);
+  const opts = options == null ? {} : options;
+  assertPlainObject("options", opts);
+  const width = opts.width == null ? 2 : assertFiniteNumber("options.width", opts.width, 1);
+  if (!Number.isInteger(width)) {
+    throw new RangeError("options.width must be an integer");
+  }
+  for (let i = 0; i < tasks.length; i += 1) {
+    assertFunction("tasks[" + i + "]", tasks[i]);
+  }
+
+  return new Promise(function (resolve) {
+    const ok = [];
+    const failed = [];
+    let next = 0;
+    let inflight = 0;
+    let settled = 0;
+    const total = tasks.length;
+
+    if (total === 0) {
+      resolve({ ok: ok, failed: failed });
+      return;
+    }
+
+    function finishOne() {
+      settled += 1;
+      inflight -= 1;
+      if (settled === total) {
+        ok.sort(function (a, b) {
+          return a.index - b.index;
+        });
+        failed.sort(function (a, b) {
+          return a.index - b.index;
+        });
+        resolve({ ok: ok, failed: failed });
+        return;
+      }
+      pump();
+    }
+
+    function pump() {
+      while (inflight < width && next < total) {
+        const index = next;
+        next += 1;
+        inflight += 1;
+        Promise.resolve()
+          .then(function () {
+            return tasks[index]();
+          })
+          .then(
+            function (value) {
+              ok.push({ index: index, value: value });
+              finishOne();
+            },
+            function (error) {
+              const err = error instanceof Error ? error : new Error(String(error));
+              failed.push({ index: index, error: err });
+              finishOne();
+            }
+          );
+      }
+    }
+
+    pump();
+  });
+}
+
+const DRAWER_TYPES = {
+  open: true,
+  sale: true,
+  tip: true,
+  payout: true,
+  close: true,
+};
+
+/**
+ * Fold cash-drawer events into per-drawer running balances and a close snapshot.
+ * Events are copied and applied in time order. Input is not mutated.
+ *
+ * @param {Array<{ type: "open"|"sale"|"tip"|"payout"|"close", drawerId: string, at: number, amount?: number, actorId?: string }>} events
+ * @returns {Record<string, { drawerId: string, openedAt: number|null, closedAt: number|null, sales: number, tips: number, payouts: number, balance: number, actors: string[] }>}
+ */
+function foldDrawerEvents(events) {
+  assertArray("events", events);
+
+  const rows = [];
+  for (let i = 0; i < events.length; i += 1) {
+    const row = events[i];
+    assertPlainObject("events[" + i + "]", row);
+    const type = assertNonEmptyString("events[" + i + "].type", row.type);
+    if (!DRAWER_TYPES[type]) {
+      throw new RangeError("events[" + i + "].type must be open|sale|tip|payout|close");
+    }
+    const drawerId = assertNonEmptyString("events[" + i + "].drawerId", row.drawerId);
+    const at = assertEpoch("events[" + i + "].at", row.at);
+    let amount = 0;
+    if (type === "sale" || type === "tip" || type === "payout") {
+      amount = assertFiniteNumber("events[" + i + "].amount", row.amount, 0);
+    } else if (row.amount != null) {
+      amount = assertFiniteNumber("events[" + i + "].amount", row.amount, 0);
+    }
+    const actorId =
+      row.actorId == null ? null : assertNonEmptyString("events[" + i + "].actorId", row.actorId);
+    rows.push({ type: type, drawerId: drawerId, at: at, amount: amount, actorId: actorId });
+  }
+
+  rows.sort(function (a, b) {
+    return a.at - b.at || a.drawerId.localeCompare(b.drawerId);
+  });
+
+  /** @type {Record<string, { drawerId: string, openedAt: number|null, closedAt: number|null, sales: number, tips: number, payouts: number, balance: number, actors: string[] }>} */
+  const ledgers = Object.create(null);
+
+  function ensure(drawerId) {
+    if (!ledgers[drawerId]) {
+      ledgers[drawerId] = {
+        drawerId: drawerId,
+        openedAt: null,
+        closedAt: null,
+        sales: 0,
+        tips: 0,
+        payouts: 0,
+        balance: 0,
+        actors: [],
+      };
+    }
+    return ledgers[drawerId];
+  }
+
+  for (let i = 0; i < rows.length; i += 1) {
+    const ev = rows[i];
+    const ledger = ensure(ev.drawerId);
+    if (ev.actorId && ledger.actors.indexOf(ev.actorId) === -1) {
+      ledger.actors.push(ev.actorId);
+    }
+    if (ev.type === "open") {
+      if (ledger.closedAt != null && ev.at >= ledger.closedAt) {
+        ledger.openedAt = ev.at;
+        ledger.closedAt = null;
+        ledger.sales = 0;
+        ledger.tips = 0;
+        ledger.payouts = 0;
+        ledger.balance = ev.amount;
+        ledger.actors = ev.actorId ? [ev.actorId] : [];
+      } else if (ledger.openedAt == null) {
+        ledger.openedAt = ev.at;
+        ledger.balance += ev.amount;
+      }
+    } else if (ev.type === "sale") {
+      ledger.sales += ev.amount;
+      ledger.balance += ev.amount;
+    } else if (ev.type === "tip") {
+      ledger.tips += ev.amount;
+      ledger.balance += ev.amount;
+    } else if (ev.type === "payout") {
+      ledger.payouts += ev.amount;
+      ledger.balance -= ev.amount;
+    } else if (ev.type === "close") {
+      ledger.closedAt = ev.at;
+    }
+  }
+
+  return ledgers;
+}
+
+/**
+ * Detect overlapping bookings that share a station or an operator.
+ * Touching edges (end === next.start) are not collisions. Input is not mutated.
+ *
+ * @param {Array<{ id: string, stationId: string, operatorId: string, start: number, end: number }>} bookings
+ * @returns {Array<{ leftId: string, rightId: string, shared: "station"|"operator"|"both", overlapMs: number }>}
+ */
+function detectBookingCollisions(bookings) {
+  assertArray("bookings", bookings);
+
+  const rows = [];
+  const seenIds = Object.create(null);
+  for (let i = 0; i < bookings.length; i += 1) {
+    const row = bookings[i];
+    assertPlainObject("bookings[" + i + "]", row);
+    const id = assertNonEmptyString("bookings[" + i + "].id", row.id);
+    if (seenIds[id]) {
+      throw new RangeError("duplicate booking id " + id);
+    }
+    seenIds[id] = true;
+    const stationId = assertNonEmptyString("bookings[" + i + "].stationId", row.stationId);
+    const operatorId = assertNonEmptyString("bookings[" + i + "].operatorId", row.operatorId);
+    const start = assertEpoch("bookings[" + i + "].start", row.start);
+    const end = assertEpoch("bookings[" + i + "].end", row.end);
+    if (end <= start) {
+      throw new RangeError("bookings[" + i + "].end must be greater than start");
+    }
+    rows.push({ id: id, stationId: stationId, operatorId: operatorId, start: start, end: end });
+  }
+
+  rows.sort(function (a, b) {
+    return a.start - b.start || a.id.localeCompare(b.id);
+  });
+
+  const clashes = [];
+  for (let i = 0; i < rows.length; i += 1) {
+    const left = rows[i];
+    for (let j = i + 1; j < rows.length; j += 1) {
+      const right = rows[j];
+      if (right.start >= left.end) {
+        continue;
+      }
+      const sameStation = left.stationId === right.stationId;
+      const sameOperator = left.operatorId === right.operatorId;
+      if (!sameStation && !sameOperator) {
+        continue;
+      }
+      const overlapStart = Math.max(left.start, right.start);
+      const overlapEnd = Math.min(left.end, right.end);
+      const overlapMs = overlapEnd - overlapStart;
+      if (overlapMs <= 0) {
+        continue;
+      }
+      clashes.push({
+        leftId: left.id,
+        rightId: right.id,
+        shared: sameStation && sameOperator ? "both" : sameStation ? "station" : "operator",
+        overlapMs: overlapMs,
+      });
+    }
+  }
+
+  clashes.sort(function (a, b) {
+    return b.overlapMs - a.overlapMs || a.leftId.localeCompare(b.leftId) || a.rightId.localeCompare(b.rightId);
+  });
+  return clashes;
+}
+
+module.exports = {
+  coalesceStationBlocks,
+  rankFloorQueue,
+  packStationBookings,
+  matchOperatorSkills,
+  runStationLanes,
+  foldDrawerEvents,
+  detectBookingCollisions,
+};

package/package.json

@@ -1,12 +1,25 @@
 {
   "name": "fenne",
-  "version": "1.0.0",
-  "description": "",
+  "version": "1.0.1",
+  "description": "Appointment studio helpers for station blocks, floor queues, booking packs, operator skills, paced lanes, drawer ledgers, and collision scans",
   "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "keywords": [],
+  "keywords": [
+    "appointment",
+    "studio",
+    "station",
+    "queue",
+    "booking",
+    "operator",
+    "drawer",
+    "collision"
+  ],
   "author": "",
   "license": "ISC",
   "type": "commonjs"