# Business APIs

## 1. Scope
Business APIs provide transactional and catalog capabilities.
They must remain tenant-aware and must not return UI/layout/theme/widget configuration.

## 2. Immutable Rule
These APIs MUST NOT return:
- page composition
- layout mode
- widget metadata
- theme/footer/static page config

That data belongs to CONFIG DOMAIN (`/bootstrap`, `/pages/:slug`).

## 3. API Catalog

## /auth
Purpose:
- session creation/validation
- login/logout flows
- token refresh where applicable

High-level response shape:
- session/token metadata
- user identity claims
- permission scopes

Tenant rule:
- auth sessions are tenant-scoped by request context.

Must not change:
- authentication contract and downstream payment/auth integrations.

## /items
Purpose:
- list/fetch product items
- search/filter/sort
- item details and availability

High-level response shape:
- item arrays / item objects
- pagination metadata
- stock/price fields

Tenant rule:
- only items visible to tenant catalog policy.

Must not change:
- item identifiers/price semantics relied on frontend checkout/cart logic.

## /searchitems
Purpose:
- keyword-based product search for catalog/search pages.

High-level response shape:
- items array
- total count

Tenant rule:
- results must respect tenant catalog visibility and pricing policies.

## /search/suggestions (future-ready)
Purpose:
- return instant search suggestions for typed keywords.

High-level response shape:
- suggestion strings or objects with label/value and optional popularity/count.

Tenant rule:
- suggestions generated only from tenant-visible catalog corpus.

## /catalog/filters (future-ready)
Purpose:
- provide dynamic filter definitions and options for current search/category context.

High-level response shape:
- filter definitions
- option counts
- optional min/max ranges

Tenant rule:
- filter options/counts must be tenant-scoped and inventory-aware.

## /products/{id}/rating
Purpose:
- return product rating aggregate for engagement UI.

High-level response shape:
- average rating
- total reviews
- star distribution (5..1)

Tenant rule:
- aggregate must be computed only from tenant-visible reviews.

## /products/{id}/reviews
Purpose:
- paginated review feed for product page.

High-level response shape:
- review list
- page/pageSize/total metadata

Tenant rule:
- only tenant-allowed and moderation-approved reviews.

## /products/{id}/questions
Purpose:
- paginated questions and answers feed for product page.

High-level response shape:
- question list with answers
- page/pageSize/total metadata

Tenant rule:
- only tenant-visible questions/answers.

## /products/{id}/reviews (POST)
Purpose:
- create review (rating/title/text/anonymous).

Must not change:
- request validation semantics expected by frontend engagement form.

## /products/{id}/questions (POST)
Purpose:
- create product question (text/anonymous).

Must not change:
- acknowledgement contract expected by frontend engagement form.

## /me/wishlist (future-ready)
Purpose:
- authenticated wishlist synchronization across devices.

High-level response shape:
- wishlist product references
- optional addedAt metadata

Tenant rule:
- wishlist entries must remain tenant-scoped.

## /me/compare (future-ready)
Purpose:
- optional compare list synchronization for authenticated users.

High-level response shape:
- compared product references
- optional addedAt metadata

Tenant rule:
- compare list must be isolated by tenant + user.

## /me/saved-searches (future-ready)
Purpose:
- persist and restore saved search presets.

High-level response shape:
- saved query/filter/sort presets
- timestamps and id

Tenant rule:
- saved searches must be tenant-scoped and user-scoped.

## /me/recently-viewed (future-ready)
Purpose:
- synchronize recently viewed product history for authenticated users.

High-level response shape:
- product references + viewedAt metadata

Tenant rule:
- history must remain tenant-scoped and privacy-safe.

## /categories
Purpose:
- category tree retrieval
- category filtering metadata

High-level response shape:
- hierarchical or flat category collections
- visibility and ordering metadata

Tenant rule:
- category graph resolved per tenant catalog configuration.

Must not change:
- category IDs and parent linkage semantics consumed by frontend domain mapping.

## /orders
Purpose:
- create and track orders
- lifecycle state transitions

High-level response shape:
- order id
- status
- totals and line-items

Tenant rule:
- order creation/query restricted to tenant context.

Must not change:
- order status lifecycle contract integrated with payment and notification flows.

## /cart
Purpose:
- cart synchronization and server-side cart state where applicable

High-level response shape:
- cart items
- totals
- selected delivery/payment metadata

Tenant rule:
- cart state must be isolated by tenant + session/user.

Must not change:
- cart schema expected by checkout and payment request builders.

## /payments
Purpose:
- payment intent/QR/card flow initiation
- payment status querying

High-level response shape:
- payment id/reference
- redirect/QR links
- status fields

Tenant rule:
- payment credentials/routes resolved per tenant context on backend.

Must not change:
- existing payment provider contracts and callback/status semantics.

## 4. Governance for All Business APIs
- tenant derived from request context only
- strict repository-level tenant filtering
- no UI config payloads
- backward compatibility for existing frontend business flows