@talex-touch/utils 1.0.42 → 1.0.44

package/plugin/sdk/feature-sdk.ts

@@ -1,12 +1,16 @@
 /**
  * Feature SDK for Plugin Development
- * 
+ *
  * Provides a unified API for plugins to manage search result items (TuffItems)
  * in the CoreBox interface. This SDK handles item lifecycle, updates, and
  * input change notifications.
  */
 
 import type { TuffItem } from '../../core-box/tuff'
+import { createPluginTuffTransport } from '../../transport'
+import { defineRawEvent } from '../../transport/event/builder'
+import { createDisposableBag } from '../../transport/sdk'
+import { useBoxItems } from './box-items'
 import { ensureRendererChannel } from './channel'
 
 /**
@@ -32,9 +36,12 @@ export interface ForwardedKeyEvent {
  */
 export type KeyEventHandler = (event: ForwardedKeyEvent) => void
 
+const featureInputChangeEvent = defineRawEvent<unknown, unknown>('core-box:input-change')
+const featureKeyEvent = defineRawEvent<unknown, unknown>('core-box:key-event')
+
 /**
  * Feature SDK interface for plugins
- * 
+ *
  * @example
  * ```typescript
  * // Push items to CoreBox
@@ -42,10 +49,10 @@ export type KeyEventHandler = (event: ForwardedKeyEvent) => void
  *   { id: 'item-1', title: 'Result 1', ... },
  *   { id: 'item-2', title: 'Result 2', ... }
  * ])
- * 
+ *
  * // Update a specific item
  * plugin.feature.updateItem('item-1', { title: 'Updated Title' })
- * 
+ *
  * // Listen for input changes
  * plugin.feature.onInputChange((input) => {
  *   console.log('User typed:', input)
@@ -55,9 +62,9 @@ export type KeyEventHandler = (event: ForwardedKeyEvent) => void
 export interface FeatureSDK {
   /**
    * Pushes multiple items to the CoreBox search results
-   * 
+   *
    * @param items - Array of TuffItem objects to display
-   * 
+   *
    * @example
    * ```typescript
    * plugin.feature.pushItems([
@@ -70,14 +77,14 @@ export interface FeatureSDK {
    * ])
    * ```
    */
-  pushItems(items: TuffItem[]): void
+  pushItems: (items: TuffItem[]) => void
 
   /**
    * Updates a specific item by ID
-   * 
+   *
    * @param id - The unique ID of the item to update
    * @param updates - Partial TuffItem with fields to update
-   * 
+   *
    * @example
    * ```typescript
    * // Update title and subtitle
@@ -87,49 +94,49 @@ export interface FeatureSDK {
    * })
    * ```
    */
-  updateItem(id: string, updates: Partial<TuffItem>): void
+  updateItem: (id: string, updates: Partial<TuffItem>) => void
 
   /**
    * Removes a specific item by ID
-   * 
+   *
    * @param id - The unique ID of the item to remove
-   * 
+   *
    * @example
    * ```typescript
    * plugin.feature.removeItem('item-1')
    * ```
    */
-  removeItem(id: string): void
+  removeItem: (id: string) => void
 
   /**
    * Clears all items pushed by this plugin
-   * 
+   *
    * @example
    * ```typescript
    * plugin.feature.clearItems()
    * ```
    */
-  clearItems(): void
+  clearItems: () => void
 
   /**
    * Gets all items currently pushed by this plugin
-   * 
+   *
    * @returns Array of TuffItem objects
-   * 
+   *
    * @example
    * ```typescript
    * const items = plugin.feature.getItems()
    * console.log(`Currently showing ${items.length} items`)
    * ```
    */
-  getItems(): TuffItem[]
+  getItems: () => TuffItem[]
 
   /**
    * Registers a listener for input changes in the CoreBox search field
-   * 
+   *
    * @param handler - Callback function invoked when input changes
    * @returns Unsubscribe function
-   * 
+   *
    * @example
    * ```typescript
    * const unsubscribe = plugin.feature.onInputChange((input) => {
@@ -137,22 +144,22 @@ export interface FeatureSDK {
    *   // Perform real-time search
    *   performSearch(input)
    * })
-   * 
+   *
    * // Later, unsubscribe
    * unsubscribe()
    * ```
    */
