@topy-ai/maggie 0.7.52 → 0.7.53

package/bundled-contracts/maggiedash/stripe-booking-capabilities-v1.json

@@ -12,41 +12,346 @@
     "avoidChargesForNewFlows": true
   },
   "x-api-matrix": [
-    { "id": "customers", "status": "core", "resource": "Customer", "operations": ["POST /v1/customers", "GET /v1/customers/:id", "POST /v1/customers/:id"], "bookingUse": "customer mapping and receipts", "officialDocs": ["https://docs.stripe.com/api/customers"] },
-    { "id": "checkout_sessions", "status": "core", "resource": "Checkout Session", "operations": ["POST /v1/checkout/sessions", "GET /v1/checkout/sessions/:id", "POST /v1/checkout/sessions/:id/expire"], "bookingUse": "hosted or embedded one-off booking payments", "officialDocs": ["https://docs.stripe.com/api/checkout/sessions"] },
-    { "id": "payment_intents", "status": "core", "resource": "PaymentIntent", "operations": ["POST /v1/payment_intents", "GET /v1/payment_intents/:id", "POST /v1/payment_intents/:id/confirm", "POST /v1/payment_intents/:id/cancel", "POST /v1/payment_intents/:id/capture"], "bookingUse": "custom payment UI, SCA, capture, reconciliation", "officialDocs": ["https://docs.stripe.com/api/payment_intents"] },
-    { "id": "setup_intents", "status": "optional", "resource": "SetupIntent", "operations": ["POST /v1/setup_intents", "GET /v1/setup_intents/:id", "POST /v1/setup_intents/:id/confirm"], "bookingUse": "consented saved payment methods", "officialDocs": ["https://docs.stripe.com/api/setup_intents"] },
-    { "id": "refunds", "status": "core", "resource": "Refund", "operations": ["POST /v1/refunds", "GET /v1/refunds/:id", "POST /v1/refunds/:id/cancel"], "bookingUse": "full and partial refunds", "officialDocs": ["https://docs.stripe.com/api/refunds"] },
-    { "id": "events", "status": "core", "resource": "Event", "operations": ["GET /v1/events/:id", "GET /v1/events"], "bookingUse": "event identity and reconciliation", "officialDocs": ["https://docs.stripe.com/api/events", "https://docs.stripe.com/api/events/types"] },
-    { "id": "promotion_codes", "status": "optional", "resource": "Promotion Code", "operations": ["POST /v1/promotion_codes", "GET /v1/promotion_codes/:id", "GET /v1/promotion_codes"], "bookingUse": "campaign and referral discount codes", "officialDocs": ["https://docs.stripe.com/api/promotion_codes"] },
-    { "id": "coupons", "status": "optional", "resource": "Coupon", "operations": ["POST /v1/coupons", "GET /v1/coupons/:id", "DELETE /v1/coupons/:id"], "bookingUse": "reusable discounts", "officialDocs": ["https://docs.stripe.com/api/coupons"] },
-    { "id": "customer_balance_transactions", "status": "optional", "resource": "Customer Balance Transaction", "operations": ["POST /v1/customers/:id/balance_transactions", "GET /v1/customers/:id/balance_transactions"], "bookingUse": "invoice credit, not gift-card redemption", "officialDocs": ["https://docs.stripe.com/api/customer_balance_transactions"] },
-    { "id": "subscriptions", "status": "future", "resource": "Subscription", "operations": ["POST /v1/subscriptions", "GET /v1/subscriptions/:id", "POST /v1/subscriptions/:id"], "bookingUse": "future memberships", "officialDocs": ["https://docs.stripe.com/api/subscriptions"] },
-    { "id": "invoices", "status": "future", "resource": "Invoice", "operations": ["POST /v1/invoices", "GET /v1/invoices/:id", "POST /v1/invoices/:id/finalize"], "bookingUse": "future business invoicing", "officialDocs": ["https://docs.stripe.com/api/invoices"] },
-    { "id": "customer_portal_sessions", "status": "future", "resource": "Billing Portal Session", "operations": ["POST /v1/billing_portal/sessions"], "bookingUse": "future customer self-service billing", "officialDocs": ["https://docs.stripe.com/api/customer_portal/sessions"] },
-    { "id": "tax", "status": "optional", "resource": "Tax Calculation/Transaction", "operations": ["POST /v1/tax/calculations", "POST /v1/tax/transactions/create_from_calculation", "POST /v1/tax/transactions/create_reversal"], "bookingUse": "optional VAT/tax calculation", "officialDocs": ["https://docs.stripe.com/tax/payment_intent", "https://docs.stripe.com/api/tax/transactions"] },
-    { "id": "terminal", "status": "future", "resource": "Terminal PaymentIntent", "operations": ["POST /v1/terminal/readers", "POST /v1/terminal/readers/:id/process_payment_intent"], "bookingUse": "future in-person payments", "officialDocs": ["https://docs.stripe.com/terminal/payments"] },
-    { "id": "connect", "status": "future", "resource": "Connected Account", "operations": ["POST /v1/accounts", "POST /v1/account_links", "POST /v1/transfers"], "bookingUse": "future multi-merchant platforms only", "officialDocs": ["https://docs.stripe.com/connect"] }
+    {
+      "id": "customers",
+      "status": "core",
+      "resource": "Customer",
+      "operations": [
+        "POST /v1/customers",
+        "GET /v1/customers/:id",
+        "POST /v1/customers/:id"
+      ],
+      "bookingUse": "customer mapping and receipts",
+      "officialDocs": [
+        "https://docs.stripe.com/api/customers"
+      ]
+    },
+    {
+      "id": "checkout_sessions",
+      "status": "core",
+      "resource": "Checkout Session",
+      "operations": [
+        "POST /v1/checkout/sessions",
+        "GET /v1/checkout/sessions/:id",
+        "POST /v1/checkout/sessions/:id/expire"
+      ],
+      "bookingUse": "hosted or embedded one-off booking payments",
+      "officialDocs": [
+        "https://docs.stripe.com/api/checkout/sessions"
+      ]
+    },
+    {
+      "id": "payment_intents",
+      "status": "core",
+      "resource": "PaymentIntent",
+      "operations": [
+        "POST /v1/payment_intents",
+        "GET /v1/payment_intents/:id",
+        "POST /v1/payment_intents/:id/confirm",
+        "POST /v1/payment_intents/:id/cancel",
+        "POST /v1/payment_intents/:id/capture"
+      ],
+      "bookingUse": "custom payment UI, SCA, capture, reconciliation",
+      "officialDocs": [
+        "https://docs.stripe.com/api/payment_intents"
+      ]
+    },
+    {
+      "id": "setup_intents",
+      "status": "optional",
+      "resource": "SetupIntent",
+      "operations": [
+        "POST /v1/setup_intents",
+        "GET /v1/setup_intents/:id",
+        "POST /v1/setup_intents/:id/confirm"
+      ],
+      "bookingUse": "consented saved payment methods",
+      "officialDocs": [
+        "https://docs.stripe.com/api/setup_intents"
+      ]
+    },
+    {
+      "id": "refunds",
+      "status": "core",
+      "resource": "Refund",
+      "operations": [
+        "POST /v1/refunds",
+        "GET /v1/refunds/:id",
+        "POST /v1/refunds/:id/cancel"
+      ],
+      "bookingUse": "full and partial refunds",
+      "officialDocs": [
+        "https://docs.stripe.com/api/refunds"
+      ]
+    },
+    {
+      "id": "events",
+      "status": "core",
+      "resource": "Event",
+      "operations": [
+        "GET /v1/events/:id",
+        "GET /v1/events"
+      ],
+      "bookingUse": "event identity and reconciliation",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events",
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "id": "promotion_codes",
+      "status": "optional",
+      "resource": "Promotion Code",
+      "operations": [
+        "POST /v1/promotion_codes",
+        "GET /v1/promotion_codes/:id",
+        "GET /v1/promotion_codes"
+      ],
+      "bookingUse": "campaign and referral discount codes",
+      "officialDocs": [
+        "https://docs.stripe.com/api/promotion_codes"
+      ]
+    },
+    {
+      "id": "coupons",
+      "status": "optional",
+      "resource": "Coupon",
+      "operations": [
+        "POST /v1/coupons",
+        "GET /v1/coupons/:id",
+        "DELETE /v1/coupons/:id"
+      ],
+      "bookingUse": "reusable discounts",
+      "officialDocs": [
+        "https://docs.stripe.com/api/coupons"
+      ]
+    },
+    {
+      "id": "customer_balance_transactions",
+      "status": "optional",
+      "resource": "Customer Balance Transaction",
+      "operations": [
+        "POST /v1/customers/:id/balance_transactions",
+        "GET /v1/customers/:id/balance_transactions"
+      ],
+      "bookingUse": "invoice credit, not gift-card redemption",
+      "officialDocs": [
+        "https://docs.stripe.com/api/customer_balance_transactions"
+      ]
+    },
+    {
+      "id": "subscriptions",
+      "status": "optional",
+      "resource": "Subscription",
+      "operations": [
+        "POST /v1/subscriptions",
+        "GET /v1/subscriptions/:id",
+        "POST /v1/subscriptions/:id"
+      ],
+      "bookingUse": "memberships billed monthly on the business's connected account, pause/resume",
+      "officialDocs": [
+        "https://docs.stripe.com/api/subscriptions"
+      ]
+    },
+    {
+      "id": "invoices",
+      "status": "future",
+      "resource": "Invoice",
+      "operations": [
+        "POST /v1/invoices",
+        "GET /v1/invoices/:id",
+        "POST /v1/invoices/:id/finalize"
+      ],
+      "bookingUse": "future business invoicing",
+      "officialDocs": [
+        "https://docs.stripe.com/api/invoices"
+      ]
+    },
+    {
+      "id": "customer_portal_sessions",
+      "status": "future",
+      "resource": "Billing Portal Session",
+      "operations": [
+        "POST /v1/billing_portal/sessions"
+      ],
+      "bookingUse": "future customer self-service billing",
+      "officialDocs": [
+        "https://docs.stripe.com/api/customer_portal/sessions"
+      ]
+    },
+    {
+      "id": "tax",
+      "status": "optional",
+      "resource": "Tax Calculation/Transaction",
+      "operations": [
+        "POST /v1/tax/calculations",
+        "POST /v1/tax/transactions/create_from_calculation",
+        "POST /v1/tax/transactions/create_reversal"
+      ],
+      "bookingUse": "optional VAT/tax calculation",
+      "officialDocs": [
+        "https://docs.stripe.com/tax/payment_intent",
+        "https://docs.stripe.com/api/tax/transactions"
+      ]
+    },
+    {
+      "id": "terminal",
+      "status": "optional",
+      "resource": "Terminal PaymentIntent",
+      "operations": [
+        "POST /v1/terminal/readers",
+        "POST /v1/terminal/readers/:id/process_payment_intent"
+      ],
+      "bookingUse": "in-person payments: server-driven readers per branch location, simulated reader for tests, Tap to Pay in the native app",
+      "officialDocs": [
+        "https://docs.stripe.com/terminal/payments"
+      ]
+    },
+    {
+      "id": "connect",
+      "status": "platform",
+      "resource": "Connected Account",
+      "operations": [
+        "POST /v2/core/accounts",
+        "POST /v2/core/account_links",
+        "POST /v1/checkout/sessions (Stripe-Account)",
+        "POST /v1/refunds (Stripe-Account)",
+        "GET /v1/payouts (Stripe-Account)",
+        "GET /v1/disputes (Stripe-Account)"
+      ],
+      "bookingUse": "multi-tenant booking platforms: direct charges on each business's connected account (Stripe-Account header), no application fee option, Accounts v2 onboarding, thin-event destinations, per-account webhook checks",
+      "officialDocs": [
+        "https://docs.stripe.com/connect"
+      ]
+    }
   ],
   "x-webhook-events": [
-    { "eventType": "checkout.session.completed", "requiredFor": "hosted checkout completion", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "checkout.session.expired", "requiredFor": "release an unpaid pending booking when its hosted Checkout expires", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "checkout.session.async_payment_succeeded", "requiredFor": "delayed payment completion", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "checkout.session.async_payment_failed", "requiredFor": "delayed payment failure", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "payment_intent.processing", "requiredFor": "payment pending", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "payment_intent.payment_failed", "requiredFor": "payment failure", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "payment_intent.succeeded", "requiredFor": "payment confirmation", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "payment_intent.requires_action", "requiredFor": "customer action", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "payment_intent.canceled", "requiredFor": "payment cancellation", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "refund.created", "requiredFor": "refund projection", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "refund.updated", "requiredFor": "refund status changes", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "refund.failed", "requiredFor": "refund failure", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "setup_intent.succeeded", "requiredFor": "saved method setup", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "setup_intent.setup_failed", "requiredFor": "saved method failure", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "invoice.paid", "requiredFor": "future recurring billing", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "invoice.payment_failed", "requiredFor": "future recurring billing failure", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "customer.subscription.updated", "requiredFor": "future membership state", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
-    { "eventType": "customer.subscription.deleted", "requiredFor": "future membership cancellation", "officialDocs": ["https://docs.stripe.com/api/events/types"] }
+    {
+      "eventType": "checkout.session.completed",
+      "requiredFor": "hosted checkout completion",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "checkout.session.expired",
+      "requiredFor": "release an unpaid pending booking when its hosted Checkout expires",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "checkout.session.async_payment_succeeded",
+      "requiredFor": "delayed payment completion",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "checkout.session.async_payment_failed",
+      "requiredFor": "delayed payment failure",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "payment_intent.processing",
+      "requiredFor": "payment pending",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "payment_intent.payment_failed",
+      "requiredFor": "payment failure",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "payment_intent.succeeded",
+      "requiredFor": "payment confirmation",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "payment_intent.requires_action",
+      "requiredFor": "customer action",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "payment_intent.canceled",
+      "requiredFor": "payment cancellation",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "refund.created",
+      "requiredFor": "refund projection",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "refund.updated",
+      "requiredFor": "refund status changes",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "refund.failed",
+      "requiredFor": "refund failure",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "setup_intent.succeeded",
+      "requiredFor": "saved method setup",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "setup_intent.setup_failed",
+      "requiredFor": "saved method failure",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "invoice.paid",
+      "requiredFor": "future recurring billing",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "invoice.payment_failed",
+      "requiredFor": "future recurring billing failure",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "customer.subscription.updated",
+      "requiredFor": "future membership state",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    },
+    {
+      "eventType": "customer.subscription.deleted",
+      "requiredFor": "future membership cancellation",
+      "officialDocs": [
+        "https://docs.stripe.com/api/events/types"
+      ]
+    }
   ],
   "x-native-capabilities": {
     "giftCards": "not-native",
@@ -59,11 +364,65 @@
     "connect": "native"
   },
   "x-ecosystem-integrations": [
-    { "id": "gift-up", "category": "gift-cards", "kind": "stripe-app", "status": "evaluate", "officialDocs": ["https://marketplace.stripe.com/apps/gift-up"], "maggieDecision": "separate partner gift-card system; retain local reference and reconciliation" },
-    { "id": "partnerstack", "category": "affiliate-and-referrals", "kind": "stripe-app", "status": "evaluate", "officialDocs": ["https://marketplace.stripe.com/apps/partnerstack"], "maggieDecision": "affiliate payout candidate; local referral attribution remains authoritative" },
-    { "id": "stripe-apps", "category": "business-operations", "kind": "stripe-product", "status": "recommended", "officialDocs": ["https://stripe.com/apps"], "maggieDecision": "prefer reviewed apps for accounting, CRM, support, analytics, and automation" },
-    { "id": "stripe-tax", "category": "tax", "kind": "stripe-product", "status": "evaluate", "officialDocs": ["https://docs.stripe.com/tax"], "maggieDecision": "enable only after jurisdiction and tax ownership review" },
-    { "id": "stripe-terminal", "category": "in-person-payments", "kind": "stripe-product", "status": "future", "officialDocs": ["https://docs.stripe.com/terminal"], "maggieDecision": "future reader operations" },
-    { "id": "stripe-connect", "category": "multi-merchant", "kind": "stripe-product", "status": "future", "officialDocs": ["https://docs.stripe.com/connect"], "maggieDecision": "future platform-only capability" }
+    {
+      "id": "gift-up",
+      "category": "gift-cards",
+      "kind": "stripe-app",
+      "status": "evaluate",
+      "officialDocs": [
+        "https://marketplace.stripe.com/apps/gift-up"
+      ],
+      "maggieDecision": "separate partner gift-card system; retain local reference and reconciliation"
+    },
+    {
+      "id": "partnerstack",
+      "category": "affiliate-and-referrals",
+      "kind": "stripe-app",
+      "status": "evaluate",
+      "officialDocs": [
+        "https://marketplace.stripe.com/apps/partnerstack"
+      ],
+      "maggieDecision": "affiliate payout candidate; local referral attribution remains authoritative"
+    },
+    {
+      "id": "stripe-apps",
+      "category": "business-operations",
+      "kind": "stripe-product",
+      "status": "recommended",
+      "officialDocs": [
+        "https://stripe.com/apps"
+      ],
+      "maggieDecision": "prefer reviewed apps for accounting, CRM, support, analytics, and automation"
+    },
+    {
+      "id": "stripe-tax",
+      "category": "tax",
+      "kind": "stripe-product",
+      "status": "evaluate",
+      "officialDocs": [
+        "https://docs.stripe.com/tax"
+      ],
+      "maggieDecision": "enable only after jurisdiction and tax ownership review"
+    },
+    {
+      "id": "stripe-terminal",
+      "category": "in-person-payments",
+      "kind": "stripe-product",
+      "status": "future",
+      "officialDocs": [
+        "https://docs.stripe.com/terminal"
+      ],
+      "maggieDecision": "future reader operations"
+    },
+    {
+      "id": "stripe-connect",
+      "category": "multi-merchant",
+      "kind": "stripe-product",
+      "status": "future",
+      "officialDocs": [
+        "https://docs.stripe.com/connect"
+      ],
+      "maggieDecision": "future platform-only capability"
+    }
   ]
 }

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

