@talex-touch/utils 1.0.42 → 1.0.45

package/plugin/sdk/plugin-info.ts

@@ -0,0 +1,64 @@
+import { getCurrentInstance } from 'vue'
+import { hasWindow } from '../../env'
+
+export interface PluginRuntimeInfo {
+  name?: string
+  sdkapi?: number
+  [key: string]: unknown
+}
+
+const DEFAULT_PLUGIN_INFO_ERROR
+  = '[Plugin SDK] Plugin info not available. Make sure this is called in a plugin context.'
+
+const DEFAULT_PLUGIN_NAME_ERROR
+  = '[Plugin SDK] Cannot determine plugin name. Make sure this is called in a plugin context.'
+
+function tryResolvePluginInfoFromInstance(): PluginRuntimeInfo | null {
+  const instance = getCurrentInstance()
+  if (!instance) {
+    return null
+  }
+
+  const proxy = instance.proxy as { $plugin?: PluginRuntimeInfo } | null
+  if (proxy?.$plugin) {
+    return proxy.$plugin
+  }
+
+  const appPlugin = instance.appContext?.config.globalProperties?.$plugin as PluginRuntimeInfo | undefined
+  return appPlugin ?? null
+}
+
+export function tryUsePluginInfo(): PluginRuntimeInfo | null {
+  const injected = tryResolvePluginInfoFromInstance()
+  if (injected) {
+    return injected
+  }
+
+  if (!hasWindow()) {
+    return null
+  }
+  return (window as any)?.$plugin ?? null
+}
+
+export function usePluginInfo(errorMessage = DEFAULT_PLUGIN_INFO_ERROR): PluginRuntimeInfo {
+  const plugin = tryUsePluginInfo()
+  if (!plugin) {
+    throw new Error(errorMessage)
+  }
+  return plugin
+}
+
+export function usePluginName(errorMessage = DEFAULT_PLUGIN_NAME_ERROR): string {
+  const plugin = usePluginInfo(errorMessage)
+  const name = typeof plugin.name === 'string' ? plugin.name : undefined
+  if (!name) {
+    throw new Error(errorMessage)
+  }
+  return name
+}
+
+export function tryGetPluginSdkApi(): number | undefined {
+  const plugin = tryUsePluginInfo()
+  const sdkapi = plugin?.sdkapi
+  return typeof sdkapi === 'number' ? sdkapi : undefined
+}

package/plugin/sdk/power.ts

