@openhi/constructs 0.0.188 → 0.0.189

package/lib/rest-api-lambda.handler.mjs

@@ -7356,6 +7356,368 @@ async function listAppointmentsRoute(req, res) {
   }
 }
 
+// src/data/recurrence/constants.ts
+import {
+  APPOINTMENT_SERIES_SYSTEM,
+  APPOINTMENT_SERIES_OCCURRENCE_SYSTEM,
+  RECURRENCE_RULE_EXTENSION_URL,
+  RECURRENCE_TIMEZONE_EXTENSION_URL,
+  RECURRENCE_ANCHOR_EXTENSION_URL,
+  SERIES_INSTANCE_OVERRIDDEN_EXTENSION_URL
+} from "@openhi/types";
+
+// src/data/recurrence/rrule.ts
+import { TZDate } from "@date-fns/tz";
+import {
+  addDays,
+  addMonths,
+  addWeeks,
+  setHours,
+  setMilliseconds,
+  setMinutes,
+  setSeconds,
+  startOfWeek
+} from "date-fns";
+var FREQ_TO_RRULE = {
+  daily: "DAILY",
+  weekly: "WEEKLY",
+  monthly: "MONTHLY"
+};
+var RRULE_TO_FREQ = {
+  DAILY: "daily",
+  WEEKLY: "weekly",
+  MONTHLY: "monthly"
+};
+var WEEKDAYS = ["MO", "TU", "WE", "TH", "FR", "SA", "SU"];
+var WEEKDAY_OFFSET_FROM_MONDAY = {
+  MO: 0,
+  TU: 1,
+  WE: 2,
+  TH: 3,
+  FR: 4,
+  SA: 5,
+  SU: 6
+};
+var JS_DAY_TO_WEEKDAY = {
+  0: "SU",
+  1: "MO",
+  2: "TU",
+  3: "WE",
+  4: "TH",
+  5: "FR",
+  6: "SA"
+};
+var DEFAULT_MAX_COUNT = 1e3;
+function pad(value, length) {
+  return String(value).padStart(length, "0");
+}
+function formatRruleUtc(date) {
+  return `${pad(date.getUTCFullYear(), 4)}${pad(date.getUTCMonth() + 1, 2)}${pad(date.getUTCDate(), 2)}T${pad(date.getUTCHours(), 2)}${pad(date.getUTCMinutes(), 2)}${pad(date.getUTCSeconds(), 2)}Z`;
+}
+function parseRruleUtc(value) {
+  const match = value.match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/);
+  if (!match) {
+    throw new Error(`Unsupported RRULE UNTIL value: ${value}`);
+  }
+  const [, y, mo, d, h, mi, s] = match;
+  return new Date(
+    Date.UTC(
+      Number(y),
+      Number(mo) - 1,
+      Number(d),
+      Number(h),
+      Number(mi),
+      Number(s)
+    )
+  );
+}
+function buildRruleString(pattern) {
+  const parts = [`FREQ=${FREQ_TO_RRULE[pattern.frequency]}`];
+  if (pattern.interval > 1) {
+    parts.push(`INTERVAL=${pattern.interval}`);
+  }
+  if (pattern.frequency === "weekly" && pattern.byWeekday?.length) {
+    const ordered = WEEKDAYS.filter((day) => pattern.byWeekday?.includes(day));
+    parts.push(`BYDAY=${ordered.join(",")}`);
+  }
+  if (pattern.end.kind === "count") {
+    parts.push(`COUNT=${pattern.end.count}`);
+  } else if (pattern.end.kind === "until") {
+    parts.push(`UNTIL=${formatRruleUtc(pattern.end.until)}`);
+  }
+  return parts.join(";");
+}
+var SUPPORTED_RRULE_KEYS = /* @__PURE__ */ new Set([
+  "FREQ",
+  "INTERVAL",
+  "BYDAY",
+  "COUNT",
+  "UNTIL"
+]);
+var WEEKDAY_SET = new Set(WEEKDAYS);
+function parsePositiveInt(value, key) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error(`Invalid RRULE ${key}: ${value}`);
+  }
+  return parsed;
+}
+function parseRruleString(rrule) {
+  const map = /* @__PURE__ */ new Map();
+  for (const segment of rrule.split(";")) {
+    const [key, value] = segment.split("=");
+    if (!key || !value) continue;
+    const normalizedKey = key.trim().toUpperCase();
+    if (!SUPPORTED_RRULE_KEYS.has(normalizedKey)) {
+      throw new Error(`Unsupported RRULE part: ${key}`);
+    }
+    map.set(normalizedKey, value.trim());
+  }
+  const freqRaw = map.get("FREQ");
+  const frequency = freqRaw ? RRULE_TO_FREQ[freqRaw.toUpperCase()] : void 0;
+  if (!frequency) {
+    throw new Error(`Unsupported RRULE FREQ: ${freqRaw ?? "(missing)"}`);
+  }
+  const interval = map.has("INTERVAL") ? parsePositiveInt(map.get("INTERVAL"), "INTERVAL") : 1;
+  let byWeekday;
+  const byDay = map.get("BYDAY");
+  if (byDay) {
+    byWeekday = byDay.split(",").map((code) => {
+      const normalized = code.trim().toUpperCase();
+      if (!WEEKDAY_SET.has(normalized)) {
+        throw new Error(`Unsupported RRULE BYDAY value: ${code}`);
+      }
+      return normalized;
+    });
+  }
+  let end = { kind: "open" };
+  if (map.has("COUNT")) {
+    end = {
+      kind: "count",
+      count: parsePositiveInt(map.get("COUNT"), "COUNT")
+    };
+  } else if (map.has("UNTIL")) {
+    end = { kind: "until", until: parseRruleUtc(map.get("UNTIL")) };
+  }
+  return { frequency, interval, byWeekday, end };
+}
+function setTimeOfDay(day, source) {
+  return setMilliseconds(
+    setSeconds(setMinutes(setHours(day, source.h), source.m), source.s),
+    source.ms
+  );
+}
+function expandOccurrences(args) {
+  const { pattern, seriesStart, timezone, window } = args;
+  const maxCount = args.maxCount ?? DEFAULT_MAX_COUNT;
+  const startZ = new TZDate(seriesStart.getTime(), timezone);
+  const timeOfDay = {
+    h: startZ.getHours(),
+    m: startZ.getMinutes(),
+    s: startZ.getSeconds(),
+    ms: startZ.getMilliseconds()
+  };
+  const startMs = seriesStart.getTime();
+  const fromMs = window.from.getTime();
+  const toMs = window.to.getTime();
+  const untilMs = pattern.end.kind === "until" ? pattern.end.until.getTime() : Infinity;
+  const countLimit = pattern.end.kind === "count" ? pattern.end.count : Infinity;
+  const results = [];
+  let produced = 0;
+  const accept = (candidate) => {
+    const ms = candidate.getTime();
+    if (ms < startMs) return true;
+    if (ms > untilMs) return false;
+    if (produced >= countLimit) return false;
+    produced += 1;
+    if (ms > toMs) return false;
+    if (ms >= fromMs) results.push(new Date(ms));
+    return true;
+  };
+  let examined = 0;
+  const interval = Math.max(1, pattern.interval);
+  let finished = false;
+  if (pattern.frequency === "daily") {
+    for (let i = 0; examined <= maxCount; i += 1, examined += 1) {
+      if (!accept(addDays(startZ, i * interval))) {
+        finished = true;
+        break;
+      }
+    }
+  } else if (pattern.frequency === "monthly") {
+    for (let i = 0; examined <= maxCount; i += 1, examined += 1) {
+      if (!accept(addMonths(startZ, i * interval))) {
+        finished = true;
+        break;
+      }
+    }
+  } else {
+    const days = pattern.byWeekday?.length ? pattern.byWeekday : [JS_DAY_TO_WEEKDAY[startZ.getDay()]];
+    const offsets = WEEKDAYS.filter((day) => days.includes(day)).map(
+      (day) => WEEKDAY_OFFSET_FROM_MONDAY[day]
+    );
+    const weekAnchor = startOfWeek(startZ, { weekStartsOn: 1 });
+    for (let w = 0; !finished && examined <= maxCount; w += interval) {
+      const weekStart = addWeeks(weekAnchor, w);
+      for (const offset of offsets) {
+        examined += 1;
+        const occurrence = setTimeOfDay(addDays(weekStart, offset), timeOfDay);
+        if (!accept(occurrence)) {
+          finished = true;
+          break;
+        }
+      }
+    }
+  }
+  if (!finished) {
+    throw new Error(
+      `Recurrence expansion hit the ${maxCount}-candidate safety cap before reaching the end of the window. Raise maxCount or narrow the window.`
+    );
+  }
+  return results;
+}
+
+// src/data/recurrence/seriesInstances.ts
+import { addMinutes } from "date-fns";
+
+// src/data/recurrence/membership.ts
+import {
+  buildSeriesIdentifier,
+  buildOccurrenceIdentifier,
+  buildRecurrenceRuleExtension,
+  buildRecurrenceTimezoneExtension,
+  buildRecurrenceAnchorExtension,
+  buildSeriesInstanceOverriddenExtension,
+  getSeriesId,
+  getOccurrenceIdentifier,
+  getOccurrenceInstant,
+  getRecurrenceRule,
+  getRecurrenceTimezone,
+  getRecurrenceAnchor,
+  isSeriesInstanceOverridden
+} from "@openhi/types";
+
+// src/data/recurrence/seriesInstances.ts
+function buildSeriesInstances(args) {
+  const {
+    base,
+    occurrences,
+    durationMinutes,
+    seriesId,
+    rrule,
+    timezone,
+    anchor
+  } = args;
+  const seriesIdentifier = buildSeriesIdentifier(seriesId);
+  const seriesExtensions = [
+    buildRecurrenceRuleExtension(rrule),
+    buildRecurrenceTimezoneExtension(timezone),
+    buildRecurrenceAnchorExtension(anchor)
+  ];
+  const baseIdentifiers = base.identifier ?? [];
+  const baseExtensions = base.extension ?? [];
+  return occurrences.map((start) => ({
+    ...base,
+    start: start.toISOString(),
+    end: addMinutes(start, durationMinutes).toISOString(),
+    minutesDuration: durationMinutes,
+    identifier: [
+      ...baseIdentifiers,
+      seriesIdentifier,
+      buildOccurrenceIdentifier(seriesId, start)
+    ],
+    extension: [...baseExtensions, ...seriesExtensions]
+  }));
+}
+
+// src/data/operations/data/appointment/appointment-series-common.ts
+var SeriesRequestError = class extends Error {
+};
+var SeriesNotFoundError = class extends Error {
+};
+var LOCATE_LIMIT = 500;
+async function locateSeriesInstances(opts) {
+  const { context, seriesId, tableName } = opts;
+  const found = await genericSearchOperation({
+    resourceType: "Appointment",
+    tenantId: context.tenantId,
+    workspaceId: context.workspaceId,
+    query: { identifier: `${APPOINTMENT_SERIES_SYSTEM}|${seriesId}` },
+    resolver: defaultSearchParameterResolver,
+    limit: LOCATE_LIMIT
+  });
+  const instances = [];
+  for (const entry of found.entries) {
+    let resource;
+    try {
+      const hydrated = await getAppointmentByIdOperation({
+        context,
+        id: entry.id,
+        tableName
+      });
+      resource = hydrated.resource;
+    } catch {
+      continue;
+    }
+    instances.push({
+      id: entry.id,
+      resource,
+      occurrenceInstant: safeOccurrenceInstant(resource)
+    });
+  }
+  instances.sort((a, b) => {
+    if (a.occurrenceInstant === null && b.occurrenceInstant === null) {
+      return a.id.localeCompare(b.id);
+    }
+    if (a.occurrenceInstant === null) return 1;
+    if (b.occurrenceInstant === null) return -1;
+    return Date.parse(a.occurrenceInstant) - Date.parse(b.occurrenceInstant) || a.id.localeCompare(b.id);
+  });
+  return instances;
+}
+function safeOccurrenceInstant(resource) {
+  try {
+    return getOccurrenceInstant(resource);
+  } catch {
+    return null;
+  }
+}
+function resolveFromOccurrence(instances, fromOccurrence) {
+  const fromMs = Date.parse(fromOccurrence);
+  if (Number.isNaN(fromMs)) {
+    throw new SeriesRequestError(
+      `fromOccurrence is not a valid ISO 8601 instant: "${fromOccurrence}".`
+    );
+  }
+  const match = instances.some(
+    (i) => i.occurrenceInstant !== null && Date.parse(i.occurrenceInstant) === fromMs
+  );
+  if (!match) {
+    throw new SeriesRequestError(
+      `fromOccurrence "${fromOccurrence}" does not match any occurrence key in the series.`
+    );
+  }
+  return fromMs;
+}
+function isAtOrAfter(instance, boundaryMs) {
+  return instance.occurrenceInstant !== null && Date.parse(instance.occurrenceInstant) >= boundaryMs;
+}
+function validateSeriesSelector(body) {
+  if (typeof body.seriesId !== "string" || body.seriesId.length === 0) {
+    throw new SeriesRequestError("seriesId is required.");
+  }
+  if (body.mode !== "following" && body.mode !== "all") {
+    throw new SeriesRequestError(
+      `mode must be "following" or "all"; received "${String(body.mode)}".`
+    );
+  }
+  if (body.mode === "following" && !body.fromOccurrence) {
+    throw new SeriesRequestError(
+      'fromOccurrence is required when mode is "following".'
+    );
+  }
+}
+
 // src/data/operations/data/appointment/appointment-update-operation.ts
 async function updateAppointmentOperation(params) {
   const { context, id, body, tableName } = params;
@@ -7380,6 +7742,653 @@ async function updateAppointmentOperation(params) {
   );
 }
 
