@talex-touch/utils 1.0.42 → 1.0.44

package/transport/events/types/storage.ts

@@ -0,0 +1,208 @@
+/**
+ * @fileoverview Type definitions for Storage domain events
+ * @module @talex-touch/utils/transport/events/types/storage
+ */
+
+// ============================================================================
+// App Storage Types
+// ============================================================================
+
+/**
+ * Request to get a storage value.
+ */
+export interface StorageGetRequest {
+  /**
+   * Storage key to retrieve.
+   */
+  key: string
+}
+
+/**
+ * Versioned storage response payload.
+ */
+export interface StorageGetVersionedResponse {
+  /**
+   * Stored data.
+   */
+  data: unknown
+
+  /**
+   * Current version number.
+   */
+  version: number
+}
+
+/**
+ * Request to set a storage value.
+ */
+export interface StorageSetRequest {
+  /**
+   * Storage key.
+   */
+  key: string
+
+  /**
+   * Value to store.
+   */
+  value: unknown
+}
+
+/**
+ * Request to save a storage value with version tracking.
+ */
+export interface StorageSaveRequest {
+  /**
+   * Storage key.
+   */
+  key: string
+
+  /**
+   * Serialized JSON content.
+   */
+  content?: string
+
+  /**
+   * Raw value to serialize (fallback when content not provided).
+   */
+  value?: unknown
+
+  /**
+   * Clear stored data for the key.
+   */
+  clear?: boolean
+
+  /**
+   * Force save even if content is unchanged.
+   */
+  force?: boolean
+
+  /**
+   * Client version for conflict detection.
+   */
+  version?: number
+}
+
+/**
+ * Result for versioned storage save.
+ */
+export interface StorageSaveResult {
+  success: boolean
+  version: number
+  conflict?: boolean
+}
+
+/**
+ * Request to delete a storage value.
+ */
+export interface StorageDeleteRequest {
+  /**
+   * Storage key to delete.
+   */
+  key: string
+}
+
+// ============================================================================
+// Plugin Storage Types
+// ============================================================================
+
+/**
+ * Request to get a plugin storage value.
+ */
+export interface PluginStorageGetRequest {
+  /**
+   * Plugin name.
+   */
+  pluginName: string
+
+  /**
+   * Storage key.
+   */
+  key: string
+}
+
+/**
+ * Request to set a plugin storage value.
+ */
+export interface PluginStorageSetRequest {
+  /**
+   * Plugin name.
+   */
+  pluginName: string
+
+  /**
+   * Storage key.
+   */
+  key: string
+
+  /**
+   * Value to store.
+   */
+  value: unknown
+}
+
+/**
+ * Request to delete a plugin storage value.
+ */
+export interface PluginStorageDeleteRequest {
+  /**
+   * Plugin name.
+   */
+  pluginName: string
+
+  /**
+   * Storage key to delete.
+   */
+  key: string
+}
+
+/**
+ * Storage subscription notification.
+ */
+export interface StorageUpdateNotification {
+  /**
+   * Storage key that was updated.
+   */
+  key: string
+
+  /**
+   * New value (undefined if deleted).
+   */
+  value?: unknown
+
+  /**
+   * Version number if available.
+   */
+  version?: number
+
+  /**
+   * Update timestamp.
+   */
+  timestamp: number
+
+  /**
+   * Source of the update.
+   */
+  source?: 'local' | 'remote' | 'sync'
+}
+
+export interface StorageLegacyUpdatePayload {
+  /**
+   * Legacy storage key name.
+   */
+  name: string
+
+  /**
+   * Version number if available.
+   */
+  version?: number
+}
+
+/**
+ * Plugin storage update notification.
+ */
+export interface PluginStorageUpdateNotification extends StorageUpdateNotification {
+  /**
+   * Plugin name.
+   */
+  pluginName: string
+}

