@agent-native/scheduling 0.1.1

package/src/core/slots.ts

@@ -0,0 +1,223 @@
+/**
+ * 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,
+  BookingLimits,
+  PeriodType,
+} from "../shared/index.js";
+import {
+  addMinutes,
+  getDayOfWeek,
+  formatLocalDate,
+  zonedTimeToUtc,
+  localDatesInRange,
+  overlaps,
+} from "./time.js";
+import { evaluateAvailabilityForDate, type ScheduleInput } from "./rules.js";
+import { hasConflict, mergeBusy } from "./conflicts.js";
+import {
+  exceedsLimits,
+  bucketKeysForSlot,
+  type BookingCounts,
+} from "./limits.js";
+import { expandSlotForConflictCheck } from "./buffers.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;
+}
+
+export function computeAvailableSlots(input: ComputeSlotsInput): Slot[] {
+  const now = input.now ?? new Date();
+  const minBookableTime = addMinutes(now, input.minimumBookingNotice);
+
+  const rangeStart = capToPeriodStart(input, input.rangeStart, now);
+  const rangeEnd = capToPeriodEnd(input, input.rangeEnd, now);
+  if (rangeStart >= rangeEnd) return [];
+
+  const mergedBusy = mergeBusy(input.busy);
+  const interval = input.slotInterval ?? input.duration;
+  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,
+    input.schedule.timezone,
+  );
+
+  for (const localDate of dates) {
+    const dow = dayOfWeekForLocalDate(localDate, input.schedule.timezone);
+    const dayIntervals = evaluateAvailabilityForDate(
+      input.schedule,
+      localDate,
+      dow,
+    );
+    if (dayIntervals.length === 0) continue;
+
+    for (const iv of dayIntervals) {
+      const dayStartUtc = zonedTimeToUtc(
+        localDate,
+        iv.startTime,
+        input.schedule.timezone,
+      );
+      const dayEndUtc = zonedTimeToUtc(
+        localDate,
+        iv.endTime,
+        input.schedule.timezone,
+      );
+
+      let slotStart = dayStartUtc;
+      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,
+          input.beforeEventBuffer,
+          input.afterEventBuffer,
+        );
+        if (hasConflict(expanded, mergedBusy)) {
+          slotStart = addMinutes(slotStart, interval);
+          continue;
+        }
+
+        // Booking limits (in viewer's timezone for perDay buckets)
+        if (
+          input.bookingCounts &&
+          exceedsLimits(
+            slotStart,
+            viewerTz,
+            input.bookingLimits,
+            input.bookingCounts,
+            input.weekStartsOn ?? 0,
+          )
+        ) {
+          slotStart = addMinutes(slotStart, interval);
+          continue;
+        }
+
+        // Seats
+        const seatsTaken = input.seatsTaken?.get(slotStart.toISOString()) ?? 0;
+        const seatsRemaining =
+          input.seatsPerTimeSlot != null
+            ? Math.max(0, input.seatsPerTimeSlot - seatsTaken)
+            : undefined;
+
+        if (input.seatsPerTimeSlot != null && seatsRemaining === 0) {
+          slotStart = addMinutes(slotStart, interval);
+          continue;
+        }
+
+        slots.push({
+          start: slotStart.toISOString(),
+          end: slotEnd.toISOString(),
+          available: true,
+          seatsRemaining,
+        });
+
+        slotStart = addMinutes(slotStart, interval);
+      }
+    }
+  }
+
+  return slots;
+}
+
+function capToPeriodStart(
+  input: ComputeSlotsInput,
+  rangeStart: Date,
+  now: Date,
+): Date {
+  if (input.periodType === "range" && input.periodStartDate) {
+    const start = new Date(input.periodStartDate);
+    return rangeStart > start ? rangeStart : start;
+  }
+  // Rolling + unlimited don't restrict start
+  return rangeStart > now ? rangeStart : now;
+}
+
+function capToPeriodEnd(
+  input: ComputeSlotsInput,
+  rangeEnd: Date,
+  now: Date,
+): Date {
+  if (input.periodType === "range" && input.periodEndDate) {
+    const end = new Date(input.periodEndDate);
+    return rangeEnd < end ? rangeEnd : end;
+  }
+  if (input.periodType === "rolling" && input.periodDays != null) {
+    const rollingEnd = addMinutes(now, input.periodDays * 24 * 60);
+    return rangeEnd < rollingEnd ? rangeEnd : rollingEnd;
+  }
+  return rangeEnd;
+}
+
+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

@@ -0,0 +1,136 @@
+/**
+ * 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,
+  timezone: string,
+): 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();
+  const mm = String(tz.getMonth() + 1).padStart(2, "0");
+  const dd = String(tz.getDate()).padStart(2, "0");
+  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");
+  const mm = String(tz.getMinutes()).padStart(2, "0");
+  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 },
+): boolean {
+  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 },
+): { start: Date; end: Date } | null {
+  const start = range.start > window.start ? range.start : window.start;
+  const end = range.end < window.end ? range.end : window.end;
+  if (start >= end) return null;
+  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,
+  stepMinutes: number,
+): Generator<Date> {
+  let cursor = new Date(start.getTime());
+  while (cursor < end) {
+    yield cursor;
+    cursor = addMinutes(cursor, stepMinutes);
+  }
+}
+
+/**
+ * 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,
+  timezone: string,
+): string[] {
+  const out: string[] = [];
+  let cursor = startUtc;
+  let last = "";
+  while (cursor < endUtc) {
+    const d = formatLocalDate(cursor, timezone);
+    if (d !== last) {
+      out.push(d);
+      last = d;
+    }
+    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

@@ -0,0 +1,14 @@
+/**
+ * @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";

package/src/manifest.ts

@@ -0,0 +1,174 @@
+/**
+ * Machine-readable manifest of what this package ships.
+ *
+ * Consumed by `agent-native add scheduling` (or the template scaffolder) to:
+ *   - generate stub action files in the consumer's `actions/` folder
+ *   - symlink/copy skill files into the consumer's `.agents/skills/`
+ *   - append required secret declarations
+ *   - print the list in `agent-native info @agent-native/scheduling`
+ */
+
+export interface SchedulingManifest {
+  name: string;
+  version: string;
+  actions: string[];
+  schemaEntryPoint: string;
+  docs: {
+    llms: string;
+    llmsFull: string;
+    skills: string[];
+  };
+  requiredSecrets: { key: string; label: string; optional?: boolean }[];
+  peerProviders: string[];
+}
+
+export const MANIFEST: SchedulingManifest = {
+  name: "@agent-native/scheduling",
+  version: "0.1.0",
+  actions: [
+    // Event types
+    "list-event-types",
+    "get-event-type",
+    "create-event-type",
+    "update-event-type",
+    "duplicate-event-type",
+    "delete-event-type",
+    "toggle-event-type-hidden",
+    "reorder-event-types",
+    "set-event-type-location",
+    "add-private-link",
+    "revoke-private-link",
+    // Availability / schedules
+    "list-schedules",
+    "create-schedule",
+    "update-schedule",
+    "delete-schedule",
+    "set-default-schedule",
+    "add-date-override",
+    "remove-date-override",
+    "get-availability",
+    "check-availability",
+    "find-available-slot",
+    // Bookings
+    "list-bookings",
+    "get-booking",
+    "create-booking",
+    "reschedule-booking",
+    "cancel-booking",
+    "confirm-booking",
+    "mark-no-show",
+    "add-booking-attendee",
+    "remove-booking-attendee",
+    "send-reschedule-link",
+    "add-booking-note",
+    "export-bookings-csv",
+    // Integrations
+    "list-calendar-integrations",
+    "connect-calendar",
+    "connect-video",
+    "disconnect-calendar",
+    "list-selected-calendars",
+    "toggle-selected-calendar",
+    "set-destination-calendar",
+    "refresh-busy-times",
+    "install-conferencing-app",
+    // Team
+    "create-team",
+    "invite-team-member",
+    "accept-team-invite",
+    "remove-team-member",
+    "update-member-role",
+    "set-team-branding",
+    // Round-robin / hosts
+    "assign-round-robin-host",
+    "set-event-type-hosts",
+    "set-host-availability-override",
+    "create-host-group",
+    // Settings / profile
+    "update-profile",
+    "set-appearance",
+    "set-default-conferencing-app",
+    // Workflows
+    "list-workflows",
+    "create-workflow",
+    "update-workflow",
+    "delete-workflow",
+    "toggle-workflow",
+    // Routing forms
+    "list-routing-forms",
+    "create-routing-form",
+    "update-routing-form",
+    "delete-routing-form",
+    "submit-routing-form-response",
+    "list-routing-form-responses",
+  ],
+  schemaEntryPoint: "@agent-native/scheduling/schema",
+  docs: {
+    llms: "docs/llms.txt",
+    llmsFull: "docs/llms-full.txt",
+    skills: [
+      "scheduling-basics",
+      "event-types",
+      "availability",
+      "bookings",
+      "booker",
+      "slot-engine",
+      "team-scheduling",
+      "integrations",
+      "embeds",
+      "workflows",
+      "routing-forms",
+    ],
+  },
+  requiredSecrets: [
+    {
+      key: "GOOGLE_CLIENT_ID",
+      label: "Google OAuth Client ID",
+      optional: true,
+    },
+    {
+      key: "GOOGLE_CLIENT_SECRET",
+      label: "Google OAuth Client Secret",
+      optional: true,
+    },
+    {
+      key: "MICROSOFT_CLIENT_ID",
+      label: "Microsoft OAuth Client ID",
+      optional: true,
+    },
+    {
+      key: "MICROSOFT_CLIENT_SECRET",
+      label: "Microsoft OAuth Client Secret",
+      optional: true,
+    },
+    { key: "ZOOM_CLIENT_ID", label: "Zoom OAuth Client ID", optional: true },
+    {
+      key: "ZOOM_CLIENT_SECRET",
+      label: "Zoom OAuth Client Secret",
+      optional: true,
+    },
+    {
+      key: "DAILY_API_KEY",
+      label: "Daily.co API Key (built-in video)",
+      optional: true,
+    },
+    {
+      key: "TWILIO_ACCOUNT_SID",
+      label: "Twilio Account SID (SMS workflows)",
+      optional: true,
+    },
+    { key: "TWILIO_AUTH_TOKEN", label: "Twilio Auth Token", optional: true },
+    {
+      key: "TWILIO_FROM_NUMBER",
+      label: "Twilio sender number",
+      optional: true,
+    },
+  ],
+  peerProviders: [
+    "google-calendar",
+    "office365",
+    "zoom",
+    "google-meet",
+    "builtin-video",
+  ],
+};

