@mission_sciences/provider-sdk 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,767 @@
+/**
+ * Dark theme matching gw-spa design system
+ */
+export declare const darkTheme: Theme;
+
+/**
+ * Extract JWT token from URL parameter
+ * @param paramName - URL parameter name (default: 'jwt')
+ * @param url - URL to extract from (default: window.location.href)
+ * @returns JWT token or null if not found
+ */
+export declare function extractTokenFromURL(paramName?: string, url?: string): string | null;
+
+/**
+ * Generate CSS string from theme colors for inline styles
+ */
+export declare function generateCSSVariables(theme: Theme): string;
+
+/**
+ * Get theme based on user preference or system setting
+ */
+export declare function getTheme(prefersDark?: boolean): Theme;
+
+/**
+ * Heartbeat Manager for active session tracking
+ * Phase 2 Feature - Sends periodic heartbeats to backend
+ */
+export declare class HeartbeatManager {
+    private sessionId;
+    private apiEndpoint;
+    private token;
+    private onSync?;
+    private onError?;
+    private intervalId;
+    private heartbeatInterval;
+    private failureCount;
+    private maxFailures;
+    private isEnabled;
+    private logger;
+    constructor(sessionId: string, apiEndpoint: string, token: string, onSync?: ((remainingSeconds: number) => void) | undefined, onError?: ((error: Error) => void) | undefined, heartbeatIntervalSeconds?: number, debug?: boolean);
+    /**
+     * Start sending heartbeats
+     */
+    start(): void;
+    /**
+     * Stop sending heartbeats
+     */
+    stop(): void;
+    /**
+     * Send a single heartbeat to backend
+     */
+    private sendHeartbeat;
+    /**
+     * Check if heartbeat is running
+     */
+    isRunning(): boolean;
+    /**
+     * Get failure count
+     */
+    getFailureCount(): number;
+    /**
+     * Update heartbeat interval
+     */
+    updateInterval(seconds: number): void;
+}
+
+/**
+ * Check if code is running in browser environment
+ */
+export declare function isBrowser(): boolean;
+
+/**
+ * JWKS Key
+ */
+export declare interface JWKSKey {
+    kty: string;
+    use: string;
+    kid: string;
+    alg: string;
+    n: string;
+    e: string;
+}
+
+/**
+ * JWKS Response
+ */
+export declare interface JWKSResponse {
+    keys: JWKSKey[];
+}
+
+/**
+ * JWKS Validator for RS256 JWT signature verification
+ * Uses jose library for browser and Node.js compatibility
+ */
+export declare class JWKSValidator {
+    private jwksUri;
+    private logger;
+    private jwks;
+    constructor(jwksUri: string, debug?: boolean);
+    /**
+     * Verify JWT signature using JWKS public key
+     * @param token - JWT token to verify
+     * @param expectedIssuer - Expected issuer (default: 'generalwisdom.com')
+     * @param expectedApplicationId - Optional application ID to validate
+     * @returns Decoded and verified JWT claims
+     */
+    verify(token: string, expectedIssuer?: string, expectedApplicationId?: string): Promise<JWTClaims>;
+    /**
+     * Update JWKS URI
+     * @param jwksUri - New JWKS URI
+     */
+    updateJwksUri(jwksUri: string): void;
+}
+
+/**
+ * JWT Claims (raw payload from token)
+ */
+export declare interface JWTClaims {
+    sessionId: string;
+    applicationId: string;
+    userId: string;
+    orgId: string;
+    startTime: number;
+    durationMinutes: number;
+    iat: number;
+    exp: number;
+    iss: string;
+    sub: string;
+}
+
+/**
+ * JWT Header
+ */
+export declare interface JWTHeader {
+    alg: string;
+    typ: string;
+    kid: string;
+}
+
+/**
+ * JWT Parser for client-side token decoding
+ * Note: Does NOT verify signature - use JWKSValidator for verification
+ */
+export declare class JWTParser {
+    /**
+     * Decode JWT payload without verification
+     * @param token - JWT token string
+     * @returns Decoded payload
+     */
+    static decode(token: string): JWTClaims;
+    /**
+     * Decode JWT header
+     * @param token - JWT token string
+     * @returns Decoded header
+     */
+    static decodeHeader(token: string): JWTHeader;
+    /**
+     * Extract specific claim from JWT
+     * @param token - JWT token string
+     * @param claim - Claim name to extract
+     * @returns Claim value
+     */
+    static extractClaim<T = any>(token: string, claim: string): T;
+    /**
+     * Check if JWT is expired (client-side only, not authoritative)
+     * @param token - JWT token string
+     * @returns True if token is expired
+     */
+    static isExpired(token: string): boolean;
+    /**
+     * Get time remaining until expiration
+     * @param token - JWT token string
+     * @returns Seconds remaining (0 if expired)
+     */
+    static getTimeRemaining(token: string): number;
+    /**
+     * Base64 URL decode
+     * @param str - Base64 URL encoded string
+     * @returns Decoded string
+     */
+    private static base64UrlDecode;
+}
+
+/**
+ * Light theme matching gw-spa design system
+ */
+export declare const lightTheme: Theme;
+
+/**
+ * Simple logger with debug mode support
+ */
+export declare class Logger {
+    private debug;
+    private prefix;
+    constructor(debug?: boolean, prefix?: string);
+    /**
+     * Log debug message (only if debug enabled)
+     */
+    log(...args: any[]): void;
+    /**
+     * Log info message (only if debug enabled)
+     */
+    info(...args: any[]): void;
+    /**
+     * Log warning message (always shown)
+     */
+    warn(...args: any[]): void;
+    /**
+     * Log error message (always shown)
+     */
+    error(...args: any[]): void;
+}
+
+/**
+ * Marketplace SDK with Phase 2 Features
+ * - Heartbeat system
+ * - Multi-tab synchronization
+ * - Visibility API integration
+ * - Session extension/completion
+ * - Backend validation
+ */
+declare class MarketplaceSDK {
+    private config;
+    private validator;
+    private timer;
+    private heartbeat;
+    private tabSync;
+    private modal;
+    private logger;
+    private events;
+    private sessionData;
+    private jwtToken;
+    private endReason;
+    constructor(config: SDKConfig);
+    /**
+     * Register event handlers
+     */
+    on<K extends keyof SDKEvents>(event: K, handler: SDKEvents[K]): void;
+    /**
+     * Execute a lifecycle hook with timeout
+     */
+    private executeHook;
+    /**
+     * Calculate actual session duration in minutes
+     */
+    private calculateActualDuration;
+    /**
+     * Initialize SDK and validate session
+     */
+    initialize(): Promise<SessionData>;
+    /**
+     * Phase 2: Validate JWT with backend
+     */
+    private validateWithBackend;
+    /**
+     * Phase 2: Handle tab sync messages
+     */
+    private handleTabSyncMessage;
+    /**
+     * Phase 2: Initialize Visibility API handling
+     */
+    private initializeVisibilityHandling;
+    /**
+     * Start session timer manually
+     */
+    startTimer(): void;
+    /**
+     * Pause session timer
+     */
+    pauseTimer(): void;
+    /**
+     * Resume session timer
+     */
+    resumeTimer(): void;
+    /**
+     * Phase 2: Extend session
+     */
+    extendSession(additionalMinutes: number): Promise<void>;
+    /**
+     * Phase 2: Complete session
+     */
+    completeSession(actualUsageMinutes?: number): Promise<void>;
+    /**
+     * End session
+     */
+    endSession(): Promise<void>;
+    /**
+     * Show warning modal
+     */
+    private showWarningModal;
+    /**
+     * Get current session data
+     */
+    getSessionData(): SessionData | null;
+    /**
+     * Get remaining time
+     */
+    getRemainingTime(): number;
+    /**
+     * Get formatted time (MM:SS)
+     */
+    getFormattedTime(): string;
+    /**
+     * Get formatted time with hours (HH:MM:SS)
+     */
+    getFormattedTimeWithHours(): string;
+    /**
+     * Check if timer is running
+     */
+    isTimerRunning(): boolean;
+    /**
+     * Cleanup and destroy SDK instance
+     */
+    destroy(): void;
+}
+export { MarketplaceSDK }
+export default MarketplaceSDK;
+
+/**
+ * Modal styling options (Legacy - prefer using theme)
+ * @deprecated Use theme configuration from src/styles/theme.ts instead
+ */
+export declare interface ModalStyles {
+    backgroundColor: string;
+    textColor: string;
+    primaryColor: string;
+    borderRadius: string;
+    fontFamily: string;
+}
+
+/**
+ * SDK Configuration
+ */
+export declare interface SDKConfig {
+    /** JWKS endpoint URL (default: https://api.generalwisdom.com/.well-known/jwks.json) */
+    jwksUri?: string;
+    /** API endpoint for backend integration (Phase 2) */
+    apiEndpoint?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Auto-start timer after initialization */
+    autoStart?: boolean;
+    /** Warning threshold in seconds (default: 300 = 5 minutes) */
+    warningThresholdSeconds?: number;
+    /** Custom styling for warning modal (Legacy - prefer using themeMode) */
+    customStyles?: Partial<ModalStyles>;
+    /** Theme mode for modal styling (default: 'light') */
+    themeMode?: ThemeMode;
+    /** Application ID for validation */
+    applicationId?: string;
+    /** Marketplace URL for redirects (default: https://d3p2yqofgy75sz.cloudfront.net/) */
+    marketplaceUrl?: string;
+    /** Enable heartbeat system (default: false) */
+    enableHeartbeat?: boolean;
+    /** Heartbeat interval in seconds (default: 30) */
+    heartbeatIntervalSeconds?: number;
+    /** Enable multi-tab synchronization (default: false) */
+    enableTabSync?: boolean;
+    /** Pause timer when tab is hidden (default: false) */
+    pauseOnHidden?: boolean;
+    /** Use backend validation instead of JWKS (default: false) */
+    useBackendValidation?: boolean;
+    /** Optional hooks for synchronizing app auth state with marketplace sessions */
+    hooks?: SessionLifecycleHooks;
+    /** Hook execution timeout in milliseconds (default: 5000) */
+    hookTimeoutMs?: number;
+}
+
+/**
+ * Custom SDK Error
+ */
+export declare class SDKError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined);
+}
+
+/**
+ * SDK Event Handlers
+ */
+export declare interface SDKEvents {
+    /** Called when session successfully initialized */
+    onSessionStart: (data: SessionData) => void;
+    /** Called when warning threshold reached */
+    onSessionWarning: (data: {
+        remainingSeconds: number;
+    }) => void;
+    /** Called when session expires or is ended */
+    onSessionEnd: () => void;
+    /** Called on any error */
+    onError: (error: Error) => void;
+}
+
+/**
+ * Session Data extracted from JWT
+ */
+export declare interface SessionData {
+    /** Unique session UUID */
+    sessionId: string;
+    /** Application ID */
+    applicationId: string;
+    /** User ID */
+    userId: string;
+    /** Organization ID */
+    orgId: string;
+    /** Session start time (Unix timestamp seconds) */
+    startTime: number;
+    /** Session duration in minutes */
+    durationMinutes: number;
+    /** Issued at timestamp (Unix seconds) */
+    iat: number;
+    /** Expiration timestamp (Unix seconds) */
+    exp: number;
+    /** Issuer */
+    iss: string;
+    /** Subject (user ID) */
+    sub: string;
+}
+
+export declare interface SessionEndContext {
+    /** Unique session UUID */
+    sessionId: string;
+    /** User ID */
+    userId: string;
+    /** Reason for session end */
+    reason: 'expired' | 'manual' | 'error';
+    /** Actual session duration in minutes (if available) */
+    actualDurationMinutes?: number;
+}
+
+export declare interface SessionExtendContext {
+    /** Unique session UUID */
+    sessionId: string;
+    /** User ID */
+    userId: string;
+    /** Additional minutes added to session */
+    additionalMinutes: number;
+    /** New expiration timestamp (Unix seconds) */
+    newExpiresAt: number;
+}
+
+/**
+ * Session Header Component
+ * Compact header widget showing session timer with extend/end controls
+ */
+export declare class SessionHeader {
+    private container;
+    private theme;
+    private updateInterval;
+    private timeDisplay;
+    private getTimeCallback;
+    private onExtendCallback;
+    private onEndCallback;
+    private mounted;
+    constructor(themeMode?: ThemeMode);
+    private detectDarkMode;
+    /**
+     * Mount the session header to a DOM element
+     * @param targetElement - Element to mount to (or selector string)
+     * @param options - Configuration options
+     */
+    mount(targetElement: HTMLElement | string, options: {
+        getTime: () => string;
+        onExtend?: () => void;
+        onEnd?: () => void;
+        position?: 'left' | 'center' | 'right';
+    }): void;
+    /**
+     * Start updating the time display
+     */
+    private startUpdating;
+    /**
+     * Unmount and cleanup the session header
+     */
+    unmount(): void;
+    /**
+     * Check if component is mounted
+     */
+    isMounted(): boolean;
+    /**
+     * Update the theme
+     */
+    updateTheme(themeMode: ThemeMode): void;
+}
+
+/**
+ * Session Lifecycle Hooks
+ * Optional callbacks that allow applications to synchronize their auth state with marketplace sessions
+ */
+export declare interface SessionLifecycleHooks {
+    /**
+     * Called after JWT validation succeeds but before session timer starts
+     * Use to: Auto-login user to your app's auth system
+     * Note: Hook failure will prevent session from starting
+     */
+    onSessionStart?: (context: SessionStartContext) => Promise<void> | void;
+    /**
+     * Called when session expires or is manually ended, before redirect
+     * Use to: Force logout user from your app's auth system
+     * Note: Hook failure will be logged but won't prevent session end
+     */
+    onSessionEnd?: (context: SessionEndContext) => Promise<void> | void;
+    /**
+     * Called when session extension succeeds
+     * Use to: Refresh app auth tokens if needed
+     */
+    onSessionExtend?: (context: SessionExtendContext) => Promise<void> | void;
+    /**
+     * Called before session warning modal is shown
+     * Use to: Prepare user for session expiration
+     */
+    onSessionWarning?: (context: SessionWarningContext) => Promise<void> | void;
+}
+
+/**
+ * Session Lifecycle Hook Contexts
+ */
+export declare interface SessionStartContext {
+    /** Unique session UUID */
+    sessionId: string;
+    /** User ID from JWT */
+    userId: string;
+    /** User email (if available in JWT) */
+    email?: string;
+    /** Organization ID */
+    orgId: string;
+    /** Application ID */
+    applicationId: string;
+    /** Session duration in minutes */
+    durationMinutes: number;
+    /** Expiration timestamp (Unix seconds) */
+    expiresAt: number;
+    /** Full JWT token for app use */
+    jwt: string;
+}
+
+export declare interface SessionWarningContext {
+    /** Unique session UUID */
+    sessionId: string;
+    /** User ID */
+    userId: string;
+    /** Remaining seconds until expiration */
+    remainingSeconds: number;
+}
+
+/**
+ * Tab Synchronization Manager
+ * Phase 2 Feature - Syncs session state across multiple tabs
+ */
+export declare class TabSyncManager {
+    private sessionId;
+    private onMessage;
+    private channel;
+    private storageKey;
+    private logger;
+    private isMaster;
+    constructor(sessionId: string, onMessage: (message: TabSyncMessage) => void, debug?: boolean);
+    /**
+     * Initialize sync mechanism
+     */
+    private initialize;
+    /**
+     * Broadcast message to other tabs
+     */
+    broadcast(type: TabSyncMessage['type'], data?: Partial<TabSyncMessage>): void;
+    /**
+     * Handle incoming message
+     */
+    private handleMessage;
+    /**
+     * Handle storage event (fallback mechanism)
+     */
+    private handleStorageEvent;
+    /**
+     * Elect this tab as master if appropriate
+     * Master tab is responsible for heartbeats
+     */
+    private electMaster;
+    /**
+     * Check if this tab is the master
+     */
+    isMasterTab(): boolean;
+    /**
+     * Cleanup and destroy
+     */
+    destroy(): void;
+}
+
+export declare interface TabSyncMessage {
+    type: 'timer_update' | 'pause' | 'resume' | 'end';
+    sessionId: string;
+    remainingSeconds?: number;
+    timestamp: number;
+}
+
+export declare interface Theme {
+    colors: ThemeColors;
+    typography: ThemeTypography;
+    spacing: ThemeSpacing;
+}
+
+/**
+ * Theme configuration matching the General Wisdom SPA design system
+ * Based on gw-spa/src/styles/globals.css and Tailwind CSS v4
+ */
+export declare interface ThemeColors {
+    background: string;
+    foreground: string;
+    card: string;
+    cardForeground: string;
+    popover: string;
+    popoverForeground: string;
+    primary: string;
+    primaryForeground: string;
+    secondary: string;
+    secondaryForeground: string;
+    muted: string;
+    mutedForeground: string;
+    accent: string;
+    accentForeground: string;
+    destructive: string;
+    destructiveForeground: string;
+    success: string;
+    successForeground: string;
+    border: string;
+    input: string;
+    ring: string;
+}
+
+/**
+ * Theme mode for modal styling
+ */
+export declare type ThemeMode = 'light' | 'dark' | 'auto';
+
+export declare interface ThemeSpacing {
+    borderRadius: {
+        sm: string;
+        md: string;
+        lg: string;
+    };
+    padding: {
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+    };
+    gap: {
+        sm: string;
+        md: string;
+        lg: string;
+    };
+}
+
+export declare interface ThemeTypography {
+    fontFamily: string;
+    fontSize: {
+        xs: string;
+        sm: string;
+        base: string;
+        lg: string;
+        xl: string;
+        '2xl': string;
+    };
+    fontWeight: {
+        normal: string;
+        medium: string;
+        semibold: string;
+        bold: string;
+    };
+    lineHeight: {
+        tight: string;
+        normal: string;
+        relaxed: string;
+    };
+}
+
+/**
+ * Timer Manager for session countdown
+ */
+export declare class TimerManager {
+    private remainingSeconds;
+    private intervalId;
+    private warningThreshold;
+    private warningShown;
+    private logger;
+    private events;
+    constructor(durationSeconds: number, warningThresholdSeconds?: number, events?: Partial<SDKEvents>, debug?: boolean);
+    /**
+     * Start countdown timer
+     */
+    start(): void;
+    /**
+     * Stop timer
+     */
+    stop(): void;
+    /**
+     * Pause timer
+     */
+    pause(): void;
+    /**
+     * Resume timer
+     */
+    resume(): void;
+    /**
+     * Get remaining time in seconds
+     */
+    getRemainingSeconds(): number;
+    /**
+     * Get formatted time string (MM:SS)
+     */
+    getFormattedTime(): string;
+    /**
+     * Get formatted time string with hours (HH:MM:SS)
+     */
+    getFormattedTimeWithHours(): string;
+    /**
+     * Check if timer is running
+     */
+    isRunning(): boolean;
+    /**
+     * Check if warning has been shown
+     */
+    hasWarningBeenShown(): boolean;
+    /**
+     * Update remaining time (useful for syncing with server)
+     */
+    updateRemainingTime(seconds: number): void;
+}
+
+/**
+ * Warning Modal for session expiration alerts
+ */
+export declare class WarningModal {
+    private modal;
+    private theme;
+    private legacyStyles;
+    private updateInterval;
+    private timeDisplay;
+    private startTime;
+    private initialSeconds;
+    private onEndCallback;
+    constructor(themeMode?: ThemeMode, customStyles?: Partial<ModalStyles>);
+    private detectDarkMode;
+    /**
+     * Show warning modal
+     */
+    show(options: {
+        remainingSeconds: number;
+        onExtend?: () => void;
+        onEnd?: () => void;
+    }): void;
+    /**
+     * Hide and remove modal
+     */
+    hide(): void;
+    /**
+     * Check if modal is currently shown
+     */
+    isShown(): boolean;
+    /**
+     * Show "Session Ending" modal before redirect
+     * Displays for a fixed duration (3 seconds) then calls callback
+     */
+    showEndingMessage(onComplete: () => void, durationMs?: number): void;
+}
+
+export { }