@@ -0,0 +1,155 @@
+import type { ITouchClientChannel } from '@talex-touch/utils/channel'
+import type { BatteryStatusPayload, FileIndexBatteryStatus } from '../../transport/events'
+import { AppEvents } from '../../transport/events'
+import { createPluginTuffTransport } from '../../transport/sdk/plugin-transport'
+import { ensureRendererChannel } from './channel'
+
+const DEFAULT_LOW_POWER_THRESHOLD = 20
+
+function normalizeThreshold(threshold?: number): number {
+  if (typeof threshold !== 'number' || !Number.isFinite(threshold)) {
+    return DEFAULT_LOW_POWER_THRESHOLD
+  }
+
+  const normalized = Math.floor(threshold)
+  if (normalized <= 0) return 1
+  if (normalized > 100) return 100
+  return normalized
+}
+
+function normalizePercent(percent: unknown): number | null {
+  if (typeof percent !== 'number' || !Number.isFinite(percent)) {
+    return null
+  }
+
+  if (percent < 0) return 0
+  if (percent > 100) return 100
+  return percent
+}
+
+function toStatusFromBattery(
+  battery: FileIndexBatteryStatus | null | undefined,
+  threshold: number
+): LowPowerStatus {
+  const percent = normalizePercent(battery?.level)
+  const onBattery = percent !== null ? battery?.charging === false : false
+
+  return {
+    lowPower: onBattery && percent !== null && percent <= threshold,
+    onBattery,
+    percent,
+    threshold
+  }
+}
+
+function toStatusFromBroadcast(
+  payload: BatteryStatusPayload | undefined,
+  threshold: number
+): LowPowerStatus | null {
+  if (typeof payload?.onBattery !== 'boolean') {
+    return null
+  }
+
+  const percent = normalizePercent(payload.percent)
+  const onBattery = payload.onBattery
+
+  return {
+    lowPower: onBattery && percent !== null && percent <= threshold,
+    onBattery,
+    percent,
+    threshold
+  }
+}
+
+function toSignature(status: LowPowerStatus): string {
+  return [status.lowPower, status.onBattery, status.percent ?? 'null', status.threshold].join(':')
+}
+
+export interface LowPowerStatus {
+  lowPower: boolean
+  onBattery: boolean
+  percent: number | null
+  threshold: number
+}
+
+export interface PowerSDK {
+  getLowPowerStatus: (options?: { threshold?: number }) => Promise<LowPowerStatus>
+  isLowPower: (options?: { threshold?: number }) => Promise<boolean>
+  onLowPowerChanged: (
+    callback: (status: LowPowerStatus) => void,
+    options?: { threshold?: number, emitImmediately?: boolean }
+  ) => () => void
+}
+
+export function createPowerSDK(channel: ITouchClientChannel): PowerSDK {
+  const transport = createPluginTuffTransport(channel)
+
+  const getStatus = async (options: { threshold?: number } = {}): Promise<LowPowerStatus> => {
+    const threshold = normalizeThreshold(options.threshold)
+    try {
+      const battery = await transport.send(AppEvents.fileIndex.batteryLevel)
+      return toStatusFromBattery(battery, threshold)
+    }
+    catch {
+      return {
+        lowPower: false,
+        onBattery: false,
+        percent: null,
+        threshold
+      }
+    }
+  }
+
+  return {
+    getLowPowerStatus: getStatus,
+
+    async isLowPower(options: { threshold?: number } = {}): Promise<boolean> {
+      const status = await getStatus(options)
+      return status.lowPower
+    },
+
+    onLowPowerChanged(
+      callback: (status: LowPowerStatus) => void,
+      options: { threshold?: number, emitImmediately?: boolean } = {}
+    ): () => void {
+      const threshold = normalizeThreshold(options.threshold)
+      let disposed = false
+      let lastSignature = ''
+
+      const emit = async (status: LowPowerStatus, force = false) => {
+        if (disposed) return
+        const signature = toSignature(status)
+        if (!force && signature === lastSignature) return
+        lastSignature = signature
+        callback(status)
+      }
+
+      const dispose = transport.on(AppEvents.power.batteryStatus, async (payload) => {
+        const fromBroadcast = toStatusFromBroadcast(payload, threshold)
+        if (fromBroadcast) {
+          await emit(fromBroadcast)
+          return
+        }
+
+        const fromQuery = await getStatus({ threshold })
+        await emit(fromQuery)
+      })
+
+      if (options.emitImmediately !== false) {
+        void getStatus({ threshold }).then((status) => emit(status, true))
+      }
+
+      return () => {
+        disposed = true
+        dispose()
+      }
+    }
+  }
+}
+
+export function usePowerSDK(): PowerSDK {
+  const channel = ensureRendererChannel(
+    '[PowerSDK] Channel not available. Make sure this is called in a plugin renderer context.'
+  )
+  return createPowerSDK(channel)
+}

package/plugin/sdk/recommend.ts

@@ -0,0 +1,21 @@
+import type { RecommendProvider } from '../../core-box/recommendation'
+
+/**
+ * SDK for plugins to register custom recommendation providers.
+ *
+ * Providers registered through this SDK will be called by the RecommendationEngine
+ * when generating recommendations for the CoreBox empty-query state.
+ */
+export interface RecommendSDK {
+  /**
+   * Register a recommendation provider.
+   * @returns A dispose function to unregister the provider.
+   */
+  registerProvider(provider: RecommendProvider): () => void
+
+  /**
+   * Unregister a recommendation provider by its ID.
+   * @returns true if the provider was found and removed.
+   */
+  unregisterProvider(providerId: string): boolean
+}

