@volter/twin-calcom 0.1.0

package/src/cli.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-calcom CLI: serve the Cal.com v2 API twin, the mirror UI, or run conformance.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createCalcomTwinServer } from './calcom-server.ts';
+import { createCalcomMirrorServer } from './calcom-mirror-ui.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+
+if (cmd === 'serve') {
+  const s = await createCalcomTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`calcom twin (v2 API)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'mirror') {
+  const s = await createCalcomMirrorServer({ ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`calcom mirror UI (dashboard) at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  // dev-only; lazy so the bin runs without @volter/world-tooling in the runtime graph
+  const { checkCalcomConformance } = await import('./calcom-conformance.ts');
+  const report = checkCalcomConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-calcom serve|mirror|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/src/index.ts

@@ -0,0 +1,101 @@
+// @volter/twin-calcom — the Cal.com twin (one vendor, one package), built on the shared
+// @volter/world-core kernel. REST (v2) transport, spec-faithful `{ status, data }` envelope,
+// stateful bookings/event-types/schedules/teams/webhooks, and a React dashboard mirror.
+// Auth is a faked-locally Bearer API key — there is NO JWT / JWKS / webhook signing
+// (Cal.com's API auth is a plain bearer `cal_…` key). Conformance tooling lives in
+// @volter/world-tooling (a dev dependency) — not shipped in the runtime API.
+export { handleCalcomTwinRequest, TWIN_API_VERSION, RESOURCE_TYPES } from './calcom-twin.ts';
+export type { CalcomRequest, CalcomResponse } from './calcom-twin.ts';
+export { createCalcomTwinFetch, createCalcomTwinServer, type CalcomTwinFetchOptions } from './calcom-server.ts';
+export {
+  calcomRequestForAction,
+  liveCalcomExecute,
+  mapBooking,
+  mapEventType,
+  pullCalcomAll,
+  pullCalcomBookings,
+  pullCalcomEventTypes,
+  syncCalcomFromReal,
+} from './calcom-connector.ts';
+export type { CalcomExecute, LiveCalcomOptions } from './calcom-connector.ts';
+// The client-side rate budget — the fail-closed backstop `liveCalcomExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is Cal.com's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
+// `CalcomBudgetError` by type; there is deliberately no export that disables the guard.
+export {
+  CALCOM_BUDGET_CEILING,
+  CALCOM_BUDGET_MAX_RETRY_AFTER_S,
+  CALCOM_BUDGET_WINDOW_MS,
+  CALCOM_CALL_WEIGHTS,
+  CALCOM_RATE_BUDGET,
+  CalcomBudget,
+  CalcomBudgetError,
+  calcomBudgetPath,
+  calcomCallWeight,
+} from './calcom-budget.ts';
+export type { CalcomBudgetErrorKind, CalcomBudgetOptions, CalcomBudgetReservation, CalcomBudgetSnapshot } from './calcom-budget.ts';
+export {
+  attendeeLabel,
+  bookingTone,
+  buildCalcomMirrorClient,
+  calcomMirrorHtml,
+  createCalcomMirrorServer,
+  formatWindow,
+} from './calcom-mirror-ui.ts';
+export type { CalcomRow } from './calcom-mirror-ui.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { CALCOM_RATE_BUDGET as RATE_BUDGET } from './calcom-budget.ts';
+import { performCalcomAction, syncCalcomFromRemote } from './calcom-connector.ts';
+
+export const pack: TwinPack = {
+  vendor: 'calcom',
+  // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of the real
+  // state system: perform one entry against Cal.com v2, refresh the root from it. Moved 2026-09-08.
+  protocol: '2',
+  refresh: { every: '5m', webhook: true, onDemand: { atMost: '30s' } },
+  stateSystem: { perform: performCalcomAction, refresh: syncCalcomFromRemote },
+  // the round trip: an event type, then a booking of it — the two things a scheduling account is made of
+  // the round trip is ONE write — an event type. A booking would have to name an event type, and the only
+  // one it could name statically is the twin's implicit default (7001), which is not the subject the kernel
+  // adopts; the reference trip below is where a booking gets made, against the event type this created.
+  roundTrip: { method: 'POST', path: '/v2/event-types', body: { title: 'Round trip', slug: 'round-trip', lengthInMinutes: 30 }, headers: { authorization: 'Bearer round-trip', 'cal-api-version': '2024-06-14' } },
+  // rule 5: a booking names the event type it is a booking OF; when the head adopts Cal.com's id for the
+  // event type, the kernel resolves the booking's field first
+  referenceTrip: { method: 'POST', path: '/v2/bookings', body: { start: '2026-09-09T11:00:00.000Z', eventTypeId: '{{evtId}}', attendee: { name: 'Round Trip', email: 'round@trip.test', timeZone: 'UTC' } }, headers: { authorization: 'Bearer round-trip', 'cal-api-version': '2024-08-13' } },
+  references: [{
+    type: 'booking', to: 'event_type',
+    key: (f: Record<string, unknown>) => (f.eventTypeId === undefined || f.eventTypeId === null ? undefined : `evt_${String(f.eventTypeId)}`),
+    adopt: (_f: Record<string, unknown>, vendorId: string) => ({ eventTypeId: vendorId.replace(/^evt_/, '') }),
+  }],
+  parityOrigin: 'http://twin',
+  shapeParity: 'held',
+  // The SAME object calcom-budget.ts declares at module load — one source of truth, so registering
+  // the pack and importing the connector can never arm two different ceilings.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  archetype: 'crud',
+  bin: 'world-calcom',
+  resources: ['booking', 'event_type', 'schedule', 'team', 'membership', 'webhook', 'slot'],
+  specSource: 'cal.com/docs/api-reference/v2 (hand-authored from the published v2 reference)',
+  description: 'Cal.com v2 REST twin — { status, data } envelope, stateful bookings/event-types/schedules/teams/webhooks, dashboard mirror.',
+  // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+  // 2026-08-31). Both credential-env spellings the vendor uses — CALCOM_* and the
+  // shorter CAL_* — stem here; there is no npm client to claim (Cal.com integrations call the v2
+  // REST surface directly), so `sdks` is deliberately absent rather than invented.
+  adoption: {
+    // Cal.com ships no Python SDK and no community client exists. The `Calcom` distribution on
+    // PyPI is an unrelated mathematics package - claiming it would map a maths dependency onto a
+    // scheduling twin.
+    pypi: [],
+    envStems: ['CALCOM', 'CAL'],
+  },
+  hosts: [{ host: 'api.cal.com' }],
+  // A scheduling client calls api.cal.com/v2/… — the dev proxy forwards '/v2/' to the twin
+  // and strips the absolute host so calls come back same-origin.
+  browserRouting: { apiPathPrefix: '/v2/', loaderHost: 'https://api.cal.com' },
+};
+// registered at import: the kernel learns the pack's state system (protocol 2)
+registerPack(pack);