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

package/src/server/event-types-repo.ts

@@ -1,10 +1,4 @@
 import { accessFilter } from "@agent-native/core/sharing";
-/**
- * Data access for event types.
- *
- * All write paths funnel through here so ownership, slug uniqueness, and
- * redirect history are handled consistently.
- */
 import { eq, and } from "drizzle-orm";
 import { nanoid } from "nanoid";
 
@@ -75,29 +69,15 @@ function parseJson<T = any>(str: string | null | undefined): T | undefined {
 }
 
 export async function listEventTypes(params: {
-  /**
-   * If provided and `useAccessFilter` is not true, narrow rows to this owner.
-   * For org-aware list calls, prefer `useAccessFilter: true` instead.
-   */
   ownerEmail?: string;
   teamId?: string;
   includeHidden?: boolean;
-  /**
-   * When true, apply the framework `accessFilter` (owner OR shared OR
-   * org-visibility OR public) instead of plain ownerEmail equality. This is
-   * the right mode for any UI/agent listing, since it admits org-shared and
-   * explicitly-shared event types in addition to the user's own.
-   */
   useAccessFilter?: boolean;
 }): Promise<EventType[]> {
   const { getDb, schema } = getSchedulingContext();
   const db = getDb();
   let rows: any[];
   if (params.teamId) {
-    // Team-scoped listings. Callers are responsible for asserting team
-    // membership before invoking — the repo does not (it runs without a
-    // request context in some paths, e.g. public booking pages that
-    // explicitly pass a teamId).
     rows = await db
       .select()
       .from(schema.eventTypes)
@@ -113,8 +93,6 @@ export async function listEventTypes(params: {
       .from(schema.eventTypes)
       .where(eq(schema.eventTypes.ownerEmail, params.ownerEmail));
   } else {
-    // Refuse to return unscoped results. Callers must supply at least
-    // one of: teamId, useAccessFilter, or ownerEmail.
     return [];
   }
   return rows
@@ -185,9 +163,6 @@ export async function createEventType(input: {
   const db = getDb();
   const now = new Date().toISOString();
   const id = nanoid();
-  // Default location: the user's `isDefault` conferencing credential if they
-  // have one installed (Zoom, Meet, Teams), otherwise no location — the
-  // editor will prompt them to pick.
   const defaultLocations: Location[] =
     input.locations ??
     (input.ownerEmail ? await resolveDefaultLocation(input.ownerEmail) : []);
@@ -242,7 +217,6 @@ export async function updateEventType(
   const dbPatch: Record<string, any> = {};
   if (patch.title != null) dbPatch.title = patch.title;
   if (patch.slug != null && patch.slug !== current.slug) {
-    // Record slug redirect
     const oldKey = keyFor(
       current.ownerEmail ?? null,
       current.teamId ?? null,
@@ -337,11 +311,6 @@ export async function deleteEventType(id: string): Promise<void> {
   await getDb().delete(schema.eventTypes).where(eq(schema.eventTypes.id, id));
 }
 
-/**
- * Return a sensible default location for a freshly-created event type.
- * Priority: the user's `isDefault` video conferencing credential → the
- * first installed video credential → an empty list (editor prompts user).
- */
 async function resolveDefaultLocation(ownerEmail: string): Promise<Location[]> {
   const { getDb, schema } = getSchedulingContext();
   const rows = await getDb()

package/src/server/hooks.ts

@@ -1,12 +1,3 @@
-/**
- * Booking lifecycle hooks → workflow / webhook dispatcher.
- *
- * When a booking is created / rescheduled / cancelled / no-shown, we:
- *   - Materialize scheduled reminders for each active workflow step
- *   - Enqueue outgoing webhook deliveries
- *
- * The actual reminder + webhook firing happens on a recurring job (not here).
- */
 import { eq, and, inArray } from "drizzle-orm";
 import { nanoid } from "nanoid";
 
@@ -31,7 +22,6 @@ export async function onBookingRescheduled(
 export async function onBookingCancelled(booking: Booking): Promise<void> {
   await materializeReminders(booking, "cancellation");
   await enqueueWebhooks(booking, "BOOKING_CANCELLED");
-  // Cancel any pending before-event reminders
   const { getDb, schema } = getSchedulingContext();
   await getDb()
     .update(schema.scheduledReminders)
@@ -74,7 +64,6 @@ async function materializeRemindersBefore(booking: Booking): Promise<void> {
   const start = new Date(booking.startTime);
   for (const wf of workflows) {
     for (const step of wf.steps) {
-      // offsetMinutes is how many minutes BEFORE the event
       const scheduledFor = addMinutes(start, -Math.abs(step.offsetMinutes));
       if (scheduledFor <= new Date()) continue;
       await writeReminder(booking, step, scheduledFor);

package/src/server/ics.ts

@@ -1,10 +1,3 @@
-/**
- * Minimal iCalendar (RFC 5545) generator for booking confirmation emails and
- * the `/booking/:uid.ics` download endpoint.
- *
- * Not exhaustive — just enough for Apple Mail / Outlook / Gmail to render
- * the event card correctly and for Add-to-Calendar buttons to work.
- */
 import type { Booking } from "../shared/index.js";
 
 export function buildIcs(booking: Booking, organizerName: string): string {

package/src/server/providers/builtin-video.ts

@@ -1,12 +1,7 @@
-/**
- * Built-in video provider (Daily.co) — zero-OAuth video provider driven by a
- * server-to-server API key. Creates a Daily.co room per booking.
- */
 import type { VideoProvider } from "./types.js";
 
 export interface DailyVideoProviderConfig {
   apiKey: string;
-  /** Prefix for Daily room names; defaults to "room-" */
   roomPrefix?: string;
 }
 

package/src/server/providers/google-calendar.ts

@@ -15,14 +15,11 @@ import type { CalendarProvider } from "./types.js";
 export interface GoogleCalendarProviderConfig {
   clientId: string;
   clientSecret: string;
-  /** Resolve a fresh access token for a given credentialId (refresh if needed). */
   getAccessToken: (credentialId: string) => Promise<string>;
-  /** Persist updated refresh/access tokens after a refresh. */
   updateTokens?: (
     credentialId: string,
     tokens: { accessToken: string; refreshToken?: string; expiresAt?: Date },
   ) => Promise<void>;
-  /** Called when the API returns 401/403; the consumer should mark the credential invalid. */
   markInvalid?: (credentialId: string) => Promise<void>;
 }
 
@@ -104,7 +101,6 @@ export function createGoogleCalendarProvider(
         expiresAt: new Date(Date.now() + (tokens.expires_in ?? 3600) * 1000),
       });
 
-      // Discover external email + calendar list
       const calendars = await apiCall<{
         items: { id: string; summary: string; primary?: boolean }[];
       }>(
@@ -208,7 +204,6 @@ export function createGoogleCalendarProvider(
     },
 
     async updateEvent({ credentialId, externalId, booking }) {
-      // Bump sequence for RFC 5545 compliance
       const newSeq = booking.iCalSequence + 1;
       const body = {
         summary: booking.title,

package/src/server/providers/google-meet.ts

@@ -1,10 +1,3 @@
-/**
- * Google Meet — piggy-backs on Google Calendar credentials. The meeting link
- * is created as part of the calendar event (conferenceData). This provider
- * exists so we can list Google Meet as an installable conferencing option in
- * the UI; the actual meeting creation happens in `google-calendar.createEvent`
- * when `includeConference` is true.
- */
 import type { VideoProvider } from "./types.js";
 
 export const googleMeetProvider: VideoProvider = {

package/src/server/providers/office365.ts

@@ -1,10 +1,4 @@
 import type { BusyInterval } from "../../shared/index.js";
-/**
- * Office 365 / Outlook calendar provider via Microsoft Graph.
- *
- * Token flow is identical to Google but against login.microsoftonline.com.
- * Uses Microsoft Graph API for calendars and events.
- */
 import type { CalendarProvider } from "./types.js";
 
 export interface Office365ProviderConfig {

package/src/server/providers/registry.ts

@@ -1,7 +1,3 @@
-/**
- * Provider registry — consumers register calendar/video/SMS providers at
- * startup. Actions look up providers by kind.
- */
 import type { CalendarProvider, VideoProvider, SmsProvider } from "./types.js";
 
 const calendarProviders = new Map<string, CalendarProvider>();

package/src/server/providers/teams.ts

@@ -1,13 +1,8 @@
-/**
- * Microsoft Teams provider — delegated Microsoft OAuth with Graph-backed
- * standalone online meetings.
- */
 import type { VideoProvider } from "./types.js";
 
 export interface TeamsProviderConfig {
   clientId: string;
   clientSecret: string;
-  /** Microsoft tenant id/domain; defaults to work-or-school accounts. */
   tenant?: string;
   getAccessToken: (credentialId: string) => Promise<string>;
   updateTokens?: (
@@ -19,7 +14,6 @@ export interface TeamsProviderConfig {
       rawResponse?: Record<string, unknown>;
     },
   ) => Promise<void>;
-  /** Called when Graph returns 401/403; mark the credential invalid in UI. */
   markInvalid?: (credentialId: string) => Promise<void>;
 }
 
@@ -106,8 +100,6 @@ export function createTeamsProvider(
         rawResponse: tokens,
       });
 
-      // Use the token from this exchange directly. The consumer's token store
-      // may not be observable through getAccessToken until after this callback.
       const identityResponse = await fetch(
         `${GRAPH_BASE_URL}/me?$select=id,mail,userPrincipalName,displayName`,
         { headers: { authorization: `Bearer ${tokens.access_token}` } },

package/src/server/providers/types.ts

@@ -1,29 +1,15 @@
-/**
- * Pluggable provider interfaces for calendar reads and video-meeting writes.
- *
- * Consumers register providers via the registry. Each provider owns its own
- * OAuth/credential lifecycle; this package is agnostic to how the tokens
- * are stored (typically in core `oauth_tokens`).
- */
 import type { BusyInterval, Booking } from "../../shared/index.js";
 
 export interface CalendarProvider {
-  /** Unique provider slug, e.g. "google_calendar" */
   kind: string;
 
-  /** Human-friendly display name, e.g. "Google Calendar" */
   label: string;
 
-  /**
-   * Start the OAuth flow — return an authorization URL for the user to visit.
-   * `redirectUri` is the server's OAuth callback path for this provider.
-   */
   startOAuth(opts: {
     redirectUri: string;
     state: string;
   }): Promise<{ authUrl: string }>;
 
-  /** Complete the OAuth flow with the received code; persist the credential. */
   completeOAuth(opts: {
     credentialId: string;
     userEmail: string;
@@ -34,12 +20,10 @@ export interface CalendarProvider {
     calendars: { externalId: string; name: string; primary: boolean }[];
   }>;
 
-  /** List the calendars the user has access to (for Selected Calendars UI). */
   listCalendars(opts: {
     credentialId: string;
   }): Promise<{ externalId: string; name: string; primary: boolean }[]>;
 
-  /** Read busy intervals across the user's selected calendars. */
   getBusy(opts: {
     credentialId: string;
     calendarExternalIds: string[];
@@ -47,7 +31,6 @@ export interface CalendarProvider {
     end: Date;
   }): Promise<BusyInterval[]>;
 
-  /** Create a calendar event; return the external id. */
   createEvent(opts: {
     credentialId: string;
     calendarExternalId: string;
@@ -59,14 +42,12 @@ export interface CalendarProvider {
     icalUid?: string;
   }>;
 
-  /** Update (e.g. after reschedule). Returns the new iCalSequence. */
   updateEvent(opts: {
     credentialId: string;
     externalId: string;
     booking: Booking;
   }): Promise<{ iCalSequence: number }>;
 
-  /** Delete/cancel an event. */
   deleteEvent(opts: {
     credentialId: string;
     externalId: string;
@@ -88,12 +69,6 @@ export interface VideoProvider {
     state: string;
   }): Promise<{ authUrl: string }>;
 
-  /**
-   * Complete the OAuth flow — optional. Paired with `startOAuth`. Consumers
-   * call this from their OAuth callback handler to exchange the `code` for
-   * tokens and return identifying info so a `scheduling_credentials` row
-   * can be written.
-   */
   completeOAuth?(opts: {
     credentialId: string;
     userEmail: string;
@@ -105,14 +80,12 @@ export interface VideoProvider {
     displayName?: string;
   }>;
 
-  /** Create a meeting room for a booking. */
   createMeeting(opts: { credentialId?: string; booking: Booking }): Promise<{
     meetingUrl: string;
     meetingId: string;
     meetingPassword?: string;
   }>;
 
-  /** Delete the meeting when the booking is cancelled. */
   deleteMeeting?(opts: {
     credentialId?: string;
     meetingId: string;

package/src/server/providers/zoom.ts

@@ -1,16 +1,3 @@
-/**
- * Zoom provider — OAuth-based; creates a Zoom meeting per booking.
- *
- * Tokens are stored via the consumer's callback (typically core's
- * oauth_tokens), keyed by credentialId. Consumers wire up
- * `getAccessToken` + `updateTokens` against their token store.
- *
- * OAuth:
- *   - Auth URL:   https://zoom.us/oauth/authorize?response_type=code&...
- *   - Token URL:  https://zoom.us/oauth/token (basic-auth client_id:secret)
- *   - Scopes:     meeting:write meeting:read (so we can create + delete)
- *   - User info:  GET https://api.zoom.us/v2/users/me (returns account_id + email)
- */
 import type { VideoProvider } from "./types.js";
 
 export class ZoomProviderError extends Error {
@@ -27,11 +14,6 @@ export interface ZoomProviderConfig {
   clientId: string;
   clientSecret: string;
   getAccessToken: (credentialId: string) => Promise<string>;
-  /**
-   * Persist tokens after `completeOAuth` (and any later refresh). Optional —
-   * if omitted, the consumer is responsible for doing the write inside their
-   * own callback handler.
-   */
   updateTokens?: (
     credentialId: string,
     tokens: {
@@ -41,11 +23,9 @@ export interface ZoomProviderConfig {
       rawResponse?: Record<string, unknown>;
     },
   ) => Promise<void>;
-  /** Called when the API returns 401/403; mark credential invalid in UI. */
   markInvalid?: (credentialId: string) => Promise<void>;
 }
 
-// Minimum scope needed to create + read meetings on the user's behalf.
 const SCOPES = ["meeting:write", "meeting:read", "user:read"];
 
 export function createZoomProvider(config: ZoomProviderConfig): VideoProvider {
@@ -103,7 +83,6 @@ export function createZoomProvider(config: ZoomProviderConfig): VideoProvider {
         rawResponse: tokens as unknown as Record<string, unknown>,
       });
 
-      // Pull user info to label the credential.
       const userRes = await fetch("https://api.zoom.us/v2/users/me", {
         headers: { authorization: `Bearer ${tokens.access_token}` },
       });

package/src/server/schedules-repo.ts

@@ -1,8 +1,4 @@
 import { accessFilter } from "@agent-native/core/sharing";
-/**
- * Data access for schedules — the weekly-hours + date-override definitions
- * that event types reference.
- */
 import { eq, and, inArray, type SQL } from "drizzle-orm";
 import { nanoid } from "nanoid";
 

package/src/server/video-oauth-state.ts

@@ -18,7 +18,7 @@
 import crypto from "node:crypto";
 
 const SEPARATOR = ".";
-const STATE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const STATE_TTL_MS = 10 * 60 * 1000;
 
 function getStateSecret(): string {
   const secret =
@@ -46,16 +46,9 @@ function hmac(message: string, secret: string): string {
 }
 
 function safeFragment(value: string): string {
-  // The encoded payload uses dots as separators, so any literal dot in the
-  // user email would corrupt parsing. Replace dots and any non-printable
-  // characters before signing.
   return value.replace(/[^A-Za-z0-9_@-]/g, "_");
 }
 
-/**
- * Mint a fresh signed state value bound to the current authenticated user
- * and the requested OAuth `kind`.
- */
 export function signVideoOAuthState(opts: {
   kind: string;
   userEmail: string;
@@ -85,7 +78,6 @@ export function verifyVideoOAuthState(opts: {
   state: string | undefined | null;
   kind: string;
   userEmail: string;
-  /** Override default 10-minute TTL (for tests). */
   ttlMs?: number;
 }): boolean {
   if (!opts.state || typeof opts.state !== "string") return false;
@@ -106,7 +98,6 @@ export function verifyVideoOAuthState(opts: {
   if (a.length !== b.length) return false;
   if (!crypto.timingSafeEqual(a, b)) return false;
 
-  // Freshness check.
   const ttl = opts.ttlMs ?? STATE_TTL_MS;
   const issuedAt = Number.parseInt(timestamp, 36);
   if (!Number.isFinite(issuedAt)) return false;

package/src/server/video-oauth.ts

@@ -1,19 +1,4 @@
 import { eq } from "drizzle-orm";
-/**
- * Server-side helper for completing video conferencing OAuth callbacks.
- *
- * Templates mount this under `/_agent-native/oauth/<kind>/callback.get.ts`
- * and forward the h3 event. The helper:
- *   1. Looks up the video provider by kind
- *   2. Allocates a `scheduling_credentials` row (so `credentialId` is stable)
- *   3. Calls the provider's `completeOAuth` (tokens get persisted via the
- *      provider's `updateTokens` callback, typically against core's
- *      `oauth_tokens` table, keyed by `credentialId`)
- *   4. Updates the credential row with display metadata
- *
- * It is intentionally agnostic to the consumer's auth/session plumbing —
- * pass in `userEmail` explicitly.
- */
 import { nanoid } from "nanoid";
 
 import { getSchedulingContext } from "./context.js";
@@ -27,10 +12,6 @@ export interface CompleteVideoOAuthResult {
   displayName?: string;
 }
 
-/**
- * Complete a video-provider OAuth callback. Throws on any failure so the
- * caller can decide how to render the error (HTML page, JSON, redirect).
- */
 export async function completeVideoOAuth(opts: {
   kind: string;
   userEmail: string;
@@ -50,8 +31,6 @@ export async function completeVideoOAuth(opts: {
   const now = new Date().toISOString();
   const credentialId = nanoid();
 
-  // Insert row up-front so `updateTokens(credentialId, ...)` inside
-  // completeOAuth has a stable key to write against.
   await getDb().insert(schema.schedulingCredentials).values({
     id: credentialId,
     type: kind,
@@ -73,14 +52,12 @@ export async function completeVideoOAuth(opts: {
       redirectUri,
     });
   } catch (err) {
-    // Roll back the credentials row on failure.
     await getDb()
       .delete(schema.schedulingCredentials)
       .where(eq(schema.schedulingCredentials.id, credentialId));
     throw err;
   }
 
-  // Update the credential row with external identity metadata.
   await getDb()
     .update(schema.schedulingCredentials)
     .set({

package/src/shared/index.ts

@@ -1,8 +1,3 @@
-/**
- * Wire-level types shared between server, actions, and React client.
- * These are the primary stable contract of the package.
- */
-
 export type SchedulingType =
   | "personal"
   | "collective"
@@ -30,28 +25,19 @@ export type LocationKind =
 
 export interface Location {
   kind: LocationKind;
-  /** Provider credential id, if applicable */
   credentialId?: string;
-  /** Meeting link override */
   link?: string;
-  /** Street address for in-person */
   address?: string;
-  /** Phone number for phone/organizer-phone */
   phone?: string;
-  /** Display name shown in booking UI */
   label?: string;
 }
 
 export type PeriodType = "unlimited" | "rolling" | "range";
 
 export interface BookingLimits {
-  /** Max bookings in one day */
   perDay?: number;
-  /** Max bookings in one week (starting on user's configured start of week) */
   perWeek?: number;
-  /** Max bookings in one month */
   perMonth?: number;
-  /** Max bookings in one year */
   perYear?: number;
 }
 
@@ -71,18 +57,13 @@ export interface CustomField {
   placeholder?: string;
   required: boolean;
   options?: string[];
-  /** Default/preset value for this field */
   defaultValue?: string | number | boolean;
-  /** Internal identifier stored on booking responses */
   name: string;
 }
 
 export interface RecurringEventRule {
-  /** iCal RRULE format, e.g. "FREQ=WEEKLY;COUNT=4" */
   rrule: string;
-  /** Max number of occurrences */
   count?: number;
-  /** How occurrences are labeled on the booker ("Weekly for 4 weeks") */
   description?: string;
 }
 
@@ -92,15 +73,12 @@ export interface EventType {
   slug: string;
   description?: string;
   length: number;
-  /** Optional additional duration choices */
   durations?: number[];
   hidden: boolean;
   position: number;
   schedulingType: SchedulingType;
-  /** If personal, the owner; if team, null (team event types) */
   ownerEmail?: string;
   teamId?: string;
-  /** Default schedule ID if not set at event level */
   scheduleId?: string;
   locations: Location[];
   customFields: CustomField[];
@@ -128,35 +106,25 @@ export interface EventType {
 }
 
 export interface Slot {
-  /** ISO 8601 start time in UTC */
   start: string;
-  /** ISO 8601 end time in UTC */
   end: string;
-  /** True if this slot can still be booked (not full for seated events) */
   available: boolean;
-  /** Seats remaining, for seated events */
   seatsRemaining?: number;
-  /** Assigned host for round-robin events (email) */
   hostEmail?: string;
 }
 
 export interface AvailabilityInterval {
-  /** "HH:MM" in schedule's timezone */
   startTime: string;
-  /** "HH:MM" in schedule's timezone */
   endTime: string;
 }
 
 export interface WeeklyAvailability {
-  /** 0=Sunday … 6=Saturday, ISO-like */
   day: number;
   intervals: AvailabilityInterval[];
 }
 
 export interface DateOverride {
-  /** YYYY-MM-DD in schedule's timezone */
   date: string;
-  /** Empty array = fully blocked */
   intervals: AvailabilityInterval[];
 }
 
@@ -227,9 +195,7 @@ export interface Host {
 }
 
 export interface BusyInterval {
-  /** ISO 8601 UTC */
   start: string;
-  /** ISO 8601 UTC */
   end: string;
   source?: string;
 }
@@ -279,7 +245,6 @@ export interface WorkflowStep {
   id: string;
   order: number;
   action: WorkflowStepAction;
-  /** Minutes from trigger; negative = before (for before-event), positive = after */
   offsetMinutes: number;
   sendTo?: string;
   emailSubject?: string;
@@ -321,7 +286,6 @@ export interface RoutingFormField {
 
 export interface RoutingFormRule {
   id: string;
-  /** Array of `{fieldId, op, value}` expressions ANDed together */
   conditions: {
     fieldId: string;
     op: "equals" | "not-equals" | "contains" | "starts-with" | "in";
@@ -341,7 +305,6 @@ export interface RoutingForm {
   teamId?: string;
   fields: RoutingFormField[];
   rules: RoutingFormRule[];
-  /** Action taken when no rules match */
   fallback:
     | { kind: "event-type"; eventTypeId: string }
     | { kind: "external-url"; url: string }
@@ -359,7 +322,6 @@ export interface HashedLink {
   usedAt?: string;
 }
 
-/** Round-robin assignment strategy */
 export type RoundRobinStrategy =
   | "lowest-recent-bookings"
   | "weighted"