@agent-native/scheduling 0.1.1

package/src/core/round-robin.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from "vitest";
+import { assignRoundRobin, type HostMetrics } from "./round-robin.js";
+import type { Host } from "../shared/index.js";
+
+const host = (email: string, overrides: Partial<Host> = {}): Host => ({
+  userEmail: email,
+  eventTypeId: "et_1",
+  isFixed: false,
+  weight: 1,
+  priority: 2,
+  ...overrides,
+});
+
+describe("assignRoundRobin", () => {
+  it("returns null with no non-fixed hosts", () => {
+    const result = assignRoundRobin({
+      hosts: [host("a@x.com", { isFixed: true })],
+      metrics: new Map(),
+      strategy: "lowest-recent-bookings",
+    });
+    expect(result).toBeNull();
+  });
+
+  it("lowest-recent-bookings picks the host with fewest recent bookings", () => {
+    const hosts = [host("a@x.com"), host("b@x.com"), host("c@x.com")];
+    const metrics = new Map<string, HostMetrics>([
+      ["a@x.com", { recentBookingCount: 5, noShowRate: 0 }],
+      ["b@x.com", { recentBookingCount: 1, noShowRate: 0 }],
+      ["c@x.com", { recentBookingCount: 3, noShowRate: 0 }],
+    ]);
+    const result = assignRoundRobin({
+      hosts,
+      metrics,
+      strategy: "lowest-recent-bookings",
+    });
+    expect(result?.userEmail).toBe("b@x.com");
+  });
+
+  it("breaks ties by priority then weight then email", () => {
+    const hosts = [
+      host("a@x.com", { priority: 2, weight: 1 }),
+      host("b@x.com", { priority: 1, weight: 1 }),
+      host("c@x.com", { priority: 1, weight: 5 }),
+    ];
+    const metrics = new Map<string, HostMetrics>([
+      ["a@x.com", { recentBookingCount: 0, noShowRate: 0 }],
+      ["b@x.com", { recentBookingCount: 0, noShowRate: 0 }],
+      ["c@x.com", { recentBookingCount: 0, noShowRate: 0 }],
+    ]);
+    const result = assignRoundRobin({
+      hosts,
+      metrics,
+      strategy: "lowest-recent-bookings",
+    });
+    // priority 1 > priority 2; within priority 1, weight 5 > weight 1
+    expect(result?.userEmail).toBe("c@x.com");
+  });
+
+  it("excludes out-of-office hosts", () => {
+    const hosts = [host("a@x.com"), host("b@x.com")];
+    const metrics = new Map<string, HostMetrics>([
+      ["a@x.com", { recentBookingCount: 0, noShowRate: 0 }],
+      ["b@x.com", { recentBookingCount: 10, noShowRate: 0 }],
+    ]);
+    const result = assignRoundRobin({
+      hosts,
+      metrics,
+      excludeEmails: new Set(["a@x.com"]),
+      strategy: "lowest-recent-bookings",
+    });
+    expect(result?.userEmail).toBe("b@x.com");
+  });
+
+  it("weighted pick is deterministic given the same seed", () => {
+    const hosts = [
+      host("a@x.com", { weight: 1 }),
+      host("b@x.com", { weight: 3 }),
+      host("c@x.com", { weight: 1 }),
+    ];
+    const metrics = new Map();
+    const r1 = assignRoundRobin({
+      hosts,
+      metrics,
+      strategy: "weighted",
+      seed: 12345,
+    });
+    const r2 = assignRoundRobin({
+      hosts,
+      metrics,
+      strategy: "weighted",
+      seed: 12345,
+    });
+    expect(r1?.userEmail).toBe(r2?.userEmail);
+  });
+});

package/src/core/round-robin.ts

