@ensemblekit/sdk-types 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# @ensemblekit/sdk-types
+
+TypeScript types for the Ensemble browser SDK wire contract — the
+`window.recs` 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
+
+```ts
+import type {RecsCommand, RecsEventPayloads} from '@ensemblekit/sdk-types';
+```
+
+To type `window.recs` globally, add one side-effect import (or put
+`@ensemblekit/sdk-types/global` in your tsconfig `types`):
+
+```ts
+import '@ensemblekit/sdk-types/global';
+
+window.recs?.('track', 'product_viewed', {
+  productId: 'gid://shopify/Product/1',
+  handle: 'slim-cuff-pant',
+  price: 98,
+  currency: 'GBP',
+});
+```
+
+Naming note: the product is Ensemble; the wire-level global and command verb
+are `recs` by design (the `gtag()` precedent), so type names keep the `Recs`
+prefix to match `window.recs`.
+
+## 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.

package/dist/global.d.ts

@@ -0,0 +1,19 @@
+import { RecsCommand } from './index.js';
+
+/**
+ * Optional global augmentation: `import '@ensemblekit/sdk-types/global'` (or add
+ * it to tsconfig `types`) to type `window.recs` without hand-declaring it.
+ */
+
+declare global {
+    interface Window {
+        /**
+         * The Ensemble SDK global. The bootstrap snippet installs the `q` queue
+         * function; `/sdk/v1.js` replaces it with a live dispatcher that drains
+         * the queue. Absent until one of them has run.
+         */
+        recs?: RecsCommand & {
+            q?: unknown[];
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Published types for the Ensemble browser SDK wire contract.
+ *
+ * The runtime contract is the zod schemas in @recs/core (what the SDK and
+ * ingest actually validate). The shapes below are authored — the published
+ * .d.ts must be dependency-free, so it can't reference zod — but drift is
+ * compile-time impossible: typetests/contract-lock.ts asserts identity
+ * against the z.infer types, and the workspace typecheck fails on any
+ * mismatch.
+ *
+ * Naming note: the product is Ensemble; the wire-level global and command
+ * verb are `recs` by design (the gtag/analytics precedent), so exported
+ * type names keep the Recs prefix to match `window.recs`.
+ */
+/** Cart/order line snapshot shared by cart_viewed, cart_updated, order_completed. */
+type RecsLine = {
+    productId: string;
+    variantId: string;
+    qty: number;
+    price: number;
+};
+type RecSlotPayload = {
+    slot: string;
+    campaignId: string;
+    productId: string;
+    position: number;
+    modelVersion: string;
+};
+/** Payload shapes for the SDK's strict event names, keyed by event name. */
+type RecsEventPayloads = {
+    page_viewed: {
+        pageType: string;
+        path: string;
+    };
+    product_viewed: {
+        productId: string;
+        handle: string;
+        variantId?: string;
+        price: number;
+        currency: string;
+    };
+    collection_viewed: {
+        collectionHandle: string;
+        productIds: string[];
+    };
+    cart_viewed: {
+        lines: RecsLine[];
+    };
+    search_viewed: {
+        query: string;
+        productIds: string[];
+    };
+    cart_updated: {
+        lines: RecsLine[];
+    };
+    product_added_to_cart: {
+        productId: string;
+        variantId: string;
+        qty: number;
+        price: number;
+        currency: string;
+    };
+    product_removed_from_cart: {
+        productId: string;
+        variantId: string;
+        qty: number;
+    };
+    order_completed: {
+        orderId: string;
+        total: number;
+        currency: string;
+        lines: RecsLine[];
+    };
+    rec_impression: RecSlotPayload;
+    rec_clicked: RecSlotPayload;
+};
+/** The strict event names accepted by `recs('track', ...)`. */
+type RecsEventName = keyof RecsEventPayloads;
+/** Config accepted by `recs('init', ...)`. */
+type RecsInitConfig = {
+    storeId: string;
+    /** Absolute URL of the ingest endpoint (POST /v1/events). Derived from the
+     * SDK script's own src origin when omitted. */
+    endpoint?: string;
+    redactPaths?: RegExp[];
+    debug?: boolean;
+};
+/**
+ * Shape of `window.recs`. Before the SDK script loads it is the bootstrap
+ * command queue; once `/sdk/v1.js` loads it is replaced with a live
+ * dispatcher that drains the queue. Both accept the same six commands.
+ */
+interface RecsCommand {
+    (command: 'init', config: RecsInitConfig): void;
+    (command: 'consent', state: 'granted' | 'revoked'): void;
+    <E extends RecsEventName>(command: 'track', name: E, payload: RecsEventPayloads[E]): void;
+    (command: 'signal', name: string, payload: Record<string, unknown>): void;
+    (command: 'customer', id?: string): void;
+    (command: 'flush'): void;
+}
+
+export type { RecsCommand, RecsEventName, RecsEventPayloads, RecsInitConfig, RecsLine };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@ensemblekit/sdk-types",
+  "version": "0.1.0",
+  "description": "TypeScript types for the Ensemble browser SDK wire contract (the window.recs command surface)",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts"
+    },
+    "./global": {
+      "types": "./dist/global.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.6.0",
+    "@recs/collector": "0.0.0",
+    "@recs/core": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/global.ts --dts-only --format esm --out-dir dist && node scripts/check-self-contained.mjs",
+    "test": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  }
+}