@gemigo/extension-sdk 0.1.2 → 0.2.1

package/dist/types/common.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Common types used across the GemiGo SDK
+ */
+/** Current platform type */
+export type Platform = 'web' | 'desktop' | 'extension';
+/** Environment capabilities */
+export interface Capabilities {
+    scheduler: boolean;
+    fileWatch: boolean;
+    fileWrite: boolean;
+    notification: boolean;
+    clipboard: boolean;
+    ai: boolean;
+    shell: boolean;
+    network: boolean;
+}
+/** File entry information */
+export interface FileEntry {
+    /** File name */
+    name: string;
+    /** Full path */
+    path: string;
+    /** Whether this is a file */
+    isFile: boolean;
+    /** Whether this is a directory */
+    isDirectory: boolean;
+    /** File size in bytes */
+    size: number;
+    /** Last modification timestamp */
+    mtime: number;
+}
+/** File stat information */
+export interface FileStat {
+    size: number;
+    mtime: number;
+    ctime: number;
+    isFile: boolean;
+    isDirectory: boolean;
+}

package/dist/types/desktop.d.ts

@@ -0,0 +1,138 @@
+import { NotifyOptions } from './notify';
+/** Scheduler task configuration */
+export interface SchedulerConfig {
+    /** Unique task ID */
+    id: string;
+    /** Interval (e.g. '30m', '1h', '2h', '1d') */
+    interval: string;
+    /** Start time (e.g. '08:00') */
+    startTime?: string;
+    /** End time (e.g. '22:00') */
+    endTime?: string;
+    /** Notification to show when task runs */
+    notification?: NotifyOptions;
+}
+/** Scheduler operation result */
+export interface SchedulerResult {
+    success: boolean;
+    reason?: string;
+}
+/** Scheduler API for background tasks */
+export interface SchedulerAPI {
+    /**
+     * Register a background scheduled task
+     * @param config - Task configuration
+     */
+    register(config: SchedulerConfig): Promise<SchedulerResult>;
+    /**
+     * Update an existing task
+     * @param id - Task ID
+     * @param config - Updated configuration
+     */
+    update(id: string, config: Partial<Omit<SchedulerConfig, 'id'>>): Promise<SchedulerResult>;
+    /**
+     * Cancel a scheduled task
+     * @param id - Task ID
+     */
+    cancel(id: string): Promise<void>;
+    /**
+     * List all scheduled tasks for this app
+     */
+    list(): Promise<SchedulerConfig[]>;
+}
+/** File watch event type */
+export type FileWatchEventType = 'create' | 'modify' | 'delete';
+/** File watch configuration */
+export interface FileWatchConfig {
+    /** Unique watch ID */
+    id: string;
+    /** Path to watch (e.g. '~/Downloads') */
+    path: string;
+    /** Glob pattern (e.g. '*.png') */
+    pattern?: string;
+    /** Events to watch for */
+    events: FileWatchEventType[];
+    /** Action to perform */
+    action: {
+        type: 'callback';
+        callback: string;
+    };
+}
+/** File watch event */
+export interface FileWatchEvent {
+    /** Watch ID */
+    id: string;
+    /** Changed file path */
+    path: string;
+    /** Event type */
+    event: FileWatchEventType;
+}
+/** FileWatch API for monitoring file system changes */
+export interface FileWatchAPI {
+    /**
+     * Register a file watch
+     * @param config - Watch configuration
+     */
+    register(config: FileWatchConfig): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Cancel a file watch
+     * @param id - Watch ID
+     */
+    cancel(id: string): Promise<void>;
+}
+/** File watch callback handler */
+export type FileWatchHandler = (callbackId: string, handler: (event: FileWatchEvent) => void) => void;
+/** Shell API for system integration */
+export interface ShellAPI {
+    /**
+     * Open URL in system default browser
+     * @param url - URL to open
+     */
+    openExternal(url: string): Promise<void>;
+    /**
+     * Show file in Finder/Explorer
+     * @param path - File path
+     */
+    showItemInFolder(path: string): Promise<void>;
+    /**
+     * Open file with system default application
+     * @param path - File path
+     */
+    openPath(path: string): Promise<void>;
+}
+/** GlobalShortcut API for system-level keyboard shortcuts */
+export interface GlobalShortcutAPI {
+    /**
+     * Register a global shortcut
+     * @param accelerator - Key combination (e.g. 'Cmd+Shift+X', 'Ctrl+Alt+P')
+     * @param callback - Handler function
+     * @returns True if registration succeeded
+     */
+    register(accelerator: string, callback: () => void): Promise<boolean>;
+    /**
+     * Unregister a global shortcut
+     * @param accelerator - Key combination
+     */
+    unregister(accelerator: string): Promise<void>;
+    /**
+     * Unregister all shortcuts for this app
+     */
+    unregisterAll(): Promise<void>;
+}
+/** Autostart API for managing app launch on system startup */
+export interface AutostartAPI {
+    /**
+     * Enable auto-start on system boot
+     */
+    enable(): Promise<void>;
+    /**
+     * Disable auto-start
+     */
+    disable(): Promise<void>;
+    /**
+     * Check if auto-start is enabled
+     */
+    isEnabled(): Promise<boolean>;
+}

