@gemigo/app-sdk 0.2.5

package/dist/types/extension.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Browser Extension API types
+ *
+ * These APIs are only available when `gemigo.platform === 'extension'`.
+ *
+ * Note: This file defines the v1 "stable surface" used by the current Host/SW
+ * implementation. Future APIs are kept as optional to avoid blocking v1.
+ */
+export interface PageInfo {
+    url: string;
+    title: string;
+    favIconUrl?: string;
+}
+export interface SelectionRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface SelectionResult {
+    text: string;
+    rect: SelectionRect | null;
+}
+export interface ElementInfo {
+    tagName: string;
+    text: string;
+    attributes: Record<string, string>;
+}
+export interface ArticleContent {
+    title: string;
+    content: string;
+    excerpt?: string;
+    url?: string;
+}
+export interface LinkInfo {
+    href: string;
+    text: string;
+    title?: string;
+}
+export interface ImageInfo {
+    src: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+}
+export interface HighlightOptions {
+    color?: string;
+    duration?: number;
+}
+export interface WidgetPosition {
+    x: number;
+    y: number;
+}
+export interface WidgetConfig {
+    html: string;
+    position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | WidgetPosition;
+}
+export interface WidgetHandle {
+    remove(): void;
+    update(html: string): void;
+}
+export interface CaptureFullOptions {
+    maxHeight?: number;
+}
+export interface ContextMenuEvent {
+    menuId: string;
+    selectionText?: string;
+    pageUrl?: string;
+}
+export interface ContextMenuEventResult {
+    success: boolean;
+    event?: ContextMenuEvent;
+}
+export interface CaptureResult {
+    success: boolean;
+    dataUrl?: string;
+    error?: string;
+}
+export interface HighlightResult {
+    success: boolean;
+    count?: number;
+    highlightId?: string;
+    error?: string;
+}
+export interface WidgetResult {
+    success: boolean;
+    widgetId?: string;
+    error?: string;
+}
+export interface CSSResult {
+    success: boolean;
+    styleId?: string;
+    error?: string;
+}
+export interface ExtractArticleResult {
+    success: boolean;
+    title?: string;
+    content?: string;
+    excerpt?: string;
+    url?: string;
+    error?: string;
+}
+export interface ExtractLinksResult {
+    success: boolean;
+    links?: LinkInfo[];
+    error?: string;
+}
+export interface ExtractImagesResult {
+    success: boolean;
+    images?: ImageInfo[];
+    error?: string;
+}
+export interface QueryElementResult {
+    success: boolean;
+    elements?: ElementInfo[];
+    count?: number;
+    error?: string;
+}
+/**
+ * Extension RPC Methods - shared between SDK and Host
+ *
+ * These methods are the actual RPC calls to the extension host.
+ * HostMethods extends this interface.
+ */
+export interface ExtensionRPCMethods {
+    getPageInfo(): Promise<PageInfo | null>;
+    getPageHTML(): Promise<string>;
+    getPageText(): Promise<string>;
+    getSelection(): Promise<SelectionResult>;
+    extractArticle(): Promise<ExtractArticleResult>;
+    extractLinks(): Promise<ExtractLinksResult>;
+    extractImages(): Promise<ExtractImagesResult>;
+    queryElement(selector: string, limit?: number): Promise<QueryElementResult>;
+    highlight(selector: string, color?: string): Promise<HighlightResult>;
+    removeHighlight(highlightId: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    insertWidget(html: string, position?: string | WidgetPosition): Promise<WidgetResult>;
+    updateWidget(widgetId: string, html: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    removeWidget(widgetId: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    injectCSS(css: string): Promise<CSSResult>;
+    removeCSS(styleId: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    captureVisible(): Promise<CaptureResult>;
+    getContextMenuEvent(): Promise<ContextMenuEventResult>;
+}
+/**
+ * Full Extension API - includes RPC methods + local event handlers
+ */
+export interface ExtensionAPI extends ExtensionRPCMethods {
+    onContextMenu(callback: (event: ContextMenuEvent) => void): () => void;
+    onSelectionChange(handler: (text: string, rect: SelectionRect | null, url?: string) => void): () => void;
+    onSelectionAction?: (actionId: string, callback: () => void) => () => void;
+    onNavigate?: (callback: (url: string) => void) => () => void;
+    onScroll?: (callback: (scrollY: number) => void) => () => void;
+    captureFull?: (options?: CaptureFullOptions) => Promise<CaptureResult>;
+    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,91 @@
+import { Platform, Capabilities, SDKError, 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, RPCResult, RPCResultWithData, SDKErrorCode, } from './common';
+export { SDKError } from './common';
+export type { StorageAPI } from './storage';
+export type { NotifyAction, NotifyOptions, NotifyResult, NotifyFn, 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, SelectionRect, SelectionResult, ElementInfo, ArticleContent, LinkInfo, ImageInfo, HighlightOptions, WidgetPosition, WidgetConfig, WidgetHandle, CaptureFullOptions, ContextMenuEvent, ContextMenuEventResult, CaptureResult, HighlightResult, WidgetResult, CSSResult, ExtractArticleResult, ExtractLinksResult, ExtractImagesResult, QueryElementResult, ExtensionRPCMethods, 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;
+    /** SDK Error class for error handling and instanceof checks */
+    readonly SDKError: typeof SDKError;
+    /** 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;
+}

package/dist/types/network.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Network API types
+ */
+/** HTTP request method */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+/** Response type */
+export type ResponseType = 'json' | 'text' | 'arraybuffer';
+/** Request options */
+export interface RequestOptions {
+    /** HTTP method */
+    method?: HttpMethod;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body */
+    body?: string | object;
+    /** Response type */
+    responseType?: ResponseType;
+}
+/** Request response */
+export interface RequestResponse<T = unknown> {
+    /** HTTP status code */
+    status: number;
+    /** Response data */
+    data: T;
+    /** Response headers */
+    headers: Record<string, string>;
+}
+/** Network API for cross-origin HTTP requests */
+export interface NetworkAPI {
+    /**
+     * Make an HTTP request (bypasses CORS restrictions)
+     * @param url - Request URL
+     * @param options - Request options
+     * @returns Response with status, data, and headers
+     */
+    request<T = unknown>(url: string, options?: RequestOptions): Promise<RequestResponse<T>>;
+}

package/dist/types/notify.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Notify API types
+ */
+/** Notification action button */
+export interface NotifyAction {
+    id: string;
+    label: string;
+}
+/** Notification options */
+export interface NotifyOptions {
+    /** Notification title (required) */
+    title: string;
+    /** Notification message text */
+    message?: string;
+    /** Icon URL */
+    icon?: string;
+    /** Action buttons (desktop only) */
+    actions?: NotifyAction[];
+}
+/** Notification result */
+export interface NotifyResult {
+    success: boolean;
+    reason?: string;
+}
+/** Notify function signature */
+export type NotifyFn = (options: NotifyOptions) => Promise<NotifyResult>;
+/** Notification action handler */
+export type NotificationActionHandler = (actionId: string, callback: () => void) => () => void;

package/dist/types/storage.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Storage API types
+ */
+/** Storage API for persistent key-value storage */
+export interface StorageAPI {
+    /**
+     * Get a stored value
+     * @param key - Storage key
+     * @returns The stored value or null if not found
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Store a value
+     * @param key - Storage key
+     * @param value - Value to store (will be JSON serialized)
+     */
+    set(key: string, value: unknown): Promise<void>;
+    /**
+     * Delete a stored value
+     * @param key - Storage key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all data for the current app
+     */
+    clear(): Promise<void>;
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@gemigo/app-sdk",
+  "private": false,
+  "version": "0.2.5",
+  "type": "module",
+  "description": "GemiGo App SDK (auto-adapts for web/desktop/extension)",
+  "main": "dist/gemigo-app-sdk.umd.js",
+  "module": "dist/gemigo-app-sdk.es.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "penpal": "^6.2.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "vite": "^6.2.5",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "format": "prettier --write .",
+    "lint": "eslint ."
+  }
+}