application public active Verified 2026-04-26

Calendar

Cloudflare-native scheduling and bookings application with public booking pages, embeddable widgets, and a cross-app event feed.

Documentation Map

What It Is

Cloudflare-native scheduling and bookings application with public booking pages, embeddable widgets, and a cross-app event feed.

Canonical documentation for Topolo Calendar lives in `PlatformApplications/TopoloDocs`.

Use this repository for implementation only. Local product and operational docs have been retired in favor of the docs application.

See `TopoloDocs` for the runtime contract, auth boundary, permission schema, and failure modes.

Architecture

Owners: platform-experience

Source repos: PlatformApplications/TopoloCalendar

Dependencies: topolo-auth, topolo-chat, topolo-nexus, topolo-notify, applications-packages

Repo shape

  • PlatformApplications/TopoloCalendar/README.md
  • PlatformApplications/TopoloCalendar/index.html
  • PlatformApplications/TopoloCalendar/migration.config.ts
  • PlatformApplications/TopoloCalendar/migrations/
  • PlatformApplications/TopoloCalendar/package-lock.json
  • PlatformApplications/TopoloCalendar/package.json
  • PlatformApplications/TopoloCalendar/public/
  • PlatformApplications/TopoloCalendar/src/
  • PlatformApplications/TopoloCalendar/test/
  • PlatformApplications/TopoloCalendar/topolo.cloudcontrol.json
  • PlatformApplications/TopoloCalendar/tsconfig.json
  • PlatformApplications/TopoloCalendar/vite.config.ts
  • PlatformApplications/TopoloCalendar/vitest.config.mts
  • PlatformApplications/TopoloCalendar/worker-configuration.d.ts
  • PlatformApplications/TopoloCalendar/wrangler.jsonc

Runtime Surfaces

Hosts:

https://calendar.topolo.app https://topolo-calendar.topolo.workers.dev

No wrangler surface was discovered under the registered repo paths.

API Reference

Coverage: curated

Source: PlatformApplications/TopoloDocs/src/content/public/applications/calendar.mdx

Source exists in repo: yes

Calendar is a Worker + D1 + per-host Durable Object application. D1 is the system of record for hosts, event types, availability rules, bookings, reserved slot-hold audit rows, and external calendar sync metadata. CalendarHostDO (keyed by host handle) serialises concurrent booking attempts, owns short-lived in-memory slot holds, and caches availability windows. Confirmed bookings are written through to D1 before the DO acknowledges success; when TOPOLO_NOTIFY_URL and TOPOLO_NOTIFY_API_KEY are configured, Calendar emits `calendar.booking.confirmed` through @topolo/notifications after persistence so the host can be notified without rolling back bookings on notification failure. Meeting sessions remain owned by Topolo Chat; `chat_meeting` bookings call Chat's internal Calendar bridge and store the returned guest URL in `meetingProviderRef`, while external providers (Microsoft Teams, Google Meet, Zoom) store host-configured links or instructions until native Nexus provisioning is added. The public root renders the shared Topolo LandingPage from Auth-managed Calendar landing config. Public booking pages (/<handle>/<event-type>) and availability/hold/confirm endpoints are unauthenticated. The admin `/login` route renders the shared first-party Topolo login on the app origin, with embedded email/password sign-in enabled by the UI Kit first-party registry, login config reads through `/api/auth/*`, and one-time `sso_code` completion on `/auth/callback`. Initial `/app` boot retries one Auth cookie refresh after a 401 admin context response and redirects to `/login` after clearing local session state if refresh fails. Signed users without a Calendar host row complete the shared @topolo/onboarding first-run host setup flow before the admin workspace opens. Signed users with a host row enter the shared `TopoloAppShell`; Calendar supplies section metadata and workspace content while the UI Kit owns sidebar, header, account menu, mobile navigation, app-switcher mount, launcher shortcut behavior, dark/light toggle, sidebar collapse, command palette, and BugFix reporter controls. Calendar scopes raw workspace CSS to app-owned containers so shared portal overlays keep package-owned styling. The default weekly Calendar view is backed by `GET /api/admin/bookings`. Calendar exposes `GET /api/widget` with the shared `@topolo/sdk` widget response contract for TopoloOne live workspace. Admin endpoints require bearer tokens validated by @topolo/auth-middleware against srv_topolo_calendar and enforce route-level Calendar service permissions, accepting Auth's service-scoped canonical grant form such as `srv_topolo_calendar.host:read`. The embed SDK (@topolo/calendar-embed) supports iframe, popup, and floating bubble modes with a @topolo/calendar-react wrapper; embed origins are validated against the service manifest allowlist.

App API page: /reference/apps/topolo-calendar

This system currently relies on a curated or README-derived contract surface instead of a source-controlled OpenAPI spec.

Auth and Permissions

Depends on Topolo Auth: yes

Service IDs:

srv_topolo_calendar

API key scopes

api_keys.write

Manage Calendar machine credentials

Resource pattern: none

availability.read

Read weekly availability rules and overrides

Resource pattern: none

availability.write

Update weekly availability rules and overrides

Resource pattern: none

bookings.read

List and inspect bookings

Resource pattern: none

bookings.write

Cancel or reschedule bookings

Resource pattern: none

embed.issue

Issue embed tokens for third-party websites

Resource pattern: none

event_types.read

List event types

Resource pattern: none

event_types.write

Create, update, or deactivate event types

Resource pattern: none

external_sync.write

Connect or revoke external calendar sync sources

Resource pattern: none

host.read

View host profile and handle

Resource pattern: none

host.write

Create or update host profile, handle, and timezone

Resource pattern: none

Service permissions

api_keys:write, availability:read, availability:write, bookings:read, bookings:write, embed:issue, event_types:read, event_types:write, external_sync:write, host:read, host:write

Data Ownership

No storage bindings were derived from wrangler configuration.

Queues / Cron / Workflows

Queue bindings:

No queue bindings were detected.

Cron triggers

No cron triggers were detected.

Workflow signals

No explicit queue/workflow script or cron signal was discovered.

Environment Variables and Bindings

Environment variables:

No environment variables were derived from wrangler configuration.

All wrangler bindings

No bindings were derived from wrangler configuration.

Deployments

Deployment environments: default only or not declared

Routes: workers.dev or Pages-only delivery

Observability enabled: no explicit setting found

Build and deploy commands

  • build — PlatformApplications/TopoloCalendar/package.json :: vite build
  • deploy — PlatformApplications/TopoloCalendar/package.json :: wrangler deploy
  • deploy:staging — PlatformApplications/TopoloCalendar/package.json :: env -u CLOUDFLARE_API_TOKEN CLOUDFLARE_ACCOUNT_ID=4f4e1c69a3830946f9fea7b1eb7531ac wrangler deploy --env staging

Failure Modes

  • No wrangler.toml surface was discovered under the registered repo paths.

Debugging Runbooks

Start with these entrypoints:

  • PlatformApplications/TopoloDocs/src/content/public/applications/calendar.mdx
  • PlatformApplications/TopoloCalendar/README.md
  • PlatformApplications/TopoloCalendar/package.json

Change Log / Verification

Lifecycle: active

Last verified: 2026-04-26

Any code change to this system is expected to update the canonical docs in PlatformApplications/TopoloDocs and refresh the verification date.