Current source-backed gateway, commerce, app marketplace, theme package, and webhook surfaces. Missing OpenAPI generation remains explicitly skipped.
Current gateway behavior from services/api-gateway/src/index.ts.
Common success, pagination, error, and correlation header behavior from the current gateway helpers.
| Response case | Current shape | Developer handling | Source |
|---|---|---|---|
| Standard success envelope | { success: true, data, ...meta } | Use data as the payload. Extra top-level metadata can appear when a route passes helper metadata. | services/api-gateway/src/lib/supabase.ts:32 |
| Paginated success envelope | { success: true, data, meta: { page, per_page, total, total_pages, has_next, has_prev } } | Read list navigation from meta; page and limit come from route query validation where present. | services/api-gateway/src/lib/supabase.ts:39 |
| Helper error envelope | { success: false, error: { code, message, status } } | Use HTTP status as authority and read error.code for programmatic branching. | services/api-gateway/src/lib/supabase.ts:58 |
| Compatibility error bodies | { error: { code, message } } or { success: false, error: { code, message } } | Some helpers omit success, so clients should branch on the error object and status instead of relying only on success=false. | services/api-gateway/src/lib/supabase.ts:70 |
| Typed application errors | { error: { code, message, details? } } with the AppError status code | Known validation, not-found, forbidden, conflict, and stock errors are sanitized by the global handler. | services/api-gateway/src/lib/errors.ts:66 + services/api-gateway/src/index.ts:233 |
| Unexpected internal errors | { error: { code: "INTERNAL_ERROR", message: "An internal error occurred", request_id } } | Full details stay server-side; use request_id for support and trace correlation. | services/api-gateway/src/index.ts:238 |
| Request correlation headers | X-Request-ID, X-Trace-ID, X-RateLimit-*, X-LetBuyy-API-Version, X-Response-Time | Send X-Request-ID for deterministic tracing; the gateway creates one if absent and exposes it through CORS. | services/api-gateway/src/index.ts:149 + services/api-gateway/src/middleware/security.ts:282 |
Mounted /v1 route groups and Hono route counts from the current worker source. Counts are router declarations, not generated OpenAPI operations.
| Surface | Mount | Access | Routes | Current scope | Source |
|---|---|---|---|---|---|
| Auth | /v1/auth | Public mount with auth rate limit | 23 | Custom session, signup/signin, OTP, password, trusted device, and token helpers. | services/api-gateway/src/index.ts:178 + routes/auth.ts |
| Contacts | /v1/contacts | Public | 2 | Public contact submission and retrieval helpers. | services/api-gateway/src/index.ts:179 + routes/contacts.ts |
| Storefront | /v1/storefront | Public | 57 | Tenant lookup, public catalog, checkout payment starts/verifications, customer account, reviews, pages, policies, blog, and contact flows. | services/api-gateway/src/index.ts:180 + routes/storefront.ts |
| Themes | /v1/themes | Public mount with merchant flows | 18 | Catalog, theme schema, editor draft/publish, preview sessions, package upload, and install flows. | services/api-gateway/src/index.ts:181 + routes/themes.ts |
| App marketplace | /v1/app-store | Public mount with merchant/app token flows | 22 | Marketplace listing, OAuth, installs, bridge fetch, developer registration, submissions, charges, and partner dashboard surfaces. | services/api-gateway/src/index.ts:182 + routes/app-store.ts |
| Internal console | /v1/internal/console | Internal token | 9 | Internal console bootstrap and platform-console helper endpoints. | services/api-gateway/src/index.ts:183 + routes/internal-console.ts |
| Stores | /v1/stores | Protected merchant session + CSRF | 10 | Store listing, handle lookup, create/update/publish/delete, and payment config. | services/api-gateway/src/index.ts:191 + routes/stores.ts |
| Products | /v1/products | Protected merchant session + CSRF | 10 | Products, collections, gift cards, create/update/delete, and bulk product actions. | services/api-gateway/src/index.ts:192 + routes/products.ts |
| Orders | /v1/orders | Protected merchant session + CSRF | 7 | Order list/detail, status updates, creation, fulfillment, refund request, and refund completion. | services/api-gateway/src/index.ts:193 + routes/orders.ts |
| Payments | /v1/payments | Protected merchant session + CSRF | 9 | Plans, subscription state/history, subscription order/verify/cancel, Razorpay, and Stripe checkout. | services/api-gateway/src/index.ts:194 + routes/payments.ts |
| Uploads | /v1/upload | Protected merchant session + CSRF | 2 | Upload helpers for merchant runtime assets. | services/api-gateway/src/index.ts:195 + routes/upload.ts |
| Portfolio | /v1/portfolio | Protected merchant session + CSRF; legacy site types only | 4 | Legacy portfolio content for existing sites. New portfolio acquisition is gated by LETBUYY_ENABLE_LEGACY_SITE_TYPES. | services/api-gateway/src/index.ts:196 + routes/portfolio.ts |
| Resume | /v1/resume | Protected merchant session + CSRF; legacy site types only | 10 | Legacy resume profile, experience, education, skills, projects, and related page data for existing sites. New resume acquisition is gated by LETBUYY_ENABLE_LEGACY_SITE_TYPES. | services/api-gateway/src/index.ts:197 + routes/resume.ts |
| Employees | /v1/employees | Protected merchant session + CSRF | 10 | Employee records, invitations, permissions, and team management. | services/api-gateway/src/index.ts:198 + routes/employee.ts |
| Admin | /v1/admin | Protected merchant session + CSRF | 12 | Admin dashboard, metrics, and operational merchant helper endpoints. | services/api-gateway/src/index.ts:199 + routes/admin.ts |
| Blog | /v1/blog | Protected merchant session + CSRF | 13 | Blog posts, categories, tags, publishing, and content management. | services/api-gateway/src/index.ts:200 + routes/blog.ts |
| Customers | /v1/customers | Protected merchant session + CSRF | 6 | Customer list/detail and customer address CRUD by email. | services/api-gateway/src/index.ts:201 + routes/customers.ts |
| Notifications | /v1/notifications | Protected merchant session + CSRF | 9 | Notification preferences, templates, sending, and inbox-style state. | services/api-gateway/src/index.ts:202 + routes/notifications.ts |
| Media | /v1/media | Protected merchant session + CSRF | 4 | Media list, create, update, and delete operations. | services/api-gateway/src/index.ts:203 + routes/media.ts |
| AI | /v1/ai | Protected merchant session + CSRF | 5 | Merchant AI helper endpoints. | services/api-gateway/src/index.ts:204 + routes/ai.ts |
| Export | /v1/export | Protected merchant session + CSRF | 3 | Export job helpers. | services/api-gateway/src/index.ts:205 + routes/export.ts |
| Shipping and tax | /v1/shipping-tax | Protected merchant session + CSRF | 12 | Shipping zones, shipping rates, and tax rates. | services/api-gateway/src/index.ts:206 + routes/shipping-tax.ts |
| Onboarding | /v1/onboarding | Protected merchant session + CSRF | 6 | Merchant onboarding progress and setup steps. | services/api-gateway/src/index.ts:207 + routes/onboarding.ts |
| Inventory | /v1/inventory | Protected merchant session + CSRF | 15 | Locations, suppliers, purchase orders, transfers, levels, adjustments, bulk adjustments, and history. | services/api-gateway/src/index.ts:208 + routes/inventory.ts |
| Coupons | /v1/coupons | Protected merchant session + CSRF | 6 | Coupon list/create/detail/update/delete and validation. | services/api-gateway/src/index.ts:209 + routes/coupons.ts |
| Categories | /v1/categories | Protected merchant session + CSRF | 5 | Category list/create/detail/update/delete. | services/api-gateway/src/index.ts:210 + routes/categories.ts |
| Analytics | /v1/analytics | Protected merchant session + CSRF | 4 | Dashboard, revenue, top products, and order analytics. | services/api-gateway/src/index.ts:211 + routes/analytics.ts |
| Reviews | /v1/reviews | Protected merchant session + CSRF | 3 | Product review list, moderation update, and delete operations. | services/api-gateway/src/index.ts:212 + routes/reviews.ts |
| Form submissions | /v1/form-submissions | Protected merchant session + CSRF | 3 | Form submission list, status update, and delete operations. | services/api-gateway/src/index.ts:213 + routes/form-submissions.ts |
| Pages | /v1/pages | Protected merchant session + CSRF | 10 | Pages, policies, navigation replacement, page updates, and deletes. | services/api-gateway/src/index.ts:214 + routes/pages.ts |
| Operations | /v1/operations | Protected merchant session + CSRF | 44 | Platform operations workflows and support tooling. | services/api-gateway/src/index.ts:215 + routes/operations.ts |
Gateway schema modules and their canonical package sources. These are source exports, not generated OpenAPI definitions.
| Facade | Route surface | Canonical source | Current exports | Portal guidance | Source |
|---|---|---|---|---|---|
| auth.schema.ts | /v1/auth | @letbuyy/auth-core | SignUp, SignIn, OTP request/verify, password reset/update, auth token helpers, and customer federation token helpers. | Auth request validation is centralized in auth-core and exposed through the gateway facade; the developer portal should not invent extra login/session fields. | services/api-gateway/src/schemas/auth.schema.ts:1 |
| store.schema.ts | /v1/stores | @letbuyy/shared-types + @letbuyy/tenant-core | Store contract, site type/status, reserved subdomains, subdomain validation, create/update store, and payment config schemas. | Store-facing docs should say store in UI but keep source truth tied to site ownership and tenant-core validation. | services/api-gateway/src/schemas/store.schema.ts:1 |
| product.schema.ts | /v1/products | @letbuyy/shared-types + @letbuyy/commerce-core | Product, collection, option, variant contracts plus create, update, list query, and bulk action schemas. | Product endpoint docs can cite real create/update/list/bulk validators, but field-level generated OpenAPI is not present. | services/api-gateway/src/schemas/product.schema.ts:1 |
| customer.schema.ts | /v1/customers | @letbuyy/shared-types + @letbuyy/commerce-core | Customer and address contracts plus create, update, create address, and list query schemas. | Customer docs should stay store-scoped and use the commerce-core customer/address request contracts. | services/api-gateway/src/schemas/customer.schema.ts:1 |
| order.schema.ts | /v1/orders, /v1/payments, /v1/storefront | @letbuyy/shared-types + @letbuyy/checkout-core | Cart, line item, order, payment contracts plus storefront checkout, provider payment, fulfillment, refund, order status, and list schemas. | Checkout and payment examples must reflect server-side order/payment schemas and provider verification contracts, not client-submitted totals. | services/api-gateway/src/schemas/order.schema.ts:1 |
| coupon.schema.ts | /v1/coupons and storefront coupon validation | @letbuyy/shared-types + @letbuyy/checkout-core | Coupon contract plus create, validate, and list query schemas. | Coupon docs can cover create/list/validate shape at a high level, while generated request examples remain skipped until tooling exists. | services/api-gateway/src/schemas/coupon.schema.ts:1 |
| theme.schema.ts | /v1/themes | @letbuyy/shared-types + @letbuyy/theme-engine | Theme, bundle, section, block, template contracts plus slug, store query, install, draft, publish, preview, rollback, upload, and purchase schemas. | Theme SDK docs should treat the JSON-contract bundle and upload route as real; npm SDK and CLI remain planned. | services/api-gateway/src/schemas/theme.schema.ts:1 |
| operations.schema.ts | /v1/operations | @letbuyy/event-core | Outbox, webhook delivery dispatch, queue jobs, review decisions, webhook subscriptions, usage, runtime replay/recovery, incident, readiness, and certification schemas. | Operational webhook subscription schemas exist, but public developer webhook management UI and sender tooling are still skipped. | services/api-gateway/src/schemas/operations.schema.ts:1 |
Protected merchant-session commerce, inventory, customer, order, and payment routes.
| Method | Route | Auth | Status | Current behavior | Source |
|---|---|---|---|---|---|
| GET | /v1/products | merchant session | Lists products for owned stores with pagination, store_id, category, status, search, sort, and order filters. | services/api-gateway/src/routes/products.ts:119 | |
| POST | /v1/products | merchant session | Creates a product through ProductExecutionAdapter after resolving the merchant profile and owned store context. | services/api-gateway/src/routes/products.ts:387 | |
| PATCH | /v1/products/:id | merchant session | Updates an owned product and emits product.updated. | services/api-gateway/src/routes/products.ts:411 | |
| POST | /v1/products/bulk | merchant session | Runs bulk activate, deactivate, or delete actions for product IDs in an owned store. | services/api-gateway/src/routes/products.ts:435 | |
| GET | /v1/orders | merchant session | Lists orders for owned stores with pagination, status, payment_status, search, sort, and order filters. | services/api-gateway/src/routes/orders.ts:230 | |
| POST | /v1/orders | merchant session | Creates a merchant-side order with server-side price calculation and idempotency. | services/api-gateway/src/routes/orders.ts:389 | |
| PATCH | /v1/orders/:id | merchant session | Transitions order status through the order execution adapter with an idempotency claim. | services/api-gateway/src/routes/orders.ts:340 | |
| POST | /v1/orders/:id/fulfill | merchant session | Creates fulfillment records and emits order.fulfilled for an owned order. | services/api-gateway/src/routes/orders.ts:449 | |
| POST | /v1/orders/:id/refund | merchant session | Creates a return and refund intent instead of marking provider success directly. | services/api-gateway/src/routes/orders.ts:540 | |
| GET | /v1/customers | merchant session | Builds store-scoped customer summaries from store customer rows and order rows. | services/api-gateway/src/routes/customers.ts:113 | |
| POST | /v1/customers/:email/addresses | merchant session | Adds a saved customer address after verifying store ownership. | services/api-gateway/src/routes/customers.ts:231 | |
| GET | /v1/inventory/levels | merchant session | Lists inventory levels for owned stores with product_id, low_stock, page, and limit filters. | services/api-gateway/src/routes/inventory.ts:557 | |
| POST | /v1/inventory/adjust | merchant session | Adjusts inventory for an owned product through the inventory ledger RPC. | services/api-gateway/src/routes/inventory.ts:645 | |
| GET | /v1/payments/plans | merchant session | Returns active subscription plans filtered by site_type and optional slug. | services/api-gateway/src/routes/payments.ts:263 | |
| POST | /v1/payments/razorpay/order | merchant session | Creates a Razorpay order for an owned payable order after amount verification and idempotency. | services/api-gateway/src/routes/payments.ts:651 | |
| POST | /v1/payments/razorpay/verify | merchant session | Verifies Razorpay signature, prevents double-payment, confirms payment, and emits order paid state. | services/api-gateway/src/routes/payments.ts:750 | |
| POST | /v1/payments/stripe/checkout | merchant session | Creates a Stripe checkout session for an owned payable order and records the Stripe session reference. | services/api-gateway/src/routes/payments.ts:843 |
Public storefront lookup, catalog, checkout, payment, content, and review routes.
| Method | Route | Auth | Status | Current behavior | Source |
|---|---|---|---|---|---|
| GET | /v1/storefront/lookup | public | Looks up a store by handle or subdomain for routing and search surfaces. | services/api-gateway/src/routes/storefront.ts:1195 | |
| GET | /v1/storefront/directory | public | Returns public discovery stores and aggregate counts for stores, themes, products, and orders. | services/api-gateway/src/routes/storefront.ts:1256 | |
| GET | /v1/storefront/store/:storeId | public | Loads published store data by immutable store ID and includes current theme release plus public app blocks. | services/api-gateway/src/routes/storefront.ts:1299 | |
| GET | /v1/storefront/:subdomain | public | Loads published store data by subdomain and includes current theme release plus public app blocks. | services/api-gateway/src/routes/storefront.ts:1529 | |
| GET | /v1/storefront/:subdomain/status | public | Returns limited status data for draft, published, suspended, or coming-soon routing. | services/api-gateway/src/routes/storefront.ts:1545 | |
| POST | /v1/storefront/:subdomain/orders | public | Creates a storefront checkout order after resolving tenant ownership by subdomain; client store IDs and totals are ignored. | services/api-gateway/src/routes/storefront.ts:1566 | |
| POST | /v1/storefront/:subdomain/payments/razorpay/order | public | Creates a Razorpay payment order for a storefront order after reloading the payable order amount. | services/api-gateway/src/routes/storefront.ts:1664 | |
| POST | /v1/storefront/:subdomain/payments/razorpay/verify | public | Verifies Razorpay storefront payment signature before confirming payment state. | services/api-gateway/src/routes/storefront.ts:1784 | |
| GET | /v1/storefront/:subdomain/products | public | Lists public products for a published store with page, limit, category, and search filters. | services/api-gateway/src/routes/storefront.ts:2474 | |
| GET | /v1/storefront/:subdomain/products/:slug | public | Loads a single active product by slug or UUID and records a storefront view. | services/api-gateway/src/routes/storefront.ts:2510 | |
| GET | /v1/storefront/:subdomain/coupons/validate | public | Validates an active coupon against a storefront subtotal and minimum-order rules. | services/api-gateway/src/routes/storefront.ts:2531 | |
| GET | /v1/storefront/:subdomain/categories | public | Lists visible product categories for a published store. | services/api-gateway/src/routes/storefront.ts:2587 | |
| GET | /v1/storefront/:subdomain/navigation | public | Loads a public navigation menu by normalized location token. | services/api-gateway/src/routes/storefront.ts:2596 | |
| GET | /v1/storefront/:subdomain/pages | public | Lists published storefront pages for the resolved store. | services/api-gateway/src/routes/storefront.ts:2617 | |
| GET | /v1/storefront/:subdomain/policies | public | Lists storefront policy pages for the resolved store. | services/api-gateway/src/routes/storefront.ts:2633 | |
| GET | /v1/storefront/reviews | public | Lists public approved product reviews through the storefront review query schema. | services/api-gateway/src/routes/storefront.ts:1382 |
Implemented order, payment, amount verification, provider verification, and retry behavior from the current gateway.
| Surface | Current contract | Developer handling | Source |
|---|---|---|---|
| Protected order mutations | PATCH /v1/orders/:id plus order create, fulfill, refund, and refund-complete routes begin an IdempotencyExecutionAdapter claim with idempotency_key and replay stored responses. | Send a stable idempotency_key for each retryable mutation. Keys are validated at 8-200 characters by checkout-core schemas. | services/api-gateway/src/routes/orders.ts:345 + packages/checkout-core/src/index.ts:26 |
| Protected order creation price authority | POST /v1/orders accepts product/variant IDs, quantity, shipping, coupon, gift-card, and payment method fields; the route delegates creation to the order execution adapter instead of accepting client totals. | Do not send totals as authority. The gateway/service path owns order pricing and emits order.created after creation. | services/api-gateway/src/routes/orders.ts:387 + packages/checkout-core/src/index.ts:26 |
| Protected Razorpay order start | POST /v1/payments/razorpay/order loads the payable order, computes minor units from order.total, rejects AMOUNT_MISMATCH when a client amount hint differs, and stores an idempotent payment order response. | Treat amount and amount_minor_units as optional consistency hints only; refresh checkout on AMOUNT_MISMATCH. | services/api-gateway/src/routes/payments.ts:673 |
| Protected Razorpay verification | POST /v1/payments/razorpay/verify checks order ownership, blocks already-paid orders, validates the HMAC payload razorpay_order_id|razorpay_payment_id, and confirms payment with idempotency_key. | Submit provider IDs, signature, order_id, and idempotency_key; handle CONFLICT when the payment is already verified or the reference mismatches. | services/api-gateway/src/routes/payments.ts:773 |
| Protected Stripe checkout | POST /v1/payments/stripe/checkout loads the payable order, derives the Stripe amount from order.total, passes idempotency_key to the Stripe adapter, and stores the payment reference. | Use the returned session URL/ID and do not derive payable totals in the client. | services/api-gateway/src/routes/payments.ts:842 |
| Storefront provider starts | Storefront Razorpay, Cashfree, Stripe, and PayPal start routes load the published store order, require supported INR amounts, create provider intents, and complete idempotency claims. | Pass idempotencyKey and orderId. Provider-specific response fields are real, but public SDK wrappers are still [SKIP — NEEDS BACKEND/SDK]. | services/api-gateway/src/routes/storefront.ts:1663 + :1901 + :2145 + :2250 |
| Storefront amount mismatch | Storefront Razorpay and Cashfree starts accept optional amount hints and reject mismatches against the server-computed amount with AMOUNT_MISMATCH. | Use amount hints for stale-checking only; rebuild the checkout from the latest order payload when the gateway rejects a mismatch. | services/api-gateway/src/routes/storefront.ts:1697 + :1936 |
| Storefront provider verification and capture | Storefront Razorpay verification, Cashfree verification, and PayPal capture use idempotencyKey, check provider references, confirm payment, emit order paid, and replay completed responses. | Keep provider reference IDs bound to the order and retry verification/capture with the same idempotencyKey after transient provider failures. | services/api-gateway/src/routes/storefront.ts:1816 + :2063 + :2394 |
| Checkout schema key casing | Protected merchant order/payment schemas use idempotency_key; storefront schemas use idempotencyKey for order, provider start, verify, checkout, and capture flows. | Match the exact route casing. The portal should not normalize casing for developers until an SDK layer exists. | packages/checkout-core/src/index.ts:26 + :69 + :84 + :92 + :105 |
Marketplace, install, OAuth, app bridge, developer, and dashboard routes.
| Method | Route | Auth | Status | Current behavior | Source |
|---|---|---|---|---|---|
| GET | /v1/app-store/categories | public | Lists active app categories. | services/api-gateway/src/routes/app-store.ts:460 | |
| GET | /v1/app-store/apps | public | Lists published marketplace apps with category, search, pricing, site_type, sort, page, and limit filters. | services/api-gateway/src/routes/app-store.ts:475 | |
| GET | /v1/app-store/apps/:id | public | Gets a published app by UUID or slug with developer, category, and extension records. | services/api-gateway/src/routes/app-store.ts:524 | |
| POST | /v1/app-store/apps/:id/oauth/authorize | merchant session | Installs or authorizes a published app, validates requested scopes and redirect_uri, creates webhook subscriptions, emits app.installed, and returns a 15-minute authorization code. | services/api-gateway/src/routes/app-store.ts:1140 | |
| POST | /v1/app-store/oauth/token | public | Exchanges grant_type=authorization_code with PKCE code_verifier, or grant_type=refresh_token with a rotated refresh token, for a scoped Bearer token. | services/api-gateway/src/routes/app-store.ts:1312 | |
| POST | /v1/app-store/oauth/token-exchange | merchant session | Exchanges an authenticated merchant session and installation_id for a 15-minute embedded app token. | services/api-gateway/src/routes/app-store.ts:1400 | |
| POST | /v1/app-store/installations/:id/embed-session | merchant session | Mints a 15-minute app bridge session for an installed admin embed surface. | services/api-gateway/src/routes/app-store.ts:682 | |
| POST | /v1/app-store/bridge/fetch | app bearer | Proxies scoped GET reads for embedded apps. Allowed first segments map to read_products, read_orders, read_customers, read_themes, and read_storefront. | services/api-gateway/src/routes/app-store.ts:781 | |
| GET | /v1/app/products | app bearer: read_products | Lists products for the installed app token's store. A mismatched store_id is rejected instead of broadening access. | services/api-gateway/src/routes/app-api.ts:152 | |
| GET | /v1/app/orders | app bearer: read_orders | Lists orders for the installed app token's store. A mismatched store_id is rejected instead of broadening access. | services/api-gateway/src/routes/app-api.ts:209 | |
| PATCH | /v1/app/installation/metadata | app bearer: write_app_metadata | Updates non-secret metadata owned by the active app installation without mutating merchant product, order, customer, or theme records. | services/api-gateway/src/routes/app-api.ts:271 | |
| POST | /v1/app-store/apps/:id/install | merchant session | Installs an app directly, mints an app token, subscribes webhooks, and dispatches app.installed. | services/api-gateway/src/routes/app-store.ts:1477 | |
| DELETE | /v1/app-store/apps/:id/install | merchant session | Uninstalls an app, revokes stored OAuth config, disables app webhook subscriptions, and dispatches app.uninstalled. | services/api-gateway/src/routes/app-store.ts:1648 | |
| GET | /v1/app-store/developers/me | merchant session | Returns the current user's developer profile if registered. | services/api-gateway/src/routes/app-store.ts:1758 | |
| POST | /v1/app-store/developers/register | merchant session | Registers the current user as an app developer with company_name and support_email. | services/api-gateway/src/routes/app-store.ts:1781 | |
| GET | /v1/app-store/developers/apps | merchant session | Lists current developer profile, submitted apps, and review records. | services/api-gateway/src/routes/app-store.ts:1813 | |
| POST | /v1/app-store/developers/apps/manifest/validate | merchant session | Validates a LetBuyy app manifest against app-engine, returning normalized extension and function registration plans without creating an app. | services/api-gateway/src/routes/app-store/developer-routes.ts | |
| POST | /v1/app-store/developers/apps | merchant session | Submits a marketplace app for review after developer registration, optional Built-for-LetBuyy quality gate checks, optional manifest persistence, and show-once hash-only credential issuance. | services/api-gateway/src/routes/app-store.ts:2085 | |
| POST | /v1/app-store/developers/apps/:id/api-key | merchant session | Rotates a show-once developer API key for an app owned by the current developer profile; plaintext is returned once and only hashes are persisted. | services/api-gateway/src/routes/app-store/developer-routes.ts |
Theme catalog, editor, package upload, preview, and install routes.
| Method | Route | Auth | Status | Current behavior | Source |
|---|---|---|---|---|---|
| GET | /v1/themes | public | Lists active themes with category, site_type, pricing, industry, search, sort, page, and limit filters. | services/api-gateway/src/routes/themes.ts:119 | |
| GET | /v1/themes/:slug/schema | public | Returns editable schemas for a theme. | services/api-gateway/src/routes/themes.ts:330 | |
| GET | /v1/themes/:slug/editor | merchant session | Loads store-scoped theme editor state using store_id. | services/api-gateway/src/routes/themes.ts:338 | |
| PUT | /v1/themes/:slug/editor/draft | merchant session | Saves a store-scoped theme draft with Zod validation from @letbuyy/theme-engine. | services/api-gateway/src/routes/themes.ts:362 | |
| POST | /v1/themes/:slug/publish | merchant session | Publishes a saved draft to the live store theme config. | services/api-gateway/src/routes/themes.ts:400 | |
| POST | /v1/themes/:slug/preview-session | merchant session | Creates a signed draft preview token. | services/api-gateway/src/routes/themes.ts:414 | |
| POST | /v1/themes/packages/upload | merchant session | Validates and persists a portable JSON-contract theme bundle, then creates a marketplace review record unless private_install is requested. | services/api-gateway/src/routes/themes.ts:467 | |
| POST | /v1/themes/:slug/install | merchant session | Installs or applies a theme to a store. | services/api-gateway/src/routes/themes.ts:566 |
Developer-facing callback contract plus internal dispatch routes.
| Method | Route | Auth | Status | Current behavior | Source |
|---|---|---|---|---|---|
| POST | https://webhooks.letbuyy.store/app-lifecycle/dispatch | internal | Internal gateway-to-webhook-service route that signs and dispatches app lifecycle callbacks. | services/webhook-service/src/index.ts:748 | |
| POST | https://webhooks.letbuyy.store/webhook-deliveries/dispatch | internal | Internal dispatcher for queued webhook delivery rows with retry scheduling. | services/webhook-service/src/index.ts:842 | |
| POST | Partner HTTPS callback URL | HMAC signature | LetBuyy sends app lifecycle and queued webhooks with X-LetBuyy-Hmac-SHA256, X-LetBuyy-Timestamp, event ID, event type, request ID, and trace ID headers. | services/webhook-service/src/app-lifecycle-dispatch.ts:86 |
Route helper and package schema facts that are currently implemented.
Built-for-LetBuyy evidence rules, draft behavior, and review-record automation from the current app engine and gateway route.
| Check | Current rule | Evidence fields | Source |
|---|---|---|---|
| Submission contract | Required fields are name, tagline, description, category_id, app_url, and privacy_url or privacy_policy_url. slug is generated from slug or name. | name, tagline, description, category_id, app_url, privacy_url, privacy_policy_url, slug | packages/app-engine/src/index.ts:753 |
| Evidence aliases | Built-for-LetBuyy evidence is parsed from quality_gate, built_for_letbuyy, or builtForLetBuyy. The gate runs only when evidence exists and save_as_draft is not true. | quality_gate, built_for_letbuyy, builtForLetBuyy, save_as_draft | packages/app-engine/src/index.ts:779 |
| Performance | Lighthouse performance score must be at least 70 before listing. | performance_score, performanceScore, lighthouse_performance | packages/app-engine/src/index.ts:666 |
| Reviews | At least one qualifying published review and rating average of 4.0 or higher are required for the badge gate. | review_count, reviews_count, rating_avg, average_rating, avg_rating | packages/app-engine/src/index.ts:669 + services/api-gateway/src/routes/app-store.ts:623 |
| Installs | At least one successful install signal is required for the badge gate. | install_count, installs | packages/app-engine/src/index.ts:671 + services/api-gateway/src/routes/app-store.ts:1617 |
| Storefront app block | At least one extension must be typed storefront_block, app-block, or app_block. | app_extensions, extensions, app_blocks | packages/app-engine/src/index.ts:654 |
| Privacy and app URLs | App and privacy URLs must be HTTPS. localhost and 127.0.0.1 HTTP are accepted only for local testing. | privacy_policy_url, privacy_url, app_url, embedded_url, website_url | packages/app-engine/src/index.ts:640 + :673 |
| Failure behavior | A non-draft submission with failed evidence returns a validation error naming the failed check keys. Draft submissions store as draft and skip the gate. | failed check keys, save_as_draft | packages/app-engine/src/index.ts:789 + :808 |
| Review record | Non-draft submissions create a marketplace review record with schema_validation, developer_profile, and built_for_letbuyy_quality_gate automated checks, then emit app.submitted. | marketplace_review_records, automated_checks, app.submitted | services/api-gateway/src/routes/app-store.ts:2130 |