create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/scheduling/cal-provider.ts

@@ -0,0 +1,392 @@
+// oss: false
+/**
+ * Cal.com provider (#4416) — the first implementation of the scheduling seam.
+ *
+ * Everything Cal-specific lives here and nowhere else: the per-endpoint
+ * `cal-api-version` headers, the event-type lookup that turns a
+ * `"<owner>/<event-slug>"` link into a numeric event-type id, the slot map
+ * keyed by day, and the booking body. `types.ts` names none of it, so #4288's
+ * self-hosted engine implements the same two methods without inheriting any
+ * of Cal's vocabulary.
+ *
+ * CREDENTIALS ARE SERVER-SIDE ONLY. `CAL_API_KEY` is read here, inside
+ * `apps/api`. The browser reaches Cal exclusively through this app's own
+ * `/v1/schedule/*` routes; the key is never serialized into a section's data,
+ * a page's props, or any response body.
+ *
+ * Cal v2 endpoints used (each pins its own API version, per Cal's docs):
+ *   GET  /v2/event-types?username=&eventTypeSlug=   cal-api-version: 2024-06-14
+ *   GET  /v2/slots?eventTypeId=&start=&end=&timeZone=  cal-api-version: 2024-09-04
+ *   POST /v2/bookings                                cal-api-version: 2024-08-13
+ */
+
+import type {
+  AvailabilityResult,
+  BookingResult,
+  SchedulingEventMeta,
+  SchedulingPrice,
+  SchedulingSlot,
+} from "@working-theory/validation";
+
+import {
+  schedulingError,
+  type CreateBookingRequest,
+  type GetEventMetaRequest,
+  type ListAvailabilityRequest,
+  type SchedulingOutcome,
+  type SchedulingProvider,
+} from "./types.js";
+
+const DEFAULT_BASE_URL = "https://api.cal.com";
+const EVENT_TYPES_API_VERSION = "2024-06-14";
+const SLOTS_API_VERSION = "2024-09-04";
+const BOOKINGS_API_VERSION = "2024-08-13";
+
+/** Cal answers in seconds-free ISO; anything else means the response drifted. */
+const REQUEST_TIMEOUT_MS = 10_000;
+
+export interface CalProviderOptions {
+  apiKey: string;
+  /** Overridable for tests and self-hosted Cal instances. */
+  baseUrl?: string;
+  /** Injectable for tests; defaults to the platform `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+
+/** `"sam/fit-check"` → `{ username: "sam", eventTypeSlug: "fit-check" }`. */
+function splitCalLink(
+  calLink: string,
+): { username: string; eventTypeSlug: string } | null {
+  const parts = calLink.split("/");
+  if (parts.length !== 2) return null;
+  const [username, eventTypeSlug] = parts;
+  if (!username || !eventTypeSlug) return null;
+  return { username, eventTypeSlug };
+}
+
+/**
+ * Cal describes an event's location as a small tagged union whose shape has
+ * changed across versions. Rather than model every variant, read the one
+ * field every variant carries and turn it into the words a booker shows
+ * ("Google Meet", "Phone call") — falling back to no meeting type at all,
+ * which the UI renders by simply omitting that meta item.
+ */
+const LOCATION_LABELS: Record<string, string> = {
+  integrations_google_meet: "Google Meet",
+  "integrations:google:meet": "Google Meet",
+  "integrations:daily": "Cal Video",
+  integrations_daily: "Cal Video",
+  "integrations:zoom": "Zoom",
+  integrations_zoom: "Zoom",
+  phone: "Phone call",
+  userPhone: "Phone call",
+  attendeeInPerson: "In person",
+  inPerson: "In person",
+  link: "Web link",
+};
+
+/**
+ * Cal states an event's price as two sibling fields — `price` in minor units
+ * (0 for every event on an account with no payment app connected) and
+ * `currency` (`"usd"`). Free and unpriced are therefore the same state at the
+ * source. Kept in minor units: converting to major units needs the currency's
+ * decimal rules and the viewer's locale, which only the rendering site has.
+ */
+function readPrice(eventType: Record<string, unknown>): SchedulingPrice | undefined {
+  const amount = eventType["price"];
+  const currency = eventType["currency"];
+  if (typeof amount !== "number" || !Number.isInteger(amount) || amount < 0) {
+    return undefined;
+  }
+  if (typeof currency !== "string" || !/^[A-Za-z]{3}$/.test(currency)) {
+    return undefined;
+  }
+  return { amountMinor: amount, currency };
+}
+
+function readMeetingType(eventType: Record<string, unknown>): string | undefined {
+  const locations = eventType["locations"];
+  if (!Array.isArray(locations) || locations.length === 0) return undefined;
+  const first = locations[0];
+  if (typeof first !== "object" || first === null) return undefined;
+  const raw = (first as Record<string, unknown>)["type"];
+  if (typeof raw !== "string" || raw === "") return undefined;
+  return LOCATION_LABELS[raw] ?? undefined;
+}
+
+/**
+ * Cal's `/v2/slots` payload is a map of day → slot list, and the slot entries
+ * have carried `start`/`time` across versions. Flatten it into the seam's
+ * `{ start, end }` pairs, deriving `end` from the event's own duration so the
+ * shape is identical no matter which key Cal used.
+ */
+function flattenSlots(
+  data: unknown,
+  durationMinutes: number,
+): SchedulingSlot[] {
+  if (typeof data !== "object" || data === null) return [];
+  const slots: SchedulingSlot[] = [];
+  for (const daySlots of Object.values(data as Record<string, unknown>)) {
+    if (!Array.isArray(daySlots)) continue;
+    for (const entry of daySlots) {
+      const start =
+        typeof entry === "string"
+          ? entry
+          : typeof entry === "object" && entry !== null
+            ? ((entry as Record<string, unknown>)["start"] ??
+              (entry as Record<string, unknown>)["time"])
+            : undefined;
+      if (typeof start !== "string") continue;
+      const startMs = Date.parse(start);
+      if (Number.isNaN(startMs)) continue;
+      slots.push({
+        start: new Date(startMs).toISOString(),
+        end: new Date(startMs + durationMinutes * 60_000).toISOString(),
+      });
+    }
+  }
+  slots.sort((a, b) => a.start.localeCompare(b.start));
+  return slots;
+}
+
+/**
+ * Build the Cal provider. A factory rather than a class, per this repo's
+ * object discipline: adapters and clients are `createX()` functions, and
+ * everything below closes over `options` instead of carrying instance state.
+ */
+export function createCalSchedulingProvider(
+  options: CalProviderOptions,
+): SchedulingProvider {
+  const apiKey = options.apiKey;
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  const fetchImpl = options.fetchImpl ?? fetch;
+
+  async function request(
+    path: string,
+    apiVersion: string,
+    init?: RequestInit,
+  ): Promise<SchedulingOutcome<unknown>> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+      const res = await fetchImpl(`${baseUrl}${path}`, {
+        ...init,
+        signal: controller.signal,
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "cal-api-version": apiVersion,
+          "Content-Type": "application/json",
+          ...(init?.headers ?? {}),
+        },
+      });
+
+      const body: unknown = await res.json().catch(() => null);
+      if (res.status === 404) {
+        return schedulingError("event_not_found", "Cal returned 404.");
+      }
+      if (!res.ok) {
+        // 409 is Cal's "someone took it" for a booking create; everything
+        // else is an upstream failure this app cannot resolve.
+        if (res.status === 409) {
+          return schedulingError(
+            "slot_unavailable",
+            "Cal reported the slot is no longer available.",
+          );
+        }
+        return schedulingError(
+          "provider_error",
+          `Cal responded ${String(res.status)}.`,
+        );
+      }
+      return { ok: true, value: body };
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : "unknown error";
+      return schedulingError("provider_error", `Cal request failed: ${detail}`);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /** Resolve `"<owner>/<event-slug>"` to the numeric id + derived event meta. */
+  async function resolveEventType(
+    calLink: string,
+    timeZoneOverride?: string,
+  ): Promise<SchedulingOutcome<{ id: number; meta: SchedulingEventMeta }>> {
+    const parts = splitCalLink(calLink);
+    if (!parts) {
+      return schedulingError(
+        "invalid_input",
+        "calLink is not owner/event-slug.",
+      );
+    }
+
+    const query = new URLSearchParams({
+      username: parts.username,
+      eventTypeSlug: parts.eventTypeSlug,
+    });
+    const res = await request(
+      `/v2/event-types?${query.toString()}`,
+      EVENT_TYPES_API_VERSION,
+    );
+    if (!res.ok) return res;
+
+    const envelope = res.value as { data?: unknown } | null;
+    const raw = envelope?.data;
+    // Cal has returned both a bare object and a single-element array here.
+    const eventType = (Array.isArray(raw) ? raw[0] : raw) as
+      | Record<string, unknown>
+      | undefined;
+    if (!eventType || typeof eventType !== "object") {
+      return schedulingError("event_not_found", "Cal returned no event type.");
+    }
+
+    const id = eventType["id"];
+    const lengthInMinutes =
+      eventType["lengthInMinutes"] ?? eventType["length"] ?? undefined;
+    if (typeof id !== "number" || typeof lengthInMinutes !== "number") {
+      return schedulingError(
+        "provider_error",
+        "Cal event type is missing id or duration.",
+      );
+    }
+
+    const title = eventType["title"];
+    const scheduleTimeZone = eventType["scheduleTimeZone"];
+    const meetingType = readMeetingType(eventType);
+    // Cal allows an empty description; omit it rather than carry "".
+    const description = eventType["description"];
+    const price = readPrice(eventType);
+    return {
+      ok: true,
+      value: {
+        id,
+        meta: {
+          title:
+            typeof title === "string" && title ? title : parts.eventTypeSlug,
+          durationMinutes: lengthInMinutes,
+          ...(typeof description === "string" && description
+            ? { description }
+            : {}),
+          ...(price !== undefined ? { price } : {}),
+          ...(meetingType !== undefined ? { meetingType } : {}),
+          timeZone:
+            timeZoneOverride ??
+            (typeof scheduleTimeZone === "string" && scheduleTimeZone
+              ? scheduleTimeZone
+              : "UTC"),
+        },
+      },
+    };
+  }
+
+  return {
+    id: "cal",
+
+    async getEventMeta(
+      req: GetEventMetaRequest,
+    ): Promise<SchedulingOutcome<SchedulingEventMeta>> {
+      // One event-type lookup and nothing else — the availability read's
+      // /v2/slots call is exactly what this method exists to avoid.
+      const resolved = await resolveEventType(req.calLink);
+      if (!resolved.ok) return resolved;
+      return { ok: true, value: resolved.value.meta };
+    },
+
+    async listAvailability(
+      req: ListAvailabilityRequest,
+    ): Promise<SchedulingOutcome<AvailabilityResult>> {
+      const resolved = await resolveEventType(req.calLink, req.timeZone);
+      if (!resolved.ok) return resolved;
+
+      const query = new URLSearchParams({
+        eventTypeId: String(resolved.value.id),
+        start: req.from,
+        end: req.to,
+        timeZone: resolved.value.meta.timeZone,
+      });
+      const res = await request(
+        `/v2/slots?${query.toString()}`,
+        SLOTS_API_VERSION,
+      );
+      if (!res.ok) return res;
+
+      const envelope = res.value as { data?: unknown } | null;
+      return {
+        ok: true,
+        value: {
+          event: resolved.value.meta,
+          slots: flattenSlots(
+            envelope?.data,
+            resolved.value.meta.durationMinutes,
+          ),
+        },
+      };
+    },
+
+    async createBooking(
+      req: CreateBookingRequest,
+    ): Promise<SchedulingOutcome<BookingResult>> {
+      const resolved = await resolveEventType(
+        req.calLink,
+        req.attendee.timeZone,
+      );
+      if (!resolved.ok) return resolved;
+
+      const res = await request("/v2/bookings", BOOKINGS_API_VERSION, {
+        method: "POST",
+        body: JSON.stringify({
+          start: req.start,
+          eventTypeId: resolved.value.id,
+          attendee: {
+            name: req.attendee.name,
+            email: req.attendee.email,
+            timeZone: req.attendee.timeZone ?? resolved.value.meta.timeZone,
+            language: "en",
+          },
+          ...(req.attendee.notes !== undefined
+            ? { metadata: { notes: req.attendee.notes } }
+            : {}),
+        }),
+      });
+      if (!res.ok) return res;
+
+      const envelope = res.value as { data?: unknown } | null;
+      const booking = envelope?.data as Record<string, unknown> | undefined;
+      if (!booking || typeof booking !== "object") {
+        return schedulingError("provider_error", "Cal returned no booking.");
+      }
+
+      const rawId = booking["uid"] ?? booking["id"];
+      const start = booking["start"];
+      if (
+        (typeof rawId !== "string" && typeof rawId !== "number") ||
+        typeof start !== "string"
+      ) {
+        return schedulingError(
+          "provider_error",
+          "Cal booking is missing uid or start.",
+        );
+      }
+
+      const startMs = Date.parse(start);
+      const end = booking["end"];
+      const meetingUrl = booking["meetingUrl"];
+      return {
+        ok: true,
+        value: {
+          bookingId: String(rawId),
+          start: new Date(startMs).toISOString(),
+          end:
+            typeof end === "string" && !Number.isNaN(Date.parse(end))
+              ? new Date(Date.parse(end)).toISOString()
+              : new Date(
+                  startMs + resolved.value.meta.durationMinutes * 60_000,
+                ).toISOString(),
+          ...(typeof meetingUrl === "string" && meetingUrl
+            ? { meetingUrl }
+            : {}),
+        },
+      };
+    },
+  };
+}

