frontpage-host 0.3.18 → 0.3.20

package/AGENTS.md

@@ -119,14 +119,14 @@ Sites are Astro 6 + Tailwind v4. More detail: `frontpage help site-building` or
 ## Modules & articles
 
 - Forms: `data-fp-form` markup in pages + `frontpage modules` for enable/config. No submit JS / honeypot / `action`. Do not put a CRM webhook or token in HTML.
-- Connect-once modules: Store Stripe connect is `frontpage payments connect`. `--no-open` for CI. `request-setup` remains valid when you want the **editor amber bar** instead. Payments and Store share one Stripe account. Pause Payments through its availability action; generic module writes cannot bypass invoice/recurring stop rules. Auto-active modules (forms/callbar/…) need markup, not request-setup. Typed settings: `frontpage modules callbar|forms|booking|signups get|set` (forms set needs `--instance`; do not target `default`). Form destinations (HubSpot / Pipedrive / Privyr): connect once, then attach each form. `frontpage modules forms destinations|connect-destination|attach-destination|detach-destination|remove-destination --yes|request-destination-setup`. Token write is **admin**; `request-destination-setup` lights the editor amber bar (**editor** key). Do not use `request-setup forms` for a CRM (no-op). Connecting does not attach every form. Privyr: paste the Incoming Webhook URL from Automations → Lead Sources → Webhooks (`https://www.privyr.com/api/v1/incoming-leads/…`), not a token and not Outgoing Webhooks. HubSpot: Development → Keys → Service keys or Development → Legacy apps → Auth → Show token. Pipedrive: profile → Company settings → Personal preferences → API. Full docs: https://frontpage.host/developers/modules#forms-destinations. `frontpage modules <key>` prints that key's CLI usage (exit 2). Index: https://frontpage.host/developers/modules. Store: https://frontpage.host/developers/store
+- Connect-once modules: Store Stripe connect is `frontpage payments connect`. `--no-open` for CI. `request-setup` remains valid when you want the **editor amber bar** instead. Payments and Store share one Stripe account. Pause Payments through its availability action; generic module writes cannot bypass invoice/recurring stop rules. Auto-active modules (forms/callbar/…) need markup, not request-setup. Typed settings: `frontpage modules callbar|forms|signups get|set` (forms set needs `--instance`; do not target `default`). Form destinations (HubSpot / Pipedrive / Privyr): connect once, then attach each form. `frontpage modules forms destinations|connect-destination|attach-destination|detach-destination|remove-destination --yes|request-destination-setup`. Token write is **admin**; `request-destination-setup` lights the editor amber bar (**editor** key). Do not use `request-setup forms` for a CRM (no-op). Connecting does not attach every form. Privyr: paste the Incoming Webhook URL from Automations → Lead Sources → Webhooks (`https://www.privyr.com/api/v1/incoming-leads/…`), not a token and not Outgoing Webhooks. HubSpot: Development → Keys → Service keys or Development → Legacy apps → Auth → Show token. Pipedrive: profile → Company settings → Personal preferences → API. Full docs: https://frontpage.host/developers/modules#forms-destinations. `frontpage modules <key>` prints that key's CLI usage (exit 2). Index: https://frontpage.host/developers/modules. Store: https://frontpage.host/developers/store
 - Google reviews: platform nodes only (`data-fp-google-reviews` / `data-fp-google-ask` + required `data-fp-requires="google_reviews"`). `data-layout` is `feed` (default), `badge`, or `link`. Never invent stars, quotes, a 1–10, or a Maps URL. Do not pick a Place ID via Autocomplete and do not write `placeId` through `modules config`. Owner-supplied Place ID / Maps URL: `frontpage modules google_reviews connect --place-id …` or `--maps-url …` (server resolves + seeds). Curation: `list-reviews`, `hide --id`, `show --id`, `set-stars`, `set-sort`, `set-weight`, `reset-weights`, `refresh`, `disconnect`. Usage: `frontpage modules google_reviews`. Docs: https://frontpage.host/developers/modules/google-reviews. Ask-widget scores: `frontpage inbox google_reviews`.
 - Articles needs no setup. `frontpage articles create-section --label "Blog" --route blog` creates an active section. Use `archive-section --section blog` / `restore-section --section blog` to turn it off / on. Draft articles stay unpublished. Bodies use sync under `content/` or `articles content get|set`. The section landing is an owned `src/pages/<section>/index.astro`. Frontpage manages article routing; do not read or edit the managed routing file.
 - Migrate a folder into Articles: prefer `frontpage prompt "migrate … into articles"` — do not invent a mass delete+write migration.
 - Extensions: `frontpage extensions`; if LOCKED on plan, do not fake charts/etc.
 - Media: `frontpage media upload <file>` — images/PDF ≤25 MB, video (MP4/WebM/MOV) ≤50 MB, SVG/text ≤4 MB (sanitizing proxy). Human output prints `sitePath:` first (use that in markup — never raw blob hosts), then optional `url:`. Optional `?w=` on rasters only. **Text/CSV** uploads are inline only — **not** added to the media library and **cannot** be linked via `/__media` (`media upload --json` omits full `content`; use `inbox … --csv` for submission exports).
 - Generated images: `frontpage images generate --prompt "…"` `[--count N]` — one prompt, 1–4 variations of that same picture. Prints `sitePath:` first. Counts against AI $ and storage. Flag-off environments return 404 (`Image generation is not enabled.`). Do not call xAI / Imagine yourself.
