Client reference

Look here when you need to know exactly what api sends, or how long it waits. For the reason to use it at all, read the Overview.

import { api, cdn, filesCdn } from '@salla.sa/twilight-theme-engine/api/client';

All three are ky instances. ky is a small wrapper around fetch.

apiCopy Anchor Link

The client for the Store API. Its methods are api.get, api.post, api.put, api.patch, api.delete and api.head. Each takes a path relative to the base URL and returns a promise with .json(), .text() and so on.

const { data } = await api.get(`cart/${cartId}`).json<{ data: CartApiResponse }>();

Use paths like 'cart/1'. A per-request timeout, headers, signal or retry option overrides the defaults for that call.

Base URLCopy Anchor Link

The client picks its base URL once, when the module loads, in this order:

1. The apiBase the server published into the page, so the browser keeps talking to the backend that rendered it.
2. VITE_API_URL, at build time or from the server's environment.
3. https://api.salla.dev/store/v1.

A live storefront sets neither, so it uses the default. VITE_API_URL exists to point a preview at another backend.

cdn and filesCdnCopy Anchor Link

Ky instances for static files. cdn has base URL https://cdn.salla.network and filesCdn has https://cdn.files.salla.network; both time out after 5000 ms. They send none of the store, token or scope headers. The translations module uses them.

Headers on every api requestCopy Anchor Link

The client sets these just before sending, so a value you pass for accept or accept-language is overwritten. Only store-identifier keeps your value. Where the token, scope and version come from is explained in Authentication and scope.

getActiveCurrencyCopy Anchor Link

A store can let shoppers see prices in another currency. The Salla SDK keeps the choice in the s-curr cookie. getActiveCurrency() returns that code, such as 'EUR', or null when the shopper kept the store's own currency. Pass a fallback to get it instead of null.

function getActiveCurrency(): string | null
function getActiveCurrency(fallback: string): string

The client sends the same value as the currency header, on the server and in the browser, so the API answers with converted amounts. It reads the request cookie on the server and document.cookie in the browser, and returns only a three-letter code.

import { getActiveCurrency } from '@salla.sa/twilight-theme-engine/api/client';
import { CurrencySymbol } from '@salla.sa/twilight-theme-engine/common';
import type { Product } from '@salla.sa/twilight-theme-engine/types';

export function PriceLabel({ product }: { product: Product }) {
  return (
    <span>
      {product.price} <CurrencySymbol currency={getActiveCurrency(product.currency)} />
    </span>
  );
}

useMoney().format already labels amounts with the chosen currency when you pass no currency.

Timeouts and retriesCopy Anchor Link

All three keep ky's default retry behaviour:

The timeout applies to each attempt. A failure throws HTTPError (non-2xx), TimeoutError or NetworkError.

NextCopy Anchor Link

• Authentication and scope: where the token, scope and version come from.
• Errors, timeouts and retries: handling the errors above.
• Write your own endpoint