@topy-ai/maggie 0.7.37 → 0.7.40

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

@@ -0,0 +1,367 @@
+# Booking data model
+
+The model is normalized around a tenant, location, service, allocation, booking,
+payment, and event boundary. The exact SQL migration belongs in MaggieDash, but
+this document is the contract that the migration and adapters must implement.
+
+## 0. MaggieDash physical mapping
+
+The current MaggieDash schema uses the existing `maggiedash_projects` identity
+as the Booking tenant. Booking tables therefore use `project_id` as the
+physical tenant key rather than introducing a second `tenant_id` hierarchy.
+The host resolves the authenticated email/password session through
+`maggiedash_memberships` before every query and mutation. This is an intentional
+MVP simplification: a future multi-brand tenancy layer may add a logical
+`booking_tenants` view or bridge without changing the source-of-truth rule.
+
+The migration includes locations, catalog, staff/resources, schedules,
+customers, holds, bookings, segments, allocations, payment accounts/attempts/
+transactions/refunds, package purchases/refunds, webhook events, outbox, notifications, audit, and
+idempotency records. `blocks` and `closures` remain host-owned schedule
+projections for this version; the current UI contract represents them through
+the schedule DTO until their dedicated policy commands are implemented.
+
+Run the source and database checks with:
+
+```bash
+npm run booking:schema:validate
+node scripts/validate-booking-schema.mjs \
+  --database-url "$DATABASE_URL" --confirm
+```
+
+The second command is an explicitly mutating migration check and must only be
+used against a disposable or approved migration-test database.
+
+## 1. Entity map
+
+```text
+Tenant
+  -> Location
+  -> UserMembership
+  -> Staff
+  -> Service -> ServiceVariant
+  -> Resource -> ServiceResourceRequirement
+  -> AvailabilityRule / Shift / TimeOff / Block / Closure
+  -> Customer
+  -> Booking -> BookingSegment -> Allocation
+  -> CustomerPackageEntitlement -> PackageRedemption
+  -> PackagePurchase -> PackagePurchaseRefund
+  -> PaymentAttempt -> PaymentTransaction -> Refund
+  -> PaymentWebhookEvent
+  -> Notification / OutboxEvent / AuditEvent
+```
+
+## 2. Core entities
+
+### Tenant and access
+
+`booking_tenants` extends or references the existing MaggieDash project identity.
+Every booking-owned table carries `tenant_id`; location-scoped records also
+carry `location_id` where the query boundary needs it.
+
+```text
+booking_tenants
+  id, project_id, name, default_timezone, default_currency, status
+
+booking_memberships
+  tenant_id, user_id, role, location_scope_json, status
+```
+
+Use the existing host email/password session. Do not create a second login
+system in the booking bundle.
+
+### Locations
+
+```text
+booking_locations
+  id, tenant_id, name, slug, timezone, locale, currency
+  address_json, phone, active, booking_enabled
+  created_at, updated_at
+```
+
+`timezone` is an IANA identifier such as `Europe/London`. It is not a browser
+offset or a fixed `+01:00` string.
+
+### Catalog
+
+```text
+booking_services
+  id, tenant_id, category_id, name, description
+  booking_enabled, online_booking_enabled, status
+  default_duration_minutes, default_amount_minor, currency
+  buffer_before_minutes, buffer_after_minutes
+  processing_minutes, finishing_minutes
+  cancellation_policy_json, deposit_policy_json
+  source_provider, source_record_id, source_url, source_revision
+  created_at, updated_at
+
+booking_service_variants
+  id, service_id, name, duration_minutes
+  amount_minor, currency, active, sort_order
+  provider_variant_id, source_json
+
+booking_staff_services
+  tenant_id, staff_id, service_id, location_id
+  duration_override_minutes, amount_override_minor, currency_override
+  active
+```
+
+Imported provider facts should map to the existing universal service catalogue
+or an explicit bridge table. AI-generated copy is not a source of price,
+duration, provider ID, or booking URL.
+
+### Treatment packages and customer entitlements
+
+The package catalogue and a customer's prepaid entitlement are separate
+aggregates. A package definition is reusable; an entitlement is tenant-scoped
+to one customer and records the granted balance, expiry, source, and audit
+history.
+
+```text
+booking_treatment_packages
+  id, tenant_id, name, description, price_minor, currency
+  expiration_days, active, metadata_json
+
+booking_treatment_package_items
+  package_id, service_variant_id, quantity, sort_order
+
+booking_customer_packages
+  id, tenant_id, customer_id, package_id
+  status, source, purchased_at, expires_at, metadata_json
+
+booking_customer_package_items
+  entitlement_id, service_variant_id
+  quantity_granted, quantity_redeemed
+
+booking_package_redemptions
+  id, tenant_id, booking_id, entitlement_id
+  service_variant_id, quantity, status, created_at
+  reversed_at, reversal_reason, reversed_by
+```
+
+The current release supports manager-granted entitlements, balance reads,
+expiry projection, atomic redemption while creating a manager or public
+customer booking, and a separate customer package purchase/refund aggregate.
+Cancelling a booking reverses its active redemption rows exactly once and
+restores the matching `quantity_redeemed` values in the same transaction;
+completed and no-show bookings intentionally retain their debits. A reversed
+ledger row is never deleted, so the package balance history remains auditable.
+Public package checkout uses the same tenant-bound customer surface as
+appointment checkout; Stripe webhooks or provider reads fulfill the
+entitlement, while refunds are rejected after any visit has been redeemed.
+
+### Staff and resources
+
+```text
+booking_staff
+  id, tenant_id, user_id, display_name, email, phone
+  role, active, bookable, commission_policy_json
+
+booking_staff_locations
+  tenant_id, staff_id, location_id, active
+
+booking_resources
+  id, tenant_id, location_id, name, type, capacity, active
+
+booking_service_resource_requirements
+  service_id, resource_id, quantity, mode
+```
+
+`mode` can later support exclusive, shared-capacity, or quantity-based
+allocation. The MVP should implement exclusive allocation first.
+
+### Schedule and allocation
+
+```text
+booking_working_hours
+  id, tenant_id, location_id, staff_id, weekday
+  start_local, end_local, timezone, active
+
+booking_shifts
+  id, tenant_id, location_id, staff_id, start_at, end_at, status
+
+booking_time_off
+  id, tenant_id, staff_id, start_at, end_at, reason
+
+booking_blocks
+  id, tenant_id, location_id, staff_id, resource_id
+  start_at, end_at, reason, status
+
+booking_closures
+  id, tenant_id, location_id, start_at, end_at, reason
+
+booking_holds
+  id, tenant_id, location_id, customer_id
+  expires_at, status, idempotency_key, release_reason
+
+booking_allocations
+  id, tenant_id, location_id, hold_id, booking_id, segment_id
+  staff_id, resource_id, start_at, end_at, status
+```
+
+Active allocations must be protected by a database-level non-overlap rule. The
+exact active statuses must be explicit in the migration and match the service
+transition code.
+
+### Booking
+
+```text
+booking_bookings
+  id, tenant_id, location_id, customer_id
+  status, payment_status, source, channel
+  start_at, end_at, timezone, timezone_fold
+  subtotal_minor, discount_minor, tax_minor, total_minor
+  currency, payment_policy_json, initial_due_minor
+  deposit_due_minor, paid_minor, balance_due_minor
+  cancellation_policy_snapshot_json
+  attribution_json, notes_redacted_or_policy_checked
+  created_by, created_at, updated_at
+
+booking_segments
+  id, booking_id, service_id, variant_id
+  staff_id, resource_id, start_at, end_at
+  amount_minor, currency, duration_minutes, sort_order
+
+booking_events
+  id, tenant_id, booking_id, type, from_status, to_status
+  actor_id, reason, correlation_id, payload_json, created_at
+```
+
+Do not use a boolean `booked`. Booking lifecycle and payment lifecycle are
+separate state machines.
+
+### Customer and consent
+
+```text
+booking_customers
+  id, tenant_id, email, phone, name
+  marketing_consent, service_consent_json
+  provider_customer_ref, provider_payment_method_ref
+  notes_policy_state, created_at, updated_at
+
+booking_customer_events
+  id, tenant_id, customer_id, type, source, created_at
+```
+
+Medical, allergy, patch-test, or consultation data requires a separate consent
+and retention design. It is not part of the basic customer table.
+
+### Payments and providers
+
+```text
+booking_payment_accounts
+  id, tenant_id, provider, account_ref, mode, capabilities_json, status
+
+booking_payment_attempts
+  id, tenant_id, booking_id, purpose, provider
+  amount_minor, currency, status, idempotency_key
+  external_intent_ref, client_reference, error_code_safe
+  created_at, updated_at
+
+booking_payment_transactions
+  id, tenant_id, booking_id, attempt_id, provider
+  type, amount_minor, currency, external_ref
+  status, occurred_at, metadata_json
+
+booking_refunds
+  id, tenant_id, booking_id, payment_transaction_id
+  amount_minor, currency, provider, external_ref, status
+  idempotency_key, reason, created_at, updated_at
+
+booking_payment_webhook_events
+  id, tenant_id, provider, external_event_id
+  customer_id, provider_payment_method_ref
+  event_type, signature_verified, received_at, processed_at
+  processing_status, safe_error, payload_hash
+```
+
+The raw provider body is not stored by default. A short-lived encrypted
+quarantine or provider dashboard link may be used under a separately reviewed
+retention policy.
+
+Provider customer and payment-method values are opaque external references;
+they are tenant-scoped and never exposed as raw provider objects to the
+browser. Customer service consent records the `noShowFee` consent used by the
+separate explicit no-show adjustment route. `adjustment` attempts are excluded
+from ordinary paid/refundable booking totals and are written only after a
+confirmed off-session provider result.
+
+### Events, notifications, and audit
+
+```text
+booking_outbox_events
+  id, tenant_id, aggregate_type, aggregate_id, event_type
+  schema_version, correlation_id, payload_json
+  status, attempts, next_attempt_at, last_error_safe
+
+booking_notifications
+  id, tenant_id, booking_id, waitlist_entry_id, package_purchase_id
+  channel, template, recipient_hash
+  status, idempotency_key, provider_ref, last_error_safe
+
+booking_audit_events
+  id, tenant_id, actor_id, action, entity_type, entity_id
+  reason, correlation_id, before_summary_json, after_summary_json
+  created_at
+```
+
+## 3. State machines
+
+### Booking state
+
+```text
+draft -> held -> pending_payment -> confirmed
+confirmed -> checked_in -> in_progress -> completed
+held -> expired
+held -> cancelled
+pending_payment -> payment_failed -> held | cancelled
+confirmed -> rescheduled -> confirmed
+confirmed -> cancelled | no_show
+```
+
+The implementation may combine `rescheduled` into an event rather than a long-
+lived status, but the old and new allocations must be auditable.
+
+### Payment state
+
+```text
+not_required
+requires_payment -> action_required -> processing -> paid
+requires_payment -> failed
+processing -> failed | paid
+paid -> partially_refunded -> refunded
+paid -> refund_pending -> partially_refunded | refunded | refund_failed
+```
+
+### Hold state
+
+```text
+active -> converted
+active -> released
+active -> expired
+```
+
+## 4. Required constraints and indexes
+
+- Unique `(tenant_id, slug)` for locations.
+- Unique `(tenant_id, provider, provider_service_id)` for imported services.
+- Unique `(tenant_id, idempotency_key, command_type)` for commands.
+- Unique `(provider, external_event_id)` for webhook deduplication.
+- Unique `(tenant_id, booking_id, active_attempt_sequence)` or an equivalent
+  local attempt sequence.
+- Index bookings by tenant, location, start time, status, and customer.
+- Index allocations by tenant, staff, resource, time range, and active status.
+- Index outbox by tenant, status, and next attempt time.
+- Database-level overlap protection for active staff/resource allocations.
+
+## 5. Migration order
+
+1. Add tenant/location/access bridge and feature flag.
+2. Add catalog, staff, resource, schedule, and policy tables.
+3. Add holds, allocations, bookings, segments, and events.
+4. Add payment accounts, attempts, transactions, refunds, and webhook events.
+5. Add treatment packages, customer entitlements, redemption ledger, outbox,
+   notifications, audit, and read-model indexes.
+6. Backfill only reviewed provider facts; never backfill invented availability.
+7. Run migration preflight, shadow reads, and conflict tests before enabling
+   writes.

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

