@syntrologie/runtime-sdk 0.2.20 → 1.0.0-canary.1

package/dist/config-validator.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Config validation and migration for SDK versioning.
+ *
+ * This module handles:
+ * - Validating configs against the current SDK schema version
+ * - Migrating old config formats to current version
+ * - Providing warnings for version mismatches
+ */
+import type { CanvasConfigResponse } from './types';
+/**
+ * Result of config validation.
+ */
+export interface ConfigValidationResult {
+    /** Whether the config is valid and can be used */
+    valid: boolean;
+    /** Warning messages (non-fatal issues) */
+    warnings: string[];
+    /** Error messages (fatal issues that prevent usage) */
+    errors: string[];
+    /** Migrated config if old version was detected */
+    migratedConfig?: CanvasConfigResponse;
+}
+/**
+ * Parse a schema version string into major and minor numbers.
+ */
+export declare function parseVersion(version: string): {
+    major: number;
+    minor: number;
+};
+/**
+ * Validate and normalize a config, handling version mismatches.
+ *
+ * This function:
+ * 1. Checks if config is valid object
+ * 2. Compares config schema version with SDK version
+ * 3. Migrates old configs to current version
+ * 4. Returns validation result with warnings/errors
+ *
+ * @param config - Raw config from backend or fetcher
+ * @returns Validation result with any migrations applied
+ */
+export declare function validateConfig(config: unknown): ConfigValidationResult;
+/**
+ * Check if a config needs migration.
+ *
+ * @param config - Config to check
+ * @returns True if migration is needed
+ */
+export declare function needsMigration(config: unknown): boolean;

package/dist/config-validator.js

