@talex-touch/utils 1.0.40 → 1.0.44

package/plugin/sdk/channel.ts

@@ -1,12 +1,94 @@
-import type { ITouchClientChannel } from '@talex-touch/utils/channel'
+import type { ITouchClientChannel, StandardChannelData } from '@talex-touch/utils/channel'
+import type { ITuffTransport } from '@talex-touch/utils/transport'
 import type { IPluginRendererChannel, PluginChannelHandler } from './types'
+import { ChannelType, DataCode } from '@talex-touch/utils/channel'
+import { hasWindow } from '@talex-touch/utils/env'
+import { defineRawEvent } from '@talex-touch/utils/transport/event/builder'
 import { genChannel } from '../channel'
 
 const ensureClientChannel = (): ITouchClientChannel => genChannel()
+function resolvePluginName(): string | undefined {
+  if (!hasWindow()) {
+    return undefined
+  }
+
+  return (window as { $plugin?: { name?: string } } | undefined)?.$plugin?.name
+}
+function buildStandardChannelEvent(eventName: string, payload: unknown, pluginName: string | undefined, reply: (code: DataCode, data: unknown) => void): StandardChannelData {
+  return {
+    name: eventName,
+    header: {
+      status: 'request',
+      type: ChannelType.PLUGIN,
+      plugin: pluginName,
+    },
+    code: DataCode.SUCCESS,
+    data: payload,
+    plugin: pluginName,
+    reply,
+  }
+}
+function createTransportClientChannel(transport: ITuffTransport, fallback: ITouchClientChannel | null): ITouchClientChannel {
+  const handlerMap = new Map<string, Map<(data: StandardChannelData) => any, () => void>>()
+
+  return {
+    regChannel: (eventName, callback) => {
+      const disposer = transport.on(defineRawEvent(eventName), async (payload) => {
+        let replied = false
+        let replyData: unknown
+        const event = buildStandardChannelEvent(
+          eventName,
+          payload,
+          resolvePluginName(),
+          (_code, data) => {
+            replied = true
+            replyData = data
+          },
+        )
+
+        const result = await callback(event)
+        return replied ? replyData : result
+      })
+
+      let handlers = handlerMap.get(eventName)
+      if (!handlers) {
+        handlers = new Map()
+        handlerMap.set(eventName, handlers)
+      }
+      handlers.set(callback, disposer)
+
+      return () => {
+        disposer()
+        handlers?.delete(callback)
+      }
+    },
+    unRegChannel: (eventName, callback) => {
+      const disposer = handlerMap.get(eventName)?.get(callback)
+      if (!disposer) {
+        return false
+      }
+      disposer()
+      handlerMap.get(eventName)?.delete(callback)
+      return true
+    },
+    send: (eventName, arg) => transport.send(defineRawEvent(eventName), arg),
+    sendSync: (eventName, arg) => {
+      if (fallback?.sendSync) {
+        return fallback.sendSync(eventName, arg)
+      }
+      throw new Error(`[Plugin SDK] sendSync is not supported without legacy channel: ${eventName}`)
+    },
+  }
+}
+function resolveRendererTransport(): ITuffTransport | null {
+  const globalWindow = hasWindow() ? window : undefined
+  return globalWindow?.$transport ?? null
+}
 
 const DEFAULT_CHANNEL_ERROR = '[Plugin SDK] Channel not available. Make sure this code runs inside a plugin renderer context.'
 
 let cachedWindowChannel: ITouchClientChannel | null = null
