Skip to main content
The StoreRouter TypeScript SDK gives you a fully typed, async client for the StoreRouter commerce API. Install it from npm, configure your 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 OCTOGEN_PLATFORM_API_KEY environment variable automatically.
You can also pass apiKey: in the constructor options if you prefer to manage secrets yourself (see Authentication below).

Authentication

OctogenClient resolves your API key in this order:
  1. The apiKey option passed to the constructor, if provided.
  2. The OCTOGEN_PLATFORM_API_KEY environment variable (process.env.OCTOGEN_PLATFORM_API_KEY).
  3. The deprecated OCTO_API_KEY environment variable. Reading it warns once, and support will be removed. Set OCTOGEN_PLATFORM_API_KEY instead.
If none of these is set, the constructor throws 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

Resolves a product page URL from StoreRouter’s index or with on-demand product resolution. Set resolutionMode: "index_only" when your integration requires indexed identity and catalog context.
Returns: Promise<MerchantProductUrlLookupResponse>

retrieveProduct and retrieveProducts

Reads back products you already hold ids for, such as a 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

Searches every catalog your key can access, or only the catalogs in 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 a TypeError before sending a request:
  • understand: false, relax, or a non-empty omitGeneratedFacets without q. omitGeneratedFacets also requires understand to stay on, and so does relax unless at least one facet is sent with relaxable: true.
  • A facet name repeated within facets or excludeFacets, or a name in both facets and omitGeneratedFacets.
  • More than 50 entries in facets, excludeFacets, or omitGeneratedFacets.
  • A negative price or priceMin > priceMax.
  • Brand quality outside 1–6, or brandQualityMin > brandQualityMax.
  • similarToBrands that is empty, has more than 10 names, or has a blank name.
An empty 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 a 422. 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

Finds products similar to a source product URL or UUID. Omit 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:
Use Facet objects to filter by brand, gender, color, category, and other attributes. Pass them in the facets field of SearchProductsParams.
FacetName is a const object with string values for all built-in facet fields: BRAND_NAME, GENDER, AGE_GROUPS, COLOR, COLOR_FAMILY, IS_ACTIVEWEAR, PRODUCT_TYPE, CATEGORY_PATH_DEPTH_0 through CATEGORY_PATH_DEPTH_6, and more. You can also pass a taxonomy attribute handle, such as fit, as a plain string. Use the bare handle: attribute_facets.fit is rejected. Facet values are canonical lowercase handles. See Facet names.

Pagination

When nextCursor 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 extend OctogenError. HTTP errors extend OctogenAPIError, which exposes statusCode, detail, and response properties.
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.
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.
Thrown when a catalog or product URL cannot be found. For lookupProduct, verify the URL belongs to a catalog your key can access.
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.
Thrown when the SDK cannot reach the API — for example, due to a network timeout or DNS failure. Does not have a statusCode.
Catch the base OctogenAPIError to handle all HTTP errors in one place:
MissingAPIKeyError is thrown by the constructor, not by a network call. It will surface at client creation time if neither apiKey nor an API key environment variable is present.

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.
The directory is complete and unpaginated. Article dates retain their actual precision. Navigation and top categories describe recorded brand-wide assortment, not live scoped inventory. Browse products and source totals respect the customer’s catalog scope. Follow 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.