+// src/data/operations/data/appointment/appointment-cancel-series-operation.ts
+async function cancelSeriesOperation(params) {
+  const { context, body, tableName } = params;
+  validateSeriesSelector(body);
+  const instances = await locateSeriesInstances({
+    context,
+    seriesId: body.seriesId,
+    tableName
+  });
+  if (instances.length === 0) {
+    throw new SeriesNotFoundError(
+      `No Appointment instances found for series "${body.seriesId}".`
+    );
+  }
+  let targets;
+  if (body.mode === "following") {
+    const boundaryMs = resolveFromOccurrence(instances, body.fromOccurrence);
+    targets = instances.filter((i) => isAtOrAfter(i, boundaryMs));
+  } else {
+    targets = [...instances];
+  }
+  const ledger = [];
+  for (const instance of targets) {
+    const occurrence = instance.occurrenceInstant ?? void 0;
+    if (instance.resource.status === "cancelled") {
+      ledger.push({
+        id: instance.id,
+        occurrence,
+        action: "skipped-already-cancelled"
+      });
+      continue;
+    }
+    try {
+      const cancelled = {
+        ...instance.resource,
+        status: "cancelled"
+      };
+      await updateAppointmentOperation({
+        context,
+        id: instance.id,
+        body: cancelled,
+        tableName
+      });
+      ledger.push({ id: instance.id, occurrence, action: "cancelled" });
+    } catch (err) {
+      ledger.push({
+        id: instance.id,
+        occurrence,
+        action: "failed",
+        diagnostics: String(err)
+      });
+    }
+  }
+  return { seriesId: body.seriesId, mode: body.mode, ledger };
+}
+
+// src/data/operations/data/appointment/appointment-create-series-operation.ts
+var SERIES_MAX_OCCURRENCES = 400;
+var FREQUENCIES = /* @__PURE__ */ new Set(["daily", "weekly", "monthly"]);
+var WEEKDAYS2 = /* @__PURE__ */ new Set(["MO", "TU", "WE", "TH", "FR", "SA", "SU"]);
+function parseSeriesPattern(pattern) {
+  if (!FREQUENCIES.has(pattern.frequency)) {
+    throw new SeriesRequestError(
+      `Unsupported pattern.frequency "${pattern.frequency}"; expected daily | weekly | monthly.`
+    );
+  }
+  if (!Number.isInteger(pattern.interval) || pattern.interval < 1) {
+    throw new SeriesRequestError(
+      `pattern.interval must be an integer >= 1; received ${pattern.interval}.`
+    );
+  }
+  let byWeekday;
+  if (pattern.byWeekday !== void 0) {
+    for (const day of pattern.byWeekday) {
+      if (!WEEKDAYS2.has(day)) {
+        throw new SeriesRequestError(
+          `Unsupported pattern.byWeekday value "${day}".`
+        );
+      }
+    }
+    byWeekday = [...pattern.byWeekday];
+  }
+  const end = pattern.end;
+  if (end.kind === "count") {
+    if (!Number.isInteger(end.count) || end.count < 1) {
+      throw new SeriesRequestError(
+        `pattern.end.count must be an integer >= 1; received ${end.count}.`
+      );
+    }
+    return {
+      frequency: pattern.frequency,
+      interval: pattern.interval,
+      byWeekday,
+      end: { kind: "count", count: end.count }
+    };
+  }
+  if (end.kind === "until") {
+    const until = new Date(end.until ?? "");
+    if (Number.isNaN(until.getTime())) {
+      throw new SeriesRequestError(
+        `pattern.end.until is not a valid ISO 8601 instant: "${end.until}".`
+      );
+    }
+    return {
+      frequency: pattern.frequency,
+      interval: pattern.interval,
+      byWeekday,
+      end: { kind: "until", until }
+    };
+  }
+  throw new SeriesRequestError(
+    `Unsupported pattern.end.kind "${end.kind}"; v1 accepts "count" or "until" only (open-ended series are not supported).`
+  );
+}
+var WINDOW_END = /* @__PURE__ */ new Date("9999-12-31T00:00:00Z");
+function expandSeries(opts) {
+  let occurrences;
+  try {
+    occurrences = expandOccurrences({
+      pattern: opts.pattern,
+      seriesStart: opts.anchor,
+      timezone: opts.timezone,
+      window: { from: opts.anchor, to: WINDOW_END },
+      // The cap throws (never silently truncates); +1 distinguishes
+      // "exactly at the ceiling" from "over it".
+      maxCount: SERIES_MAX_OCCURRENCES + 1
+    });
+  } catch (err) {
+    throw new SeriesRequestError(
+      `Series expansion exceeded the ${SERIES_MAX_OCCURRENCES}-occurrence server ceiling: ${String(err)}`
+    );
+  }
+  if (occurrences.length > SERIES_MAX_OCCURRENCES) {
+    throw new SeriesRequestError(
+      `Series expands to ${occurrences.length} occurrences; the server ceiling is ${SERIES_MAX_OCCURRENCES}.`
+    );
+  }
+  return occurrences;
+}
+async function createSeriesOperation(params) {
+  const { context, body, tableName } = params;
+  if (typeof body.seriesId !== "string" || body.seriesId.length === 0) {
+    throw new SeriesRequestError("seriesId is required.");
+  }
+  if (body.template === void 0 || typeof body.template !== "object") {
+    throw new SeriesRequestError("template is required.");
+  }
+  if (!Number.isInteger(body.durationMinutes) || body.durationMinutes < 1) {
+    throw new SeriesRequestError(
+      `durationMinutes must be an integer >= 1; received ${body.durationMinutes}.`
+    );
+  }
+  if (typeof body.timezone !== "string" || body.timezone.length === 0) {
+    throw new SeriesRequestError("timezone is required (IANA zone).");
+  }
+  const anchor = new Date(body.anchor ?? "");
+  if (Number.isNaN(anchor.getTime())) {
+    throw new SeriesRequestError(
+      `anchor is not a valid ISO 8601 instant: "${body.anchor}".`
+    );
+  }
+  const pattern = parseSeriesPattern(
+    body.pattern ?? {}
+  );
+  const rrule = buildRruleString(pattern);
+  const occurrences = expandSeries({
+    pattern,
+    anchor,
+    timezone: body.timezone
+  });
+  if (body.dryRun === true) {
+    return {
+      seriesId: body.seriesId,
+      rrule,
+      occurrences: occurrences.map((o) => o.toISOString())
+    };
+  }
+  const existing = await locateSeriesInstances({
+    context,
+    seriesId: body.seriesId,
+    tableName
+  });
+  const existingInstants = new Set(
+    existing.map((i) => i.occurrenceInstant).filter((v) => v !== null).map((v) => Date.parse(v))
+  );
+  const {
+    id: _id,
+    start: _start,
+    end: _end,
+    ...template
+  } = body.template;
+  const instances = buildSeriesInstances({
+    base: template,
+    occurrences,
+    durationMinutes: body.durationMinutes,
+    seriesId: body.seriesId,
+    rrule,
+    timezone: body.timezone,
+    anchor
+  });
+  const ledger = [];
+  for (let i = 0; i < instances.length; i++) {
+    const occurrence = occurrences[i].toISOString();
+    if (existingInstants.has(occurrences[i].getTime())) {
+      ledger.push({ occurrence, action: "skipped-existing" });
+      continue;
+    }
+    try {
+      const created = await createAppointmentOperation({
+        context,
+        body: instances[i],
+        tableName
+      });
+      ledger.push({ id: created.id, occurrence, action: "created" });
+    } catch (err) {
+      ledger.push({ occurrence, action: "failed", diagnostics: String(err) });
+    }
+  }
+  return {
+    seriesId: body.seriesId,
+    rrule,
+    occurrences: occurrences.map((o) => o.toISOString()),
+    ledger
+  };
+}
+
+// src/data/operations/data/appointment/appointment-edit-series-operation.ts
+import { randomUUID } from "crypto";
+import { TZDate as TZDate2 } from "@date-fns/tz";
+import {
+  addMinutes as addMinutes2,
+  setHours as setHours2,
+  setMilliseconds as setMilliseconds2,
+  setMinutes as setMinutes2,
+  setSeconds as setSeconds2
+} from "date-fns";
+var LOCAL_TIME_PATTERN = /^([01]\d|2[0-3]):[0-5]\d$/;
+function validateChanges(changes) {
+  if (changes === void 0 || typeof changes !== "object") {
+    throw new SeriesRequestError("changes is required.");
+  }
+  const named = changes.startTime !== void 0 || changes.practitioners !== void 0 || changes.patients !== void 0 || changes.appointmentType !== void 0 || changes.description !== void 0;
+  if (!named) {
+    throw new SeriesRequestError(
+      "changes must name at least one of: startTime, practitioners, patients, appointmentType, description."
+    );
+  }
+  if (changes.startTime !== void 0) {
+    if (!LOCAL_TIME_PATTERN.test(changes.startTime.localTime ?? "")) {
+      throw new SeriesRequestError(
+        `changes.startTime.localTime must be wall-clock "HH:mm"; received "${changes.startTime.localTime}".`
+      );
+    }
+    if (!Number.isInteger(changes.startTime.durationMinutes) || changes.startTime.durationMinutes < 1) {
+      throw new SeriesRequestError(
+        "changes.startTime.durationMinutes must be an integer >= 1."
+      );
+    }
+  }
+  validateRoleParticipants(changes.practitioners, "Practitioner/");
+  validateRoleParticipants(changes.patients, "Patient/");
+}
+function validateRoleParticipants(participants, rolePrefix) {
+  if (participants === void 0) return;
+  for (const p of participants) {
+    const reference = p.actor?.reference ?? "";
+    if (!reference.startsWith(rolePrefix)) {
+      throw new SeriesRequestError(
+        `Every entry in the ${rolePrefix.slice(0, -1)} participant list must reference a ${rolePrefix.slice(0, -1)} (got "${reference}").`
+      );
+    }
+  }
+}
+function replaceRoleParticipants(existing, rolePrefix, replacements) {
+  const others = existing.filter(
+    (p) => !(p.actor?.reference ?? "").startsWith(rolePrefix)
+  );
+  return [...others, ...replacements];
+}
+function deriveWallClockStart(occurrenceInstant, timezone, localTime) {
+  const [hours, minutes] = localTime.split(":").map(Number);
+  const onDate = new TZDate2(Date.parse(occurrenceInstant), timezone);
+  const adjusted = setMilliseconds2(
+    setSeconds2(setMinutes2(setHours2(onDate, hours), minutes), 0),
+    0
+  );
+  return new Date(adjusted.getTime());
+}
+function applyChanges(instance, changes, timezone) {
+  const resource = { ...instance.resource };
+  if (changes.startTime !== void 0) {
+    if (instance.occurrenceInstant === null) {
+      throw new SeriesRequestError(
+        `Instance ${instance.id} has no occurrence identifier; cannot re-derive its start time.`
+      );
+    }
+    const start = deriveWallClockStart(
+      instance.occurrenceInstant,
+      timezone,
+      changes.startTime.localTime
+    );
+    resource.start = start.toISOString();
+    resource.end = addMinutes2(
+      start,
+      changes.startTime.durationMinutes
+    ).toISOString();
+    resource.minutesDuration = changes.startTime.durationMinutes;
+  }
+  if (changes.practitioners !== void 0 || changes.patients !== void 0) {
+    let participants = [...resource.participant ?? []];
+    if (changes.practitioners !== void 0) {
+      participants = replaceRoleParticipants(
+        participants,
+        "Practitioner/",
+        changes.practitioners
+      );
+    }
+    if (changes.patients !== void 0) {
+      participants = replaceRoleParticipants(
+        participants,
+        "Patient/",
+        changes.patients
+      );
+    }
+    resource.participant = participants;
+  }
+  if (changes.appointmentType !== void 0) {
+    resource.appointmentType = changes.appointmentType;
+  }
+  if (changes.description !== void 0) {
+    resource.description = changes.description;
+  }
+  return resource;
+}
+function readSeriesRecurrence(instances) {
+  for (const instance of instances) {
+    const rule = getRecurrenceRule(instance.resource);
+    const timezone = getRecurrenceTimezone(instance.resource);
+    const anchor = getRecurrenceAnchor(instance.resource);
+    if (rule !== null && timezone !== null && anchor !== null) {
+      return { pattern: parseRruleString(rule), timezone, anchor };
+    }
+  }
+  throw new SeriesRequestError(
+    "Series instances are missing the recurrence-rule / recurrence-timezone / recurrence-anchor extensions; the series cannot be edited as a series."
+  );
+}
+function withTruncatedRule(resource, rule) {
+  const extension = (resource.extension ?? []).map(
+    (ext) => ext.url === RECURRENCE_RULE_EXTENSION_URL ? { ...ext, valueString: rule } : ext
+  );
+  return { ...resource, extension };
+}
+function buildTailTemplate(resource) {
+  const { id: _id, start: _start, end: _end, meta: _meta, ...rest } = resource;
+  const identifier = (rest.identifier ?? []).filter(
+    (i) => i.system !== APPOINTMENT_SERIES_SYSTEM && i.system !== APPOINTMENT_SERIES_OCCURRENCE_SYSTEM
+  );
+  const stripped = /* @__PURE__ */ new Set([
+    RECURRENCE_RULE_EXTENSION_URL,
+    RECURRENCE_TIMEZONE_EXTENSION_URL,
+    RECURRENCE_ANCHOR_EXTENSION_URL,
+    SERIES_INSTANCE_OVERRIDDEN_EXTENSION_URL
+  ]);
+  const extension = (rest.extension ?? []).filter(
+    (e) => !stripped.has(e.url ?? "")
+  );
+  return {
+    ...rest,
+    identifier,
+    extension,
+    // A tail regenerated from a cancelled instance must not be born cancelled.
+    status: rest.status === "cancelled" ? "booked" : rest.status
+  };
+}
+async function editSeriesOperation(params) {
+  const { context, body, tableName } = params;
+  validateSeriesSelector(body);
+  validateChanges(body.changes);
+  if (body.newPattern !== void 0 && body.mode !== "following") {
+    throw new SeriesRequestError(
+      'newPattern is only valid with mode="following".'
+    );
+  }
+  const instances = await locateSeriesInstances({
+    context,
+    seriesId: body.seriesId,
+    tableName
+  });
+  if (instances.length === 0) {
+    throw new SeriesNotFoundError(
+      `No Appointment instances found for series "${body.seriesId}".`
+    );
+  }
+  const { pattern, timezone, anchor } = readSeriesRecurrence(instances);
+  if (body.mode === "all") {
+    return editAll({ context, body, instances, timezone, tableName });
+  }
+  return editFollowing({
+    context,
+    body,
+    instances,
+    pattern,
+    timezone,
+    anchor,
+    tableName
+  });
+}
+async function editAll(opts) {
+  const { context, body, instances, timezone, tableName } = opts;
+  const ledger = [];
+  for (const instance of instances) {
+    const occurrence = instance.occurrenceInstant ?? void 0;
+    if (instance.resource.status === "cancelled") {
+      ledger.push({
+        id: instance.id,
+        occurrence,
+        action: "skipped-already-cancelled"
+      });
+      continue;
+    }
+    if (isSeriesInstanceOverridden(instance.resource)) {
+      ledger.push({
+        id: instance.id,
+        occurrence,
+        action: "skipped-overridden"
+      });
+      continue;
+    }
+    try {
+      const updated = applyChanges(instance, body.changes, timezone);
+      await updateAppointmentOperation({
+        context,
+        id: instance.id,
+        body: updated,
+        tableName
+      });
+      ledger.push({ id: instance.id, occurrence, action: "updated" });
+    } catch (err) {
+      if (err instanceof SeriesRequestError) throw err;
+      ledger.push({
+        id: instance.id,
+        occurrence,
+        action: "failed",
+        diagnostics: String(err)
+      });
+    }
+  }
+  return { seriesId: body.seriesId, mode: "all", ledger };
+}
+async function editFollowing(opts) {
+  const { context, body, instances, pattern, timezone, anchor, tableName } = opts;
+  const boundaryMs = resolveFromOccurrence(instances, body.fromOccurrence);
+  const kept = instances.filter((i) => !isAtOrAfter(i, boundaryMs));
+  const replaced = instances.filter((i) => isAtOrAfter(i, boundaryMs));
+  if (kept.length === 0) {
+    throw new SeriesRequestError(
+      'fromOccurrence is the first occurrence of the series \u2014 there is nothing to split. Use mode="all" instead.'
+    );
+  }
+  const lastKeptMs = Math.max(
+    ...kept.map((i) => i.occurrenceInstant).filter((v) => v !== null).map((v) => Date.parse(v))
+  );
+  const truncatedPattern = {
+    ...pattern,
+    end: { kind: "until", until: new Date(lastKeptMs) }
+  };
+  const truncatedRule = buildRruleString(truncatedPattern);
+  let tailPattern;
+  if (body.newPattern !== void 0) {
+    tailPattern = parseSeriesPattern(body.newPattern);
+  } else if (pattern.end.kind === "count") {
+    const producedBefore = expandOccurrences({
+      pattern,
+      seriesStart: anchor,
+      timezone,
+      window: { from: anchor, to: new Date(boundaryMs - 1) }
+    }).length;
+    const remaining = pattern.end.count - producedBefore;
+    if (remaining < 1) {
+      throw new SeriesRequestError(
+        "The original series has no occurrences remaining at fromOccurrence; nothing to regenerate."
+      );
+    }
+    tailPattern = { ...pattern, end: { kind: "count", count: remaining } };
+  } else {
+    tailPattern = pattern;
+  }
+  const boundaryInstant = new Date(boundaryMs).toISOString();
+  const newAnchor = body.changes.startTime !== void 0 ? deriveWallClockStart(
+    boundaryInstant,
+    timezone,
+    body.changes.startTime.localTime
+  ) : new Date(boundaryMs);
+  const tailOccurrences = expandSeries({
+    pattern: tailPattern,
+    anchor: newAnchor,
+    timezone
+  });
+  const templateSource = replaced[0];
+  const edited = applyChanges(
+    { ...templateSource, occurrenceInstant: boundaryInstant },
+    body.changes,
+    timezone
+  );
+  const template = buildTailTemplate(edited);
+  const durationMinutes = body.changes.startTime?.durationMinutes ?? templateSource.resource.minutesDuration ?? defaultDurationMinutes(templateSource.resource);
+  const newSeriesId = randomUUID();
+  const newRrule = buildRruleString(tailPattern);
+  const tailInstances = buildSeriesInstances({
+    base: template,
+    occurrences: tailOccurrences,
+    durationMinutes,
+    seriesId: newSeriesId,
+    rrule: newRrule,
+    timezone,
+    anchor: newAnchor
+  });
+  const ledger = [];
+  for (const instance of kept) {
+    try {
+      await updateAppointmentOperation({
+        context,
+        id: instance.id,
+        body: withTruncatedRule(instance.resource, truncatedRule),
+        tableName
+      });
+      ledger.push({
+        id: instance.id,
+        occurrence: instance.occurrenceInstant ?? void 0,
+        action: "rule-truncated"
+      });
+    } catch (err) {
+      ledger.push({
+        id: instance.id,
+        occurrence: instance.occurrenceInstant ?? void 0,
+        action: "failed",
+        diagnostics: String(err)
+      });
+    }
+  }
+  for (let i = 0; i < tailInstances.length; i++) {
+    const occurrence = tailOccurrences[i].toISOString();
+    try {
+      const created = await createAppointmentOperation({
+        context,
+        body: tailInstances[i],
+        tableName
+      });
+      ledger.push({ id: created.id, occurrence, action: "created" });
+    } catch (err) {
+      ledger.push({ occurrence, action: "failed", diagnostics: String(err) });
+    }
+  }
+  for (const instance of replaced) {
+    try {
+      await deleteAppointmentOperation({ context, id: instance.id, tableName });
+      ledger.push({
+        id: instance.id,
+        occurrence: instance.occurrenceInstant ?? void 0,
+        action: "deleted"
+      });
+    } catch (err) {
+      ledger.push({
+        id: instance.id,
+        occurrence: instance.occurrenceInstant ?? void 0,
+        action: "failed",
+        diagnostics: String(err)
+      });
+    }
+  }
+  return {
+    seriesId: body.seriesId,
+    mode: "following",
+    newSeriesId,
+    truncatedRule,
+    newRrule,
+    ledger
+  };
+}
+function defaultDurationMinutes(resource) {
+  const start = Date.parse(resource.start ?? "");
+  const end = Date.parse(resource.end ?? "");
+  if (!Number.isNaN(start) && !Number.isNaN(end) && end > start) {
+    return Math.round((end - start) / 6e4);
+  }
+  throw new SeriesRequestError(
+    "Cannot derive the tail's duration: supply changes.startTime.durationMinutes (the template instance has no usable minutesDuration or start/end)."
+  );
+}
+
+// src/data/rest-api/routes/data/appointment/appointment-series-routes.ts
+function sendOperationOutcome(res, status, code, diagnostics) {
+  return res.status(status).json({
+    resourceType: "OperationOutcome",
+    issue: [{ severity: "error", code, diagnostics }]
+  });
+}
+function sendSeriesError(res, err, logContext) {
+  if (err instanceof SeriesRequestError) {
+    return sendOperationOutcome(res, 400, "invalid", err.message);
+  }
+  if (err instanceof SeriesNotFoundError) {
+    return sendOperationOutcome(res, 404, "not-found", err.message);
+  }
+  return sendOperationOutcome500(res, err, logContext);
+}
+async function createSeriesRoute(req, res) {
+  const bodyResult = requireJsonBodyAs(req, res);
+  if ("errorResponse" in bodyResult) return bodyResult.errorResponse;
+  try {
+    const result = await createSeriesOperation({
+      context: req.openhiContext,
+      body: bodyResult.body
+    });
+    return res.status(200).json(result);
+  } catch (err) {
+    return sendSeriesError(res, err, "POST /Appointment/$create-series error:");
+  }
+}
+async function editSeriesRoute(req, res) {
+  const bodyResult = requireJsonBodyAs(req, res);
+  if ("errorResponse" in bodyResult) return bodyResult.errorResponse;
+  try {
+    const result = await editSeriesOperation({
+      context: req.openhiContext,
+      body: bodyResult.body
+    });
+    return res.status(200).json(result);
+  } catch (err) {
+    return sendSeriesError(res, err, "POST /Appointment/$edit-series error:");
+  }
+}
+async function cancelSeriesRoute(req, res) {
+  const bodyResult = requireJsonBodyAs(req, res);
+  if ("errorResponse" in bodyResult) return bodyResult.errorResponse;
+  try {
+    const result = await cancelSeriesOperation({
+      context: req.openhiContext,
+      body: bodyResult.body
+    });
+    return res.status(200).json(result);
+  } catch (err) {
+    return sendSeriesError(res, err, "POST /Appointment/$cancel-series error:");
+  }
+}
+
 // src/data/rest-api/routes/data/appointment/appointment-update-route.ts
 async function updateAppointmentRoute(req, res) {
   const bodyResult = requireJsonBodyAs(req, res);
@@ -7414,6 +8423,9 @@ var router14 = express14.Router();
 router14.get("/", listAppointmentsRoute);
 router14.get("/:id", getAppointmentByIdRoute);
 router14.post("/", createAppointmentRoute);
+router14.post("/$create-series", createSeriesRoute);
+router14.post("/$edit-series", editSeriesRoute);
+router14.post("/$cancel-series", cancelSeriesRoute);
 router14.put("/:id", updateAppointmentRoute);
 router14.delete("/:id", deleteAppointmentRoute);