@agent-native/scheduling 0.1.1

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

@@ -0,0 +1,116 @@
+/**
+ * HMAC-signed state for video conferencing OAuth flows.
+ *
+ * The `state` value sent to the OAuth provider must round-trip back to our
+ * callback verbatim. We use HMAC-SHA256 to bind the state to the kind +
+ * authenticated user email + a server secret + a freshness timestamp.
+ * The callback re-derives the HMAC and rejects mismatches — this prevents
+ * an attacker from forging a callback for someone else's account or
+ * replaying an old completed flow.
+ *
+ * Output format:
+ *   <random-nonce>.<timestamp>.<kind>.<base64url-hmac>
+ *
+ * The nonce keeps every issued state distinct even if the same user
+ * starts two parallel OAuth flows for the same provider. The timestamp
+ * lets us bound replay attempts (default: 10 minutes).
+ */
+import crypto from "node:crypto";
+
+const SEPARATOR = ".";
+const STATE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+
+function getStateSecret(): string {
+  const secret =
+    process.env.SCHEDULING_OAUTH_STATE_SECRET ||
+    process.env.BETTER_AUTH_SECRET ||
+    process.env.AUTH_SECRET;
+  if (!secret) {
+    throw new Error(
+      "OAuth state secret is not configured. Set BETTER_AUTH_SECRET (or SCHEDULING_OAUTH_STATE_SECRET).",
+    );
+  }
+  return secret;
+}
+
+function b64url(buf: Buffer): string {
+  return buf
+    .toString("base64")
+    .replace(/=+$/, "")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_");
+}
+
+function hmac(message: string, secret: string): string {
+  return b64url(crypto.createHmac("sha256", secret).update(message).digest());
+}
+
+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;
+}): string {
+  const nonce = crypto.randomBytes(12).toString("hex");
+  const timestamp = Date.now().toString(36);
+  const safeKind = safeFragment(opts.kind);
+  const safeEmail = safeFragment(opts.userEmail.toLowerCase());
+  const message = [nonce, timestamp, safeKind, safeEmail].join(SEPARATOR);
+  const sig = hmac(message, getStateSecret());
+  return [nonce, timestamp, safeKind, sig].join(SEPARATOR);
+}
+
+/**
+ * Verify a state value returned from the OAuth provider matches one
+ * minted by `signVideoOAuthState` for the same authenticated user.
+ *
+ * Returns `true` only when:
+ *   1. The state has the expected shape
+ *   2. The HMAC matches (kind + user-email + secret)
+ *   3. The state is not older than STATE_TTL_MS
+ *
+ * Uses `crypto.timingSafeEqual` to prevent timing-based recovery of the
+ * signature.
+ */
+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;
+  const parts = opts.state.split(SEPARATOR);
+  if (parts.length !== 4) return false;
+  const [nonce, timestamp, kindFragment, providedSig] = parts;
+  if (!nonce || !timestamp || !kindFragment || !providedSig) return false;
+
+  const expectedKind = safeFragment(opts.kind);
+  if (kindFragment !== expectedKind) return false;
+
+  const safeEmail = safeFragment(opts.userEmail.toLowerCase());
+  const message = [nonce, timestamp, kindFragment, safeEmail].join(SEPARATOR);
+  const expectedSig = hmac(message, getStateSecret());
+
+  const a = Buffer.from(providedSig);
+  const b = Buffer.from(expectedSig);
+  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;
+  if (Date.now() - issuedAt > ttl) return false;
+
+  return true;
+}