@@ -0,0 +1,173 @@
+/**
+ * Config validation and migration for SDK versioning.
+ *
+ * This module handles:
+ * - Validating configs against the current SDK schema version
+ * - Migrating old config formats to current version
+ * - Providing warnings for version mismatches
+ */
+import { SDK_SCHEMA_VERSION } from './types';
+/**
+ * Parse a schema version string into major and minor numbers.
+ */
+export function parseVersion(version) {
+    const parts = version.split('.');
+    return {
+        major: parseInt(parts[0] || '0', 10),
+        minor: parseInt(parts[1] || '0', 10),
+    };
+}
+/**
+ * Validate and normalize a config, handling version mismatches.
+ *
+ * This function:
+ * 1. Checks if config is valid object
+ * 2. Compares config schema version with SDK version
+ * 3. Migrates old configs to current version
+ * 4. Returns validation result with warnings/errors
+ *
+ * @param config - Raw config from backend or fetcher
+ * @returns Validation result with any migrations applied
+ */
+export function validateConfig(config) {
+    const warnings = [];
+    const errors = [];
+    // Type check
+    if (!config || typeof config !== 'object') {
+        return {
+            valid: false,
+            errors: ['Config must be an object'],
+            warnings,
+        };
+    }
+    const typedConfig = config;
+    // Check required fields
+    if (!typedConfig.tiles) {
+        errors.push('Config missing required field: tiles');
+    }
+    if (!typedConfig.actions) {
+        errors.push('Config missing required field: actions');
+    }
+    if (!typedConfig.fetchedAt) {
+        errors.push('Config missing required field: fetchedAt');
+    }
+    if (errors.length > 0) {
+        return { valid: false, errors, warnings };
+    }
+    // Check schema version
+    const configVersion = typedConfig.schemaVersion || '1.0';
+    const configVer = parseVersion(configVersion);
+    const sdkVer = parseVersion(SDK_SCHEMA_VERSION);
+    // Future schema version (newer backend)
+    if (configVer.major > sdkVer.major) {
+        warnings.push(`Config schema v${configVersion} is newer than SDK v${SDK_SCHEMA_VERSION}. ` +
+            `Some features may not work. Update SDK to latest version.`);
+    }
+    // Old schema version (older backend or missing version)
+    if (configVer.major < sdkVer.major || !typedConfig.schemaVersion) {
+        warnings.push(`Config schema v${configVersion} is older than SDK v${SDK_SCHEMA_VERSION}. ` +
+            `Migrating config to current version.`);
+        return {
+            valid: true,
+            warnings,
+            errors,
+            migratedConfig: migrateConfig(typedConfig, configVersion),
+        };
+    }
+    // Compatible version (same major version)
+    return {
+        valid: true,
+        warnings,
+        errors,
+    };
+}
+/**
+ * Migrate old config format to current SDK version.
+ *
+ * This function applies all necessary transformations to bring
+ * an old config up to the current schema version.
+ *
+ * @param config - Config to migrate
+ * @param fromVersion - Version to migrate from
+ * @returns Migrated config at current SDK version
+ */
+function migrateConfig(config, fromVersion) {
+    let migrated = { ...config };
+    const fromVer = parseVersion(fromVersion);
+    // v1.x -> v2.x migration
+    if (fromVer.major === 1) {
+        migrated = migrateV1ToV2(migrated);
+    }
+    // Update schema version to current
+    migrated.schemaVersion = SDK_SCHEMA_VERSION;
+    return migrated;
+}
+/**
+ * Migrate v1.x config to v2.0 format.
+ *
+ * Changes in v2.0:
+ * - Introduced ActivationConfig to replace experiment field
+ * - Unified ActionStep format
+ * - Added schemaVersion field
+ */
+function migrateV1ToV2(config) {
+    const migrated = {
+        schemaVersion: '2.0',
+        tiles: [],
+        actions: config.actions || [],
+        fetchedAt: config.fetchedAt || new Date().toISOString(),
+    };
+    // Migrate tiles
+    if (config.tiles && Array.isArray(config.tiles)) {
+        migrated.tiles = config.tiles.map((tile) => {
+            const migratedTile = { ...tile };
+            // Migrate deprecated experiment field to activation
+            if (tile.experiment && !tile.activation) {
+                const exp = tile.experiment;
+                // Convert old experiment format to new activation format
+                if (exp.featureKey) {
+                    migratedTile.activation = {
+                        strategy: {
+                            type: 'external',
+                            provider: 'growthbook',
+                            featureKey: exp.featureKey,
+                            fallback: false,
+                        },
+                    };
+                }
+                // Remove deprecated field
+                delete migratedTile.experiment;
+            }
+            return migratedTile;
+        });
+    }
+    // Copy optional fields
+    if (config.configVersion)
+        migrated.configVersion = config.configVersion;
+    if (config.canvasTitle)
+        migrated.canvasTitle = config.canvasTitle;
+    if (config.theme)
+        migrated.theme = config.theme;
+    if (config.launcher)
+        migrated.launcher = config.launcher;
+    if (config.routes)
+        migrated.routes = config.routes;
+    return migrated;
+}
+/**
+ * Check if a config needs migration.
+ *
+ * @param config - Config to check
+ * @returns True if migration is needed
+ */
+export function needsMigration(config) {
+    if (!config || typeof config !== 'object') {
+        return false;
+    }
+    const typedConfig = config;
+    const configVersion = typedConfig.schemaVersion || '1.0';
+    const configVer = parseVersion(configVersion);
+    const sdkVer = parseVersion(SDK_SCHEMA_VERSION);
+    return configVer.major < sdkVer.major || !typedConfig.schemaVersion;
+}
+//# sourceMappingURL=config-validator.js.map

package/dist/config-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-validator.js","sourceRoot":"","sources":["../src/config-validator.ts"],"names":[],"mappings":"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"}

package/dist/configFetcher.d.ts