-  onInputChange(handler: InputChangeHandler): () => void
+  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) => {
@@ -167,70 +174,95 @@ export interface FeatureSDK {
    *     openSearch()
    *   }
    * })
-   * 
+   *
    * // Later, unsubscribe
    * unsubscribe()
    * ```
    */
-  onKeyEvent(handler: KeyEventHandler): () => void
+  onKeyEvent: (handler: KeyEventHandler) => () => void
+
+  /**
+   * 释放内部监听器，避免重复注册导致的内存泄漏
+   */
+  dispose: () => void
 }
 
 /**
  * Creates a Feature SDK instance for plugin use
- * 
+ *
  * @param boxItemsAPI - The boxItems API object from plugin context
  * @param channel - The plugin channel bridge for IPC communication
  * @returns Configured Feature SDK instance
- * 
+ *
  * @internal
  */
 export function createFeatureSDK(boxItemsAPI: any, channel: any): FeatureSDK {
   const inputChangeHandlers: Set<InputChangeHandler> = new Set()
   const keyEventHandlers: Set<KeyEventHandler> = new Set()
+  const disposables = createDisposableBag()
+  const transport = createPluginTuffTransport(channel)
+  let disposed = false
+
+  const emitInput = (payload: any) => {
+    const input = payload?.input || payload?.query?.text || payload || ''
+    for (const handler of inputChangeHandlers) {
+      try {
+        handler(input)
+      }
+      catch (error) {
+        console.error('[Feature SDK] onInputChange handler error:', error)
+      }
+    }
+  }
+
+  const emitKeyEvent = (payload: any) => {
+    const keyEvent = payload as ForwardedKeyEvent
+    if (!keyEvent) {
+      return
+    }
+
+    for (const handler of keyEventHandlers) {
+      try {
+        handler(keyEvent)
+      }
+      catch (error) {
+        console.error('[Feature SDK] onKeyEvent handler error:', error)
+      }
+    }
+  }
 
-  // Register listener for input change events from main process
-  const registerInputListener = () => {
-    if (channel.onMain) {
-      // Main process plugin context
-      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-change', (data: any) => {
-        const input = data?.input || data?.query?.text || data || ''
-        inputChangeHandlers.forEach(handler => handler(input))
-      })
+  const ensureActive = (method: string) => {
+    if (disposed) {
+      throw new Error(`[Feature SDK] Cannot call ${method} after dispose`)
     }
   }
 
-  // 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))
-        }
-      })
+  const dispose = () => {
+    if (disposed) {
+      return
     }
+
+    disposed = true
+    inputChangeHandlers.clear()
+    keyEventHandlers.clear()
+    disposables.dispose()
+    transport.destroy()
   }
 
-  registerInputListener()
-  registerKeyListener()
+  disposables.add(
+    transport.on(featureInputChangeEvent, emitInput),
+    transport.on(featureKeyEvent, emitKeyEvent),
+  )
+
+  if (typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
+    const onBeforeUnload = () => dispose()
+    window.addEventListener('beforeunload', onBeforeUnload, { once: true })
+    disposables.add(() => window.removeEventListener('beforeunload', onBeforeUnload))
+  }
 
   return {
     pushItems(items: TuffItem[]): void {
+      ensureActive('pushItems')
       if (!boxItemsAPI || !boxItemsAPI.pushItems) {
         throw new Error('[Feature SDK] boxItems API not available')
       }
@@ -238,6 +270,7 @@ export function createFeatureSDK(boxItemsAPI: any, channel: any): FeatureSDK {
     },
 
     updateItem(id: string, updates: Partial<TuffItem>): void {
+      ensureActive('updateItem')
       if (!boxItemsAPI || !boxItemsAPI.update) {
         throw new Error('[Feature SDK] boxItems API not available')
       }
@@ -245,6 +278,7 @@ export function createFeatureSDK(boxItemsAPI: any, channel: any): FeatureSDK {
     },
 
     removeItem(id: string): void {
+      ensureActive('removeItem')
       if (!boxItemsAPI || !boxItemsAPI.remove) {
         throw new Error('[Feature SDK] boxItems API not available')
       }
@@ -252,6 +286,7 @@ export function createFeatureSDK(boxItemsAPI: any, channel: any): FeatureSDK {
     },
 
     clearItems(): void {
+      ensureActive('clearItems')
       if (!boxItemsAPI || !boxItemsAPI.clear) {
         throw new Error('[Feature SDK] boxItems API not available')
       }
@@ -259,6 +294,7 @@ export function createFeatureSDK(boxItemsAPI: any, channel: any): FeatureSDK {
     },
 
     getItems(): TuffItem[] {
+      ensureActive('getItems')
       if (!boxItemsAPI || !boxItemsAPI.getItems) {
         throw new Error('[Feature SDK] boxItems API not available')
       }
@@ -266,45 +302,44 @@ export function createFeatureSDK(boxItemsAPI: any, channel: any): FeatureSDK {
     },
 
     onInputChange(handler: InputChangeHandler): () => void {
+      ensureActive('onInputChange')
       inputChangeHandlers.add(handler)
-      
+
       return () => {
         inputChangeHandlers.delete(handler)
       }
     },
 
     onKeyEvent(handler: KeyEventHandler): () => void {
+      ensureActive('onKeyEvent')
       keyEventHandlers.add(handler)
-      
+
       return () => {
         keyEventHandlers.delete(handler)
       }
-    }
+    },
+
+    dispose,
   }
 }
 
 /**
  * Hook for using Feature SDK in plugin context
- * 
+ *
  * @returns Feature SDK instance
- * 
+ *
  * @example
  * ```typescript
  * const feature = useFeature()