@@ -46,17 +46,28 @@ creates four user-visible failures:
   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.
+## 4. Scope boundaries
+
+Shipped as contracts (rules with shared test vectors in
+[RULES.md](./RULES.md), `maggie booking rules-vectors`) that hosts implement:
+the booking state machine, late payment after an expired hold, venue-time
+schedule inputs, money in minor units, till/checkout maths with tips and
+service charge, payment-policy setup validation, reminders and notices,
+`.ics`, availability rules (split hours, rotas, per-staff durations, gaps,
+groups, peak pricing), team roles and permissions with PIN switching, client
+safety (patch tests, blocked clients), loyalty and memberships, team pay
+(commissions, time clock), and customer accounts. The gift voucher ledger is
+fixed by the [voucher lifecycle contract](./VOUCHERS.md) (0.7.48). A platform
+that hosts many businesses uses Stripe Connect direct charges
+([STRIPE-INTEGRATION.md](./STRIPE-INTEGRATION.md#platform-hosts-stripe-connect)).
+
+Still out of scope for the MaggieDash manager UI itself:
+
+- Payroll filing, tax filing and inventory management (pay runs export to
+  accounting tools instead).
+- Being the merchant of record for businesses: a platform host uses direct
+  charges so each business stays the merchant.
+- Advanced waitlist optimisation beyond the bounded priority/FIFO matcher.
 - Replacing the host's authentication, database connection, deployment, or
   media storage.
 - Storing card numbers, CVC, or other payment credentials in the host database.