package/dist/types/dialog.d.ts

@@ -0,0 +1,65 @@
+import { FileEntry } from './common';
+/** File filter for save dialog */
+export interface FileFilter {
+    name: string;
+    extensions: string[];
+}
+/** Open file dialog options */
+export interface OpenFileOptions {
+    /** MIME type filter, e.g. 'image/*' */
+    accept?: string;
+    /** Allow multiple file selection */
+    multiple?: boolean;
+}
+/** Save file dialog options */
+export interface SaveFileOptions {
+    /** Default file name */
+    defaultName?: string;
+    /** File type filters */
+    filters?: FileFilter[];
+}
+/** Message dialog options */
+export interface MessageOptions {
+    /** Dialog title */
+    title: string;
+    /** Dialog message */
+    message: string;
+    /** Message type */
+    type?: 'info' | 'warning' | 'error';
+    /** Button labels */
+    buttons?: string[];
+}
+/** Dialog API */
+export interface DialogAPI {
+    /**
+     * Open file selection dialog
+     * @param options - Dialog options
+     * @returns Selected file(s) or null if cancelled
+     */
+    openFile(options?: OpenFileOptions): Promise<FileEntry | FileEntry[] | null>;
+    /**
+     * Open directory selection dialog
+     * @returns Selected directory path or null if cancelled
+     */
+    openDirectory(): Promise<{
+        path: string;
+    } | null>;
+    /**
+     * Open save file dialog
+     * @param options - Dialog options
+     * @returns Selected save path or null if cancelled
+     */
+    saveFile(options?: SaveFileOptions): Promise<{
+        path: string;
+    } | null>;
+    /**
+     * Show a message dialog
+     * @param options - Message options
+     * @returns Index of clicked button
+     */
+    message(options: MessageOptions): Promise<number>;
+}
+/** File drop callback */
+export type FileDropCallback = (files: FileEntry[]) => void;
+/** File drop handler (top-level API) */
+export type FileDropHandler = (callback: FileDropCallback) => () => void;

