Documentation Index
Fetch the complete documentation index at: https://docs.mareaalcalina.com/llms.txt
Use this file to discover all available pages before exploring further.
Changelog
Improved — comprehensive docs audit + Stripe-style cleanup.Following the first public publish, a senior-engineer pass cross-checked every claim in the docs against the cloud-functions Zod contracts as ground truth.
- API Reference now covers all 13 v1 operations (previously a Phase-1 stub with
/v1/meonly).openapi.jsonis script-generated from the cloud-functions Zod schemas via@asteasolutions/zod-to-openapi(zero drift): tags, operationIds, both security schemes (Bearer + X-API-Key), rate-limit response headers, idempotency headers, and full$reftoApiErrorResponseon every 4xx/5xx. - Stripe-style URL slugs. API reference pages now ship at clean URLs like
/api/storefronts/create-storefrontand/api/identity/get-current-identity(previously they were verbose auto-slugified sentences). - Plan limits corrected.
plan.limitsshape is{storefronts, products, publishable}(not the docs’ previous{maxStorefronts, maxProducts, canPublish}invention). Free plan has two variants (FREE_NEW1 storefront,FREE_OLDlegacy 3 storefronts). Pre-paywall accounts have a 2,000 draft-product cap. Single-product POST returnsplan_max_products_reached, notproducts_over_limit(the latter is the 207-batch path). - Scopes corrected. Eight real scopes:
developer:bootstrap,developer:read,developer:issueUserKey,catalog:read,catalog:write,storefront:publish,me:verify,me:resendVerification. Earlier docs referenced a non-existentusers:bootstrap— now removed everywhere. - Error codes: ~40 real
error.codevalues cross-checked againstgrep ApiErroracrosssrc/api/. Removed three fabricated codes (validation_failed,product_not_found,rpd_exceeded-as-code) that the docs invented; replaced with the real ones (invalid_request_body,storefront_not_found,rate_limit_exceeded).rpd_exceeded/rpm_exceededcontinue to surface insideerror.messageonly. - MCP quickstart: install path now uses the
mcp-remotebridge (verified package). Tool count corrected to 7 (verify + resend are REST-only by design). - Four concept pages that were placeholders are now real content:
verification-flow,tos-jurisdiction,arco-procedures,versioning. Each is sourced from cloud-functions handlers, with TTLs, lockouts, cancel reasons, and breaking-change rules from code. - Homepage: removed redundant H1 + intro paragraph that duplicated frontmatter title/description (Mintlify renders both automatically). Added a “Webhook surfaces” CardGroup so first-time readers see both surfaces.
- Receiver helpers:
concepts/webhooks↔concepts/page-webhooksnow both ship full JS + Python verifiers inapi/webhooks/*.mdx, with theX-Marea-Source(developervsmerchant) header disambiguating endpoints that serve both surfaces.
Added — Page webhooks: real-time order events for merchant POS / Zapier / Make.com / accounting integrations.A new merchant-configured webhook surface, distinct from the developer-configured Agent webhooks. Three event types ship:
If your single endpoint serves both surfaces, branch on
order.created— fires on checkout completion (whenorderStatustransitions topendingand apublicOrderIdis assigned). Carries the full order: items, pricing, customer, delivery, payment method.order.status_updated— fires on every order-status transition (e.g.pending→inProgress→completed, plus any custom-pipeline transitions). Slim payload —previousState → newStateonly; receivers cacheorder.createdand merge byorderId.order.paid— fires on Stripe Checkout success or PayPal capture success. Finance-focused payload with provider reconciliation IDs (stripeCheckoutSessionId,paypalCaptureId, etc.) and no customer PII.
/menus/profile?section=integrations. Marea generates a 32-byte HMAC signing secret on first save and reveals it once.Differs from Agent webhooks:| Agent webhooks | Page webhooks | |
|---|---|---|
| Configured by | Developer (in /developers/webhooks) | Merchant (in /menus/profile?section=integrations) |
| Events | user.verified, user.cancelled | order.created, order.status_updated, order.paid |
| Signing key | HKDF-SHA256 from apiKeys/{keyId}.keyHash | Raw 32-byte hex from users/{uid}.webhookSigningSecret |
| Header to disambiguate | X-Marea-Source: developer | X-Marea-Source: merchant |
X-Marea-Source to pick the right verification path.Same retry semantics as Agent webhooks: 3 attempts (immediate / +30s / +5min); 5-second timeout per attempt; 5-minute replay window on the t= timestamp. Dead-letters surface in the merchant’s recent-deliveries log (last 50 entries, rolling 30-day window).Receiver code: ready-to-paste JS + Python verifier at /api/webhooks/page-webhook-helpers.Concept page: /concepts/page-webhooks.Rollout: default-OFF in production behind a server-side flag; per-merchant overrides during canary. Friendly-merchant cohort onboarding before fleet-wide enable.