@volter/twin-calcom 0.1.0

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,31 @@
+#!/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.js";
+import { createCalcomMirrorServer } from "./calcom-mirror-ui.js";
+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.js");
+    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/dist/src/index.d.ts

@@ -0,0 +1,11 @@
+export { handleCalcomTwinRequest, TWIN_API_VERSION, RESOURCE_TYPES } from './calcom-twin.js';
+export type { CalcomRequest, CalcomResponse } from './calcom-twin.js';
+export { createCalcomTwinFetch, createCalcomTwinServer, type CalcomTwinFetchOptions } from './calcom-server.js';
+export { calcomRequestForAction, liveCalcomExecute, mapBooking, mapEventType, pullCalcomAll, pullCalcomBookings, pullCalcomEventTypes, syncCalcomFromReal, } from './calcom-connector.js';
+export type { CalcomExecute, LiveCalcomOptions } from './calcom-connector.js';
+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.js';
+export type { CalcomBudgetErrorKind, CalcomBudgetOptions, CalcomBudgetReservation, CalcomBudgetSnapshot } from './calcom-budget.js';
+export { attendeeLabel, bookingTone, buildCalcomMirrorClient, calcomMirrorHtml, createCalcomMirrorServer, formatWindow, } from './calcom-mirror-ui.js';
+export type { CalcomRow } from './calcom-mirror-ui.js';
+import { type TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,69 @@
+// @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.js";
+export { createCalcomTwinFetch, createCalcomTwinServer } from "./calcom-server.js";
+export { calcomRequestForAction, liveCalcomExecute, mapBooking, mapEventType, pullCalcomAll, pullCalcomBookings, pullCalcomEventTypes, syncCalcomFromReal, } from "./calcom-connector.js";
+// 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.js";
+export { attendeeLabel, bookingTone, buildCalcomMirrorClient, calcomMirrorHtml, createCalcomMirrorServer, formatWindow, } from "./calcom-mirror-ui.js";
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack } from '@volter/world-core';
+import { CALCOM_RATE_BUDGET as RATE_BUDGET } from "./calcom-budget.js";
+import { performCalcomAction, syncCalcomFromRemote } from "./calcom-connector.js";
+export const pack = {
+    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) => (f.eventTypeId === undefined || f.eventTypeId === null ? undefined : `evt_${String(f.eventTypeId)}`),
+            adopt: (_f, vendorId) => ({ 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);

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@volter/twin-calcom",
+  "version": "0.1.0",
+  "description": "Local Cal.com twin — a faithful, stateful local Cal.com v2 API your scheduling integration talks to unmodified. Mirror, simulate, and fork. Built on @volter/world-core.",
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "fixtures",
+    "testing",
+    "api",
+    "scheduling",
+    "calcom",
+    "cal.com",
+    "bookings"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "client",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/calcom"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/calcom#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-calcom": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/calcom-budget.ts

@@ -0,0 +1,171 @@
+// Cal.com's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveCalcomExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
+// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger —
+// lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that module's
+// header for the full rationale AND for the honest list of what the guard does not guarantee (an
+// injected clock or ledger path still defeats it — it guards carelessness, not malice).
+//
+// ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────
+// A real ~4.5-DAY vendor lockout (Figma, 2026-07-25) happened because raw API calls were made
+// outside the pack's connector — no cache, no batching, no ceiling. Discipline only binds the code
+// that follows it; a BUDGET binds the code that does not.
+//
+// ── HOW THE CEILING WAS CHOSEN ──────────────────────────────────────────────────────────────
+// Cal.com DOES publish a scalar limit, so this models the real thing rather than guessing. From
+// https://cal.com/docs/api-reference/v2/introduction (read 2026-07-26): API-key authentication is
+// limited to 120 requests per minute (raisable on request); the same 120/minute is the default for
+// unauthenticated traffic.
+//
+// The `X-RateLimit-Limit` / `-Remaining` / `-Reset` response headers this guard reads are NOT on that
+// page — they are the conventional spelling, matched structurally by the kernel, and are read IF
+// PRESENT and never assumed. (§9 corrected an earlier line here that attributed them to the cited
+// page, 2026-07-26. Do not turn an observation into a citation.)
+//
+// The ceiling is 60 weighted units per 60s — 60 calls a minute at the default weight, HALF the
+// documented 120/minute, so the 60-second AVERAGE stays under the vendor's own even before any
+// weighting. It is more permissive than the kernel's undeclared fallback (30 calls/min) precisely
+// because 120/min is documented; without that number it would not be.
+//
+// It bounds the average; it does NOT pace (the kernel refuses, it never sleeps — see its header).
+// Cal.com's window is also a minute, so the shapes line up well here, but an intra-second burst can
+// still reach the vendor first; the backstop for that is the cooldown armed from the 429 /
+// `X-RateLimit-Remaining: 0`.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN (and what is a judgement call) ───────────────────────────────
+// Cal.com counts REQUESTS, so weight 1 is the faithful price and that is what reads get. Two
+// deliberate exceptions, both judgement calls rather than published costs:
+//   • `POST /bookings` costs 3. A booking is not a database row — it sends invitation e-mail,
+//     writes to the organiser's and attendees' real connected calendars, and fires webhooks. A
+//     runaway create loop is the failure mode with a HUMAN blast radius, not just a throttle.
+//   • `GET /slots` costs 2. Availability is computed across every connected calendar for a date
+//     range, so it is the expensive read, and it is the one a naive UI polls in a loop.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'calcom';
+
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const CALCOM_BUDGET_WINDOW_MS = 60_000;
+
+/**
+ * Weighted units allowed inside one window. 60/60s = 60 calls a minute at the default weight —
+ * half Cal.com's documented 120 requests/minute per API key.
+ */
+export const CALCOM_BUDGET_CEILING = 60;
+
+/** Seconds. A `Retry-After` above this means the key is throttled hard — fail loudly, don't sleep. */
+export const CALCOM_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
+export const CALCOM_CALL_WEIGHTS = {
+  /** `POST /bookings` — sends e-mail, writes real calendars, fires webhooks. Human blast radius. */
+  book: 3,
+  /** `GET /slots` — availability computed across every connected calendar. The expensive read. */
+  slots: 2,
+  /** Everything else: booking/event-type reads, updates, cancellations, schedules, me. */
+  other: 1,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, the only Cal.com-specific thing in the whole budget. */
+export const CALCOM_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: CALCOM_BUDGET_WINDOW_MS,
+  ceiling: CALCOM_BUDGET_CEILING,
+  defaultWeight: CALCOM_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: CALCOM_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    { match: '^POST /bookings$', weight: CALCOM_CALL_WEIGHTS.book },
+    { match: '^GET /slots', weight: CALCOM_CALL_WEIGHTS.slots },
+  ],
+  reason:
+    'Cal.com documents 120 requests/minute per API key (cal.com/docs/api-reference/v2/introduction, ' +
+    'read 2026-07-26; the same 120/min is the unauthenticated default, and it is raisable on ' +
+    'request). That page documents no response headers; the X-RateLimit-* names the guard reads are ' +
+    'the conventional spelling, read if present and never assumed. 60 weighted units / 60s is 60 ' +
+    'calls a minute — HALF the documented 120, so the 60s average stays ' +
+    "under the vendor's own. It is deliberately more permissive than the kernel's undeclared " +
+    'fallback (30 calls/min) BECAUSE 120/min is documented; without that number it would not be. ' +
+    'POST /bookings costs 3 (it sends e-mail, writes real connected calendars and fires webhooks — ' +
+    'a human blast radius, not just a throttle) and GET /slots costs 2 (availability computed across ' +
+    'every connected calendar, and the endpoint a naive UI polls in a loop) — judgement calls, not ' +
+    'published costs. The window bounds the 60s AVERAGE and does not pace; the 429 / ' +
+    '`X-RateLimit-Remaining: 0` cooldown is the backstop for a sub-second burst.',
+};
+
+// Declared at module load, so merely importing this module (which `calcom-connector.ts` does) is
+// enough to arm the real ceiling. `RateBudget` reads its policy live precisely so this declaration
+// takes effect the moment it lands, and constructing through the subclass below (which imports this
+// module) is what makes the ordering a non-issue in practice.
+declareRateBudget(VENDOR, CALCOM_RATE_BUDGET);
+
+/**
+ * Price one call. The key is `"<METHOD> <path>"` (the v2 path as the connector states it, without
+ * the `/v2` prefix the live executor adds) with the query string split off, so a rule can price by
+ * method without the kernel knowing anything about Cal.com. An unclassified endpoint still costs
+ * `defaultWeight` — nothing is ever free.
+ */
+export function calcomCallWeight(method: string, path: string): number {
+  const { bare, query } = splitQuery(path);
+  // UPPER-CASE the method: `fetch` normalizes a known lowercase method before sending, so
+  // `execute('post', …)` really does issue a POST and must be priced as one.
+  return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+
+/**
+ * `/v1/x?a=1` -> `{ bare: '/v1/x', query: { a: '1' } }`. Rules match the path; `whenQuery*` the query.
+ *
+ * NORMALIZED, because the anchored rules are otherwise trivially evaded (§9 finding, 2026-07-26):
+ * `fetch` upper-cases a known method before sending, so `execute('post', …)` issues a real WRITE
+ * that a `^POST ` rule would price as a read; and a trailing slash makes a path miss a `$` anchor
+ * while most routers treat it as the same endpoint. Both are input variations, not attacks, and
+ * either one silently voids the "expensive endpoints are priced up" claim the ceiling rests on.
+ */
+function splitQuery(path: string): { bare: string; query: Record<string, string> } {
+  const at = path.indexOf('?');
+  const query: Record<string, string> = {};
+  if (at !== -1) for (const [k, v] of new URLSearchParams(path.slice(at + 1))) query[k] = v;
+  const raw = at === -1 ? path : path.slice(0, at);
+  // Collapse a trailing slash, but never turn the root path into the empty string.
+  const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+  return { bare, query };
+}
+
+/** Where Cal.com's ledger lives. Token-keyed and cwd-independent by default (the limit is per API
+ *  key, so a cwd-scoped ledger would hand the same key a fresh allowance in every checkout,
+ *  worktree and CI matrix leg); pass `root` to opt into world-scoped accounting. */
+export function calcomBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+  // excess-property check only catches object literals) must not redirect this pack's ledger to
+  // another vendor's file.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options for Cal.com's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type CalcomBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * Cal.com's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof CalcomBudget` in `liveCalcomExecute` means "a budget that
+ * accounts against CAL.COM's ledger under CAL.COM's ceiling": another vendor's `RateBudget` (with
+ * its own, possibly larger, ceiling) is NOT assignable there.
+ */
+export class CalcomBudget extends RateBudget {
+  constructor(opts: CalcomBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as CalcomBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as CalcomBudgetErrorKind } from '@volter/world-core';
+export type CalcomBudgetReservation = RateBudgetReservation;
+export type CalcomBudgetSnapshot = RateBudgetSnapshot;