@hcu-lab.me/mcp-device 1.0.0

package/dist/ui/shared/widget-state.js

@@ -0,0 +1,158 @@
+/**
+ * Widget state persistence for MCP Apps hosts.
+ *
+ * ChatGPT has a special extension (window.openai.widgetState) for persisting
+ * widget state across page refreshes. Other hosts use the standard MCP Apps
+ * pattern where ui/notifications/tool-result is re-sent when needed.
+ *
+ * This module provides a simple abstraction:
+ * - ChatGPT: Uses window.openai.widgetState
+ * - Other hosts: No-op (rely on standard ui/notifications/tool-result)
+ */
+const FALLBACK_WIDGET_STATE_KEY_PREFIX = 'mcp-device:widget-state';
+const FALLBACK_WIDGET_INSTANCE_MARKER = '__mcp_device_widget_id__:';
+function createWidgetInstanceId() {
+    const cryptoObject = typeof globalThis.crypto === 'object' ? globalThis.crypto : undefined;
+    if (typeof cryptoObject?.randomUUID === 'function') {
+        return cryptoObject.randomUUID();
+    }
+    return `widget-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function readWidgetInstanceIdFromWindowName(windowName) {
+    const markerIndex = windowName.indexOf(FALLBACK_WIDGET_INSTANCE_MARKER);
+    if (markerIndex === -1) {
+        return undefined;
+    }
+    const encodedValue = windowName
+        .slice(markerIndex + FALLBACK_WIDGET_INSTANCE_MARKER.length)
+        .split('|', 1)[0];
+    if (!encodedValue) {
+        return undefined;
+    }
+    try {
+        return decodeURIComponent(encodedValue);
+    }
+    catch {
+        return encodedValue;
+    }
+}
+function getFallbackWidgetInstanceId() {
+    if (typeof window === 'undefined') {
+        return 'unknown-instance';
+    }
+    const currentWindowName = typeof window.name === 'string' ? window.name : '';
+    const existingInstanceId = readWidgetInstanceIdFromWindowName(currentWindowName);
+    if (existingInstanceId) {
+        return existingInstanceId;
+    }
+    const instanceId = createWidgetInstanceId();
+    const marker = `${FALLBACK_WIDGET_INSTANCE_MARKER}${encodeURIComponent(instanceId)}`;
+    try {
+        window.name = currentWindowName ? `${currentWindowName}|${marker}` : marker;
+    }
+    catch {
+        // Ignore window.name write failures and fall back to the in-memory id.
+    }
+    return instanceId;
+}
+function getFallbackWidgetStateKey() {
+    if (typeof window === 'undefined') {
+        return `${FALLBACK_WIDGET_STATE_KEY_PREFIX}:unknown`;
+    }
+    const appPath = window.location.pathname || 'unknown';
+    const instanceId = getFallbackWidgetInstanceId();
+    return `${FALLBACK_WIDGET_STATE_KEY_PREFIX}:${appPath}:${encodeURIComponent(instanceId)}`;
+}
+function getSessionStorage() {
+    if (typeof window === 'undefined') {
+        return undefined;
+    }
+    try {
+        return window.sessionStorage;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Check if we're running in ChatGPT (has special widget state API)
+ */
+export function isChatGPT() {
+    return typeof window !== 'undefined' &&
+        typeof window.openai?.setWidgetState === 'function';
+}
+/**
+ * Create a widget state storage adapter.
+ *
+ * On ChatGPT: Uses window.openai.widgetState for persistence
+ * On other hosts: Uses sessionStorage as a fallback so the preview can survive
+ *   transient interruptions (page refresh on hosts that don't re-send tool_result,
+ *   visibility/focus loss, etc.).
+ *   The fallback cache key is scoped by app pathname and a per-frame widget id
+ *   persisted in window.name, so different widgets in the same origin/session
+ *   do not overwrite one another's cached state.
+ */
+export function createWidgetStateStorage(validator) {
+    if (!isChatGPT()) {
+        const storage = getSessionStorage();
+        const storageKey = getFallbackWidgetStateKey();
+        return {
+            read() {
+                if (!storage)
+                    return undefined;
+                try {
+                    const raw = storage.getItem(storageKey);
+                    if (!raw)
+                        return undefined;
+                    const parsed = JSON.parse(raw);
+                    const payload = parsed?.payload;
+                    if (payload === undefined)
+                        return undefined;
+                    if (validator && !validator(payload))
+                        return undefined;
+                    return payload;
+                }
+                catch {
+                    return undefined;
+                }
+            },
+            write(state) {
+                if (!storage)
+                    return;
+                try {
+                    storage.setItem(storageKey, JSON.stringify({ payload: state }));
+                }
+                catch {
+                    // Ignore storage failures
+                }
+            }
+        };
+    }
+    // ChatGPT-specific implementation
+    return {
+        read() {
+            try {
+                const state = window.openai?.widgetState;
+                if (state === undefined || state === null)
+                    return undefined;
+                const payload = state.payload;
+                if (payload === undefined)
+                    return undefined;
+                if (validator && !validator(payload))
+                    return undefined;
+                return payload;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        write(state) {
+            try {
+                window.openai?.setWidgetState?.({ payload: state });
+            }
+            catch {
+                // Ignore write failures
+            }
+        }
+    };
+}

package/dist/utils/ab-test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Get the exact assigned variant for a named experiment.
+ */
+export declare function getABTestVariant(experimentName: string): Promise<string | null>;
+/**
+ * Check if a feature (variant name) is enabled for current user
+ */
+export declare function hasFeature(featureName: string): Promise<boolean>;
+/**
+ * Get all A/B test assignments for analytics (reads from config)
+ */
+export declare function getABTestAssignments(): Promise<Record<string, string>>;

package/dist/utils/ab-test.js

@@ -0,0 +1,104 @@
+import { configManager } from '../config-manager.js';
+import { featureFlagManager } from './feature-flags.js';
+// Cache for variant assignments (loaded once per session)
+const variantCache = {};
+/**
+ * Get experiments config from feature flags
+ */
+function getExperiments() {
+    return featureFlagManager.get('experiments', {});
+}
+/**
+ * Get user's variant for an experiment (cached, deterministic)
+ * Supports weighted variants for unequal splits
+ */
+async function getVariant(experimentName) {
+    const experiments = getExperiments();
+    const experiment = experiments[experimentName];
+    if (!experiment?.variants?.length)
+        return null;
+    // Check cache
+    if (variantCache[experimentName]) {
+        return variantCache[experimentName];
+    }
+    // Check persisted assignment
+    const configKey = `abTest_${experimentName}`;
+    const existing = await configManager.getValue(configKey);
+    // Validate existing assignment is still a valid variant
+    const variantNames = experiment.variants.map(v => v.name);
+    if (existing && variantNames.includes(existing)) {
+        variantCache[experimentName] = existing;
+        return existing;
+    }
+    // New assignment based on clientId with weighted selection
+    const clientId = await configManager.getOrCreateClientId();
+    const hash = hashCode(clientId + experimentName);
+    // Calculate total weight and select variant
+    const totalWeight = experiment.variants.reduce((sum, v) => sum + v.weight, 0);
+    let variant;
+    if (totalWeight > 0) {
+        const roll = hash % totalWeight;
+        let cumulative = 0;
+        variant = experiment.variants[0].name; // fallback
+        for (const v of experiment.variants) {
+            cumulative += v.weight;
+            if (roll < cumulative) {
+                variant = v.name;
+                break;
+            }
+        }
+    }
+    else {
+        // Fallback to equal split when weights are misconfigured (all zero)
+        const index = hash % experiment.variants.length;
+        variant = experiment.variants[index].name;
+    }
+    await configManager.setValue(configKey, variant);
+    variantCache[experimentName] = variant;
+    return variant;
+}
+/**
+ * Get the exact assigned variant for a named experiment.
+ */
+export async function getABTestVariant(experimentName) {
+    return getVariant(experimentName);
+}
+/**
+ * Check if a feature (variant name) is enabled for current user
+ */
+export async function hasFeature(featureName) {
+    const experiments = getExperiments();
+    if (!experiments || typeof experiments !== 'object')
+        return false;
+    for (const [expName, experiment] of Object.entries(experiments)) {
+        const variantNames = experiment?.variants?.map(v => v.name) || [];
+        if (variantNames.includes(featureName)) {
+            const variant = await getVariant(expName);
+            return variant === featureName;
+        }
+    }
+    return false;
+}
+/**
+ * Get all A/B test assignments for analytics (reads from config)
+ */
+export async function getABTestAssignments() {
+    const experiments = getExperiments();
+    const assignments = {};
+    for (const expName of Object.keys(experiments)) {
+        const configKey = `abTest_${expName}`;
+        const variant = await configManager.getValue(configKey);
+        if (variant) {
+            assignments[`ab_${expName}`] = variant;
+        }
+    }
+    return assignments;
+}
+function hashCode(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        hash = ((hash << 5) - hash) + str.charCodeAt(i);
+        hash |= 0;
+    }
+    return Math.abs(hash);
+}

package/dist/utils/capture.d.ts

@@ -0,0 +1,35 @@
+export declare function runInUiOriginCallContext<T>(fn: () => T): T;
+export declare function isInsideUiOriginCall(): boolean;
+/**
+ * Hard kill-switch for telemetry via environment variable.
+ *
+ * Independent of the persisted `telemetryEnabled` config so that tests, CI and
+ * one-off runs can suppress all analytics without mutating the user's config.
+ * Set DESKTOP_COMMANDER_DISABLE_TELEMETRY to 1/true/yes/on to disable.
+ */
+export declare function isTelemetryDisabledByEnv(): boolean;
+/**
+ * Sanitizes error objects to remove potentially sensitive information like file paths
+ * @param error Error object or string to sanitize
+ * @returns An object with sanitized message and optional error code
+ */
+export declare function sanitizeError(error: any): {
+    message: string;
+    code?: string;
+};
+/**
+ * Send an event to telemetry
+ * @param event Event name
+ * @param properties Optional event properties
+ */
+export declare const captureBase: (captureURL: string, event: string, properties?: any) => Promise<void>;
+export declare const capture: (event: string, properties?: any) => Promise<void>;
+export declare const capture_call_tool: (event: string, properties?: any) => Promise<void>;
+export declare const capture_ui_event: (event: string, properties?: any) => Promise<void>;
+/**
+ * Wrapper for capture() that automatically adds remote flag for device telemetry
+ * Also adds additional privacy filtering to remove sensitive identity information
+ * @param event Event name
+ * @param properties Optional event properties
+ */
+export declare const captureRemote: (event: string, properties?: any) => Promise<void>;