@topy-ai/maggie 0.7.38 → 0.7.40

package/bundled-references/maggiedash-booking/PAYMENT-GATEWAY.md

@@ -0,0 +1,267 @@
+# Payment gateway architecture
+
+The booking domain depends on a provider-neutral payment port. Stripe is the
+first implementation because the current product already uses it, but the
+booking service must not import Stripe types or encode Stripe state names.
+
+The dated Stripe resource/event audit is in
+[`STRIPE-INTEGRATION.md`](./STRIPE-INTEGRATION.md). It is deliberately separate
+from this provider-neutral design so a host can upgrade Stripe without making
+the booking domain depend on Stripe object names. The installable matrix lives
+in the MaggieDash
+[`stripe-booking-capabilities-v1.json`](../../bundled-contracts/maggiedash/stripe-booking-capabilities-v1.json)
+contract.
+
+## 1. Design rule
+
+```text
+Booking service
+      |
+      v
+PaymentGateway port
+      |
+  +---+-------------------+
+  |                       |
+Stripe adapter       Future adapter
+```
+
+The local database owns payment attempts, transaction projections, refund
+limits, and the relationship between payment and booking. The gateway owns the
+external payment lifecycle and returns normalized facts.
+
+## 2. Implemented port boundary
+
+MaggieDash now ships the provider-neutral orchestration in
+`backend/booking/payment-gateway.mjs` and a deterministic fake implementation
+in `backend/booking/fake-payment-gateway.mjs`. The fake gateway supports
+`success`, `action_required`, `delayed`, and `failure` modes, plus refund and
+reconciliation observations. It is for tests only; it never stores card data or
+provider secrets.
+
+```bash
+npm run booking:payment:test
+```
+
+## 3. Port shape
+
+This TypeScript shape is a contract sketch for the implementation. Keep it in a
+shared contract package when code work begins.
+
+```ts
+type Money = {
+  amountMinor: number;
+  currency: string;
+};
+
+type PaymentCapabilities = {
+  onlinePayment: boolean;
+  delayedCapture: boolean;
+  savedPaymentMethod: boolean;
+  offSessionCharge: boolean;
+  refunds: boolean;
+  partialRefunds: boolean;
+  terminal: boolean;
+  connectedAccounts: boolean;
+  webhookVerification: boolean;
+};
+
+type PaymentGateway = {
+  id: string;
+  capabilities(): Promise<PaymentCapabilities>;
+  health(): Promise<{ configured: boolean; capabilities: string[]; reason?: string }>;
+  createPayment(input: CreatePaymentInput): Promise<PaymentAction>;
+  getPayment(input: GetPaymentInput): Promise<PaymentSnapshot>;
+  cancelPayment(input: CancelPaymentInput): Promise<PaymentSnapshot>;
+  refundPayment(input: RefundPaymentInput): Promise<RefundSnapshot>;
+  savePaymentMethod?(input: SavePaymentMethodInput): Promise<SavedMethodSnapshot>;
+  chargeSavedMethod?(input: ChargeSavedMethodInput): Promise<PaymentAction>;
+  createTerminalPayment?(input: TerminalPaymentInput): Promise<PaymentAction>;
+  verifyWebhook(input: VerifyWebhookInput): Promise<VerifiedPaymentEvent>;
+};
+```
+
+Every input carries `tenantId`, `bookingId` or another local aggregate ID,
+`correlationId`, a scope-specific idempotency key, money, and a purpose. The
+adapter maps local IDs to provider metadata without exposing internal secrets.
+
+## 4. Service payment policies and normalized purposes
+
+Each service variant may declare one provider-neutral payment policy:
+
+| Policy | Initial due | Booking after initial capture | Remaining balance |
+|---|---:|---|---:|
+| `full` | 100% | confirmed when captured | zero after capture |
+| `deposit` | configured amount or percentage | confirmed after deposit capture | total minus captured amount |
+| `pay_later` | zero online | confirmed without online payment | payable at the appointment |
+| `no_payment` | zero | confirmed without payment | zero |
+
+The policy is stored on the booking as a snapshot. A payment attempt is labelled
+with `deposit`, `balance`, `full`, or `adjustment`; the worker and payment
+repository aggregate successful attempts and pending/successful refunds into
+`paidMinor`, `balanceDueMinor`, and `paymentStatus`. A later balance attempt
+is rejected when it exceeds the current balance. Idempotency replay is resolved
+before mutable balance validation, so retries return the original provider
+action safely.
+
+```text
+deposit
+balance
+full
+adjustment
+no_show_fee
+package_purchase
+membership
+gift_card
+```
+
+The first booking release implements `deposit`, `balance`, `full`, and
+`adjustment`. The additional purposes remain documented extension points so
+later features do not fork the payment model.
+
+Treatment package balances do not use `package_purchase` as a booking payment
+attempt. A customer package purchase is its own payment aggregate: the public
+checkout creates a pending purchase, Stripe/webhooks reconcile it, and a
+succeeded purchase atomically creates the customer entitlement. Managers can
+also grant an entitlement manually; redemption remains atomic and no money is
+implied by that redemption. Package refunds are blocked after any visit has
+been redeemed and cancel an unredeemed entitlement when the provider refund is
+accepted.
+
+## 5. Stripe adapter responsibilities
+
+The `StripePaymentGateway` should:
+
+- create or reuse the configured Stripe customer mapping server-side;
+- create a provider payment object for the normalized amount and currency;
+- pass a local idempotency key to each mutating Stripe request;
+- return `action_required`, `processing`, `paid`, or `failed` without exposing
+  raw provider objects to the browser;
+- verify webhook signatures before parsing an event;
+- map provider events into normalized events;
+- make refund and partial refund requests idempotent;
+- support a connected-account context only when the tenant's payment account
+  configuration explicitly enables it;
+- report capability and health separately from booking configuration;
+- never store card numbers, CVC, or full payment method payloads.
+
+For new flows, the adapter should use Checkout Sessions or PaymentIntents. A
+SetupIntent is appropriate only when the customer has explicitly consented to a
+future charge. The adapter must pin the account/server API version, test
+upgrades in a sandbox, and avoid introducing new code on the legacy Charges
+API. Stripe's effective API version is account-scoped; see the official
+[versioning guidance](https://docs.stripe.com/api/versioning).
+
+The host owns secret loading. The dashboard receives only a client-safe action
+token or URL where the chosen payment flow needs one.
+
+## 6. Cancellation settlement and Resend hand-off
+
+An allowed cancellation is a two-stage operation:
+
+1. Booking commits the lifecycle transition and releases allocations.
+2. The PostgreSQL settlement seam reads captured attempts and prior refunds,
+   calculates the policy-safe full/deposit amount, and calls the injected
+   provider with a booking/payment-attempt idempotency key.
+
+The booking remains cancelled if Stripe is unavailable. The result is bounded
+as `manual_required`, so operators can retry from the payment/refund workspace
+without treating a provider outage as a successful refund. The host queues the
+`payment.refunded` intent into the existing tenant-scoped notification outbox
+only when the provider returns `pending` or `succeeded`; the Resend worker owns
+delivery, retry, and dead-letter handling.
+
+No-show fee calculation is deliberately separate from charging. The local
+implementation exposes an explicit manager/finance adjustment route that
+requires saved-payment-method consent, provider capability checks, and
+confirmation. A status transition never charges automatically; pending or
+failed provider results remain `manual_required`/pending and do not queue a
+success notification.
+
+MaggieDash's `backend/booking/stripe-adapter.mjs` implements this boundary
+without importing the Stripe SDK. The host passes `createClient(secret,
+{apiVersion})`, `getSecret`, `getWebhookSecret`, and optional connected-account
+scope. The adapter exposes normalized payment/read/refund/webhook operations;
+it never serializes the secret or raw webhook body into a response.
+
+## 6. Payment and booking are separate
+
+Examples of valid combinations:
+
+| Booking status | Payment status | Meaning |
+|---|---|---|
+| confirmed | not_required | Manager or policy allows no payment |
+| confirmed | partially_paid | Deposit captured, balance due |
+| pending_payment | action_required | Customer must complete authentication |
+| confirmed | refund_pending | Booking cancelled, provider refund is not final |
+| cancelled | refunded | Booking released and money returned |
+| completed | paid | Full visit and payment complete |
+
+No provider status should be copied into the booking status field.
+
+## 7. Webhook and reconciliation flow
+
+1. Receive the provider request on a server-only endpoint.
+2. Resolve the provider account and verify the signature with the correct
+   secret.
+3. Extract provider event ID and reject or acknowledge duplicates using the
+   unique event record.
+4. Map the event to a local payment attempt or store it as unmatched for safe
+   review.
+5. Apply the normalized payment projection in a transaction.
+6. Re-evaluate the associated booking/hold transition with current state and
+   policy.
+7. Append payment, booking, audit, and outbox events.
+8. Return a bounded success response; retryable failures remain visible to the
+   worker.
+
+The customer return URL can request a provider read, but it cannot mark a
+payment paid without this reconciliation path.
+
+## 8. Refund rules
+
+- The local captured total is the upper bound for all refunds.
+- A refund request creates a local `refund_pending` record before the provider
+  call when the operation is asynchronous.
+- The same refund idempotency key returns the original refund record.
+- A provider rejection is recorded as `refund_failed` with a safe reason.
+- Partial refunds preserve the remaining refundable amount.
+- Cancellation policy, reason, actor, and policy version are stored locally.
+- A no-show transition returns a bounded `review_required` fee preview from the
+  booking-scoped policy. It never creates a refund item or calls the provider;
+  charging a no-show fee requires a separate explicit manager/finance action,
+  customer consent, a saved provider payment method, and verified provider
+  off-session capability.
+
+## 9. Future provider onboarding
+
+Adding a provider requires:
+
+1. Implement the port without changing booking tables or transitions.
+2. Declare capabilities and configuration names.
+3. Add success, missing-credentials, timeout, duplicate, out-of-order event,
+   refund, and unsupported-capability fixtures.
+4. Run provider contract and conformance tests.
+5. Add a redacted health report and operator-facing setup errors.
+6. Add a migration only if the provider needs a new generic external reference,
+   never a provider-specific booking column.
+
+The first candidate after Stripe can be Square if merchant demand requires it.
+Provider choice does not change the local availability or booking engine.
+
+## 10. Configuration shape
+
+```json
+{
+  "payment": {
+    "defaultProvider": "stripe",
+    "mode": "test",
+    "accountScope": "tenant",
+    "capturePolicy": "automatic",
+    "capabilitiesRequired": ["onlinePayment", "refunds"]
+  }
+}
+```
+
+This is metadata only. Actual secrets use server runtime configuration, secret
+manager references, or encrypted host storage. No secret belongs in this JSON,
+the dashboard bundle, a fixture, or an issue report.

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

@@ -0,0 +1,228 @@
+# Booking workspace PRD
+
+Status: local implementation delivered; real-host release evidence pending
+Owner: MaggieDash / ai-cmo-skills
+Target route: `/_maggie/booking`
+Authentication: host-owned email/password session
+First payment adapter: Stripe
+First release posture: single business or small multi-location tenant, provider-neutral core
+
+## 1. Product summary
+
+MaggieDash currently gives a store manager an admin workspace for site content,
+services, SEO, activity, navigation, media, and AI-assisted operations. This
+project adds a separate Booking workspace where a manager can configure the
+business, staff, services, resources, availability, payment rules, bookings,
+customers, notifications, and reports.
+
+The product must support a real booking lifecycle rather than only linking to a
+third-party booking page. It must prevent double booking under concurrent
+requests, reconcile asynchronous payment events, and retain an audit trail for
+every material change.
+
+## 2. Problem
+
+Store managers currently need to stitch together service pages, a booking
+provider, a payment dashboard, a calendar, email tools, and spreadsheets. This
+creates four user-visible failures:
+
+1. The published availability does not match staff, resource, or closure rules.
+2. A customer pays but the booking is not confirmed, or two customers pay for
+   the same slot.
+3. A manager cannot see the operational day in one place.
+4. Adding a second payment provider would require changing booking business
+   logic and UI code.
+
+## 3. Goals
+
+- Give a manager one authenticated workspace at `/_maggie/booking`.
+- Provide a correct service, staff, resource, schedule, availability, hold,
+  booking, payment, and customer model.
+- Make the payment provider replaceable through a stable internal port.
+- Keep Stripe-specific objects behind the Stripe adapter.
+- Make all writes idempotent, auditable, and safe to retry.
+- Expose provider capabilities honestly. Unsupported operations fail closed.
+- Provide ai-cmo-skills contracts, fixtures, validators, and release gates for
+  host integration.
+- Preserve the existing `/_maggie/admin` content and operations workspace.
+
+## 4. Non-goals for the first release
+
+- Payroll, commissions, inventory, accounting, or tax filing.
+- A marketplace, platform-led merchant-of-record flow, or public discovery
+  network.
+- Memberships, loyalty, gift-card ledgers, or advanced waitlist optimization
+  in the first production slice. The current release includes treatment
+  packages, customer entitlements, package checkout/refunds, package
+  redemption, cancellation-safe credit restoration, a tenant-scoped waitlist
+  queue, and a bounded priority/FIFO matcher with manual conversion to a real
+  booking.
+- Replacing the host's authentication, database connection, deployment, or
+  media storage.
+- Storing card numbers, CVC, or other payment credentials in the host database.
+
+These remain documented extension points, not hidden commitments.
+
+## 5. Personas
+
+| Persona | Job to be done | Success signal |
+|---|---|---|
+| Owner | Configure the business and understand revenue | Can open a day, see bookings and payment status, and audit changes |
+| Store manager | Run the day and resolve exceptions | Can create, move, cancel, refund, check in, and complete a booking safely |
+| Staff member | See assigned work and update visit status | Sees only permitted locations and can check in/out without payment access |
+| Customer | Find a valid slot and pay or reserve it | Receives one clear outcome with no duplicate charge or booking |
+| Finance/support operator | Reconcile money and recover failures | Can trace a booking to gateway attempts, refunds, webhooks, and events |
+| Host developer | Integrate MaggieDash with a project | Has typed routes, fixtures, conformance evidence, and deterministic gates |
+
+## 6. MVP user outcomes
+
+### Manager setup
+
+The manager creates a location, timezone, service, service variant, staff member,
+staff-service eligibility, working hours, and optional resource requirement. The
+workspace reports whether the configuration is bookable and names the missing
+dependency when it is not.
+
+### Customer booking
+
+The customer selects a service and location, receives slots calculated from
+the availability engine, creates a short-lived hold, completes the configured
+payment or deposit step, and receives a confirmation only after the payment
+state is verified.
+
+### Daily operations
+
+The manager views a day or week calendar, filters by staff/location/status,
+opens a booking, records check-in and completion, takes an outstanding payment,
+reschedules, cancels, or starts a refund according to policy.
+
+### Payment recovery
+
+If a gateway redirect is interrupted, the customer refreshes or returns later,
+or a webhook is delayed, the booking remains in an explicit pending state. A
+reconciliation job can safely retry the provider read without creating another
+booking or charge.
+
+The same recovery rule applies when the provider call fails after a hold has
+already been converted: the customer checkout idempotency key must replay the
+conversion, reuse the valid customer token, and retry the provider operation
+without creating a second booking.
+
+## 7. Functional requirements
+
+### Configuration
+
+| ID | Requirement | Acceptance condition |
+|---|---|---|
+| BK-CFG-01 | A tenant can manage one or more locations | Every location has an IANA timezone, locale, currency, and active flag |
+| BK-CFG-02 | A tenant can manage services and variants | Duration, price, currency, buffers, booking window, and status are explicit |
+| BK-CFG-03 | A tenant can assign staff to services and locations | Ineligible staff never appear in valid slot results |
+| BK-CFG-04 | A tenant can configure resources | A slot is unavailable when any required resource conflicts |
+| BK-CFG-05 | A tenant can configure opening hours, shifts, closures, time off, and blocks | DST, overnight hours, and exceptions have deterministic tests |
+| BK-CFG-06 | A tenant can configure payment policy | Full payment, deposit, pay-later, no-show protection, and no-payment are distinct |
+| BK-CFG-07 | A tenant can configure cancellation/refund policy | The policy version is copied to each booking at creation |
+
+Implementation note: BK-CFG-07 is implemented as a normalized catalogue policy
+with a booking-time snapshot and customer cancellation-cutoff enforcement.
+Refund execution is wired through the host provider boundary. A no-show
+transition remains review-only; a separate manager/finance action can charge a
+policy-derived fee only when the customer consented, a saved payment method
+exists, and Stripe off-session capability is verified. Live migration, provider
+acceptance, and delivery evidence remain host/provider release work.
+
+### Availability and booking
+
+| ID | Requirement | Acceptance condition |
+|---|---|---|
+| BK-BOOK-01 | Calculate availability from all applicable constraints | Results include a traceable reason for exclusion in diagnostics mode |
+| BK-BOOK-02 | Create a first-class booking hold | Hold has owner, expiry, scope, idempotency key, and release reason |
+| BK-BOOK-03 | Prevent double booking at the database boundary | Concurrent requests yield at most one active allocation |
+| BK-BOOK-04 | Create multi-service bookings with segments | Each segment has its own staff/resource allocation and time range |
+| BK-BOOK-05 | Support manager-created bookings | Manager can bypass customer payment only when policy and permission allow it |
+| BK-BOOK-06 | Support reschedule without destructive replacement | Original allocation and actor/reason remain in event history |
+| BK-BOOK-07 | Support cancellation, no-show, check-in, in-progress, and completion | Invalid transitions are rejected and visible to the operator |
+
+### Payments
+
+| ID | Requirement | Acceptance condition |
+|---|---|---|
+| BK-PAY-01 | Use a provider-neutral payment port | Booking code imports no Stripe SDK or provider object |
+| BK-PAY-02 | Support payment attempts and transactions separately | A retry never overwrites the prior attempt |
+| BK-PAY-03 | Reconcile verified provider events | Duplicate and out-of-order events are harmless |
+| BK-PAY-04 | Support deposits and outstanding balances | Booking and payment statuses remain independent |
+| BK-PAY-05 | Support refunds and partial refunds | Refund totals cannot exceed captured amount; allowed cancellation policy settlements call the provider after the lifecycle write with idempotency and a manual-review fallback |
+| BK-PAY-06 | Expose provider capability flags | UI hides or disables unsupported operations with a reason |
+| BK-PAY-07 | Support future providers without schema forks | Provider-specific IDs live in an external-object table or metadata map |
+
+The local payment slice also supports Stripe Customer mapping, saved payment
+methods for ordinary PaymentIntents, setup-only SetupIntents, and an explicit
+consented no-show fee adjustment. It does not automatically charge when a
+booking changes to `no_show`.
+
+### Public customer boundary
+
+| ID | Requirement | Acceptance condition |
+|---|---|---|
+| BK-CUSTOMER-01 | Expose public catalogue and availability safely | Public DTOs omit tenant, customer, provider, and credential internals and responses are no-store/noindex |
+| BK-CUSTOMER-02 | Create a short-lived customer hold | Request is tenant-bound, idempotent, validates email and booking-update consent, and returns an expiry without exposing internal allocation data |
+| BK-CUSTOMER-03 | Start checkout and recover payment returns | Payment return state is informational; only verified webhook/provider read changes payment truth |
+| BK-CUSTOMER-04 | Queue customer lifecycle notifications | Confirmation, cancellation, reschedule, reminder, and accepted/pending refund intents use the allowlisted outbox templates and are not duplicated on idempotent retries |
+| BK-CUSTOMER-05 | Fail closed at the public host boundary | Host supplies origin/CSRF, rate-limit, bot, persistence, and opaque return-token controls |
+
+### Workspace and reporting
+
+| ID | Requirement | Acceptance condition |
+|---|---|---|
+| BK-UI-01 | Serve a dedicated booking workspace | Route is authenticated, noindex, and visually consistent with MaggieDash |
+| BK-UI-02 | Provide overview, calendar, bookings, customers, services, staff, resources, payments, settings, and audit screens | Every screen has loading, empty, error, and permission states |
+| BK-UI-03 | Preserve filters in URL state | Reloading or sharing a permitted URL keeps the view context |
+| BK-UI-04 | Keep one scroll owner in dialogs | Long booking, refund, and configuration dialogs do not create nested page scroll |
+| BK-UI-05 | Surface pending states honestly | No UI says “confirmed” or “paid” from a redirect alone |
+| BK-UI-06 | Show audit history for material changes | Actor, reason, correlation ID, before/after summary, and timestamp are visible |
+
+## 8. Non-functional requirements
+
+| Area | Target |
+|---|---|
+| Correctness | No confirmed double allocations under the supported concurrency test |
+| Idempotency | Repeating a request with the same key returns the original result |
+| Availability | Manager read APIs degrade to a safe read-only state when optional adapters fail |
+| Performance | P95 availability query under 500 ms for the launch dataset; measure with a fixed fixture |
+| Security | No secret or payment credential in HTML, props, browser environment, logs, or audit payloads |
+| Privacy | Customer data is tenant-scoped, minimized, exportable, and deletable according to policy |
+| Accessibility | Keyboard navigation, focus management, labels, contrast, and reduced motion are tested |
+| Time | UTC instants in storage; venue timezone required for wall-clock input |
+| Observability | Correlation ID through request, booking event, payment attempt, webhook, and notification |
+| Recovery | Failed webhooks, notifications, and provider reads are retryable without duplicate business effects |
+
+## 9. Success metrics
+
+- At least 99.99% of accepted booking requests result in one and only one
+  allocation or one explicit failure outcome.
+- Zero payment-success records without a matching verified provider event or
+  provider reconciliation result.
+- Zero cross-tenant reads in automated authorization tests.
+- 100% of production payment webhooks have signature, idempotency, and replay
+  evidence.
+- A new payment adapter can pass the provider contract without changing booking
+  tables or booking state transitions.
+- A store manager can complete daily open, operate, and close flows without
+  leaving the booking workspace for normal operations.
+
+## 10. Release acceptance
+
+The MVP is not releasable until:
+
+1. Host adapter conformance passes for every required booking endpoint.
+2. Email/password login and role checks pass against a real host session.
+3. Availability, hold expiry, database conflict, and DST tests pass.
+4. Stripe test-mode payment, failed payment, duplicate webhook, delayed
+   webhook, refund, no-show adjustment, and reconciliation tests pass against
+   the real host account.
+5. Browser tests pass at desktop and mobile widths with no console errors.
+6. Security review confirms no card data or raw provider credentials reach the
+   public browser bundle. If the optional dashboard-managed Stripe path is
+   enabled, only owner/manager HTTPS submissions are accepted, verified before
+   persistence, stored as authenticated ciphertext, and never returned.
+7. A sanitized runtime evidence bundle is stored and the release gate reports
+   the exact build, schema, adapter, and fixture revisions.