onin-sdk 1.3.0

package/dist/core/adapters/base.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 窗口适配器基础接口
+ *
+ * 定义了处理窗口事件的统一接口，具体实现由 InlineAdapter 和 WindowAdapter 提供。
+ *
+ * @module core/adapters/base
+ */
+export type EventCallback = () => void | Promise<void>;
+/**
+ * 窗口适配器接口
+ *
+ * 定义了窗口事件监听的统一 API，不同运行模式有不同的实现：
+ * - InlineAdapter: 使用 postMessage 和 visibilitychange
+ * - WindowAdapter: 使用 Tauri 事件系统
+ */
+export interface WindowAdapter {
+    /**
+     * 监听窗口显示事件
+     */
+    onShow(callback: EventCallback): void;
+    /**
+     * 监听窗口隐藏事件
+     */
+    onHide(callback: EventCallback): void;
+    /**
+     * 监听窗口获得焦点事件
+     */
+    onFocus(callback: EventCallback): void;
+    /**
+     * 监听窗口失去焦点事件
+     */
+    onBlur(callback: EventCallback): void;
+    /**
+     * 销毁适配器（清理事件监听器）
+     */
+    destroy(): void;
+}
+/**
+ * 适配器基类 - 提供回调管理的通用逻辑
+ */
+export declare abstract class BaseAdapter implements WindowAdapter {
+    protected showCallbacks: EventCallback[];
+    protected hideCallbacks: EventCallback[];
+    protected focusCallbacks: EventCallback[];
+    protected blurCallbacks: EventCallback[];
+    protected initialized: boolean;
+    protected isVisible: boolean;
+    protected isFocused: boolean;
+    protected static readonly DEBOUNCE_MS = 100;
+    protected lastShowTime: number;
+    protected lastHideTime: number;
+    protected lastFocusTime: number;
+    protected lastBlurTime: number;
+    /**
+     * 获取带时间戳的日志前缀
+     */
+    protected log(msg: string): void;
+    onShow(callback: EventCallback): void;
+    onHide(callback: EventCallback): void;
+    onFocus(callback: EventCallback): void;
+    onBlur(callback: EventCallback): void;
+    protected ensureInitialized(): void;
+    protected abstract initialize(): void;
+    destroy(): void;
+    /**
+     * 执行显示回调（带防抖和状态检查）
+     */
+    protected executeShowCallbacks(): Promise<void>;
+    /**
+     * 执行隐藏回调（带防抖和状态检查）
+     */
+    protected executeHideCallbacks(): Promise<void>;
+    protected executeFocusCallbacks(): Promise<void>;
+    protected executeBlurCallbacks(): Promise<void>;
+}

package/dist/core/adapters/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 适配器模块导出
+ *
+ * @module core/adapters
+ */
+export type { WindowAdapter, EventCallback } from './base';
+export { BaseAdapter } from './base';
+export { InlineAdapter } from './inline';
+export { WindowModeAdapter } from './window';
+export { PostMessageAdapter } from './postmessage';

package/dist/core/adapters/inline.d.ts

@@ -0,0 +1,17 @@
+import { BaseAdapter } from './base';
+/**
+ * 内联模式（iframe）窗口适配器
+ */
+export declare class InlineAdapter extends BaseAdapter {
+    private messageHandler;
+    private visibilityHandler;
+    private focusHandler;
+    private blurHandler;
+    initialize(): void;
+    /**
+     * 设置 fallback 事件监听
+     * 当 postMessage 不可用时，使用浏览器原生事件
+     */
+    private setupFallbackEvents;
+    destroy(): void;
+}

package/dist/core/adapters/postmessage.d.ts

@@ -0,0 +1,47 @@
+import { BaseAdapter } from './base';
+/**
+ * 运行时信息
+ */
+interface RuntimeInfo {
+    mode: 'inline' | 'window';
+    pluginId: string;
+    version: string;
+    mainWindowLabel: string;
+}
+/**
+ * 统一 PostMessage 适配器
+ */
+export declare class PostMessageAdapter extends BaseAdapter {
+    private messageHandler;
+    private runtimeResolve;
+    private runtimePromise;
+    private _runtime;
+    constructor();
+    /**
+     * 立即初始化
+     */
+    private initializeNow;
+    /**
+     * 尝试从 URL 参数设置运行时信息（作为 fallback）
+     */
+    private trySetRuntimeFromUrl;
+    /**
+     * 获取运行时信息（异步）
+     */
+    getRuntime(): Promise<RuntimeInfo>;
+    /**
+     * 获取运行时信息（同步，可能返回 null）
+     */
+    getRuntimeSync(): RuntimeInfo | null;
+    protected initialize(): void;
+    /**
+     * 处理运行时初始化
+     */
+    private handleRuntimeInit;
+    /**
+     * 处理生命周期事件
+     */
+    private handleLifecycleEvent;
+    destroy(): void;
+}
+export {};