package/src/react/components/SlotPicker.tsx

@@ -0,0 +1,72 @@
+/**
+ * SlotPicker — minimal, unstyled primitive that renders a vertical list of
+ * available slots grouped by date. Consumers style the buttons via their
+ * own Tailwind class layer.
+ *
+ * This is the "headless" spec: if you want a fully styled picker, look at
+ * `templates/scheduling/app/components/booker/SlotPicker.tsx`.
+ */
+import type { Slot } from "../../shared/index.js";
+import { TZDate } from "@date-fns/tz";
+import { format } from "date-fns";
+import React from "react";
+
+export interface SlotPickerProps {
+  slots: Slot[];
+  timezone: string;
+  selectedStart?: string;
+  onSelect: (slot: Slot) => void;
+  timeFormat?: "12h" | "24h";
+  className?: string;
+  slotClassName?: string;
+  dayClassName?: string;
+}
+
+export function SlotPicker(props: SlotPickerProps) {
+  const grouped = new Map<string, Slot[]>();
+  for (const s of props.slots) {
+    const localDay = format(
+      new TZDate(new Date(s.start).getTime(), props.timezone),
+      "yyyy-MM-dd",
+    );
+    if (!grouped.has(localDay)) grouped.set(localDay, []);
+    grouped.get(localDay)!.push(s);
+  }
+  const fmt = props.timeFormat === "24h" ? "HH:mm" : "h:mma";
+
+  return (
+    <div className={props.className ?? ""}>
+      {Array.from(grouped.entries()).map(([date, daySlots]) => (
+        <section key={date} className={props.dayClassName ?? ""}>
+          <header>
+            {format(
+              new TZDate(`${date}T12:00:00Z`, props.timezone),
+              "EEEE, MMM d",
+            )}
+          </header>
+          <ul>
+            {daySlots.map((s) => (
+              <li key={s.start}>
+                <button
+                  type="button"
+                  className={props.slotClassName ?? ""}
+                  aria-pressed={props.selectedStart === s.start}
+                  disabled={!s.available}
+                  onClick={() => props.onSelect(s)}
+                >
+                  {format(
+                    new TZDate(new Date(s.start).getTime(), props.timezone),
+                    fmt,
+                  )}
+                  {s.seatsRemaining != null && s.seatsRemaining > 0 && (
+                    <span> · {s.seatsRemaining} left</span>
+                  )}
+                </button>
+              </li>
+            ))}
+          </ul>
+        </section>
+      ))}
+    </div>
+  );
+}

