DocsDocsAgents

React SDK agent commerce and Search handoff

Help agents split shopper UI composition from Search GraphQL and purchase-side contract truth.

Start here when a task crosses shopper-facing React UI, Search GraphQL data, pricing display, or purchase-adjacent behavior.

Keep the ownership split explicit

Search query shape, variables, generated documents, fragments, and types start at Search GraphQL latest. Keep exact query truth in the Search reference and package reference.

Server-side Search usage starts at TypeScript SDK latest and /ai/ts-sdk/latest. Keep exact helper behavior in the @enadhq/enad-ts-sdk/search reference.

Shopper-facing PLP, autocomplete, filters, result cards, and Search UI composition start at Product listing and search. Keep exact component and helper exports in React SDK package reference.

PDP display composition starts at Product detail page. Keep purchase-adjacent effects in app-owned handlers and API reference.

The React SDK is the composition layer. Search GraphQL and API references remain the contract layer.

Current handoff rules to preserve

  • Provider-backed Search runtime keeps market, store group, and locale together.
  • graphql.storeGroupSlug can override groupId for Search context.
  • mapSearchProductToProductCard() accepts storeGroupSlug so mapped cards can prefer the intended store-group price.
  • Product cards and Search UI should display normalized data; they should not silently own cart or checkout side effects.
  • Exact Search fields, filter names, fragment coverage, and generated types must come from Search reference, not prose memory.

Practical agent workflow

  1. Decide whether the question is mostly about contract truth or mostly about shopper UI.
  2. If contract truth is the problem, start at Search latest or the relevant API reference before touching React composition.
  3. If shopper UI is the problem, start at Product listing and search or Commerce components.
  4. Carry market, store group, locale, and any warehouseSlug context through the whole flow.
  5. Keep cart, checkout, and other write-side effects in app-owned handlers after the display layer has done its job.

Common mistakes

Do not let an agent invent Search fields, fragment members, or helper signatures from prose.

Do not treat a Search product card as the place to mutate cart or checkout state. Keep market, store group, and locale together when debugging price or availability mismatches.

Do not move server-side Search loading into browser-only UI code without checking runtime placement. Keep React composition questions separate from OpenAPI or GraphQL schema questions.

React SDK agent commerce and Search handoff

# React SDK agent commerce and Search handoff Start here when a task crosses shopper-facing React UI, Search GraphQL data, pricing display, or purchase-adjacent behavior. ## Keep the ownership split explicit Search query shape, variables, generated documents, fragments, and types start at [Search GraphQL latest](/search/latest). Keep exact query truth in the Search reference and package reference. Server-side Search usage starts at [TypeScript SDK latest](/ts-sdk/latest) and [/ai/ts-sdk/latest](/ai/ts-sdk/latest). Keep exact helper behavior in the `@enadhq/enad-ts-sdk/search` reference. Shopper-facing PLP, autocomplete, filters, result cards, and Search UI composition start at [Product listing and search](/react-sdk/latest/guides/product-listing-search). Keep exact component and helper exports in React SDK package reference. PDP display composition starts at [Product detail page](/react-sdk/latest/guides/product-detail-page). Keep purchase-adjacent effects in app-owned handlers and API reference. The React SDK is the composition layer. Search GraphQL and API references remain the contract layer. ## Current handoff rules to preserve - Provider-backed Search runtime keeps market, store group, and locale together. - `graphql.storeGroupSlug` can override `groupId` for Search context. - `mapSearchProductToProductCard()` accepts `storeGroupSlug` so mapped cards can prefer the intended store-group price. - Product cards and Search UI should display normalized data; they should not silently own cart or checkout side effects. - Exact Search fields, filter names, fragment coverage, and generated types must come from Search reference, not prose memory. ## Practical agent workflow 1. Decide whether the question is mostly about contract truth or mostly about shopper UI. 2. If contract truth is the problem, start at [Search latest](/search/latest) or the relevant API reference before touching React composition. 3. If shopper UI is the problem, start at [Product listing and search](/react-sdk/latest/guides/product-listing-search) or [Commerce components](/react-sdk/latest/components/commerce). 4. Carry market, store group, locale, and any `warehouseSlug` context through the whole flow. 5. Keep cart, checkout, and other write-side effects in app-owned handlers after the display layer has done its job. ## Common mistakes Do not let an agent invent Search fields, fragment members, or helper signatures from prose. Do not treat a Search product card as the place to mutate cart or checkout state. Keep market, store group, and locale together when debugging price or availability mismatches. Do not move server-side Search loading into browser-only UI code without checking runtime placement. Keep React composition questions separate from OpenAPI or GraphQL schema questions. ## Related routes - [Search GraphQL latest](/search/latest) - [React SDK setup](/react-sdk/latest/setup) - [Product listing and search](/react-sdk/latest/guides/product-listing-search) - [Commerce components](/react-sdk/latest/components/commerce) - [TypeScript SDK latest](/ts-sdk/latest) - [React SDK agent discovery and imports](/ai/react-sdk/latest/discovery)