package/plugin/sdk/service/index.ts

@@ -1,8 +1,11 @@
 import type { IService } from '../../../service'
-import { genChannel } from '../../channel'
+import { useChannel } from '../channel'
 
-export function regService(service: IService, handler: Function): boolean {
-  const res = !!genChannel().sendSync('service:reg', { service: service.name })
+type ServiceHandler = (data: any) => unknown
+
+export async function regService(service: IService, handler: ServiceHandler): Promise<boolean> {
+  const channel = useChannel('[Plugin SDK] Service registration requires renderer channel.')
+  const res = !!(await channel.send('service:reg', { service: service.name }))
 
   if (res)
     onHandleService(service, handler)
@@ -10,13 +13,14 @@ export function regService(service: IService, handler: Function): boolean {
   return res
 }
 
-export function unRegService(service: IService): boolean {
-  return !!genChannel().sendSync('service:unreg', { service: service.name })
+export async function unRegService(service: IService): Promise<boolean> {
+  const channel = useChannel('[Plugin SDK] Service unregistration requires renderer channel.')
+  return !!(await channel.send('service:unreg', { service: service.name }))
 }
 
-export function onHandleService(service: IService, handler: Function) {
-  // @ts-ignore
-  genChannel().regChannel('service:handle', ({ data: _data }) => {
+export function onHandleService(service: IService, handler: ServiceHandler) {
+  const channel = useChannel('[Plugin SDK] Service handling requires renderer channel.')
+  channel.regChannel('service:handle', ({ data: _data }) => {
     const { data } = _data
 
     // console.log('service:handle', data, service)

package/plugin/sdk/sqlite.ts

@@ -0,0 +1,141 @@
+import { ensureRendererChannel } from './channel'
+import { usePluginName } from './plugin-info'
+
+export interface PluginSqliteStatement {
+  sql: string
+  params?: unknown[]
+}
+
+export interface PluginSqliteExecuteResult {
+  rowsAffected: number
+  lastInsertRowId: number | null
+}
+
+export interface PluginSqliteQueryResult<T extends Record<string, unknown>> {
+  rows: T[]
+  columns: string[]
+}
+
+export interface PluginSqliteTransactionResult {
+  results: PluginSqliteExecuteResult[]
+}
+
+function normalizeSql(sql: string): string {
+  return typeof sql === 'string' ? sql.trim() : ''
+}
+
+function normalizeParams(params?: unknown[]): unknown[] {
+  return Array.isArray(params) ? params : []
+}
+
+export function usePluginSqlite() {
+  const pluginName = usePluginName(
+    '[Plugin SQLite SDK] Cannot determine plugin name. Make sure this is called in a plugin context.'
+  )
+  const channel = ensureRendererChannel(
+    '[Plugin SQLite SDK] Channel not available. Make sure this is called in a plugin context.'
+  )
+
+  return {
+    execute: async (
+      sql: string,
+      params?: unknown[]
+    ): Promise<PluginSqliteExecuteResult> => {
+      const normalizedSql = normalizeSql(sql)
+      if (!normalizedSql) {
+        throw new Error('[Plugin SQLite SDK] SQL is required.')
+      }
+
+      const response = await channel.send('plugin:sqlite:execute', {
+        pluginName,
+        sql: normalizedSql,
+        params: normalizeParams(params)
+      })
+
+      if (!response || typeof response !== 'object' || (response as { success?: unknown }).success !== true) {
+        const error =
+          response && typeof response === 'object' && 'error' in response
+            ? String((response as { error?: unknown }).error ?? 'Unknown error')
+            : 'Unknown error'
+        throw new Error(`[Plugin SQLite SDK] Execute failed: ${error}`)
+      }
+
+      return {
+        rowsAffected: Number((response as { rowsAffected?: unknown }).rowsAffected ?? 0),
+        lastInsertRowId:
+          typeof (response as { lastInsertRowId?: unknown }).lastInsertRowId === 'number'
+            ? Math.trunc((response as { lastInsertRowId?: number }).lastInsertRowId ?? 0)
+            : null
+      }
+    },
+
+    query: async <T extends Record<string, unknown> = Record<string, unknown>>(
+      sql: string,
+      params?: unknown[]
+    ): Promise<PluginSqliteQueryResult<T>> => {
+      const normalizedSql = normalizeSql(sql)
+      if (!normalizedSql) {
+        throw new Error('[Plugin SQLite SDK] SQL is required.')
+      }
+
+      const response = await channel.send('plugin:sqlite:query', {
+        pluginName,
+        sql: normalizedSql,
+        params: normalizeParams(params)
+      })
+
+      if (!response || typeof response !== 'object' || (response as { success?: unknown }).success !== true) {
+        const error =
+          response && typeof response === 'object' && 'error' in response
+            ? String((response as { error?: unknown }).error ?? 'Unknown error')
+            : 'Unknown error'
+        throw new Error(`[Plugin SQLite SDK] Query failed: ${error}`)
+      }
+
+      return {
+        rows: Array.isArray((response as { rows?: unknown }).rows)
+          ? ((response as { rows: T[] }).rows)
+          : [],
+        columns: Array.isArray((response as { columns?: unknown }).columns)
+          ? ((response as { columns: string[] }).columns)
+          : []
+      }
+    },
+
+    transaction: async (
+      statements: PluginSqliteStatement[]
+    ): Promise<PluginSqliteTransactionResult> => {
+      if (!Array.isArray(statements) || statements.length === 0) {
+        throw new Error('[Plugin SQLite SDK] Transaction statements are required.')
+      }
+
+      const payload = statements.map((statement) => ({
+        sql: normalizeSql(statement.sql),
+        params: normalizeParams(statement.params)
+      }))
+
+      if (payload.some((statement) => !statement.sql)) {
+        throw new Error('[Plugin SQLite SDK] Each transaction statement must include SQL.')
+      }
+
+      const response = await channel.send('plugin:sqlite:transaction', {
+        pluginName,
+        statements: payload
+      })
+
+      if (!response || typeof response !== 'object' || (response as { success?: unknown }).success !== true) {
+        const error =
+          response && typeof response === 'object' && 'error' in response
+            ? String((response as { error?: unknown }).error ?? 'Unknown error')
+            : 'Unknown error'
+        throw new Error(`[Plugin SQLite SDK] Transaction failed: ${error}`)
+      }
+
+      const results = Array.isArray((response as { results?: unknown }).results)
+        ? (response as { results: PluginSqliteExecuteResult[] }).results
+        : []
+
+      return { results }
+    }
+  }
+}

package/plugin/sdk/storage.ts

@@ -1,5 +1,6 @@
 import type { FileDetails, StorageStats, StorageTreeNode } from '../../types/storage'
 import { ensureRendererChannel } from './channel'
+import { usePluginName } from './plugin-info'
 
 /**
  * Get the storage for the current plugin.
@@ -9,12 +10,7 @@ import { ensureRendererChannel } from './channel'
  * @returns An object with methods to interact with the storage.
  */
 export function usePluginStorage() {
-  // @ts-ignore
-  const pluginName = window.$plugin.name as string
-
-  if (!pluginName) {
-    throw new Error('[Plugin SDK] Cannot determine plugin name. Make sure this is called in a plugin context.')
-  }
+  const pluginName = usePluginName('[Plugin SDK] Cannot determine plugin name. Make sure this is called in a plugin context.')
 
   const channel = ensureRendererChannel('[Plugin Storage] Channel not available. Make sure this is called in a plugin context.')
 

package/plugin/sdk/system.ts

@@ -1,14 +1,7 @@
 import type { ActiveAppSnapshot } from './types'
-
-function ensurePluginChannel() {
-  const channel = (window as any)?.$channel
-  if (!channel) {
-    throw new Error('[Plugin SDK] System channel requires plugin renderer context with $channel available.')
-  }
-  return channel
-}
+import { useChannel } from './channel'
 
 export async function getActiveAppSnapshot(options: { forceRefresh?: boolean } = {}): Promise<ActiveAppSnapshot | null> {
-  const channel = ensurePluginChannel()
+  const channel = useChannel('[Plugin SDK] System channel requires plugin renderer context with $channel available.')
   return channel.send('system:get-active-app', options)
 }

package/plugin/sdk/temp-files.ts

@@ -0,0 +1,41 @@
+import { useChannel } from './channel'
+
+export interface TempPluginFileCreateOptions {
+  ext?: string
+  text?: string
+  base64?: string
+  prefix?: string
+  /**
+   * Optional retention in milliseconds.
+   * If omitted, the host will apply a default plugin temp retention policy.
+   */
+  retentionMs?: number
+}
+
+export interface TempPluginFileResult {
+  url: string
+  sizeBytes: number
+  createdAt: number
+}
+
+export function useTempPluginFiles() {
+  const channel = useChannel('[Plugin SDK] Temp files require plugin renderer context with $channel available.')
+
+  return {
+    async create(options: TempPluginFileCreateOptions): Promise<TempPluginFileResult> {
+      const res = await channel.send('temp-file:create', options ?? {})
+      if (!res || typeof res !== 'object') {
+        throw new Error('[Plugin SDK] temp-file:create returned invalid response')
+      }
+      return res as TempPluginFileResult
+    },
+
+    async delete(url: string): Promise<boolean> {
+      const res = await channel.send('temp-file:delete', { url })
+      if (res && typeof res === 'object' && 'success' in res) {
+        return Boolean((res as any).success)
+      }
+      return Boolean(res)
+    },
+  }
+}

package/plugin/sdk/touch-sdk.ts

@@ -0,0 +1,18 @@
+import type { ITouchSDK } from './index'
+import { hasWindow } from '../../env'
+
+const DEFAULT_TOUCH_SDK_ERROR
+  = '[TouchSDK] Touch SDK not available. Make sure this is called in a plugin context.'
+
+let cachedTouchSDK: ITouchSDK | null = null
+
+export function useTouchSDK(errorMessage: string = DEFAULT_TOUCH_SDK_ERROR): ITouchSDK {
+  const globalWindow = hasWindow() ? window : undefined
+  const windowSdk = (globalWindow as any)?.$touchSDK as ITouchSDK | undefined
+  const sdk = windowSdk ?? cachedTouchSDK
+  if (!sdk) {
+    throw new Error(errorMessage)
+  }
+  cachedTouchSDK = sdk
+  return sdk
+}

package/plugin/sdk/types.ts

@@ -6,6 +6,7 @@
 
 import type { ITouchChannel, ITouchClientChannel, StandardChannelData } from '@talex-touch/utils/channel'
 import type { IPluginFeature } from '../index'
+import path from 'node:path'
 
 /**
  * Handler signature for plugin channel events.
@@ -90,6 +91,15 @@ export interface IPluginRendererChannel {
 export interface PluginClipboardItem {
   id?: number
   type: 'text' | 'image' | 'files'
+  /**
+   * Clipboard content:
+   * - text: plain string
+   * - files: JSON string array
+   * - image: defaults to a small preview data URL to keep IPC payload light
+   *
+   * For images, the original asset URL (tfile://...) may be available at:
+   * - `meta.image_original_url`
+   */
   content: string
   thumbnail?: string | null
   rawContent?: string | null
@@ -144,7 +154,6 @@ export interface PluginClipboardSearchResponse {
   pageSize: number
 }
 
-
 export interface ActiveAppSnapshot {
   identifier: string | null
   displayName: string | null
@@ -230,6 +239,24 @@ export interface IPluginUtils {
    */
   feature: import('./feature-sdk').FeatureSDK
 
+  /**
+   * MetaOverlay SDK for registering global actions
+   * @see {@link MetaSDK}
+   */
+  meta: import('./meta-sdk').MetaSDK
+
+  /**
+   * Power SDK for low power status
+   * @see {@link PowerSDK}
+   */
+  power: import('./power').PowerSDK
+
+  /**
+   * Recommend SDK for registering custom recommendation providers
+   * @see {@link RecommendSDK}
+   */
+  recommend: import('./recommend').RecommendSDK
+
   /**
    * Opens a URL in the default browser
    * @param url - The URL to open
@@ -496,14 +523,14 @@ export interface IEventManager {
    * @param event - The event name to listen for
    * @param callback - The callback function to execute when event is emitted
    */
-  on: (event: string, callback: Function) => void
+  on: (event: string, callback: PluginEventHandler) => void
 
   /**
    * Removes an event listener
    * @param event - The event name to stop listening for
    * @param callback - The callback function to remove
    */
-  off: (event: string, callback: Function) => void
+  off: (event: string, callback: PluginEventHandler) => void
 
   /**
    * Emits an event with optional arguments
@@ -513,6 +540,8 @@ export interface IEventManager {
   emit: (event: string, ...args: any[]) => void
 }
 
+export type PluginEventHandler = (...args: any[]) => void
+
 /**
  * Plugin configuration interface
  *
@@ -644,7 +673,6 @@ export function createStorageManager(
   pluginPath: string,
   fse: any,
 ): IStorageManager {
-  const path = require('node:path')
   const dataPath = path.join(pluginPath, 'data')
 
   /**
@@ -954,6 +982,18 @@ export interface TriggerFeatureRequest {
   query?: string
 }
 
+/**
+ * Register a widget for preview or rendering
+ */
+export interface RegisterWidgetRequest {
+  /** Plugin name */
+  plugin: string
+  /** Feature ID */
+  feature: string
+  /** Emit update event even if cached */
+  emitAsUpdate?: boolean
+}
+
 /**
  * Input changed event payload
  */

package/plugin/sdk/window/index.ts

@@ -3,28 +3,31 @@ import type {
   BrowserWindowConstructorOptions,
   WebContents,
 } from 'electron'
-import { genChannel } from '../../channel'
+import { useChannel } from '../channel'
 
-export function createWindow(options: BrowserWindowConstructorOptions & { file?: string } & { url?: string }): number {
-  const res = genChannel().sendSync('window:new', options)
+export async function createWindow(
+  options: BrowserWindowConstructorOptions & { file?: string } & { url?: string },
+): Promise<number> {
+  const channel = useChannel('[Plugin SDK] Window creation requires renderer channel.')
+  const res = await channel.send('window:new', options)
   if (res.error)
     throw new Error(res.error)
 
   return res.id
 }
 
-export function toggleWinVisible(id: number, visible?: boolean): boolean {
-  const res = genChannel().sendSync('window:visible', visible !== undefined ? { id, visible } : { id })
+export async function toggleWinVisible(id: number, visible?: boolean): Promise<boolean> {
+  const channel = useChannel('[Plugin SDK] Window visibility requires renderer channel.')
+  const res = await channel.send('window:visible', visible !== undefined ? { id, visible } : { id })
   if (res.error)
     throw new Error(res.error)
 
   return res.visible
 }
 
-export function setWindowProperty(id: number, property: {
-
-}): boolean {
-  const res = genChannel().sendSync('window:property', { id, property })
+export async function setWindowProperty(id: number, property: WindowProperties): Promise<boolean> {
+  const channel = useChannel('[Plugin SDK] Window property requires renderer channel.')
+  const res = await channel.send('window:property', { id, property })
   if (res.error)
     throw new Error(res.error)