@odla-ai/cli 0.11.2 → 0.12.0

package/skills/odla/references/sdks.md

@@ -32,34 +32,46 @@ Worker/admin side: `init({ appId: tenantId, adminToken: env.ODLA_API_KEY, endpoi
 The publishable key is public; `provision` stores it (`setAuth`). Rules evaluate
 the signed-in user's JWT as `auth` — e.g. `auth.signedIn`, `auth.email`.
 
-## @odla-ai/calendar — read-only Google booking mirror
+## @odla-ai/calendar — live Google Calendar booking
 
 Calendar requires `services: ["db", "calendar"]` plus a `calendar.google`
-block. Normal provision opens a second, state-bound Google checkpoint issued by the platform for the
-human to grant `calendar.events.readonly`; Google tokens stay in the hosted
-connector and never become app/CLI secrets.
+block (`availabilityCalendars` per env, optional `bookingCalendar`). Normal
+provision opens a second, state-bound Google checkpoint issued by the
+platform; the human grants the booking scopes in a browser. Google tokens
+stay platform-side and never become app/CLI secrets. Google Calendar is the
+single source of truth — odla stores no calendar or attendee data, and
+nothing syncs.
 
 ```ts
 // Trusted Worker only — the admin key must never enter browser code.
-const calendar = initCalendar({
-  appId: env.ODLA_TENANT,
+const cal = initCalendar({
+  appId: env.ODLA_APP_ID,       // registry app id
+  env: env.ODLA_ENV,
   adminToken: env.ODLA_API_KEY,
-  endpoint: env.ODLA_ENDPOINT,
+  endpoint: env.ODLA_PLATFORM ?? "https://odla.ai",
 });
-const next = await calendar.bookings.next("member@example.com");
+const fb = await cal.availability.freeBusy({ timeMin, timeMax });
+const slots = computeBookableSlots(fb.busy, { from: timeMin, to: timeMax,
+  timezone, slotMinutes: 30 });
+const { booking } = await cal.actions.create(
+  { summary, startAt, endAt, attendees: [email], timezone, meet: true },
+  { idempotencyKey: `booking:${recordId}` }, // retry-safe; Google emails the invite
+);
 ```
 
-Browser code may query `$bookings` with `@odla-ai/db/client` only under an
-explicit view rule, and may import pure formatting helpers from
-`@odla-ai/calendar/client`. Do not import `initCalendar` or expose
-`ODLA_API_KEY` in a browser. Provider actions are not part of the read-only
-slice; a `calendar_not_connected`/501 action response is not a reason to widen
-credentials or request a Google token.
+Store the returned `eventId`/`meetUrl` on the app's own record;
+`actions.reschedule(eventId, …)` and `actions.cancel(eventId)` use it. A
+taken slot rejects with non-retryable `calendar_slot_unavailable` — refetch
+slots, don't retry. Browser code never calls `initCalendar` or the platform
+calendar routes; it hits the app's own endpoints and may import pure helpers
+(`computeBookableSlots`, formatters) from `@odla-ai/calendar/client`.
+`SlotPicker` from `@odla-ai/ui` renders the slot output directly.
 
 After consent, use `odla-ai calendar calendars --env dev --json` to discover
-selectable ids, edit the checked-in list, and optionally set a public per-env
-`bookingPageUrl` for Appointment Schedule embed/link mode. Re-provision, then verify with
-`calendar status --json` and `smoke`.
+selectable ids and edit the checked-in list. Re-provision, then verify
+`calendar status --env dev` reports `bookable: yes` and `smoke` passes. A
+pre-pivot read-only grant reports `degraded`/`calendar_reconsent_required`;
+re-run `calendar connect`.
 
 ## @odla-ai/ai — inference (Claude / GPT / Gemini)
 

package/skills/odla-migrate/SKILL.md

@@ -2,7 +2,7 @@
 name: odla-migrate
 description: >
   Migrate a static site (e.g. GitHub Pages) to odla on Cloudflare in safe
-  phases, then add a database, optional read-only calendar mirror, Clerk login, and AI. Use when the user wants to
+  phases, then add a database, optional Google Calendar booking, Clerk login, and AI. Use when the user wants to
   move a static or GitHub Pages site to Cloudflare/odla, or to add a backend,
   database, login/auth, or AI features to a static site via odla.
 runbookOrder:
@@ -49,10 +49,12 @@ installed skill at `../odla/SKILL.md` instead.
    approved o11y rotation with `--push-secrets` so the Worker is updated in the
    same run. If the final Wrangler transfer fails, use the CLI's printed
    non-rotating `secrets push` retry; never rotate again just to retry delivery.
-7. Existing calendar embeds are public links, not proof of a booking. Preserve
-   them via `bookingPageUrl`; never claim reconciliation until the read-only
-   mirror is connected and the app correlates `$bookings` deliberately. Google
-   OAuth tokens never enter the repo, CLI, or chat.
+7. Calendar booking is server-side only. `initCalendar` and the platform's
+   calendar routes authenticate with the app's full `ODLA_API_KEY` — never
+   call them from a browser; the browser talks to the app's own Worker
+   endpoints. An old public embed link is not a booking flow; preserve it via
+   `bookingPageUrl` only until the native flow is verified. Google OAuth
+   tokens never enter the repo, CLI, or chat.
 
 ## Phase state machine
 
@@ -108,7 +110,7 @@ Read the current phase's file when you enter it — not before:
 - references/phase-0-preflight.md
 - references/phase-1-static.md
 - references/phase-2-db.md
-- references/phase-2b-calendar.md (optional: preserve an embed and add authoritative read-only reconciliation)
+- references/phase-2b-calendar.md (optional: live Google Calendar booking — slots, create/reschedule/cancel through the app's own Worker)
 - references/phase-3-auth.md
 - references/phase-3b-user-sync.md (optional: mirror Clerk users into $users)
 - references/phase-4-ai.md

package/skills/odla-migrate/references/phase-2b-calendar.md

@@ -1,42 +1,130 @@
-# Phase 2b — Google Calendar (optional, read-only)
-
-Use this phase only when the existing site has a Google Appointment Schedule
-link/embed or locally reported meeting state. Keep the old booking experience
-working while adding an authoritative read-only mirror.
-
-Human obligations: review attendee-data retention and complete the second,
-server-issued Google consent page. They never paste an OAuth code or token.
-
-1. Inventory the old behavior. Distinguish a public appointment-page link from
-   actual event create/reschedule/cancel APIs. Do not promise more than exists.
-2. Require `npm view @odla-ai/calendar@0.1.1 version` to succeed, then install
-   `npm i --save-exact @odla-ai/calendar@0.1.1` as a runtime dependency. An
-   exact-version `E404` blocks this phase; do not substitute a git checkout or
-   another version. Add `"calendar"` beside
-   `"db"` in services and configure:
-   - `calendar.google.calendars.dev` (start with `"primary"`);
-   - optional summary/organizer/attendee match filters;
-   - deliberate `attendeePolicy: "full" | "hashed"`;
-   - the old public Appointment Schedule URL as `bookingPageUrl.dev` when
-     preserving the embed/link. It is public configuration, not a secret.
-3. Run `doctor`, then `provision --dry-run`. Show the human the calendars,
-   attendee policy, public booking page, and read-only scope.
-4. Run normal dev provision. After odla device approval, pause again while the
-   human grants Google `calendar.events.readonly`; the CLI follows initial sync.
-5. Run `calendar calendars --env dev --json`, refine the checked-in ids, and
-   re-provision. Verify `calendar status --env dev --json` and `smoke --env dev`.
-6. Put `initCalendar` only in trusted Worker code. Browser code may keep using
-   the public `bookingPageUrl`, query `$bookings` through explicit db rules, or
-   import pure helpers from `@odla-ai/calendar/client`. Never expose
-   `ODLA_API_KEY`.
-7. Replace self-reported meeting state only after an explicit, tested
-   application-to-booking correlation exists. A matching attendee email may be
-   sufficient for some apps; do not silently regress later workflow statuses.
-
-This slice cannot create, reschedule, or cancel Google events. A static picker
-continues to be Google's sealed UI; odla supplies configuration, mirror reads,
-and reconciliation.
-
-Gate: the old embed/link still works, status is healthy, the selected calendars
-match config, `$bookings` smoke succeeds, no Google credential exists in local
-files, and `MIGRATION.md` records the disclosure/correlation decision.
+# Phase 2b — Google Calendar booking (optional)
+
+Use this phase when the site should offer real scheduling: visitors pick a
+bookable slot and the app creates a live Google Calendar event — with a Meet
+link and an invitation email that Google itself sends. Google Calendar is the
+single source of truth; odla stores no calendar or attendee data. There is no
+sync, no mirror, and no `$bookings` namespace.
+
+Human obligations: complete the server-issued Google consent page in a
+browser (they never paste an OAuth code or token), and receive the test
+invitation email during verification.
+
+Boundary that shapes every step: `initCalendar` and the platform's calendar
+routes are **server-side only** — they authenticate with the app's full
+`ODLA_API_KEY`. Never call them from a browser; the browser talks only to
+this app's own Worker endpoints and may import pure helpers from
+`@odla-ai/calendar/client`.
+
+1. Require `npm view @odla-ai/calendar@0.2.0 version` to succeed, then
+   install `npm i --save-exact @odla-ai/calendar@0.2.0` as a runtime
+   dependency. An exact-version `E404` blocks this phase; do not substitute a
+   git checkout or another version.
+2. Add `"calendar"` beside `"db"` in services and author the config block —
+   booking rides the existing db key, so calendar adds no new secret:
+
+   ```js
+   calendar: {
+     google: {
+       availabilityCalendars: { dev: ["primary"] }, // 1–10 per env
+       bookingCalendar: { dev: "primary" },         // optional; defaults to first availability calendar
+       bookingPageUrl: { dev: null },               // optional legacy fallback link
+     },
+   },
+   ```
+
+3. Run `doctor`, then `provision --dry-run`; show the human the calendars and
+   the booking scopes. Run normal dev provision. Consent runs last: the CLI
+   prints/opens a state-bound Google URL and the human grants access in a
+   browser. If the platform connector reports a readiness 503
+   (`calendar_*_not_configured`), provision still completes and prints a
+   `calendar connect --env dev` resume hint — that gap is platform-operator
+   work, not yours. Then `calendar calendars --env dev --json` to refine
+   checked-in ids, and verify `calendar status --env dev` shows
+   `bookable: yes` (a pre-pivot read-only grant shows `degraded` /
+   `calendar_reconsent_required`; re-run `calendar connect`).
+4. Build the **slots endpoint** in the app's Worker — capability-gated like
+   every other route (a booking endpoint that ignores Phase 3 auth decisions
+   is a regression):
+
+   ```ts
+   import { initCalendar, computeBookableSlots } from "@odla-ai/calendar";
+
+   // GET /api/booking/slots
+   const cal = initCalendar({
+     appId: env.ODLA_APP_ID,
+     env: env.ODLA_ENV,
+     adminToken: env.ODLA_API_KEY,
+     endpoint: env.ODLA_PLATFORM ?? "https://odla.ai",
+   });
+   const fb = await cal.availability.freeBusy({
+     timeMin: Date.now(),
+     timeMax: Date.now() + 14 * 86_400_000,
+   });
+   const slots = computeBookableSlots(fb.busy, {
+     from: fb.timeMin,
+     to: fb.timeMax,
+     timezone: BOOKING_TIMEZONE,          // app-owned config, not user input
+     slotMinutes: 30,
+     businessHours: { days: [1, 2, 3, 4, 5], startHour: 9, endHour: 17 },
+     minNoticeMs: 24 * 3_600_000,
+   });
+   return Response.json({ slots, timezone: BOOKING_TIMEZONE });
+   ```
+
+   Business hours, slot length, notice, and buffers are this app's product
+   decisions — keep them in app config, and reject slot requests wider than
+   the window you offer.
+5. Build the **create endpoint** (`POST /api/booking`). Validate that the
+   requested slot is one this app offers (recompute from the same config),
+   then create — the platform re-validates availability under its booking
+   lease, so a stale slot cannot double-book:
+
+   ```ts
+   const { booking, duplicate } = await cal.actions.create(
+     {
+       summary: `Intro call — ${name}`,
+       startAt, endAt,
+       attendees: [email],
+       timezone: BOOKING_TIMEZONE,
+       meet: true,               // Meet link on the event and in the invite
+       // notify defaults true → Google emails the invitation
+     },
+     { idempotencyKey: `booking:${applicationId}` }, // your own stable record id
+   );
+   ```
+
+   Store the returned `booking.eventId` and `booking.meetUrl` on the app's
+   own record (its odla-db row) — that record is the app's only persistence;
+   attendee data lives in Google. On `calendar_slot_unavailable` (409,
+   non-retryable) return a "slot taken" response; the client refetches
+   `/api/booking/slots` and re-picks. On retryable
+   `calendar_booking_in_progress`, retry once after a short delay.
+6. Reschedule/cancel go through the stored id:
+   `cal.actions.reschedule(eventId, { startAt, endAt })` and
+   `cal.actions.cancel(eventId)` (idempotent) — expose them as app endpoints
+   gated to the record's owner. Attendees can also act through Google's own
+   invitation flows; treat Google as authoritative.
+7. Frontend. Two supported shapes:
+   - **`@odla-ai/ui` SlotPicker** — renders the slots response directly
+     (`{ slots, timezone, onSelect }`). On a non-framework static site use a
+     Preact island: a small entry that mounts `<SlotPicker>` into a div,
+     bundled with esbuild as an IIFE with `react`/`react-dom` aliased to
+     `preact/compat`, committed as a static asset next to the site's other
+     assets.
+   - **Plain fetch + buttons** — `fetch("/api/booking/slots")`, render times
+     with `formatBookingRange` from `@odla-ai/calendar/client`, POST the
+     chosen slot.
+   Either way the browser only ever talks to this app's Worker.
+8. If the old site had a Google Appointment Schedule embed/link, keep it
+   working via `bookingPageUrl` until the native flow is verified, then
+   retire it deliberately.
+
+Gate (live dev round-trip, all of it): a booking made through the site's own
+UI creates the event on the booking calendar with a Meet link; the Google
+invitation email arrives in the test attendee's inbox; a repeat POST with the
+same idempotency key returns `duplicate: true` (no second event); a taken
+slot returns 409 and the UI refetches slots; reschedule and cancel work via
+the stored `eventId`; zero attendee data is persisted anywhere except the
+app's own tenant record; no Google credential exists in local files; and
+`MIGRATION.md` records the booking-flow decision.

package/skills/odla-migrate/references/secrets-map.md

@@ -15,6 +15,9 @@
 | `o11y_…` (o11y ingest token) | wrangler secret `ODLA_O11Y_TOKEN` + `.odla/credentials.local.json` (0600) + `.dev.vars` | only if the app enables o11y; provision issues/reuses it and moves it alongside the db key; never a var, never chat |
 | `ODLA_ENDPOINT` / `ODLA_TENANT` / `ODLA_PLATFORM` / `ODLA_APP_ID` / `ODLA_ENV` | wrangler `vars` | not secrets; keep them set in every env block |
 | `ODLA_O11Y_ENDPOINT` / `ODLA_O11Y_SERVICE` | `.dev.vars` from provision or optional wrangler `vars` overrides | not secrets; public ingest defaults to `https://o11y.odla.ai` and `ODLA_APP_ID` when the token is present |
+| `GOOGLE_CALENDAR_CLIENT_ID` / `GOOGLE_CALENDAR_CLIENT_SECRET` / `CALENDAR_TOKEN_MASTER_KEY` | platform-operator Worker secrets on `odla-apps` | never part of a customer migration; never in chat, the repo, or the app's wrangler config — a readiness 503 (`calendar_*_not_configured`) means the operator sets these, not you |
+| Google calendar grant (OAuth tokens) | platform-side, sealed after human browser consent | the human clicks the server-issued consent URL; no code or token is ever pasted, and the CLI/app/repo never hold one |
+| calendar booking auth (app side) | none — rides the existing `ODLA_API_KEY` | enabling calendar adds NO new app secret; `initCalendar` uses the app's server db key, server-side only, never in a browser |
 
 System AI provider credentials are platform-owned and never enter a customer
 migration. `odla-ai security run` receives only app/run-bound role grants; do

package/skills/odla-migrate/references/troubleshooting.md

@@ -29,11 +29,22 @@ prints what it verified against.
 
 Cause: the `odla_dev_…` token expired (~24h) or the handshake was never
 approved.
-Fix: re-run `npx @odla-ai/cli provision` — it starts a fresh handshake; the
-matching existing account must be supplied with `--email` or
-`ODLA_USER_EMAIL`, then signs in, reviews, and approves the exact code at the
-printed URL. Never ask for a password or session token. Use `--no-open` in
-non-interactive shells if the browser launch misbehaves.
+Fix: re-run `npx @odla-ai/cli provision` — it resumes a still-pending
+handshake if one exists, else starts a fresh one; the matching existing
+account must be supplied with `--email` or `ODLA_USER_EMAIL`, then signs in,
+reviews, and approves the exact code at the printed URL. Never ask for a
+password or session token.
+
+## Handshake exits with code 75 / "handshake still pending"
+
+Cause: nobody approved within the wait cap (90s outside an interactive
+terminal; `--wait <seconds>` overrides). This is normal in agent shells and
+loses nothing — the handshake is persisted in `.odla/handshake.local.json`.
+Fix: relay the printed approval URL to the human **verbatim** (browser
+launch is best-effort — a sandboxed shell can report success with no tab
+appearing), wait for them to approve, then re-run the same command; it
+resumes the same code and collects the token. Do not loop unattended
+retries; each handshake lives ~10 minutes.
 
 ## `smoke` fails: missing credentials