@@ -0,0 +1,103 @@
+/**
+ * Round-robin host assignment.
+ *
+ * For a given event type, pick the host who should take the next booking.
+ *
+ * Strategies:
+ *   - "lowest-recent-bookings" — host with fewest bookings in the rolling
+ *     window (default 30 days) wins; tie-break by priority then weight.
+ *   - "weighted" — distribute by relative weight; random weighted draw that's
+ *     deterministic-per-timestamp (seeded for reproducibility in tests).
+ *   - "calibrated" — weighted but scaled by no-show rate; hosts with high
+ *     no-show rates receive fewer bookings until their rate recovers.
+ *
+ * Out-of-office hosts are filtered out before selection.
+ */
+import type { Host, RoundRobinStrategy } from "../shared/index.js";
+
+export interface HostMetrics {
+  recentBookingCount: number;
+  /** 0–1; fraction of recent bookings that were no-shows */
+  noShowRate: number;
+}
+
+export interface AssignRoundRobinInput {
+  hosts: Host[];
+  metrics: Map<string, HostMetrics>;
+  excludeEmails?: Set<string>;
+  strategy: RoundRobinStrategy;
+  /** Deterministic seed (e.g. booking timestamp) for reproducible weighted picks */
+  seed?: number;
+}
+
+export function assignRoundRobin(input: AssignRoundRobinInput): Host | null {
+  const candidates = input.hosts.filter(
+    (h) => !h.isFixed && !input.excludeEmails?.has(h.userEmail),
+  );
+  if (candidates.length === 0) return null;
+
+  switch (input.strategy) {
+    case "lowest-recent-bookings":
+      return lowestBookings(candidates, input.metrics);
+    case "weighted":
+      return weightedPick(
+        candidates,
+        (h) => h.weight,
+        input.seed ?? Date.now(),
+      );
+    case "calibrated":
+      return weightedPick(
+        candidates,
+        (h) => {
+          const m = input.metrics.get(h.userEmail);
+          const penalty = m ? 1 - m.noShowRate * 0.5 : 1;
+          return Math.max(0.1, h.weight * penalty);
+        },
+        input.seed ?? Date.now(),
+      );
+  }
+}
+
+function lowestBookings(
+  hosts: Host[],
+  metrics: Map<string, HostMetrics>,
+): Host {
+  const sorted = hosts.slice().sort((a, b) => {
+    const ac = metrics.get(a.userEmail)?.recentBookingCount ?? 0;
+    const bc = metrics.get(b.userEmail)?.recentBookingCount ?? 0;
+    if (ac !== bc) return ac - bc;
+    if (a.priority !== b.priority) return a.priority - b.priority;
+    if (a.weight !== b.weight) return b.weight - a.weight;
+    return a.userEmail.localeCompare(b.userEmail);
+  });
+  return sorted[0];
+}
+
+function weightedPick(
+  hosts: Host[],
+  weightOf: (h: Host) => number,
+  seed: number,
+): Host {
+  const weights = hosts.map(weightOf);
+  const total = weights.reduce((a, b) => a + b, 0);
+  if (total <= 0) return hosts[0];
+  const rand = mulberry32(seed)();
+  let r = rand * total;
+  for (let i = 0; i < hosts.length; i++) {
+    r -= weights[i];
+    if (r <= 0) return hosts[i];
+  }
+  return hosts[hosts.length - 1];
+}
+
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return function () {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}

package/src/core/rrule.ts

@@ -0,0 +1,20 @@
+/**
+ * Recurring event expansion.
+ *
+ * Given an RRULE string and a time range, return the list of occurrence
+ * start times. Uses `rrule` npm package under the hood.
+ */
+import { RRule, rrulestr } from "rrule";
+
+export function expandRecurring(
+  rruleString: string,
+  dtstart: Date,
+  rangeStart: Date,
+  rangeEnd: Date,
+  maxOccurrences = 10,
+): Date[] {
+  // rrulestr parses RRULE:... with or without the DTSTART prefix.
+  const rule = rrulestr(rruleString, { dtstart }) as RRule;
+  const all = rule.between(rangeStart, rangeEnd, true);
+  return all.slice(0, maxOccurrences);
+}

package/src/core/rules.ts