package/dist/core/adapters/window.d.ts

@@ -0,0 +1,37 @@
+import { BaseAdapter } from './base';
+/**
+ * 窗口模式适配器
+ * 使用 Tauri 事件系统监听窗口事件
+ */
+export declare class WindowModeAdapter extends BaseAdapter {
+    private unlistenVisibility;
+    private unlistenFocus;
+    private unlistenBlur;
+    private tauriEventsActive;
+    initialize(): void;
+    /**
+     * 重置状态为未知，这样第一个事件会被正确处理
+     */
+    private resetStateToUnknown;
+    /**
+     * 尝试监听 Tauri 事件（带重试机制）
+     */
+    private tryListenTauriEvents;
+    /**
+     * 处理 focus 事件
+     */
+    private handleFocusEvent;
+    /**
+     * 处理 blur 事件
+     */
+    private handleBlurEvent;
+    /**
+     * 处理 show 事件
+     */
+    private handleShowEvent;
+    /**
+     * 处理 hide 事件
+     */
+    private handleHideEvent;
+    destroy(): void;
+}

package/dist/core/dispatch.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Defines handler function signatures for different environments
+ * @interface Handlers
+ * @typeParam T - The return type of the handlers
+ * @since 0.1.0
+ * @group Core
+ */
+export interface Handlers<T> {
+    webview: () => T;
+    headless: () => T;
+}
+/**
+ * Automatically selects and executes the appropriate handler function based on the current runtime environment.
+ *
+ * This function provides environment-aware execution, allowing the same code to work seamlessly
+ * in both webview (UI) and headless (background) environments. It automatically detects the
+ * current runtime and calls the appropriate handler.
+ *
+ * @typeParam T - The return type of the handler functions
+ * @param handlers - An object containing implementations for both webview and headless environments
+ * @returns The execution result of the selected handler function
+ * @throws {Error} If the environment is neither webview nor headless
+ * @example
+ * ```typescript
+ * // Different behavior for different environments
+ * const result = dispatch({
+ *   webview: () => {
+ *     // Code that runs in UI environment
+ *     return window.someWebAPICall();
+ *   },
+ *   headless: () => {
+ *     // Code that runs in background environment
+ *     return Deno.env.get('SOME_VALUE');
+ *   }
+ * });
+ *
+ * // API calls that work in both environments
+ * await dispatch({
+ *   webview: () => invoke('some_command', args),
+ *   headless: () => invoke('some_command', args)
+ * });
+ * ```
+ * @since 0.1.0
+ * @group Core
+ */
+export declare function dispatch<T>(handlers: Handlers<T>): T;

package/dist/core/environment.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Runtime environment detection module
+ * @fileoverview Used to identify whether the current SDK is running in a Headless (Deno) environment or Webview (HTML) environment
+ */
+/**
+ * Supported runtime environment enumeration
+ * @enum {string}
+ */
+export declare enum RuntimeEnvironment {
+    Headless = "headless",/** Headless Deno environment */
+    Webview = "webview",/** Webview environment with UI */
+    Iframe = "iframe",/** Iframe environment (plugin in iframe) */
+    Unknown = "unknown"
+}
+/**
+ * Gets the current runtime environment.
+ *
+ * Determines the current code's runtime environment by checking global objects and runtime characteristics.
+ * - If `window.__TAURI_INTERNALS__` object exists, it's considered a Webview environment
+ * - If running in an iframe (window.self !== window.top), it's considered an Iframe environment
+ * - If `Deno.core` exists, it's considered a Headless environment (including plugin runtime)
+ * - Otherwise, it's considered an unknown environment.
+ *
+ * @returns The current runtime environment
+ */
+export declare function getEnvironment(): RuntimeEnvironment;

package/dist/core/ipc.d.ts