package/transport/events/types/transport.ts

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Type definitions for Transport port upgrade events
+ * @module @talex-touch/utils/transport/events/types/transport
+ * @since v0.9.0
+ */
+
+export type TransportPortScope = 'app' | 'window' | 'plugin'
+
+export interface TransportPortError {
+  code: string
+  message: string
+}
+
+export interface TransportPortUpgradeRequest {
+  channel: string
+  scope?: TransportPortScope
+  windowId?: number
+  plugin?: string
+  permissions?: string[]
+}
+
+export interface TransportPortUpgradeResponse {
+  accepted: boolean
+  channel: string
+  scope?: TransportPortScope
+  permissions?: string[]
+  portId?: string
+  error?: TransportPortError
+}
+
+export interface TransportPortConfirmPayload {
+  channel: string
+  portId: string
+  scope?: TransportPortScope
+  permissions?: string[]
+}
+
+export interface TransportPortClosePayload {
+  channel: string
+  portId?: string
+  scope?: TransportPortScope
+  reason?: string
+}
+
+export interface TransportPortErrorPayload {
+  channel: string
+  portId?: string
+  scope?: TransportPortScope
+  error: TransportPortError
+}
+
+export interface TransportPortEnvelope<TPayload = unknown> {
+  channel: string
+  portId?: string
+  streamId?: string
+  sequence?: number
+  type: 'data' | 'close' | 'error'
+  payload?: TPayload
+  error?: TransportPortError
+}

package/transport/events/types/tray.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Type definitions for Tray domain events
+ * @module @talex-touch/utils/transport/events/types/tray
+ */
+
+export type TrayAutostartUpdateRequest = boolean
+export type TrayAutostartUpdateResponse = boolean
+
+export type TrayAutostartGetResponse = boolean
+
+export type TrayShowGetResponse = boolean
+
+export type TrayShowSetRequest = boolean
+export type TrayShowSetResponse = boolean
+
+export type TrayHideDockSetResponse = boolean

package/transport/events/types/update.ts

@@ -0,0 +1,78 @@
+import type {
+  AppPreviewChannel,
+  CachedUpdateRecord,
+  GitHubRelease,
+  UpdateCheckResult,
+  UpdateSettings,
+  UpdateUserAction,
+} from '../../../types/update'
+
+export interface UpdateOpResponse<T = void> {
+  success: boolean
+  data?: T
+  error?: string
+}
+
+export interface UpdateCheckRequest {
+  force?: boolean
+}
+
+export type UpdateGetStatusResponse = UpdateOpResponse<{
+  enabled: boolean
+  frequency: UpdateSettings['frequency']
+  source: UpdateSettings['source']
+  channel: AppPreviewChannel
+  polling: boolean
+  lastCheck: number | null
+  downloadReady?: boolean
+  downloadReadyVersion?: string | null
+  downloadTaskId?: string | null
+}>
+
+export interface UpdateCachedReleaseRequest {
+  channel?: AppPreviewChannel
+}
+
+export interface UpdateRecordActionRequest {
+  tag: string
+  action: UpdateUserAction
+}
+
+export type UpdateDownloadRequest = GitHubRelease
+
+export type UpdateDownloadResponse = UpdateOpResponse<{
+  taskId?: string
+}>
+
+export interface UpdateInstallRequest {
+  taskId?: string
+}
+
+export interface UpdateIgnoreVersionRequest {
+  version: string
+}
+
+export interface UpdateAutoDownloadRequest {
+  enabled: boolean
+}
+
+export interface UpdateAutoCheckRequest {
+  enabled: boolean
+}
+
+export interface UpdateAvailablePayload {
+  hasUpdate: boolean
+  release: GitHubRelease
+  source: string
+  channel?: AppPreviewChannel
+}
+
+export type UpdateGetCachedReleaseResponse = UpdateOpResponse<CachedUpdateRecord | null>
+
+export type UpdateCheckResponse = UpdateOpResponse<UpdateCheckResult>
+
+export type UpdateGetSettingsResponse = UpdateOpResponse<UpdateSettings>
+
+export interface UpdateUpdateSettingsRequest {
+  settings: Partial<UpdateSettings>
+}

package/transport/index.ts