- * 
+ *
  * feature.pushItems([
  *   { id: '1', title: { text: 'Item 1' }, ... }
  * ])
  * ```
  */
 export function useFeature(): FeatureSDK {
-  // @ts-ignore - window.$boxItems is injected by the plugin system
-  const boxItemsAPI = window.$boxItems
+  const boxItemsAPI = useBoxItems()
   const channel = ensureRendererChannel('[Feature SDK] Channel not available. Make sure this is called in a plugin context.')
-  
-  if (!boxItemsAPI) {
-    throw new Error('[Feature SDK] boxItems API not available. Make sure this is called in a plugin context.')
-  }
-  
+
   return createFeatureSDK(boxItemsAPI, channel)
 }

package/plugin/sdk/flow.ts

@@ -6,14 +6,29 @@
  */
 
 import type {
-  FlowPayload,
   FlowDispatchOptions,
   FlowDispatchResult,
-  FlowTargetInfo,
+  FlowPayload,
+  FlowPayloadType,
   FlowSessionUpdate,
-  FlowPayloadType
+  FlowTargetInfo,
 } from '../../types/flow'
-import { FlowIPCChannel } from '../../types/flow'
+import { createPluginTuffTransport } from '../../transport'
+import { FlowEvents } from '../../transport/events'
+import { tryGetPluginSdkApi } from './plugin-info'
+
+function resolveSdkApi(): number | undefined {
+  return tryGetPluginSdkApi()
+}
+
+/**
+ * Flow transfer handler function type
+ */
+export type FlowTransferHandler = (
+  payload: FlowPayload,
+  sessionId: string,
+  senderInfo: { senderId: string, senderName?: string },
+) => Promise<void> | void
 
 /**
  * Flow SDK interface
@@ -41,7 +56,7 @@ export interface IFlowSDK {
    * )
    * ```
    */
-  dispatch(payload: FlowPayload, options?: FlowDispatchOptions): Promise<FlowDispatchResult>
+  dispatch: (payload: FlowPayload, options?: FlowDispatchOptions) => Promise<FlowDispatchResult>
 
   /**
    * Gets available flow targets
@@ -49,7 +64,25 @@ export interface IFlowSDK {
    * @param payloadType - Filter by payload type (optional)
    * @returns List of available targets
    */