@@ -0,0 +1,94 @@
+# Booking decision log
+
+This is the durable decision record for the Booking workspace. D-001, D-002,
+D-007 and the v1 contract boundaries have landed in MaggieDash. The remaining
+runtime decisions stay explicit until the host services and production tests
+land.
+
+## D-001: Separate `/_maggie/booking` workspace
+
+Status: accepted and implemented in MaggieDash
+
+Create a separate booking workspace beside `/_maggie/admin`. Booking has a
+different information architecture, permission model, operational density, and
+failure vocabulary. Sharing primitives and session infrastructure is useful;
+merging the screens would make the existing admin surface harder to operate.
+
+## D-002: PostgreSQL is business truth
+
+Status: accepted for the starter schema; host migration pending
+
+The local database owns tenants, catalog, schedule, availability, holds,
+bookings, customers, payment projections, audit, and outbox. External providers
+are sources of external facts and money state, not the local booking database.
+
+## D-003: Holds are first-class
+
+Status: accepted and implemented locally; host transaction evidence pending
+
+A selected slot is reserved before payment starts. Holds have expiry, scope,
+idempotency, and release reason. This prevents two successful payments for one
+allocation and gives the customer a bounded payment window.
+
+## D-004: Database constraints enforce allocation correctness
+
+Status: accepted and implemented in the starter schema and repository seams;
+host concurrency evidence pending
+
+The availability UI is advisory. A database-level overlap constraint and
+transactional allocation are the final double-booking guard.
+
+## D-005: Payment adapter, not payment logic in Booking
+
+Status: accepted and implemented locally; live provider evidence pending
+
+Booking uses a `PaymentGateway` port. Stripe is implemented first. This keeps
+provider changes out of booking transitions, data tables, and manager screens.
+
+## D-006: Webhook or provider reconciliation is payment proof
+
+Status: accepted and implemented locally; signed live webhook evidence pending
+
+A redirect is a navigation event. A verified provider event or server-side
+provider read is required before local payment projection and booking
+confirmation.
+
+## D-007: Email/password auth stays host-owned
+
+Status: accepted from current MaggieDash contract
+
+MaggieDash uses the host's traditional email/password session. Booking must use
+the same boundary and must not add passkeys, passwordless login, or a second
+identity store.
+
+## D-008: Provider capability flags fail closed
+
+Status: accepted and implemented locally; host account verification pending
+
+If a provider does not support live availability, refunds, saved methods, or
+Terminal, the UI and API do not pretend that it does. Public links remain a
+safe fallback where native booking is not enabled.
+
+## D-009: Domain features are phased
+
+Status: accepted phased rollout; packages and bounded waitlist are in the local
+v1 slice, while memberships, gifts, loyalty, and recurring appointments remain
+future modules
+
+Ship catalog, schedule, availability, holds, booking, payment, treatment
+packages, and a bounded priority/FIFO waitlist matcher before memberships,
+gifts, loyalty, marketplace, and AI concierge. Advanced optimization across
+multiple services, locations, and alternative staff remains a later phase. The
+first proof is reliable Calendar -> Availability -> Booking -> Payment behavior.
+
+## Remaining decisions
+
+1. Which PostgreSQL versions and deployment platforms belong in the supported
+   production matrix?
+2. Whether future multi-location tenants need separate payment accounts per
+   location; v1 currently uses one tenant-scoped account.
+3. Which future module gets a separate contract first: memberships, gift cards,
+   recurring appointments, loyalty, or SMS/WhatsApp.
+
+Until these are resolved, implementation should use the provider-neutral
+interfaces and avoid irreversible migrations.