@topy-ai/maggie 0.7.37 → 0.7.40

package/bundled-contracts/maggiedash/host-capabilities-v1.schema.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "MaggieDash host capability manifest",
+  "type": "object",
+  "required": ["schemaVersion", "endpoints"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-host-capabilities.v1"},
+    "endpoints": {"type": "array", "minItems": 1, "items": {"type": "object", "required": ["id", "path", "enabled"]}}
+  }
+}

package/bundled-contracts/maggiedash/site-structure-v1.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Provider-neutral Maggie site structure",
+  "type": "object",
+  "required": ["schemaVersion", "menus", "templates", "pages", "bands"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-site-structure.v1"},
+    "menus": {"type": "array"},
+    "templates": {"type": "array"},
+    "pages": {"type": "array"},
+    "bands": {"type": "array"}
+  }
+}

package/bundled-references/maggiedash-booking/ARCHITECTURE.md

@@ -0,0 +1,218 @@
+# Booking workspace architecture
+
+This document explains the boundary between MaggieDash, the host project, the
+booking domain, and external providers. The manager workspace, distribution
+manifest, starter schema, versioned contracts, reference host, PostgreSQL
+seams, Stripe boundary, Resend outbox, and Astro host scaffold are implemented
+locally. Production credentials, migrations, scheduler enablement, and
+real-host evidence remain the host integration boundary.
+
+## 1. Current boundary and target boundary
+
+### Current, verified in repository
+
+- MaggieDash installs its React source into `./_maggie/admin`.
+- The host owns the framework route, email/password session, database,
+  `/api/maggie/*` endpoints, provider credential boundary, and deployment.
+  Stripe may come from the deployment secret store or the owner/manager-only
+  dashboard setup path, where it is verified before authenticated encryption;
+  raw credentials never cross into the public browser bundle.
+- The dashboard uses `/api/maggie` and a versioned host adapter contract.
+- `maggie-service-booking` imports and validates provider-owned service data. It
+  does not claim live booking mutation or availability when provider evidence is
+  missing.
+- The shared PostgreSQL starter schema covers projects, users, memberships,
+  sessions, documents, media, section presets, and audit events.
+- MaggieDash distributes a sibling `./_maggie/booking` workspace with overview,
+  calendar, booking, customer, catalogue, staff, resource, payment, settings,
+  and audit screens.
+- The Booking host adapter v1, provider-neutral starter schema, runtime worker,
+  reference host, and Astro host wiring are shipped with the distribution; the
+  host still supplies production database/provider credentials and evidence.
+
+### Host runtime extension
+
+The first-party Booking workspace is installed under `/_maggie/booking`. It shares
+the host session, project identity, design primitives, HTTP transport, audit
+conventions, and runtime evidence model with `/_maggie/admin`, but owns booking
+screens and booking-specific API contracts.
+
+The two workspaces should be siblings, not one huge admin screen:
+
+```text
+/_maggie/admin       content, SEO, media, AI operations, project settings
+/_maggie/booking     calendar, bookings, customers, services, staff, payments
+```
+
+Both routes may import shared UI primitives, but booking must not reach into
+content-specific tables or assume that a provider page is a transactional
+booking record.
+
+## 2. Runtime topology
+
+```text
+Browser
+  |
+  | email/password host session cookie
+  v
+Host framework route
+  |-- /_maggie/admin       -> MaggieDash admin UI
+  |-- /_maggie/booking     -> MaggieDash booking UI
+  |-- /api/maggie/*        -> host adapter endpoints
+  |-- /api/maggie/booking/*-> booking adapter endpoints
+  |
+  | server-only
+  v
+Booking application services
+  |-- catalog
+  |-- availability
+  |-- holds and allocation
+  |-- booking lifecycle
+  |-- payment orchestration
+  |-- customer and consent
+  |-- notifications and outbox
+  |-- audit and reporting
+  |
+  +--> PostgreSQL: business truth
+  +--> PaymentGateway: Stripe first, others later
+  +--> Email/SMS adapters
+  +--> Calendar adapters, optional
+```
+
+The browser receives normalized DTOs and capability flags. It does not receive
+database connections, Stripe secret keys, raw provider objects, or unrestricted
+agent tools.
+
+## 3. Logical modules
+
+| Module | Owns | Must not own |
+|---|---|---|
+| Tenant and access | project, tenant, location scope, role checks | provider credential values |
+| Catalog | services, variants, treatment packages, provider facts | availability decisions, customer balances |
+| Schedule | opening hours, shifts, time off, blocks, closures | payment status |
+| Resource | rooms, equipment, capacity, requirements | customer identity |
+| Availability | candidate slots, exclusion reasons, holds | gateway-specific objects |
+| Booking | booking, segments, transitions, reschedules, cancellation | card data |
+| Payment | attempts, transactions, refunds, reconciliation | staff schedules |
+| Customer | contact, consent, notes, booking history, package entitlements | raw payment method |
+| Notification | durable events, templates, delivery attempts | booking truth mutation |
+| Reporting | read models, daily totals, utilization, reconciliation | source-of-truth writes |
+| Audit | append-only actor/action/reason trail | secret or full payload storage |
+| Provider adapters | translate external APIs and events | canonical business rules |
+
+## 4. Source-of-truth rules
+
+| Question | Source of truth | Why |
+|---|---|---|
+| Does a slot conflict? | PostgreSQL allocation constraints plus availability service | UI checks alone race |
+| Is a booking confirmed? | Booking state machine in PostgreSQL | Gateway success is not a booking transition |
+| Did money settle? | Verified gateway event or provider read, projected into payment tables | Redirects can be abandoned or forged |
+| What did the manager change? | Audit events and booking events | Support needs actor and reason |
+| What can a provider do? | Provider capability declaration and health result | UI must fail closed |
+| What does the customer see? | Host-rendered booking/public DTO | External provider UI is not the product contract |
+| What is a service fact? | Approved catalogue provenance | AI copy must not invent price, duration, or URL |
+
+## 5. Request and command flow
+
+Every mutating request follows this shape:
+
+1. Resolve the host session and project/tenant scope.
+2. Authorize the action against role, location, and object ownership.
+3. Validate the request DTO and idempotency key.
+4. Load current state and required policy version.
+5. Apply a transaction with database constraints.
+6. Append a domain event and audit event in the same transaction where possible.
+7. Commit an outbox record for notifications, provider side effects, and reports.
+8. Return the canonical result plus `correlationId`, current state, and safe
+   next actions.
+
+External side effects are not allowed to decide whether the local booking
+transaction commits. A worker handles retries and reconciliation.
+
+## 6. Booking allocation strategy
+
+The availability query produces candidates. The hold or booking command takes
+the final allocation lock. The database must reject overlapping active
+allocations for a staff member or resource within the same tenant and location.
+
+For PostgreSQL, the implementation should evaluate an exclusion constraint over
+a range built from `start_at` and `end_at`, with an explicit status predicate
+for active holds/bookings. The exact migration must be reviewed against the
+host's PostgreSQL version and tenancy model before implementation.
+
+Application checks remain useful for good error messages, but they are not the
+correctness boundary.
+
+## 7. Time and money
+
+- Persist instants as `timestamptz` or an equivalent UTC representation.
+- Persist the venue IANA timezone on the location and copy the resolved
+  timezone/fold into booking input evidence.
+- Reject nonexistent local times during DST transitions.
+- Require an explicit fold for ambiguous local times.
+- Persist amount in integer minor units and a three-letter ISO currency.
+- Never derive money from a formatted display string.
+- Store the policy, tax, discount, and rounding decisions used for the booking.
+
+## 8. Provider-neutral payment boundary
+
+Booking services depend on the interface described in
+[PAYMENT-GATEWAY.md](./PAYMENT-GATEWAY.md). The first implementation is
+`StripePaymentGateway`. It translates local payment intents into Stripe
+PaymentIntents, SetupIntents, refunds, or Terminal operations as configured.
+
+The local `payment_attempts`, `payment_transactions`, and `payment_webhook_events`
+tables remain the system's reconciliation record. A Stripe object ID is an
+external reference, never the only local payment record.
+
+## 9. Failure isolation
+
+The UI and write API must distinguish:
+
+- configuration missing;
+- provider unavailable;
+- payment action required;
+- payment failed;
+- webhook pending;
+- reconciliation pending;
+- booking conflict;
+- notification failed;
+- permission denied.
+
+One failed email or analytics delivery must not roll back a confirmed booking.
+One failed payment read must not mark a captured payment as failed. One
+provider timeout must not cause a second charge without an explicit new payment
+attempt and idempotency key.
+
+## 10. Route integration
+
+Astro currently rewrites underscore-prefixed dashboard filesystem paths once in
+middleware because Astro excludes those segments. The booking adapter should
+follow the same rule:
+
+```text
+/_maggie/booking       -> /maggie/booking
+/_maggie/booking/*     -> /maggie/booking/*
+/_maggie/booking/book  -> public host route using the customer page starter
+```
+
+The manager URL stays `/_maggie/booking`; the internal route must not rewrite
+to itself. The manager page is server-rendered only for the shell, carries
+`noindex`, and redirects unauthenticated users to the host login. The optional
+customer page is `/_maggie/booking/book`; it is public/noindex and must use the
+host's separate tenant-bound public API policy.
+
+## 11. Extension points
+
+The design intentionally leaves these ports stable:
+
+- `PaymentGateway`: Stripe, Square, Adyen, Mollie, or a future provider;
+- `NotificationProvider`: email, SMS, WhatsApp, push;
+- `CalendarProvider`: internal calendar, Google, Outlook, or none;
+- `BookingProvider`: local transactional engine, or a provider link for
+  projects that have not enabled native booking;
+- `MediaStorageProvider`: the existing provider-neutral media contract;
+- `AnalyticsSink`: local event/outbox consumer, never a booking dependency.
+
+Provider-specific metadata is namespaced and stored as external references.
+Canonical booking state, amount, and lifecycle remain provider-neutral.

