Add open-slot availability for the calendar

A real calendar suggests free times instead of making staff eyeball gaps. Adds
a pure findOpenSlots engine (working window + slot length + busy intervals ->
free slots; supports a finer step than the slot, never runs past day end,
back-to-back aware) with 5 unit tests, exposed as appointments.availableSlots
(by date, duration, optional doctor/room, working hours). Reusable by the
portal booking flow and the agent.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: evangauer

apps/web/lib/scheduling/__tests__/availability.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+import { findOpenSlots } from "../availability";
+
+const d = (iso: string) => new Date(iso);
+
+describe("findOpenSlots", () => {
+  it("fills an empty day with non-overlapping slots", () => {
+    const slots = findOpenSlots({
+      dayStart: d("2026-06-02T09:00:00Z"),
+      dayEnd: d("2026-06-02T12:00:00Z"),
+      slotMinutes: 30,
+      busy: [],
+    });
+    expect(slots).toHaveLength(6); // 3 hours / 30 min
+    expect(slots[0]!.start.toISOString()).toBe("2026-06-02T09:00:00.000Z");
+    expect(slots[5]!.end.toISOString()).toBe("2026-06-02T12:00:00.000Z");
+  });
+
+  it("removes slots that overlap a busy interval but keeps adjacent ones", () => {
+    const slots = findOpenSlots({
+      dayStart: d("2026-06-02T09:00:00Z"),
+      dayEnd: d("2026-06-02T11:00:00Z"),
+      slotMinutes: 30,
+      busy: [{ startTime: d("2026-06-02T09:30:00Z"), endTime: d("2026-06-02T10:00:00Z") }],
+    });
+    const starts = slots.map((s) => s.start.toISOString());
+    // 09:00 ok, 09:30 blocked, 10:00 ok (back-to-back), 10:30 ok
+    expect(starts).toEqual([
+      "2026-06-02T09:00:00.000Z",
+      "2026-06-02T10:00:00.000Z",
+      "2026-06-02T10:30:00.000Z",
+    ]);
+  });
+
+  it("does not return a slot that would run past dayEnd", () => {
+    const slots = findOpenSlots({
+      dayStart: d("2026-06-02T09:00:00Z"),
+      dayEnd: d("2026-06-02T09:45:00Z"),
+      slotMinutes: 30,
+      busy: [],
+    });
+    // Only 09:00-09:30 fits; 09:30-10:00 would exceed dayEnd.
+    expect(slots).toHaveLength(1);
+  });
+
+  it("supports a finer step than the slot length", () => {
+    const slots = findOpenSlots({
+      dayStart: d("2026-06-02T09:00:00Z"),
+      dayEnd: d("2026-06-02T10:00:00Z"),
+      slotMinutes: 30,
+      stepMinutes: 15,
+      busy: [],
+    });
+    // starts at :00, :15, :30 (last that still fits a 30-min slot before 10:00)
+    expect(slots.map((s) => s.start.toISOString())).toEqual([
+      "2026-06-02T09:00:00.000Z",
+      "2026-06-02T09:15:00.000Z",
+      "2026-06-02T09:30:00.000Z",
+    ]);
+  });
+
+  it("throws on a non-positive slot length", () => {
+    expect(() =>
+      findOpenSlots({ dayStart: d("2026-06-02T09:00:00Z"), dayEnd: d("2026-06-02T10:00:00Z"), slotMinutes: 0, busy: [] })
+    ).toThrow(/positive/);
+  });
+});

apps/web/lib/scheduling/availability.ts

@@ -0,0 +1,40 @@
+import { overlaps } from "./conflicts";
+
+/**
+ * Pure open-slot generation. Given a working window, a slot length, and the
+ * busy intervals (existing appointments), produce the free slots a new
+ * appointment of that length could occupy. No I/O.
+ */
+
+export interface BusyInterval {
+  startTime: Date;
+  endTime: Date;
+}
+
+export interface OpenSlot {
+  start: Date;
+  end: Date;
+}
+
+export function findOpenSlots(opts: {
+  dayStart: Date;
+  dayEnd: Date;
+  slotMinutes: number;
+  /** Candidate start cadence; defaults to slotMinutes (non-overlapping slots). */
+  stepMinutes?: number;
+  busy: BusyInterval[];
+}): OpenSlot[] {
+  const { dayStart, dayEnd, slotMinutes, busy } = opts;
+  if (slotMinutes <= 0) throw new Error("slotMinutes must be positive.");
+  const step = (opts.stepMinutes && opts.stepMinutes > 0 ? opts.stepMinutes : slotMinutes) * 60_000;
+  const slotMs = slotMinutes * 60_000;
+
+  const slots: OpenSlot[] = [];
+  for (let t = dayStart.getTime(); t + slotMs <= dayEnd.getTime(); t += step) {
+    const start = new Date(t);
+    const end = new Date(t + slotMs);
+    const blocked = busy.some((b) => overlaps(start, end, b.startTime, b.endTime));
+    if (!blocked) slots.push({ start, end });
+  }
+  return slots;
+}

apps/web/server/routers/appointments.ts

@@ -18,6 +18,7 @@ import {
   hasConflict,
   type ExistingBooking,
 } from "@/lib/scheduling/conflicts";
+import { findOpenSlots } from "@/lib/scheduling/availability";
 
 /** Fetch blocking appointments overlapping [start, end) for conflict checks. */
 async function fetchOverlapping(
@@ -296,6 +297,41 @@ export const appointmentsRouter = createRouter({
       return updated!;
     }),
 
+  /** Open slots on a given date for a doctor and/or room. */
+  availableSlots: protectedProcedure
+    .input(
+      z.object({
+        date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+        durationMinutes: z.number().int().min(5).max(480).default(30),
+        stepMinutes: z.number().int().min(5).max(240).optional(),
+        doctorId: z.string().uuid().optional(),
+        roomId: z.string().uuid().optional(),
+        dayStartHour: z.number().int().min(0).max(23).default(8),
+        dayEndHour: z.number().int().min(1).max(24).default(18),
+      })
+    )
+    .query(async ({ ctx, input }) => {
+      const dayStart = new Date(`${input.date}T${String(input.dayStartHour).padStart(2, "0")}:00:00`);
+      const dayEnd = new Date(`${input.date}T${String(input.dayEndHour % 24 || 24).padStart(2, "0")}:00:00`);
+
+      const existing = await fetchOverlapping(ctx.db, ctx.practiceId, dayStart, dayEnd);
+      // Only the chosen doctor/room blocks availability; if neither given, any
+      // booking on the day blocks (treat the schedule as a single resource).
+      const busy = existing.filter((b) => {
+        if (input.doctorId && b.doctorId === input.doctorId) return true;
+        if (input.roomId && b.roomId === input.roomId) return true;
+        return !input.doctorId && !input.roomId;
+      });
+
+      return findOpenSlots({
+        dayStart,
+        dayEnd,
+        slotMinutes: input.durationMinutes,
+        stepMinutes: input.stepMinutes,
+        busy,
+      });
+    }),
+
   listTypes: protectedProcedure.query(async ({ ctx }) => {
     return ctx.db
       .select()