@@ -0,0 +1,66 @@
+import { EventName, EventCallback, UnlistenFn } from '@tauri-apps/api/event';
+/**
+ * Cross-environment invoke function for calling Tauri commands
+ *
+ * Provides a unified interface for invoking Tauri commands that works seamlessly
+ * in both webview and headless environments. Automatically handles environment
+ * detection and uses the appropriate underlying implementation.
+ *
+ * @typeParam T - The expected return type
+ * @param method - The method name to invoke
+ * @param arg - Arguments to pass to the method
+ * @returns Promise resolving to the method result
+ * @throws {Error} When the method call fails or returns an error
+ * @example
+ * ```typescript
+ * // Simple method call
+ * const result = await invoke('get_app_version');
+ *
+ * // Method call with arguments
+ * const response = await invoke<UserData>('get_user_data', { userId: 123 });
+ *
+ * // Error handling
+ * try {
+ *   const data = await invoke('risky_operation', { param: 'value' });
+ *   console.log('Success:', data);
+ * } catch (error) {
+ *   console.error('Operation failed:', error.message);
+ * }
+ * ```
+ * @since 0.1.0
+ * @group Core
+ */
+export declare function invoke<T>(method: string, arg: any): Promise<T>;
+/**
+ * Cross-environment event listener for Tauri events
+ *
+ * Provides a unified interface for listening to Tauri events that works in both
+ * webview and headless environments. In webview mode, it uses the standard Tauri
+ * event system. In headless mode, it provides limited event support for specific
+ * plugin-related events.
+ *
+ * @typeParam T - The event payload type
+ * @param event - The event name to listen for
+ * @param handler - The event handler function
+ * @returns Promise resolving to an unlisten function
+ * @throws {Error} When event listening setup fails
+ * @example
+ * ```typescript
+ * // Listen for custom events
+ * const unlisten = await listen<string>('my-event', (event) => {
+ *   console.log('Received event:', event.payload);
+ * });
+ *
+ * // Listen for plugin command execution (special case)
+ * await listen('plugin_command_execute', async (event) => {
+ *   const { command, args } = event.payload;
+ *   console.log(`Executing command: ${command}`, args);
+ * });
+ *
+ * // Clean up listener when done
+ * unlisten();
+ * ```
+ * @since 0.1.0
+ * @group Core
+ */
+export declare function listen<T>(event: EventName, handler: EventCallback<T>): Promise<UnlistenFn>;

package/dist/core/runtime.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 插件运行时环境模块
+ *
+ * 提供统一的运行时环境检测，通过主应用注入的 __ONIN_RUNTIME__ 对象
+ * 来判断插件的运行模式，而不是使用不可靠的 iframe 检测方法。
+ *
+ * @module core/runtime
+ */
+/**
+ * 插件运行模式
+ */
+export type PluginMode = 'inline' | 'window';
+/**
+ * 运行时环境信息接口
+ */
+export interface OninRuntime {
+    /** 插件运行模式：inline（iframe 内联）或 window（独立窗口） */
+    mode: PluginMode;
+    /** 插件 ID */
+    pluginId: string;
+    /** 插件版本 */
+    version: string;
+    /** 主窗口标签 */
+    mainWindowLabel: string;
+}
+declare global {
+    interface Window {
+        __ONIN_RUNTIME__?: OninRuntime;
+    }
+}
+/**
+ * 获取运行时环境信息
+ *
+ * 优先从 window.__ONIN_RUNTIME__ 读取主应用注入的信息，
+ * 如果不存在则根据环境自动检测。
+ */
+export declare function getRuntime(): OninRuntime;
+/**
+ * 重置运行时缓存（用于测试）
+ * @internal
+ */
+export declare function _resetRuntimeCache(): void;
+/**
+ * 当前运行时环境信息
+ * 注意：这是延迟计算的 getter，不是立即执行的
+ */
+export declare const runtime: {
+    readonly mode: PluginMode;
+    readonly pluginId: string;
+    readonly version: string;
+    readonly mainWindowLabel: string;
+};
+/**
+ * 是否为内联模式（iframe）
+ */
+export declare function isInlineMode(): boolean;
+/**
+ * 是否为窗口模式（独立窗口）
+ */
+export declare function isWindowMode(): boolean;
+/**
+ * 获取当前插件 ID
+ */
+export declare function getPluginId(): string;

package/dist/event-DiwgtsjL.js

