Snap Client

🔌 What is Snap Client

@athoscommerce/snap-client is the data layer of the Snap SDK. A small, dependency-light JavaScript/TypeScript wrapper around the Athos APIs. It handles network requests, query parameter construction, response typing, and caching so your team doesn't have to. It is a wrapper around the Athos API that provides a simple interface for fetching data.

👍
Building a custom API integration? You don't need to adopt the full Snap SDK to get value here. Snap Client works standalone, providing a typed, cached fetcher for the Athos APIs, with no Controller, no UI components, and no required state management.

🖐️
Note: The Snap Client has built-in transform functionality that updates the API request/response structure to be in line with our Snap SDK expectations. The Snap Client responses for Search and Autocomplete will NOT follow the same format as raw API responses. For more details on how the response transform impacts your returned data, check out our Snap Client Sandbox.

📘
Already using Snap or Snap Templates? Snap Client is a dependency of Snap Controller, and it's recommended you use the Controller's search method instead of calling Snap Client directly. These docs are for teams building a direct API integration who want the Client on its own.

🚀 Key Features

Typed Requests & Responses: Ships with full TypeScript definitions for requests and responses.
Built-in Caching: Each API method has its own configurable cache with size limits, and auto-purging; backed by localStorage.
Global + Per-Request Config: Set account-wide defaults (like siteId or background filters) once, then override them per requester or per call. Good for partners working with more than one domain.
Runtime Flexible: Works in the browser or server-side (SSR/Node), and accepts a custom fetch implementation if needed.

📦 Installation

npm install --save @athoscommerce/snap-client

import { Client } from '@athoscommerce/snap-client';

⚙️ Configuration

Global Config

The Client constructor's first argument is a ClientGlobals object. This object can be used to set parameters that will apply to every request made with the client. This will typically just be your siteId, but can also include global filters, sorts, or merchandising segments.

siteId is required:

const globals = {
  siteId: 'a1b2c3'
};

Any other keys defined here are passed through to the API request. For example, applying a background filter globally:

const globals = {
  siteId: 'a1b2c3',
  filters: [{
    field: 'stock_status',
    value: 'yes',
    type: 'value',
    background: true
  }]
};

Client Config

The second, optional argument configures how the client communicates with the API. This is useful for pointing at a development origin or tuning cache behavior per requester.

type ClientConfig = {
  mode?: keyof typeof AppMode | AppMode;
  initiator?: string;
  fetchApi?: WindowOrWorkerGlobalScope['fetch'];
  meta?: RequesterConfig<MetaRequestModel, MetaRequesterPaths>;
  search?: RequesterConfig<SearchRequestModel, SearchRequesterPaths>; // also used by autocomplete, category, and finder
  recommend?: RequesterConfig<RecommendRequestModel, RecommendRequesterPaths>;
  suggest?: RequesterConfig<SuggestRequestModel, SuggestRequesterPaths>; // also used by trending
};

type RequesterConfig<RequestType, PathConfigurationType> = {
  origin?: string;
  headers?: HTTPHeaders;
  cache?: CacheConfig;
  globals?: Partial<RequestType>;
  paths?: Partial<PathConfigurationType>;
};

📘
Note: The search requester config also governs the autocomplete, category, and finder methods, and suggest governs trending. For more informations see the ClientConfig Snap docs.

Cache Config

Each requester has its own cache, configurable under RequesterConfig.cache:

Option	Description	Default
`enabled`	Opt out of caching for this requester.	`true`
`ttl`	How long (in ms) requests are stored before expiring.	`300000`
`maxSize`	Maximum size (in KB) the cache is allowed to store in `localStorage`.	`200`
`purgeable`	Whether older entries are auto-purged when `maxSize` is hit, based on time remaining to expiration.	`true` (except `meta`)
`entries`	Preload the cache with existing entries — primarily used for Email Recommendations.	`{}`

type RequesterConfig<RequestType, PathConfigurationType> = {
    origin?: string;
    headers?: { [key: string]: string };
    cache?: {
        enabled?: boolean;
        ttl?: number;
        maxSize?: number; // default: 200 - maximum size in KB to store in sessionStorage
        purgeable?: boolean; //allows the cache to be purged from sessionStorage when maxSize is reached (with exception when used for meta)
        entries?: { [key: string]: Response }; // default: undefined
    };
    globals?: Partial<RequestType>;
    paths?: Partial<PathConfigurationType>; // override the default API endpoint paths
};

🧩 Available Methods

Each method maps to an Athos API endpoint and returns a promise.

Method	Athos API	Reference Docs
`search`	Search API	Search API
`autocomplete`	Autocomplete API	Autocomplete API
`category`	Category API	Category API
`meta`	Search API (meta only)	Meta API
`trending`	Trending API	Trending API
`finder`	Finder API	Finder API
`recommend`	Recommendations API	Recommendations API

`search`

Makes a request to the Athos Search API.

const client = new Client(globals, clientConfig);

const { meta, search } = await client.search({
  search: {
    query: {
      string: 'dress'
    }
  }
});

`autocomplete`

Makes a request to the Athos Autocomplete API.

const client = new Client(globals, clientConfig);

const { meta, search } = await client.autocomplete({
  suggestions: {
    count: 5
  },
  search: {
    query: {
      string: 'yellw',
    }
  }
});

`category`

Makes a request to the Athos Category API.

const client = new Client(globals, clientConfig);

const { meta, search } = await client.category({
  filters: [{
    field: 'categoryId',
    value: '12345',
    type: 'value',
    background: true,
  }]
});

`meta`

Makes a request to the Athos Search API to fetch meta properties (facets, sort options). The search method uses this internally, but it's also available on its own.

const client = new Client(globals, clientConfig);
const meta = await client.meta();

`trending`

Makes a request to the Athos Trending API. siteId is sourced from globals automatically, but can be overridden per call.

const client = new Client(globals, clientConfig);
const results = await client.trending({
  siteId: 'REPLACE_WITH_YOUR_SITE_ID',
  limit: 5
});

`finder`

Makes a request to the Athos Finder API.

const client = new Client(globals, clientConfig);
const { meta, search } = await client.finder({
  filters: [{
    type: "value",
    field: "color",
    background: false,
    value: "red",
  }]
});

`recommend`

Makes a request to the Athos Recommendations API.

const client = new Client(globals, clientConfig);
const { profile, meta, results, responseId } = await client.recommend({
  tag: 'similar',
  siteId: 'REPLACE_WITH_YOUR_SITE_ID',
  products: ['product123'],
  shopper: '[REPLACE WITH LOGGED IN SHOPPER ID]'
});

🔁 Standalone Usage

Since Snap Client can be used independently of the Snap SDK, this is all you need for a fully working, cached, typed API integration:

const client = new Client(globals, clientConfig);

const { meta, search } = await client.search({
  search: {
    query: {
      string: 'dress'
    }
  }
});

🏁 Get Started

Check the source: Snap Client on GitHub
Explore the full SDK: Snap Documentation
Contribute: We welcome issues and PRs! See our Contribution Guidelines.

❗️
Note: Snap packages are versioned together. If you later adopt Snap Controller or the UI layer, use the matching version of @athoscommerce/snap-client to avoid compatibility issues.