@syntrologie/runtime-sdk 2.8.0-canary.183 → 2.8.0-canary.185

package/dist/telemetry/adapters/posthog.d.ts

@@ -73,6 +73,20 @@ export interface PostHogAdapterOptions {
      * @default false
      */
     requireExplicitConsent?: boolean;
+    /**
+     * PostHog cookieless tracking mode. Captures events with a privacy-
+     * preserving session-scoped hash instead of a persistent cookie.
+     *
+     * - 'always': never use cookies; always cookieless
+     * - 'on_reject': use cookies until consent is rejected, then cookieless
+     *
+     * Recommended pairing for the SDK consent layer: `'on_reject'` so
+     * baseline behavioral telemetry flows for all visitors regardless
+     * of consent state, with full identified tracking only after grant.
+     *
+     * @default undefined (cookies used unconditionally)
+     */
+    cookieless_mode?: 'always' | 'on_reject';
     /**
      * Enable behavioral signal detection (hesitation, rage click, etc.)
      * Pass `true` for defaults, or a partial DetectorConfig to customize thresholds.
@@ -128,6 +142,18 @@ export declare class PostHogAdapter implements TelemetryClient {
     getSegmentFlags(): Record<string, boolean>;
     identify(id: string, props?: Properties): void;
     alias(id: string, aliasId: string): void;
+    /**
+     * Opt the current visitor INTO capturing. Drives the granted-state
+     * transition from the consent gate. When previously cookieless or
+     * opted-out, switches to full identified capture.
+     */
+    optInCapturing(): void;
+    /**
+     * Opt the current visitor OUT of capturing. Drives the denied-state
+     * transition from the consent gate. Stops sending events; existing
+     * cookieless/anonymous events remain in the data warehouse.
+     */
+    optOutCapturing(): void;
     track(eventName: string, payload?: CanvasAnalyticsPayload): void;
     trackCanvasOpened(surface: CanvasSurface): void;
     trackCanvasClosed(surface: CanvasSurface): void;

package/dist/telemetry/consent/ConsentDetector.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ConsentDetector — orchestrates ConsentAdapters.
+ *
+ * Probes adapters in priority order. First adapter whose `detect()`
+ * returns true wins; its state changes are pushed into the gate. If
+ * no adapter matches, applies the configured fallback.
+ *
+ * See docs/plans/current/2026-05-04-sdk-default-instrumentation-spec.md
+ * Section X.
+ */
+import type { ConsentGate } from './ConsentGate';
+import type { DetectorOptions } from './types';
+export declare class ConsentDetector {
+    private readonly options;
+    constructor(options: DetectorOptions);
+    /**
+     * Start the detector. Probes adapters in array order; first match wins.
+     * Returns a teardown function that unsubscribes the active adapter.
+     *
+     * Async because adapters may need async initialization. Bootstrap
+     * should NOT await this — feature flags and anonymous telemetry
+     * should keep flowing while the detector probes.
+     */
+    start(gate: ConsentGate): Promise<() => void>;
+    private resolveFallback;
+}

package/dist/telemetry/{consent.d.ts → consent/ConsentGate.d.ts}

@@ -21,6 +21,16 @@ export interface ConsentConfig {
     readFromGtmConsentMode?: boolean;
     /** Called whenever consent status changes. */
     onConsentChange?: (status: ConsentStatus) => void;
+    /**
+     * Resolves what 'pending' should be treated as for users who have not
+     * explicitly granted/denied (no banner interaction yet).
+     *
+     * For ROW (rest of world): typically returns 'granted' (opt-out regimes).
+     * For EU/UK/CH: returns 'denied' (explicit-opt-in regimes).
+     *
+     * Called lazily by `resolvePending()`. If not provided, defaults to 'denied'.
+     */
+    pendingResolver?: () => Promise<ConsentStatus>;
 }
 type ConsentListener = (status: ConsentStatus) => void;
 export declare class ConsentGate {
@@ -29,6 +39,7 @@ export declare class ConsentGate {
     private configCallback?;
     private gtmEnabled;
     private destroyed;
+    private pendingResolverFn?;
     constructor(config?: ConsentConfig);
     /**
      * Grant consent — enables telemetry collection.
@@ -47,6 +58,27 @@ export declare class ConsentGate {
      * Returns an unsubscribe function.
      */
     subscribe(listener: ConsentListener): () => void;
+    /**
+     * Subscribe to the next definitive (granted | denied) status change,
+     * then auto-unsubscribe. If status is already definitive, fires
+     * synchronously (next microtask) with current status.
+     *
+     * Used by D-2 (URL-param identify) to defer the identify() call
+     * until consent is decided.
+     */
+    subscribeOnce(listener: ConsentListener): () => void;
+    /**
+     * Resolve what the current 'pending' state should be treated as,
+     * via the configured pendingResolver. Returns the current status
+     * directly if it's already 'granted' or 'denied'.
+     *
+     * Defaults to 'denied' if no resolver is configured (conservative).
+     */
+    resolvePending(): Promise<ConsentStatus>;
+    /**
+     * Public setter — used by ConsentDetector / adapters to push state changes.
+     */
+    setStatus(newStatus: ConsentStatus): void;
     /**
      * Poll GTM's dataLayer for consent state.
      * Scans for the most recent consent update event with analytics_storage.
@@ -56,7 +88,7 @@ export declare class ConsentGate {
      * Clean up listeners and stop responding to changes.
      */
     destroy(): void;
-    private setStatus;
+    private applyStatus;
     private notify;
 }
 export {};

package/dist/telemetry/consent/adapters/gtmConsentMode.d.ts

@@ -0,0 +1,18 @@
+/**
+ * GTM Consent Mode v2 adapter.
+ *
+ * Reads `analytics_storage` from window.dataLayer consent events.
+ * Universal de facto standard — most CMPs (Cookiebot, OneTrust,
+ * Iubenda, Termly, etc.) push to dataLayer.
+ *
+ * See docs/plans/current/2026-05-04-sdk-default-instrumentation-spec.md
+ * Section Y.
+ */
+import type { ConsentStatus } from '../ConsentGate';
+import type { ConsentAdapter } from '../types';
+export declare class GtmConsentModeAdapter implements ConsentAdapter {
+    readonly name = "gtm-consent-mode-v2";
+    detect(): boolean;
+    initialize(callback: (status: ConsentStatus) => void): () => void;
+    private readCurrentState;
+}

package/dist/telemetry/consent/adapters/iabTcf.d.ts

@@ -0,0 +1,21 @@
+/**
+ * IAB TCF v2 adapter.
+ *
+ * Reads consent state from window.__tcfapi — the IAB Transparency &
+ * Consent Framework standard. Used by all major EU-focused CMPs:
+ * OneTrust, Cookiebot, Iubenda, Didomi, Sourcepoint, etc.
+ *
+ * Maps Purpose 1 (storage access) + Purpose 8 (measure content
+ * performance, i.e. analytics) → granted/denied. Both must be granted
+ * for analytics tracking to be allowed under TCF.
+ *
+ * See docs/plans/current/2026-05-04-sdk-default-instrumentation-spec.md
+ * Section W.
+ */
+import type { ConsentStatus } from '../ConsentGate';
+import type { ConsentAdapter } from '../types';
+export declare class IabTcfAdapter implements ConsentAdapter {
+    readonly name = "iab-tcf-v2";
+    detect(): boolean;
+    initialize(callback: (status: ConsentStatus) => void): () => void;
+}

package/dist/telemetry/consent/adapters/shopify.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shopify Customer Privacy adapter.
+ *
+ * Authoritative on Shopify storefronts. Uses Shopify's built-in
+ * customer-privacy API which combines analytics/marketing/preferences/
+ * sale-of-data consents into a single boolean via userCanBeTracked().
+ *
+ * See docs/plans/current/2026-05-04-sdk-default-instrumentation-spec.md
+ * Section Z.
+ */
+import type { ConsentStatus } from '../ConsentGate';
+import type { ConsentAdapter } from '../types';
+export declare class ShopifyCustomerPrivacyAdapter implements ConsentAdapter {
+    readonly name = "shopify-customer-privacy";
+    detect(): boolean;
+    initialize(callback: (status: ConsentStatus) => void): () => void;
+}

package/dist/telemetry/consent/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Consent management — public exports.
+ *
+ * See:
+ * - ConsentGate: the runtime state machine for granted/denied/pending
+ * - ConsentDetector: orchestrates adapters that detect CMPs on the page
+ * - ConsentAdapter: the interface adapters implement
+ *
+ * Architecture per docs/plans/current/2026-05-04-sdk-default-instrumentation-spec.md.
+ */
+export { GtmConsentModeAdapter } from './adapters/gtmConsentMode';
+export { IabTcfAdapter } from './adapters/iabTcf';
+export { ShopifyCustomerPrivacyAdapter } from './adapters/shopify';
+export { ConsentDetector } from './ConsentDetector';
+export type { ConsentConfig, ConsentStatus } from './ConsentGate';
+export { ConsentGate } from './ConsentGate';
+export type { ConsentAdapter, DetectorOptions } from './types';

package/dist/telemetry/consent/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Public types for the consent detection framework.
+ *
+ * See docs/plans/current/2026-05-04-sdk-default-instrumentation-spec.md
+ * Section X for the design rationale.
+ */
+import type { ConsentStatus } from './ConsentGate';
+export interface ConsentAdapter {
+    /** Stable identifier — used in telemetry / logs. */
+    readonly name: string;
+    /**
+     * Synchronous detection: is this CMP currently present on the page?
+     * Must be cheap and never throw. Just check for global presence
+     * (e.g. `typeof window.Shopify?.customerPrivacy !== 'undefined'`).
+     */
+    detect(): boolean;
+    /**
+     * Subscribe to consent state. Returns immediately with a teardown
+     * function. The callback fires:
+     *   - Once with the current best-known state (could be 'pending' if
+     *     adapter needs an async handshake).
+     *   - Whenever the state changes (user accepts/rejects, etc).
+     *
+     * Adapters that need async initialization (e.g. Shopify's
+     * loadFeatures) should fire 'pending' synchronously and update via
+     * the callback when the async work finishes.
+     */
+    initialize(callback: (status: ConsentStatus) => void): () => void;
+}
+export interface DetectorOptions {
+    /**
+     * Adapters in priority order. First adapter whose `detect()` returns
+     * true wins.
+     */
+    adapters: ConsentAdapter[];
+    /**
+     * Optional callback fired once when the detector picks a winning
+     * adapter (or determines no adapter matched). Use for telemetry.
+     */
+    onAdapterSelected?: (name: string | null) => void;
+    /**
+     * Status to apply when no adapter matches. Typically wired to a
+     * geo-aware function ("granted" outside EU, "denied" inside).
+     * Defaults to 'pending' if not provided.
+     */
+    fallbackStatus?: () => ConsentStatus | Promise<ConsentStatus>;
+}

package/dist/telemetry/types.d.ts

@@ -75,4 +75,28 @@ export interface TelemetryClient {
      * Used by audit events to send named events to PostHog.
      */
     track?(eventName: string, properties?: Record<string, unknown>): void;
+    /**
+     * Identify the current visitor with a stable ID.
+     * Merges anonymous events into the new person record. Idempotent
+     * for the same id. See SDK defaults spec D-1 / D-2.
+     */
+    identify?(distinctId: string, properties?: Record<string, unknown>): void;
+    /**
+     * Alias an existing identity to another id (treat as same person).
+     * Used when a previously-identified visitor reveals an additional id
+     * in the same session (e.g., logs in as bolshoifish then enters
+     * parker.lowrey at checkout). PostHog merges both ids into one
+     * person record.
+     */
+    alias?(newDistinctId: string, oldDistinctId?: string): void;
+    /**
+     * Switch from cookieless / opted-out mode to full identified capture.
+     * Driven by the ConsentGate when status transitions to 'granted'.
+     */
+    optInCapturing?(): void;
+    /**
+     * Switch off all capturing. Driven by the ConsentGate when status
+     * transitions to 'denied'.
+     */
+    optOutCapturing?(): void;
 }

package/dist/version.d.ts

@@ -10,4 +10,4 @@
  *
  * @since 2.0.0
  */
-export declare const SDK_VERSION = "2.8.0-canary.183";
+export declare const SDK_VERSION = "2.8.0-canary.185";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syntrologie/runtime-sdk",
-  "version": "2.8.0-canary.183",
+  "version": "2.8.0-canary.185",
   "description": "Syntrologie Runtime SDK for web experimentation and analytics",
   "license": "Proprietary",
   "private": false,
@@ -39,15 +39,13 @@
   "files": [
     "dist",
     "schema",
-    "scripts/validate-config.mjs",
-    "CAPABILITIES.md"
+    "scripts/validate-config.mjs"
   ],
   "scripts": {
     "clean": "rm -rf dist",
-    "aggregate-capabilities": "node ./scripts/aggregate-capabilities.mjs",
     "generate-schema": "node ./scripts/generate-unified-schema.mjs",
     "generate-schema:check": "node ./scripts/generate-unified-schema.mjs --check",
-    "build": "npm run aggregate-capabilities && npm run build:types && npm run build:lib && npm run generate-schema && npm run build:cdn && npm run build:adaptives",
+    "build": "npm run build:types && npm run build:lib && npm run generate-schema && npm run build:cdn && npm run build:adaptives",
     "build:types": "tsc --project tsconfig.build.json",
     "build:lib": "node ./scripts/build-lib.mjs",
     "build:cdn": "node ./scripts/build-cdn.js",