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	`globalThis`	index.js global context API
Box SDK	`useBox()`	Control CoreBox window
Clipboard SDK	`useClipboard()`	Clipboard read/write 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
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)
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,
  usePowerSDK,
  useChannel,
  useFeature,
  useDivisionBox
} from '@talex-touch/utils/plugin/sdk'

// Initialize SDKs
const box = useBox()
const clipboard = useClipboard()
const storage = usePluginStorage()
const power = usePowerSDK()
const channel = useChannel()
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'