package/templates/apps/api/src/services/scheduling/index.ts

@@ -0,0 +1,63 @@
+// oss: false
+/**
+ * Scheduling service entry point (#4416) — provider resolution.
+ *
+ * `resolveSchedulingProvider()` returns `null` when no provider is
+ * configured, and that null is a FIRST-CLASS STATE, not an error: the routes
+ * turn it into a 503 `scheduling_not_configured`, the MCP twins surface it as
+ * `not_configured`, and the `booker` section renders its degraded state with
+ * a direct link out to the provider's own booking page. A deployment that
+ * never sets `CAL_API_KEY` still ships a page that books.
+ *
+ * Config:
+ *   CAL_API_KEY           — required to enable scheduling. Server-side only.
+ *   CAL_API_BASE_URL      — optional; self-hosted Cal instances.
+ *   SCHEDULING_PROVIDER   — optional; defaults to "cal". The config flip that
+ *                           #4288's self-hosted engine will answer to.
+ */
+
+import { createCalSchedulingProvider } from "./cal-provider.js";
+import type { SchedulingProvider } from "./types.js";
+
+export {
+  createCalSchedulingProvider,
+  type CalProviderOptions,
+} from "./cal-provider.js";
+export {
+  schedulingError,
+  type CreateBookingRequest,
+  type GetEventMetaRequest,
+  type ListAvailabilityRequest,
+  type SchedulingError,
+  type SchedulingOutcome,
+  type SchedulingProvider,
+} from "./types.js";
+
+/**
+ * Build the configured provider, or `null` when scheduling is unconfigured.
+ *
+ * Read per call rather than cached at module load so a test (and a process
+ * that loads its env late) sees the current environment — the same posture
+ * `packages/email`'s Resend client takes with `RESEND_API_KEY`.
+ */
+export function resolveSchedulingProvider(): SchedulingProvider | null {
+  const providerId = process.env["SCHEDULING_PROVIDER"] ?? "cal";
+  if (providerId !== "cal") return null;
+
+  const apiKey = process.env["CAL_API_KEY"];
+  if (!apiKey) return null;
+
+  const baseUrl = process.env["CAL_API_BASE_URL"];
+  return createCalSchedulingProvider({
+    apiKey,
+    ...(baseUrl ? { baseUrl } : {}),
+  });
+}
+
+/**
+ * Whether scheduling is configured. Cheap enough to call from a route and
+ * side-effect free — used for the degraded-state branch.
+ */
+export function isSchedulingConfigured(): boolean {
+  return resolveSchedulingProvider() !== null;
+}