@@ -0,0 +1,29 @@
+function d(r, n = !1) {
+  return window.__TAURI_INTERNALS__.transformCallback(r, n);
+}
+async function t(r, n = {}, e) {
+  return window.__TAURI_INTERNALS__.invoke(r, n, e);
+}
+var _;
+(function(r) {
+  r.WINDOW_RESIZED = "tauri://resize", r.WINDOW_MOVED = "tauri://move", r.WINDOW_CLOSE_REQUESTED = "tauri://close-requested", r.WINDOW_DESTROYED = "tauri://destroyed", r.WINDOW_FOCUS = "tauri://focus", r.WINDOW_BLUR = "tauri://blur", r.WINDOW_SCALE_FACTOR_CHANGED = "tauri://scale-change", r.WINDOW_THEME_CHANGED = "tauri://theme-changed", r.WINDOW_CREATED = "tauri://window-created", r.WEBVIEW_CREATED = "tauri://webview-created", r.DRAG_ENTER = "tauri://drag-enter", r.DRAG_OVER = "tauri://drag-over", r.DRAG_DROP = "tauri://drag-drop", r.DRAG_LEAVE = "tauri://drag-leave";
+})(_ || (_ = {}));
+async function l(r, n) {
+  window.__TAURI_EVENT_PLUGIN_INTERNALS__.unregisterListener(r, n), await t("plugin:event|unlisten", {
+    event: r,
+    eventId: n
+  });
+}
+async function s(r, n, e) {
+  var a;
+  const u = typeof (e == null ? void 0 : e.target) == "string" ? { kind: "AnyLabel", label: e.target } : (a = e == null ? void 0 : e.target) !== null && a !== void 0 ? a : { kind: "Any" };
+  return t("plugin:event|listen", {
+    event: r,
+    target: u,
+    handler: d(n)
+  }).then((i) => async () => l(r, i));
+}
+export {
+  _ as TauriEvent,
+  s as listen
+};

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import { http } from './api/request';
+import { storage } from './api/storage';
+import { notification } from './api/notification';
+import { command } from './api/command';
+import { fs } from './api/fs';
+import { dialog } from './api/dialog';
+import { clipboard } from './api/clipboard';
+import { settings } from './api/settings';
+import { lifecycle } from './api/lifecycle';
+import { scheduler } from './api/scheduler';
+import { pluginWindow } from './api/window';
+import { ai } from './api/ai';
+import { invoke, listen } from './core/ipc';
+import { debug } from './utils/debug';
+import * as error from './types/errors';
+import * as retry from './utils/retry';
+import type * as Permissions from './types/permissions';
+import type * as Errors from './types/errors';
+import type * as Retry from './utils/retry';
+import type * as Fs from './api/fs';
+import type * as Dialog from './api/dialog';
+import type * as Settings from './api/settings';
+/**
+ * Contains all available type definitions for the SDK
+ *
+ * Provides access to TypeScript type definitions for all SDK components.
+ * Use these types for better type safety and IDE support when working with
+ * the SDK APIs.
+ *
+ * @namespace types
+ * @version 0.1.0
+ * @since 0.1.0
+ * @group Types
+ * @example
+ * ```typescript
+ * import { types } from 'onin-plugin-sdk';
+ *
+ * // Use error types
+ * function handleError(error: types.Errors.PluginError) {
+ *   console.log('Error code:', error.code);
+ * }
+ *
+ * // Use file system types
+ * function processFile(info: types.Fs.FileInfo) {
+ *   console.log('File size:', info.size);
+ * }
+ *
+ * // Use dialog types
+ * const filters: types.Dialog.DialogFilter[] = [
+ *   { name: 'Text Files', extensions: ['txt', 'md'] }
+ * ];
+ * ```
+ */
+declare const types: {
+    Permissions: typeof Permissions;
+    Errors: typeof Errors;
+    Retry: typeof Retry;
+    Fs: typeof Fs;
+    Dialog: typeof Dialog;
+    Settings: typeof Settings;
+};
+export { http, storage, notification, command, fs, dialog, clipboard, settings, lifecycle, scheduler, pluginWindow, ai, invoke, listen, debug, error, retry, types, };
+export type { SettingField, TextSettingField, PasswordSettingField, TextareaSettingField, NumberSettingField, ColorSettingField, DateSettingField, TimeSettingField, DatetimeSettingField, SliderSettingField, SwitchSettingField, RadioSettingField, SelectSettingField, MultiSelectSettingField, ButtonSettingField, SettingOption, JsonValue, SettingsValues, SettingSchemaDesc, } from './api/settings';
+export type { PluginError, ErrorCode } from './types/errors';
+export type { FileInfo } from './api/fs';
+export type { DialogFilter, OpenDialogOptions, SaveDialogOptions, } from './api/dialog';
+export type { ClipboardMetadata, ClipboardContentType, ClipboardFile, } from './api/clipboard';