package/dist/types/extension.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Browser Extension API types
+ * These APIs are only available when gemigo.platform === 'extension'
+ */
+/** Page information */
+export interface PageInfo {
+    url: string;
+    title: string;
+    favIconUrl?: string;
+}
+/** DOM element information */
+export interface ElementInfo {
+    text: string;
+    html: string;
+    rect: DOMRect;
+}
+/** Extracted article content */
+export interface ArticleContent {
+    title: string;
+    content: string;
+    author?: string;
+    date?: string;
+}
+/** Link information */
+export interface LinkInfo {
+    text: string;
+    href: string;
+}
+/** Image information */
+export interface ImageInfo {
+    src: string;
+    alt: string;
+    width: number;
+    height: number;
+}
+/** Highlight options */
+export interface HighlightOptions {
+    /** Highlight color */
+    color?: string;
+    /** Duration in ms before auto-remove */
+    duration?: number;
+}
+/** Widget position */
+export interface WidgetPosition {
+    x: number;
+    y: number;
+}
+/** Widget configuration */
+export interface WidgetConfig {
+    /** HTML content */
+    html: string;
+    /** Position on page */
+    position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | WidgetPosition;
+}
+/** Widget handle for controlling inserted widget */
+export interface WidgetHandle {
+    /** Remove the widget from page */
+    remove(): void;
+    /** Update widget HTML content */
+    update(html: string): void;
+}
+/** Full page capture options */
+export interface CaptureFullOptions {
+    /** Maximum height in pixels (default: 30000) */
+    maxHeight?: number;
+}
+/** Context menu event */
+export interface ContextMenuEvent {
+    menuId: string;
+    selectionText?: string;
+    pageUrl?: string;
+}
+/** Context menu event result */
+export interface ContextMenuEventResult {
+    success: boolean;
+    event?: ContextMenuEvent;
+}
+/** Capture result */
+export interface CaptureResult {
+    success: boolean;
+    dataUrl?: string;
+    error?: string;
+}
+/** Browser Extension API */
+export interface ExtensionAPI {
+    /**
+     * Listen for context menu clicks
+     * @param callback - Event handler
+     * @returns Unsubscribe function
+     */
+    onContextMenu(callback: (event: ContextMenuEvent) => void): () => void;
+    /**
+     * Get pending context menu event (when app opened via context menu)
+     */
+    getContextMenuEvent(): Promise<ContextMenuEventResult>;
+    /**
+     * Handle selection action button click
+     * @param actionId - Action ID from manifest
+     * @param callback - Handler function
+     */
+    onSelectionAction(actionId: string, callback: () => void): () => void;
+    /**
+     * Get current tab's page info
+     */
+    getPageInfo(): Promise<PageInfo>;
+    /**
+     * Get full page HTML
+     * @throws CROSS_ORIGIN error for cross-origin iframes
+     */
+    getPageHTML(): Promise<string>;
+    /**
+     * Get page text content (stripped of HTML tags)
+     */
+    getPageText(): Promise<string>;
+    /**
+     * Query element by CSS selector
+     * @param selector - CSS selector
+     * @returns Element info or null
+     */
+    queryElement(selector: string): Promise<ElementInfo | null>;
+    /**
+     * Extract article content using Readability algorithm
+     */
+    extractArticle(): Promise<ArticleContent>;
+    /**
+     * Extract all links from page
+     */
+    extractLinks(): Promise<LinkInfo[]>;
+    /**
+     * Extract all images from page
+     */
+    extractImages(): Promise<ImageInfo[]>;
+    /**
+     * Highlight elements matching selector
+     * @param selector - CSS selector
+     * @param options - Highlight options
+     * @returns Function to remove highlight
+     */
+    highlight(selector: string, options?: HighlightOptions): Promise<() => void>;
+    /**
+     * Insert a floating widget on page
+     * @param config - Widget configuration
+     * @returns Widget handle for control
+     */
+    insertWidget(config: WidgetConfig): Promise<WidgetHandle>;
+    /**
+     * Inject custom CSS styles
+     * @param css - CSS string
+     * @returns Function to remove injected styles
+     */
+    injectCSS(css: string): Promise<() => void>;
+    /**
+     * Listen for text selection changes
+     * @param callback - Selection change handler
+     * @returns Unsubscribe function
+     */
+    onSelectionChange(callback: (text: string) => void): () => void;
+    /**
+     * Listen for page navigation
+     * @param callback - Navigation handler
+     * @returns Unsubscribe function
+     */
+    onNavigate(callback: (url: string) => void): () => void;
+    /**
+     * Listen for page scroll (throttled)
+     * @param callback - Scroll handler
+     * @returns Unsubscribe function
+     */
+    onScroll(callback: (scrollY: number) => void): () => void;
+    /**
+     * Capture visible area screenshot
+     */
+    captureVisible(): Promise<CaptureResult>;
+    /**
+     * Capture full page screenshot (long screenshot)
+     * @param options - Capture options
+     * @returns Base64 PNG data URL
+     */
+    captureFull(options?: CaptureFullOptions): Promise<string>;
+    /**
+     * Register page-level keyboard shortcut
+     * @param combo - Key combination (e.g. 'Ctrl+Shift+T')
+     * @param callback - Handler function
+     * @returns Unregister function
+     */
+    registerShortcut(combo: string, callback: () => void): () => void;
+}

package/dist/types/file.d.ts