-- Analytics: bare `frontpage analytics` = dashboard; also `summary|query|funnel|timeseries|compare|sql` for structured reads (SQL is guard + RLS site-scoped).
+- Analytics: bare `frontpage analytics` = dashboard; also `summary|query|funnel|timeseries|compare|sql` for reads. Use type=pageview when counting views; count alone includes every matching event. Custom SQL is parsed/allowlisted and site-scoped by RLS; it rejects unrelated tables, unsafe functions/types, recursive CTEs and unsupported syntax. Keep SQL dates inside SQL (there is no SQL --days flag). Limits: 4000 input characters, five seconds, 500 returned rows. Metric definitions and supported examples: https://frontpage.host/developers/analytics. MCP uses separate structured tools and excludes raw SQL.
 - People CRM: `frontpage people list|get|add|set|note|rm-note|follow-up|hide|unhide|export`. Site-scoped person graph (email or phone). Inbox stays the raw ledger. Hide is not forget. List export is CSV (not a one-person legal dump). Full guide: https://frontpage.host/developers/people
 - Routines: `frontpage routines list|get|add|set|pause|resume|rm|run|runs`. One routine can hold several hours and several days. `8am,12pm,4pm` on `tue,thu,fri` stores hours `[8, 12, 16]` and weekdays `[2, 4, 5]`. Ask for an IANA timezone. Do not guess UTC. Full guide: https://frontpage.host/developers/routines
 - Store catalog: `frontpage store items|variants|categories|settings|orders|import`. Integer cents only (`$49.99` is `4999`). `--price-cents` is the usual cost. Optional `--discount-cents` is the sale the buyer pays (must be lower). End a sale with `frontpage store variants update <itemId> --id <variantId> --clear-discount`. This sends discountPriceCents: null and keeps the regular price. Omit both sale flags on update to preserve the current sale. Do not combine --clear-discount with --discount-cents; 0 means free, not removal. Read the item back to verify. Stock: use --stock unlimited on variants update or items stock --set unlimited; zero is sold out. Omit stock on update to preserve it. Rename option types or return to one SKU with items update --file, preserving the surviving variant’s regular price, sale and stock. Create a category before assigning it. Photos are a site path `/__media/uploads/<this-slug>/…` or an HTTPS URL already saved on this site. `frontpage payments connect [--no-open]` opens Frontpage then Stripe. Store always uses Add to cart. Use Payments for standalone Pay now and invoices. Service fee is `settings set-checkout-fee`. The cart starts hidden. Product pages are the default: unless they said they do not want product pages, write one `src/pages/products/item.astro` (or shop) with `data-fp-store-product`. If they said no, skip that file and do not bind `href` or `url`. Description is a small markdown subset; product-page bind is `<div data-fp-store-bind="description">`. Every store control carries `data-fp-requires="store"`. Do not bake titles or prices. Full guide: https://frontpage.host/developers/store
@@ -317,3 +317,7 @@ prepared copy over its exact original. Different uploads with the same display n
 remain distinct. Existing URLs and published videos are not converted automatically.
 Upgrade the CLI to receive upload-time preparation. Source path and access denials
 remain errors; they do not become original-file fallback successes.
+
+## Native Booking
+
+Read [BOOKING.md](./BOOKING.md) before using `frontpage modules booking`. Use native settings, types/forms, members/spaces, availability, reservations and recurring blocks. Do not send new bookings through the old generic module collector. Every write requires a stable request key; updates require the current revision. Consent and private calendar-link entry stay with the human in Workspace → Connections. Ordinary owned connection management and self-hours share the workspace actions; setup requests appear in the editor status bar and overview.

package/BOOKING.md