package/bundled-references/maggiedash-booking/CURRENT-STATE.md

@@ -0,0 +1,92 @@
+# MaggieDash Booking current state and gaps
+
+Status: current snapshot, 2026-09-21
+
+This is the canonical status document for the Booking implementation. The
+append-only [`PROGRESS.md`](./PROGRESS.md) keeps historical counts and decisions
+from earlier delivery turns; those historical values must not be read as the
+current contract.
+
+## Verified implementation surface
+
+| Surface | Current state | Authoritative evidence |
+|---|---|---|
+| MaggieDash source | Package `0.2.9`, with host capability, site-structure, and treatment-group contracts; the working tree contains the current Booking release changes | `/home/balalior/Dev/MaggieDash/package.json`, `maggiedash.json`, `git status` |
+| Manager host contract | 47 endpoint IDs, email/password session, server-side role/capability checks | `MaggieDash/contracts/booking-host-adapter-v1.json` |
+| Public customer contract | 11 endpoint IDs, separate noindex/no-store boundary and token policy | `MaggieDash/contracts/booking-customer-surface-v1.json` |
+| Booking access contract | 4 administrator-only access endpoints, staff/manager/finance roles and granular permissions | `MaggieDash/contracts/booking-access-v1.json` |
+| Resend template contract | 10 tenant-scoped events, allowlisted variables, preview/publish/rollback and server-only recipient/provider data | `MaggieDash/contracts/booking-email-templates-v1.json` |
+| Browser evidence contract | 15 manager routes × 3 viewports = 45 screens | `MaggieDash/contracts/booking-browser-evidence-v1.json` |
+| Execution board | 87 tasks: 84 `passed`, 3 `needs-evidence` (`BK-030`, `BK-031`, `BK-032`) | [`EXECUTION-BOARD.json`](./EXECUTION-BOARD.json) |
+| Local regression | AI-CMO Python suite: 364 tests passed; MaggieDash `npm test`, ORA contract checks, and ORA Astro build passed | recorded in the current verification output and [`PROGRESS.md`](./PROGRESS.md) |
+
+## What is implemented locally
+
+- Traditional email/password owner registration, login, staff invitations,
+  password reset, revocation, disabled-account protection, and server-enforced
+  granular Booking permissions.
+- Tenant-scoped locations, services/variants, treatment packages, customer
+  entitlements, staff, resources, schedules, closures, buffers, availability,
+  holds, multi-treatment bookings, rescheduling, cancellation, waitlist, and
+  customer-manage history.
+- Provider-neutral payment orchestration plus the Stripe adapter seam,
+  PaymentIntent saved-method flow, SetupIntent setup-only flow, Stripe Customer
+  mapping, webhook normalization, refunds, package purchase/refund settlement,
+  and explicit consented no-show fee charging.
+- Resend outbox delivery, ten event templates, invitations, reminders,
+  customer-manage links, waitlist/package/refund/no-show notification intents,
+  retry, dead-letter, and audited replay.
+- PostgreSQL repository seams, schema/preflight tooling, worker scheduling
+  artifacts, reference-host validators, runtime/browser/ops evidence contracts,
+  and the ai-cmo-skills installer/inspect/release gates.
+
+“Implemented locally” means source, contract, fixture, and local/reference-host
+evidence exist. It does not mean a production tenant has been migrated or that
+provider delivery has been proven on the live host.
+
+## Open gaps
+
+| Priority | Gap | Current evidence | Exit evidence |
+|---|---|---|---|
+| P0 | ORA Booking schema and access tables are not installed in the configured database | Read-only schema check reported `needs-migration`; core exists, Booking/access tables do not | Owner-approved backup/restore rehearsal, then `node scripts/maggie-booking-schema.mjs --apply --confirm` and a post-migration check |
+| P0 | Stripe test account is not fully verified for Booking | ORA `.env` has the existing `ST_SECRECT_KEY` test secret alias and `ST_PUB_KEY`; `STRIPE_WEBHOOK_SECRET` is absent | Add webhook signing secret, run the authenticated **Verify Stripe connection** action, and capture signed success/failure/delayed/duplicate/refund/no-show test evidence |
+| P0 | Worker and alerting are not enabled on the real host | systemd/cron artifacts are generated, but no host schedule, lock, alert route, or recovery evidence has been supplied | Enable one scheduler, run a disposable/staging worker cycle, prove lock/retry/dead-letter/recovery alerts, and retain sanitized ops evidence |
+| P0 | Real-host runtime and browser conformance is missing | Reference-host, fixture, and local build evidence pass; no authenticated HTTPS runtime/browser artifact exists | Run all 47 manager endpoints and all 45 browser screens against a dedicated staging/test tenant, then pass `release-gate --require-runtime --require-browser --require-ops` |
+| P1 | Published npm package is behind the current Booking contracts | Local AI-CMO package source is `0.7.40`; publish and registry readback are the remaining release actions | Verify the installed public tarball, and rerun `maggie booking inspect` against ORA |
+| P1 | ORA staging data and legacy allocation backfill need approval | `maggie-booking-buffer-backfill.sql` is present but not applied; active locations/catalogue/staff/schedule/payment policy still need real data verification | Apply the reviewed additive/backfill migration in staging, seed a test location/catalogue/staff schedule, and prove readiness plus conflict behavior |
+| P1 | End-to-end Resend delivery is unproven | Outbox/worker code and validators pass, but invitation, reset, reminder, waitlist, package, refund, and no-show messages have not been observed in a staging mailbox | Capture redacted delivery, retry, dead-letter, replay, and duplicate-suppression evidence |
+| P1 | Release/canary ownership is incomplete | `BK-032` remains `needs-evidence`; no final release artifact or canary report is recorded | Produce the board-complete release report, rollback rehearsal, canary window, and feedback closure |
+| P2 | Product scope remains intentionally narrower than Fresha | Memberships, gift-card ledger, recurring appointments, SMS/WhatsApp, tax/accounting, advanced waitlist optimization, and multi-provider production adapters are not in v1 | Create separate contracts/PRDs before promising these capabilities |
+
+## Required host sequence
+
+1. Back up the database and rehearse restore into an empty disposable target.
+2. Apply the Booking and access migrations with explicit owner approval.
+3. Register the first owner and verify staff/role boundaries.
+4. Configure Stripe test secret plus webhook secret and verify capabilities.
+5. Configure and test the Resend worker and one scheduler with alerting.
+6. Seed a staging location, service variants, bookable staff, hours, and policy.
+7. Capture runtime, browser, and ops evidence; run the final release gate.
+8. Canary one location, monitor conflicts/payments/outbox, then decide whether to
+   enable public booking.
+
+## Re-audit commands
+
+```bash
+# ai-cmo-skills
+python3 -m unittest discover -s tools/tests -p 'test_*.py'
+python3 tools/clis/maggie_booking.py tasks validate
+
+# MaggieDash
+npm test
+node scripts/validate-booking-service-contract.mjs
+node scripts/validate-booking-host-contract.mjs
+
+# ORA host (read-only checks)
+npm run contract:check
+npm run build
+npm run booking:schema -- --check
+```
+
+Do not put Stripe, Resend, database, session, or customer secrets into this
+document or into evidence artifacts.

