@agent-native/scheduling 0.1.1

package/src/server/providers/types.ts

@@ -0,0 +1,126 @@
+/**
+ * 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;
+    code: string;
+    redirectUri: string;
+  }): Promise<{
+    externalEmail: string;
+    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[];
+    start: Date;
+    end: Date;
+  }): Promise<BusyInterval[]>;
+
+  /** Create a calendar event; return the external id. */
+  createEvent(opts: {
+    credentialId: string;
+    calendarExternalId: string;
+    booking: Booking;
+    includeConference?: boolean;
+  }): Promise<{
+    externalId: string;
+    meetingUrl?: string;
+    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;
+  }): Promise<void>;
+}
+
+export interface VideoProvider {
+  kind: string;
+  label: string;
+
+  /**
+   * Start the OAuth flow — optional. Present on providers like Zoom /
+   * Microsoft Teams that require a user's OAuth grant to create meetings on
+   * their behalf. Zero-OAuth providers (the built-in video provider, or
+   * Google Meet which piggy-backs on the Google Calendar scope) omit this.
+   */
+  startOAuth?(opts: {
+    redirectUri: string;
+    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;
+    code: string;
+    redirectUri: string;
+  }): Promise<{
+    externalEmail?: string;
+    externalAccountId: string;
+    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;
+  }): Promise<void>;
+}
+
+export interface SmsProvider {
+  kind: string;
+  label: string;
+  sendSms(opts: { to: string; body: string; from?: string }): Promise<void>;
+}

package/src/server/providers/zoom.ts