@@ -0,0 +1,79 @@
+import { FileEntry, FileStat } from './common';
+/** Mkdir options */
+export interface MkdirOptions {
+    /** Create parent directories if they don't exist */
+    recursive?: boolean;
+}
+/** File API for file system operations */
+export interface FileAPI {
+    /**
+     * Read text file (UTF-8)
+     * @param path - File path
+     * @returns File content as text
+     */
+    readText(path: string): Promise<string>;
+    /**
+     * Read binary file
+     * @param path - File path
+     * @returns File content as ArrayBuffer
+     */
+    readBinary(path: string): Promise<ArrayBuffer>;
+    /**
+     * Write to file
+     * @param path - File path
+     * @param data - Content to write
+     */
+    write(path: string, data: string | ArrayBuffer): Promise<void>;
+    /**
+     * Append to file
+     * @param path - File path
+     * @param data - Content to append
+     */
+    append(path: string, data: string | ArrayBuffer): Promise<void>;
+    /**
+     * Check if path exists
+     * @param path - File path
+     * @returns True if exists
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Get file/directory stats
+     * @param path - File path
+     * @returns File stat information
+     */
+    stat(path: string): Promise<FileStat>;
+    /**
+     * Copy file
+     * @param src - Source path
+     * @param dest - Destination path
+     */
+    copy(src: string, dest: string): Promise<void>;
+    /**
+     * Move/rename file
+     * @param src - Source path
+     * @param dest - Destination path
+     */
+    move(src: string, dest: string): Promise<void>;
+    /**
+     * Remove file or directory
+     * @param path - Path to remove
+     */
+    remove(path: string): Promise<void>;
+    /**
+     * List directory contents
+     * @param path - Directory path
+     * @returns Array of file entries
+     */
+    list(path: string): Promise<FileEntry[]>;
+    /**
+     * Create directory
+     * @param path - Directory path
+     * @param options - Creation options
+     */
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    /**
+     * Persist permission for a user-selected path
+     * @param path - Path to persist permission for
+     */
+    persistPermission(path: string): Promise<void>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,88 @@
+import { Platform, Capabilities, FileEntry } from './common';
+import { StorageAPI } from './storage';
+import { NotifyOptions, NotifyResult } from './notify';
+import { AIAPI } from './ai';
+import { ClipboardAPI } from './clipboard';
+import { DialogAPI } from './dialog';
+import { FileAPI } from './file';
+import { NetworkAPI } from './network';
+import { SchedulerAPI, FileWatchAPI, FileWatchEvent, ShellAPI, GlobalShortcutAPI, AutostartAPI } from './desktop';
+import { ExtensionAPI } from './extension';
+/**
+ * GemiGo SDK Types
+ *
+ * Complete TypeScript type definitions for the GemiGo SDK API.
+ */
+export type { Platform, Capabilities, FileEntry, FileStat } from './common';
+export type { StorageAPI } from './storage';
+export type { NotifyAction, NotifyOptions, NotifyResult, NotifyAPI, NotificationActionHandler, } from './notify';
+export type { ChatMessage, ChatResponse, TranslateOptions, TranslateResult, AIAPI, } from './ai';
+export type { ClipboardContent, ClipboardChangeCallback, ClipboardAPI, } from './clipboard';
+export type { FileFilter, OpenFileOptions, SaveFileOptions, MessageOptions, DialogAPI, FileDropCallback, FileDropHandler, } from './dialog';
+export type { MkdirOptions, FileAPI } from './file';
+export type { HttpMethod, ResponseType, RequestOptions, RequestResponse, NetworkAPI, } from './network';
+export type { SchedulerConfig, SchedulerResult, SchedulerAPI, FileWatchEventType, FileWatchConfig, FileWatchEvent, FileWatchAPI, FileWatchHandler, ShellAPI, GlobalShortcutAPI, AutostartAPI, } from './desktop';
+export type { PageInfo, ElementInfo, ArticleContent, LinkInfo, ImageInfo, HighlightOptions, WidgetPosition, WidgetConfig, WidgetHandle, CaptureFullOptions, ContextMenuEvent, ContextMenuEventResult, CaptureResult, ExtensionAPI, } from './extension';
+export type { AppType, PlatformType, PermissionType, FileScope, ContextMenuContext, ContextMenuItem, SelectionAction, SidePanelConfig, UIConfig, BackgroundCapability, BackgroundConfig, FileConfig, ExtensionConfig, AppManifest, } from './manifest';
+/**
+ * Complete GemiGo SDK interface
+ *
+ * Available APIs depend on the current platform:
+ * - `web`: Common APIs only
+ * - `desktop`: Common + Desktop APIs
+ * - `extension`: Common + Extension APIs
+ */
+export interface GemigoSDK {
+    /** Current platform: 'web' | 'desktop' | 'extension' */
+    readonly platform: Platform;
+    /** Available capabilities for current environment */
+    readonly capabilities: Capabilities;
+    /** Persistent key-value storage */
+    storage: StorageAPI;
+    /**
+     * Send system notification
+     * @param options - Notification options
+     */
+    notify(options: NotifyOptions): Promise<NotifyResult>;
+    /**
+     * Listen for notification action button clicks
+     * @param actionId - Action ID from notification
+     * @param callback - Handler function
+     * @returns Unsubscribe function
+     */
+    onNotificationAction(actionId: string, callback: () => void): () => void;
+    /** AI/LLM integration */
+    ai: AIAPI;
+    /** Clipboard access */
+    clipboard: ClipboardAPI;
+    /** File/folder dialogs */
+    dialog: DialogAPI;
+    /**
+     * Listen for files dropped onto the app
+     * @param callback - Drop handler
+     * @returns Unsubscribe function
+     */
+    onFileDrop(callback: (files: FileEntry[]) => void): () => void;
+    /** File system operations */
+    file: FileAPI;
+    /** Cross-origin HTTP requests */
+    network: NetworkAPI;
+    /** Background scheduled tasks */
+    scheduler?: SchedulerAPI;
+    /** File system change monitoring */
+    fileWatch?: FileWatchAPI;
+    /**
+     * Listen for file watch events
+     * @param callbackId - Callback ID from registration
+     * @param handler - Event handler
+     */
+    onFileWatch?(callbackId: string, handler: (event: FileWatchEvent) => void): void;
+    /** System shell integration */
+    shell?: ShellAPI;
+    /** Global keyboard shortcuts */
+    globalShortcut?: GlobalShortcutAPI;
+    /** Auto-start on system boot */
+    autostart?: AutostartAPI;
+    /** Browser extension page interaction */
+    extension?: ExtensionAPI;
+}

package/dist/types/manifest.d.ts

@@ -0,0 +1,87 @@
+/**
+ * App Manifest types
+ */
+/** Application type */
+export type AppType = 'ui' | 'hybrid' | 'service';
+/** Platform type */
+export type PlatformType = 'web' | 'desktop' | 'extension';
+/** Permission types */
+export type PermissionType = 'storage' | 'notify' | 'scheduler' | 'fileWatch' | 'fileWrite' | 'ai' | 'clipboard' | 'shell' | 'network' | 'extension.modify' | 'extension.capture' | 'extension.shortcuts';
+/** File scope paths */
+export type FileScope = '$DOWNLOAD' | '$DOCUMENT' | '$PICTURE' | '$DESKTOP' | '$APP_DATA' | '$TEMP';
+/** Context menu context types */
+export type ContextMenuContext = 'selection' | 'page' | 'image';
+/** Context menu item configuration */
+export interface ContextMenuItem {
+    id: string;
+    title: string;
+    contexts: ContextMenuContext[];
+}
+/** Selection action configuration */
+export interface SelectionAction {
+    id: string;
+    label: string;
+    icon?: string;
+}
+/** Side panel configuration */
+export interface SidePanelConfig {
+    enabled: boolean;
+    icon?: string;
+    title?: string;
+}
+/** UI entry points */
+export interface UIConfig {
+    /** Main UI HTML file */
+    main: string;
+    /** Settings UI HTML file (for hybrid/service apps) */
+    settings?: string;
+}
+/** Background capabilities */
+export type BackgroundCapability = 'scheduler' | 'fileWatch';
+/** Background configuration */
+export interface BackgroundConfig {
+    enabled: boolean;
+    capabilities?: BackgroundCapability[];
+}
+/** File permission configuration */
+export interface FileConfig {
+    scope?: FileScope[];
+}
+/** Extension-specific configuration */
+export interface ExtensionConfig {
+    sidePanel?: SidePanelConfig;
+    contextMenu?: ContextMenuItem[];
+    selectionAction?: SelectionAction;
+}
+/**
+ * Application manifest definition
+ * The manifest.json file that configures app metadata and permissions
+ */
+export interface AppManifest {
+    /** App name (required) */
+    name: string;
+    /** Version string (required) */
+    version: string;
+    /** App description (required) */
+    description: string;
+    /** App icon relative path (required) */
+    icon: string;
+    /** Author name */
+    author?: string;
+    /** App type (default: 'ui') */
+    type?: AppType;
+    /** Supported platforms */
+    platforms?: PlatformType[];
+    /** Required permissions */
+    permissions?: PermissionType[];
+    /** UI entry configuration */
+    ui?: UIConfig;
+    /** Installation script */
+    onInstall?: string;
+    /** File permission scopes */
+    file?: FileConfig;
+    /** Background task configuration */
+    background?: BackgroundConfig;
+    /** Browser extension configuration */
+    extension?: ExtensionConfig;
+}