@talex-touch/utils 1.0.39 → 1.0.42

package/plugin/sdk/clipboard.ts

@@ -44,67 +44,141 @@ export interface ClipboardApplyOptions {
   type?: PluginClipboardItem['type']
 }
 
+export interface ClipboardWriteOptions {
+  text?: string
+  html?: string
+  image?: string
+  files?: string[]
+}
+
+export interface ClipboardReadResult {
+  text: string
+  html: string
+  hasImage: boolean
+  hasFiles: boolean
+  formats: string[]
+}
+
+export interface ClipboardImageResult {
+  dataUrl: string
+  width: number
+  height: number
+}
+
+export interface ClipboardCopyAndPasteOptions {
+  text?: string
+  html?: string
+  image?: string
+  files?: string[]
+  delayMs?: number
+  hideCoreBox?: boolean
+}
+
 export type ClipboardSearchOptions = PluginClipboardSearchOptions
 export type ClipboardSearchResponse = PluginClipboardSearchResponse
 
+/**
+ * @deprecated Use `useClipboard()` instead. This function will be removed in a future version.
+ */
 export function useClipboardHistory() {
+  return useClipboard().history
+}
+
+/**
+ * Unified Clipboard SDK for plugin renderer context.
+ *
+ * Provides:
+ * - Basic clipboard operations (read/write) via IPC to main process
+ * - Clipboard history management
+ * - Copy and paste to active application
+ *
+ * All operations go through IPC to avoid WebContents focus issues.
+ *
+ * @example
+ * ```typescript
+ * const clipboard = useClipboard()
+ *
+ * // === Basic Operations ===
+ * await clipboard.writeText('Hello World')
+ * const content = await clipboard.read()
+ *
+ * // === Copy and Paste ===
+ * await clipboard.copyAndPaste({ text: 'Pasted content' })
+ *
+ * // === History Operations ===
+ * const latest = await clipboard.history.getLatest()
+ * const { history } = await clipboard.history.getHistory({ page: 1 })
+ *
+ * // === Listen to Changes ===
+ * // Note: Plugin must call box.allowClipboard(types) first
+ * const unsubscribe = clipboard.history.onDidChange((item) => {
+ *   console.log('Clipboard changed:', item)
+ * })
+ * ```
+ */
+export function useClipboard() {
   const channel = ensurePluginChannel()
 
-  return {
+  const history = {
+    /**
+     * Gets the most recent clipboard item
+     */
     async getLatest(): Promise<PluginClipboardItem | null> {
       const result = await channel.send('clipboard:get-latest')
       return normalizeItem(result)
     },
 
+    /**
+     * Gets clipboard history with pagination
+     */
     async getHistory(options: ClipboardHistoryOptions = {}): Promise<PluginClipboardHistoryResponse> {
       const response = await channel.send('clipboard:get-history', options)
-      const history = Array.isArray(response?.history)
+      const items = Array.isArray(response?.history)
         ? response.history.map((item: PluginClipboardItem) => normalizeItem(item) ?? item)
         : []
       return {
         ...response,
-        history,
+        history: items,
       }
     },
 
+    /**
+     * Sets favorite status for a clipboard item
+     */
     async setFavorite(options: ClipboardFavoriteOptions): Promise<void> {
       await channel.send('clipboard:set-favorite', options)
     },
 
+    /**
+     * Deletes a clipboard item from history
+     */
     async deleteItem(options: ClipboardDeleteOptions): Promise<void> {
       await channel.send('clipboard:delete-item', options)
     },
 
+    /**
+     * Clears all clipboard history
+     */
     async clearHistory(): Promise<void> {
       await channel.send('clipboard:clear-history')
     },
 
     /**
-     * Search clipboard history with advanced filtering options.
-     * Supports keyword search, time-based filtering, and combined filters.
-     *
-     * @param options - Search options
-     * @returns Search results with pagination metadata
+     * Search clipboard history with advanced filtering
      *
      * @example
      * ```typescript
      * // Search by keyword
-     * const result = await searchHistory({ keyword: 'hello' })
-     *
-     * // Search by time range (last 24 hours)
-     * const oneDayAgo = Date.now() - 24 * 60 * 60 * 1000
-     * const recent = await searchHistory({ startTime: oneDayAgo })
+     * const result = await clipboard.history.searchHistory({ keyword: 'hello' })
      *
-     * // Combined search: text type, favorite items from a specific app
-     * const filtered = await searchHistory({
+     * // Filter by type and time
+     * const recent = await clipboard.history.searchHistory({
      *   type: 'text',
-     *   isFavorite: true,
-     *   sourceApp: 'com.apple.Safari'
+     *   startTime: Date.now() - 24 * 60 * 60 * 1000
      * })
      * ```
      */
     async searchHistory(options: ClipboardSearchOptions = {}): Promise<ClipboardSearchResponse> {
-      // Use the extended clipboard:get-history interface with search parameters
       const response = await channel.send('clipboard:get-history', options)
       const items = Array.isArray(response?.history)
         ? response.history.map((item: PluginClipboardItem) => normalizeItem(item) ?? item)
@@ -117,21 +191,120 @@ export function useClipboardHistory() {
       }
     },
 
+    /**
+     * Listen to clipboard changes.
+     *
+     * **Important**: Plugin must call `box.allowClipboard(types)` first to enable monitoring.
+     * Only changes matching the allowed types will be received.
+     *
+     * @example
+     * ```typescript
+     * import { ClipboardType } from '@talex-touch/utils/plugin/sdk'
+     *
+     * // Enable monitoring for text and images
+     * await box.allowClipboard(ClipboardType.TEXT | ClipboardType.IMAGE)
+     *
+     * // Listen to changes
+     * const unsubscribe = clipboard.history.onDidChange((item) => {
+     *   console.log('New clipboard item:', item.type, item.content)
+     * })
+     *
+     * // Later: stop listening
+     * unsubscribe()
+     * ```
+     */
     onDidChange(callback: (item: PluginClipboardItem) => void): () => void {
-      return channel.regChannel('core-box:clipboard-change', ({ data }) => {
-        const item = (data && 'item' in data ? data.item : data) as PluginClipboardItem
+      return channel.regChannel('core-box:clipboard-change', ({ data }: { data: unknown }) => {
+        const item = (data && typeof data === 'object' && 'item' in data ? (data as { item: PluginClipboardItem }).item : data) as PluginClipboardItem
         callback(normalizeItem(item) ?? item)
       })
     },
 
     /**
-     * Writes the provided clipboard payload to the system clipboard and issues a paste command
-     * to the foreground application.
+     * Apply a clipboard item to the active application (write + paste)
+     * @deprecated Use `clipboard.copyAndPaste()` instead
      */
     async applyToActiveApp(options: ClipboardApplyOptions = {}): Promise<boolean> {
       const response = await channel.send('clipboard:apply-to-active-app', options)
       if (typeof response === 'object' && response) {
-        return Boolean((response as any).success)
+        return Boolean((response as { success?: boolean }).success)
+      }
+      return true
+    },
+  }
+
+  return {
+    /**
+     * Clipboard history operations
+     */
+    history,
+
+    /**
+     * Writes text to the system clipboard
+     */
+    async writeText(text: string): Promise<void> {
+      await channel.send('clipboard:write-text', { text })
+    },
+
+    /**
+     * Writes content to the system clipboard.
+     * Supports text, HTML, image (data URL), and files.
+     */
+    async write(options: ClipboardWriteOptions): Promise<void> {
+      await channel.send('clipboard:write', options)
+    },
+
+    /**
+     * Reads current clipboard content
+     */
+    async read(): Promise<ClipboardReadResult> {
+      return await channel.send('clipboard:read')
+    },
+
+    /**
+     * Reads image from clipboard as data URL
+     */
+    async readImage(): Promise<ClipboardImageResult | null> {
+      return await channel.send('clipboard:read-image')
+    },
+
+    /**
+     * Reads file paths from clipboard
+     */
+    async readFiles(): Promise<string[]> {
+      return await channel.send('clipboard:read-files')
+    },
+
+    /**
+     * Clears the system clipboard
+     */
+    async clear(): Promise<void> {
+      await channel.send('clipboard:clear')
+    },
+
+    /**
+     * Writes content to clipboard and simulates paste command to the active application.
+     * This is the recommended way to "paste" content from a plugin.
+     *
+     * @example
+     * ```typescript
+     * // Paste text
+     * await clipboard.copyAndPaste({ text: 'Hello' })
+     *
+     * // Paste with HTML formatting
+     * await clipboard.copyAndPaste({ text: 'Hello', html: '<b>Hello</b>' })
+     *
+     * // Paste image
+     * await clipboard.copyAndPaste({ image: 'data:image/png;base64,...' })
+     *
+     * // Paste files
+     * await clipboard.copyAndPaste({ files: ['/path/to/file.txt'] })
+     * ```
+     */
+    async copyAndPaste(options: ClipboardCopyAndPasteOptions): Promise<boolean> {
+      const response = await channel.send('clipboard:copy-and-paste', options)
+      if (typeof response === 'object' && response) {
+        return Boolean((response as { success?: boolean }).success)
       }
       return true
     },

package/plugin/sdk/enum/bridge-event.ts

@@ -1,4 +1,5 @@
 export enum BridgeEventForCoreBox {
   CORE_BOX_INPUT_CHANGE = 'core-box:input-change',
   CORE_BOX_CLIPBOARD_CHANGE = 'core-box:clipboard-change',
+  CORE_BOX_KEY_EVENT = 'core-box:key-event',
 }

package/plugin/sdk/feature-sdk.ts

@@ -14,6 +14,24 @@ import { ensureRendererChannel } from './channel'
  */
 export type InputChangeHandler = (input: string) => void
 
+/**
+ * Keyboard event data forwarded from CoreBox
+ */
+export interface ForwardedKeyEvent {
+  key: string
+  code: string
+  metaKey: boolean
+  ctrlKey: boolean
+  altKey: boolean
+  shiftKey: boolean
+  repeat: boolean
+}
+
+/**
+ * Key event handler
+ */
+export type KeyEventHandler = (event: ForwardedKeyEvent) => void
+
 /**
  * Feature SDK interface for plugins
  * 
@@ -125,6 +143,36 @@ export interface FeatureSDK {
    * ```
    */
   onInputChange(handler: InputChangeHandler): () => void
+
+  /**
+   * Registers a listener for keyboard events forwarded from CoreBox
+   * 
+   * When a plugin's UI view is attached to CoreBox, certain key events
+   * (Enter, Arrow keys, Meta+key combinations) are forwarded to the plugin.
+   * 
+   * @param handler - Callback function invoked when a key event is forwarded
+   * @returns Unsubscribe function
+   * 
+   * @example
+   * ```typescript
+   * const unsubscribe = plugin.feature.onKeyEvent((event) => {
+   *   if (event.key === 'Enter') {
+   *     // Handle enter key
+   *     submitSelection()
+   *   } else if (event.key === 'ArrowDown') {
+   *     // Navigate down in list
+   *     selectNext()
+   *   } else if (event.metaKey && event.key === 'k') {
+   *     // Handle Cmd+K
+   *     openSearch()
+   *   }
+   * })
+   * 
+   * // Later, unsubscribe
+   * unsubscribe()
+   * ```
+   */
+  onKeyEvent(handler: KeyEventHandler): () => void
 }
 
 /**
@@ -138,25 +186,48 @@ export interface FeatureSDK {
  */
 export function createFeatureSDK(boxItemsAPI: any, channel: any): FeatureSDK {
   const inputChangeHandlers: Set<InputChangeHandler> = new Set()
+  const keyEventHandlers: Set<KeyEventHandler> = new Set()
 
   // Register listener for input change events from main process
-  const registerListener = () => {
+  const registerInputListener = () => {
     if (channel.onMain) {
       // Main process plugin context
-      channel.onMain('core-box:input-changed', (event: any) => {
-        const input = event.data?.input || event.input || ''
+      channel.onMain('core-box:input-change', (event: any) => {
+        const input = event.data?.input || event.data?.query?.text || event.input || ''
         inputChangeHandlers.forEach(handler => handler(input))
       })
     } else if (channel.on) {
       // Renderer process context
-      channel.on('core-box:input-changed', (data: any) => {
-        const input = data?.input || data || ''
+      channel.on('core-box:input-change', (data: any) => {
+        const input = data?.input || data?.query?.text || data || ''
         inputChangeHandlers.forEach(handler => handler(input))
       })
     }
   }
 
-  registerListener()
+  // Register listener for key events from main process
+  const registerKeyListener = () => {
+    if (channel.onMain) {
+      // Main process plugin context
+      channel.onMain('core-box:key-event', (event: any) => {
+        const keyEvent = event.data as ForwardedKeyEvent
+        if (keyEvent) {
+          keyEventHandlers.forEach(handler => handler(keyEvent))
+        }
+      })
+    } else if (channel.on) {
+      // Renderer process context
+      channel.on('core-box:key-event', (data: any) => {
+        const keyEvent = data as ForwardedKeyEvent
+        if (keyEvent) {
+          keyEventHandlers.forEach(handler => handler(keyEvent))
+        }
+      })
+    }
+  }
+
+  registerInputListener()
+  registerKeyListener()
 
   return {
     pushItems(items: TuffItem[]): void {
@@ -200,6 +271,14 @@ export function createFeatureSDK(boxItemsAPI: any, channel: any): FeatureSDK {
       return () => {
         inputChangeHandlers.delete(handler)
       }
+    },
+
+    onKeyEvent(handler: KeyEventHandler): () => void {
+      keyEventHandlers.add(handler)
+      
+      return () => {
+        keyEventHandlers.delete(handler)
+      }
     }
   }
 }

package/plugin/sdk/flow.ts

@@ -0,0 +1,246 @@
+/**
+ * Flow SDK
+ *
+ * Plugin-side API for Flow Transfer operations.
+ * Allows plugins to dispatch flows and receive flow data.
+ */
+
+import type {
+  FlowPayload,
+  FlowDispatchOptions,
+  FlowDispatchResult,
+  FlowTargetInfo,
+  FlowSessionUpdate,
+  FlowPayloadType
+} from '../../types/flow'
+import { FlowIPCChannel } from '../../types/flow'
+
+/**
+ * Flow SDK interface
+ */
+export interface IFlowSDK {
+  /**
+   * Dispatches a flow payload to another plugin
+   *
+   * @param payload - Data to transfer
+   * @param options - Dispatch options
+   * @returns Dispatch result
+   *
+   * @example
+   * ```typescript
+   * const result = await flow.dispatch(
+   *   {
+   *     type: 'text',
+   *     data: 'Hello from plugin A',
+   *     context: { sourcePluginId: 'plugin-a' }
+   *   },
+   *   {
+   *     title: 'Share Text',
+   *     preferredTarget: 'plugin-b.quick-note'
+   *   }
+   * )
+   * ```
+   */
+  dispatch(payload: FlowPayload, options?: FlowDispatchOptions): Promise<FlowDispatchResult>
+
+  /**
+   * Gets available flow targets
+   *
+   * @param payloadType - Filter by payload type (optional)
+   * @returns List of available targets
+   */
+  getAvailableTargets(payloadType?: FlowPayloadType): Promise<FlowTargetInfo[]>
+
+  /**
+   * Listens for session updates
+   *
+   * @param sessionId - Session to listen to
+   * @param handler - Update handler
+   * @returns Unsubscribe function
+   */
+  onSessionUpdate(
+    sessionId: string,
+    handler: (update: FlowSessionUpdate) => void
+  ): () => void
+
+  /**
+   * Cancels a flow session
+   *
+   * @param sessionId - Session to cancel
+   */
+  cancel(sessionId: string): Promise<void>
+
+  /**
+   * Acknowledges a received flow (for target plugins)
+   *
+   * @param sessionId - Session to acknowledge
+   * @param ackPayload - Optional acknowledgment data
+   */
+  acknowledge(sessionId: string, ackPayload?: any): Promise<void>
+
+  /**
+   * Reports an error for a received flow (for target plugins)
+   *
+   * @param sessionId - Session to report error for
+   * @param message - Error message
+   */
+  reportError(sessionId: string, message: string): Promise<void>
+}
+
+/**
+ * Creates a Flow SDK instance
+ *
+ * @param channel - Channel for IPC communication
+ * @param pluginId - Current plugin ID
+ * @returns Flow SDK instance
+ */
+export function createFlowSDK(
+  channel: { send: (event: string, data?: any) => Promise<any> },
+  pluginId: string
+): IFlowSDK {
+  const sessionListeners = new Map<string, Set<(update: FlowSessionUpdate) => void>>()
+
+  // Listen for session updates
+  if (typeof window !== 'undefined') {
+    window.addEventListener('message', (event) => {
+      if (event.data?.type === FlowIPCChannel.SESSION_UPDATE) {
+        const update = event.data.payload as FlowSessionUpdate
+        const listeners = sessionListeners.get(update.sessionId)
+        if (listeners) {
+          for (const listener of listeners) {
+            try {
+              listener(update)
+            } catch (error) {
+              console.error('[FlowSDK] Error in session listener:', error)
+            }
+          }
+        }
+      }
+    })
+  }
+
+  return {
+    async dispatch(payload: FlowPayload, options?: FlowDispatchOptions): Promise<FlowDispatchResult> {
+      // Ensure context has sourcePluginId
+      const enrichedPayload: FlowPayload = {
+        ...payload,
+        context: {
+          ...payload.context,
+          sourcePluginId: payload.context?.sourcePluginId || pluginId
+        }
+      }
+
+      const response = await channel.send(FlowIPCChannel.DISPATCH, {
+        senderId: pluginId,
+        payload: enrichedPayload,
+        options
+      })
+
+      if (!response?.success) {
+        throw new Error(response?.error?.message || 'Flow dispatch failed')
+      }
+
+      return response.data
+    },
+
+    async getAvailableTargets(payloadType?: FlowPayloadType): Promise<FlowTargetInfo[]> {
+      const response = await channel.send(FlowIPCChannel.GET_TARGETS, {
+        payloadType
+      })
+
+      if (!response?.success) {
+        throw new Error(response?.error?.message || 'Failed to get targets')
+      }
+
+      return response.data || []
+    },
+
+    onSessionUpdate(
+      sessionId: string,
+      handler: (update: FlowSessionUpdate) => void
+    ): () => void {
+      if (!sessionListeners.has(sessionId)) {
+        sessionListeners.set(sessionId, new Set())
+      }
+      sessionListeners.get(sessionId)!.add(handler)
+
+      return () => {
+        const listeners = sessionListeners.get(sessionId)
+        if (listeners) {
+          listeners.delete(handler)
+          if (listeners.size === 0) {
+            sessionListeners.delete(sessionId)
+          }
+        }
+      }
+    },
+
+    async cancel(sessionId: string): Promise<void> {
+      const response = await channel.send(FlowIPCChannel.CANCEL, {
+        sessionId
+      })
+
+      if (!response?.success) {
+        throw new Error(response?.error?.message || 'Failed to cancel session')
+      }
+    },
+
+    async acknowledge(sessionId: string, ackPayload?: any): Promise<void> {
+      const response = await channel.send(FlowIPCChannel.ACKNOWLEDGE, {
+        sessionId,
+        ackPayload
+      })
+
+      if (!response?.success) {
+        throw new Error(response?.error?.message || 'Failed to acknowledge session')
+      }
+    },
+
+    async reportError(sessionId: string, message: string): Promise<void> {
+      const response = await channel.send(FlowIPCChannel.REPORT_ERROR, {
+        sessionId,
+        message
+      })
+
+      if (!response?.success) {
+        throw new Error(response?.error?.message || 'Failed to report error')
+      }
+    }
+  }
+}
+
+/**
+ * Helper to extract flow data from TuffQuery
+ *
+ * When a feature is triggered via Flow, the query will contain flow information.
+ *
+ * @param query - TuffQuery from feature trigger
+ * @returns Flow data if present, null otherwise
+ */
+export function extractFlowData(query: any): {
+  sessionId: string
+  payload: FlowPayload
+  senderId: string
+  senderName?: string
+} | null {
+  if (!query?.flow) {
+    return null
+  }
+
+  return {
+    sessionId: query.flow.sessionId,
+    payload: query.flow.payload,
+    senderId: query.flow.senderId,
+    senderName: query.flow.senderName
+  }
+}
+
+/**
+ * Helper to check if a feature was triggered via Flow
+ *
+ * @param query - TuffQuery from feature trigger
+ * @returns True if triggered via Flow
+ */
+export function isFlowTriggered(query: any): boolean {
+  return !!query?.flow
+}