@@ -0,0 +1,139 @@
+/**
+ * @fileoverview TuffTransport - Next-generation IPC communication system for Tuff
+ * @module @talex-touch/utils/transport
+ * @version 2.0.0
+ *
+ * @description
+ * TuffTransport provides a type-safe, high-performance IPC communication layer
+ * with support for batching, streaming, and plugin isolation.
+ *
+ * @example
+ * ```typescript
+ * import { useTuffTransport, CoreBoxEvents } from '@talex-touch/utils/transport'
+ *
+ * const transport = useTuffTransport()
+ * await transport.send(CoreBoxEvents.ui.hide)
+ * ```
+ */
+
+// ============================================================================
+// Event Builder
+// ============================================================================
+
+export {
+  /**
+   * @deprecated Use `useTuffTransport()` instead. Will be removed in v3.0.0.
+   */
+  ChannelType,
+  /**
+   * @deprecated Use `TuffTransportErrorCode` instead. Will be removed in v3.0.0.
+   */
+  DataCode,
+} from '../channel'
+
+// ============================================================================
+// Event Types
+// ============================================================================
+
+export type {
+  /**
+   * @deprecated Use `ITuffTransport` instead. Will be removed in v3.0.0.
+   */
+  ITouchChannel,
+  /**
+   * @deprecated Use `ITuffTransport` instead. Will be removed in v3.0.0.
+   */
+  ITouchClientChannel,
+  /**
+   * @deprecated Use TuffTransport types instead. Will be removed in v3.0.0.
+   */
+  RawStandardChannelData,
+  /**
+   * @deprecated Use TuffTransport types instead. Will be removed in v3.0.0.
+   */
+  StandardChannelData,
+} from '../channel'
+
+// ============================================================================
+// Predefined Events (by domain)
+// ============================================================================
+
+export {
+  TuffTransportError,
+  TuffTransportErrorCode,
+} from './errors'
+
+// ============================================================================
+// SDK Types
+// ============================================================================
+
+export {
+  assertTuffEvent,
+  defineEvent,
+  isTuffEvent,
+  TuffActionBuilder,
+  TuffEventBuilder,
+  TuffModuleBuilder,
+} from './event/builder'
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+export type {
+  BatchConfig,
+  EventOptions,
+  EventRequest,
+  EventResponse,
+  IsStreamEvent,
+  StreamChunk,
+  StreamConfig,
+  TuffEvent,
+} from './event/types'
+
+// ============================================================================
+// SDK Functions
+// ============================================================================
+
+export * from './events'
+
+// ============================================================================
+// Legacy Compatibility (Deprecated)
+// ============================================================================
+
+export {
+  createPluginTuffTransport,
+  createTuffRendererTransport,
+  useTuffTransport,
+} from './sdk'
+
+export type {
+  // Batch types
+  BatchPayload,
+  BatchResponse,
+  BatchResult,
+
+  // Contexts
+  HandlerContext,
+  IPluginTuffTransport,
+  // Transport interfaces
+  ITuffTransport,
+
+  ITuffTransportMain,
+  PluginKeyManager,
+
+  // Plugin security
+  PluginSecurityContext,
+  // Options
+  SendOptions,
+  StreamContext,
+
+  StreamController,
+  // Stream types
+  StreamMessage,
+
+  StreamMessageType,
+  StreamOptions,
+  TransportPortHandle,
+  TransportPortOpenOptions,
+} from './types'

package/transport/main.ts

@@ -0,0 +1,2 @@
+export * from './index'
+export { getTuffTransportMain } from './sdk/main'

package/transport/sdk/constants.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Constants for TuffTransport SDK
+ * @module @talex-touch/utils/transport/sdk/constants
+ */
+
+/**
+ * Default timeout for transport requests (ms)
+ */
+export const DEFAULT_TIMEOUT = 10_000
+
+/**
+ * Stream message types
+ */
+export const STREAM_MESSAGE_TYPES = {
+  DATA: 'data',
+  ERROR: 'error',
+  END: 'end',
+} as const
+
+/**
+ * Stream event name suffixes
+ */
+export const STREAM_SUFFIXES = {
+  START: ':stream:start',
+  DATA: ':stream:data',
+  END: ':stream:end',
+  ERROR: ':stream:error',
+  CANCEL: ':stream:cancel',
+} as const

package/transport/sdk/domains/agents-market.ts

