@talex-touch/utils 1.0.18 → 1.0.21

package/plugin/plugin-source.ts

@@ -0,0 +1,74 @@
+import { IManifest } from '@talex-touch/utils/plugin'
+
+/**
+ * Interface for plugin download options.
+ */
+export interface IDownloadOptions {
+  /**
+   * Timeout configuration for download in milliseconds.
+   */
+  timeout?: number;
+  /**
+   * List of fallback download URLs.
+   */
+  fallbackUrls?: string[];
+  /**
+   * Callback function for download progress, with progress value (0-100).
+   */
+  onProgress?: (progress: number) => void;
+}
+
+/**
+ * Interface for plugin download results.
+ */
+export interface IDownloadResult {
+  /**
+   * Local file path after download, which can be the plugin's compressed package or the unzipped folder path.
+   */
+  filePath?: string;
+}
+
+/**
+ * Interface for options when resolving a plugin manifest.
+ */
+export interface IResolveManifestOptions {
+  // Add any future resolution options here, e.g., caching strategy, network request configuration.
+}
+
+/**
+ * Abstract interface for a plugin source. Defines how to resolve and download plugins.
+ */
+export interface IPluginSource {
+  /**
+   * Get the name of the plugin source.
+   * @returns The name of the plugin source.
+   */
+  getSourceName(): string;
+  /**
+   * Get the description of the plugin source.
+   * @returns The description of the plugin source.
+   */
+  getSourceDesc(): string;
+  /**
+   * Timestamp of the last update for this plugin source.
+   */
+  lastUpdateTime?: number;
+
+  /**
+   * Attempts to resolve a plugin manifest from the specified path or URL.
+   * If resolution is successful, returns an IManifest; otherwise, returns undefined.
+   * The returned result must be a plugin manifest object conforming to the IManifest format.
+   * @param sourcePath The root directory path or URL of the plugin.
+   * @param options Resolution options.
+   * @returns A Promise containing the plugin manifest, or undefined if resolution fails.
+   */
+  resolveManifest(sourcePath: string, options?: IResolveManifestOptions): Promise<IManifest | undefined>
+
+  /**
+   * Downloads the plugin source.
+   * @param sourceUrl The URL of the plugin source.
+   * @param options Download options.
+   * @returns A Promise containing the download result. The filePath must be the path to the plugin's compressed package or unzipped folder.
+   */
+  downloadPlugin(sourceUrl: string, options?: IDownloadOptions): Promise<IDownloadResult>
+}

package/plugin/preload.ts

@@ -1,4 +1,4 @@
-import { genChannel } from './channel'
+import type { ITouchClientChannel } from '../channel'
 import './sdk/index'
 
 // window type
@@ -8,9 +8,7 @@ declare global {
       name: string
       path: Object
     }
-    $send: (type: string, data: any) => void
-    $sendSync: (type: string, data: any) => Promise<any>
-    $regChannel: (type: string, callback: Function) => void
+    $channel: ITouchClientChannel
     $crash: (message: string, extraData: any) => void
     $config: {
       themeStyle: any
@@ -18,22 +16,14 @@ declare global {
   }
 }
 
