@avsbhq/snippet-types 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AvsB Platform
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# @avsbhq/snippet-types
+
+TypeScript types for `window.avsb`, the A vs B web-snippet API.
+
+Types only. Nothing is bundled, nothing runs, and your production build is
+unchanged: the snippet itself arrives from the A vs B CDN through the install tag
+you paste into your site.
+
+## Install
+
+```bash
+npm install --save-dev @avsbhq/snippet-types
+```
+
+## Use it
+
+These are global declarations, so add the package to `types` in your
+`tsconfig.json` rather than importing it:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@avsbhq/snippet-types"]
+  }
+}
+```
+
+If you would rather not touch `types` (which replaces the default "include every
+installed type package" behaviour), reference it from any `.d.ts` in your project
+instead:
+
+```ts
+// docs-example: not typechecked here, because the A vs B repository does not install @avsbhq/snippet-types as a dependency, so the type reference has nothing to resolve against
+
+/// <reference types="@avsbhq/snippet-types" />
+```
+
+Either way, `avsb` and `window.avsb` are typed everywhere, and every shape has a
+name you can use:
+
+```ts
+avsb.ready?.(() => {
+  avsb.track.event('signup_completed', { revenue: 49.99 });
+
+  const variation: string | null = avsb.getVariation('exp_id_from_the_dashboard');
+  if (variation) console.log('running', variation, 'on snippet', avsb.version);
+});
+
+function reportOrder(order: AvsbPurchaseOrder): void {
+  avsb.track.purchase(order);
+}
+
+const unsubscribe = avsb.on?.('event', (record: AvsbIntegrationRecord) => {
+  if (record.event_type === 'exposure') myAnalytics.track('AB exposure', { ...record });
+});
+unsubscribe?.();
+```
+
+`ready`, `on` and `consent` are optional on `AvsbApi` because the preview bypass
+runtime does not define them, so reach them with `?.` as above.
+
+`getVisitorId()` is typed `string | null`, because there is no visitor id before
+`avsb.init()` in consent mode, and none at all for a visitor who denied
+analytics:
+
+```ts
+const visitorId: string | null = avsb.getVisitorId();
+if (visitorId) sendToYourBackend(visitorId);
+```
+
+## The names
+
+`AvsbApi` is the type of `window.avsb`. The shapes it uses are all named too:
+`AvsbTrackFunction`, `AvsbTrackEventProperties`, `AvsbPurchaseOrder`,
+`AvsbPurchaseItem`, `AvsbIntegrationRecord`, `AvsbIntegrationEventType`,
+`AvsbConsentApi`, `AvsbConsentState`, `AvsbDatasetHandle`,
+`AvsbDatasetGetResult`, `AvsbRecsClient`, `AvsbRecsRequest`, `AvsbRecsResult`,
+`AvsbRecProduct`, `AvsbCommerceApi`, `AvsbContractProduct`, `AvsbContractCart`,
+`AvsbContractCartLine`, `AvsbUtils`, `AvsbWaitUntilFn`, `AvsbWaitTarget`,
+`AvsbWaitOptions`, `AvsbGuardedThenable`, `AvsbCookieApi`, `AvsbKVStore`,
+`AvsbElementProps`.
+
+Every one of them is global, so no import is needed, and every one is stable:
+names here are only added, never renamed or removed.
+
+## Writing variation, trigger, or project code
+
+Code written inside the A vs B editor gets an `options` toolkit and the
+`initVariation` / `initTrigger` / `initProject` entry points. Those are authoring
+globals, so they live behind a subpath and stay out of your site's global scope:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@avsbhq/snippet-types", "@avsbhq/snippet-types/variation-code"]
+  }
+}
+```
+
+```ts
+function initVariation(options: AvsbVariationOptions): void {
+  options.waitUntil<HTMLElement>('.hero h1').then((el) => {
+    options.utils.setText(el, 'A clearer headline');
+    options.track.event('hero_seen');
+  });
+}
+```
+
+The A vs B CLI (`avsb clone`) already writes this configuration for you when it
+scaffolds a local experiment project.
+
+## Calling the API before the snippet has loaded
+
+The loader tag is `async`, so the API can arrive after your own code runs. The
+install tag defines `avsb.ready`, `avsb.on`, `avsb.consent.set` and the four
+`avsb.track.*` methods from the first byte of the page, so those calls are queued
+and replayed. Everything else belongs inside `avsb.ready(...)`.
+
+## Versioning
+
+Published in lockstep with the rest of the `@avsbhq/*` family. The declarations
+mirror the snippet runtime's own types, and a test in the A vs B repository fails
+if the two drift apart.
+
+## Links
+
+- [Snippet SDK API reference](https://avsb.cloud/docs/developer-reference/snippet-sdk-api)
+- [Tracking events](https://avsb.cloud/docs/developer-reference/tracking-events)
+- [Debug mode](https://avsb.cloud/docs/troubleshooting/debug-mode)

package/avsb.d.ts

@@ -0,0 +1,413 @@
+// TypeScript declarations for `window.avsb`, the A vs B web-snippet API.
+//
+// SOURCE OF TRUTH for two consumers: this package (`@avsbhq/snippet-types`), and
+// the dashboard code editor's ambient lib at `snippet/types/avsb.d.ts`, which is
+// a generated copy (run `npm run sync:types` here after editing; `sync.test.ts`
+// fails if it drifts).
+//
+// Every shape mirrors the runtime's own types in `snippet/src/types.ts` (plus
+// `utils/types.ts`, `purchase.ts`, `datasets.ts`, `recs.ts`, `commerceTypes.ts`),
+// and `sync.test.ts` asserts that `AvsbApi` and `AvsbTrackFunction` carry exactly
+// the members of `AvsbPublicAPI` and `TrackFunction` there, so an API added to the
+// snippet cannot quietly go missing here.
+//
+// Two rules for editing:
+//
+//  - Keep every interface member on ONE line. The sync test reads members by line.
+//  - Never add an `import` or `export`. That turns the file into a module, which
+//    hides every name below and stops `interface Window` merging with the
+//    browser's own, so consumers following the documented setup get nothing.
+//    Names are FROZEN at launch: rename nothing, add only.
+
+// --- Tracking ---
+
+interface AvsbTrackEventProperties {
+  /** Monetary amount for this event. Feeds revenue metrics. Plain number, no currency symbol. */
+  revenue?: number
+  /** Continuous measurement (order value, load time, scroll depth) for percentile and value metrics. */
+  value?: number
+}
+
+interface AvsbPurchaseItem {
+  sku: string
+  /** Parent product id when `sku` is a variant. Defaults to `sku` server-side. */
+  productKey?: string
+  name?: string
+  price?: number
+  quantity?: number
+  category?: string
+}
+
+/** An order passed to `avsb.track.purchase`. Money is decimal, in the project currency. */
+interface AvsbPurchaseOrder {
+  /** Unique order id. Required. */
+  orderId: string
+  /** Order total as a decimal, e.g. 99.95. Required. */
+  total: number
+  /** ISO 4217 code. Defaults to the project currency. */
+  currency?: string
+  subtotal?: number
+  shipping?: number
+  tax?: number
+  discount?: number
+  coupon?: string
+  /** Stored but excluded from every calculation. For testing your integration. */
+  test?: boolean
+  items?: AvsbPurchaseItem[]
+}
+
+interface AvsbTrackFunction {
+  /** Fire a custom event by its metric event key. Numbers are coerced to strings, so a numeric key works when the metric's key is those digits. An unmatched key warns and lists the keys that do work. */
+  event(eventKey: string | number, properties?: AvsbTrackEventProperties): void
+  /** Record a visitor attribute you can slice results by. */
+  segment(segmentKey: string, segmentValue: string): void
+  /** Send an order immediately. Not batched. */
+  purchase(order: AvsbPurchaseOrder): void
+  /** Tell the snippet the current cart total, for commerce audience conditions. `totalMinor` wins when both are set. */
+  cart(cart: { total?: number; totalMinor?: number }): void
+}
+
+// --- Event bus record ---
+
+type AvsbIntegrationEventType =
+  | 'exposure'
+  | 'goal'
+  | 'purchase'
+  | 'rec_impression'
+  | 'rec_click'
+  | 'custom'
+  | 'test'
+
+/**
+ * The record delivered to `avsb.on('event')` subscribers, one per dispatched
+ * exposure, goal, purchase, or rec event. snake_case, shaped for analytics tools.
+ */
+interface AvsbIntegrationRecord {
+  /** Experiment shortId as a string. */
+  experiment_id: string
+  /** Display name; falls back to the shortId, never an empty string. */
+  experiment_name: string
+  /** Variation shortId as a string. */
+  variation_id: string
+  /** Display name; falls back to the shortId, never an empty string. */
+  variation_name: string
+  event_type: AvsbIntegrationEventType
+  /** Rendered event name (native defaults plus your configured overrides). */
+  event_name: string
+  /** UUID; matches the AvsB event id for tracker-queued events. */
+  event_id: string
+  revenue: number | null
+  value: number | null
+  /** Purchases only. */
+  currency?: string
+  /** Purchases only: the order id. */
+  transaction_id?: string
+  /** Goals and custom events: metric `type:shortId` or the developer eventKey. */
+  goal_key?: string
+  visitor_id: string
+  page_url: string
+  timestamp: number
+  sdk_version: string
+  /** Recommendation product data (recipe, items, position, ...). */
+  attributes?: Record<string, string | number>
+  /** Set to 'preview' or 'internal' on QA traffic; absent for live visitors. */
+  source?: 'preview' | 'internal'
+}
+
+// --- Waiting ---
+
+// A wait target: a CSS selector, a `window.x.y` global path, or a predicate.
+type AvsbWaitTarget<T = unknown> = string | (() => T)
+
+interface AvsbWaitOptions {
+  /** Milliseconds before the wait rejects. Default 10000. */
+  timeout?: number
+  /** Resolve a selector with an array of all matches (querySelectorAll). */
+  all?: boolean
+}
+
+// Promise-like whose `.catch()` is OPTIONAL: a failed wait logs gracefully rather
+// than raising an unhandled rejection. `.stop()` cancels it.
+interface AvsbGuardedThenable<T> extends PromiseLike<T> {
+  then<R1 = T, R2 = never>(
+    onFulfilled?: ((value: T) => R1 | PromiseLike<R1>) | null,
+    onRejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null
+  ): AvsbGuardedThenable<R1 | R2>
+  catch<R = never>(
+    onRejected?: ((reason: unknown) => R | PromiseLike<R>) | null
+  ): AvsbGuardedThenable<T | R>
+  finally(onFinally?: (() => void) | null): AvsbGuardedThenable<T>
+  stop(): void
+}
+
+interface AvsbWaitUntilFn {
+  /** Wait for a selector / `window.x.y` path / predicate to resolve. */
+  <T = unknown>(target: AvsbWaitTarget<T>, opts?: AvsbWaitOptions): AvsbGuardedThenable<T>
+  /** Wait for several targets at once; resolves with an array of results. */
+  <T extends unknown[]>(targets: AvsbWaitTarget[], opts?: AvsbWaitOptions): AvsbGuardedThenable<T>
+}
+
+// --- Consent ---
+
+/** Per-category consent flags. An absent key means "not expressed" (allowed). */
+interface AvsbConsentState {
+  analytics?: boolean
+  marketing?: boolean
+}
+
+/**
+ * Visitor consent, the hook your cookie banner calls. `set` persists for 1 year in
+ * the first-party `avsb_consent` cookie and wins over the inferred Google signal.
+ */
+interface AvsbConsentApi {
+  set(state: AvsbConsentState): void
+  get(): AvsbConsentState
+}
+
+// --- Datasets ---
+
+interface AvsbDatasetGetResult {
+  found: boolean
+  /** FEED only: the row's ordered items array. */
+  items?: unknown[]
+  /** TABLE only: the full row object. */
+  row?: unknown
+  /** LIST only: whether the key is a member of the list. */
+  member?: boolean
+  meta: { slug: string; version: number | null }
+}
+
+interface AvsbDatasetHandle {
+  get(key: string): Promise<AvsbDatasetGetResult>
+  has(key: string): Promise<boolean>
+}
+
+// --- Recommendations ---
+
+interface AvsbRecProduct {
+  id: string
+  title?: string
+  image?: string
+  href?: string
+  category?: string
+  /** MINOR units (ISO-4217). */
+  price?: number
+  /** MINOR units. */
+  compareAtPrice?: number
+  currency?: string
+  availability?: 'in_stock' | 'out_of_stock' | 'removed'
+}
+
+interface AvsbRecsRequest {
+  recipe: string
+  context?: { seed?: string; seeds?: string[]; recentlyViewed?: number }
+  maxItems?: number
+  excludeOutOfStock?: boolean
+  /** Which rec surface this call serves, for multi-surface pages. */
+  surface?: string
+}
+
+interface AvsbRecsResult {
+  items: AvsbRecProduct[]
+  served: boolean
+  recipe: string
+  /** Slug of the chain step that served, null on a miss. */
+  source: string | null
+  fallbackStep: number | null
+  /** True when the resolve failed (timeout, network, HTTP, parse). */
+  degraded: boolean
+}
+
+interface AvsbRecsClient {
+  /** Resolve items for a recipe. Auto-fires rec:impression on success. Never throws. */
+  get(req: AvsbRecsRequest): Promise<AvsbRecsResult>
+  /** Fire a rec:click for a product the visitor clicked. */
+  trackClick(productId: string, opts?: { position?: number }): void
+  /** Record a product view (feeds recently-viewed and commerce audiences). */
+  trackView(sku: string, meta?: { category?: string }): void
+}
+
+// --- Commerce data contract ---
+
+interface AvsbContractProduct {
+  /** Required. The merchant's product id. */
+  sku: string
+  /** Product-grain canonical key. Defaults to `sku`. */
+  productKey?: string
+  title?: string
+  /** Major units as displayed. */
+  price?: number
+  /** Already-minor integer. Wins over `price`. */
+  priceMinor?: number
+  compareAtPrice?: number
+  compareAtPriceMinor?: number
+  currency?: string
+  image?: string
+  url?: string
+  brand?: string
+  category?: string
+  categories?: string[]
+  availability?: 'in_stock' | 'out_of_stock' | 'preorder'
+  stock?: number
+  variant?: { variantSku: string; options?: Record<string, string>; price?: number; priceMinor?: number; stock?: number }
+  customFields?: Record<string, string | number | boolean>
+  /** ms-epoch product createdAt. */
+  createdAt?: number
+}
+
+interface AvsbContractCartLine {
+  sku: string
+  productKey?: string
+  quantity: number
+  price?: number
+  priceMinor?: number
+  variantSku?: string
+}
+
+interface AvsbContractCart {
+  items: AvsbContractCartLine[]
+  total?: number
+  totalMinor?: number
+  currency?: string
+}
+
+interface AvsbCommerceApi {
+  productView(p: AvsbContractProduct): void
+  /** Category / collection impressions. */
+  productList(items: AvsbContractProduct[], meta?: { listId?: string }): void
+  addToCart(line: AvsbContractCartLine): void
+  removeFromCart(line: AvsbContractCartLine): void
+  /** Full cart snapshot. */
+  cart(cart: AvsbContractCart): void
+  checkoutStep(step: { step: number | string; cart?: AvsbContractCart }): void
+  search(q: { query: string; resultCount?: number; skus?: string[] }): void
+  categoryView(c: { category: string; skus?: string[] }): void
+  wishlist(w: { sku: string; action: 'add' | 'remove' }): void
+}
+
+// --- Utils toolkit (avsb.utils.* and options.utils.*) ---
+interface AvsbCookieApi {
+  get(name: string): string | null
+  set(name: string, value: string, opts?: { days?: number; path?: string; domain?: string; sameSite?: 'Lax' | 'Strict' | 'None'; secure?: boolean }): void
+  remove(name: string): void
+}
+
+interface AvsbKVStore {
+  get<T = unknown>(key: string): T | null
+  set(key: string, value: unknown): void
+  remove(key: string): void
+}
+
+interface AvsbElementProps {
+  class?: string
+  id?: string
+  text?: string
+  html?: string
+  attrs?: Record<string, string>
+  style?: Record<string, string>
+  on?: Record<string, EventListener>
+}
+
+interface AvsbUtils {
+  /** Guarded, promise-based wait. `.catch()` optional; failures log gracefully. */
+  waitUntil: AvsbWaitUntilFn
+  /** Alias of waitUntil (Qubit `poll` compatibility). */
+  poll: AvsbWaitUntilFn
+  /** Resolve once a single selector is present. */
+  waitForElement(selector: string, opts?: { timeout?: number; root?: ParentNode }): AvsbGuardedThenable<Element>
+  /** Run a callback for each matching element, now and on future mutations. Supports shadow roots via `root`. */
+  onMutation(selector: string, callback: (el: Element) => void, opts?: { root?: ParentNode; once?: boolean; attributes?: boolean }): { stop(): void }
+  once<F extends (...args: never[]) => unknown>(fn: F): F
+  throttle<F extends (...args: never[]) => void>(fn: F, ms: number): F & { cancel(): void }
+  debounce<F extends (...args: never[]) => void>(fn: F, ms: number): F & { cancel(): void }
+  raf(fn: FrameRequestCallback): { cancel(): void }
+  idle(fn: () => void, opts?: { timeout?: number }): { cancel(): void }
+  domReady(): AvsbGuardedThenable<void>
+  retry<T>(fn: () => Promise<T> | T, opts?: { attempts?: number; delay?: number; factor?: number }): Promise<T>
+  $(selector: string, root?: ParentNode): Element | null
+  $$(selector: string, root?: ParentNode): Element[]
+  createElement(tag: string, props?: AvsbElementProps, children?: (Node | string)[]): HTMLElement
+  insertAfter(newNode: Node, ref: Node): void
+  insertBefore(newNode: Node, ref: Node): void
+  wrap(node: Node, wrapper: HTMLElement): void
+  remove(node: Node): void
+  setText(node: Node, text: string): void
+  /** Sets innerHTML; scrubs scripts and handlers unless `{ raw: true }`. */
+  setHtml(node: Element, html: string, opts?: { raw?: boolean }): void
+  /** Direct listener, or (with a selector string target) a delegated listener that also catches future nodes. */
+  on(target: EventTarget | string, type: string, handler: (event: Event, matched?: Element) => void, opts?: AddEventListenerOptions): { off(): void }
+  /** Fires on client-side route changes. */
+  onUrlChange(callback: (url: string) => void): { off(): void }
+  cookie: AvsbCookieApi
+  query: { get(name: string): string | null; getAll(): Record<string, string> }
+  storage: { local: AvsbKVStore; session: AvsbKVStore }
+  /** Share values between triggers.js and variation.js of the same experiment. */
+  state: { get<T = unknown>(key: string): T | undefined; set(key: string, value: unknown): void }
+  /** Scoped logger: debug/info emit only in debug, preview, or dev mode; warn always. */
+  log: { debug(...args: unknown[]): void; info(...args: unknown[]): void; warn(...args: unknown[]): void }
+}
+
+// --- Experiment decisions ---
+
+/** Why an experiment did or did not run for this visit. `variant` / `control` mean the visitor is IN the test. */
+type AvsbDecisionStatus = 'variant' | 'control' | 'trigger-pending' | 'not-targeted' | 'audience-mismatch' | 'excluded' | 'traffic-holdout' | 'capped' | 'scheduled-off' | 'error'
+
+/** One row of `avsb.getExperimentDecisions()`. The variation fields are present only when a variation was assigned. */
+interface AvsbExperimentDecision {
+  experimentId: string
+  status: AvsbDecisionStatus
+  variationId?: string
+  variationName?: string
+}
+
+// --- The global API ---
+
+interface AvsbApi {
+  /** Consent mode only: start the snippet once the visitor has agreed. No effect otherwise. */
+  init(): void | Promise<void>
+  /** Stop everything and forget the visitor: tracking off, timers and listeners cleared, variations reverted, visitor cookie expired. */
+  disable(): void
+  track: AvsbTrackFunction
+  /** The visitor's id, or null when there isn't one (before `init()` in consent mode, or for a visitor who denied analytics). */
+  getVisitorId(): string | null
+  /** Replace the visitor id to stitch a browser onto a logged-in account. Drops sticky assignments and re-evaluates, so the variation can change. Returns false for an unusable id. */
+  setVisitorId(visitorId: string): boolean
+  /** The variation this visitor is assigned in the experiment, or null. Pass the numeric **Experiment ID** from the experiment details panel (a number or its string form); the value returned is that variation's numeric **Variation ID**. Internal UUIDs are not accepted. */
+  getVariation(experimentId: string | number): string | null
+  /** Force a variation, for QA, by the numeric **Experiment ID** and **Variation ID** shown in the experiment details panel. `{ track: false }` applies it without recording an exposure. */
+  forceVariation(experimentId: string | number, variationId: string | number, options?: { track?: boolean }): boolean
+  waitUntil: AvsbWaitUntilFn
+  utils: AvsbUtils
+  /** Subscribe to every experiment event. Returns an unsubscribe function. Absent in the preview bypass runtime. */
+  on?(event: 'event', callback: (record: AvsbIntegrationRecord) => void): () => void
+  /** Run a callback once experiments have been evaluated. Safe to call before the snippet loads. */
+  ready?(callback: () => void): void
+  /** @deprecated Use `ready`. Same machinery. */
+  onReady(callback: () => void): void
+  /** Visitor consent: `set` from your banner, `get` for the effective state. Absent in the preview bypass runtime. */
+  consent?: AvsbConsentApi
+  /** Experiments this visitor is active in on this page, as the same numeric dashboard ids `getVariation` takes, in string form. */
+  getActiveExperiments(): Array<{ experimentId: string; variationId: string }>
+  /** One row per experiment on the page: what happened to this visit and why (held out, mismatched, pending, running). Rebuilt on every evaluation; empty before evaluation and after `disable()`. Optional: absent on snippet builds that predate it, so read it as `avsb.getExperimentDecisions?.()`. */
+  getExperimentDecisions?(): AvsbExperimentDecision[]
+  /** Read a server-side dataset. Never throws: unknown slugs resolve `{ found: false }`. */
+  dataset(slug: string): AvsbDatasetHandle
+  /** Headless recommendations. Inside variation code prefer `options.recs`, which attributes automatically. */
+  recs: AvsbRecsClient
+  /** Commerce events. Buffered until the commerce chunk loads. */
+  commerce: AvsbCommerceApi
+  /** Leave a shared preview link: clears the preview token and reloads. */
+  exitPreview(): void
+  /** Re-run every experiment against the page as it is now. For app-driven navigation the History API never sees. */
+  refresh(): void
+  /** The snippet build running on this page, e.g. `1.1.0`. */
+  version: string
+}
+
+/** `window.avsb`. `q` is the install tag's early-call queue, drained by the runtime. */
+interface Window {
+  avsb: AvsbApi & { q?: Array<[string, ...unknown[]]> }
+}
+
+/** The same object as `window.avsb`, so `avsb.track.event(...)` reads cleanly. */
+declare const avsb: AvsbApi

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@avsbhq/snippet-types",
+  "version": "1.0.0",
+  "description": "TypeScript declarations for window.avsb, the A vs B web-snippet API",
+  "keywords": [
+    "avsb",
+    "ab-testing",
+    "experiments",
+    "types",
+    "typescript",
+    "snippet"
+  ],
+  "license": "MIT",
+  "sideEffects": false,
+  "types": "./avsb.d.ts",
+  "exports": {
+    ".": {
+      "types": "./avsb.d.ts"
+    },
+    "./variation-code": {
+      "types": "./variation-code.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "avsb.d.ts",
+    "variation-code.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/avsbhq/a-vs-b.git",
+    "directory": "packages/avsb-snippet-types"
+  },
+  "homepage": "https://github.com/avsbhq/a-vs-b/tree/main/packages/avsb-snippet-types#readme",
+  "bugs": {
+    "url": "https://github.com/avsbhq/a-vs-b/issues"
+  },
+  "scripts": {
+    "sync:types": "node ../../snippet/scripts/syncSnippetTypes.mjs",
+    "check:types": "node ../../snippet/scripts/syncSnippetTypes.mjs --check"
+  }
+}

package/variation-code.d.ts

@@ -0,0 +1,72 @@
+// TypeScript declarations for code you write INSIDE A vs B: variation code,
+// trigger code, and project code. Companion to `avsb.d.ts`, which types the
+// `window.avsb` global and must be loaded alongside this file.
+//
+// Kept separate because these are authoring globals (`options`, `activate`,
+// `initVariation`, ...). A site consuming `@avsbhq/snippet-types` for
+// `window.avsb` should not have them in its global scope, so they live behind
+// the `@avsbhq/snippet-types/variation-code` subpath.
+//
+// SOURCE OF TRUTH. The dashboard code editor's copy at
+// `snippet/types/variation-code.d.ts` is generated: run `npm run sync:types` in
+// this package after editing. Mirrors `HarnessOptions` in
+// `snippet/src/userCodeHarness.ts`.
+//
+// Not a module, for the same reason as `avsb.d.ts`: these are global names, and
+// an `export` would hide all of them. Frozen at launch: rename nothing, add only.
+
+/** Recommendations client pre-bound to the running experiment and variation. */
+interface AvsbBoundRecsClient extends AvsbRecsClient {
+  /** Resolve THIS variation's bound recipe, so one code block serves every variation. */
+  getBound(req?: Omit<AvsbRecsRequest, 'recipe'>): Promise<AvsbRecsResult>
+}
+
+/** What every user-code surface receives. Self-cleaning helpers are torn down for you. */
+interface AvsbCodeOptions {
+  /** Present in variation and trigger code. */
+  experimentId?: string
+  experimentName?: string
+  variationId?: string
+  variationName?: string
+  variationType?: 'control' | 'variant'
+  /** Present in project code only. */
+  projectId?: string
+  /** Runs when the variation is activated. In variation code it fires as soon as your function returns. */
+  onActivation(cb: () => void): void
+  /** Runs when the variation is removed (client-side navigation, teardown, forced switch). */
+  onRemove(cb: () => void): void
+  track: AvsbTrackFunction
+  /** Impressions and clicks attribute to this variation automatically. */
+  recs: AvsbBoundRecsClient
+  getVisitorId(): string | null
+  /** The visitor's numeric **Variation ID** in that experiment, or null. Takes the numeric **Experiment ID** from the experiment details panel, NOT the `experimentId` above (that one is the internal id). */
+  getVariation(experimentId: string | number): string | null
+  /** Experiments running on this page, as the same numeric dashboard ids. */
+  getActiveExperiments(): Array<{ experimentId: string; variationId: string }>
+  /** Force a variation by the numeric **Experiment ID** and **Variation ID** from the experiment details panel. */
+  forceVariation(experimentId: string | number, variationId: string | number, options?: { track?: boolean }): boolean
+  /** Cancelled automatically on teardown, unlike `avsb.waitUntil`. */
+  waitUntil: AvsbWaitUntilFn
+  utils: AvsbUtils
+  /** Same numeric handle as the browser's own. Cancelled for you on teardown. */
+  setTimeout(handler: () => void, ms?: number): number
+  setInterval(handler: () => void, ms?: number): number
+  addEventListener(target: EventTarget, type: string, handler: EventListenerOrEventListenerObject, opts?: AddEventListenerOptions | boolean): void
+}
+
+type AvsbTriggerOptions = AvsbCodeOptions
+type AvsbVariationOptions = AvsbCodeOptions
+type AvsbProjectOptions = AvsbCodeOptions
+
+// Ambient declarations for standalone authoring files. They look unused to
+// ESLint because nothing in this declaration file references them: they are the
+// names your own trigger, variation, and project code calls into, so they must
+// stay literal.
+/* eslint-disable @typescript-eslint/no-unused-vars */
+declare const options: AvsbCodeOptions
+declare function activate(): void
+declare function deactivate(): void
+declare function initVariation(options: AvsbVariationOptions): void
+declare function initTrigger(options: AvsbTriggerOptions, activate: () => void, deactivate: () => void): void
+declare function initProject(options: AvsbProjectOptions): void
+/* eslint-enable @typescript-eslint/no-unused-vars */