@cognior/iap-sdk 0.1.0

package/src/services/flowNormalizer.ts

@@ -0,0 +1,74 @@
+// src/services/flowNormalizer.ts
+// Service for normalizing flow data from server format to client format
+
+import type { ContextualFlow } from './flowManager';
+
+/**
+ * Server flow format types
+ */
+interface ServerFlow {
+  id: string;
+  type: string;
+  data: any;
+  context?: {
+    elementSelector?: string;
+    elementTrigger?: string;
+    elementLocation?: string;
+    [key: string]: any;
+  };
+  [key: string]: any;
+}
+
+/**
+ * Normalizes server flow data to the client-side format
+ * @param serverFlows Array of flows in server format
+ * @returns Array of normalized flows
+ */
+export function normalizeFlows(serverFlows: ServerFlow[]): ContextualFlow[] {
+  return serverFlows.map(serverFlow => {
+    const baseFlow = {
+      id: serverFlow.id,
+      type: serverFlow.type.toLowerCase(),
+      payload: serverFlow.data || {},
+      originalData: serverFlow
+    };
+    
+    // Add contextual properties if available
+    if (serverFlow.context) {
+      return {
+        ...baseFlow,
+        elementSelector: serverFlow.context.elementSelector,
+        elementTrigger: serverFlow.context.elementTrigger || 'click',
+        elementLocation: serverFlow.context.elementLocation
+      };
+    }
+    
+    return baseFlow;
+  });
+}
+
+/**
+ * Normalizes a single server flow to client format
+ * @param serverFlow Flow in server format
+ * @returns Normalized flow
+ */
+export function normalizeFlow(serverFlow: ServerFlow): ContextualFlow {
+  const baseFlow = {
+    id: serverFlow.id,
+    type: serverFlow.type.toLowerCase(),
+    payload: serverFlow.data || {},
+    originalData: serverFlow
+  };
+  
+  // Add contextual properties if available
+  if (serverFlow.context) {
+    return {
+      ...baseFlow,
+      elementSelector: serverFlow.context.elementSelector,
+      elementTrigger: serverFlow.context.elementTrigger || 'click',
+      elementLocation: serverFlow.context.elementLocation
+    };
+  }
+  
+  return baseFlow;
+}

package/src/services/locationContextService.ts

