Skip to content

quick-reference.md

Latest commit

 

History

History
168 lines (130 loc) · 5.28 KB

quick-reference.md

File metadata and controls

168 lines (130 loc) · 5.28 KB
Raw

Quick Reference

One-page cheat sheet. Details in linked docs.

Commerce runtime

checkout  = collect money      services.checkout
refunds   = reverse money      services.refunds
inventory = move stock         services.inventory
admin     = authorize ops      services.admin
crm       = customer truth     services.crm
support   = issue resolution   services.support
events    = committed memory   CommerceEventBus → commerce_events
timeline  = operator view      GET /api/admin/orders/:id/timeline

Rule: No route/tool calls RefundService, OrderService, or InventoryService for mutations.
Seal: src/tests/protocol-guard.test.ts
Operator guide: operator-commerce-runtime.md

Checkout methods → routes

Method Route
createCheckoutSession POST /api/checkout/create-payment-intent
recoverPendingOrder GET /api/checkout/verify
handleCheckoutWebhook POST /api/webhooks/stripe
completeCheckoutWithPaymentMethod POST /api/orders
cleanupExpiredPendingOrders POST /api/system/cleanup-orders
handleReconciliationOperatorAction POST /api/admin/reconciliation/cases

Inventory methods → callers

Method Primary caller
checkAvailability CartService
reserveInventory Checkout mutation
confirmReservation Checkout mutation
releaseReservation Checkout / cleanup / admin
adjustInventory Admin batch API
receiveStockAtLocation PurchaseOrderService
applyInventoryDeltas Refund, transfer, order admin
reconcileInventory Admin reconcile API
cleanupExpiredReservations System cleanup job

Refund entry points

Caller Path
Admin UI admin.requestRefund → refunds.createRefund({ source: 'admin' })
Concierge refunds.createRefund({ source: 'concierge' })

Required: orderId, amount, reason, idempotencyKey, actor

Result types

Protocol Type Adapter
Checkout CheckoutResult<T> checkoutRouteAdapter.ts
Inventory InventoryResult<T> inventoryRouteAdapter.ts
Refunds RefundResult<T> refundRouteAdapter.ts
Admin AdminResult<T> adminRouteAdapter.ts

Shape: { ok: true, data } or { ok: false, code, message, retryable }

Idempotency stores

Domain Collection
Stripe webhooks stripe_webhook_events
Checkout recovery checkout_recovery_attempts
Operator actions operator_action_events
Refund claims refund_execution_claims
Refund audit refund_execution_events
Admin mutations admin_mutation_claims
Inventory ledger marker entries in inventory_ledger

Key env vars

Variable Required for
SESSION_SECRET Signed cookies
FIREBASE_SERVICE_ACCOUNT_JSON Server Firestore
NEXT_PUBLIC_FIREBASE_* Client auth
STRIPE_* Payments
STRIPE_WEBHOOK_SECRET Webhook verify
SYSTEM_JOB_TOKEN Cleanup cron routes
GEMINI_API_KEY Concierge (optional)
NEXT_PUBLIC_E2E_MOCK_CHECKOUT 1 — shows Mock Pay button in checkout (E2E only)

Storefront runtime (frozen)

catalog/PDP  = read intent
cart         = purchase intent buffer   services.cart
checkout     = commitment gate          services.checkout
inventory    = scarcity (reserve)       services.inventory @ checkout only
payment      = money capture            services.checkout + Stripe webhook

Storefront gate: npm run test:storefront-release (125 tests)
Checkout smoke: npm run test:e2e:checkout-smoke (3 tests)
Detail: storefront-release.md

Verification (fast)

npm run test:storefront-release
npm test -- --run src/tests/protocol-guard.test.ts
npm test -- --run src/tests/checkout-verification-ladder.test.ts
npm test -- --run src/tests/inventory-verification-ladder.test.ts
npm test -- --run src/tests/refund-verification-ladder.test.ts
npm test -- --run src/tests/admin-verification-ladder.test.ts
npm run test:e2e:checkout-smoke

Dev shortcuts

Task Command / URL
Setup npm run setup
Dev server npm run dev
Dev + E2E mock pay button npm run dev:e2e
Storefront proof suite npm run test:storefront-release
Checkout E2E smoke npm run test:e2e:checkout-smoke
Clear stuck port 3000 npm run cleanup
Stripe webhooks local stripe listen --forward-to localhost:3000/api/webhooks/stripe
Admin login admin@woodbine.com / admin-password-123 (local only)
Test card 4242 4242 4242 4242

Doc index

Need Doc
First run onboarding.md
Debug troubleshooting.md
Flows flows.md
Extend code contributing-commerce.md
All protocols protocols.md
Env vars environment-variables.md
Local dev local-development.md
Rebrand customization.md
Release release-checklist.md
Terms glossary.md
Full index index.md