@ensemblekit/sdk-types 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,7 @@
 # @ensemblekit/sdk-types
 
 TypeScript types for the Ensemble browser SDK wire contract — the
-`window.recs` command surface installed by the hosted script tag
+`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
@@ -10,16 +10,16 @@ from npm; storefronts load it via the script tag.
 ## Usage
 
 ```ts
-import type {RecsCommand, RecsEventPayloads} from '@ensemblekit/sdk-types';
+import type {EnsembleCommand, EnsembleEventPayloads} from '@ensemblekit/sdk-types';
 ```
 
-To type `window.recs` globally, add one side-effect import (or put
+To type `window.ensemble` 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', {
+window.ensemble?.('track', 'product_viewed', {
   productId: 'gid://shopify/Product/1',
   handle: 'slim-cuff-pant',
   price: 98,
@@ -27,9 +27,9 @@ window.recs?.('track', 'product_viewed', {
 });
 ```
 
-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`.
+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
 

package/dist/global.d.ts

@@ -1,8 +1,8 @@
-import { RecsCommand } from './index.js';
+import { EnsembleCommand } 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.
+ * it to tsconfig `types`) to type `window.ensemble` without hand-declaring it.
  */
 
 declare global {
@@ -12,7 +12,7 @@ declare global {
          * function; `/sdk/v1.js` replaces it with a live dispatcher that drains
          * the queue. Absent until one of them has run.
          */
-        recs?: RecsCommand & {
+        recs?: EnsembleCommand & {
             q?: unknown[];
         };
     }

package/dist/index.d.ts

@@ -8,12 +8,12 @@
  * 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`.
+ * Naming note: the developer-facing surface is the brand — `window.ensemble`
+ * and Ensemble* type names. Wire plumbing (cookies `_recs_vid`/`_recs_sid`,
+ * the /v1/events path, internal package names) keeps the `recs` working name.
  */
 /** Cart/order line snapshot shared by cart_viewed, cart_updated, order_completed. */
-type RecsLine = {
+type EnsembleLine = {
     productId: string;
     variantId: string;
     qty: number;
@@ -27,7 +27,7 @@ type RecSlotPayload = {
     modelVersion: string;
 };
 /** Payload shapes for the SDK's strict event names, keyed by event name. */
-type RecsEventPayloads = {
+type EnsembleEventPayloads = {
     page_viewed: {
         pageType: string;
         path: string;
@@ -44,14 +44,14 @@ type RecsEventPayloads = {
         productIds: string[];
     };
     cart_viewed: {
-        lines: RecsLine[];
+        lines: EnsembleLine[];
     };
     search_viewed: {
         query: string;
         productIds: string[];
     };
     cart_updated: {
-        lines: RecsLine[];
+        lines: EnsembleLine[];
     };
     product_added_to_cart: {
         productId: string;
@@ -69,15 +69,15 @@ type RecsEventPayloads = {
         orderId: string;
         total: number;
         currency: string;
-        lines: RecsLine[];
+        lines: EnsembleLine[];
     };
     rec_impression: RecSlotPayload;
     rec_clicked: RecSlotPayload;
 };
 /** The strict event names accepted by `recs('track', ...)`. */
-type RecsEventName = keyof RecsEventPayloads;
+type EnsembleEventName = keyof EnsembleEventPayloads;
 /** Config accepted by `recs('init', ...)`. */
-type RecsInitConfig = {
+type EnsembleInitConfig = {
     storeId: string;
     /** Absolute URL of the ingest endpoint (POST /v1/events). Derived from the
      * SDK script's own src origin when omitted. */
@@ -86,17 +86,17 @@ type RecsInitConfig = {
     debug?: boolean;
 };
 /**
- * Shape of `window.recs`. Before the SDK script loads it is the bootstrap
+ * Shape of `window.ensemble`. 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;
+interface EnsembleCommand {
+    (command: 'init', config: EnsembleInitConfig): void;
     (command: 'consent', state: 'granted' | 'revoked'): void;
-    <E extends RecsEventName>(command: 'track', name: E, payload: RecsEventPayloads[E]): void;
+    <E extends EnsembleEventName>(command: 'track', name: E, payload: EnsembleEventPayloads[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 };
+export type { EnsembleCommand, EnsembleEventName, EnsembleEventPayloads, EnsembleInitConfig, EnsembleLine };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ensemblekit/sdk-types",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript types for the Ensemble browser SDK wire contract (the window.recs command surface)",
   "type": "module",
   "license": "MIT",
@@ -21,8 +21,8 @@
   "devDependencies": {
     "tsup": "^8.5.1",
     "typescript": "^5.6.0",
-    "@recs/collector": "0.0.0",
-    "@recs/core": "0.0.0"
+    "@recs/core": "0.0.0",
+    "@recs/collector": "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",