-  getAvailableTargets(payloadType?: FlowPayloadType): Promise<FlowTargetInfo[]>
+  getAvailableTargets: (payloadType?: FlowPayloadType) => Promise<FlowTargetInfo[]>
+
+  /**
+   * Registers a handler for incoming flow transfers
+   * This tells the system that your plugin can handle flow data
+   *
+   * @param handler - Handler function for incoming flows
+   * @returns Unsubscribe function
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = flow.onFlowTransfer(async (payload, sessionId, sender) => {
+   *   console.log(`Received ${payload.type} from ${sender.senderName}`)
+   *   // Process the payload...
+   *   await flow.acknowledge(sessionId, { processed: true })
+   * })
+   * ```
+   */
+  onFlowTransfer: (handler: FlowTransferHandler) => () => void
 
   /**
    * Listens for session updates
@@ -58,17 +91,17 @@ export interface IFlowSDK {
    * @param handler - Update handler
    * @returns Unsubscribe function
    */
-  onSessionUpdate(
+  onSessionUpdate: (
     sessionId: string,
-    handler: (update: FlowSessionUpdate) => void
-  ): () => void
+    handler: (update: FlowSessionUpdate) => void,
+  ) => () => void
 
   /**
    * Cancels a flow session
    *
    * @param sessionId - Session to cancel
    */
-  cancel(sessionId: string): Promise<void>
+  cancel: (sessionId: string) => Promise<void>
 
   /**
    * Acknowledges a received flow (for target plugins)
@@ -76,7 +109,7 @@ export interface IFlowSDK {
    * @param sessionId - Session to acknowledge
    * @param ackPayload - Optional acknowledgment data
    */
-  acknowledge(sessionId: string, ackPayload?: any): Promise<void>
+  acknowledge: (sessionId: string, ackPayload?: any) => Promise<void>
 
   /**
    * Reports an error for a received flow (for target plugins)
@@ -84,40 +117,61 @@ export interface IFlowSDK {
    * @param sessionId - Session to report error for
    * @param message - Error message
    */