@@ -1,5 +1,5 @@
-import type { CanvasConfigFetcher } from "./types";
-import type { ExperimentClient } from "./experiments/types";
+import type { CanvasConfigFetcher } from './types';
+import type { ExperimentClient } from './experiments/types';
 export interface CanvasFetcherOptions {
     configUri?: string;
     experiments?: ExperimentClient;

package/dist/configFetcher.js

@@ -1,3 +1,6 @@
+import { SDK_SCHEMA_VERSION } from './types';
+import { SDK_VERSION } from './version';
+import { debug } from './logger';
 /**
  * Allowed hosts for fetching config.
  * Only config from these hosts will be fetched.
@@ -6,7 +9,7 @@ const ALLOWED_CONFIG_HOSTS = [
     'api.syntrologie.com',
     'cdn.syntrologie.com',
     'localhost',
-    '127.0.0.1'
+    '127.0.0.1',
 ];
 /**
  * Validates that a config URI is from an allowed host.
@@ -22,7 +25,7 @@ function validateConfigUri(uri) {
             return false;
         }
         // Check against allowlist
-        const isAllowed = ALLOWED_CONFIG_HOSTS.some(host => parsed.hostname === host);
+        const isAllowed = ALLOWED_CONFIG_HOSTS.some((host) => parsed.hostname === host);
         if (!isAllowed) {
             console.warn('[SmartCanvas] Config URI host not in allowlist:', parsed.hostname);
             return false;
@@ -48,7 +51,7 @@ function isSameOrigin(uri) {
         return false;
     }
 }
-export const resolveConfigUri = ({ configUri, experiments, featureKey = "smart-canvas-config-uri", }) => {
+export const resolveConfigUri = ({ configUri, experiments, featureKey = 'smart-canvas-config-uri', }) => {
     var _a;
     if (configUri)
         return configUri;
@@ -57,21 +60,22 @@ export const resolveConfigUri = ({ configUri, experiments, featureKey = "smart-c
         return fromFeature;
     return undefined;
 };
-export const createCanvasConfigFetcher = ({ configUri, experiments, featureKey, credentials, configFeatureKey = "smart-canvas-config", }) => {
+export const createCanvasConfigFetcher = ({ configUri, experiments, featureKey, credentials, configFeatureKey = 'smart-canvas-config', }) => {
     return async () => {
         var _a;
         // First check if we have a direct config object from experiment platform
         if (experiments && configFeatureKey) {
             const directConfig = (_a = experiments.getFeatureValue) === null || _a === void 0 ? void 0 : _a.call(experiments, configFeatureKey, null);
             if (directConfig && typeof directConfig === 'object') {
-                // Return the config directly - no fetch needed
+                debug('SmartCanvas Config', 'Resolved config directly from feature flag', directConfig);
                 return directConfig;
             }
         }
         // Fall back to URI-based fetching
         const uri = resolveConfigUri({ configUri, experiments, featureKey });
         if (!uri) {
-            throw new Error("SmartCanvas: config URI missing (env + feature flag unset).");
+            debug('SmartCanvas Config', 'No config available — returning empty config');
+            return { tiles: [], overlays: [] };
         }
         // Security: Validate URI against allowlist
         if (!validateConfigUri(uri)) {
@@ -80,11 +84,19 @@ export const createCanvasConfigFetcher = ({ configUri, experiments, featureKey,
         // Security: Only send credentials to same-origin requests
         // This prevents leaking cookies to third-party servers
         const effectiveCredentials = credentials !== null && credentials !== void 0 ? credentials : (isSameOrigin(uri) ? 'include' : 'omit');
-        const response = await fetch(uri, { credentials: effectiveCredentials });
+        const response = await fetch(uri, {
+            credentials: effectiveCredentials,
+            headers: {
+                'X-SDK-Version': SDK_VERSION,
+                'X-SDK-Schema-Version': SDK_SCHEMA_VERSION,
+            },
+        });
         if (!response.ok) {
             throw new Error(`SmartCanvas: failed to fetch config (${response.status})`);
         }
-        return await response.json();
+        const config = await response.json();
+        debug('SmartCanvas Config', 'Fetched config from URI', config);
+        return config;
     };
 };
 //# sourceMappingURL=configFetcher.js.map

package/dist/configFetcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"configFetcher.js","sourceRoot":"","sources":["../src/configFetcher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"configFetcher.js","sourceRoot":"","sources":["../src/configFetcher.ts"],"names":[],"mappings":"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"}

package/dist/context/ContextManager.d.ts

@@ -0,0 +1,66 @@
+/**
+ * ContextManager - Manages runtime context and notifies subscribers of changes.
+ *
+ * The ContextManager is responsible for:
+ * - Collecting context from various sources (page, session, viewport)
+ * - Notifying subscribers when context changes
+ * - Providing the current context snapshot
+ */
+import type { RuntimeContext, AnchorState, ContextChangeCallback, Unsubscribe, PageHistoryEntry } from './types';
+import type { TelemetryClient } from '../telemetry/types';
+import type { RoutesConfig } from '../types';
+export interface ContextManagerOptions {
+    /** Telemetry client for session ID */
+    telemetry?: TelemetryClient;
+    /** Routes config for route matching */
+    routes?: RoutesConfig;
+    /** Initial page history (optional) */
+    initialPageHistory?: PageHistoryEntry[];
+}
+/**
+ * ContextManager class for managing runtime context.
+ */
+export declare class ContextManager {
+    private context;
+    private previousContext;
+    private listeners;
+    private telemetry?;
+    private routes?;
+    private cleanupFns;
+    constructor(options?: ContextManagerOptions);
+    /**
+     * Get the current runtime context.
+     */
+    get(): RuntimeContext;
+    /**
+     * Subscribe to context changes.
+     * Returns an unsubscribe function.
+     */
+    subscribe(callback: ContextChangeCallback): Unsubscribe;
+    /**
+     * Update the routes config (e.g., when config is fetched).
+     */
+    setRoutes(routes: RoutesConfig): void;
+    /**
+     * Update anchor states.
+     */
+    setAnchors(anchors: AnchorState[]): void;
+    /**
+     * Manually update the session ID (e.g., when telemetry initializes).
+     */
+    setSessionId(sessionId: string): void;
+    /**
+     * Clean up event listeners and subscriptions.
+     */
+    destroy(): void;
+    private setupBrowserListeners;
+    private updateViewport;
+    private updatePage;
+    private addPageToHistory;
+    private updateContext;
+    private notifyListeners;
+}
+/**
+ * Create a ContextManager instance.
+ */
+export declare function createContextManager(options?: ContextManagerOptions): ContextManager;

package/dist/context/ContextManager.js

@@ -0,0 +1,268 @@
+/**
+ * Creates a default RuntimeContext.
+ */
+function createDefaultContext() {
+    const now = Date.now();
+    return {
+        page: {
+            url: typeof window !== 'undefined' ? window.location.href : '',
+            title: typeof document !== 'undefined' ? document.title : undefined,
+        },
+        session: {
+            sessionId: '',
+            startTs: now,
+            pageHistory: [],
+        },
+        viewport: {
+            width: typeof window !== 'undefined' ? window.innerWidth : 0,
+            height: typeof window !== 'undefined' ? window.innerHeight : 0,
+        },
+    };
+}
+/**
+ * Match a URL against route patterns from RoutesConfig.
+ * Returns the matched pattern or undefined.
+ */
+function matchRoute(url, routes) {
+    if (!routes)
+        return undefined;
+    // Extract pathname from URL
+    let pathname;
+    try {
+        pathname = new URL(url).pathname;
+    }
+    catch {
+        pathname = url;
+    }
+    // Check exclude patterns first
+    if (routes.exclude) {
+        for (const pattern of routes.exclude) {
+            if (matchPattern(pathname, pattern)) {
+                return undefined; // Excluded route
+            }
+        }
+    }
+    // Check include patterns
+    if (routes.include) {
+        for (const pattern of routes.include) {
+            if (matchPattern(pathname, pattern)) {
+                return pattern;
+            }
+        }
+        return undefined; // No match in include list
+    }
+    return pathname; // No include list, return pathname as route
+}
+/**
+ * Simple pattern matching for routes.
+ * Supports:
+ * - Exact matches: "/products"
+ * - Wildcard segments: "/products/*"
+ * - Parameter segments: "/products/:id"
+ */
+function matchPattern(pathname, pattern) {
+    // Normalize paths
+    const normalizedPath = pathname.replace(/\/$/, '') || '/';
+    const normalizedPattern = pattern.replace(/\/$/, '') || '/';
+    // Exact match
+    if (normalizedPath === normalizedPattern)
+        return true;
+    // Convert pattern to regex
+    const regexPattern = normalizedPattern
+        .replace(/:[^/]+/g, '[^/]+') // :param -> [^/]+
+        .replace(/\*/g, '.*'); // * -> .*
+    const regex = new RegExp(`^${regexPattern}$`);
+    return regex.test(normalizedPath);
+}
+/**
+ * ContextManager class for managing runtime context.
+ */
+export class ContextManager {
+    constructor(options = {}) {
+        var _a;
+        this.listeners = new Set();
+        // Event listener cleanup functions
+        this.cleanupFns = [];
+        this.telemetry = options.telemetry;
+        this.routes = options.routes;
+        // Initialize context
+        this.context = createDefaultContext();
+        this.previousContext = { ...this.context };
+        // Set initial session ID from telemetry
+        if ((_a = options.telemetry) === null || _a === void 0 ? void 0 : _a.getSessionId) {
+            const sessionId = options.telemetry.getSessionId();
+            if (sessionId) {
+                this.context.session.sessionId = sessionId;
+            }
+        }
+        // Set initial page history
+        if (options.initialPageHistory) {
+            this.context.session.pageHistory = options.initialPageHistory;
+        }
+        // Set initial route ID
+        this.context.page.routeId = matchRoute(this.context.page.url, this.routes);
+        // Add current page to history
+        this.addPageToHistory(this.context.page.url);
+        // Setup browser event listeners
+        if (typeof window !== 'undefined') {
+            this.setupBrowserListeners();
+        }
+    }
+    /**
+     * Get the current runtime context.
+     */
+    get() {
+        return { ...this.context };
+    }
+    /**
+     * Subscribe to context changes.
+     * Returns an unsubscribe function.
+     */
+    subscribe(callback) {
+        this.listeners.add(callback);
+        return () => {
+            this.listeners.delete(callback);
+        };
+    }
+    /**
+     * Update the routes config (e.g., when config is fetched).
+     */
+    setRoutes(routes) {
+        this.routes = routes;
+        // Re-evaluate current route
+        const newRouteId = matchRoute(this.context.page.url, this.routes);
+        if (newRouteId !== this.context.page.routeId) {
+            this.updateContext({ page: { ...this.context.page, routeId: newRouteId } });
+        }
+    }
+    /**
+     * Update anchor states.
+     */
+    setAnchors(anchors) {
+        this.updateContext({ anchors });
+    }
+    /**
+     * Manually update the session ID (e.g., when telemetry initializes).
+     */
+    setSessionId(sessionId) {
+        if (sessionId !== this.context.session.sessionId) {
+            this.updateContext({
+                session: { ...this.context.session, sessionId },
+            });
+        }
+    }
+    /**
+     * Clean up event listeners and subscriptions.
+     */
+    destroy() {
+        for (const cleanup of this.cleanupFns) {
+            cleanup();
+        }
+        this.cleanupFns = [];
+        this.listeners.clear();
+    }
+    // ==================== Private Methods ====================
+    setupBrowserListeners() {
+        // Viewport resize listener (debounced)
+        let resizeTimeout;
+        const handleResize = () => {
+            clearTimeout(resizeTimeout);
+            resizeTimeout = setTimeout(() => {
+                this.updateViewport();
+            }, 100);
+        };
+        window.addEventListener('resize', handleResize);
+        this.cleanupFns.push(() => window.removeEventListener('resize', handleResize));
+        // Navigation listener (popstate for back/forward)
+        const handlePopState = () => {
+            this.updatePage();
+        };
+        window.addEventListener('popstate', handlePopState);
+        this.cleanupFns.push(() => window.removeEventListener('popstate', handlePopState));
+        // History pushState/replaceState interception
+        const originalPushState = history.pushState.bind(history);
+        const originalReplaceState = history.replaceState.bind(history);
+        history.pushState = (...args) => {
+            originalPushState(...args);
+            this.updatePage();
+        };
+        history.replaceState = (...args) => {
+            originalReplaceState(...args);
+            this.updatePage();
+        };
+        this.cleanupFns.push(() => {
+            history.pushState = originalPushState;
+            history.replaceState = originalReplaceState;
+        });
+    }
+    updateViewport() {
+        const newViewport = {
+            width: window.innerWidth,
+            height: window.innerHeight,
+        };
+        if (newViewport.width !== this.context.viewport.width ||
+            newViewport.height !== this.context.viewport.height) {
+            this.updateContext({ viewport: newViewport });
+        }
+    }
+    updatePage() {
+        const url = window.location.href;
+        const title = document.title;
+        const routeId = matchRoute(url, this.routes);
+        const newPage = {
+            url,
+            title,
+            routeId,
+        };
+        // Only update if something changed
+        if (newPage.url !== this.context.page.url ||
+            newPage.title !== this.context.page.title ||
+            newPage.routeId !== this.context.page.routeId) {
+            // Add to page history if URL changed
+            if (newPage.url !== this.context.page.url) {
+                this.addPageToHistory(newPage.url);
+            }
+            this.updateContext({ page: newPage });
+        }
+    }
+    addPageToHistory(url) {
+        const entry = {
+            url,
+            ts: Date.now(),
+        };
+        const pageHistory = [...(this.context.session.pageHistory || []), entry];
+        // Keep last 50 pages in history
+        if (pageHistory.length > 50) {
+            pageHistory.shift();
+        }
+        this.context.session.pageHistory = pageHistory;
+    }
+    updateContext(partial) {
+        // Save previous context
+        this.previousContext = { ...this.context };
+        // Merge updates
+        this.context = {
+            ...this.context,
+            ...partial,
+        };
+        // Notify listeners
+        this.notifyListeners();
+    }
+    notifyListeners() {
+        for (const callback of this.listeners) {
+            try {
+                callback(this.context, this.previousContext);
+            }
+            catch (err) {
+                console.error('[ContextManager] Listener error:', err);
+            }
+        }
+    }
+}
+/**
+ * Create a ContextManager instance.
+ */
+export function createContextManager(options = {}) {
+    return new ContextManager(options);
+}
+//# sourceMappingURL=ContextManager.js.map