@wox-launcher/wox-plugin 0.0.107 → 0.0.111

package/README.md

@@ -1 +1,208 @@
-Nodejs Type Definition for Wox Plugin
+# Wox Plugin SDK for TypeScript/JavaScript
+
+TypeScript type definitions and SDK for developing Wox plugins in TypeScript/JavaScript.
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install wox-plugin
+```
+
+### Basic Plugin
+
+```typescript
+import { Plugin, Context, Query, Result, NewContext, WoxImage } from "wox-plugin"
+
+class MyPlugin implements Plugin {
+  private api: PublicAPI
+
+  async init(ctx: Context, initParams: PluginInitParams): Promise<void> {
+    this.api = initParams.API
+    await this.api.Log(ctx, "Info", "MyPlugin initialized")
+  }
+
+  async query(ctx: Context, query: Query): Promise<Result[]> {
+    const results: Result[] = []
+
+    for (const item of this.getItems(query.Search)) {
+      results.push({
+        Title: item.name,
+        SubTitle: item.description,
+        Icon: { ImageType: "emoji", ImageData: "🔍" },
+        Score: 100,
+        Actions: [
+          {
+            Name: "Open",
+            Icon: { ImageType: "emoji", ImageData: "🔗" },
+            IsDefault: true,
+            Action: async (ctx, actionCtx) => {
+              await this.openItem(item)
+            }
+          }
+        ]
+      })
+    }
+
+    return results
+  }
+}
+```
+
+## Key Components
+
+### Plugin Interface
+
+Every plugin must implement the `Plugin` interface:
+
+```typescript
+interface Plugin {
+  init: (ctx: Context, initParams: PluginInitParams) => Promise<void>
+  query: (ctx: Context, query: Query) => Promise<Result[]>
+}
+```
+
+### Query Models
+
+- **Query**: User query with search text, type, selection, environment
+- **QueryType**: `INPUT` (typing) or `SELECTION` (selected content)
+- **Selection**: Text or file paths selected by user
+- **QueryEnv**: Environment context (active window, browser URL)
+
+### Result Models
+
+- **Result**: Search result with title, icon, preview, actions
+- **ResultAction**: User action on a result
+- **ResultActionType**: `EXECUTE` (immediate) or `FORM` (show form)
+- **ResultTail**: Additional visual elements (text or image)
+- **UpdatableResult**: Result that can be updated in UI
+
+### Image Types
+
+Supported image types:
+
+- `absolute`: Absolute file path
+- `relative`: Path relative to plugin directory
+- `base64`: Base64 encoded image with data URI prefix (`data:image/png;base64,...`)
+- `svg`: SVG string content
+- `url`: HTTP/HTTPS URL
+- `emoji`: Emoji character
+- `lottie`: Lottie animation JSON
+
+```typescript
+// Emoji icon
+{ ImageType: "emoji", ImageData: "🔍" }
+
+// Base64 image
+{ ImageType: "base64", ImageData: "data:image/png;base64,iVBORw0..." }
+
+// Relative path
+{ ImageType: "relative", ImageData: "./icons/icon.png" }
+```
+
+### Public API
+
+Methods for interacting with Wox:
+
+- **UI Control**: `showApp()`, `hideApp()`, `isVisible()`, `notify()`
+- **Query**: `changeQuery()`, `refreshQuery()`, `pushResults()`
+- **Settings**: `getSetting()`, `saveSetting()`, `onSettingChanged()`
+- **Logging**: `log()`
+- **i18n**: `getTranslation()`
+- **Results**: `getUpdatableResult()`, `updateResult()`
+- **AI**: `llmStream()`
+- **MRU**: `onMruRestore()`
+- **Callbacks**: `onUnload()`, `onDeepLink()`
+- **Commands**: `registerQueryCommands()`
+- **Clipboard**: `copy()`
+
+## Actions
+
+Actions are operations users can perform on results:
+
+```typescript
+ResultAction({
+  name: "Copy",
+  icon: { ImageType: "emoji", ImageData: "📋" },
+  isDefault: true,
+  hotkey: "Ctrl+C",
+  action: async (ctx, actionCtx) => {
+    await this.copyToClipboard(actionCtx.contextData)
+  }
+})
+```
+
+## Settings
+
+Define settings for your plugin:
+
+```typescript
+const settings: PluginSettingDefinitionItem[] = [
+  createTextboxSetting({
+    key: "apiKey",
+    label: "API Key",
+    tooltip: "Enter your API key",
+    defaultValue: ""
+  }),
+  createCheckboxSetting({
+    key: "enabled",
+    label: "Enable Feature",
+    defaultValue: "true"
+  })
+]
+```
+
+## AI/LLM Integration
+
+Stream responses from AI models:
+
+```typescript
+const conversations: AI.Conversation[] = [
+  { Role: "system", Text: "You are a helpful assistant.", Timestamp: Date.now() },
+  { Role: "user", Text: "Hello!", Timestamp: Date.now() }
+]
+
+await api.LLMStream(ctx, conversations, (data: AI.ChatStreamData) => {
+  if (data.Status === "streaming") {
+    console.log("Chunk:", data.Data)
+  } else if (data.Status === "finished") {
+    console.log("Complete:", data.Data)
+  }
+})
+```
+
+## Plugin Metadata
+
+Plugins must declare metadata in a `plugin.json` file:
+
+```json
+{
+  "ID": "com.myplugin.example",
+  "Name": "My Plugin",
+  "Author": "Your Name",
+  "Version": "1.0.0",
+  "MinWoxVersion": "2.0.0",
+  "Runtime": "nodejs",
+  "Entry": "main.js",
+  "TriggerKeywords": ["my"],
+  "Description": "My awesome Wox plugin",
+  "Website": "https://github.com/user/myplugin",
+  "Icon": "https://example.com/icon.png"
+}
+```
+
+## Query Flow
+
+1. User triggers Wox and types trigger keyword (e.g., "my query")
+2. Wox calls `plugin.query()` with:
+   - `query.triggerKeyword = "my"`
+   - `query.command = ""`
+   - `query.search = "query"`
+3. Plugin returns `Result[]`
+4. Wox displays results sorted by score
+
+## For More Information
+
+- Wox Documentation: https://github.com/Wox-launcher/Wox
+- Plugin Examples: https://github.com/Wox-launcher/Wox.Plugin.Nodejs

package/dist/context.js

@@ -1,3 +1,17 @@
+/**
+ * Create a new context with auto-generated trace ID.
+ *
+ * The context is used throughout the plugin API for request tracking
+ * and passing custom data between function calls.
+ *
+ * @returns A new Context instance with a UUID in the "traceId" key
+ *
+ * @example
+ * ```typescript
+ * const ctx = NewContext()
+ * console.log(ctx.Get("traceId"))  // e.g., "550e8400-e29b-41d4-a716-446655440000"
+ * ```
+ */
 export function NewContext() {
     return {
         Values: {
@@ -14,6 +28,23 @@ export function NewContext() {
         }
     };
 }
+/**
+ * Create a new context with an initial key-value pair.
+ *
+ * In addition to the auto-generated trace ID, this function
+ * initializes the context with a custom key-value pair.
+ *
+ * @param key - The key to set
+ * @param value - The value to store
+ * @returns A new Context instance with the trace ID and custom value
+ *
+ * @example
+ * ```typescript
+ * const ctx = NewContextWithValue("userId", "12345")
+ * console.log(ctx.Get("userId"))   // "12345"
+ * console.log(ctx.Get("traceId"))  // auto-generated UUID
+ * ```
+ */
 export function NewContextWithValue(key, value) {
     const ctx = NewContext();
     ctx.Set(key, value);

package/dist/image.js

@@ -1,3 +1,24 @@
+/**
+ * Create a base64 WoxImage from image data.
+ *
+ * This helper function creates a WoxImage with type "base64".
+ * The image data must include the data URI prefix.
+ *
+ * @param imageData - Base64 image data with data URI prefix (e.g., "data:image/png;base64,...")
+ * @returns A WoxImage with type "base64"
+ *
+ * @example
+ * ```typescript
+ * const pngData = "data:image/png;base64,iVBORw0KGgoAAAA..."
+ * const icon = NewBase64WoxImage(pngData)
+ *
+ * // Use in a result
+ * const result = {
+ *   Title: "My Result",
+ *   Icon: icon
+ * }
+ * ```
+ */
 export function NewBase64WoxImage(imageData) {
     return {
         ImageType: "base64",

package/dist/index.js

@@ -1,2 +1,22 @@
+/**
+ * Wox Plugin SDK for TypeScript/JavaScript
+ *
+ * This package provides utility functions for developing Wox plugins in TypeScript/JavaScript.
+ *
+ * @module
+ *
+ * @example
+ * ```typescript
+ * import { NewContext, NewBase64WoxImage } from "wox-plugin"
+ *
+ * // Create a new context
+ * const ctx = NewContext()
+ *
+ * // Create a base64 image
+ * const icon = NewBase64WoxImage("data:image/png;base64,...")
+ * ```
+ */
+// Re-export all context-related functions
 export * from "./context.js";
+// Re-export all image-related functions
 export * from "./image.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wox-launcher/wox-plugin",
-  "version": "0.0.107",
+  "version": "0.0.111",
   "description": "All nodejs plugin for Wox should use types in this package",
   "repository": {
     "type": "git",

package/types/ai.d.ts

@@ -1,21 +1,370 @@
+/**
+ * AI/LLM related types for streaming chat conversations.
+ *
+ * This namespace provides types for interacting with AI models through Wox's
+ * streaming chat interface. It supports conversation management, streaming
+ * responses, and tool calling capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { AI, PublicAPI } from "wox-plugin"
+ *
+ * // Prepare conversation history
+ * const conversations: AI.Conversation[] = [
+ *   { Role: "system", Text: "You are a helpful assistant.", Timestamp: Date.now() },
+ *   { Role: "user", Text: "What is the capital of France?", Timestamp: Date.now() }
+ * ]
+ *
+ * // Stream the response
+ * await api.LLMStream(ctx, conversations, (streamData) => {
+ *   if (streamData.Status === "streaming") {
+ *     console.log("Chunk:", streamData.Data)
+ *   } else if (streamData.Status === "finished") {
+ *     console.log("Complete:", streamData.Data)
+ *   }
+ * })
+ * ```
+ */
 export namespace AI {
-  export type ConversationRole = "user" | "system"
-  export type ChatStreamDataType = "streaming" | "finished" | "error"
+  /**
+   * Role of a message in a conversation.
+   *
+   * - `system`: System prompt that sets AI behavior
+   * - `user`: Message from the user
+   * - `assistant`: Response from the AI model
+   * - `tool`: Result from a tool/function call execution
+   */
+  export type ConversationRole = "user" | "system" | "assistant" | "tool"
 
+  /**
+   * Status of a streaming chat response.
+   *
+   * - `streaming`: actively receiving response chunks
+   * - `streamed`: all content received, ready to process tool calls (if any)
+   * - `running_tool_call`: executing tool calls
+   * - `finished`: all content and tool calls completed
+   * - `error`: an error occurred during streaming or tool execution
+   */
+  export type ChatStreamDataType = "streaming" | "streamed" | "running_tool_call" | "finished" | "error"
+
+  /**
+   * Status of a tool call execution.
+   *
+   * - `streaming`: tool call arguments are being streamed
+   * - `pending`: streaming finished, ready to execute
+   * - `running`: currently executing
+   * - `succeeded`: executed successfully
+   * - `failed`: execution failed
+   */
+  export type ToolCallStatus = "streaming" | "pending" | "running" | "succeeded" | "failed"
+
+  /**
+   * Represents a single message in an AI conversation.
+   *
+   * Conversations are passed to the AI model in order to maintain context
+   * across multiple turns of dialogue.
+   *
+   * @example
+   * ```typescript
+   * const systemMessage: AI.Conversation = {
+   *   Role: "system",
+   *   Text: "You are a helpful coding assistant.",
+   *   Timestamp: Date.now()
+   * }
+   *
+   * const userMessage: AI.Conversation = {
+   *   Role: "user",
+   *   Text: "How do I reverse a string in JavaScript?",
+   *   Timestamp: Date.now()
+   * }
+   * ```
+   */
   export interface Conversation {
+    /**
+     * The role of the message sender.
+     *
+     * - `system`: Sets behavior/context for the AI
+     * - `user`: Human input
+     * - `assistant`: AI response
+     * - `tool`: Result from tool execution
+     */
     Role: ConversationRole
+
+    /**
+     * The text content of the message.
+     *
+     * For system messages, this defines the AI's behavior.
+     * For user messages, this is the user's input.
+     * For assistant messages, this is the AI's response.
+     * For tool messages, this is the stringified tool result.
+     */
     Text: string
+
+    /**
+     * Reasoning content from models that support reasoning (e.g., DeepSeek, OpenAI o1, Qwen).
+     *
+     * This is the model's internal thinking process, separate from the final response.
+     * It's useful for understanding how the model arrived at its answer.
+     *
+     * Only present for assistant messages when using models that support reasoning.
+     */
+    Reasoning?: string
+
+    /**
+     * List of PNG image bytes for vision models.
+     *
+     * Only applicable for user messages when using vision-capable models.
+     * Images should be in PNG format as raw byte arrays.
+     */
+    Images?: Uint8Array[]
+
+    /**
+     * Tool call information for assistant or tool messages.
+     *
+     * - For assistant messages: describes which tool(s) the AI wants to call
+     * - For tool messages: describes the result of a tool execution
+     */
+    ToolCallInfo?: ToolCallInfo
+
+    /**
+     * Unix timestamp in milliseconds when this message was created.
+     *
+     * Used for ordering messages in the conversation history.
+     */
     Timestamp: number
   }
 
+  /**
+   * Information about a tool/function call requested by the AI model.
+   *
+   * When the AI decides to use a tool, it populates this structure with
+   * the tool name and arguments. After execution, the result is stored here.
+   *
+   * @example
+   * ```typescript
+   * const toolCall: AI.ToolCallInfo = {
+   *   Id: "call_123",
+   *   Name: "get_weather",
+   *   Arguments: { city: "London", unit: "celsius" },
+   *   Status: "running",
+   *   Delta: "",
+   *   Response: "",
+   *   StartTimestamp: Date.now(),
+   *   EndTimestamp: 0
+   * }
+   * ```
+   */
+  export interface ToolCallInfo {
+    /**
+     * Unique identifier for this tool call.
+     *
+     * Used to match tool requests with responses.
+     */
+    Id: string
+
+    /**
+     * Name of the tool/function to call.
+     *
+     * This should match a registered tool name in the Wox system.
+     */
+    Name: string
+
+    /**
+     * Arguments to pass to the tool function.
+     *
+     * Key-value pairs representing the parameters for the tool call.
+     * The schema depends on the tool's definition.
+     */
+    Arguments: Record<string, any>
+
+    /**
+     * Current status of the tool call.
+     *
+     * Progresses through: streaming -> pending -> running -> succeeded/failed
+     */
+    Status: ToolCallStatus
+
+    /**
+     * Delta content when tool call is being streamed.
+     *
+     * As the model streams the tool call arguments, partial content
+     * appears here. Once complete, Arguments contains the full data.
+     */
+    Delta: string
+
+    /**
+     * The response/result from tool execution.
+     *
+     * After the tool completes, this contains the stringified result
+     * that will be sent back to the AI model.
+     */
+    Response: string
+
+    /**
+     * Unix timestamp in milliseconds when tool execution started.
+     */
+    StartTimestamp: number
+
+    /**
+     * Unix timestamp in milliseconds when tool execution finished.
+     *
+     * Zero if the tool hasn't finished yet.
+     */
+    EndTimestamp: number
+  }
+
+  /**
+   * Data returned during a streaming chat response.
+   *
+   * As the AI model generates its response, this structure is updated
+   * with new content. It supports regular text, reasoning content,
+   * and tool calling.
+   *
+   * @example
+   * ```typescript
+   * await api.LLMStream(ctx, conversations, (data: AI.ChatStreamData) => {
+   *   switch (data.Status) {
+   *     case "streaming":
+   *       // Still receiving content
+   *       process.stdout.write(data.Data)
+   *       break
+   *     case "streamed":
+   *       // All content received, checking for tool calls
+   *       console.log("\nContent complete. Tool calls:", data.ToolCalls)
+   *       break
+   *     case "running_tool_call":
+   *       // Executing tools
+   *       data.ToolCalls.forEach(tc => {
+   *         console.log(`Running ${tc.Name}: ${tc.Status}`)
+   *       })
+   *       break
+   *     case "finished":
+   *       // Completely done
+   *       console.log("\nFinal result:", data.Data)
+   *       break
+   *     case "error":
+   *       console.error("Error:", data.Data)
+   *       break
+   *   }
+   * })
+   * ```
+   */
   export interface ChatStreamData {
-    /** Stream status */
+    /**
+     * Current status of the stream.
+     *
+     * Indicates what phase the chat is in: streaming content,
+     * executing tools, completed, or errored.
+     */
     Status: ChatStreamDataType
-    /** Aggregated content data */
+
+    /**
+     * Aggregated text content from the AI.
+     *
+     * This field accumulates content as it's streamed. For example:
+     * - Chunk 1: Data = "Hello"
+     * - Chunk 2: Data = "Hello world"
+     * - Chunk 3: Data = "Hello world!"
+     *
+     * Use this for the final complete response.
+     */
     Data: string
-    /** Reasoning content from models that support reasoning (e.g., DeepSeek, OpenAI o1). Separate from Data for clean processing. */
+
+    /**
+     * Reasoning content from models that support thinking.
+     *
+     * Models like DeepSeek-R1, OpenAI o1, and Qwen separate their
+     * internal reasoning from the final response. This field contains
+     * the model's thinking process.
+     *
+     * To display reasoning nicely, you can format it with a "> " prefix:
+     * ```typescript
+     * const reasoning = data.Reasoning
+     *   .split('\n')
+     *   .map(line => `> ${line}`)
+     *   .join('\n')
+     * ```
+     */
     Reasoning: string
+
+    /**
+     * Tool calls requested by the AI model.
+     *
+     * Populated when the model decides to use one or more tools.
+     * Each tool call includes its name, arguments, and execution status.
+     *
+     * @example
+     * ```typescript
+     * if (data.ToolCalls.length > 0) {
+     *   for (const toolCall of data.ToolCalls) {
+     *     console.log(`Tool: ${toolCall.Name}`)
+     *     console.log(`Args: ${JSON.stringify(toolCall.Arguments)}`)
+     *     console.log(`Status: ${toolCall.Status}`)
+     *   }
+     * }
+     * ```
+     */
+    ToolCalls: ToolCallInfo[]
   }
 
+  /**
+   * Callback function type for receiving streaming chat data.
+   *
+   * Passed to `PublicAPI.LLMStream()` and called repeatedly as
+   * the AI generates its response.
+   *
+   * @param streamData - The current streaming data chunk
+   *
+   * @example
+   * ```typescript
+   * const callback: AI.ChatStreamFunc = (streamData) => {
+   *   if (streamData.Status === "streaming") {
+   *     // Append to display
+   *     display.textContent = streamData.Data
+   *   }
+   * }
+   *
+   * await api.LLMStream(ctx, conversations, callback)
+   * ```
+   */
   export type ChatStreamFunc = (streamData: ChatStreamData) => void
+
+  /**
+   * Definition of an AI model (provider and model name).
+   *
+   * Used when specifying which model to use for chat completions.
+   *
+   * @example
+   * ```typescript
+   * const model: AI.AIModel = {
+   *   Provider: "openai",
+   *   ProviderAlias: "my-openai-account", // optional, for multiple configs
+   *   Name: "gpt-4"
+   * }
+   * ```
+   */
+  export interface AIModel {
+    /**
+     * The model provider name.
+     *
+     * Common values: "openai", "anthropic", "deepseek", "ollama", etc.
+     */
+    Provider: string
+
+    /**
+     * Optional provider alias.
+     *
+     * When you have multiple configurations of the same provider
+     * (e.g., two different OpenAI API keys), use this to specify
+     * which one to use. If omitted, uses the default configuration.
+     */
+    ProviderAlias?: string
+
+    /**
+     * The specific model name.
+     *
+     * Examples: "gpt-4", "claude-3-opus", "deepseek-chat", "llama3:70b"
+     */
+    Name: string
+  }
 }