+let cachedTransportChannel: ITouchClientChannel | null = null
 
 /**
  * Ensures that the renderer-side plugin channel (window.$channel) exists and returns it.
@@ -14,7 +96,16 @@ let cachedWindowChannel: ITouchClientChannel | null = null
  * @param errorMessage - Optional custom error message when the channel is unavailable
  */
 export function ensureRendererChannel(errorMessage = DEFAULT_CHANNEL_ERROR): ITouchClientChannel {
-  const globalWindow = typeof window === 'undefined' ? undefined : window
+  const globalWindow = hasWindow() ? window : undefined
+  const transport = globalWindow?.$transport ?? null
+  if (transport) {
+    if (!cachedTransportChannel) {
+      const fallback = globalWindow?.$channel ?? cachedWindowChannel ?? null
+      cachedTransportChannel = createTransportClientChannel(transport, fallback)
+    }
+    return cachedTransportChannel
+  }
+
   const channel = globalWindow?.$channel ?? cachedWindowChannel
 
   if (!channel) {
@@ -34,9 +125,13 @@ export function useChannel(errorMessage?: string): ITouchClientChannel {
 
 export function createPluginRendererChannel(): IPluginRendererChannel {
   const client = ensureClientChannel()
+  const transport = resolveRendererTransport()
 
   return {
     send(eventName, payload) {
+      if (transport) {
+        return transport.send(defineRawEvent(eventName), payload)
+      }
       return client.send(eventName, payload)
     },
 
@@ -45,7 +140,26 @@ export function createPluginRendererChannel(): IPluginRendererChannel {
     },
 
     on(eventName, handler) {
-      return client.regChannel(eventName, handler)
+      if (!transport) {
+        return client.regChannel(eventName, handler)
+      }
+
+      return transport.on(defineRawEvent(eventName), async (payload) => {
+        let replied = false
+        let replyData: unknown
+        const event = buildStandardChannelEvent(
+          eventName,
+          payload,
+          resolvePluginName(),
+          (_code, data) => {
+            replied = true
+            replyData = data
+          },
+        )
+
+        const result = await handler(event)
+        return replied ? replyData : result
+      })
     },
 
     once(eventName, handler) {
@@ -55,7 +169,7 @@ export function createPluginRendererChannel(): IPluginRendererChannel {
         handler(event)
       }
 
-      dispose = client.regChannel(eventName, wrapped)
+      dispose = this.on(eventName, wrapped)
       return dispose
     },
 
@@ -78,5 +192,6 @@ export function usePluginRendererChannel(): IPluginRendererChannel {
 declare global {
   interface Window {
     $channel: ITouchClientChannel
+    $transport?: ITuffTransport
   }
 }

package/plugin/sdk/clipboard.ts

@@ -1,12 +1,5 @@
 import type { PluginClipboardHistoryResponse, PluginClipboardItem, PluginClipboardSearchOptions, PluginClipboardSearchResponse } from './types'
-
-function ensurePluginChannel() {
-  const channel = (window as any)?.$channel
-  if (!channel) {
-    throw new Error('[Plugin SDK] Clipboard channel requires plugin renderer context with $channel available.')
-  }
-  return channel
-}
+import { useChannel } from './channel'
 
 function normalizeItem(item: PluginClipboardItem | null): PluginClipboardItem | null {
   if (!item)
@@ -63,6 +56,11 @@ export interface ClipboardImageResult {
   dataUrl: string
   width: number
   height: number
+  /**
+   * Original image as a local streamable URL (Electron only).
+   * Returned when calling `readImage({ preview: false })`.
+   */
+  tfileUrl?: string
 }
 
 export interface ClipboardCopyAndPasteOptions {
@@ -117,7 +115,7 @@ export function useClipboardHistory() {
  * ```
  */
 export function useClipboard() {
-  const channel = ensurePluginChannel()
+  const channel = useChannel('[Plugin SDK] Clipboard channel requires plugin renderer context with $channel available.')
 
   const history = {
     /**
@@ -214,7 +212,8 @@ export function useClipboard() {
      * ```
      */
     onDidChange(callback: (item: PluginClipboardItem) => void): () => void {
-      return channel.regChannel('core-box:clipboard-change', ({ data }: { data: unknown }) => {
+      return channel.regChannel('core-box:clipboard-change', (event) => {
+        const data = event?.data
         const item = (data && typeof data === 'object' && 'item' in data ? (data as { item: PluginClipboardItem }).item : data) as PluginClipboardItem
         callback(normalizeItem(item) ?? item)
       })
@@ -264,8 +263,23 @@ export function useClipboard() {
     /**
      * Reads image from clipboard as data URL
      */
-    async readImage(): Promise<ClipboardImageResult | null> {
-      return await channel.send('clipboard:read-image')
+    async readImage(options?: { preview?: boolean }): Promise<ClipboardImageResult | null> {
+      return await channel.send('clipboard:read-image', { preview: options?.preview ?? true })
+    },
+
+    /**
+     * Resolves the original image URL for a clipboard history item (streamable via tfile://).
+     *
+     * @remarks
+     * - This avoids transferring large base64 payloads over IPC.
+     * - Returns null if the item is not an image or original asset is not available.
+     */
+    async getHistoryImageUrl(id: number): Promise<string | null> {
+      const res = await channel.send('clipboard:get-image-url', { id })
+      if (res && typeof res === 'object' && 'url' in res && typeof (res as any).url === 'string') {
+        return (res as any).url as string
+      }
+      return null
     },
 
     /**

package/plugin/sdk/cloud-sync.ts

@@ -0,0 +1,113 @@
+import type { CloudSyncSDKOptions as ClientOptions } from '../../cloud-sync/cloud-sync-sdk'
+import { CloudSyncSDK as CloudSyncClientSDK, CloudSyncError } from '../../cloud-sync/cloud-sync-sdk'
+import type { HandshakeResponse, PullResponse, PushResponse, SyncItemInput } from '../../types/cloud-sync'
+import { accountSDK } from '../../account'
+import { ensureRendererChannel } from './channel'
+
+export interface CloudSyncSDKOptions {
+  baseUrl?: string
+  serviceBaseUrl?: string
+  fetch?: typeof fetch
+  now?: () => number
+  syncTokenCache?: { token?: string, expiresAt?: string }
+  onSyncTokenUpdate?: (token: string, expiresAt: string) => void
+  onHandshake?: (response: HandshakeResponse) => void
+  onStepUpRequired?: () => string | null | Promise<string | null>
+  formDataFactory?: () => FormData
+  channelSend?: (event: string, data?: any) => Promise<any>
+  ignoreSyncPreferenceCheck?: boolean
+}
+
+let accountChannelBound = false
+
+function bindAccountChannel(options?: CloudSyncSDKOptions) {
+  if (accountChannelBound)
+    return
+
+  if (options?.channelSend) {
+    accountSDK.setChannelSend(options.channelSend)
+    accountChannelBound = true
+    return
+  }
+
+  const channel = ensureRendererChannel('[CloudSyncSDK] Channel not available. Make sure this runs in plugin renderer context.')
+  accountSDK.setChannelSend(channel.send)
+  accountChannelBound = true
+}
+
+async function resolveAuthToken(options?: CloudSyncSDKOptions): Promise<string> {
+  bindAccountChannel(options)
+  if (!options?.ignoreSyncPreferenceCheck) {
+    const syncEnabled = await accountSDK.getSyncEnabled()
+    if (!syncEnabled) {
+      throw new CloudSyncError(
+        '[CloudSyncSDK] Sync is disabled by user preference.',
+        403,
+        'SYNC_DISABLED'
+      )
+    }
+  }
+  const token = await accountSDK.getAuthToken()
+  if (!token) {
+    throw new Error('[CloudSyncSDK] Auth token is not available. Ensure user is signed in and AccountSDK channel is configured.')
+  }
+  return token
+}
+
+async function resolveDeviceId(options?: CloudSyncSDKOptions): Promise<string> {
+  bindAccountChannel(options)
+  const deviceId = await accountSDK.getDeviceId()
+  if (!deviceId) {
+    throw new Error('[CloudSyncSDK] Device ID is not available. Ensure AccountSDK channel is configured.')
+  }
+  return deviceId
+}
+
+export class CloudSyncSDK extends CloudSyncClientSDK {
+  constructor(options: CloudSyncSDKOptions = {}) {
+    bindAccountChannel(options)
+    const clientOptions: ClientOptions = {
+      baseUrl: options.baseUrl ?? options.serviceBaseUrl,
+      fetch: options.fetch,
+      now: options.now,
+      syncTokenCache: options.syncTokenCache,
+      onSyncTokenUpdate: options.onSyncTokenUpdate,
+      onHandshake: options.onHandshake,
+      onStepUpRequired: options.onStepUpRequired,
+      formDataFactory: options.formDataFactory,
+      getAuthToken: () => resolveAuthToken(options),
+      getDeviceId: () => resolveDeviceId(options),
+    }
+    super(clientOptions)
+  }
+
+  async push(items: SyncItemInput[]): Promise<PushResponse> {
+    const response = await super.push(items)
+    await accountSDK.recordSyncActivity('push')
+    return response
+  }
+
+  async pull(params?: { cursor?: number, limit?: number }): Promise<PullResponse> {
+    const response = await super.pull(params)
+    await accountSDK.recordSyncActivity('pull')
+    return response
+  }
+}
+
+let cachedSDK: CloudSyncSDK | null = null
+
+export function createCloudSyncSDK(options?: CloudSyncSDKOptions): CloudSyncSDK {
+  return new CloudSyncSDK(options)
+}
+
+export function useCloudSyncSDK(options?: CloudSyncSDKOptions): CloudSyncSDK {
+  if (!cachedSDK)
+    cachedSDK = new CloudSyncSDK(options)
+  return cachedSDK
+}
+
+export function resetCloudSyncSDK(): void {
+  cachedSDK = null
+}
+
+export { CloudSyncError }

package/plugin/sdk/common.ts

@@ -5,7 +5,10 @@
  * 提供插件SDK的通用功能，包括通信、快捷键等
  */
 
-import { genChannel } from '../channel'
+import { getLogger } from '../../common/logger'
+import { useChannel } from './channel'
+
+const sdkLog = getLogger('plugin-sdk')
 
 /**
  * Register a shortcut
@@ -13,16 +16,21 @@ import { genChannel } from '../channel'
  * @param func - The trigger function
  * @returns Whether the shortcut is registered successfully
  */
-export function regShortcut(key: string, func: Function): boolean {
-  const channel = genChannel()
+export async function regShortcut(key: string, func: () => void): Promise<boolean> {
+  const channel = useChannel('[Plugin SDK] Shortcut registration requires renderer channel.')
 
-  const res = channel.sendSync('shortcon:reg', { key })
-  if (res instanceof String)
+  const res = await channel.send('shortcon:reg', { key })
+  if (typeof res === 'string' || Object.prototype.toString.call(res) === '[object String]')
     throw new Error(String(res))
   if (res === false)
     return false
 
-  channel.regChannel('shortcon:trigger', ({ data }) => key === data.key && func())
+  channel.regChannel('shortcon:trigger', ({ data }) => {
+    const payload = data as { key?: string, id?: string } | undefined
+    const triggerKey = payload?.key ?? payload?.id
+    if (triggerKey === key)
+      func()
+  })
 
   return true
 }
@@ -37,7 +45,7 @@ export async function communicateWithPlugin(
   key: string,
   info: any = {},
 ): Promise<any> {
-  const channel = genChannel()
+  const channel = useChannel('[Plugin SDK] Communication requires renderer channel.')
 
   try {
     return await channel.send('index:communicate', {
@@ -46,7 +54,7 @@ export async function communicateWithPlugin(
     })
   }
   catch (error) {
-    console.error(`[Plugin SDK] Failed to communicate`, error)
+    sdkLog.error('Failed to communicate', { error })
     throw error
   }
 }
@@ -58,13 +66,13 @@ export async function communicateWithPlugin(
  * @returns Promise<any> The message result
  */
 export async function sendMessage(message: string, data: any = {}): Promise<any> {
-  const channel = genChannel()
+  const channel = useChannel('[Plugin SDK] Messaging requires renderer channel.')
 
   try {
     return await channel.send(`plugin:${message}`, data)
   }
   catch (error) {
-    console.error(`[Plugin SDK] Failed to send message: ${message}`, error)
+    sdkLog.error(`Failed to send message: ${message}`, { error })
     throw error
   }
 }
@@ -75,7 +83,7 @@ export async function sendMessage(message: string, data: any = {}): Promise<any>
  * @returns The channel object for the plugin
  */
 export function getChannel() {
-  return genChannel()
+  return useChannel('[Plugin SDK] Channel requires renderer context.')
 }
 
 export * from './window'

package/plugin/sdk/core-box.ts

@@ -1,20 +1,11 @@
-import type { IPluginRendererChannel } from './types'
+import { useChannel } from './channel'
+import { usePluginName } from './plugin-info'
 
-function ensurePluginContext(): { channel: IPluginRendererChannel, pluginName: string } {
-  const plugin = (window as any)?.$plugin
-  if (!plugin?.name) {
-    throw new Error('[TouchSDK] Unable to resolve plugin name inside renderer context.')
-  }
+function ensurePluginContext(): { channel: ReturnType<typeof useChannel>, pluginName: string } {
+  const pluginName = usePluginName('[TouchSDK] Unable to resolve plugin name inside renderer context.')
+  const channel = useChannel('[TouchSDK] Channel bridge is not available for the current plugin renderer.')
 
-  const channel = (window as any)?.$channel as IPluginRendererChannel | undefined
-  if (!channel) {
-    throw new Error('[TouchSDK] Channel bridge is not available for the current plugin renderer.')
-  }
-
-  return {
-    channel,
-    pluginName: plugin.name as string,
-  }
+  return { channel, pluginName }
 }
 
 /**