SDK API Overview

The Tuff Plugin SDK provides a complete set of APIs for developing CoreBox plugins. All APIs follow a functional design pattern, accessed through use* hook functions.

Installation

pnpm add @talex-touch/utils

SDK Modules

Module	Import	Description
Plugin Context	`globalThis`	index.js global context API
Box SDK	`useBox()`	Control CoreBox window
Clipboard SDK	`useClipboard()`	Clipboard read/write and history
Storage SDK	`usePluginStorage()`	Plugin data persistence
Account SDK	`accountSDK`	User info, subscription, quota
TuffTransport	`useTuffTransport()`	Next-gen IPC (recommended)
Channel SDK	`useChannel()`	IPC communication (legacy)
Feature SDK	`useFeature()`	Search result management
DivisionBox SDK	`useDivisionBox()`	Independent window management
Flow SDK	`createFlowSDK()`	Inter-plugin data transfer
Intelligence SDK	`useIntelligence()`	AI capabilities

New: TuffTransport is the recommended IPC API for new plugins. It provides type-safe events, automatic batching, and streaming support. See also TuffTransport Internals for technical details.

Quick Start

import {
  useBox,
  useClipboard,
  usePluginStorage,
  useChannel,
  useFeature,
  useDivisionBox
} from '@talex-touch/utils/plugin/sdk'

// Initialize SDKs
const box = useBox()
const clipboard = useClipboard()
const storage = usePluginStorage()
const channel = useChannel()
const feature = useFeature()
const divisionBox = useDivisionBox()

// Usage example
async function init() {
  // Read config
  const config = await storage.getFile('config.json')
  
  // Listen to input changes
  feature.onInputChange(async (input) => {
    const results = await search(input)
    feature.pushItems(results)
  })
  
  // Listen to clipboard
  await box.allowClipboard(ClipboardType.TEXT)
  clipboard.history.onDidChange((item) => {
    console.log('Clipboard changed:', item)
  })
}

Design Principles

1. Functional API

All SDKs are accessed through use* functions, no context passing required:

// ✅ Correct
const storage = usePluginStorage()
await storage.getFile('config.json')

// ❌ Wrong (deprecated API)
// const storage = ctx.storage
// await storage.getItem('key')

2. Automatic Context Detection

SDKs automatically detect plugin context, no manual configuration needed:

const storage = usePluginStorage()
// Automatically gets current plugin name

3. Returns Dispose Function

All listeners return an unsubscribe function:

const unsubscribe = feature.onInputChange((input) => {
  // ...
})

// Unsubscribe when component unmounts
onUnmounted(() => {
  unsubscribe()
})

4. Promise-based Async

All async operations return Promises:

const config = await storage.getFile('config.json')
await clipboard.copyAndPaste({ text: 'Hello' })

Type Imports

import type {
  TuffItem,
  TuffQuery,
  ClipboardType,
  DivisionBoxConfig,
  FlowPayload
} from '@talex-touch/utils/plugin/sdk'