package/src/server/video-oauth.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 { eq } from "drizzle-orm";
+import { getSchedulingContext } from "./context.js";
+import { getVideoProvider } from "./providers/registry.js";
+
+export interface CompleteVideoOAuthResult {
+  credentialId: string;
+  kind: string;
+  externalEmail?: string;
+  externalAccountId: string;
+  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;
+  code: string;
+  redirectUri: string;
+}): Promise<CompleteVideoOAuthResult> {
+  const { kind, userEmail, code, redirectUri } = opts;
+  const provider = getVideoProvider(kind);
+  if (!provider) {
+    throw new Error(`No video provider registered for ${kind}`);
+  }
+  if (!provider.completeOAuth) {
+    throw new Error(`Video provider ${kind} does not support OAuth`);
+  }
+
+  const { getDb, schema } = getSchedulingContext();
+  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,
+    userEmail,
+    appId: kind,
+    oauthTokenId: credentialId,
+    isDefault: false,
+    invalid: false,
+    createdAt: now,
+    updatedAt: now,
+  });
+
+  let result: Awaited<ReturnType<NonNullable<typeof provider.completeOAuth>>>;
+  try {
+    result = await provider.completeOAuth({
+      credentialId,
+      userEmail,
+      code,
+      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({
+      externalEmail: result.externalEmail ?? null,
+      displayName: result.displayName ?? null,
+      updatedAt: new Date().toISOString(),
+    })
+    .where(eq(schema.schedulingCredentials.id, credentialId));
+
+  return {
+    credentialId,
+    kind,
+    externalEmail: result.externalEmail,
+    externalAccountId: result.externalAccountId,
+    displayName: result.displayName,
+  };
+}

package/src/shared/index.ts

@@ -0,0 +1,366 @@
+/**
+ * Wire-level types shared between server, actions, and React client.
+ * These are the primary stable contract of the package.
+ */
+
+export type SchedulingType =
+  | "personal"
+  | "collective"
+  | "round-robin"
+  | "managed";
+
+export type BookingStatus =
+  | "pending"
+  | "confirmed"
+  | "cancelled"
+  | "rejected"
+  | "rescheduled";
+
+export type LocationKind =
+  | "builtin-video"
+  | "zoom"
+  | "google-meet"
+  | "teams"
+  | "phone"
+  | "in-person"
+  | "custom-link"
+  | "attendee-phone"
+  | "organizer-phone"
+  | "attendee-choice";
+
+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;
+}
+
+export interface CustomField {
+  id: string;
+  type:
+    | "text"
+    | "textarea"
+    | "number"
+    | "email"
+    | "phone"
+    | "select"
+    | "multiselect"
+    | "boolean"
+    | "radio";
+  label: string;
+  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;
+}
+
+export interface EventType {
+  id: string;
+  title: string;
+  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[];
+  minimumBookingNotice: number;
+  beforeEventBuffer: number;
+  afterEventBuffer: number;
+  slotInterval: number | null;
+  periodType: PeriodType;
+  periodDays?: number;
+  periodStartDate?: string;
+  periodEndDate?: string;
+  seatsPerTimeSlot?: number;
+  requiresConfirmation: boolean;
+  disableGuests: boolean;
+  hideCalendarNotes: boolean;
+  successRedirectUrl?: string;
+  bookingLimits?: BookingLimits;
+  lockTimeZoneToggle: boolean;
+  color?: string;
+  eventName?: string;
+  recurringEvent?: RecurringEventRule;
+  metadata?: Record<string, any>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+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[];
+}
+
+export interface Schedule {
+  id: string;
+  name: string;
+  timezone: string;
+  ownerEmail: string;
+  weeklyAvailability: WeeklyAvailability[];
+  dateOverrides: DateOverride[];
+  isDefault: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Attendee {
+  email: string;
+  name: string;
+  timezone?: string;
+  locale?: string;
+  noShow?: boolean;
+}
+
+export interface BookingReference {
+  type: string;
+  externalId: string;
+  meetingUrl?: string;
+  meetingPassword?: string;
+  credentialId?: string;
+}
+
+export interface Booking {
+  id: string;
+  uid: string;
+  eventTypeId: string;
+  hostEmail: string;
+  title: string;
+  description?: string;
+  startTime: string;
+  endTime: string;
+  timezone: string;
+  status: BookingStatus;
+  location?: Location;
+  attendees: Attendee[];
+  references: BookingReference[];
+  customResponses?: Record<string, any>;
+  cancellationReason?: string;
+  reschedulingReason?: string;
+  cancelToken?: string;
+  rescheduleToken?: string;
+  fromReschedule?: string;
+  iCalUid: string;
+  iCalSequence: number;
+  recurringEventId?: string;
+  paid?: boolean;
+  metadata?: Record<string, any>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Host {
+  userEmail: string;
+  eventTypeId: string;
+  scheduleId?: string;
+  isFixed: boolean;
+  weight: number;
+  priority: number;
+}
+
+export interface BusyInterval {
+  /** ISO 8601 UTC */
+  start: string;
+  /** ISO 8601 UTC */
+  end: string;
+  source?: string;
+}
+
+export interface Team {
+  id: string;
+  slug: string;
+  name: string;
+  logoUrl?: string;
+  brandColor?: string;
+  darkBrandColor?: string;
+  bio?: string;
+  hideBranding: boolean;
+  metadata?: Record<string, any>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export type TeamRole = "owner" | "admin" | "member";
+
+export interface TeamMember {
+  teamId: string;
+  userEmail: string;
+  role: TeamRole;
+  accepted: boolean;
+  joinedAt?: string;
+}
+
+export type WorkflowTrigger =
+  | "new-booking"
+  | "before-event"
+  | "after-event"
+  | "reschedule"
+  | "cancellation"
+  | "no-show";
+
+export type WorkflowStepAction =
+  | "email-host"
+  | "email-attendee"
+  | "email-address"
+  | "sms-attendee"
+  | "sms-host"
+  | "sms-number"
+  | "webhook";
+
+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;
+  emailBody?: string;
+  smsBody?: string;
+  webhookUrl?: string;
+  template?: string;
+}
+
+export interface Workflow {
+  id: string;
+  name: string;
+  trigger: WorkflowTrigger;
+  ownerEmail?: string;
+  teamId?: string;
+  activeOnEventTypeIds: string[];
+  steps: WorkflowStep[];
+  disabled: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export type RoutingFormFieldType =
+  | "text"
+  | "email"
+  | "phone"
+  | "number"
+  | "select"
+  | "multi";
+
+export interface RoutingFormField {
+  id: string;
+  name: string;
+  label: string;
+  type: RoutingFormFieldType;
+  required: boolean;
+  options?: string[];
+}
+
+export interface RoutingFormRule {
+  id: string;
+  /** Array of `{fieldId, op, value}` expressions ANDed together */
+  conditions: {
+    fieldId: string;
+    op: "equals" | "not-equals" | "contains" | "starts-with" | "in";
+    value: string | string[];
+  }[];
+  action:
+    | { kind: "event-type"; eventTypeId: string; teamId?: string }
+    | { kind: "external-url"; url: string }
+    | { kind: "custom-message"; message: string };
+}
+
+export interface RoutingForm {
+  id: string;
+  name: string;
+  description?: string;
+  ownerEmail?: string;
+  teamId?: string;
+  fields: RoutingFormField[];
+  rules: RoutingFormRule[];
+  /** Action taken when no rules match */
+  fallback:
+    | { kind: "event-type"; eventTypeId: string }
+    | { kind: "external-url"; url: string }
+    | { kind: "custom-message"; message: string };
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface HashedLink {
+  id: string;
+  hash: string;
+  eventTypeId: string;
+  expiresAt?: string;
+  isSingleUse: boolean;
+  usedAt?: string;
+}
+
+/** Round-robin assignment strategy */
+export type RoundRobinStrategy =
+  | "lowest-recent-bookings"
+  | "weighted"
+  | "calibrated";

package/src/version.ts

@@ -0,0 +1 @@
+export const VERSION = "0.1.0";