@@ -0,0 +1,47 @@
+import type {
+  AgentsMarketCategoriesResponse,
+  AgentsMarketInfo,
+  AgentsMarketInstallResponse,
+  AgentsMarketSearchRequest,
+  AgentsMarketSearchResponse,
+} from '../../events/types'
+import type { ITuffTransport } from '../../types'
+import { AgentsEvents } from '../../events'
+
+export type MarketAgentInfo = AgentsMarketInfo
+export type AgentSearchOptions = AgentsMarketSearchRequest
+export type AgentSearchResult = AgentsMarketSearchResponse
+export type AgentInstallResult = AgentsMarketInstallResponse
+export type AgentCategory = AgentsMarketCategoriesResponse[number]
+
+export interface AgentMarketSdk {
+  searchAgents: (options?: AgentSearchOptions) => Promise<AgentSearchResult>
+  getAgentDetails: (agentId: string) => Promise<MarketAgentInfo | null>
+  getFeaturedAgents: () => Promise<MarketAgentInfo[]>
+  getInstalledAgents: () => Promise<MarketAgentInfo[]>
+  getCategories: () => Promise<AgentCategory[]>
+  installAgent: (agentId: string, version?: string) => Promise<AgentInstallResult>
+  uninstallAgent: (agentId: string) => Promise<AgentInstallResult>
+  checkUpdates: () => Promise<MarketAgentInfo[]>
+}
+
+export function createAgentMarketSdk(transport: ITuffTransport): AgentMarketSdk {
+  return {
+    searchAgents: options => transport.send(AgentsEvents.market.search, options),
+
+    getAgentDetails: agentId => transport.send(AgentsEvents.market.get, { agentId }),
+
+    getFeaturedAgents: () => transport.send(AgentsEvents.market.featured),
+
+    getInstalledAgents: () => transport.send(AgentsEvents.market.installed),
+
+    getCategories: () => transport.send(AgentsEvents.market.categories),
+
+    installAgent: (agentId, version) =>
+      transport.send(AgentsEvents.market.install, { agentId, version }),
+
+    uninstallAgent: agentId => transport.send(AgentsEvents.market.uninstall, { agentId }),
+
+    checkUpdates: () => transport.send(AgentsEvents.market.checkUpdates),
+  }
+}

package/transport/sdk/domains/agents.ts

@@ -0,0 +1,62 @@
+import type {
+  AgentsCancelResponse,
+  AgentsExecuteImmediateRequest,
+  AgentsExecuteImmediateResponse,
+  AgentsExecuteRequest,
+  AgentsExecuteResponse,
+  AgentsGetResponse,
+  AgentsListResponse,
+  AgentsStatsResponse,
+  AgentsTaskCancelledPayload,
+  AgentsTaskCompletedPayload,
+  AgentsTaskFailedPayload,
+  AgentsTaskProgressPayload,
+  AgentsTaskStartedPayload,
+  AgentsTaskStatusResponse,
+  AgentsToolsGetResponse,
+  AgentsToolsListResponse,
+  AgentsUpdatePriorityResponse,
+} from '../../events/types'
+import type { ITuffTransport } from '../../types'
+import { AgentsEvents } from '../../events'
+
+export interface AgentsSdk {
+  list: () => Promise<AgentsListResponse>
+  listAll: () => Promise<AgentsListResponse>
+  get: (id: string) => Promise<AgentsGetResponse>
+  execute: (task: AgentsExecuteRequest) => Promise<AgentsExecuteResponse>
+  executeImmediate: (task: AgentsExecuteImmediateRequest) => Promise<AgentsExecuteImmediateResponse>
+  cancel: (taskId: string) => Promise<AgentsCancelResponse>
+  getTaskStatus: (taskId: string) => Promise<AgentsTaskStatusResponse>
+  updatePriority: (taskId: string, priority: number) => Promise<AgentsUpdatePriorityResponse>
+  getStats: () => Promise<AgentsStatsResponse>
+  listTools: () => Promise<AgentsToolsListResponse>
+  getTool: (toolId: string) => Promise<AgentsToolsGetResponse>
+  onTaskStarted: (handler: (payload: AgentsTaskStartedPayload) => void) => () => void
+  onTaskProgress: (handler: (payload: AgentsTaskProgressPayload) => void) => () => void
+  onTaskCompleted: (handler: (payload: AgentsTaskCompletedPayload) => void) => () => void
+  onTaskFailed: (handler: (payload: AgentsTaskFailedPayload) => void) => () => void
+  onTaskCancelled: (handler: (payload: AgentsTaskCancelledPayload) => void) => () => void
+}
+
+export function createAgentsSdk(transport: ITuffTransport): AgentsSdk {
+  return {
+    list: () => transport.send(AgentsEvents.api.list),
+    listAll: () => transport.send(AgentsEvents.api.listAll),
+    get: id => transport.send(AgentsEvents.api.get, { id }),
+    execute: task => transport.send(AgentsEvents.api.execute, task),
+    executeImmediate: task => transport.send(AgentsEvents.api.executeImmediate, task),
+    cancel: taskId => transport.send(AgentsEvents.api.cancel, { taskId }),
+    getTaskStatus: taskId => transport.send(AgentsEvents.api.taskStatus, { taskId }),
+    updatePriority: (taskId, priority) =>
+      transport.send(AgentsEvents.api.updatePriority, { taskId, priority }),
+    getStats: () => transport.send(AgentsEvents.api.stats),
+    listTools: () => transport.send(AgentsEvents.api.tools.list),
+    getTool: toolId => transport.send(AgentsEvents.api.tools.get, { toolId }),
+    onTaskStarted: handler => transport.on(AgentsEvents.push.taskStarted, handler),
+    onTaskProgress: handler => transport.on(AgentsEvents.push.taskProgress, handler),
+    onTaskCompleted: handler => transport.on(AgentsEvents.push.taskCompleted, handler),
+    onTaskFailed: handler => transport.on(AgentsEvents.push.taskFailed, handler),
+    onTaskCancelled: handler => transport.on(AgentsEvents.push.taskCancelled, handler),
+  }
+}

