@agent-native/scheduling 0.2.1 → 0.2.2-nightly-20260927013707

package/src/actions/_helpers.ts

@@ -1,6 +1,3 @@
-/**
- * Shared helpers for actions in this package.
- */
 import { and, eq } from "drizzle-orm";
 
 import { getSchedulingContext } from "../server/context.js";
@@ -15,13 +12,6 @@ export function currentUserEmailOrNull(): string | null {
   return getSchedulingContext().getCurrentUserEmail() ?? null;
 }
 
-/**
- * Verify the current user is the host of a booking. Throws "Not authorized to
- * <action>" if not. Mirrors the `isHost` half of the `isHost || hasToken`
- * guard used by cancel-booking/reschedule-booking, for booking actions that
- * don't accept a public capability token (attendee/note/status mutations —
- * host identity is the only legitimate caller for these).
- */
 export function assertBookingHost(
   booking: { hostEmail: string },
   action: string,
@@ -56,12 +46,6 @@ export async function assertTeamAdmin(teamId: string): Promise<void> {
   }
 }
 
-/**
- * Verify the current user is a member of the team (any role). Read-only
- * team resource listings should gate on this so that team IDs cannot be
- * enumerated by guessing. Throws "Not authenticated" if there is no
- * current user, and "Forbidden" if the user is not a member.
- */
 export async function assertTeamMember(teamId: string): Promise<void> {
   const { getDb, schema } = getSchedulingContext();
   const email = currentUserEmail();

package/src/actions/booking-authz.spec.ts

@@ -1,9 +1,3 @@
-/**
- * Cross-tenant write (IDOR) regression tests for booking actions that
- * mutate — or disclose a capability token for — a booking that belongs to
- * another host. Mirrors the `isHost` guard already proven in
- * `cancel-booking.ts` / `reschedule-booking.ts`.
- */
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";

package/src/actions/create-team.ts

@@ -30,7 +30,6 @@ export default defineAction({
         ownerEmail,
         orgId: currentOrgId() ?? null,
       });
-    // Owner is automatically a member with owner role
     await getDb().insert(schema.teamMembers).values({
       id: nanoid(),
       teamId: id,

package/src/actions/event-type-authz.spec.ts

@@ -1,10 +1,3 @@
-/**
- * Cross-tenant write (IDOR) regression tests for event-type-scoped actions
- * that mutate a resource owned by another tenant: revoking a private hashed
- * link and duplicating an event type. Mirrors the `assertAccess("event-type",
- * ..., <role>)` guard already used by `add-private-link.ts` /
- * `delete-event-type.ts`.
- */
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -164,10 +157,6 @@ beforeEach(async () => {
   setSchedulingContext({
     getDb: () => db,
     schema,
-    // Mirrors real app wiring (templates/scheduling's server plugin): the
-    // scheduling package's own "current user" and the framework's
-    // request-context ALS (used by `assertAccess`) both resolve to the same
-    // identity.
     getCurrentUserEmail: () => getRequestUserEmail(),
   });
   registerShareableResource({

package/src/actions/list-bookings.ts

@@ -17,10 +17,6 @@ export default defineAction({
     from: z.string().optional(),
     to: z.string().optional(),
     limit: z.number().optional(),
-    /**
-     * If true, narrow to bookings where you are the host. Defaults to false
-     * so org-shared bookings + bookings shared with you appear too.
-     */
     onlyMine: z.boolean().optional().default(false),
   }),
   run: async (args) => {

package/src/actions/refresh-busy-times.ts

@@ -12,7 +12,6 @@ export default defineAction({
   run: async (args) => {
     const { getDb, schema } = getSchedulingContext();
     const email = args.userEmail ?? currentUserEmail();
-    // Delete cache rows for all of this user's credentials
     const creds = await getDb()
       .select({ id: schema.schedulingCredentials.id })
       .from(schema.schedulingCredentials)

package/src/actions/revoke-private-link.ts

@@ -20,8 +20,6 @@ export default defineAction({
     try {
       await assertAccess("event-type", link.eventTypeId, "editor");
     } catch {
-      // Keep private-link hashes unprobeable: callers without access receive
-      // the same idempotent result as callers presenting an unknown hash.
       return { ok: true };
     }
     await db

package/src/actions/update-profile.ts

@@ -3,8 +3,6 @@ import { z } from "zod";
 
 import { currentUserEmail } from "./_helpers.js";
 
-// Profile data lives in consumer-provided settings (not the scheduling schema);
-// this action delegates to the core `settings` subsystem via a well-known key.
 export default defineAction({
   description:
     "Update the current user's profile (name, bio, timezone, brand colors, etc.)",
@@ -20,9 +18,6 @@ export default defineAction({
     hideBranding: z.boolean().optional(),
   }),
   run: async (args) => {
-    // The consumer template wires a `profile-settings` settings key; we just
-    // read/merge/write it. Accessed via dynamic import to avoid a hard dep on
-    // the core settings API here (different consumers may use alternate stores).
     const core: any = await import("@agent-native/core");
     if (core.writeSetting) {
       const existing = (await core.readSetting?.("profile-settings")) ?? {};

package/src/core/buffers.ts

@@ -1,19 +1,6 @@
-/**
- * Buffer application.
- *
- * Buffers pad a slot with prep/cool-down time that the host needs but the
- * attendee shouldn't see as part of the meeting. A before-event buffer
- * means the slot reserves extra time before its displayed start; the slot
- * itself is still shown at the true meeting time.
- *
- * The practical effect: a slot [10:00–10:30] with before=10 means the host
- * is considered "busy" from 09:50 to 10:30, so it conflicts with a 09:00–09:50
- * meeting only if THAT meeting also has an after-buffer.
- */
 import type { BusyInterval } from "../shared/index.js";
 import { addMinutes } from "./time.js";
 
-/** Expand a busy interval to include before/after buffers. */
 export function applyBuffers(
   busy: BusyInterval,
   beforeMinutes: number,
@@ -28,11 +15,6 @@ export function applyBuffers(
   };
 }
 
-/**
- * Expand a proposed slot window (start→end) to include the event type's
- * before/after buffers. The expanded window is what collision detection
- * uses; the displayed slot remains the unexpanded window.
- */
 export function expandSlotForConflictCheck(
   start: Date,
   end: Date,

package/src/core/conflicts.ts

@@ -1,6 +1,3 @@
-/**
- * Conflict detection — does a proposed interval overlap any busy interval?
- */
 import type { BusyInterval } from "../shared/index.js";
 import { overlaps } from "./time.js";
 
@@ -21,7 +18,6 @@ export function hasConflict(
   return false;
 }
 
-/** Merge overlapping busy intervals into a canonical, non-overlapping set. */
 export function mergeBusy(busy: BusyInterval[]): BusyInterval[] {
   if (busy.length === 0) return [];
   const sorted = busy

package/src/core/limits.ts

@@ -1,14 +1,6 @@
 import { TZDate } from "@date-fns/tz";
 import { startOfWeek, startOfMonth, startOfYear, format } from "date-fns";
 
-/**
- * Booking limits enforcement.
- *
- * Limits constrain how many bookings an event type can receive in a time
- * window (day / week / month / year). We pass in existing booking counts
- * per bucket and return a function that tells us whether a proposed start
- * time would exceed any limit.
- */
 import type { BookingLimits } from "../shared/index.js";
 
 export interface BookingCounts {

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

@@ -53,7 +53,6 @@ describe("assignRoundRobin", () => {
       metrics,
       strategy: "lowest-recent-bookings",
     });
-    // priority 1 > priority 2; within priority 1, weight 5 > weight 1
     expect(result?.userEmail).toBe("c@x.com");
   });
 

package/src/core/round-robin.ts

@@ -1,23 +1,7 @@
-/**
- * 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;
 }
 
@@ -26,7 +10,6 @@ export interface AssignRoundRobinInput {
   metrics: Map<string, HostMetrics>;
   excludeEmails?: Set<string>;
   strategy: RoundRobinStrategy;
-  /** Deterministic seed (e.g. booking timestamp) for reproducible weighted picks */
   seed?: number;
 }
 

package/src/core/rrule.ts

@@ -1,9 +1,3 @@
-/**
- * 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(
@@ -13,7 +7,6 @@ export function expandRecurring(
   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

@@ -1,12 +1,3 @@
-/**
- * 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,
@@ -19,10 +10,6 @@ export interface ScheduleInput {
   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,
@@ -34,10 +21,6 @@ export function evaluateAvailabilityForDate(
   return weekly?.intervals ?? [];
 }
 
-/**
- * Normalize an interval list: sort by start, merge overlapping/adjacent,
- * drop zero-length.
- */
 export function normalizeIntervals(
   intervals: AvailabilityInterval[],
 ): AvailabilityInterval[] {

package/src/core/slots.test.ts

@@ -17,7 +17,6 @@ const utc: ScheduleInput = {
 
 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,
@@ -50,7 +49,6 @@ describe("computeAvailableSlots", () => {
       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");
   });
 
@@ -74,7 +72,6 @@ describe("computeAvailableSlots", () => {
         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();
@@ -94,15 +91,12 @@ describe("computeAvailableSlots", () => {
       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();
@@ -118,7 +112,6 @@ describe("computeAvailableSlots", () => {
       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"),
@@ -141,7 +134,6 @@ describe("computeAvailableSlots", () => {
       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(),
@@ -150,7 +142,6 @@ describe("computeAvailableSlots", () => {
   });
 
   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: [
@@ -171,9 +162,8 @@ describe("computeAvailableSlots", () => {
       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
+    expect(slots[0].start).toBe("2026-03-08T16:00:00.000Z");
   });
 
   it("respects seats-per-time-slot", () => {

package/src/core/slots.ts

@@ -1,21 +1,3 @@
-/**
- * Slot computation — the heart of the scheduling package.
- *
- * Input: an event type's config (duration, buffers, limits, period),
- *        a schedule (weekly hours + date overrides),
- *        a set of busy intervals (from external calendars + existing bookings),
- *        a time range to compute over.
- * Output: an array of Slot objects (UTC start/end) that are available
- *         and pass every constraint.
- *
- * Correctness priorities, in order:
- *   1. Never return a slot in the past (respect `now + minimumBookingNotice`)
- *   2. Never return a slot that overlaps a busy interval (with buffers)
- *   3. Never return a slot outside the schedule's available windows
- *   4. Never exceed booking limits (per-day/week/month/year)
- *   5. Respect the event type's period (rolling / range / unlimited)
- *   6. Correctness across DST transitions
- */
 import type {
   Slot,
   BusyInterval,
@@ -34,38 +16,25 @@ import {
 } from "./time.js";
 
 export interface ComputeSlotsInput {
-  /** Event type duration, minutes */
   duration: number;
-  /** Minutes before event start where the event type becomes unbookable; 0 = up to now */
   minimumBookingNotice: number;
-  /** Buffers in minutes applied to any existing busy interval and the candidate slot */
   beforeEventBuffer: number;
   afterEventBuffer: number;
-  /** Null = increment by duration */
   slotInterval: number | null;
   periodType: PeriodType;
   periodDays?: number;
   periodStartDate?: string;
   periodEndDate?: string;
   bookingLimits?: BookingLimits;
-  /** Schedule — intervals in schedule's timezone */
   schedule: ScheduleInput;
-  /** Busy intervals in UTC (already aggregated from all sources) */
   busy: BusyInterval[];
-  /** Existing bookings grouped by bucket key — used for limit enforcement */
   bookingCounts?: BookingCounts;
-  /** Week start for limit-bucketing */
   weekStartsOn?: 0 | 1;
-  /** Range to compute over, UTC */
   rangeStart: Date;
   rangeEnd: Date;
-  /** Current time (UTC). Defaults to now. */
   now?: Date;
-  /** Seats per slot — if > 1, slot stays available until seats exhausted */
   seatsPerTimeSlot?: number;
-  /** Seat count already reserved, keyed by ISO start */
   seatsTaken?: Map<string, number>;
-  /** Timezone in which the Booker displays the slots (for limit buckets) */
   viewerTimezone?: string;
 }
 
@@ -82,7 +51,6 @@ export function computeAvailableSlots(input: ComputeSlotsInput): Slot[] {
   const viewerTz = input.viewerTimezone ?? input.schedule.timezone;
   const slots: Slot[] = [];
 
-  // Enumerate each local day in the schedule's timezone that the range touches.
   const dates = localDatesInRange(
     rangeStart,
     rangeEnd,
@@ -114,19 +82,16 @@ export function computeAvailableSlots(input: ComputeSlotsInput): Slot[] {
       while (addMinutes(slotStart, input.duration) <= dayEndUtc) {
         const slotEnd = addMinutes(slotStart, input.duration);
 
-        // Cap to range
         if (slotStart < rangeStart || slotEnd > rangeEnd) {
           slotStart = addMinutes(slotStart, interval);
           continue;
         }
 
-        // Respect minimum notice
         if (slotStart < minBookableTime) {
           slotStart = addMinutes(slotStart, interval);
           continue;
         }
 
-        // Conflict check (expanded with buffers)
         const expanded = expandSlotForConflictCheck(
           slotStart,
           slotEnd,
@@ -138,7 +103,6 @@ export function computeAvailableSlots(input: ComputeSlotsInput): Slot[] {
           continue;
         }
 
-        // Booking limits (in viewer's timezone for perDay buckets)
         if (
           input.bookingCounts &&
           exceedsLimits(
@@ -153,7 +117,6 @@ export function computeAvailableSlots(input: ComputeSlotsInput): Slot[] {
           continue;
         }
 
-        // Seats
         const seatsTaken = input.seatsTaken?.get(slotStart.toISOString()) ?? 0;
         const seatsRemaining =
           input.seatsPerTimeSlot != null
@@ -189,7 +152,6 @@ function capToPeriodStart(
     const start = new Date(input.periodStartDate);
     return rangeStart > start ? rangeStart : start;
   }
-  // Rolling + unlimited don't restrict start
   return rangeStart > now ? rangeStart : now;
 }
 
@@ -210,8 +172,6 @@ function capToPeriodEnd(
 }
 
 function dayOfWeekForLocalDate(localDate: string, timezone: string): number {
-  // Construct a UTC date that corresponds to noon on that local date in the
-  // target timezone, then ask what day-of-week it is in that timezone.
   const noon = zonedTimeToUtc(localDate, "12:00", timezone);
   return getDayOfWeek(noon, timezone);
 }

package/src/core/time.ts

@@ -1,43 +1,22 @@
-/**
- * DST-safe time math.
- *
- * Rules:
- *   - Never use raw `Date` arithmetic for anything timezone-aware.
- *   - Always work in UTC internally; convert at the edges.
- *   - Date strings are ISO-8601 (UTC). Local-day strings are "YYYY-MM-DD".
- *   - Times of day are "HH:MM" (24h, no seconds).
- *   - Timezones are IANA identifiers like "America/Los_Angeles".
- */
 import { TZDate } from "@date-fns/tz";
 import { addMinutes as _addMinutes, differenceInMinutes } from "date-fns";
 
-/** Parse an ISO 8601 string to a UTC Date. */
 export function parseISO(iso: string): Date {
   return new Date(iso);
 }
 
-/** Format a Date to an ISO 8601 UTC string ending in "Z". */
 export function toISO(d: Date): string {
   return d.toISOString();
 }
 
-/** Add minutes to a Date (UTC-safe; DST-safe because we stay in UTC). */
 export function addMinutes(d: Date, minutes: number): Date {
   return _addMinutes(d, minutes);
 }
 
-/** Minutes between two Dates (end - start). Can be negative. */
 export function minutesBetween(start: Date, end: Date): number {
   return differenceInMinutes(end, start);
 }
 
-/**
- * Build a UTC Date from a local date + time of day + timezone.
- *
- * Example:
- *   zonedTimeToUtc("2026-04-04", "09:00", "America/Los_Angeles")
- *   → Date where UTC hour depends on whether PDT or PST is active.
- */
 export function zonedTimeToUtc(
   localDate: string,
   localTime: string,
@@ -45,13 +24,10 @@ export function zonedTimeToUtc(
 ): Date {
   const [y, m, d] = localDate.split("-").map(Number);
   const [h, mm] = localTime.split(":").map(Number);
-  // TZDate constructor takes local-in-timezone components and produces a
-  // Date whose UTC value is correct for that wall-clock time in `timezone`.
   const tz = new TZDate(y, (m ?? 1) - 1, d ?? 1, h ?? 0, mm ?? 0, 0, timezone);
   return new Date(tz.getTime());
 }
 
-/** Format a UTC Date into a "YYYY-MM-DD" string in the target timezone. */
 export function formatLocalDate(d: Date, timezone: string): string {
   const tz = new TZDate(d.getTime(), timezone);
   const yyyy = tz.getFullYear();
@@ -60,7 +36,6 @@ export function formatLocalDate(d: Date, timezone: string): string {
   return `${yyyy}-${mm}-${dd}`;
 }
 
-/** Format a UTC Date into a "HH:MM" string in the target timezone. */
 export function formatLocalTime(d: Date, timezone: string): string {
   const tz = new TZDate(d.getTime(), timezone);
   const hh = String(tz.getHours()).padStart(2, "0");
@@ -68,13 +43,11 @@ export function formatLocalTime(d: Date, timezone: string): string {
   return `${hh}:${mm}`;
 }
 
-/** Day of week (0=Sun, 6=Sat) for a UTC Date in the target timezone. */
 export function getDayOfWeek(d: Date, timezone: string): number {
   const tz = new TZDate(d.getTime(), timezone);
   return tz.getDay();
 }
 
-/** True if two intervals overlap (end-exclusive). */
 export function overlaps(
   a: { start: Date; end: Date },
   b: { start: Date; end: Date },
@@ -82,7 +55,6 @@ export function overlaps(
   return a.start < b.end && b.start < a.end;
 }
 
-/** Clamp a date range to a window. Returns null if they don't intersect. */
 export function clampRange(
   range: { start: Date; end: Date },
   window: { start: Date; end: Date },
@@ -93,10 +65,6 @@ export function clampRange(
   return { start, end };
 }
 
-/**
- * Iterate UTC Date objects from start (inclusive) to end (exclusive) by
- * stepping `stepMinutes`. Safe across DST because we never touch local time.
- */
 export function* steppedDates(
   start: Date,
   end: Date,
@@ -109,10 +77,6 @@ export function* steppedDates(
   }
 }
 
-/**
- * Enumerate "YYYY-MM-DD" local dates in `timezone` from `startUtc` to `endUtc`.
- * Useful for iterating per-day availability over a booking window.
- */
 export function localDatesInRange(
   startUtc: Date,
   endUtc: Date,
@@ -129,7 +93,6 @@ export function localDatesInRange(
     }
     cursor = addMinutes(cursor, 60);
   }
-  // Include final local day even if loop stopped exactly at midnight boundary
   const endLocal = formatLocalDate(new Date(endUtc.getTime() - 1), timezone);
   if (out[out.length - 1] !== endLocal) out.push(endLocal);
   return out;

package/src/index.ts

@@ -1,14 +1,3 @@
-/**
- * @agent-native/scheduling
- *
- * Root entry — re-exports shared types and constants only.
- * Subpath imports are the primary API surface:
- *
- *   import { eventTypes, bookings } from "@agent-native/scheduling/schema";
- *   import { computeAvailableSlots } from "@agent-native/scheduling/core";
- *   import { useSlots } from "@agent-native/scheduling/react";
- */
-
 export * from "./shared/index.js";
 export { MANIFEST } from "./manifest.js";
 export { VERSION } from "./version.js";