> ## Documentation Index
> Fetch the complete documentation index at: https://docs-loja.usecorvex.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Contract

> Contrato canônico de dados da vitrine — como sections recebem produtos, carrinho e contexto de página.

> Esta página é o **contrato canônico** para dados disponíveis a Themes na Corvex.

Dados da loja são acessados via **Theme SDK** (`@corvex/theme-sdk`). O tema MUST NOT usar APIs admin ou autenticação interna.

API version pública: `2026-08` (`STOREFRONT_API_VERSION`).

***

## MUST — pacote público

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  createStorefront,
  usePage,
  useCorvexCart,
  useStorefront,
  defineSection,
  defineSectionData,
  SECTION_DATA_KEYS,
} from '@corvex/theme-sdk';
```

Build de temas também resolve `@corvex/sdk` como **alias legado** do mesmo módulo — preferir `@corvex/theme-sdk` em código novo.

***

## Como uma section recebe dados

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
schema.data[]  ou  defineSectionData(loader)
        ↓
Runtime resolve (page context + storefront client)
        ↓
Prop data na section (ou useSectionDataByNodeId)
```

### 1. Declarativo — `schema.data`

Chaves em `sections/{id}/schema.json` ou `defineSection({ data: [...] })`.

| Chave | Origem típica |
| - | - |
| `products` | `storefront.products.list(settings)` |
| `product` | contexto de página `product` |
| `collection`, `category` | contexto de página |
| `collections`, `categories` | `storefront.categories.list()` |
| `cart` | contexto ou `storefront.cart.ensure()` |
| `search` | resultados da página de busca |
| `reviews`, `reviews_summary`, `recommendations` | APIs + `product` |
| `discount_ranges`, `payment_discounts`, `coupons` | list APIs |
| `blog`, `article`, `page` | contexto de página |

### 2. Loader customizado

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
export const data = defineSectionData(async ({ storefront, settings, page }) => ({
  products: await storefront.products.list({
    first: settings.limit ?? 4,
    featured: true,
  }),
}));
```

MUST exportar função marcada com `defineSectionData`.

***

## Contexto de página (`PageContextMap`)

| PageType | Campos principais |
| - | - |
| `index` | `shop` |
| `product` | `product`, optional `reviews`, `recommendations` |
| `collection` | `collection`, optional `products` |
| `category` | `category`, optional `products` |
| `search` | `searchQuery`, `results` |
| `cart` | `cart` |
| `page` | `page` |
| `blog` | `blog`, optional `articles`, `article` |
| `article` | `blog`, `article` |

Acesso:

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { usePage } from '@corvex/theme-sdk';

const { product } = usePage('product');
const { searchQuery, results } = usePage('search');
```

`usePage` ignora o texto do argumento e devolve o contexto da página aberta. O argumento só documenta a intenção.

Cookbook: [Search Results](https://docs-loja.usecorvex.com.br/cookbook/search-results.md).

***

## StorefrontClient (`createStorefront`)

Cliente browser para API pública da vitrine:

* `products`, `categories` / `collections` (alias)
* `search`, `reviews`, `recommendations`, `leads`
* `discountRanges`, `paymentDiscounts`, `coupons`
* `cart`, `shop`, `menus`, `blogs`, `pages`
* `query()` — existe e lança erro: GraphQL ainda não está disponível. Use `products.list` e as outras APIs do cliente

Hooks memoizados: `useStorefront()`.

***

## Conexões paginadas

Listas retornam `Connection<T>`:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ nodes: T[]; pageInfo: { hasNextPage, hasPreviousPage, … } }
```

***

## SSR vs CSR (abstração pública)

* Boot da loja pode incluir metadados de shop e revisão publicada no servidor.
* **Dados de catálogo e carrinho** são obtidos no cliente via Theme SDK (fetch browser).
* Sections MUST tratar `loading` / listas vazias.

***

## MUST NOT

* MUST NOT fazer `fetch` manual a endpoints não documentados no SDK.
* Não assumir `product` global em toda section — declare `data` ou use `usePage`.
* MUST NOT usar campos de objeto não declarados em [Product Contract](https://docs-loja.usecorvex.com.br/reference/contracts/product.md) sem confirmação.

***

## Recursos tipados

* [Product](https://docs-loja.usecorvex.com.br/reference/contracts/product.md)
* [Cart](https://docs-loja.usecorvex.com.br/reference/contracts/cart.md)
* [Coleção](https://docs-loja.usecorvex.com.br/data/resources/category.md)

***

## Veja também

* [Section Contract](https://docs-loja.usecorvex.com.br/reference/contracts/section.md)
* [SDK overview](https://docs-loja.usecorvex.com.br/sdk/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.