package/transport/sdk/domains/app.ts

@@ -0,0 +1,48 @@
+import type { ITuffTransport } from '../../types'
+import { AppEvents } from '../../events'
+
+export interface AppSdk {
+  close: () => Promise<void>
+  hide: () => Promise<void>
+  minimize: () => Promise<void>
+  focus: () => Promise<void>
+  openDevTools: (options?: Parameters<ITuffTransport['send']>[1]) => Promise<void>
+
+  getCwd: () => Promise<string>
+  getOS: () => Promise<unknown>
+  getPackage: () => Promise<unknown>
+  getPath: (name: string) => Promise<string | null>
+  getSecureValue: (key: string) => Promise<string | null>
+  setSecureValue: (key: string, value: string | null) => Promise<void>
+
+  openExternal: (url: string) => Promise<void>
+  showInFolder: (path: string) => Promise<void>
+  openApp: (options: { appName?: string, path?: string }) => Promise<void>
+  openPromptsFolder: () => Promise<void>
+  executeCommand: (options: { command: string }) => Promise<unknown>
+  readFile: (path: string) => Promise<string>
+}
+
+export function createAppSdk(transport: ITuffTransport): AppSdk {
+  return {
+    close: () => transport.send(AppEvents.window.close),
+    hide: () => transport.send(AppEvents.window.hide),
+    minimize: () => transport.send(AppEvents.window.minimize),
+    focus: () => transport.send(AppEvents.window.focus),
+    openDevTools: options => transport.send(AppEvents.debug.openDevTools, options as any),
+
+    getCwd: () => transport.send(AppEvents.system.getCwd),
+    getOS: () => transport.send(AppEvents.system.getOS),
+    getPackage: () => transport.send(AppEvents.system.getPackage),
+    getPath: name => transport.send(AppEvents.system.getPath, { name }),
+    getSecureValue: key => transport.send(AppEvents.system.getSecureValue, { key }),
+    setSecureValue: (key, value) => transport.send(AppEvents.system.setSecureValue, { key, value }),
+
+    openExternal: url => transport.send(AppEvents.system.openExternal, { url }),
+    showInFolder: path => transport.send(AppEvents.system.showInFolder, { path }),
+    openApp: options => transport.send(AppEvents.system.openApp, options),
+    openPromptsFolder: () => transport.send(AppEvents.system.openPromptsFolder),
+    executeCommand: options => transport.send(AppEvents.system.executeCommand, options as any),
+    readFile: path => transport.send(AppEvents.system.readFile, { source: path }),
+  }
+}