Use this guide when your task involves @enadhq/enad-ts-sdk, @enadhq/enad-ts-sdk/search, or the boundary between SDK usage and direct API calls.

Choose the TypeScript route first

Start here when you need to route package usage, Search helpers, root helpers, and API boundary questions.

Choose a narrower route first when possible:

• Go to Product listing helpers for listing URL state or REST listing query shaping.
• Go to Search GraphQL latest when the task is primarily Search query shape, generated documents, facets, autocomplete, or targeting.
• Go to API reference or OpenAPI-backed routes before writing exact request, response, auth, or parameter code.
• Go to React SDK agent guide when the real job is provider-backed React composition rather than TypeScript package usage.

Use this page to choose the right SDK, API, Search, or helper surface. Check package reference for exact exports, helper signatures, Search documents, and method behavior before writing code.

Exact reference boundary

• Use docs for setup guidance and surface choice.
• Use TypeScript SDK package reference for exact exports, method signatures, generated types, Search documents, and package behavior.
• Use API reference or OpenAPI specs for endpoint fields.
• Do not hand-author endpoint, GraphQL operation, or fragment truth from memory.

Safe agent workflow

1. Identify the API, SDK surface, or Search operation the task needs.
2. Check whether the task is SDK usage, direct API usage, Search GraphQL usage, or root-helper usage.
3. Use this guide for boundaries and setup framing.
4. If the task is listing URL state or REST listing query shaping, open Product listing helpers before inventing app-local utilities.
5. Inspect current package reference when exact signatures matter.
6. Keep auth, app context, market, store group, locale, and runtime placement explicit.

Search workflow

For Search-specific tasks, start with Search GraphQL latest and keep app, market, store-group, and locale context explicit.

Current package behavior:

• @enadhq/enad-ts-sdk/search exposes the lower-level Search GraphQL surface.
• createSearchClient() is the package-supported Search client entry point.
• createSearchClient() needs appId, marketSlug, storeGroupSlug, and locale; pass baseUrl, fetch, or headers only when the runtime needs explicit transport setup.
• Named SearchClient methods cover products, product cards, product by slug/SKU, facets, brands, series, category browsing, category lookup by ID or URI, collection browsing, collection lookup by ID or URI, redirects, variants, completions, and product slugs.
• Search helpers return data or throw SearchClientError for configuration, HTTP, JSON, GraphQL, or missing-data failures. Do not tuple-destructure Search helper results.
• Brand and series work can use named searchBrands() and searchSeries() helpers; generated brand and series documents remain available for lower-level execution.
• Product lookup, product slug, and variant helpers default to active records unless a supported onlyActive request value overrides that default.
• Keep warehouseSlug as a top-level product/facet query variable, not as a ProductFilter field.

Root helper reminder

@enadhq/enad-ts-sdk exposes root-package helpers in addition to generated clients and the lower-level Search package. Use Product listing helpers for listing query options and URL state. The root package also exposes resolveProductPrice(), normalizeVariantStockSignal(), and orderProductsBySlugs().

The listing helper guide covers names such as toProductQueryOptions(), ProductListingQueryOptions, parseProductListingUrlState(), serializeProductListingUrlState(), and toggleProductFilterValue().

Treat helper signatures and return types as package reference truth. Treat tuple-style SDK responses as [data, error] on the core Enad API client surface, and keep normalizeVariantStockSignal() limited to stock-only variant facts instead of purchase or UI policy.

Prompt boundary

Use docs for Enad TypeScript SDK routing, but inspect package reference for exact exports, SearchClient methods, generated documents, helper signatures, and method behavior. Use @enadhq/enad-ts-sdk/search and createSearchClient() for package-backed Search GraphQL usage. Search helpers return data or throw SearchClientError; core Enad API client methods use tuple-style [data, error] responses. Use the root package helper guide for listing URL state or REST listing query shaping. Do not invent request fields, response fields, GraphQL fragment fields, or convenience methods. If endpoint truth matters, check API reference or OpenAPI reference.

API usage checklist

• Which Enad app or tenant context does the call need?
• Which API owns the resource?
• Is this a server-side call, browser call, or build-time data fetch?
• Which auth token or credential boundary applies?
• Is there an OpenAPI spec or reference entry for the endpoint?
• Does the React SDK already provide a safer provider-backed surface for the same job?

Versioning boundary

Docs versioning tracks package versions, not whole-site versions. Use the latest agent guide for current package guidance and preserved package-version routes when they exist.