@@ -0,0 +1,66 @@
+/**
+ * Availability rule evaluation.
+ *
+ * Given a Schedule (weekly rules + date overrides) and a local date in the
+ * schedule's timezone, produce the set of available intervals on that day.
+ *
+ * Date overrides win over weekly rules: an empty-intervals override blocks
+ * the day entirely; a non-empty override replaces the weekly rules for the day.
+ */
+import type {
+  AvailabilityInterval,
+  DateOverride,
+  WeeklyAvailability,
+} from "../shared/index.js";
+
+export interface ScheduleInput {
+  timezone: string;
+  weeklyAvailability: WeeklyAvailability[];
+  dateOverrides: DateOverride[];
+}
+
+/**
+ * Return the intervals available for a given local date.
+ * Intervals are in the schedule's local HH:MM, not UTC.
+ */
+export function evaluateAvailabilityForDate(
+  schedule: ScheduleInput,
+  localDate: string,
+  dayOfWeek: number,
+): AvailabilityInterval[] {
+  const override = schedule.dateOverrides.find((o) => o.date === localDate);
+  if (override) return override.intervals;
+  const weekly = schedule.weeklyAvailability.find((w) => w.day === dayOfWeek);
+  return weekly?.intervals ?? [];
+}
+
+/**
+ * Normalize an interval list: sort by start, merge overlapping/adjacent,
+ * drop zero-length.
+ */
+export function normalizeIntervals(
+  intervals: AvailabilityInterval[],
+): AvailabilityInterval[] {
+  const sorted = intervals
+    .filter((i) => toMinutes(i.startTime) < toMinutes(i.endTime))
+    .slice()
+    .sort((a, b) => toMinutes(a.startTime) - toMinutes(b.startTime));
+  const out: AvailabilityInterval[] = [];
+  for (const iv of sorted) {
+    const last = out[out.length - 1];
+    if (last && toMinutes(iv.startTime) <= toMinutes(last.endTime)) {
+      last.endTime =
+        toMinutes(iv.endTime) > toMinutes(last.endTime)
+          ? iv.endTime
+          : last.endTime;
+    } else {
+      out.push({ ...iv });
+    }
+  }
+  return out;
+}
+
+function toMinutes(hhmm: string): number {
+  const [h, m] = hhmm.split(":").map(Number);
+  return (h ?? 0) * 60 + (m ?? 0);
+}

package/src/core/slots.test.ts

