Flow Transfer API
Flow Transfer API
Overview
Flow Transfer is a cross-plugin data handoff system, similar to “share” on mobile but more flexible and structured.
Introduction
This document covers current capabilities:
- Sender:
dispatch()+ target selector - Target:
onFlowTransfer()+acknowledge()/reportError() - Native share:
nativeShare()
Permission note: Flow Transfer is gated by the Permission Center. Unauthorized requests return
PERMISSION_DENIEDand trigger consent UI.
Core Concepts
Flow payload
interface FlowPayload {
type: 'text' | 'image' | 'files' | 'json' | 'html' | 'custom'
data: string | object
mimeType?: string
context?: {
sourcePluginId: string
sourceFeatureId?: string
originalQuery?: TuffQuery
metadata?: Record<string, any>
}
}
Flow target
interface FlowTarget {
id: string
name: string
description?: string
supportedTypes: ('text' | 'image' | 'files' | 'json' | 'html' | 'custom')[]
icon?: string
featureId?: string
}
Shortcuts
| Shortcut | Action | Notes |
|---|---|---|
Command/Ctrl+D | Detach to DivisionBox | Detach selected item |
Command/Ctrl+Shift+D | Flow Transfer | Open target picker |
Plugin Configuration
Declare Flow capabilities in manifest.json:
flowSender?: booleanflowTargets?: FlowTarget[]
{
"name": "my-plugin",
"version": "1.0.0",
"flowSender": true,
"flowTargets": [
{
"id": "quick-note",
"name": "Quick Note",
"description": "Save content as a note",
"supportedTypes": ["text", "html", "image"],
"icon": "ri:sticky-note-line",
"featureId": "create-note"
}
]
}
SDK Usage
Send flow (sender)
import { createFlowSDK } from '@talex-touch/utils/plugin/sdk'
const flow = createFlowSDK(channel, 'my-plugin-id')
const result = await flow.dispatch(
{
type: 'text',
data: 'Hello from my plugin!',
context: {
sourcePluginId: 'my-plugin-id',
metadata: { timestamp: Date.now() }
}
},
{
title: 'Share text',
description: 'Send to another plugin'
}
)
Get available targets
const allTargets = await flow.getAvailableTargets()
const textTargets = await flow.getAvailableTargets('text')
Receive flow (target)
import { createFlowSDK } from '@talex-touch/utils/plugin/sdk'
const flow = createFlowSDK(channel, 'my-plugin-id')
flow.onFlowTransfer(async (payload, ctx) => {
try {
await handlePayload(payload)
ctx.acknowledge({ success: true })
} catch (error) {
ctx.reportError({ message: 'Failed to handle payload' })
}
})
Native share
Flow Transfer can call native share targets. If your plugin is sharing the current CoreBox item from a MetaK / Quick Actions action, prefer QuickActions SDK shareItem() so target resolution and platform fallback stay centralized.
await flow.nativeShare({
type: 'text',
data: 'Share via system dialog'
})
Native targets
| Platform | Target | Notes |
|---|---|---|
| macOS | system / system-share | Native share chooser |
| macOS | airdrop | AirDrop |
| macOS | mail | |
| macOS | messages | iMessage |
| Windows | mail | Default mail client |
| Linux | mail | Default mail client |
Flow target lists expose the system chooser as system-share; flow.nativeShare() also accepts system as a compatibility alias. Windows and Linux currently expose only the explicit mail fallback, not a fake system share panel.
Best Practices
- Register
onFlowTransferto avoid being marked “not supported”. - Provide clear
supportedTypesanddescriptionfor better target ranking. - Use
requireAckfor critical workflows and handle fallback actions. - Use QuickActions
shareItem()for MetaK item sharing.
Technical Notes
- Target list is maintained by the main process and merged with native share targets.
- Plugins are registered via
flow:register-targets; missing registration means targets won’t appear.