package/bundled-references/maggiedash-booking/DATA-FLOW.md

@@ -0,0 +1,143 @@
+# Booking data flow
+
+This document defines the system's data-flow boundaries. The rendered diagrams
+are linked images so they work in GitHub even when Mermaid rich display is
+unavailable.
+
+## Level 0: context
+
+![Booking system context](./diagrams/system-context.svg)
+
+[Open Mermaid source](./diagrams/system-context.mmd) · [PNG](./diagrams/system-context.png)
+
+External actors exchange normalized commands, facts, and events with the
+Booking application. The browser never talks directly to Stripe with a secret
+or writes the database.
+
+## Level 1: booking DFD
+
+![Booking data-flow diagram](./diagrams/booking-dfd.svg)
+
+[Open Mermaid source](./diagrams/booking-dfd.mmd) · [PNG](./diagrams/booking-dfd.png)
+
+### Flow descriptions
+
+| Flow | Producer | Consumer | Data | Trust rule |
+|---|---|---|---|---|
+| `availability.query` | booking UI/public page | availability service | service, location, date, preferences | Treat all client values as untrusted; public response uses the customer DTO |
+| `hold.create` | booking UI/public page/manager UI | booking service | candidate allocation, customer, policy version, idempotency key | Recheck availability inside transaction; public route is tenant-bound and rate-limited |
+| `payment.start` | booking service | payment adapter | local payment attempt, amount, currency, return context | Provider receives only normalized payment request |
+| `payment.event` | payment provider | webhook endpoint | signed provider event | Verify signature and deduplicate before projection |
+| `booking.confirmed` | booking transaction | outbox consumers | local booking ID and safe facts | Notifications do not mutate booking truth; public customer intent is allowlisted |
+| `package.grant` | manager dashboard | booking service | customer, package, quantities, expiry, idempotency key | Grant is tenant-scoped and audited; it is not a payment confirmation |
+| `package.redeem` | manager or public customer booking transaction | entitlement ledger | booking, customer-bound matching service variants, quantities | Lock entitlement and item rows; tenant/customer binding and decrement happen in the same transaction as the booking |
+| `package.redeem.reverse` | successful manager or eligible customer cancellation | entitlement ledger | booking, active redemption rows, cancellation reason | Lock the redemption/item rows; restore each quantity once, mark the ledger row reversed, and keep no-show/completed debits |
+| `no_show_fee.charge` | authorized manager/finance action | Stripe adapter and payment repository | no-show booking, policy amount, saved method, explicit confirmation | Require customer consent, saved provider method, verified off-session capability, and idempotency; never charge on status transition |
+| `notification.delivery` | notification worker | email/SMS provider | rendered message and delivery key | Failure is retryable and non-blocking |
+| `audit.append` | command/event transaction | audit store and activity UI | actor, action, entity, reason, correlation ID | Redact secrets and customer-sensitive payloads |
+| `report.project` | reporting worker | manager dashboard | aggregate counts and money totals | Derived data can be rebuilt |
+
+The implemented provider-neutral command layer sits between the HTTP adapter
+and the transaction boundary. It normalizes local wall time with an explicit
+IANA timezone/fold, checks every segment against active allocations, then
+returns the booking/hold mutation together with event and audit intent. A host
+must persist that result atomically; the command layer does not bypass the
+database overlap constraints.
+
+## Level 2: paid booking sequence
+
+![Payment sequence](./diagrams/payment-sequence.svg)
+
+[Open Mermaid source](./diagrams/payment-sequence.mmd) · [PNG](./diagrams/payment-sequence.png)
+
+The sequence has two independent confirmations:
+
+1. The local database confirms the allocation and booking transition.
+2. The provider confirms the money state through a verified event or a provider
+   read.
+
+The final local transition joins those facts transactionally. A provider
+redirect only starts reconciliation; it cannot complete the transition alone.
+
+An ordinary paid booking may save a method through
+`setup_future_usage=off_session`. A later no-show fee is a separate explicit
+adjustment: the no-show transition produces review state, and only an
+authorized manager/finance command can request the off-session charge. A
+successful charge is persisted and then queues `payment.no_show_fee` through
+the Resend outbox; pending or failed results remain operator-visible.
+
+## State flow
+
+![Booking state machine](./diagrams/booking-state-machine.svg)
+
+[Open Mermaid source](./diagrams/booking-state-machine.mmd) · [PNG](./diagrams/booking-state-machine.png)
+
+Booking and payment states are separate. A confirmed booking may have a deposit
+paid and a balance due. A cancelled booking may have a refund pending. The UI
+must show both values.
+
+## Event and outbox flow
+
+```text
+Command request
+  -> database transaction
+     -> booking / payment / allocation rows
+     -> booking event
+     -> audit event
+     -> outbox event
+  -> response
+
+Outbox worker
+  -> notification adapter
+  -> provider reconciliation
+  -> analytics/read model projection
+  -> retry / dead-letter record
+```
+
+The outbox record contains a stable event ID, event type, tenant/project ID,
+aggregate ID, correlation ID, schema version, safe payload, attempt count, next
+attempt time, and processing state. It does not contain card details, provider
+secrets, or raw webhook bodies.
+
+## Consistency rules
+
+### Strong consistency
+
+- tenant and location authorization;
+- allocation conflict checks;
+- hold creation and expiry transition;
+- booking lifecycle transition;
+- payment/refund transaction totals;
+- package entitlement balance and redemption ledger;
+- idempotency-key response ownership;
+- audit event creation for a successful material mutation.
+
+### Eventual consistency
+
+- email/SMS/push delivery;
+- analytics and attribution projections;
+- daily metrics and utilization reports;
+- provider health snapshots;
+- search/read-model indexes;
+- webhook retry and reconciliation queues.
+
+## Idempotency keys
+
+Every external or retryable command has a scope-specific idempotency key:
+
+```text
+tenant:{tenantId}:booking:create:{clientKey}
+tenant:{tenantId}:booking:{bookingId}:payment:{attemptKey}
+tenant:{tenantId}:payment:{paymentId}:refund:{refundKey}
+provider:{providerId}:webhook:{providerEventId}
+```
+
+The key is stored with request hash, response reference, status, and expiry.
+Reusing a key with a different request hash is a conflict, not a new action.
+
+## Privacy boundary
+
+Customer contact data is available only to authorized services and roles. The
+activity screen gets a redacted summary. The dashboard never receives raw
+webhook bodies, secret headers, card numbers, CVC, access tokens, or provider
+credentials.