package/templates/apps/api/src/services/scheduling/types.ts

@@ -0,0 +1,88 @@
+// oss: false
+/**
+ * The scheduling provider seam (#4416, meta read #4633).
+ *
+ * THREE CALLS. That is the whole interface, and keeping it that small is the
+ * point: the `booker` section is written against `listAvailability` +
+ * `createBooking`, and a booking tile against `getEventMeta` — the meta-only
+ * read that exists so rendering an event's facts never costs an availability
+ * window. The self-hosted scheduling engine (#4288) ships as a second
+ * implementation of this file's `SchedulingProvider` and nothing in
+ * `packages/ui`, `apps/mcp`, or the routes changes — same section, same
+ * content, a config flip.
+ *
+ * Nothing Cal-specific appears below. Cal's event-type ids, its per-endpoint
+ * `cal-api-version` headers, and its slot-map response shape are all confined
+ * to `cal-provider.ts`; a second provider owes this file only the two methods
+ * and the shared error vocabulary.
+ */
+
+import type {
+  AvailabilityResult,
+  BookingResult,
+  SchedulingAttendee,
+  SchedulingErrorKind,
+  SchedulingEventMeta,
+} from "@working-theory/validation";
+
+/** A failure, in the provider-independent vocabulary the routes map to status codes. */
+export interface SchedulingError {
+  kind: SchedulingErrorKind;
+  /** Operator-facing detail. Safe to log; the routes decide what to expose. */
+  message: string;
+}
+
+export type SchedulingOutcome<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: SchedulingError };
+
+/** The range + presentation options for an availability read. */
+export interface ListAvailabilityRequest {
+  /** `"<owner>/<event-slug>"`. */
+  calLink: string;
+  /** Range start, ISO-8601 instant. */
+  from: string;
+  /** Range end, ISO-8601 instant. */
+  to: string;
+  /** Present slots in this IANA timezone; omitted → the event's own. */
+  timeZone?: string;
+}
+
+/**
+ * The meta-only read (#4633): one event's derived facts, no slots. The route
+ * fans out over its comma-separated `calLinks`, one of these per link.
+ */
+export interface GetEventMetaRequest {
+  /** `"<owner>/<event-slug>"`. */
+  calLink: string;
+}
+
+/** One slot plus who is taking it. */
+export interface CreateBookingRequest {
+  calLink: string;
+  /** The chosen slot's start, ISO-8601 instant. */
+  start: string;
+  attendee: SchedulingAttendee;
+}
+
+export interface SchedulingProvider {
+  /** Stable identifier for logs and the degraded-state message. */
+  readonly id: string;
+  listAvailability(
+    request: ListAvailabilityRequest,
+  ): Promise<SchedulingOutcome<AvailabilityResult>>;
+  createBooking(
+    request: CreateBookingRequest,
+  ): Promise<SchedulingOutcome<BookingResult>>;
+  getEventMeta(
+    request: GetEventMetaRequest,
+  ): Promise<SchedulingOutcome<SchedulingEventMeta>>;
+}
+
+/** Convenience constructor so implementations read as one line per failure. */
+export function schedulingError(
+  kind: SchedulingErrorKind,
+  message: string,
+): { ok: false; error: SchedulingError } {
+  return { ok: false, error: { kind, message } };
+}