-  reportError(sessionId: string, message: string): Promise<void>
+  reportError: (sessionId: string, message: string) => Promise<void>
+
+  /**
+   * Uses native system share functionality
+   *
+   * @param payload - Data to share
+   * @param target - Optional preferred native target (system, airdrop, mail, messages)
+   */
+  nativeShare: (payload: FlowPayload, target?: string) => Promise<{ success: boolean, target?: string, error?: string }>
 }
 
 /**
  * Creates a Flow SDK instance
  *
  * @param channel - Channel for IPC communication
+ * @param channel.send - Send function 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
+  pluginId: string,
 ): IFlowSDK {
   const sessionListeners = new Map<string, Set<(update: FlowSessionUpdate) => void>>()
+  const flowTransferHandlers = new Set<FlowTransferHandler>()
+  let hasRegisteredHandler = false
 
-  // 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)
-            }
-          }
-        }
+  const transport = createPluginTuffTransport(channel as any)
+
+  transport.on(FlowEvents.sessionUpdate, (update) => {
+    const listeners = sessionListeners.get((update as any)?.sessionId)
+    if (!listeners) {
+      return
+    }
+    for (const listener of listeners) {
+      try {
+        listener(update as any)
       }
-    })
-  }
+      catch (error) {
+        console.error('[FlowSDK] Error in session listener:', error)
+      }
+    }
+  })
+
+  transport.on(FlowEvents.deliver, (payload) => {
+    const { sessionId, payload: flowPayload, senderId, senderName } = payload as any
+    for (const h of flowTransferHandlers) {
+      try {
+        h(flowPayload, sessionId, { senderId, senderName })
+      }
+      catch (error) {
+        console.error('[FlowSDK] Error in flow transfer handler:', error)
+      }
+    }
+  })
 
   return {
     async dispatch(payload: FlowPayload, options?: FlowDispatchOptions): Promise<FlowDispatchResult> {
@@ -126,26 +180,32 @@ export function createFlowSDK(
         ...payload,
         context: {
           ...payload.context,
-          sourcePluginId: payload.context?.sourcePluginId || pluginId
-        }
+          sourcePluginId: payload.context?.sourcePluginId || pluginId,
+        },
       }
 
-      const response = await channel.send(FlowIPCChannel.DISPATCH, {
+      const response = await transport.send(FlowEvents.dispatch, {
         senderId: pluginId,
         payload: enrichedPayload,
-        options
+        options,
+        _sdkapi: resolveSdkApi(),
       })
 
       if (!response?.success) {
         throw new Error(response?.error?.message || 'Flow dispatch failed')
       }
 
+      if (!response.data) {
+        throw new Error('Flow dispatch failed')
+      }
+
       return response.data
     },
 
     async getAvailableTargets(payloadType?: FlowPayloadType): Promise<FlowTargetInfo[]> {
-      const response = await channel.send(FlowIPCChannel.GET_TARGETS, {
-        payloadType
+      const response = await transport.send(FlowEvents.getTargets, {
+        payloadType,
+        _sdkapi: resolveSdkApi(),
       })
 
       if (!response?.success) {
@@ -157,7 +217,7 @@ export function createFlowSDK(
 
     onSessionUpdate(
       sessionId: string,
-      handler: (update: FlowSessionUpdate) => void
+      handler: (update: FlowSessionUpdate) => void,
     ): () => void {
       if (!sessionListeners.has(sessionId)) {
         sessionListeners.set(sessionId, new Set())
@@ -176,8 +236,9 @@ export function createFlowSDK(
     },
 
     async cancel(sessionId: string): Promise<void> {
-      const response = await channel.send(FlowIPCChannel.CANCEL, {
-        sessionId
+      const response = await transport.send(FlowEvents.cancel, {
+        sessionId,
+        _sdkapi: resolveSdkApi(),
       })
 
       if (!response?.success) {
@@ -186,9 +247,10 @@ export function createFlowSDK(
     },
 
     async acknowledge(sessionId: string, ackPayload?: any): Promise<void> {
-      const response = await channel.send(FlowIPCChannel.ACKNOWLEDGE, {
+      const response = await transport.send(FlowEvents.acknowledge, {
         sessionId,
-        ackPayload
+        ackPayload,
+        _sdkapi: resolveSdkApi(),
       })
 
       if (!response?.success) {
@@ -197,15 +259,54 @@ export function createFlowSDK(
     },
 
     async reportError(sessionId: string, message: string): Promise<void> {
-      const response = await channel.send(FlowIPCChannel.REPORT_ERROR, {
+      const response = await transport.send(FlowEvents.reportError, {
         sessionId,
-        message
+        message,
+        _sdkapi: resolveSdkApi(),
       })
 
       if (!response?.success) {
         throw new Error(response?.error?.message || 'Failed to report error')
       }
-    }
+    },
+
+    onFlowTransfer(handler: FlowTransferHandler): () => void {
+      flowTransferHandlers.add(handler)
+
+      // Notify the system that this plugin has a flow handler
+      if (!hasRegisteredHandler) {
+        hasRegisteredHandler = true
+        void transport.send(FlowEvents.setPluginHandler, {
+          pluginId,
+          hasHandler: true,
+          _sdkapi: resolveSdkApi(),
+        }).catch((err: unknown) => {
+          console.warn('[FlowSDK] Failed to register flow handler:', err)
+        })
+      }
+
+      return () => {
+        flowTransferHandlers.delete(handler)
+        if (flowTransferHandlers.size === 0) {
+          hasRegisteredHandler = false
+          void transport.send(FlowEvents.setPluginHandler, {
+            pluginId,
+            hasHandler: false,
+            _sdkapi: resolveSdkApi(),
+          }).catch(() => {})
+        }
+      }
+    },
+
+    async nativeShare(payload: FlowPayload, target?: string): Promise<{ success: boolean, target?: string, error?: string }> {
+      const response = await transport.send(FlowEvents.nativeShare, {
+        payload,
+        target,
+        _sdkapi: resolveSdkApi(),
+      })
+
+      return response || { success: false, error: 'Native share failed' }
+    },
   }
 }
 
@@ -231,7 +332,7 @@ export function extractFlowData(query: any): {
     sessionId: query.flow.sessionId,
     payload: query.flow.payload,
     senderId: query.flow.senderId,
-    senderName: query.flow.senderName
+    senderName: query.flow.senderName,
   }
 }