@talex-touch/utils 1.0.40 → 1.0.44

package/plugin/sdk/meta-sdk.ts

@@ -0,0 +1,244 @@
+/**
+ * MetaOverlay SDK for Plugin Development
+ *
+ * Provides API for plugins to register global actions in MetaOverlay.
+ * MetaOverlay is a floating action panel that appears above plugin UI.
+ */
+
+import type { TuffItem } from '../../core-box/tuff/tuff-dsl'
+import type { MetaAction } from '../../transport/events/types/meta-overlay'
+import { createPluginTuffTransport } from '../../transport'
+import { defineRawEvent } from '../../transport/event/builder'
+import { MetaOverlayEvents } from '../../transport/events/meta-overlay'
+import { createDisposableBag } from '../../transport/sdk'
+
+/**
+ * Action execution handler
+ */
+export type ActionExecuteHandler = (data: {
+  actionId: string
+  item: TuffItem
+}) => void
+
+const metaOverlayActionExecutedEvent = defineRawEvent<{ pluginId: string, actionId: string, item: TuffItem }, void>('meta-overlay:action-executed')
+
+/**
+ * MetaOverlay SDK interface for plugins
+ *
+ * @example
+ * ```typescript
+ * // Register a global action
+ * const unregister = plugin.meta.registerAction({
+ *   id: 'my-plugin-action',
+ *   render: {
+ *     basic: {
+ *       title: 'My Action',
+ *       subtitle: 'Execute my plugin action',
+ *       icon: { type: 'class', value: 'i-ri-star-line' }
+ *     },
+ *     shortcut: '⌘M',
+ *     group: '插件操作'
+ *   },
+ *   priority: 100
+ * })
+ *
+ * // Listen for action execution
+ * plugin.meta.onActionExecute((data) => {
+ *   if (data.actionId === 'my-plugin-action') {
+ *     // Handle action
+ *   }
+ * })
+ *
+ * // Unregister all actions
+ * plugin.meta.unregisterAll()
+ * ```
+ */
+export interface MetaSDK {
+  /**
+   * Registers a global action that will appear in MetaOverlay
+   *
+   * @param action - Action definition
+   * @returns Cleanup function to unregister this action
+   *
+   * @example
+   * ```typescript
+   * const unregister = plugin.meta.registerAction({
+   *   id: 'custom-action',
+   *   render: {
+   *     basic: {
+   *       title: 'Custom Action',
+   *       subtitle: 'Description',
+   *       icon: { type: 'emoji', value: '🚀' }
+   *     },
+   *     shortcut: '⌘K',
+   *     group: 'Custom'
+   *   },
+   *   priority: 100
+   * })
+   *
+   * // Later: unregister
+   * unregister()
+   * ```
+   */
+  registerAction: (action: MetaAction) => () => void
+
+  /**
+   * Unregisters all actions registered by this plugin
+   *
+   * @example
+   * ```typescript
+   * // Cleanup on plugin unload
+   * plugin.meta.unregisterAll()
+   * ```
+   */
+  unregisterAll: () => void
+
+  /**
+   * Registers a listener for when actions registered by this plugin are executed
+   *
+   * @param handler - Handler function
+   * @returns Cleanup function to remove listener
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = plugin.meta.onActionExecute((data) => {
+   *   console.log(`Action ${data.actionId} executed for item ${data.item.id}`)
+   *   // Handle the action
+   * })
+   *
+   * // Later: unsubscribe
+   * unsubscribe()
+   * ```
+   */
+  onActionExecute: (handler: ActionExecuteHandler) => () => void
+
+  /**
+   * 释放 SDK 内部监听器
+   */
+  dispose: () => void
+}
+
+/**
+ * Creates a MetaSDK instance for plugin use
+ *
+ * @param channel - The plugin channel bridge for IPC communication
+ * @param pluginId - Plugin identifier
+ * @returns Configured MetaSDK instance
+ *
+ * @internal
+ */
+export function createMetaSDK(channel: any, pluginId: string): MetaSDK {
+  const actionExecuteHandlers: Set<ActionExecuteHandler> = new Set()
+  const registeredActionIds: Set<string> = new Set()
+  const transport = createPluginTuffTransport(channel)
+  const disposables = createDisposableBag()
+  let disposed = false
+
+  const emitActionExecute = (data: { pluginId: string, actionId: string, item: TuffItem }) => {
+    if (data.pluginId !== pluginId || !registeredActionIds.has(data.actionId)) {
+      return
+    }
+
+    for (const handler of actionExecuteHandlers) {
+      try {
+        handler({
+          actionId: data.actionId,
+          item: data.item,
+        })
+      }
+      catch (error) {
+        console.error('[MetaSDK] onActionExecute handler error', error)
+      }
+    }
+  }
+
+  const dispose = () => {
+    if (disposed) {
+      return
+    }
+
+    disposed = true
+    actionExecuteHandlers.clear()
+
+    if (registeredActionIds.size > 0) {
+      void transport.send(MetaOverlayEvents.action.unregister, { pluginId }).catch((error) => {
+        console.error('[MetaSDK] Failed to unregister all actions during dispose', error)
+      })
+    }
+
+    registeredActionIds.clear()
+    disposables.dispose()
+    transport.destroy()
+  }
+
+  const ensureActive = (method: string) => {
+    if (disposed) {
+      throw new Error(`[MetaSDK] Cannot call ${method} after dispose`)
+    }
+  }
+
+  disposables.add(
+    transport.on(metaOverlayActionExecutedEvent, (payload) => {
+      emitActionExecute(payload)
+    }),
+  )
+
+  if (typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
+    const onBeforeUnload = () => dispose()
+    window.addEventListener('beforeunload', onBeforeUnload, { once: true })
+    disposables.add(() => window.removeEventListener('beforeunload', onBeforeUnload))
+  }
+
+  return {
+    registerAction(action: MetaAction): () => void {
+      ensureActive('registerAction')
+      registeredActionIds.add(action.id)
+
+      void transport.send(MetaOverlayEvents.action.register, {
+        pluginId,
+        action: {
+          ...action,
+          handler: pluginId,
+          priority: action.priority ?? 100,
+        },
+      }).catch((error) => {
+        console.error('[MetaSDK] Failed to register action', error)
+      })
+
+      return () => {
+        if (!registeredActionIds.has(action.id)) {
+          return
+        }
+
+        registeredActionIds.delete(action.id)
+        void transport.send(MetaOverlayEvents.action.unregister, {
+          pluginId,
+          actionId: action.id,
+        } as any).catch((error) => {
+          console.error('[MetaSDK] Failed to unregister action', error)
+        })
+      }
+    },
+
+    unregisterAll(): void {
+      ensureActive('unregisterAll')
+      registeredActionIds.clear()
+
+      void transport.send(MetaOverlayEvents.action.unregister, {
+        pluginId,
+      }).catch((error) => {
+        console.error('[MetaSDK] Failed to unregister all actions', error)
+      })
+    },
+
+    onActionExecute(handler: ActionExecuteHandler): () => void {
+      ensureActive('onActionExecute')
+      actionExecuteHandlers.add(handler)
+      return () => {
+        actionExecuteHandlers.delete(handler)
+      }
+    },
+
+    dispose,
+  }
+}

package/plugin/sdk/notification.ts

@@ -0,0 +1,9 @@
+import { createNotificationSdk } from '../../transport/sdk/domains/notification'
+import { createPluginTuffTransport } from '../../transport/sdk/plugin-transport'
+import { useChannel } from './channel'
+
+export function useNotificationSdk() {
+  const channel = useChannel()
+  const transport = createPluginTuffTransport(channel)
+  return createNotificationSdk(transport)
+}

package/plugin/sdk/performance.ts

@@ -5,24 +5,9 @@
  * and storage statistics.
  */
 import type { ITouchClientChannel } from '@talex-touch/utils/channel'
+import type { StorageStats } from '../../types/storage'
 import { ensureRendererChannel } from './channel'
 
-/**
- * Storage statistics interface
- */
-export interface StorageStats {
-  /** Total size in bytes */
-  totalSize: number
-  /** Number of files */
-  fileCount: number
-  /** Number of directories */
-  dirCount: number
-  /** Maximum allowed size in bytes */
-  maxSize: number
-  /** Usage percentage (0-100) */
-  usagePercent: number
-}
-
 /**
  * Performance metrics interface
  */

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 }
+    }
+  }
+}