Installation
npm install @protonagency/sdk
Configuration
Shopify (optional)
Storefront API is opt-in. Enable it for richer product data (metafields, full variant info, collection/page metadata).
| Option | Type | Required | Description |
|---|
enableStorefront | boolean | No | Enable Storefront API hydration (default: false) |
shop | string | When enableStorefront: true | Store domain |
storefrontPublicToken | string | When enableStorefront: true | Storefront API public access token |
storefrontApiVersion | string | No | API version (default: 2025-01) |
fetch | CustomFetch | No | Custom fetch implementation (SSR, testing, proxying) |
Layers
| Option | Type | Required | Description |
|---|
layersPublicToken | string | Yes | Layers API public token |
sorts | Sort[] | Yes | Sort options ({ label, code }) |
facets | string[] | Yes | Facet fields for filtering |
attributes | string[] | No | Product attributes to fetch |
layersBaseUrl | string | No | Custom API URL |
fetch | CustomFetch | No | Custom fetch implementation (SSR, testing, proxying) |
Product
| Option | Type | Description |
|---|
currencyCode | string | Currency for price formatting |
formatPrice | (amount, currency) => string | Custom price formatter |
swatches | Swatch[] | Color swatch definitions |
options | string[] | Product options to expose |
productMetafields | { namespace, key }[] | Product metafields to fetch |
variantMetafields | { namespace, key }[] | Variant metafields to fetch |
Extensibility
| Option | Type | Description |
|---|
extendProduct | (product, raw) => P | Transform products after hydration |
extendCollection | (result, raw) => result | Transform collection results |
extendSearch | (result, raw) => result | Transform search results |
transformFilters | (filters) => FilterGroup | Custom filter transformation |
filterMap | FilterMap | URL-friendly filter key mapping |
// Configure once at initialization
const sdk = createSdk({
// ... base config
extendProduct: (product, raw) => ({
...product,
isNew: raw.tags?.includes('new') ?? false,
rating: raw.calculated?.average_rating,
}),
filterMap: {
color: 'options.color',
size: 'options.size',
},
})
// All SDK methods automatically use your transformers
const collection = sdk.collection({ handle: 'shirts' })
await collection.execute({ filters: { color: 'Red' } }) // filterMap applied
// → result.products have isNew and rating properties
Cache
| Option | Type | Description |
|---|
cacheMaxProducts | number | Max products in cache |
cacheMaxEntries | number | Max query entries in cache |
cacheTtl | number | TTL in milliseconds |
Singleton Access
After initialization, access the SDK anywhere:
import { getSdk, isInitialized } from '@protonagency/sdk'
if (isInitialized()) {
const result = getSdk()
if (result.data) {
const sdk = result.data
// Use sdk
}
}
Important Notes
All SDK methods return a Result type instead of throwing exceptions. Always check for result.error before accessing result.data.
