create-ailk 0.2.0 → 0.4.0

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

@@ -1,392 +0,0 @@
-// 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

@@ -1,63 +0,0 @@
-// 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

@@ -1,88 +0,0 @@
-// 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 } };
-}