@@ -0,0 +1,79 @@
+# Bookings
+
+Use `frontpage modules booking` to read the command list. Booking settings, forms, availability and reservations use the same service as Workspace → Bookings. The CLI uses the site's existing plan and membership rules. Admins configure settings, members/spaces and booking types. Editors manage bookings and blocks. Viewers read availability and manage their own appointment hours and authorized calendar operations through the same shared actions. Consent, private calendar-link entry and private event content require the human workspace flow.
+
+Start with `frontpage modules booking status --site SITE --json`. An admin must set the business time zone and availability, publish a booking type with assigned members or spaces, and turn online booking on. A member must already hold a Frontpage account and have joined the site. Use the existing Viewer role when inviting someone who only needs personal availability and calendar connections. Workspace Booking tabs are Calendar, Bookings, Booking types, Spaces, Connections and Settings. Choose joined site members directly in a type; there is no Booking Members screen. Each member sets My appointment hours in Settings for this site. Spaces has its own editor.
+
+## Commands
+
+| Command after `frontpage modules booking` | Purpose |
+| --- | --- |
+| `status`, `get`, `set` | Read setup/status, read settings, save complete settings. |
+| `resources list`, `resources save`, `resources catalog` | Read or save internal joined-member availability records and spaces. Creating an existing member resolves its shared record without overwriting hours. |
+| `types list`, `types save`, `types catalog` | Read or save booking types and their customer questions. |
+| `calendar` | Read a bounded calendar range, with optional member/space filters. |
+| `availability` | Read real time slots or stay dates for a published type. |
+| `bookings list`, `bookings get` | Read a page or the current booking details/revision. |
+| `bookings create`, `accept`, `decline`, `cancel`, `withdraw`, `reschedule` | Create or change a reservation. `withdraw` cancels the customer's request; it does not withdraw just a proposed date change. |
+| `blocks get`, `blocks save`, `blocks remove` | Read, save or remove timed, full-day or recurring blocks. |
+| `members list` | Page joined site members as an admin; no invitations or new people. |
+| `hours get`, `hours set` | Read/save the current member's appointment hours. |
+| `activation set` | Pause, resume or archive native Booking with a current revision. |
+| `accounts list`, `accounts calendars`, `accounts disconnect` | Read own accounts/calendar choices or explicitly disconnect an account. |
+| `calendars get`, `calendars save` | Read current calendar selection or save its binding/destination. |
+| `connections list`, `connect`, `save`, `refresh`, `disconnect` | Read safe status, request secure setup, or perform ordinary owned operations. |
+| `setup list`, `setup dismiss` | Read or dismiss a pending human request. |
+| `event-open --file event.json` | Return an owner-authenticated workspace URL; no private event fields. |
+
+Use `--site SITE` on every example when the CLI has no selected site. Read operations accept `--limit 1..100` and `--before CURSOR` where supported. Keep the same list filters when using a returned `nextCursor`. Booking lists also accept `--search TEXT` and `--status requested|confirmed|cancelled|declined|expired`.
+
+Calendar and availability use `--from ISO_INSTANT --to ISO_INSTANT`, at most 31 days per call. Calendar uses optional `--member ID --space ID`. Availability also needs `--type TYPE_ID`; use `--booking BOOKING_ID` when changing that existing reservation; stays can use `--arrival YYYY-MM-DD`. Returned slots contain exact instants; do not invent a time or infer availability from an empty/error response.
+
+## Writes and retries
+
+Save/create/reschedule commands take `--file value.json` containing the complete native value, under 60 KB. Updates also need `--id ID --revision N`; initial settings use `--revision 0`. Read current values before editing. Keep only input fields, not IDs, timestamps, service state or other response metadata. A type owns its own extra form questions; phone is not a site-wide requirement. Name and email remain required.
+
+Every write needs `--request-key UNIQUE_KEY` (8–128 letters, digits, `_` or `-`). Reuse the exact key and file after a timeout. Changed input needs a new key. A revision/availability conflict needs fresh reads and user review; do not blindly retry with a newer revision.
+
+```bash
+frontpage modules booking get --site SITE --json
+frontpage modules booking set --site SITE --file settings.json --revision 0 --request-key setup-20261027
+frontpage modules booking resources list --site SITE --json
+frontpage modules booking types list --site SITE --limit 50 --json
+frontpage modules booking availability --site SITE --type TYPE_ID --from 2026-11-02T00:00:00Z --to 2026-11-03T00:00:00Z --json
+frontpage modules booking bookings create --site SITE --file booking.json --request-key request-20261027 --json
+frontpage modules booking bookings get --site SITE --id BOOKING_ID --json
+frontpage modules booking bookings accept --site SITE --id BOOKING_ID --revision 1 --request-key accept-20261027 --json
+```
+
+Appointments use `typeId`, `start`, `customer:{name,email}` and `answers:{}`. Stays use `arrival` and `departure` instead of `start`; the type sets check-in/check-out times and night limits. Optional `memberResourceId` and `spaceResourceId` select preferences from real resources. Rescheduling keeps the booking's saved type, customer and answers. An approval request holds availability until accepted, declined or expired; it is not a confirmed booking. A proposed change can hold new dates while retaining the confirmed original.
+
+A recurring block update/removal adds `--scope this|following|all` and the exact returned `--occurrence YYYY-MM-DDTHH:mm` when required. Times follow the block's IANA time zone; full-day ends are exclusive. A single occurrence can change its title and dates, including full-day or timed spans. Its members/spaces and repeat schedule stay with the series; choose the entire series to change them. Don't guess an occurrence from the currently displayed week.
+
+## Connections and the website
+
+Calendar consent stays with the person connecting the account. Never put OAuth credentials or private iCal URLs into CLI files, prompts or agent tools. Follow the returned workspace link and connect there. Each member controls their own calendars; admins can connect shared calendars to spaces. Hard refresh permits two distinct attempts per calendar in a rolling 15 minutes, including failures. The same retry identity does not spend another attempt. The dispatcher runs every five minutes; healthy reconciliation targets 15 minutes, plus scheduling delay and provider backoff.
+
+Google and Outlook import busy periods and can receive Frontpage-owned confirmed events when the owner grants write access. Private event details never reach visitors. iCal imports busy times for appointments or stays under either confirmation policy; it does not send bookings back or provide a real-time double-booking guarantee.
+
+Website authors use the platform Booking runtime and `data-fp-booking` containers. The agent controls surrounding HTML and CSS; the service controls forms, availability, validation, email verification and reservation state. Read the Booking module docs and use their exact starter markup. Do not use the old `data-fp-form="booking"` collector for new forms. Customers review the booking, verify their email and submit; verification creates no inventory hold. A customer management link opens a dedicated page. Viewing a link never accepts, declines or cancels a booking.
+
+Private external event details are available only to the connecting human in the workspace Calendar. CLI/agent calendar output remains busy times only; there is no CLI command for private event content.
+
+## Shared setup and connection operations
+
+All commands above call the same Booking actions as the workspace and internal agent. Source command aliases and write requirements come from the generated shared contract. Publishing this package is a separate release step; a local source build is not proof of npm availability.
+
+`hours set --file hours.json` takes `{"hours":[{"day":1,"start":"09:00","end":"17:00"}]}` with the current revision/key. The server infers the current user; no target-user flag exists. `activation set --file state.json` takes `{"state":"active"}` (also `disabled` or `archived`). `types save --member-users USER_ID,USER_ID --file type.json` resolves joined members in the shared operation; the complete type value must use `memberResourceIds:[]`. Omit the flag to keep the resource-ID contract. An empty `--member-users ''` clears assigned members.
+
+`connections connect --file setup.json --request-key KEY` takes `{"provider":"google","ownership":"personal"}`. Providers are `google`, `outlook`, `ical`; iCal accepts `ownership:"personal"` for your own member or `ownership:"shared"` for admin-managed spaces. Optional `action:"reconnect"` requires the existing `connectionId`. An admin may name `responsibleUserId` to request their joined member's consent; the admin does not receive that member's authorization. Follow the returned workspace URL. The same request appears in the editor status bar and workspace overview. An account-only OAuth return is not complete until calendar selection/binding saves. Failures retain a truthful next step; repeating the same request does not create duplicate notices. `setup dismiss --id REQUEST_ID --revision GENERATION --request-key KEY` hides the request; it does not disconnect or mark connected.
+
+`accounts calendars --id ACCOUNT_ID` returns owned provider calendar choices. `calendars save --record-kind account --id ACCOUNT_ID --file selection.json --request-key KEY` selects one, using `calendarId`, `label`, `resourceIds`, `receivesBookings` and `ownership`. Editing uses `--record-kind calendar --id CONNECTION_ID --account ACCOUNT_ID --revision N`. Use `--setup REQUEST_ID` when completing a returned connection request. Provider identity and consent remain protected by the server.
+
+`connections save` updates an iCal connection's label/resourceIds with the current revision. `connections refresh --record-kind feed|calendar --id CONNECTION_ID --revision N --request-key KEY` executes the server-limited refresh, not a link-only request. Disconnect uses the same record kind/ID/revision plus `--file disconnect.json` containing `{"confirmed":true,"removeBinding":true}`. `accounts disconnect` uses the account ID/revision and the same explicit value. Normal disconnect uses `true` to stop checking that source. Explicit `removeBinding:false` keeps dependent availability unavailable until reconnected. Existing bookings remain. Never infer that requesting refresh means sync succeeded.
+
+Only consent/private-link entry uses the secure human handoff. Never pass OAuth codes/tokens or private export URLs through files, CLI arguments or chat. `event-open` takes `{"detailId":"OPAQUE_ID_FROM_OWNER_CALENDAR"}`; opening its URL still requires the connecting human. All ordinary reads preserve role redaction; all mutations preserve stable keys, revisions and the existing two-refreshes-per-15-minutes server allowance.
+
+Only the booking type chooses instant confirmation or manual acceptance of customer requests; connecting a calendar never changes that choice. Successful imports revalidate every 15 minutes even when the source advertises a longer cache lifetime. Connection summaries include safe `health` with `status`, `label`, `message` and `usable`. Fresh last-good busy times still apply during refresh or a temporary failure; missing, revoked, disconnected, stale (30 minutes) or uncovered imports keep dependent availability unavailable. Retries keep existing backoff and Retry-After. Imported event titles and private feed URLs never appear in these summaries.
+
+Repeated Connect for your existing Google/Microsoft account returns its current calendar choices without replacing its grant or selections. Use Reconnect on the existing account to renew permissions.

