OCTOGEN_PLATFORM_API_KEY, and you can search products by keyword and facet, find products similar to a source product, and look up any product by URL — all with complete TypeScript interfaces so your editor catches mistakes before they reach production.
Installation
1
Install the package
Requires Node.js 20 or later. The SDK ships as ESM only. This page documents version 0.9.0.
2
Set your API key
The client reads your key from the You can also pass
OCTOGEN_PLATFORM_API_KEY environment variable automatically.apiKey: in the constructor options if you prefer to manage secrets yourself (see Authentication below).Authentication
OctogenClient resolves your API key in this order:
- The
apiKeyoption passed to the constructor, if provided. - The
OCTOGEN_PLATFORM_API_KEYenvironment variable (process.env.OCTOGEN_PLATFORM_API_KEY). - The deprecated
OCTO_API_KEYenvironment variable. Reading it warns once, and support will be removed. SetOCTOGEN_PLATFORM_API_KEYinstead.
MissingAPIKeyError immediately — before any network request is made. Every request then sends the key as Authorization: Bearer <api-key>.
Client options
These examples set the StoreRouter base URL explicitly, including when you use an SDK release that predates the domain migration.OctogenClient accepts an optional OctogenClientOptions object:
Methods
lookupProduct
resolutionMode: "index_only" when your integration requires indexed identity and catalog context.
Promise<MerchantProductUrlLookupResponse>
retrieveProduct and retrieveProducts
uuid from search or lookup. Index-only and not billed. An older id resolves to the product; store the result’s uuid. A product the merchant stopped offering still comes back, with isActive: false and lastDeactivatedAt. retrieveProducts takes 1–50 ids and returns one result per id, in request order. Requires @octogen-ai/sdk 0.10.0 or later.
retrieveProduct throws OctogenNotFoundError (detail product_not_found) for an unknown id, a product that left the index, or a product outside your key’s catalog access. In a batch, the same cases are status: "not_found".
Returns: Promise<ProductRetrieveResult> / Promise<ProductRetrieveBatchResponse> (results: ProductRetrieveResult[])
searchProducts
catalogs. Each field controls one thing and is sent under its snake_case wire name (for example, excludeFacets as exclude_facets). See POST /products/search for the full field semantics.
SearchProductsParams fields:
Returns:
Promise<ProgrammaticProductSearchPage>. ProgrammaticProductSearchPage extends MerchantProductListPage, so code typed against the old return type still compiles.
Each
MerchantProductListItem includes uuid, catalogKey, productUrl, title, brand, currentPrice, originalPrice, primaryImage, images, rating, isActive, optional match scores, and updatedAt. It also carries the deprecated imageUrl.
primaryImage and each entry in images are MerchantProductImageMetadataView objects with url, cdnUrl, width, height, sizeBytes, and mimeType. Prefer the hosted copy and fall back to the merchant URL:
Local validation
The SDK checks the contradictions the API would refuse and throws aTypeError before sending a request:
understand: false,relax, or a non-emptyomitGeneratedFacetswithoutq.omitGeneratedFacetsalso requiresunderstandto stay on, and so doesrelaxunless at least one facet is sent withrelaxable: true.- A facet name repeated within
facetsorexcludeFacets, or a name in bothfacetsandomitGeneratedFacets. - More than 50 entries in
facets,excludeFacets, oromitGeneratedFacets. - A negative price or
priceMin > priceMax. - Brand quality outside 1–6, or
brandQualityMin > brandQualityMax. similarToBrandsthat is empty, has more than 10 names, or has a blank name.
catalogs list or a blank key also throws a TypeError. The server remains the source of truth for everything else, such as unknown facet names.
Removed in 0.5.0
These fields were deprecated in 0.4.0 and are gone in 0.5.0, because the API now rejects them with a422. Passing catalog or textSearchQuery from JavaScript, or past the types, throws a TypeError that names the replacement.
textSearchQuery’s retrieval tuning (searchId, rankingText, embedding columns, similarity weights, searchAfter, browseMenuUuid, compactMode) has no replacement on /v1 search.
moreLikeThisProducts
catalogs to search all active crawled catalogs, or pass 1–100 catalog keys to keep the results within those catalogs.
MoreLikeThisProductsParams fields:
Returns:
Promise<MoreLikeThisProductsResponse>
Complete example
The following example searches all active crawled catalogs for women’s linen dresses and prints each result with its brand and price:Faceted search
UseFacet objects to filter by brand, gender, color, category, and other attributes. Pass them in the facets field of SearchProductsParams.
Pagination
WhennextCursor is not null in a response, pass it back verbatim as cursor, with the same other params, to retrieve the following page. A cursor the API cannot use returns 400 with detail "invalid cursor"; restart from page 1 without cursor. Pages don’t overlap, but a product can repeat if the catalog changes between requests, so de-duplicate by uuid.
Error handling
All SDK errors extendOctogenError. HTTP errors extend OctogenAPIError, which exposes statusCode, detail, and response properties.
OctogenAuthenticationError — 401
OctogenAuthenticationError — 401
Thrown when your API key is missing, malformed, or has been revoked. Check that
OCTOGEN_PLATFORM_API_KEY is set correctly and that the key is still active in StoreRouter Platform.OctogenForbiddenError — 403
OctogenForbiddenError — 403
Thrown when a valid key attempts an action it is not authorized for — for example, accessing a catalog that has not been granted to your organization.
OctogenNotFoundError — 404
OctogenNotFoundError — 404
Thrown when a catalog or product URL cannot be found. For
lookupProduct, verify the URL belongs to a catalog your key can access.OctogenValidationError — 422
OctogenValidationError — 422
Thrown when the API rejects a request due to invalid parameters. The
detail property contains the validation error list from the API. searchProducts catches many invalid combinations locally and throws a TypeError before sending a request.OctogenConnectionError
OctogenConnectionError
Thrown when the SDK cannot reach the API — for example, due to a network timeout or DNS failure. Does not have a
statusCode.OctogenAPIError to handle all HTTP errors in one place:
Brand directory, profiles, and browsing
Use TypeScript SDK 0.14.0 or later for the lightweight profile contract.getBrandDetails returns BrandDetailsView; request the separate BrandCoverageResponse with getBrandCoverage.
nextOffset, even when products is empty. It advances by source page size rather than the projected product count. It becomes null at exhaustion or the offset cap of 11976. See brand browsing.
An OctogenNotFoundError means an unknown identity. Keep server failures separate from missing or empty data. Fetch optional coverage independently when the profile needs to render during a snapshot outage. Use the HTTP directory example for ETag revalidation.