@ensemblekit/sdk-types

TypeScript types for the Ensemble browser SDK wire contract — the window.ensemble command surface installed by the hosted script tag ({ingest-origin}/sdk/v1.js).

Types only: no runtime, no dependencies. The SDK itself is never installed from npm; storefronts load it via the script tag.

Usage

import type {EnsembleCommand, EnsembleEventPayloads} from '@ensemblekit/sdk-types';

To type window.ensemble globally, add one side-effect import (or put @ensemblekit/sdk-types/global in your tsconfig types):

import '@ensemblekit/sdk-types/global';

window.ensemble?.('track', 'product_viewed', {
  productId: 'gid://shopify/Product/1',
  handle: 'slim-cuff-pant',
  price: 98,
  currency: 'GBP',
});

Naming note: the developer-facing surface is the brand — window.ensemble and Ensemble* type names. Wire plumbing (the _recs_vid/_recs_sid cookies and the /v1/events path) keeps the recs working name.

Contract guarantee

The runtime contract is the zod schemas in the Ensemble monorepo's @recs/core — what the SDK and ingest actually validate. The shapes published here are locked to those schemas by a compile-time identity assertion (typetests/contract-lock.ts); any mismatch fails the workspace typecheck, so a release cannot drift from the wire contract.

Versioning follows the contract's schema policy: the ingest accepts schema versions {N, N−1}, and payload-shape changes bump this package accordingly.