Package reference

One instance, four calls, one track and a few loose pieces. The types come from the OpenAPI contract and are never written by hand: if the contract changes, the package changes with it.

`createStorefront(options): Storefront`

The instance:

Member	What it does
`getRecommendations(input)`	Requests a recommendation. Throws `CrossUpApiError` if it fails
`tryGetRecommendations(input, onError?)`	The same, but an error returns `null`
`getCatalogItem(itemId)`	The canonical aggregate of an item. Throws if it fails
`tryGetCatalogItem(itemId, onError?)`	The same, but an error returns `null`
`track`	The seven signals: Report signals
`flush()`	Sends everything pending now and waits. Never rejects
`pendingSignals()`	How many signals are waiting
`visitor()`	The visitor that would travel now, or `undefined` if it is off
`resetVisitor()`	Forgets the persisted visitor

The options

Only the first two are required.

string

required

The spk_… key you copy from the admin. Why it can be public: Keys and security.

string

required

Your store’s connection (cn_…). It is validated against the key’s store.

string

default:"https://api.crossup.ai/salespilot"

The API endpoint. In production, https://salespilot.crossup.ai.

typeof fetch

Your own fetch, for tests or for a runtime without a global fetch.

boolean

default:"true"

true stores it in localStorage and a cookie, mirrored. false keeps it in memory: it still travels, but every load is a new visitor. Use it without consent.

VisitorStorage

Your own storage. Wins over persistVisitor.

Cookie domain (.mystore.com): the same visitor across all subdomains.

(() => Visitor | undefined) | false

Your own visitor, for those who already resolved it (a server). false sends no visitor in any request.

(error: unknown) => void

Called when the visitor couldn’t be resolved and the request went out without it. Never called with an API error.

(() => ClientContext | undefined) | false

The browser context (page, referrer, UTM, language, screen). By default it is read on every request; false doesn’t send it; a function replaces it. It never breaks the request.

(error: unknown) => void

Every signal that couldn’t be built, that the server rejected, that was dropped on a 4xx or that fell out of the full queue. Never called for a retry.

(result, signal) => void

Every server response to a signal: accepted, duplicate or rejected.

SignalOptions

How signals are batched and retried: flushIntervalMs (2000), maxQueueSize (200), maxBackoffMs (60000), storage. See Report signals.

Types

Type	What it is
`StorefrontOptions`, `SignalOptions`	The options of the instance and of the queue
`RecommendationInput`	`surface`, `placementKey`, `contextItemId?`, `cartItems?`, `visitor?`
`Decision`, `DecisionResult`	The recommendation a request returns (the list of recommended products) and each of its results
`CatalogAggregate`	`item`, `variants`, `availability`
`CartItem`	`item_id`, `variant_id`, `quantity`
`RecommendationSurface`	The six moments; `RECOMMENDATION_SURFACES` is the list and `isShooterSurface()` says whether it starts from a product
`Visitor`, `ClientContext`	What travels with every request
`StorefrontSignal`, `StorefrontSignalType`, `StorefrontSignalResult`, `StorefrontSignalBatch`, `StorefrontSignalBatchResponse`	The signals, as the contract generates them
`DecisionRef`, `ResultRef`	A recommendation or its `decision_id`; a result or its `item_id`
`TrackOptions`, `ImpressionOptions`, `ResultOptions`, `AddToCartOptions`, `UpdateQuantityOptions`, `PurchaseOptions`, `PurchaseItem`	The options of each `track.*`
`StorefrontTrack`	The shape of `track`

Errors

Export	What it is
`CrossUpApiError`	The typed error: `code`, `status`, `requestId`, `extensions`, and `is(code)`
`isCrossUpApiError(err)`	How to recognize it. Use it instead of `instanceof`
`StorefrontSignalError`	A signal that couldn’t be built, was rejected or was dropped; arrives through `onSignalError`
`SignalErrorReason`	The reason of a `StorefrontSignalError`

Visitor and storage

Export	What it is
`VisitorTracker`, `VisitorTrackerOptions`	The one that generates and renews `vis_…` and `ses_…`
`VISITOR_KEY`, `SESSION_KEY`	`crossup_vid`, `crossup_sid`
`DEFAULT_SESSION_TIMEOUT_MS`	30 minutes
`COOKIE_MAX_AGE_SECONDS`	400 days
`defaultStorage()`, `localStorageOf()`, `cookieStorageOf()`, `memoryStorage()`, `mirroredStorage()`	The storages, and how to combine them
`VisitorStorage`, `CookieOptions`	Their types
`isValidVisitor(value)`	Whether something has the shape the contract requires
`collectClientContext()`	The browser context, as the SDK reads it

Signals

Export	What it is
`SignalQueue`, `SignalQueueOptions`, `SignalTimers`	The queue, for those who want to use it on its own
`newSignalId()`, `SIGNAL_ID`	How a `sig_…` is generated, and the pattern it follows
`MAX_BATCH_SIZE`	50
`DEFAULT_FLUSH_INTERVAL_MS`, `DEFAULT_MAX_QUEUE_SIZE`, `DEFAULT_MAX_BACKOFF_MS`	2 000, 200, 60 000
`SIGNALS_KEY`	`crossup_signals`: the queue’s key in `localStorage`
`DEFAULT_BASE_URL`	`https://api.crossup.ai/salespilot`

​createStorefront(options): Storefront

​The options

​Types

​Errors

​Visitor and storage

​Signals

`createStorefront(options): Storefront`

The options

Types

Errors

Visitor and storage

Signals