@volter/twin-calcom 0.1.0

package/src/calcom-twin.ts

@@ -0,0 +1,675 @@
+// Cal.com twin REQUEST HANDLER — the canonical Cal.com v2 API surface for the twin and
+// the QA stack's authoritative Cal.com. Contract: handleCalcomTwinRequest({method, path,
+// body}) -> {status, body}. Backed by the @volter/world-core event/action-log kernel; response
+// SHAPES are faithful to real Cal.com v2 (the `{ status, data }` envelope), not invented.
+// HTTP wrapper: calcom-server.ts → createCalcomTwinServer.
+//
+// State lives in the action log (R18): writes are local actions, reads fold the projection.
+// No real Cal.com is ever called. Auth is a faked-locally Bearer API key (`cal_...`); there
+// is NO JWT / JWKS / webhook signing — Cal.com's API auth is a plain bearer key.
+import { applyTwinWrite, projectResources, resolveSubjectId } from '@volter/world-core';
+
+const SERVICE = 'calcom';
+
+export type CalcomRequest = { method: string; path: string; body?: string; occurredAt?: string; root?: string; readOnly?: boolean; apiVersion?: string };
+export type CalcomResponse = { status: number; body: unknown };
+
+// Cal.com v2 pins behavior with a per-endpoint `cal-api-version` (YYYY-MM-DD) header. The
+// twin pins the versions its shapes were built against; a request may echo its own.
+export const TWIN_API_VERSION = '2024-08-13';
+
+// ── the v2 envelope ──────────────────────────────────────────────────────────
+// Every v2 response is { status: "success" | "error", data } (errors add { error }).
+function success(data: unknown, status = 200): CalcomResponse {
+  return { status, body: { status: 'success', data } };
+}
+function failure(message: string, status = 400, code?: string): CalcomResponse {
+  return { status, body: { status: 'error', error: { code: code ?? errCode(status), message } } };
+}
+function errCode(status: number): string {
+  if (status === 404) return 'NotFoundException';
+  if (status === 401) return 'UnauthorizedException';
+  if (status === 409) return 'ConflictException';
+  return 'BadRequestException';
+}
+
+// ── id helpers (type-prefixed subject ids) ─────────────────────────────────────
+// Subject ids are type-prefixed to stay self-describing across resource types (a
+// convention — the kernel resolves a write's returned resource by (type, id)).
+// Booking uid is the public handle; the numeric `id` and
+// `uid` Cal.com returns are derived deterministically from a monotonic per-root counter.
+function nextSeq(type: string, root?: string): number {
+  // derive a stable next number from how many of this type already exist + a base offset
+  // event_type base is 7100 so created ids never collide with DEFAULT_EVENT_TYPE.id (7001).
+  const base: Record<string, number> = { booking: 9000, event_type: 7100, schedule: 8000, team: 6000, membership: 4000, webhook: 3000 };
+  const count = list(type, root).length;
+  return (base[type] ?? 1000) + count + 1;
+}
+
+function list(type: string, root?: string): Record<string, unknown>[] {
+  return (projectResources(SERVICE, root).filter((r) => r.type === type) as unknown as Record<string, unknown>[])
+    .filter((r) => r.deleted !== true);
+}
+function getById(type: string, id: string, root?: string): Record<string, unknown> | undefined {
+  // protocol 2: after a landing adopted Cal.com's id for this subject, a caller on a branch may still name it
+  // as it was — the alias map is asked once, here, before any row is read
+  const subject = resolveSubjectId(SERVICE, type, id, root);
+  return list(type, root).find((r) => (r as { id: string }).id === subject);
+}
+
+// The twin's single seeded user (the API key owner) — Cal.com's GET /v2/me.
+// Faithful to the QA stack's `/v2/me` shape.
+const ME = {
+  id: 5000,
+  username: 'twin-calcom-admin',
+  email: 'admin@calcom.twin',
+  name: 'Cal.com Twin Admin',
+  avatarUrl: null,
+  bio: null,
+  timeFormat: 12,
+  defaultScheduleId: 8000,
+  weekStart: 'Monday',
+  timeZone: 'America/Los_Angeles',
+  organizationId: 6000,
+  organization: { id: 6000, isPlatform: true },
+};
+
+// The live profile = the seeded ME merged with any persisted PATCH /v2/me overlay (kernel-folded).
+function meProfile(root?: string): Record<string, unknown> {
+  const overlay = getById('profile', 'profile_me', root);
+  if (!overlay) return ME;
+  const { type, updatedAt, id, ...rest } = overlay as Record<string, unknown>;
+  void type; void updatedAt; void id;
+  return { ...ME, ...rest };
+}
+
+// The twin ships one implicit default event type (id 7001) so a booking can be created out of
+// the box (Cal.com's demo "30 Min Meeting"). It never requiresConfirmation.
+const DEFAULT_EVENT_TYPE = { id: 7001, title: '30 Min Meeting', slug: 'consultation', lengthInMinutes: 30, requiresConfirmation: false } as Record<string, unknown>;
+
+function parseBody(body?: string): Record<string, unknown> {
+  if (!body) return {};
+  try { return JSON.parse(body) as Record<string, unknown>; } catch { return {}; }
+}
+
+async function write(type: string, id: string, fields: Record<string, unknown>, root?: string, occurredAt?: string): Promise<void> {
+  await applyTwinWrite(SERVICE, { operation: `set.${type}`, subjectType: type, subjectId: id, fields, ...(occurredAt ? { occurredAt } : {}), actor: { kind: 'agent' } }, root);
+}
+
+// Strip the kernel's projection-internal fields (id/type/updatedAt) and re-key the public id.
+function emit(r: Record<string, unknown>, publicIdKey = 'id'): Record<string, unknown> {
+  const { type, updatedAt, id, ...rest } = r as { type?: unknown; updatedAt?: unknown; id?: unknown } & Record<string, unknown>;
+  void type; void updatedAt; void publicIdKey;
+  return rest;
+}
+
+// ── take/skip pagination (Cal.com v2 list shape) ──────────────────────────────
+// Cal.com list endpoints page with `take` (page size) + `skip` (offset). When neither is
+// present we return the full array (back-compat with non-paginated callers). When present we
+// slice and attach a sibling `pagination` object: { totalCount, take, skip, hasMore }.
+function paginated(rows: unknown[], query: URLSearchParams): CalcomResponse {
+  const takeRaw = query.get('take');
+  const skipRaw = query.get('skip');
+  if (takeRaw === null && skipRaw === null) return success(rows);
+  const skip = Math.max(0, Number.isFinite(Number(skipRaw)) ? Number(skipRaw) : 0);
+  const take = takeRaw === null ? rows.length : Math.max(0, Number(takeRaw) || 0);
+  const page = rows.slice(skip, skip + take);
+  const body = { status: 'success', data: page, pagination: { totalCount: rows.length, take, skip, hasMore: skip + take < rows.length } };
+  return { status: 200, body };
+}
+
+// ── slots availability (deterministic, derived) ───────────────────────────────
+// Cal.com's GET /v2/slots returns availability keyed by date: { "<YYYY-MM-DD>": [{ start }] }.
+// We derive a deterministic two-slot day (16:00 + 17:00 UTC) from a base date so the verify is
+// reproducible offline. `start` (or `startTime`) query param picks the base day; default = a
+// fixed reference date so the response is stable without a clock.
+const SLOT_REF = '2026-07-01T00:00:00.000Z';
+function computeSlots(query: URLSearchParams): Record<string, { start: string }[]> {
+  const startParam = query.get('start') ?? query.get('startTime');
+  const base = new Date(startParam && !Number.isNaN(Date.parse(startParam)) ? startParam : SLOT_REF);
+  base.setUTCHours(16, 0, 0, 0);
+  const second = new Date(base.getTime() + 60 * 60 * 1000);
+  const dateKey = base.toISOString().slice(0, 10);
+  return { [dateKey]: [{ start: base.toISOString() }, { start: second.toISOString() }] };
+}
+
+// ── booking shape (faithful to v2 BookingOutput + the QA stack's shape) ────────
+function bookingView(r: Record<string, unknown>): Record<string, unknown> {
+  return emit(r);
+}
+
+export async function handleCalcomTwinRequest(req: CalcomRequest): Promise<CalcomResponse> {
+  const { method, root, occurredAt } = req;
+  const readOnly = req.readOnly ?? false;
+  const isWrite = method !== 'GET' && method !== 'HEAD';
+  let url: URL;
+  try { url = new URL(req.path, 'http://twin.local'); } catch { return failure('invalid path', 400); }
+  // Normalize: tolerate both /v2/<x> and /<x> (the QA sandbox hits both forms).
+  const pathname = url.pathname.replace(/^\/v2(\/|$)/, '/');
+  const parts = pathname.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+  const query = url.searchParams;
+  const body = parseBody(req.body);
+
+  if (readOnly && isWrite) return failure('this twin was started read-only; omit readOnly to accept writes', 405, 'ReadOnlyException');
+
+  // GET /v2/me  — the profile is ME merged with any persisted profile overlay (PATCH /v2/me)
+  if (parts[0] === 'me' && parts.length === 1) {
+    if (method === 'GET') return success(meProfile(root));
+    // PATCH /v2/me — update a small set of mutable profile fields (Cal.com's UpdateOrgMembership-ish)
+    if (method === 'PATCH') {
+      const allowed = ['name', 'email', 'timeZone', 'weekStart', 'timeFormat', 'bio', 'avatarUrl', 'locale', 'username'] as const;
+      const patch: Record<string, unknown> = {};
+      for (const k of allowed) if (body[k] !== undefined) patch[k] = body[k];
+      if (Object.keys(patch).length === 0) return failure('at least one updatable profile field is required', 400);
+      await write('profile', 'profile_me', patch, root, occurredAt);
+      return success(meProfile(root));
+    }
+  }
+
+  // GET /v2/slots  (availability)
+  if (method === 'GET' && parts[0] === 'slots' && parts.length === 1) {
+    return success(computeSlots(query));
+  }
+  // POST /v2/slots/reservations  (reserve a slot)
+  if (parts[0] === 'slots' && parts[1] === 'reservations') {
+    if (method === 'POST' && parts.length === 2) {
+      const eventTypeId = body.eventTypeId;
+      const slotStart = body.slotStart ?? body.start;
+      if (eventTypeId === undefined) return failure('eventTypeId is required', 400);
+      if (slotStart === undefined) return failure('slotStart is required', 400);
+      const uid = `slot_${seqHex('slot', root)}`;
+      await write('slot', uid, { reservationUid: uid, eventTypeId, slotStart, slotDuration: body.slotDuration ?? 30 }, root, occurredAt);
+      return success({ reservationUid: uid, eventTypeId, slotStart, slotEnd: addMinutes(String(slotStart), Number(body.slotDuration ?? 30)) }, 201);
+    }
+    // GET/DELETE /v2/slots/reservations/{uid}
+    if (parts.length === 3) {
+      const slotId = `slot_${stripPrefix(parts[2]!, 'slot_')}`;
+      const found = getById('slot', slotId, root) ?? getById('slot', parts[2]!, root);
+      if (method === 'GET') {
+        if (!found) return failure(`No reservation found for uid ${parts[2]}`, 404);
+        return success(emit(found));
+      }
+      // DELETE /v2/slots/reservations/{uid} — release a held slot (then GET → 404)
+      if (method === 'DELETE') {
+        if (!found) return failure(`No reservation found for uid ${parts[2]}`, 404);
+        await write('slot', (found.id as string), { deleted: true }, root, occurredAt);
+        return success({ reservationUid: parts[2] });
+      }
+    }
+  }
+
+  // ── Bookings ────────────────────────────────────────────────────────────────
+  if (parts[0] === 'bookings') {
+    // POST /v2/bookings  (create)
+    if (method === 'POST' && parts.length === 1) {
+      const start = body.start;
+      if (start === undefined || typeof start !== 'string' || Number.isNaN(Date.parse(start))) {
+        return failure('start is required and must be an ISO 8601 datetime', 400);
+      }
+      const attendee = (body.attendee as Record<string, unknown> | undefined) ?? {};
+      if (!attendee.name || !attendee.email) return failure('attendee.name and attendee.email are required', 400);
+      const eventTypeId = (body.eventTypeId as number | undefined) ?? DEFAULT_EVENT_TYPE.id;
+      // Faithful: a provided eventTypeId that resolves to no event type is a 404 (the twin ships
+      // one implicit default event type, id 7001, that always exists — Cal.com's demo flow).
+      const evt = eventTypeId === DEFAULT_EVENT_TYPE.id ? DEFAULT_EVENT_TYPE : getById('event_type', `evt_${eventTypeId}`, root);
+      if (!evt) return failure(`No event type found for id ${eventTypeId}`, 404);
+      const duration = (body.lengthInMinutes as number | undefined) ?? (evt.lengthInMinutes as number | undefined) ?? 30;
+      const numId = nextSeq('booking', root);
+      const uid = `booking_${seqHex('booking', root)}`;
+      const end = addMinutes(start, duration);
+      // Faithful to Cal.com: a booking on an event type that requiresConfirmation starts
+      // `pending` (the host must confirm/decline it); otherwise it is immediately `accepted`.
+      const initialStatus = evt?.requiresConfirmation === true ? 'pending' : 'accepted';
+      const record = {
+        bid: numId,
+        uid,
+        title: (body.title as string | undefined) ?? (evt?.title as string | undefined) ?? 'Consultation between Cal.com Twin Admin and ' + attendee.name,
+        status: initialStatus,
+        start,
+        end,
+        duration,
+        eventTypeId,
+        eventType: { id: eventTypeId, slug: (evt?.slug as string | undefined) ?? 'consultation' },
+        attendees: [{
+          name: attendee.name,
+          email: attendee.email,
+          timeZone: attendee.timeZone ?? 'America/Los_Angeles',
+          language: attendee.language ?? 'en',
+          absent: false,
+        }],
+        hosts: [{ id: ME.id, name: ME.name, timeZone: ME.timeZone, mandatory: true }],
+        guests: (body.guests as unknown[] | undefined) ?? [],
+        location: (body.location as unknown) ?? null,
+        meetingUrl: (body.meetingUrl as unknown) ?? null,
+        metadata: (body.metadata as Record<string, unknown> | undefined) ?? {},
+      };
+      await write('booking', uid, record as Record<string, unknown>, root, occurredAt);
+      const out = await renderBooking(uid, root);
+      return success(out, 201);
+    }
+    // GET /v2/bookings  (list — with status/attendeeEmail/eventTypeId filters + take/skip)
+    if (method === 'GET' && parts.length === 1) {
+      const all = list('booking', root).filter((b) => (b.uid as string | undefined)); // bookings only
+      let filtered = all;
+      const status = query.get('status');
+      if (status) filtered = filtered.filter((b) => b.status === status);
+      const attendeeEmail = query.get('attendeeEmail');
+      if (attendeeEmail) filtered = filtered.filter((b) => Array.isArray(b.attendees) && (b.attendees as Record<string, unknown>[]).some((a) => a.email === attendeeEmail));
+      const eventTypeId = query.get('eventTypeId');
+      if (eventTypeId) filtered = filtered.filter((b) => String(b.eventTypeId) === eventTypeId);
+      const rendered = await Promise.all(filtered.map((b) => renderBooking(b.id as string, root)));
+      return paginated(rendered, query);
+    }
+    // GET /v2/bookings/{uid}
+    if (method === 'GET' && parts.length === 2) {
+      const uid = canonicalBookingId(parts[1]!);
+      const found = getById('booking', uid, root);
+      if (!found) return failure(`No booking found for uid ${parts[1]}`, 404);
+      return success(await renderBooking(uid, root));
+    }
+    // GET /v2/bookings/{uid}/references | /recordings | /transcripts (read sub-resources)
+    if (method === 'GET' && parts.length === 3) {
+      const uid = canonicalBookingId(parts[1]!);
+      const sub = parts[2]!;
+      const found = getById('booking', uid, root);
+      if (!found) return failure(`No booking found for uid ${parts[1]}`, 404);
+      if (sub === 'references') {
+        // Booking references = the per-integration external handles a booking accrues (calendar
+        // event id, conferencing meeting id). A local twin has no real providers, so a freshly
+        // created twin booking carries no external references → an empty array (faithful: the
+        // field exists and is queryable, it is simply empty without a real integration).
+        return success((found.references as unknown[] | undefined) ?? []);
+      }
+      if (sub === 'recordings') {
+        // Recordings are produced by the real video provider (Daily). A local twin never records,
+        // so the list is empty — but the endpoint exists and returns the v2 array shape.
+        return success((found.recordings as unknown[] | undefined) ?? []);
+      }
+      // unknown sub-resource → 404 like the vendor
+      return failure(`Cannot GET /v2/bookings/${parts[1]}/${sub}`, 404);
+    }
+    // POST /v2/bookings/{uid}/cancel | /reschedule | /confirm | /decline | /mark-absent
+    if (method === 'POST' && parts.length === 3) {
+      const uid = canonicalBookingId(parts[1]!);
+      const action = parts[2]!;
+      const found = getById('booking', uid, root);
+      if (!found) return failure(`No booking found for uid ${parts[1]}`, 404);
+      const cur = found.status as string;
+
+      if (action === 'mark-absent') {
+        // Mark host and/or attendees absent (no-show). Cal.com flags `absent` on the matching
+        // attendees and `noShowHost` on the booking; the booking status is unchanged.
+        if (cur === 'cancelled') return failure('Cannot mark a cancelled booking absent', 400);
+        const noShowHost = body.noShowHost === true;
+        const absentEmails = new Set((Array.isArray(body.attendees) ? body.attendees as Record<string, unknown>[] : []).filter((a) => a.absent === true).map((a) => String(a.email)));
+        const attendees = (found.attendees as Record<string, unknown>[]).map((a) => absentEmails.has(String(a.email)) ? { ...a, absent: true } : a);
+        await write('booking', uid, { attendees, noShowHost }, root, occurredAt);
+        return success({ ...(await renderBooking(uid, root)), noShowHost });
+      }
+
+      if (action === 'cancel') {
+        if (cur === 'cancelled') return failure(`Booking ${parts[1]} is already cancelled`, 400, 'ConflictException');
+        await write('booking', uid, { status: 'cancelled', cancellationReason: (body.cancellationReason as string | undefined) ?? null }, root, occurredAt);
+        return success({ ...(await renderBooking(uid, root)), status: 'cancelled' });
+      }
+      if (action === 'reschedule') {
+        if (cur === 'cancelled') return failure(`Cannot reschedule a cancelled booking`, 400);
+        const start = body.start;
+        if (start === undefined || typeof start !== 'string' || Number.isNaN(Date.parse(start))) return failure('start is required to reschedule', 400);
+        const newUid = `booking_${seqHex('booking', root)}`;
+        const duration = found.duration as number;
+        const rec = { ...found, uid: newUid, bid: nextSeq('booking', root), start, end: addMinutes(start, duration), status: 'accepted', reschedulingReason: (body.reschedulingReason as string | undefined) ?? null, fromReschedule: uid };
+        await write('booking', newUid, rec as Record<string, unknown>, root, occurredAt);
+        await write('booking', uid, { status: 'cancelled', rescheduled: true }, root, occurredAt);
+        return success(await renderBooking(newUid, root), 201);
+      }
+      if (action === 'confirm') {
+        if (cur !== 'pending') return failure(`Only a pending booking can be confirmed (current status: ${cur})`, 400);
+        await write('booking', uid, { status: 'accepted' }, root, occurredAt);
+        return success(await renderBooking(uid, root));
+      }
+      if (action === 'decline') {
+        if (cur !== 'pending') return failure(`Only a pending booking can be declined (current status: ${cur})`, 400);
+        await write('booking', uid, { status: 'rejected', rejectionReason: (body.reason as string | undefined) ?? null }, root, occurredAt);
+        return success(await renderBooking(uid, root));
+      }
+      return failure(`Unknown booking action: ${action}`, 404);
+    }
+  }
+
+  // ── Event types ───────────────────────────────────────────────────────────
+  if (parts[0] === 'event-types') {
+    if (method === 'POST' && parts.length === 1) {
+      if (!body.title || !body.slug || body.lengthInMinutes === undefined) return failure('title, slug and lengthInMinutes are required', 400);
+      const numId = nextSeq('event_type', root);
+      const id = `evt_${numId}`;
+      const rec = {
+        evtId: numId,
+        title: body.title,
+        slug: body.slug,
+        lengthInMinutes: body.lengthInMinutes,
+        description: body.description ?? null,
+        ownerId: ME.id,
+        hidden: body.hidden ?? false,
+        scheduleId: body.scheduleId ?? null,
+        requiresConfirmation: body.requiresConfirmation ?? false,
+        bookingUrl: `https://cal.com/${ME.username}/${body.slug}`,
+        locations: body.locations ?? [],
+        bookingFields: body.bookingFields ?? [],
+        seatsPerTimeSlot: body.seatsPerTimeSlot ?? null,
+        seatsShowAttendees: body.seatsShowAttendees ?? false,
+        seatsShowAvailabilityCount: body.seatsShowAvailabilityCount ?? true,
+        beforeEventBuffer: body.beforeEventBuffer ?? 0,
+        afterEventBuffer: body.afterEventBuffer ?? 0,
+        minimumBookingNotice: body.minimumBookingNotice ?? 0,
+      };
+      await write('event_type', id, rec as Record<string, unknown>, root, occurredAt);
+      return success(eventTypeView(getById('event_type', id, root)!), 201);
+    }
+    if (method === 'GET' && parts.length === 1) {
+      // Personal event types only (team event types live under /v2/teams/{id}/event-types).
+      let rows = list('event_type', root).filter((e) => e.teamId === undefined || e.teamId === null).map(eventTypeView);
+      // Public lookup: GET /v2/event-types?username=&eventSlug= — filter to one owner/slug. Cal.com
+      // requires username when eventSlug is given. The implicit default ("30 Min Meeting") belongs
+      // to the seeded admin and is included so a fresh account is still publicly bookable.
+      const username = query.get('username');
+      const eventSlug = query.get('eventSlug');
+      if (eventSlug !== null && username === null) return failure('username is required when eventSlug is provided', 400);
+      if (username !== null) {
+        if (username === ME.username) rows = [defaultEventTypeView(), ...rows];
+        else rows = []; // unknown user has no event types
+        if (eventSlug !== null) rows = rows.filter((e) => e.slug === eventSlug);
+      }
+      return paginated(rows, query);
+    }
+    if (parts.length === 2) {
+      const id = parts[1]!.startsWith('evt_') ? parts[1]! : `evt_${parts[1]}`;
+      const found = getById('event_type', id, root);
+      if (method === 'GET') {
+        if (!found) return failure(`No event type found for id ${parts[1]}`, 404);
+        return success(eventTypeView(found));
+      }
+      if (method === 'PATCH') {
+        if (!found) return failure(`No event type found for id ${parts[1]}`, 404);
+        await write('event_type', id, body, root, occurredAt);
+        return success(eventTypeView(getById('event_type', id, root)!));
+      }
+      if (method === 'DELETE') {
+        if (!found) return failure(`No event type found for id ${parts[1]}`, 404);
+        await write('event_type', id, { deleted: true }, root, occurredAt);
+        return success({ id: found.evtId, lengthInMinutes: found.lengthInMinutes, title: found.title, slug: found.slug });
+      }
+    }
+  }
+
+  // ── Schedules / availability ─────────────────────────────────────────────────
+  if (parts[0] === 'schedules') {
+    if (method === 'POST' && parts.length === 1) {
+      if (!body.name || !body.timeZone || body.isDefault === undefined) return failure('name, timeZone and isDefault are required', 400);
+      const numId = nextSeq('schedule', root);
+      const id = `sched_${numId}`;
+      const rec = {
+        schedId: numId,
+        ownerId: ME.id,
+        name: body.name,
+        timeZone: body.timeZone,
+        availability: body.availability ?? [{ days: ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'], startTime: '09:00', endTime: '17:00' }],
+        isDefault: body.isDefault,
+        overrides: body.overrides ?? [],
+      };
+      await write('schedule', id, rec as Record<string, unknown>, root, occurredAt);
+      return success(scheduleView(getById('schedule', id, root)!), 201);
+    }
+    if (method === 'GET' && parts.length === 1) {
+      return success(list('schedule', root).map(scheduleView));
+    }
+    if (parts.length === 2) {
+      const id = parts[1]!.startsWith('sched_') ? parts[1]! : `sched_${parts[1]}`;
+      const found = getById('schedule', id, root);
+      if (method === 'GET') {
+        if (!found) return failure(`No schedule found for id ${parts[1]}`, 404);
+        return success(scheduleView(found));
+      }
+      if (method === 'PATCH') {
+        if (!found) return failure(`No schedule found for id ${parts[1]}`, 404);
+        await write('schedule', id, body, root, occurredAt);
+        return success(scheduleView(getById('schedule', id, root)!));
+      }
+      if (method === 'DELETE') {
+        if (!found) return failure(`No schedule found for id ${parts[1]}`, 404);
+        await write('schedule', id, { deleted: true }, root, occurredAt);
+        return success({ id: found.schedId });
+      }
+    }
+  }
+
+  // ── Teams ────────────────────────────────────────────────────────────────────
+  if (parts[0] === 'teams') {
+    if (method === 'POST' && parts.length === 1) {
+      if (!body.name) return failure('name is required', 400);
+      const numId = nextSeq('team', root);
+      const id = `team_${numId}`;
+      await write('team', id, { teamId: numId, name: body.name, slug: body.slug ?? slugify(String(body.name)), isOrganization: body.isOrganization ?? false }, root, occurredAt);
+      return success(teamView(getById('team', id, root)!), 201);
+    }
+    if (method === 'GET' && parts.length === 1) return success(list('team', root).map(teamView));
+    if (parts.length === 2) {
+      const id = parts[1]!.startsWith('team_') ? parts[1]! : `team_${parts[1]}`;
+      const found = getById('team', id, root);
+      if (method === 'GET') {
+        if (!found) return failure(`No team found for id ${parts[1]}`, 404);
+        return success(teamView(found));
+      }
+      // PATCH /v2/teams/{id} — update mutable team fields
+      if (method === 'PATCH') {
+        if (!found) return failure(`No team found for id ${parts[1]}`, 404);
+        const patch: Record<string, unknown> = {};
+        for (const k of ['name', 'slug', 'bio', 'hideBranding', 'isPrivate'] as const) if (body[k] !== undefined) patch[k] = body[k];
+        if (Object.keys(patch).length === 0) return failure('at least one updatable team field is required', 400);
+        await write('team', id, patch, root, occurredAt);
+        return success(teamView(getById('team', id, root)!));
+      }
+      // DELETE /v2/teams/{id} — delete (then 404)
+      if (method === 'DELETE') {
+        if (!found) return failure(`No team found for id ${parts[1]}`, 404);
+        await write('team', id, { deleted: true }, root, occurredAt);
+        return success(teamView(found));
+      }
+    }
+    // Team event types: /v2/teams/{teamId}/event-types ...
+    if (parts[2] === 'event-types') {
+      const teamId = parts[1]!.startsWith('team_') ? parts[1]! : `team_${parts[1]}`;
+      const team = getById('team', teamId, root);
+      if (!team) return failure(`No team found for id ${parts[1]}`, 404);
+      const teamNumId = team.teamId as number;
+      if (method === 'POST' && parts.length === 3) {
+        if (!body.title || !body.slug || body.lengthInMinutes === undefined) return failure('title, slug and lengthInMinutes are required', 400);
+        const numId = nextSeq('event_type', root);
+        const id = `evt_${numId}`;
+        const rec = {
+          evtId: numId, title: body.title, slug: body.slug, lengthInMinutes: body.lengthInMinutes,
+          description: body.description ?? null, ownerId: ME.id, hidden: body.hidden ?? false,
+          scheduleId: body.scheduleId ?? null, requiresConfirmation: body.requiresConfirmation ?? false,
+          bookingUrl: `https://cal.com/team/${team.slug}/${body.slug}`,
+          teamId: teamNumId, schedulingType: body.schedulingType ?? 'collective',
+          locations: body.locations ?? [], bookingFields: body.bookingFields ?? [],
+        };
+        await write('event_type', id, rec as Record<string, unknown>, root, occurredAt);
+        return success(eventTypeView(getById('event_type', id, root)!), 201);
+      }
+      if (method === 'GET' && parts.length === 3) {
+        return success(list('event_type', root).filter((e) => e.teamId === teamNumId).map(eventTypeView));
+      }
+    }
+    // Memberships: /teams/{teamId}/memberships ...
+    if (parts[2] === 'memberships') {
+      const teamId = parts[1]!.startsWith('team_') ? parts[1]! : `team_${parts[1]}`;
+      if (!getById('team', teamId, root)) return failure(`No team found for id ${parts[1]}`, 404);
+      if (method === 'POST' && parts.length === 3) {
+        if (body.userId === undefined) return failure('userId is required', 400);
+        const numId = nextSeq('membership', root);
+        const id = `mem_${numId}`;
+        await write('membership', id, { memId: numId, teamId, userId: body.userId, role: body.role ?? 'MEMBER', accepted: body.accepted ?? true }, root, occurredAt);
+        return success(membershipView(getById('membership', id, root)!), 201);
+      }
+      if (method === 'GET' && parts.length === 3) {
+        return success(list('membership', root).filter((m) => m.teamId === teamId).map(membershipView));
+      }
+      // /teams/{teamId}/memberships/{membershipId}  (read/update/delete one)
+      if (parts.length === 4) {
+        const memId = parts[3]!.startsWith('mem_') ? parts[3]! : `mem_${parts[3]}`;
+        const found = getById('membership', memId, root);
+        if (!found || found.teamId !== teamId) return failure(`No membership found for id ${parts[3]}`, 404);
+        if (method === 'GET') return success(membershipView(found));
+        if (method === 'PATCH') {
+          const patch: Record<string, unknown> = {};
+          for (const k of ['role', 'accepted', 'disableImpersonation'] as const) if (body[k] !== undefined) patch[k] = body[k];
+          if (Object.keys(patch).length === 0) return failure('at least one updatable membership field is required', 400);
+          await write('membership', memId, patch, root, occurredAt);
+          return success(membershipView(getById('membership', memId, root)!));
+        }
+        if (method === 'DELETE') {
+          await write('membership', memId, { deleted: true }, root, occurredAt);
+          return success(membershipView(found));
+        }
+      }
+    }
+  }
+
+  // ── Webhooks (registration CRUD only — NO signing) ────────────────────────────
+  if (parts[0] === 'webhooks') {
+    if (method === 'POST' && parts.length === 1) {
+      if (!body.subscriberUrl || !Array.isArray(body.triggers) || body.triggers.length === 0) {
+        return failure('subscriberUrl and a non-empty triggers[] are required', 400);
+      }
+      const numId = nextSeq('webhook', root);
+      const id = `wh_${numId}`;
+      await write('webhook', id, { whId: id, subscriberUrl: body.subscriberUrl, triggers: body.triggers, active: body.active ?? true, payloadTemplate: body.payloadTemplate ?? null }, root, occurredAt);
+      return success(webhookView(getById('webhook', id, root)!), 201);
+    }
+    if (method === 'GET' && parts.length === 1) return success(list('webhook', root).map(webhookView));
+    if (parts.length === 2) {
+      const id = parts[1]!.startsWith('wh_') ? parts[1]! : `wh_${parts[1]}`;
+      const found = getById('webhook', id, root);
+      if (method === 'GET') {
+        if (!found) return failure(`No webhook found for id ${parts[1]}`, 404);
+        return success(webhookView(found));
+      }
+      if (method === 'PATCH') {
+        if (!found) return failure(`No webhook found for id ${parts[1]}`, 404);
+        await write('webhook', id, body, root, occurredAt);
+        return success(webhookView(getById('webhook', id, root)!));
+      }
+      if (method === 'DELETE') {
+        if (!found) return failure(`No webhook found for id ${parts[1]}`, 404);
+        await write('webhook', id, { deleted: true }, root, occurredAt);
+        return success({ id });
+      }
+    }
+  }
+
+  // Unmodeled op → 404, like the vendor (never a fake success).
+  return failure(`Cannot ${method} ${url.pathname}`, 404);
+}
+
+// ── view projections (kernel record → public v2 data object) ───────────────────
+async function renderBooking(uid: string, root?: string): Promise<Record<string, unknown>> {
+  const r = getById('booking', uid, root)!;
+  const v = bookingView(r);
+  // public `id` is the numeric Cal.com booking id; `uid` is the string handle
+  return {
+    id: r.bid,
+    uid: r.uid,
+    title: v.title,
+    status: v.status,
+    start: v.start,
+    end: v.end,
+    duration: v.duration,
+    eventTypeId: v.eventTypeId,
+    eventType: v.eventType,
+    attendees: v.attendees,
+    hosts: v.hosts,
+    guests: v.guests ?? [],
+    location: v.location ?? null,
+    meetingUrl: v.meetingUrl ?? null,
+    metadata: v.metadata ?? {},
+    ...(v.noShowHost !== undefined ? { noShowHost: v.noShowHost } : {}),
+    ...(v.cancellationReason !== undefined && v.cancellationReason !== null ? { cancellationReason: v.cancellationReason } : {}),
+    ...(v.reschedulingReason !== undefined && v.reschedulingReason !== null ? { reschedulingReason: v.reschedulingReason } : {}),
+  };
+}
+
+function eventTypeView(r: Record<string, unknown>): Record<string, unknown> {
+  return {
+    id: r.evtId,
+    lengthInMinutes: r.lengthInMinutes,
+    title: r.title,
+    slug: r.slug,
+    description: r.description ?? null,
+    ownerId: r.ownerId,
+    hidden: r.hidden ?? false,
+    scheduleId: r.scheduleId ?? null,
+    requiresConfirmation: r.requiresConfirmation ?? false,
+    bookingUrl: r.bookingUrl,
+    locations: r.locations ?? [],
+    bookingFields: r.bookingFields ?? [],
+    seatsPerTimeSlot: r.seatsPerTimeSlot ?? null,
+    seatsShowAttendees: r.seatsShowAttendees ?? false,
+    seatsShowAvailabilityCount: r.seatsShowAvailabilityCount ?? true,
+    beforeEventBuffer: r.beforeEventBuffer ?? 0,
+    afterEventBuffer: r.afterEventBuffer ?? 0,
+    minimumBookingNotice: r.minimumBookingNotice ?? 0,
+    ...(r.teamId !== undefined && r.teamId !== null ? { teamId: r.teamId, schedulingType: r.schedulingType ?? 'collective' } : {}),
+  };
+}
+// The implicit default event type rendered through the public-lookup view.
+function defaultEventTypeView(): Record<string, unknown> {
+  return eventTypeView({ evtId: DEFAULT_EVENT_TYPE.id, ...DEFAULT_EVENT_TYPE, ownerId: ME.id, bookingUrl: `https://cal.com/${ME.username}/${DEFAULT_EVENT_TYPE.slug}` });
+}
+function scheduleView(r: Record<string, unknown>): Record<string, unknown> {
+  return {
+    id: r.schedId,
+    ownerId: r.ownerId,
+    name: r.name,
+    timeZone: r.timeZone,
+    availability: r.availability ?? [],
+    isDefault: r.isDefault ?? false,
+    overrides: r.overrides ?? [],
+  };
+}
+function teamView(r: Record<string, unknown>): Record<string, unknown> {
+  return { id: r.teamId, name: r.name, slug: r.slug, isOrganization: r.isOrganization ?? false };
+}
+function membershipView(r: Record<string, unknown>): Record<string, unknown> {
+  return { id: r.memId, userId: r.userId, role: r.role, accepted: r.accepted ?? true, teamId: teamNum(r.teamId as string), disableImpersonation: r.disableImpersonation ?? false };
+}
+function webhookView(r: Record<string, unknown>): Record<string, unknown> {
+  return { id: r.whId, subscriberUrl: r.subscriberUrl, triggers: r.triggers, active: r.active ?? true, payloadTemplate: r.payloadTemplate ?? null };
+}
+
+// ── small utilities ────────────────────────────────────────────────────────────
+function addMinutes(iso: string, minutes: number): string {
+  return new Date(new Date(iso).getTime() + minutes * 60 * 1000).toISOString();
+}
+function slugify(s: string): string {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+function stripPrefix(s: string, p: string): string {
+  return s.startsWith(p) ? s.slice(p.length) : s;
+}
+function teamNum(id: string): number {
+  return Number(stripPrefix(id, 'team_'));
+}
+// A booking can be addressed by its string uid (booking_xxx) OR — once we returned a public
+// numeric `id` — only the uid is the stable path handle, mirroring Cal.com (paths use {uid}).
+function canonicalBookingId(raw: string): string {
+  return raw.startsWith('booking_') ? raw : `booking_${raw}`;
+}
+// Monotonic per-type hex sequence for stable string handles (deterministic given root state).
+function seqHex(type: string, root?: string): string {
+  const n = list(type, root).length + 1;
+  return n.toString(16).padStart(6, '0');
+}
+
+// The subject types this twin projects (for the pack descriptor / conformance).
+export const RESOURCE_TYPES = ['booking', 'event_type', 'schedule', 'team', 'membership', 'webhook', 'slot'] as const;