@bobfrankston/msgapidefs 0.1.0

package/msgapidefs.ts

@@ -0,0 +1,427 @@
+/**
+ * TypeScript definitions for the msgapi JavaScript API
+ *
+ * This module provides type-safe access to msgapi's window control,
+ * data persistence, and file system features (used by msgview and msger).
+ *
+ * Usage:
+ * ```typescript
+ * import type { MsgAPI } from '@bobfrankston/msgapidefs';
+ *
+ * declare global {
+ *     interface Window {
+ *         msgapi?: MsgAPI;
+ *     }
+ * }
+ *
+ * // Check if running in msgview/msger
+ * if (window.msgapi) {
+ *     window.msgapi.setTitle('My App');
+ * }
+ * ```
+ */
+
+/**
+ * Result object returned when the window closes
+ */
+export interface MsgResult {
+    /** Button that was clicked */
+    button: string;
+    /** Optional input field value */
+    value?: string;
+    /** Optional form data */
+    form?: Record<string, any>;
+    /** True if window was closed via close button */
+    closed?: boolean;
+    /** True if window was dismissed via Escape key */
+    dismissed?: boolean;
+    /** True if window was closed due to timeout */
+    timeout?: boolean;
+}
+
+/**
+ * File information returned by file system operations
+ */
+export interface FileInfo {
+    /** File name */
+    name: string;
+    /** Full file path */
+    path: string;
+    /** True if this is a directory */
+    isDir: boolean;
+    /** File size in bytes (0 for directories) */
+    size: number;
+    /** Last modified timestamp (ISO 8601 string) */
+    modified?: string;
+}
+
+/**
+ * Options for file selection dialogs
+ */
+export interface FileDialogOptions {
+    /** Dialog title */
+    title?: string;
+    /** Default filename for save dialogs */
+    defaultFilename?: string;
+    /** File filters (e.g., [{name: "Text", extensions: ["txt", "md"]}]) */
+    filters?: Array<{name: string; extensions: string[]}>;
+    /** Default directory to open */
+    defaultPath?: string;
+}
+
+/**
+ * Selected file with content
+ */
+export interface SelectedFile {
+    /** File name */
+    name: string;
+    /** Full file path */
+    path: string;
+    /** File content as string */
+    content: string;
+}
+
+/**
+ * msgapi JavaScript API
+ *
+ * Available when running inside msgview/msger via window.msgapi
+ */
+export interface MsgAPI {
+    // ========================================
+    // Window Control
+    // ========================================
+
+    /**
+     * Toggle fullscreen mode on/off
+     * @example
+     * msgapi.toggleFullscreen();
+     */
+    toggleFullscreen(): void;
+
+    /**
+     * Set fullscreen mode
+     * @param enabled - true to enter fullscreen, false to exit
+     * @example
+     * msgapi.setFullscreen(true);
+     */
+    setFullscreen(enabled: boolean): void;
+
+    /**
+     * Minimize the window
+     * @example
+     * msgapi.minimize();
+     */
+    minimize(): void;
+
+    /**
+     * Toggle maximize/restore window
+     * @example
+     * msgapi.maximize();
+     */
+    maximize(): void;
+
+    /**
+     * Set window size
+     * @param width - Window width in pixels
+     * @param height - Window height in pixels
+     * @example
+     * msgapi.setSize(800, 600);
+     */
+    setSize(width: number, height: number): void;
+
+    /**
+     * Set window position
+     * @param x - X coordinate in pixels
+     * @param y - Y coordinate in pixels
+     * @example
+     * msgapi.setPosition(100, 100);
+     */
+    setPosition(x: number, y: number): void;
+
+    /**
+     * Set always-on-top behavior
+     * @param enabled - true to keep window on top
+     * @example
+     * msgapi.setAlwaysOnTop(true);
+     */
+    setAlwaysOnTop(enabled: boolean): void;
+
+    /**
+     * Set window title
+     * @param title - New window title
+     * @example
+     * msgapi.setTitle("My Application");
+     */
+    setTitle(title: string): void;
+
+    /**
+     * Close the window
+     * @param result - Optional result to return to parent process
+     * @example
+     * // Close with default dismissed result
+     * msgapi.close();
+     *
+     * // Close with custom result
+     * msgapi.close({button: 'OK', value: 'user data'});
+     */
+    close(result?: Partial<MsgResult>): void;
+
+    /**
+     * Send result and close window (legacy compatibility)
+     * @param result - Result to return to parent process
+     * @example
+     * msgapi.sendResult({button: 'Submit', value: 'form data'});
+     */
+    sendResult(result: Partial<MsgResult>): void;
+
+    // ========================================
+    // Data Persistence (localStorage wrapper)
+    // ========================================
+
+    /**
+     * Save data to persistent storage
+     * Data is stored with 'msgapi_' prefix in localStorage
+     * @param key - Storage key
+     * @param value - Value to store (will be JSON.stringify'd)
+     * @returns true on success, false on failure
+     * @example
+     * msgapi.saveData('userPrefs', {theme: 'dark', fontSize: 14});
+     */
+    saveData(key: string, value: any): boolean;
+
+    /**
+     * Load data from persistent storage
+     * @param key - Storage key
+     * @param defaultValue - Default value if key not found
+     * @returns Stored value or defaultValue
+     * @example
+     * const prefs = msgapi.loadData('userPrefs', {theme: 'light'});
+     */
+    loadData<T = any>(key: string, defaultValue?: T): T;
+
+    /**
+     * Remove data from persistent storage
+     * @param key - Storage key to remove
+     * @returns true on success, false on failure
+     * @example
+     * msgapi.removeData('tempData');
+     */
+    removeData(key: string): boolean;
+
+    /**
+     * Clear all msgapi data from persistent storage
+     * Only removes items with 'msgapi_' prefix
+     * @returns true on success, false on failure
+     * @example
+     * msgapi.clearData();
+     */
+    clearData(): boolean;
+
+    // ========================================
+    // File System Access (to be implemented)
+    // ========================================
+
+    /**
+     * File system operations namespace
+     */
+    fs?: {
+        /**
+         * Select a file using native file picker
+         * @param options - File dialog options
+         * @returns Selected file with content, or null if cancelled
+         * @example
+         * const file = await msgapi.fs.selectFile({
+         *     title: 'Open File',
+         *     filters: [{name: 'Text', extensions: ['txt', 'md']}]
+         * });
+         * if (file) {
+         *     console.log(file.content);
+         * }
+         */
+        selectFile(options?: FileDialogOptions): Promise<SelectedFile | null>;
+
+        /**
+         * Select multiple files using native file picker
+         * @param options - File dialog options
+         * @returns Array of selected files with content
+         * @example
+         * const files = await msgapi.fs.selectFiles({
+         *     title: 'Open Files'
+         * });
+         */
+        selectFiles(options?: FileDialogOptions): Promise<SelectedFile[]>;
+
+        /**
+         * Save file using native save dialog
+         * @param content - File content to save
+         * @param defaultFilename - Default filename
+         * @param options - Additional dialog options
+         * @returns Path where file was saved, or null if cancelled
+         * @example
+         * const path = await msgapi.fs.saveFileAs('Hello World', 'greeting.txt');
+         */
+        saveFileAs(
+            content: string,
+            defaultFilename?: string,
+            options?: FileDialogOptions
+        ): Promise<string | null>;
+
+        /**
+         * Select a directory using native folder picker
+         * @param options - Dialog options
+         * @returns Selected directory path, or null if cancelled
+         * @example
+         * const dir = await msgapi.fs.selectFolder({
+         *     title: 'Select Output Folder'
+         * });
+         */
+        selectFolder(options?: FileDialogOptions): Promise<string | null>;
+
+        /**
+         * Read file contents
+         * Note: Requires allowFs: true flag when launching msgview/msger
+         * @param path - File path to read
+         * @returns File content as string
+         * @example
+         * const content = await msgapi.fs.read('/path/to/file.txt');
+         */
+        read(path: string): Promise<string>;
+
+        /**
+         * Write file contents
+         * Note: Requires allowFs: true flag when launching msgview/msger
+         * @param path - File path to write
+         * @param content - Content to write
+         * @example
+         * await msgapi.fs.write('/path/to/file.txt', 'Hello World');
+         */
+        write(path: string, content: string): Promise<void>;
+
+        /**
+         * List directory contents
+         * Note: Requires allowFs: true flag when launching msgview/msger
+         * @param path - Directory path to list
+         * @returns Array of file information
+         * @example
+         * const files = await msgapi.fs.list('/path/to/dir');
+         */
+        list(path: string): Promise<FileInfo[]>;
+
+        /**
+         * Check if file or directory exists
+         * Note: Requires allowFs: true flag when launching msgview/msger
+         * @param path - Path to check
+         * @returns true if exists
+         * @example
+         * const exists = await msgapi.fs.exists('/path/to/file.txt');
+         */
+        exists(path: string): Promise<boolean>;
+
+        /**
+         * Delete file or directory
+         * Note: Requires allowFs: true flag when launching msgview/msger
+         * @param path - Path to delete
+         * @example
+         * await msgapi.fs.delete('/path/to/file.txt');
+         */
+        delete(path: string): Promise<void>;
+    };
+}
+
+/**
+ * Helper to check if code is running in msgview/msger
+ * @returns true if running in msgapi environment
+ * @example
+ * if (isMsgAPI()) {
+ *     msgapi.setTitle('Running in msgview/msger!');
+ * } else {
+ *     console.log('Running in browser');
+ * }
+ */
+export function isMsgAPI(): boolean {
+    return typeof window !== 'undefined' && typeof window.msgapi !== 'undefined';
+}
+
+/**
+ * Get msgapi API with fallback for browser compatibility
+ * @returns msgapi API if available, or stub implementation for browser
+ * @example
+ * const api = getMsgAPI();
+ * api.saveData('key', 'value'); // Works in both msgview/msger and browser
+ */
+export function getMsgAPI(): MsgAPI {
+    if (isMsgAPI()) {
+        return window.msgapi!;
+    }
+
+    // Return browser-compatible stub
+    return {
+        // Window control - no-op in browser
+        toggleFullscreen: () => {},
+        setFullscreen: () => {},
+        minimize: () => {},
+        maximize: () => {},
+        setSize: () => {},
+        setPosition: () => {},
+        setAlwaysOnTop: () => {},
+        setTitle: (title: string) => { document.title = title; },
+        close: () => { window.close(); },
+        sendResult: () => { window.close(); },
+
+        // Data persistence - use localStorage in browser
+        saveData: (key: string, value: any): boolean => {
+            try {
+                localStorage.setItem('msgapi_' + key, JSON.stringify(value));
+                return true;
+            } catch {
+                return false;
+            }
+        },
+        loadData: <T = any>(key: string, defaultValue?: T): T => {
+            try {
+                const item = localStorage.getItem('msgapi_' + key);
+                return item ? JSON.parse(item) : (defaultValue as T);
+            } catch {
+                return defaultValue as T;
+            }
+        },
+        removeData: (key: string): boolean => {
+            try {
+                localStorage.removeItem('msgapi_' + key);
+                return true;
+            } catch {
+                return false;
+            }
+        },
+        clearData: (): boolean => {
+            try {
+                const keys = Object.keys(localStorage);
+                for (const key of keys) {
+                    if (key.startsWith('msgapi_')) {
+                        localStorage.removeItem(key);
+                    }
+                }
+                return true;
+            } catch {
+                return false;
+            }
+        },
+
+        // File system - not available in browser
+        fs: undefined
+    };
+}
+
+/**
+ * Declare global window.msgapi
+ */
+declare global {
+    interface Window {
+        msgapi?: MsgAPI;
+    }
+}
+
+export default {
+    isMsgAPI,
+    getMsgAPI
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@bobfrankston/msgapidefs",
+  "version": "0.1.0",
+  "description": "TypeScript definitions for msgapi JavaScript API (msgview/msger)",
+  "type": "module",
+  "main": "./msgapidefs.js",
+  "types": "./msgapidefs.d.ts",
+  "exports": {
+    ".": {
+      "import": "./msgapidefs.js",
+      "types": "./msgapidefs.d.ts"
+    }
+  },
+  "files": [
+    "msgapidefs.js",
+    "msgapidefs.d.ts",
+    "msgapidefs.ts",
+    "README.md",
+    "samples.html"
+  ],
+  "keywords": [
+    "msgapi",
+    "msgview",
+    "msger",
+    "typescript",
+    "definitions",
+    "types",
+    "webview"
+  ],
+  "author": "Bob Frankston",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BobFrankston/msgapidefs.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}