-export function init(window: Window) {
+export function initTuff(window: Window) {
   const plugin = window.$plugin
   if (!plugin)
     throw new Error('Plugin has a fatal error! Please check your plugin!')
 
   window.$crash = function (message, extraData) {
-    window.$send('crash', { message, ...extraData })
+    window.$channel.send('crash', { message, ...extraData })
   }
 
-  initBridge(window)
-}
-
-export function initBridge(window: Window) {
-  const touchChannel = genChannel()
-
-  window.$send = touchChannel.send.bind(touchChannel)
-  window.$sendSync = touchChannel.sendSync.bind(touchChannel)
-  window.$regChannel = touchChannel.regChannel.bind(touchChannel)
+  console.log(`%c[Plugin] ${plugin.name} loaded`, 'color: #42b983')
 }

package/plugin/providers/index.ts

@@ -0,0 +1,2 @@
+export * from './registry'
+export * from './types'

package/plugin/providers/registry.ts

@@ -0,0 +1,47 @@
+import { defaultRiskPromptHandler } from '../risk'
+import type { PluginInstallRequest, PluginInstallResult, PluginProvider, PluginProviderContext } from './types'
+
+class ProviderRegistry {
+  private providers: PluginProvider[] = []
+
+  register(provider: PluginProvider): void {
+    if (this.providers.some((item) => item.type === provider.type)) {
+      throw new Error(`Plugin provider '${provider.type}' already registered`)
+    }
+    this.providers.push(provider)
+  }
+
+  unregister(type: PluginProvider['type']): void {
+    this.providers = this.providers.filter((item) => item.type !== type)
+  }
+
+  clear(): void {
+    this.providers = []
+  }
+
+  resolve(request: PluginInstallRequest): PluginProvider | undefined {
+    return this.providers.find((provider) => provider.canHandle(request))
+  }
+
+  async install(
+    request: PluginInstallRequest,
+    context: PluginProviderContext = {}
+  ): Promise<PluginInstallResult | undefined> {
+    const provider = this.resolve(request)
+    if (!provider) return undefined
+
+    const composedContext: PluginProviderContext = {
+      riskPrompt: defaultRiskPromptHandler,
+      ...context
+    }
+
+    if (!composedContext.riskPrompt) {
+      composedContext.riskPrompt = defaultRiskPromptHandler
+    }
+
+    return provider.install(request, composedContext)
+  }
+}
+
+export const pluginProviderRegistry = new ProviderRegistry()
+export type { PluginProvider } from './types'

package/plugin/providers/types.ts

@@ -0,0 +1,54 @@
+import type { IDownloadOptions, IDownloadResult } from '../plugin-source'
+import type { IManifest } from '..'
+import type { RiskPromptHandler } from '../risk'
+
+export enum PluginProviderType {
+  GITHUB = 'github',
+  NPM = 'npm',
+  TPEX = 'tpex',
+  FILE = 'file',
+  DEV = 'dev'
+}
+
+export interface PluginInstallRequest {
+  /** 用户输入或配置的原始地址，例如 repo URL、npm 包名、文件路径等。 */
+  source: string
+  /** 额外提示信息，例如指定 provider 类型或版本。 */
+  hintType?: PluginProviderType
+  /** 可选元数据，在调用链中透传。 */
+  metadata?: Record<string, unknown>
+}
+
+export interface PluginProviderContext {
+  /** 下载配置，例如进度回调、超时时间等。 */
+  downloadOptions?: IDownloadOptions
+  /** 风险提示处理器，未提供时默认为自动通过。 */
+  riskPrompt?: RiskPromptHandler
+  /** 提供缓存或临时目录位置。 */
+  tempDir?: string
+}
+
+export interface PluginInstallResult extends IDownloadResult {
+  /** provider 类型，便于后续逻辑分支。 */
+  provider: PluginProviderType
+  /** 是否经过官方认证或白名单。 */
+  official?: boolean
+  /** 解析得到的 manifest；某些 provider 可能只提供压缩包路径。 */
+  manifest?: IManifest
+  /** 附加信息，例如使用的 tag、branch 等。 */
+  metadata?: Record<string, unknown>
+}
+
+export interface PluginProvider {
+  readonly type: PluginProviderType
+  canHandle(request: PluginInstallRequest): boolean
+  install(
+    request: PluginInstallRequest,
+    context?: PluginProviderContext
+  ): Promise<PluginInstallResult>
+}
+
+export interface PluginInstallSummary {
+  manifest?: IManifest
+  providerResult: PluginInstallResult
+}

package/plugin/risk/index.ts

@@ -0,0 +1 @@
+export * from './types'

package/plugin/risk/types.ts

@@ -0,0 +1,20 @@
+export type RiskLevel = 'trusted' | 'needs_confirmation' | 'blocked'
+
+export interface RiskPromptInput {
+  /** 资源来源标识，例如 provider 类型。 */
+  sourceType: string
+  /** 用户可识别的资源名称或路径。 */
+  sourceId: string
+  /** 风险等级，用于决定是否需要拦截或弹窗确认。 */
+  level: RiskLevel
+  /** 供 UI 展示的标题。 */
+  title?: string
+  /** 供 UI 展示的详细描述。 */
+  description?: string
+  /** 附加元数据，方便调用方扩展。 */
+  metadata?: Record<string, unknown>
+}
+
+export type RiskPromptHandler = (input: RiskPromptInput) => Promise<boolean>
+
+export const defaultRiskPromptHandler: RiskPromptHandler = async () => true

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

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

package/plugin/sdk/enum/index.ts

@@ -0,0 +1 @@
+export * from './bridge-event'

package/plugin/sdk/hooks/bridge.ts

@@ -0,0 +1,68 @@
+import { BridgeEventForCoreBox } from '../enum/bridge-event'
+
+export type BridgeEvent = BridgeEventForCoreBox
+
+/**
+ * Defines the shape of a bridge hook function.
+ * @template T The type of data the hook will receive.
+ */
+export type BridgeHook<T = any> = (data: T) => void
+
+const __hooks: Record<BridgeEvent, Array<BridgeHook>> = {
+  [BridgeEventForCoreBox.CORE_BOX_INPUT_CHANGE]: [],
+}
+
+/**
+ * Injects a hook for a given bridge event.
+ * @param type The bridge event type.
+ * @param hook The hook function to inject.
+ * @returns The wrapped hook function.
+ * @internal
+ * @template T The type of data the hook will receive.
+ */
+export function injectBridgeEvent<T>(type: BridgeEvent, hook: BridgeHook<T>) {
+  const hooks: Array<BridgeHook<T>> = __hooks[type] || (__hooks[type] = [])
+
+  // Only register the channel listener once per event type
+  if (hooks.length === 0) {
+    window.$channel.regChannel(type, ({ data }) => {
+      console.debug(`[TouchSDK] ${type} event received: `, data)
+      // When the event is received, call all registered hooks for this type
+      const registeredHooks = __hooks[type]
+      if (registeredHooks) {
+        registeredHooks.forEach(h => h(data))
+      }
+    })
+  }
+
+  const wrappedHook = (data: T) => {
+
+    try {
+
+      hook(data)
+
+    } catch (e) {
+      console.error(`[TouchSDK] ${type} hook error: `, e)
+    }
+
+  }
+
+  hooks.push(wrappedHook)
+
+  return wrappedHook
+}
+
+/**
+ * Creates a hook for a given bridge event.
+ * @param type The bridge event type.
+ * @returns A function that takes a hook function and injects it.
+ * @template T The type of data the hook will receive.
+ */
+export const createBridgeHook = <T>(type: BridgeEvent) => (hook: BridgeHook<T>) => injectBridgeEvent<T>(type, hook)
+
+/**
+ * Hook for when the core box input changes.
+ * The hook receives the new input value as a string.
+ * @param data The input change data (string).
+ */
+export const onCoreBoxInputChange = createBridgeHook<{ query: string }>(BridgeEventForCoreBox.CORE_BOX_INPUT_CHANGE)

package/plugin/sdk/hooks/index.ts

@@ -1 +1,2 @@
-export * as LifeCycle from './life-cycle'
+export * as LifeCycle from './life-cycle'
+export * from './bridge'

package/plugin/sdk/hooks/life-cycle.ts

@@ -1,5 +1,3 @@
-import { genChannel } from './../../channel';
-
 export enum LifecycleHooks {
   ENABLE = 'en',
   DISABLE = 'di',
@@ -25,7 +23,7 @@ export function injectHook(type: LifecycleHooks, hook: Function, processFunc = (
 
   if (hooks.length === 0) {
 
-    genChannel().regChannel("@lifecycle:" + type, (obj: any) => {
+    window.$channel.regChannel("@lifecycle:" + type, (obj: any) => {
 
       processFunc(obj)
 
@@ -93,4 +91,4 @@ export const onPluginInactive = createHook(LifecycleHooks.INACTIVE)
  * data.extraData Crash data
  * @returns void
  */
-export const onCrash = createHook(LifecycleHooks.CRASH)
+export const onCrash = createHook(LifecycleHooks.CRASH)

package/plugin/sdk/index.ts

@@ -16,3 +16,5 @@ export * from './types'
 export * from './window/index'
 export * from './hooks/index'
 export * from './service/index'
+
+export * from './storage'

package/plugin/sdk/storage.ts

@@ -0,0 +1,84 @@
+/**
+ * Get the storage for the current plugin.
+ * It provides a simple key-value store that is persisted across application launches.
+ * The data is stored in a JSON file in the application's support directory.
+ * Each plugin has its own separate storage file.
+ *
+ * @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 channel = window.$channel
+
+  return {
+    /**
+     * Retrieves an item from the storage.
+     * @param key The key of the item to retrieve.
+     * @returns A promise that resolves with the value of the item, or null if the item does not exist.
+     */
+    getItem: async (key: string): Promise<any> => {
+      return channel.send('plugin:storage:get-item', { pluginName, key })
+    },
+
+    /**
+     * Stores an item in the storage.
+     * @param key The key of the item to store.
+     * @param value The value of the item to store.
+     * @returns A promise that resolves when the item has been stored.
+     */
+    setItem: async (key: string, value: any): Promise<{ success: boolean, error?: string }> => {
+      return channel.send('plugin:storage:set-item', { pluginName, key, value: JSON.parse(JSON.stringify(value)) })
+    },
+
+    /**
+     * Removes an item from the storage.
+     * @param key The key of the item to remove.
+     * @returns A promise that resolves when the item has been removed.
+     */
+    removeItem: async (key: string): Promise<{ success: boolean, error?: string }> => {
+      return channel.send('plugin:storage:remove-item', { pluginName, key })
+    },
+
+    /**
+     * Clears all items from the storage for the current plugin.
+     * @returns A promise that resolves when the storage has been cleared.
+     */
+    clear: async (): Promise<{ success: boolean, error?: string }> => {
+      return channel.send('plugin:storage:clear', { pluginName })
+    },
+
+    /**
+     * Retrieves all items from the storage for the current plugin.
+     * @returns A promise that resolves with an object containing all items.
+     */
+    getAllItems: async (): Promise<Record<string, any>> => {
+      return channel.send('plugin:storage:get-all', { pluginName })
+    },
+
+    /**
+     * Listens for changes to the storage.
+     * When `clear()` is called, the key will be `__clear__`.
+     * @param callback The function to call when the storage changes for the current plugin.
+     * @returns A function to unsubscribe from the listener.
+     */
+    onDidChange: (callback: (data: { name: string, key?: string }) => void) => {
+      const listener = (data: { name: string, key?: string }) => {
+        if (data.name === pluginName) {
+          callback(data)
+        }
+      }
+
+      channel.on('plugin:storage:update', listener)
+
+      return () => {
+        channel.off('plugin:storage:update', listener)
+      }
+    }
+  }
+}

package/plugin/sdk/types.ts

@@ -1,6 +1,6 @@
 /**
- * @fileoverview Plugin SDK utilities and interfaces for Talex Touch plugin development
- * @author Talex Touch Team
+ * @fileoverview Plugin SDK utilities and interfaces for Tuff plugin development
+ * @author Tuff Team
  * @version 1.0.0
  */
 

package/plugin/sdk/window/index.ts

@@ -1,7 +1,9 @@
 import { genChannel } from '../../channel';
-import {
-  BrowserWindowConstructorOptions, BrowserWindow, WebContents
-} from "electron";
+import type {
+  BrowserWindowConstructorOptions,
+  BrowserWindow,
+  WebContents,
+} from 'electron'
 
 export function createWindow(options: BrowserWindowConstructorOptions & { file?: string } & { url?: string }): number {
   const res = genChannel().sendSync('window:new', options)

package/preload/index.ts

@@ -0,0 +1,2 @@
+export * from './loading'
+export * from './renderer'

package/preload/loading.ts

@@ -0,0 +1,15 @@
+export const PRELOAD_LOADING_CHANNEL = '@talex-touch/preload'
+
+export type LoadingMode = 'classic' | 'progress' | 'debug'
+
+export type LoadingState = 'start' | 'finish'
+
+export type LoadingEvent =
+  | { type: 'mode'; mode: LoadingMode }
+  | { type: 'message'; message: string }
+  | { type: 'progress'; delta?: number; reset?: boolean }
+  | { type: 'state'; state: LoadingState }
+
+export interface PreloadAPI {
+  sendPreloadEvent(event: LoadingEvent): void
+}

package/preload/renderer.ts

@@ -0,0 +1,41 @@
+import type { LoadingEvent, LoadingMode, LoadingState, PreloadAPI } from './loading'
+
+function getPreloadApi(): PreloadAPI | null {
+  if (typeof window === 'undefined') return null
+  return window.api ?? null
+}
+
+export function sendPreloadEvent(event: LoadingEvent): void {
+  const api = getPreloadApi()
+  api?.sendPreloadEvent(event)
+}
+
+export function preloadLog(message: string): void {
+  sendPreloadEvent({ type: 'message', message })
+}
+
+export function preloadProgress(delta = 0.05): void {
+  sendPreloadEvent({ type: 'progress', delta })
+}
+
+export function preloadResetProgress(): void {
+  sendPreloadEvent({ type: 'progress', reset: true })
+}
+
+export function preloadSetMode(mode: LoadingMode): void {
+  sendPreloadEvent({ type: 'mode', mode })
+}
+
+export function preloadState(state: LoadingState): void {
+  sendPreloadEvent({ type: 'state', state })
+}
+
+export function preloadDebugStep(message: string, delta = 0.08): void {
+  preloadLog(message)
+  preloadProgress(delta)
+}
+
+export function preloadRemoveOverlay(): void {
+  if (typeof window === 'undefined') return
+  window.postMessage({ payload: 'removeLoading' }, '*')
+}

package/renderer/hooks/arg-mapper.ts

@@ -0,0 +1,79 @@
+
+/**
+ * Interface for command line argument mapper options
+ * @interface IArgMapperOptions
+ */
+export interface IArgMapperOptions {
+  /** The type of touch window - either main window or core-box popup */
+  touchType?: 'main' | 'core-box'
+  /** User data directory path */
+  userDataDir?: string
+  /** Application path */
+  appPath?: string
+  /** Renderer client identifier */
+  rendererClientId?: string
+  /** Launch time ticks value */
+  launchTimeTicks?: string
+  /** Time ticks value */
+  timeTicks?: string
+  /** Additional dynamic string properties */
+  [key: string]: string | undefined
+}
+
+declare global {
+  export interface Window {
+    /** Global argument mapper cache */
+    $argMapper: IArgMapperOptions
+  }
+}
+
+/**
+ * Converts environment arguments into a structured mapper object
+ * @param args - Array of command line arguments (defaults to process.argv)
+ * @returns Mapped command line arguments as key-value pairs
+ */
+export function useArgMapper(args: string[] = process.argv): IArgMapperOptions {
+  if ( window.$argMapper ) {
+    return window.$argMapper
+  }
+
+  const mapper: IArgMapperOptions = {}
+
+  for (const arg of args) {
+    if (arg.startsWith('--') && arg.includes('=')) {
+      const [key, ...valueParts] = arg.slice(2).split('=')
+      const value = valueParts.join('=')
+
+      const camelCaseKey = key.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())
+      mapper[camelCaseKey] = value
+    }
+  }
+
+  return window.$argMapper = mapper
+}
+
+/**
+ * Gets the current touch type from command line arguments
+ * @returns The touch type ('main' | 'core-box') or undefined
+ */
+export function useTouchType() {
+  const argMapper = useArgMapper()
+
+  return argMapper.touchType
+}
+
+/**
+ * Checks if the current window is the main window
+ * @returns True if the current window is the main window
+ */
+export function isMainWindow() {
+  return useTouchType() === 'main'
+}
+
+/**
+ * Checks if the current window is a core-box popup
+ * @returns True if the current window is a core-box popup
+ */
+export function isCoreBox() {
+  return useTouchType() === 'core-box'
+}

package/renderer/hooks/index.ts

@@ -0,0 +1,2 @@
+export * from './arg-mapper'
+export * from './initialize'