package/src/react/components/TimezoneSelect.tsx

@@ -0,0 +1,55 @@
+/**
+ * TimezoneSelect — unstyled primitive. A native <select> with the full IANA
+ * list. Consumer should swap the outer element for shadcn Select.
+ */
+import React from "react";
+
+export interface TimezoneSelectProps {
+  value: string;
+  onChange: (tz: string) => void;
+  className?: string;
+}
+
+// A compact list; consumers can replace with the full 600+ IANA zones from
+// `Intl.supportedValuesOf("timeZone")` at the call site if they need all of them.
+const COMMON_ZONES = [
+  "UTC",
+  "America/New_York",
+  "America/Chicago",
+  "America/Denver",
+  "America/Los_Angeles",
+  "America/Sao_Paulo",
+  "Europe/London",
+  "Europe/Paris",
+  "Europe/Berlin",
+  "Europe/Moscow",
+  "Africa/Cairo",
+  "Asia/Jerusalem",
+  "Asia/Dubai",
+  "Asia/Kolkata",
+  "Asia/Singapore",
+  "Asia/Tokyo",
+  "Asia/Shanghai",
+  "Australia/Sydney",
+  "Pacific/Auckland",
+];
+
+export function TimezoneSelect(props: TimezoneSelectProps) {
+  const supported =
+    typeof Intl !== "undefined" && (Intl as any).supportedValuesOf
+      ? (Intl as any).supportedValuesOf("timeZone")
+      : COMMON_ZONES;
+  return (
+    <select
+      value={props.value}
+      onChange={(e) => props.onChange(e.currentTarget.value)}
+      className={props.className ?? ""}
+    >
+      {supported.map((tz: string) => (
+        <option key={tz} value={tz}>
+          {tz}
+        </option>
+      ))}
+    </select>
+  );
+}