package/README.md

@@ -150,3 +150,22 @@ prepared copy over its exact original. Different uploads with the same display n
 remain distinct. Existing URLs and published videos are not converted automatically.
 Upgrade the CLI to receive upload-time preparation. Source path and access denials
 remain errors; they do not become original-file fallback successes.
+
+Bookings: read packaged [BOOKING.md](./BOOKING.md) and `frontpage modules booking`. Native commands share workspace validation, per-type forms, resource availability, revisions and stable request keys. Calendar consent and private calendar-link entry use a human handoff; ordinary authorized refresh/hours/connection operations run through shared actions; never pass private feed links or OAuth secrets through CLI/agent inputs.
+
+## Analytics
+
+`frontpage analytics` reads the existing site-wide dashboard. Use `query`,
+`summary`, `timeseries`, `funnel` and `compare` for structured reports; page filters
+can select one recorded path. For pageview counts include `type: pageview`: a
+plain count includes all matching events. Presets are 1, 7, 30 and 90 days; bare
+dashboard defaults to 7, structured operations to 30. Funnels report session
+overlap, not strictly ordered events.
+
+Custom `analytics sql` uses PostgreSQL parsing, reporting-object allowlists, RLS
+and a read-only transaction. Put dates inside SQL. Input is capped at 4000
+characters, database time at five seconds and returned rows at 500. Unrelated
+tables, scope-changing functions, custom types and unsupported syntax reject.
+Use the [analytics reference](https://frontpage.host/developers/analytics) for
+metric definitions and examples. The internal agent and MCP expose full
+page-detail report tools; this release adds no CLI command. MCP excludes SQL.

package/dist/commands/modules.js

@@ -1,7 +1,8 @@
+import { runBooking } from "../modules/booking.js";
 import { resolveSlug } from "../site.js";
 import { EXIT_OK, exitCodeForError, v1Get, v1Post } from "../http/client.js";
 import { takeFlag } from "../argv.js";
-import { emitUsage } from "../runtime.js";
+import { emitErr, emitUsage } from "../runtime.js";
 import { formatModuleUsage, formatModulesIndex, formatPaymentsIsNotAModule, formatShopIsNotAModule, isCliModuleAction, isDocumentedModuleKey, isGenericModuleVerb, } from "../modules/commands.js";
 import { runGoogleReviews } from "../modules/google_reviews.js";
 import { isTypedConfigCliKey, runTypedConfig } from "../modules/typed_config.js";
@@ -48,6 +49,8 @@ export async function runModules(args) {
             if (isCliModuleAction(peekedKey, peekedAction)) {
                 const { slug } = await resolveSlug(args);
                 const extraFlags = positionalArgs(args).slice(2);
+                if (peekedKey === "booking")
+                    return await runBooking(slug, peekedAction, extraFlags);
                 if (peekedKey === "google_reviews") {
                     return await runGoogleReviews(slug, peekedAction, extraFlags);
                 }
@@ -165,6 +168,9 @@ export async function runModules(args) {
         ].join("\n"));
     }
     catch (err) {
+        // Keep Booking domain codes, retry advice and field feedback through the outer command too.
+        if (positionalArgs(args)[0] === "booking")
+            return emitErr("modules booking", err);
         console.error(err instanceof Error ? err.message : String(err));
         return exitCodeForError(err);
     }

package/dist/http/client.d.ts

@@ -8,6 +8,11 @@ export type V1Envelope = {
         code?: string;
         message?: string;
         requestId?: string;
+        details?: {
+            bookingCode?: string;
+            retryable?: boolean;
+            fieldErrors?: Record<string, string>;
+        };
     };
 };
 export declare class CliHttpError extends Error {
@@ -16,9 +21,14 @@ export declare class CliHttpError extends Error {
     readonly code?: string;
     /** v1 envelope requestId when the API returned one (§CLI Phase D). */
     readonly requestId?: string;
+    bookingDetails?: {
+        bookingCode: string;
+        retryable: boolean;
+        fieldErrors?: Record<string, string>;
+    };
     constructor(message: string, exitCode: number, status: number, code?: string, requestId?: string);
 }
-/** Map a non-OK v1 response into CliHttpError (shared by JSON + multipart clients). */
+/** Booking preserves its existing service error contract without changing other CLI failures. */
 export declare function httpErrorFromV1(status: number, parsed: V1Envelope, fallbackMessage?: string): CliHttpError;
 export declare function apiBase(): string;
 /** Bearer header for raw fetch (e.g. Blob client-token exchange). */

package/dist/http/client.js

@@ -14,6 +14,7 @@ export class CliHttpError extends Error {
     code;
     /** v1 envelope requestId when the API returned one (§CLI Phase D). */
     requestId;
+    bookingDetails;
     constructor(message, exitCode, status, code, requestId) {
         super(message);
         this.name = "CliHttpError";
@@ -24,7 +25,7 @@ export class CliHttpError extends Error {
     }
 }
 /** Map a non-OK v1 response into CliHttpError (shared by JSON + multipart clients). */
-export function httpErrorFromV1(status, parsed, fallbackMessage) {
+function baseHttpErrorFromV1(status, parsed, fallbackMessage) {
     const message = parsed.error?.message ?? fallbackMessage ?? `Request failed (${status})`;
     const code = parsed.error?.code;
     const requestId = parsed.error?.requestId;
@@ -55,6 +56,13 @@ export function httpErrorFromV1(status, parsed, fallbackMessage) {
     }
     return new CliHttpError(message, EXIT_UNEXPECTED, status, code, requestId);
 }
+/** Booking preserves its existing service error contract without changing other CLI failures. */
+export function httpErrorFromV1(status, parsed, fallbackMessage) {
+    const error = baseHttpErrorFromV1(status, parsed, fallbackMessage), details = parsed.error?.details;
+    if (details && typeof details.bookingCode === "string")
+        error.bookingDetails = { bookingCode: details.bookingCode, retryable: details.retryable === true, ...(details.fieldErrors ? { fieldErrors: details.fieldErrors } : {}) };
+    return error;
+}
 export function apiBase() {
     const fromEnv = process.env.FRONTPAGE_API_BASE?.replace(/\/$/, "");
     if (fromEnv)

package/dist/modules/booking-contract.generated.json

@@ -0,0 +1,130 @@
+{
+    "groups": {
+        "resources": {
+            "list": "resources_list",
+            "save": "resource_save",
+            "catalog": "resource_catalog"
+        },
+        "members": {
+            "list": "members_list"
+        },
+        "hours": {
+            "get": "appointment_hours_get",
+            "set": "appointment_hours_save"
+        },
+        "activation": {
+            "set": "activation_save"
+        },
+        "accounts": {
+            "list": "provider_accounts_list",
+            "calendars": "provider_calendars_list",
+            "disconnect": "provider_account_disconnect"
+        },
+        "calendars": {
+            "get": "provider_calendar_get",
+            "save": "provider_calendar_save"
+        },
+        "setup": {
+            "list": "setup_requests_list",
+            "dismiss": "setup_request_dismiss"
+        },
+        "types": {
+            "list": "types_list",
+            "save": "type_save",
+            "catalog": "type_catalog"
+        },
+        "bookings": {
+            "list": "bookings_list",
+            "get": "booking_get",
+            "create": "booking_create",
+            "accept": "booking_accept",
+            "decline": "booking_decline",
+            "cancel": "booking_cancel",
+            "withdraw": "booking_withdraw",
+            "reschedule": "booking_reschedule"
+        },
+        "blocks": {
+            "get": "block_get",
+            "save": "block_save",
+            "remove": "block_remove"
+        },
+        "connections": {
+            "list": "connections_list",
+            "connect": "connect_request",
+            "refresh": "connection_refresh",
+            "save": "connection_save",
+            "disconnect": "connection_disconnect"
+        }
+    },
+    "direct": {
+        "status": "status",
+        "get": "settings_get",
+        "set": "settings_save",
+        "calendar": "calendar",
+        "availability": "availability",
+        "event-open": "event_open"
+    },
+    "writes": [
+        "settings_save",
+        "resource_save",
+        "type_save",
+        "booking_create",
+        "booking_accept",
+        "booking_decline",
+        "booking_cancel",
+        "booking_reschedule",
+        "booking_withdraw",
+        "block_save",
+        "block_remove",
+        "connection_refresh",
+        "connect_request",
+        "activation_save",
+        "appointment_hours_save",
+        "provider_calendar_save",
+        "provider_account_disconnect",
+        "connection_save",
+        "connection_disconnect",
+        "setup_request_dismiss"
+    ],
+    "actions": [
+        "status",
+        "settings_get",
+        "settings_save",
+        "resources_list",
+        "resource_save",
+        "types_list",
+        "type_save",
+        "calendar",
+        "availability",
+        "bookings_list",
+        "booking_get",
+        "booking_create",
+        "booking_accept",
+        "booking_decline",
+        "booking_cancel",
+        "booking_reschedule",
+        "booking_withdraw",
+        "block_get",
+        "block_save",
+        "block_remove",
+        "connections_list",
+        "connection_refresh",
+        "connect_request",
+        "activation_save",
+        "members_list",
+        "resource_catalog",
+        "type_catalog",
+        "appointment_hours_get",
+        "appointment_hours_save",
+        "provider_accounts_list",
+        "provider_calendars_list",
+        "provider_calendar_get",
+        "provider_calendar_save",
+        "provider_account_disconnect",
+        "connection_save",
+        "connection_disconnect",
+        "event_open",
+        "setup_requests_list",
+        "setup_request_dismiss"
+    ]
+}

package/dist/modules/booking.d.ts

@@ -0,0 +1,2 @@
+export declare const BOOKING_CLI_ACTIONS: string[];
+export declare function runBooking(slug: string, verb: string, args: string[]): Promise<number>;

package/dist/modules/booking.js

@@ -0,0 +1,91 @@
+import { readFile, stat } from "node:fs/promises";
+import { assertNoUnknownFlags, takeFlagValue } from "../argv.js";
+import { CliHttpError, EXIT_OK, EXIT_USAGE, v1Post } from "../http/client.js";
+import { emitOk, isJson } from "../runtime.js";
+import contract from "./booking-contract.generated.json" with { type: "json" };
+const groups = contract.groups;
+export const BOOKING_CLI_ACTIONS = [...Object.keys(contract.groups), ...Object.keys(contract.direct)];
+export async function runBooking(slug, verb, args) {
+    const rest = [...args], action = groups[verb]
+        ? groups[verb][rest.shift() || "list"]
+        : contract.direct[verb];
+    if (!action)
+        throw new CliHttpError("Unknown Booking action. Run: frontpage modules booking", EXIT_USAGE, 0);
+    const id = takeFlagValue(rest, "--id"), file = takeFlagValue(rest, "--file"), revision = takeFlagValue(rest, "--revision"), requestKey = takeFlagValue(rest, "--request-key"), scope = takeFlagValue(rest, "--scope"), occurrence = takeFlagValue(rest, "--occurrence"), recordKind = takeFlagValue(rest, "--record-kind"), accountId = takeFlagValue(rest, "--account"), setupRequestId = takeFlagValue(rest, "--setup"), memberUsers = takeFlagValue(rest, "--member-users");
+    const query = {};
+    for (const [flag, key] of [
+        ["--from", "from"],
+        ["--to", "to"],
+        ["--type", "typeId"],
+        ["--booking", "bookingId"],
+        ["--member", "memberResourceId"],
+        ["--space", "spaceResourceId"],
+        ["--arrival", "arrival"],
+        ["--before", "before"],
+        ["--limit", "limit"],
+        ["--search", "search"],
+        ["--status", "status"],
+    ]) {
+        const value = takeFlagValue(rest, flag);
+        if (value !== undefined)
+            query[key] = key === "limit" ? Number(value) : value;
+    }
+    if (action === "calendar") {
+        if (query.memberResourceId) {
+            query.memberId = query.memberResourceId;
+            delete query.memberResourceId;
+        }
+        if (query.spaceResourceId) {
+            query.spaceId = query.spaceResourceId;
+            delete query.spaceResourceId;
+        }
+    }
+    assertNoUnknownFlags(rest, "modules");
+    if (rest.length)
+        throw new CliHttpError(`Unexpected Booking argument: ${rest[0]}`, EXIT_USAGE, 0);
+    const writes = contract.writes.includes(action);
+    if (writes && (!requestKey || !/^[A-Za-z0-9_-]{8,128}$/.test(requestKey)))
+        throw new CliHttpError("Writes require --request-key (8–128 letters/digits/_/-). Reuse exactly this key and input after a timeout.", EXIT_USAGE, 0);
+    let value;
+    if (file) {
+        const info = await stat(file);
+        if (!info.isFile() || info.size > 60000)
+            throw new CliHttpError("Booking --file must be a JSON file under 60 KB.", EXIT_USAGE, 0);
+        try {
+            value = JSON.parse(await readFile(file, "utf8"));
+        }
+        catch {
+            throw new CliHttpError("Booking --file must contain valid JSON.", EXIT_USAGE, 0);
+        }
+    }
+    if ((action.endsWith("_save") ||
+        action === "booking_create" ||
+        action === "booking_reschedule") &&
+        value === undefined)
+        throw new CliHttpError("This action requires --file with the complete Booking value.", EXIT_USAGE, 0);
+    if (revision !== undefined &&
+        (!Number.isSafeInteger(Number(revision)) || Number(revision) < 0))
+        throw new CliHttpError("--revision must be a non-negative integer.", EXIT_USAGE, 0);
+    const input = {
+        action,
+        ...(id ? { id } : {}),
+        ...(recordKind ? { recordKind } : {}),
+        ...(accountId ? { accountId } : {}),
+        ...(setupRequestId ? { setupRequestId } : {}),
+        ...(memberUsers !== undefined
+            ? { memberUserIds: memberUsers ? memberUsers.split(",") : [] }
+            : {}),
+        ...(value === undefined ? {} : { value }),
+        ...(revision === undefined ? {} : { expectedRevision: Number(revision) }),
+        ...(requestKey ? { requestKey } : {}),
+        ...(scope ? { scope } : {}),
+        ...(occurrence ? { occurrence } : {}),
+        ...(Object.keys(query).length ? { query } : {}),
+    };
+    const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/booking`, input, { timeoutMs: 25000 });
+    if (isJson())
+        emitOk("modules booking", data);
+    else
+        console.log(JSON.stringify(data, null, 2));
+    return EXIT_OK;
+}

package/dist/modules/commands.js

@@ -1,3 +1,4 @@
+import bookingContract from "./booking-contract.generated.json" with { type: "json" };
 /**
  * §CLI-MOD-FW — per-key CLI registry (usage printer + help --json).
  * Instagram is not documented here. Google reviews extras ship in Phase 1.
@@ -92,21 +93,35 @@ export const MODULE_COMMANDS = [
     {
         key: "booking",
         name: "Booking",
-        summary: "Booking requests. Typed get/set for notify email and hours.",
-        genericActions: GENERIC_ACTIONS,
+        summary: "Appointments, stays, per-type forms and calendar availability.",
+        genericActions: ["docs"],
         extraActions: [
+            "status",
             "get",
-            "set [--notify-email] [--hours \"…\"]",
+            "set --file settings.json --revision N --request-key KEY",
+            "resources list|save|catalog", "members list", "hours get|set", "activation set", "accounts list|calendars|disconnect", "calendars get|save", "setup list|dismiss", "event-open --file event.json",
+            "types list|save|catalog",
+            "bookings list|get|create|accept|decline|cancel|reschedule|withdraw",
+            "blocks get|save|remove",
+            "connections list|connect|save|refresh|disconnect",
+            "calendar --from ISO --to ISO [--member ID] [--space ID]",
+            "availability --type ID --from ISO --to ISO [--arrival YYYY-MM-DD] [--booking ID]",
         ],
         notYet: [],
         examples: [
-            "frontpage modules booking",
+            "frontpage modules booking status",
             "frontpage modules booking get",
-            "frontpage modules booking set --notify-email book@example.com --hours \"Mon–Fri 9–5\"",
+            "frontpage modules booking types list --limit 50",
+            "frontpage modules booking types save --file type.json --request-key type-create-unique-1",
+            "frontpage modules booking bookings accept --id <id> --revision 2 --request-key accept-unique-1",
+            "frontpage modules booking connections connect --file setup.json --request-key setup-request-unique-1",
             "frontpage modules booking docs",
         ],
         notes: [
-            "Typed flags write the same whitelist as `modules config`. Generic JSON config still works.",
+            "Use --file for a complete settings/resource/type/booking/block value. Updates need --id and --revision. First settings save uses --revision 0.",
+            "Every write requires --request-key. Reuse its exact body/key after timeout; changed input needs a new key. List responses return nextCursor; pass it as --before with the same list/site and filters. Limit is at most 100. Booking lists accept --search and --status.",
+            "Calendar ranges are at most 31 days. --member/--space filter both together. Blocks support --scope this|following|all and the exact --occurrence returned by the calendar.",
+            "Connections connect/refresh return a human workspace link. Calendar consent and private calendar settings stay with the connecting human. No secrets go through the CLI.",
         ],
     },
     {
@@ -218,7 +233,9 @@ export function isCliModuleAction(key, action) {
                 "request-destination-setup",
             ].includes(action));
     }
-    if (key === "callbar" || key === "booking" || key === "signups") {
+    if (key === "booking")
+        return Object.hasOwn(bookingContract.groups, action) || Object.hasOwn(bookingContract.direct, action);
+    if (key === "callbar" || key === "signups") {
         return TYPED_CONFIG_CLI_ACTIONS.includes(action);
     }
     return false;

package/dist/registry.js

@@ -308,10 +308,10 @@ export const COMMANDS = [
         examples: [
             "frontpage analytics --days 7",
             "frontpage analytics summary --days 30",
-            "frontpage analytics query --dimension path --measure count --limit 10",
+            "frontpage analytics query --dimension path --measure count --filters '{\"type\":\"pageview\"}' --limit 10",
             `frontpage analytics funnel --steps '[{"path":"/"},{"path":"/pricing"}]'`,
             "frontpage analytics funnel --steps /, /pricing, /updates",
-            "frontpage analytics timeseries --metric pageviews --interval day --days 14",
+            "frontpage analytics timeseries --metric pageviews --interval day --days 7",
             `frontpage analytics compare --a '{"device":"mobile"}' --b '{"device":"desktop"}'`,
             'frontpage analytics sql --sql "SELECT path, count(*)::int AS n FROM analytics_events GROUP BY 1 ORDER BY n DESC LIMIT 10"',
         ],
@@ -320,7 +320,13 @@ export const COMMANDS = [
             "funnel --steps accepts JSON array or comma-separated paths (/, /pricing)",
             "Invalid JSON for --steps / --a / --b prints an explicit parse error (not bare Usage)",
             "Unknown leftover flags fail closed (exit 2)",
-            "Ops use POST …/analytics with allowlisted dimensions/measures; SQL is guard-validated + RLS",
+            "Ops use POST …/analytics with allowlisted dimensions/measures; custom SQL is parsed, allowlisted and RLS site-scoped",
+            "Days presets: 1, 7, 30, 90. Bare dashboard defaults to 7; other structured ops default to 30",
+            "For pageviews filter type=pageview; count without that filter includes all matching events",
+            "SQL: one validated reporting SELECT tree; 4000 input chars, 5s timeout, 500 returned rows; dates belong inside SQL",
+            "Custom functions/types, unrelated/system tables, scope changes, recursive CTEs and unknown syntax reject",
+            "Funnel counts sessions matching successive step sets; it does not require chronological event order",
+            "Metrics and SQL reference: https://frontpage.host/developers/analytics; MCP has separate tools and no raw SQL",
         ],
     },
     {

package/dist/runtime.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Process-global CLI runtime flags (set once from argv in bin.ts).
+ */
+import { CliHttpError } from "./http/client.js";
 export declare function setRuntimeFlags(flags: {
     json?: boolean;
     quiet?: boolean;
@@ -14,6 +18,7 @@ export type JsonErrorBody = {
     httpStatus?: number;
     exitCode: number;
     requestId?: string;
+    details?: CliHttpError["bookingDetails"];
 };
 export declare function emitOk(command: string, data: unknown): void;
 /** Structured failure with optional data payload (e.g. failed run wait). */
@@ -24,6 +29,7 @@ export declare function emitFail(command: string, args: {
     requestId?: string;
     httpStatus?: number;
     data?: unknown;
+    details?: CliHttpError["bookingDetails"];
 }): number;
 export declare function emitErr(command: string, err: unknown): number;
 export declare function emitUsage(command: string, message: string, exitCode?: number): number;

package/dist/runtime.js

@@ -43,6 +43,8 @@ export function emitFail(command, args) {
         body.httpStatus = args.httpStatus;
     if (args.requestId)
         body.requestId = args.requestId;
+    if (args.details)
+        body.details = args.details;
     if (jsonMode) {
         const out = { ok: false, command, error: body };
         if (args.data !== undefined)
@@ -65,6 +67,7 @@ export function emitErr(command, err) {
             code: err.code,
             httpStatus: err.status || undefined,
             requestId: err.requestId,
+            details: err.bookingDetails,
         });
     }
     return emitFail(command, { message, exitCode });

package/llms.txt

@@ -65,3 +65,7 @@ Video uploads: the current CLI prepares a browser-compatible MP4 after uploading
 AI Support Agent knowledge: read the latest note, then save the same ID. Last save wins and prior saved changes remain in history. Knowledge history supports limit/cursor and version reads within the plan Rewind allowance plus the latest version. Archive with customer-inbox post knowledge/ID/archive and {} to stop future use without deleting records. See CUSTOMER-INBOX.md.
 
 Articles needs no setup. Use `frontpage articles create-section --label "Blog" --route blog` to create an active section, `archive-section --section blog` / `restore-section --section blog` to turn it off / on, and `create-article` or `content get|set` for content. Draft articles stay unpublished. Frontpage manages article routing; do not read or edit the managed routing file.
+
+Bookings: read packaged [BOOKING.md](./BOOKING.md) and `frontpage modules booking`. Native commands share workspace validation, per-type forms, resource availability, revisions and stable request keys. Calendar consent and private calendar-link entry use a human handoff; ordinary authorized refresh/hours/connection operations run through shared actions; never pass private feed links or OAuth secrets through CLI/agent inputs.
+
+Analytics reference: https://frontpage.host/developers/analytics. Filter type=pageview for views; count alone includes all matching events. Days presets are 1/7/30/90; bare dashboard defaults to 7, structured ops to 30. SQL dates belong in SQL; parsed reporting allowlists and site RLS apply (4000 chars, 5s, 500 returned rows). Unsafe functions/types, unrelated tables, recursion and unsupported syntax reject. Funnels count session overlap without enforcing chronological order. MCP excludes raw SQL and has its own dashboard/page-detail tools; the CLI has no new page-detail subcommand.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontpage-host",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "description": "Frontpage CLI — manage your site from the terminal",
   "type": "module",
   "bin": {
@@ -14,7 +14,8 @@
     "PEOPLE.md",
     "MAIL.md",
     "CUSTOMER-INBOX.md",
-    "PAYMENTS.md"
+    "PAYMENTS.md",
+    "BOOKING.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",