SDK API Overview

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.

Introduction

The SDK exposes window control, clipboard, search, storage, and transport capabilities through a unified runtime context, so plugins can stay small and focused.

Installation

pnpm add @talex-touch/utils

API Reference

Module	Import	Description
Plugin Context	`IPluginContext` / `context.utils`	Canonical lifecycle capability facade
Box SDK	`useBox()`	Control CoreBox window
Clipboard SDK	`useClipboard()` / `system.captureSelection()`	Clipboard, selected text, and history
TempFile SDK	`useTempPluginFiles()`	Create and clean temp files
Storage SDK	`usePluginStorage()`	Plugin data persistence
Download SDK	`useDownloadSdk()`	Download task management
Platform Capabilities SDK	`usePlatformSdk()`	Platform capability catalog
Screenshot SDK	`screenshot` / `plugin.screenshot`	Permission-gated display, cursor, and region capture
PowerSDK	`usePowerSDK()`	Low-power status for plugin adaptation
RecommendSDK	`recommend`	Custom recommendation provider registration
Account SDK	`accountSDK`	User info, subscription, quota
TuffTransport	`useTuffTransport()`	Next-gen IPC (recommended)
Feature SDK	`useFeature()`	Search result management
Search / Indexed Source SDK	`@talex-touch/utils/search`	Search providers and indexed-source lifecycle contracts
QuickActions SDK	`quickActions` / `plugin.quickActions`	MetaK global actions and native share
QuickOps SDK	`quickOps` / `plugin.quickOps`	Bounded, policy-aware host facade for built-in local tools
DivisionBox SDK	`useDivisionBox()`	Independent window management
Flow SDK	`createFlowSDK()`	Inter-plugin data transfer
Intelligence SDK	`useIntelligenceSdk()` / `plugin.intelligence`	AI capabilities and provider discovery
Localization SDK	`usePluginI18n()` / `plugin.i18n`	Host locale, localized text, and scoped Domain Lexicon

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,
usePowerSDK,
useFeature,
useDivisionBox
} from '@talex-touch/utils/plugin/sdk'
import { useTuffTransport } from '@talex-touch/utils/transport'

// Initialize SDKs
const box = useBox()
const clipboard = useClipboard()
const storage = usePluginStorage()
const power = usePowerSDK()
const transport = useTuffTransport()
const feature = useFeature()
const divisionBox = useDivisionBox()

// Usage example
async function init() {
// Read config
const config = await storage.getFile('config.json')

    // Read low-power status
    const lowPower = await power.isLowPower({ threshold: 25 })
    if (lowPower) {
      console.log('Skip heavy work on battery')
    }

    // 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)
    })

## }

Best Practices

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' })

Technical Notes

use* hooks resolve plugin context at runtime to avoid manual wiring.
IPC and transport abstractions provide consistent cleanup via dispose functions.

Type Imports

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