@@ -0,0 +1,173 @@
+/**
+ * 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 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: {
+      accessToken: string;
+      refreshToken?: string;
+      expiresAt?: Date;
+      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 {
+  return {
+    kind: "zoom_video",
+    label: "Zoom",
+
+    async startOAuth({ redirectUri, state }) {
+      const params = new URLSearchParams({
+        response_type: "code",
+        client_id: config.clientId,
+        redirect_uri: redirectUri,
+        state,
+        scope: SCOPES.join(" "),
+      });
+      return {
+        authUrl: `https://zoom.us/oauth/authorize?${params}`,
+      };
+    },
+
+    async completeOAuth({ code, redirectUri, credentialId }) {
+      const basic = Buffer.from(
+        `${config.clientId}:${config.clientSecret}`,
+      ).toString("base64");
+      const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: redirectUri,
+      });
+      const tokenRes = await fetch("https://zoom.us/oauth/token", {
+        method: "POST",
+        headers: {
+          authorization: `Basic ${basic}`,
+          "content-type": "application/x-www-form-urlencoded",
+        },
+        body,
+      });
+      if (!tokenRes.ok) {
+        throw new Error(
+          `Zoom token exchange failed: ${tokenRes.status} ${await tokenRes.text()}`,
+        );
+      }
+      const tokens = (await tokenRes.json()) as {
+        access_token: string;
+        refresh_token?: string;
+        expires_in?: number;
+        scope?: string;
+        token_type?: string;
+      };
+
+      await config.updateTokens?.(credentialId, {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresAt: new Date(Date.now() + (tokens.expires_in ?? 3600) * 1000),
+        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}` },
+      });
+      let externalEmail: string | undefined;
+      let externalAccountId = credentialId;
+      let displayName: string | undefined;
+      if (userRes.ok) {
+        const user = (await userRes.json()) as {
+          id?: string;
+          email?: string;
+          first_name?: string;
+          last_name?: string;
+          account_id?: string;
+        };
+        externalEmail = user.email;
+        externalAccountId = user.id ?? user.account_id ?? credentialId;
+        if (user.first_name || user.last_name) {
+          displayName = [user.first_name, user.last_name]
+            .filter(Boolean)
+            .join(" ");
+        }
+      }
+
+      return { externalAccountId, externalEmail, displayName };
+    },
+
+    async createMeeting({ credentialId, booking }) {
+      if (!credentialId) throw new Error("Zoom requires credentialId");
+      const token = await config.getAccessToken(credentialId);
+      const res = await fetch("https://api.zoom.us/v2/users/me/meetings", {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${token}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          topic: booking.title,
+          type: 2,
+          start_time: booking.startTime,
+          duration: Math.round(
+            (new Date(booking.endTime).getTime() -
+              new Date(booking.startTime).getTime()) /
+              60000,
+          ),
+          timezone: booking.timezone,
+          settings: {
+            join_before_host: true,
+            waiting_room: false,
+            mute_upon_entry: false,
+          },
+        }),
+      });
+      if (res.status === 401 || res.status === 403) {
+        await config.markInvalid?.(credentialId);
+      }
+      if (!res.ok) throw new Error(`Zoom ${res.status}: ${await res.text()}`);
+      const body = await res.json();
+      return {
+        meetingUrl: body.join_url,
+        meetingId: String(body.id),
+        meetingPassword: body.password,
+      };
+    },
+
+    async deleteMeeting({ credentialId, meetingId }) {
+      if (!credentialId) return;
+      const token = await config.getAccessToken(credentialId);
+      await fetch(
+        `https://api.zoom.us/v2/meetings/${encodeURIComponent(meetingId)}`,
+        {
+          method: "DELETE",
+          headers: { authorization: `Bearer ${token}` },
+        },
+      );
+    },
+  };
+}

package/src/server/schedules-repo.ts

@@ -0,0 +1,279 @@
+/**
+ * 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";
+import { accessFilter } from "@agent-native/core/sharing";
+import type {
+  Schedule,
+  WeeklyAvailability,
+  DateOverride,
+  AvailabilityInterval,
+} from "../shared/index.js";
+import { getSchedulingContext } from "./context.js";
+
+export async function listSchedules(
+  ownerEmailOrParams:
+    | string
+    | {
+        ownerEmail?: string;
+        useAccessFilter?: boolean;
+      },
+): Promise<Schedule[]> {
+  const params =
+    typeof ownerEmailOrParams === "string"
+      ? { ownerEmail: ownerEmailOrParams }
+      : ownerEmailOrParams;
+  const { getDb, schema } = getSchedulingContext();
+  const db = getDb();
+  let where: SQL | undefined;
+  if (params.useAccessFilter) {
+    where = accessFilter(schema.schedules, schema.scheduleShares);
+  } else if (params.ownerEmail) {
+    where = eq(schema.schedules.ownerEmail, params.ownerEmail);
+  }
+  const scheduleRows = await db.select().from(schema.schedules).where(where);
+  if (scheduleRows.length === 0) return [];
+  const ids = scheduleRows.map((r: any) => r.id);
+  const availabilityRows = await db
+    .select()
+    .from(schema.scheduleAvailability)
+    .where(inArray(schema.scheduleAvailability.scheduleId, ids));
+  const overrideRows = await db
+    .select()
+    .from(schema.dateOverrides)
+    .where(inArray(schema.dateOverrides.scheduleId, ids));
+  return scheduleRows.map((s: any) =>
+    hydrateSchedule(s, availabilityRows, overrideRows),
+  );
+}
+
+export async function getScheduleById(id: string): Promise<Schedule | null> {
+  const { getDb, schema } = getSchedulingContext();
+  const db = getDb();
+  const s = await db
+    .select()
+    .from(schema.schedules)
+    .where(eq(schema.schedules.id, id));
+  if (!s[0]) return null;
+  const avail = await db
+    .select()
+    .from(schema.scheduleAvailability)
+    .where(eq(schema.scheduleAvailability.scheduleId, id));
+  const overrides = await db
+    .select()
+    .from(schema.dateOverrides)
+    .where(eq(schema.dateOverrides.scheduleId, id));
+  return hydrateSchedule(s[0], avail, overrides);
+}
+
+export async function createSchedule(input: {
+  ownerEmail: string;
+  orgId?: string;
+  name: string;
+  timezone: string;
+  isDefault?: boolean;
+  weeklyAvailability?: WeeklyAvailability[];
+}): Promise<Schedule> {
+  const { getDb, schema } = getSchedulingContext();
+  const db = getDb();
+  const id = nanoid();
+  const now = new Date().toISOString();
+  await db.insert(schema.schedules).values({
+    id,
+    name: input.name,
+    timezone: input.timezone,
+    isDefault: Boolean(input.isDefault),
+    ownerEmail: input.ownerEmail,
+    orgId: input.orgId ?? null,
+    createdAt: now,
+    updatedAt: now,
+  });
+  const weekly = input.weeklyAvailability ?? defaultWeeklyAvailability();
+  for (const w of weekly) {
+    for (const iv of w.intervals) {
+      await db.insert(schema.scheduleAvailability).values({
+        id: nanoid(),
+        scheduleId: id,
+        day: w.day,
+        startTime: iv.startTime,
+        endTime: iv.endTime,
+        createdAt: now,
+      });
+    }
+  }
+  const out = await getScheduleById(id);
+  if (!out) throw new Error("Failed to create schedule");
+  return out;
+}
+
+export async function updateSchedule(
+  id: string,
+  patch: {
+    name?: string;
+    timezone?: string;
+    weeklyAvailability?: WeeklyAvailability[];
+    dateOverrides?: DateOverride[];
+    isDefault?: boolean;
+  },
+): Promise<Schedule> {
+  const { getDb, schema } = getSchedulingContext();
+  const db = getDb();
+  const now = new Date().toISOString();
+  const setClause: any = { updatedAt: now };
+  if (patch.name != null) setClause.name = patch.name;
+  if (patch.timezone != null) setClause.timezone = patch.timezone;
+  if (patch.isDefault != null) setClause.isDefault = patch.isDefault;
+  await db
+    .update(schema.schedules)
+    .set(setClause)
+    .where(eq(schema.schedules.id, id));
+
+  if (patch.weeklyAvailability) {
+    await db
+      .delete(schema.scheduleAvailability)
+      .where(eq(schema.scheduleAvailability.scheduleId, id));
+    for (const w of patch.weeklyAvailability) {
+      for (const iv of w.intervals) {
+        await db.insert(schema.scheduleAvailability).values({
+          id: nanoid(),
+          scheduleId: id,
+          day: w.day,
+          startTime: iv.startTime,
+          endTime: iv.endTime,
+          createdAt: now,
+        });
+      }
+    }
+  }
+  if (patch.dateOverrides) {
+    await db
+      .delete(schema.dateOverrides)
+      .where(eq(schema.dateOverrides.scheduleId, id));
+    for (const o of patch.dateOverrides) {
+      await db.insert(schema.dateOverrides).values({
+        id: nanoid(),
+        scheduleId: id,
+        date: o.date,
+        intervals: JSON.stringify(o.intervals),
+        createdAt: now,
+      });
+    }
+  }
+  const updated = await getScheduleById(id);
+  if (!updated) throw new Error("Failed to update schedule");
+  return updated;
+}
+
+export async function deleteSchedule(id: string): Promise<void> {
+  const { getDb, schema } = getSchedulingContext();
+  const db = getDb();
+  await db
+    .delete(schema.dateOverrides)
+    .where(eq(schema.dateOverrides.scheduleId, id));
+  await db
+    .delete(schema.scheduleAvailability)
+    .where(eq(schema.scheduleAvailability.scheduleId, id));
+  await db.delete(schema.schedules).where(eq(schema.schedules.id, id));
+}
+
+export async function setDefaultSchedule(
+  ownerEmail: string,
+  scheduleId: string,
+): Promise<void> {
+  const { getDb, schema } = getSchedulingContext();
+  const db = getDb();
+  const now = new Date().toISOString();
+  const all = await db
+    .select({ id: schema.schedules.id })
+    .from(schema.schedules)
+    .where(eq(schema.schedules.ownerEmail, ownerEmail));
+  for (const row of all) {
+    await db
+      .update(schema.schedules)
+      .set({ isDefault: row.id === scheduleId, updatedAt: now })
+      .where(eq(schema.schedules.id, row.id));
+  }
+}
+
+export async function upsertDateOverride(
+  scheduleId: string,
+  date: string,
+  intervals: AvailabilityInterval[],
+): Promise<void> {
+  const { getDb, schema } = getSchedulingContext();
+  const db = getDb();
+  const now = new Date().toISOString();
+  await db
+    .delete(schema.dateOverrides)
+    .where(
+      and(
+        eq(schema.dateOverrides.scheduleId, scheduleId),
+        eq(schema.dateOverrides.date, date),
+      ),
+    );
+  await db.insert(schema.dateOverrides).values({
+    id: nanoid(),
+    scheduleId,
+    date,
+    intervals: JSON.stringify(intervals),
+    createdAt: now,
+  });
+}
+
+export async function removeDateOverride(
+  scheduleId: string,
+  date: string,
+): Promise<void> {
+  const { getDb, schema } = getSchedulingContext();
+  await getDb()
+    .delete(schema.dateOverrides)
+    .where(
+      and(
+        eq(schema.dateOverrides.scheduleId, scheduleId),
+        eq(schema.dateOverrides.date, date),
+      ),
+    );
+}
+
+function hydrateSchedule(
+  s: any,
+  availabilityRows: any[],
+  overrideRows: any[],
+): Schedule {
+  const weekly = new Map<number, AvailabilityInterval[]>();
+  for (const row of availabilityRows) {
+    if (row.scheduleId !== s.id) continue;
+    const day = row.day;
+    if (!weekly.has(day)) weekly.set(day, []);
+    weekly.get(day)!.push({ startTime: row.startTime, endTime: row.endTime });
+  }
+  const weeklyAvailability: WeeklyAvailability[] = Array.from(weekly.entries())
+    .map(([day, intervals]) => ({ day, intervals }))
+    .sort((a, b) => a.day - b.day);
+  const dateOverrides: DateOverride[] = overrideRows
+    .filter((r) => r.scheduleId === s.id)
+    .map((r) => ({
+      date: r.date,
+      intervals: JSON.parse(r.intervals),
+    }));
+  return {
+    id: s.id,
+    name: s.name,
+    timezone: s.timezone,
+    ownerEmail: s.ownerEmail,
+    isDefault: Boolean(s.isDefault),
+    weeklyAvailability,
+    dateOverrides,
+    createdAt: s.createdAt,
+    updatedAt: s.updatedAt,
+  };
+}
+
+function defaultWeeklyAvailability(): WeeklyAvailability[] {
+  return [1, 2, 3, 4, 5].map((day) => ({
+    day,
+    intervals: [{ startTime: "09:00", endTime: "17:00" }],
+  }));
+}

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

@@ -0,0 +1,120 @@
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import {
+  signVideoOAuthState,
+  verifyVideoOAuthState,
+} from "./video-oauth-state.js";
+
+const ORIGINAL_SECRET = process.env.BETTER_AUTH_SECRET;
+
+describe("video-oauth-state", () => {
+  beforeEach(() => {
+    process.env.BETTER_AUTH_SECRET = "test-secret-do-not-use-in-prod";
+  });
+
+  afterEach(() => {
+    if (ORIGINAL_SECRET === undefined) delete process.env.BETTER_AUTH_SECRET;
+    else process.env.BETTER_AUTH_SECRET = ORIGINAL_SECRET;
+  });
+
+  it("signs and verifies a state for the same user + kind", () => {
+    const state = signVideoOAuthState({
+      kind: "zoom_video",
+      userEmail: "alice@example.com",
+    });
+    expect(
+      verifyVideoOAuthState({
+        state,
+        kind: "zoom_video",
+        userEmail: "alice@example.com",
+      }),
+    ).toBe(true);
+  });
+
+  it("rejects a state forged for a different user", () => {
+    const state = signVideoOAuthState({
+      kind: "zoom_video",
+      userEmail: "alice@example.com",
+    });
+    expect(
+      verifyVideoOAuthState({
+        state,
+        kind: "zoom_video",
+        userEmail: "mallory@example.com",
+      }),
+    ).toBe(false);
+  });
+
+  it("rejects a state cross-bound to a different kind", () => {
+    const state = signVideoOAuthState({
+      kind: "zoom_video",
+      userEmail: "alice@example.com",
+    });
+    expect(
+      verifyVideoOAuthState({
+        state,
+        kind: "google_meet",
+        userEmail: "alice@example.com",
+      }),
+    ).toBe(false);
+  });
+
+  it("rejects empty / malformed state", () => {
+    expect(
+      verifyVideoOAuthState({
+        state: undefined,
+        kind: "zoom_video",
+        userEmail: "alice@example.com",
+      }),
+    ).toBe(false);
+    expect(
+      verifyVideoOAuthState({
+        state: "",
+        kind: "zoom_video",
+        userEmail: "alice@example.com",
+      }),
+    ).toBe(false);
+    expect(
+      verifyVideoOAuthState({
+        state: "garbage",
+        kind: "zoom_video",
+        userEmail: "alice@example.com",
+      }),
+    ).toBe(false);
+    expect(
+      verifyVideoOAuthState({
+        state: "a.b.c.d.e",
+        kind: "zoom_video",
+        userEmail: "alice@example.com",
+      }),
+    ).toBe(false);
+  });
+
+  it("rejects expired state", () => {
+    const state = signVideoOAuthState({
+      kind: "zoom_video",
+      userEmail: "alice@example.com",
+    });
+    expect(
+      verifyVideoOAuthState({
+        state,
+        kind: "zoom_video",
+        userEmail: "alice@example.com",
+        ttlMs: -1, // every state is "older" than -1 ms ago.
+      }),
+    ).toBe(false);
+  });
+
+  it("is case-insensitive on email but rejects mismatched casing if secret rotates", () => {
+    const state = signVideoOAuthState({
+      kind: "zoom_video",
+      userEmail: "Alice@Example.COM",
+    });
+    expect(
+      verifyVideoOAuthState({
+        state,
+        kind: "zoom_video",
+        userEmail: "alice@example.com",
+      }),
+    ).toBe(true);
+  });
+});