@@ -0,0 +1,189 @@
+// src/services/locationContextService.ts
+// Service to track the current screen/location context
+
+export interface LocationContext {
+  currentPath: string;
+  screenId?: string;
+}
+
+/**
+ * Service for managing the current location context within the application.
+ * Tracks the current page path and screen ID to enable contextual experiences.
+ */
+export class LocationContextService {
+  private static _instance: LocationContextService;
+  private _currentContext: LocationContext;
+  private _listeners: Set<(context: LocationContext) => void> = new Set();
+
+  private constructor() {
+    // Initialize with normalized path (remove leading slashes)
+    this._currentContext = {
+      currentPath: window.location.pathname.replace(/^\/+/, '')
+    };
+    
+    // Listen for navigation events
+    window.addEventListener('popstate', this.updateContext.bind(this));
+    window.addEventListener('hashchange', this.updateContext.bind(this));
+    
+    // For SPAs, hook into history API
+    this.monitorHistoryChanges();
+  }
+
+  /**
+   * Get the singleton instance of the LocationContextService
+   */
+  public static getInstance(): LocationContextService {
+    if (!this._instance) {
+      this._instance = new LocationContextService();
+    }
+    return this._instance;
+  }
+
+  /**
+   * Set the current screen ID
+   * @param screenId The ID of the current screen/view
+   */
+  public setScreenId(screenId: string): void {
+    // Normalize screenId by removing leading forward slashes
+    const normalizedScreenId = screenId.replace(/^\/+/, '');
+    
+    this._currentContext = {
+      ...this._currentContext,
+      screenId: normalizedScreenId
+    };
+    this.notifyListeners();
+  }
+  
+  /**
+   * Set the current location context
+   * @param context New context values
+   */
+  public setContext(context: Partial<LocationContext>): void {
+    // Create normalized context by removing leading slashes
+    const normalizedContext: Partial<LocationContext> = { ...context };
+    
+    if (normalizedContext.currentPath) {
+      normalizedContext.currentPath = normalizedContext.currentPath.replace(/^\/+/, '');
+    }
+    
+    if (normalizedContext.screenId) {
+      normalizedContext.screenId = normalizedContext.screenId.replace(/^\/+/, '');
+    }
+    
+    this._currentContext = {
+      ...this._currentContext,
+      ...normalizedContext
+    };
+    this.notifyListeners();
+  }
+
+  /**
+   * Get the current location context
+   * @returns The current location context
+   */
+  public getContext(): LocationContext {
+    return { ...this._currentContext };
+  }
+
+  /**
+   * Subscribe to location context changes
+   * @param listener Function to call when the context changes
+   * @returns Function to unsubscribe
+   */
+  public subscribe(listener: (context: LocationContext) => void): () => void {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  }
+
+  /**
+   * Monitor history API changes for SPAs
+   * This helps detect navigation in single-page applications
+   */
+  private monitorHistoryChanges(): void {
+    // Store original methods
+    const originalPushState = history.pushState;
+    const originalReplaceState = history.replaceState;
+    
+    // Override pushState
+    history.pushState = (...args) => {
+      originalPushState.apply(history, args);
+      this.updateContext();
+    };
+    
+    // Override replaceState
+    history.replaceState = (...args) => {
+      originalReplaceState.apply(history, args);
+      this.updateContext();
+    };
+  }
+
+  /**
+   * Update the current context based on window location
+   */
+  private updateContext(): void {
+    // Normalize pathname by removing leading forward slashes
+    const normalizedPath = window.location.pathname.replace(/^\/+/, '');
+    
+    this._currentContext = {
+      ...this._currentContext,
+      currentPath: normalizedPath
+    };
+    this.notifyListeners();
+  }
+
+  /**
+   * Check if the current location matches a specific location requirement
+   * @param elementLocation The required location/route from the flow
+   * @returns True if the current location matches the requirement
+   */
+  public matchesLocation(elementLocation: string): boolean {
+    if (!elementLocation) return true; // No requirement means match all
+    
+    const currentPath = this._currentContext.currentPath || '';
+    const currentScreenId = this._currentContext.screenId || '';
+    
+    // Normalize the required location
+    const normalizedRequired = elementLocation.replace(/^\/+/, '').toLowerCase();
+    
+    // Check exact matches
+    if (currentPath.toLowerCase() === normalizedRequired ||
+        currentScreenId.toLowerCase() === normalizedRequired) {
+      return true;
+    }
+    
+    // Check if current path contains the required location
+    if (currentPath.toLowerCase().includes(normalizedRequired)) {
+      return true;
+    }
+    
+    // Check if current path starts with the required location (for nested routes)
+    if (currentPath.toLowerCase().startsWith(normalizedRequired + '/')) {
+      return true;
+    }
+    
+    // Check if URL hash contains the location
+    const hash = window.location.hash.replace(/^#+/, '').toLowerCase();
+    if (hash === normalizedRequired || hash.includes(normalizedRequired)) {
+      return true;
+    }
+    
+    // Check if URL search params contain route indicators
+    const urlParams = new URLSearchParams(window.location.search);
+    const routeParam = urlParams.get('route') || urlParams.get('page') || urlParams.get('view');
+    if (routeParam && routeParam.toLowerCase() === normalizedRequired) {
+      return true;
+    }
+    
+    return false;
+  }
+
+  /**
+   * Notify all listeners of context change
+   */
+  private notifyListeners(): void {
+    this._listeners.forEach(listener => listener(this.getContext()));
+  }
+}
+
+// Export singleton instance
+export const locationContext = LocationContextService.getInstance();

package/src/services/pageContextService.ts

@@ -0,0 +1,221 @@
+// src/services/pageContextService.ts
+// Page context management for SPA and multi-page applications
+
+export interface PageContext {
+  href: string;
+  pathname: string;
+  hash: string;
+  search: string;
+  timestamp: number;
+}
+
+export interface PageChangeEvent {
+  previous: PageContext | null;
+  current: PageContext;
+  type: 'initial' | 'navigation' | 'popstate' | 'reload';
+}
+
+type PageChangeHandler = (event: PageChangeEvent) => void;
+
+export class PageContextService {
+  private static instance: PageContextService | null = null;
+  private handlers: Set<PageChangeHandler> = new Set();
+  private currentContext: PageContext | null = null;
+  private initialized = false;
+
+  private constructor() {}
+
+  static getInstance(): PageContextService {
+    if (!PageContextService.instance) {
+      PageContextService.instance = new PageContextService();
+    }
+    return PageContextService.instance;
+  }
+
+  /**
+   * Initialize page context tracking
+   */
+  initialize(): void {
+    if (this.initialized) return;
+    
+    console.debug('[DAP] PageContextService: Initializing...');
+    
+    // Set initial context
+    this.currentContext = this.captureCurrentContext();
+    
+    // Listen for browser navigation
+    window.addEventListener('popstate', this.handlePopState.bind(this));
+    
+    // Hook into History API for SPA navigation
+    this.interceptHistoryMethods();
+    
+    this.initialized = true;
+    console.debug('[DAP] PageContextService: Initialized with context:', this.currentContext);
+    
+    // Notify initial page load
+    this.notifyHandlers({
+      previous: null,
+      current: this.currentContext,
+      type: 'initial'
+    });
+  }
+
+  /**
+   * Get current page context
+   */
+  getCurrentContext(): PageContext {
+    if (!this.currentContext) {
+      this.currentContext = this.captureCurrentContext();
+    }
+    return this.currentContext;
+  }
+
+  /**
+   * Subscribe to page change events
+   */
+  subscribe(handler: PageChangeHandler): () => void {
+    this.handlers.add(handler);
+    return () => {
+      this.handlers.delete(handler);
+    };
+  }
+
+  /**
+   * Manually trigger page context update (for framework integration)
+   */
+  updateContext(type: 'navigation' | 'reload' = 'navigation'): void {
+    const previous = this.currentContext;
+    const current = this.captureCurrentContext();
+    
+    if (!this.hasContextChanged(previous, current)) {
+      return;
+    }
+    
+    console.debug('[DAP] PageContextService: Context changed:', {
+      from: previous?.pathname,
+      to: current.pathname
+    });
+    
+    this.currentContext = current;
+    this.notifyHandlers({
+      previous,
+      current,
+      type
+    });
+  }
+
+  /**
+   * Check if selector is relevant for current page
+   */
+  isSelectorRelevant(selector: string): boolean {
+    if (!selector) return false;
+    
+    // For now, we don't filter selectors by page context
+    // All selectors are potentially relevant until proven otherwise
+    return true;
+  }
+
+  /**
+   * Get page identifier for debugging/logging
+   */
+  getPageId(): string {
+    const context = this.getCurrentContext();
+    return `${context.pathname}${context.hash}${context.search}`;
+  }
+
+  /**
+   * Clean up resources
+   */
+  destroy(): void {
+    if (!this.initialized) return;
+    
+    console.debug('[DAP] PageContextService: Destroying...');
+    
+    window.removeEventListener('popstate', this.handlePopState.bind(this));
+    this.restoreHistoryMethods();
+    
+    this.handlers.clear();
+    this.currentContext = null;
+    this.initialized = false;
+  }
+
+  // Private methods
+
+  private captureCurrentContext(): PageContext {
+    return {
+      href: window.location.href,
+      pathname: window.location.pathname,
+      hash: window.location.hash,
+      search: window.location.search,
+      timestamp: Date.now()
+    };
+  }
+
+  private hasContextChanged(previous: PageContext | null, current: PageContext): boolean {
+    if (!previous) return true;
+    
+    return (
+      previous.href !== current.href ||
+      previous.pathname !== current.pathname ||
+      previous.hash !== current.hash ||
+      previous.search !== current.search
+    );
+  }
+
+  private handlePopState(event: PopStateEvent): void {
+    console.debug('[DAP] PageContextService: Popstate event detected');
+    this.updateContext('navigation');
+  }
+
+  private originalPushState = history.pushState;
+  private originalReplaceState = history.replaceState;
+
+  private interceptHistoryMethods(): void {
+    const self = this;
+    
+    // Intercept pushState for SPA navigation
+    history.pushState = function(state: any, title: string, url?: string | URL | null) {
+      self.originalPushState.apply(history, arguments as any);
+      console.debug('[DAP] PageContextService: PushState detected:', url);
+      
+      // Use setTimeout to ensure URL has updated
+      setTimeout(() => {
+        self.updateContext('navigation');
+      }, 0);
+    };
+    
+    // Intercept replaceState for SPA navigation
+    history.replaceState = function(state: any, title: string, url?: string | URL | null) {
+      self.originalReplaceState.apply(history, arguments as any);
+      console.debug('[DAP] PageContextService: ReplaceState detected:', url);
+      
+      // Use setTimeout to ensure URL has updated
+      setTimeout(() => {
+        self.updateContext('navigation');
+      }, 0);
+    };
+  }
+
+  private restoreHistoryMethods(): void {
+    history.pushState = this.originalPushState;
+    history.replaceState = this.originalReplaceState;
+  }
+
+  private notifyHandlers(event: PageChangeEvent): void {
+    console.debug('[DAP] PageContextService: Notifying handlers:', event.type, {
+      from: event.previous?.pathname,
+      to: event.current.pathname
+    });
+    
+    this.handlers.forEach(handler => {
+      try {
+        handler(event);
+      } catch (error) {
+        console.error('[DAP] PageContextService: Handler error:', error);
+      }
+    });
+  }
+}
+
+// Export singleton instance
+export const pageContextService = PageContextService.getInstance();