@@ -0,0 +1,246 @@
+import { describe, it, expect } from "vitest";
+import { computeAvailableSlots } from "./slots.js";
+import type { ScheduleInput } from "./rules.js";
+
+const utc: ScheduleInput = {
+  timezone: "UTC",
+  weeklyAvailability: [
+    { day: 1, intervals: [{ startTime: "09:00", endTime: "17:00" }] }, // Mon
+    { day: 2, intervals: [{ startTime: "09:00", endTime: "17:00" }] }, // Tue
+    { day: 3, intervals: [{ startTime: "09:00", endTime: "17:00" }] }, // Wed
+    { day: 4, intervals: [{ startTime: "09:00", endTime: "17:00" }] }, // Thu
+    { day: 5, intervals: [{ startTime: "09:00", endTime: "17:00" }] }, // Fri
+  ],
+  dateOverrides: [],
+};
+
+describe("computeAvailableSlots", () => {
+  it("enumerates 30-minute slots across a single day", () => {
+    // Mon 2026-04-06 09:00Z → 17:00Z → 16 slots of 30 min
+    const slots = computeAvailableSlots({
+      duration: 30,
+      minimumBookingNotice: 0,
+      beforeEventBuffer: 0,
+      afterEventBuffer: 0,
+      slotInterval: null,
+      periodType: "unlimited",
+      schedule: utc,
+      busy: [],
+      rangeStart: new Date("2026-04-06T00:00:00Z"),
+      rangeEnd: new Date("2026-04-07T00:00:00Z"),
+      now: new Date("2026-04-06T00:00:00Z"),
+    });
+    expect(slots.length).toBe(16);
+    expect(slots[0].start).toBe("2026-04-06T09:00:00.000Z");
+    expect(slots[slots.length - 1].end).toBe("2026-04-06T17:00:00.000Z");
+  });
+
+  it("respects minimum booking notice", () => {
+    const slots = computeAvailableSlots({
+      duration: 30,
+      minimumBookingNotice: 180, // 3h
+      beforeEventBuffer: 0,
+      afterEventBuffer: 0,
+      slotInterval: null,
+      periodType: "unlimited",
+      schedule: utc,
+      busy: [],
+      rangeStart: new Date("2026-04-06T00:00:00Z"),
+      rangeEnd: new Date("2026-04-07T00:00:00Z"),
+      now: new Date("2026-04-06T10:00:00Z"),
+    });
+    // now=10:00, +3h → earliest bookable is 13:00
+    expect(slots[0].start).toBe("2026-04-06T13:00:00.000Z");
+  });
+
+  it("removes slots that conflict with busy intervals", () => {
+    const slots = computeAvailableSlots({
+      duration: 30,
+      minimumBookingNotice: 0,
+      beforeEventBuffer: 0,
+      afterEventBuffer: 0,
+      slotInterval: null,
+      periodType: "unlimited",
+      schedule: utc,
+      busy: [{ start: "2026-04-06T10:00:00Z", end: "2026-04-06T11:30:00Z" }],
+      rangeStart: new Date("2026-04-06T00:00:00Z"),
+      rangeEnd: new Date("2026-04-07T00:00:00Z"),
+      now: new Date("2026-04-06T00:00:00Z"),
+    });
+    const busy = slots.filter(
+      (s) =>
+        s.start >= "2026-04-06T10:00:00.000Z" &&
+        s.start < "2026-04-06T11:30:00.000Z",
+    );
+    expect(busy.length).toBe(0);
+    // 11:30 slot should still be available (not overlapping)
+    expect(
+      slots.find((s) => s.start === "2026-04-06T11:30:00.000Z"),
+    ).toBeTruthy();
+  });
+
+  it("applies before/after buffers", () => {
+    const slots = computeAvailableSlots({
+      duration: 30,
+      minimumBookingNotice: 0,
+      beforeEventBuffer: 15,
+      afterEventBuffer: 15,
+      slotInterval: null,
+      periodType: "unlimited",
+      schedule: utc,
+      busy: [{ start: "2026-04-06T11:00:00Z", end: "2026-04-06T11:30:00Z" }],
+      rangeStart: new Date("2026-04-06T00:00:00Z"),
+      rangeEnd: new Date("2026-04-07T00:00:00Z"),
+      now: new Date("2026-04-06T00:00:00Z"),
+    });
+    // 10:30 slot + afterBuffer=15 → conflict with 11:00 busy
+    expect(
+      slots.find((s) => s.start === "2026-04-06T10:30:00.000Z"),
+    ).toBeFalsy();
+    // 11:30 slot - beforeBuffer=15 → 11:15, conflicts with busy end at 11:30
+    expect(
+      slots.find((s) => s.start === "2026-04-06T11:30:00.000Z"),
+    ).toBeFalsy();
+    // 12:00 slot - 15 → 11:45, fully clear of busy interval [11:00, 11:30)
+    expect(
+      slots.find((s) => s.start === "2026-04-06T12:00:00.000Z"),
+    ).toBeTruthy();
+  });
+
+  it("honors weekly availability — returns no slots on weekends", () => {
+    const slots = computeAvailableSlots({
+      duration: 30,
+      minimumBookingNotice: 0,
+      beforeEventBuffer: 0,
+      afterEventBuffer: 0,
+      slotInterval: null,
+      periodType: "unlimited",
+      schedule: utc,
+      busy: [],
+      // 2026-04-04 is a Saturday
+      rangeStart: new Date("2026-04-04T00:00:00Z"),
+      rangeEnd: new Date("2026-04-05T00:00:00Z"),
+      now: new Date("2026-04-04T00:00:00Z"),
+    });
+    expect(slots.length).toBe(0);
+  });
+
+  it("caps rolling period", () => {
+    const slots = computeAvailableSlots({
+      duration: 30,
+      minimumBookingNotice: 0,
+      beforeEventBuffer: 0,
+      afterEventBuffer: 0,
+      slotInterval: null,
+      periodType: "rolling",
+      periodDays: 1,
+      schedule: utc,
+      busy: [],
+      rangeStart: new Date("2026-04-06T00:00:00Z"),
+      rangeEnd: new Date("2026-04-10T00:00:00Z"),
+      now: new Date("2026-04-06T08:00:00Z"),
+    });
+    // All slots must fall within [now, now+1d]
+    for (const s of slots) {
+      expect(new Date(s.end).getTime()).toBeLessThanOrEqual(
+        new Date("2026-04-07T08:00:00Z").getTime(),
+      );
+    }
+  });
+
+  it("handles DST transition (spring forward) in America/Los_Angeles", () => {
+    // 2026-03-08 is the spring-forward date in US; 2am→3am.
+    const tz: ScheduleInput = {
+      timezone: "America/Los_Angeles",
+      weeklyAvailability: [
+        { day: 0, intervals: [{ startTime: "09:00", endTime: "17:00" }] }, // Sunday
+      ],
+      dateOverrides: [],
+    };
+    const slots = computeAvailableSlots({
+      duration: 30,
+      minimumBookingNotice: 0,
+      beforeEventBuffer: 0,
+      afterEventBuffer: 0,
+      slotInterval: null,
+      periodType: "unlimited",
+      schedule: tz,
+      busy: [],
+      rangeStart: new Date("2026-03-08T00:00:00Z"),
+      rangeEnd: new Date("2026-03-09T00:00:00Z"),
+      now: new Date("2026-03-08T00:00:00Z"),
+    });
+    // 9-17 PDT on 2026-03-08 = 16:00 UTC to 00:00 UTC next day → 16 30-min slots
+    expect(slots.length).toBeGreaterThanOrEqual(15);
+    expect(slots[0].start).toBe("2026-03-08T16:00:00.000Z"); // 9am PDT = 16:00 UTC
+  });
+
+  it("respects seats-per-time-slot", () => {
+    const seatsTaken = new Map<string, number>([
+      ["2026-04-06T09:00:00.000Z", 2],
+    ]);
+    const slots = computeAvailableSlots({
+      duration: 30,
+      minimumBookingNotice: 0,
+      beforeEventBuffer: 0,
+      afterEventBuffer: 0,
+      slotInterval: null,
+      periodType: "unlimited",
+      schedule: utc,
+      busy: [],
+      rangeStart: new Date("2026-04-06T09:00:00Z"),
+      rangeEnd: new Date("2026-04-06T10:00:00Z"),
+      now: new Date("2026-04-06T00:00:00Z"),
+      seatsPerTimeSlot: 3,
+      seatsTaken,
+    });
+    const slot900 = slots.find((s) => s.start === "2026-04-06T09:00:00.000Z");
+    expect(slot900?.seatsRemaining).toBe(1);
+  });
+
+  it("respects booking limits (perDay)", () => {
+    const slots = computeAvailableSlots({
+      duration: 30,
+      minimumBookingNotice: 0,
+      beforeEventBuffer: 0,
+      afterEventBuffer: 0,
+      slotInterval: null,
+      periodType: "unlimited",
+      schedule: utc,
+      busy: [],
+      bookingLimits: { perDay: 2 },
+      bookingCounts: {
+        perDay: { "2026-04-06": 2 },
+        perWeek: {},
+        perMonth: {},
+        perYear: {},
+      },
+      rangeStart: new Date("2026-04-06T00:00:00Z"),
+      rangeEnd: new Date("2026-04-07T00:00:00Z"),
+      now: new Date("2026-04-06T00:00:00Z"),
+      viewerTimezone: "UTC",
+    });
+    expect(slots.length).toBe(0);
+  });
+
+  it("date override blocks day entirely", () => {
+    const tz: ScheduleInput = {
+      ...utc,
+      dateOverrides: [{ date: "2026-04-06", intervals: [] }],
+    };
+    const slots = computeAvailableSlots({
+      duration: 30,
+      minimumBookingNotice: 0,
+      beforeEventBuffer: 0,
+      afterEventBuffer: 0,
+      slotInterval: null,
+      periodType: "unlimited",
+      schedule: tz,
+      busy: [],
+      rangeStart: new Date("2026-04-06T00:00:00Z"),
+      rangeEnd: new Date("2026-04-07T00:00:00Z"),
+      now: new Date("2026-04-06T00:00:00Z"),
+    });
+    expect(slots.length).toBe(0);
+  });
+});