Kunkun Docs

The @kunkunsh/sdk package is your interface to the host. Friendly wrappers (Clipboard, fs, db, …) call the underlying getHostAPI() proxy over kkrpc. Every method is async and permission-checked host-side.

Subpath exports

Import	Provides
`@kunkunsh/sdk`	Main API: `Clipboard`, `LocalStorage`, `fs`, `shell`, `path`, `db`, `showToast`, `spawnBackend`, …
`@kunkunsh/sdk/ui`	Worker/node-view UI primitives (`Button`, `List`, `Form`, …)
`@kunkunsh/sdk/runtime`	Bootstraps + `getHostAPI`, service clients, `startKunkunHeadlessPlugin`
`@kunkunsh/sdk/contract`	`defineServiceContract`, `method`, `InferService`
`@kunkunsh/sdk/backend`	`exposeBackend` (backend-process side)
`@kunkunsh/sdk/manifest`	Manifest schemas + validators
`@kunkunsh/sdk/events`	Event types + `EventMap`
`@kunkunsh/sdk/utils`	React hooks: `useQuery`, `useRecord`, `useForm`, `useCachedState`, …
`@kunkunsh/sdk/build`	Build helpers: `kunkunCommandPlugin`, `dedupeReact`

Clipboard

Clipboard.readText(): Promise<string>
Clipboard.copy(content: string, options?: { transient?: boolean }): Promise<void>
Clipboard.paste(content: string): Promise<void>
Clipboard.clear(): Promise<void>
clipboard.hasImage(): Promise<boolean>
clipboard.getImageBase64(): Promise<string>

Storage

Key/value store (LocalStorage). For lists and queries use Record Storage.

LocalStorage.getItem(key: string): Promise<string | undefined>
LocalStorage.setItem(key: string, value: string): Promise<void>
LocalStorage.removeItem(key: string): Promise<void>
LocalStorage.allItems(): Promise<Record<string, string>>
LocalStorage.clear(): Promise<void>

Requires the storage permission.

showToast(options: { title: string; message?: string; style?: Toast.Style }): Promise<void>
showHUD(title: string): Promise<void>
confirmAlert(options: { title: string; message?: string; primaryAction?: { title: string } }): Promise<boolean>
popToRoot(options?: { clearSearchBar?: boolean }): Promise<void>
closeMainWindow(options?: { clearRootSearch?: boolean }): Promise<void>

fs

fs.readTextFile(path): Promise<string>
fs.readFile(path): Promise<Uint8Array>
fs.writeTextFile(path, content, options?): Promise<void>
fs.writeFile(path, data, options?): Promise<void>
fs.readDir(path, options?): Promise<DirEntry[]>
fs.stat(path) / fs.lstat(path): Promise<FileInfo>
fs.exists(path): Promise<boolean>
fs.mkdir(path, options?) / fs.remove(path, options?) / fs.rename(old, new) / fs.copyFile(src, dst): Promise<void>

Requires scoped fs-read / fs-write.

shell

shell.execute(program, args?, options?): Promise<ChildProcess>
shell.spawn(program, args?, options?): AsyncIterable<SpawnEvent>
shell.hasCommand(command): Promise<boolean>
shell.whereIsCommand(command): Promise<string | null>
shell.executeBashScript / executeZshScript / executeAppleScript / executePowershellScript / executePythonScript / executeNodeScript(script, options?): Promise<ChildProcess>

Requires scoped shell.

path

path.join(...parts) / resolve(...parts) / normalize(p) / dirname(p) / basename(p, ext?) / extname(p): Promise<string>
path.homeDir() / desktopDir() / downloadDir() / documentDir() / appDataDir() / tempDir(): Promise<string>
path.extensionDir() / extensionSupportDir(): Promise<string>

dialog

openFileDialog(options?): Promise<string[] | null>
saveFileDialog(options?): Promise<string | null>
showMessageDialog(options): Promise<number>

open

openUrl(url) / openFile(path) / openFolder(path): Promise<void>

Scoped by open-url / open-file / open-folder.

system

showInFinder(path): Promise<void>
trash(path: string | string[]): Promise<void>
getApplications(): Promise<Array<{ name; path; bundleId? }>>
getFrontmostApplication(): Promise<{ name; path; bundleId? }>
getSelectedText(): Promise<string>

Window

windowControl.setSize(size) / setPosition(pos) / setTitle(title): Promise<void>
windowControl.minimize() / toggleMaximize() / center() / hide() / show() / close(): Promise<void>
windowControl.setFullscreen(bool) / setAlwaysOnTop(bool) / setVibrancy(type | null) / setOpacity(n): Promise<void>
windowControl.isMaximized() / isMinimized() / isFullscreen(): Promise<boolean>

Requires window-control.

permissions

requestPermission(type: string, scope: string, reason?: string): Promise<boolean>
checkPermission(type: string, scope: string): Promise<boolean>
listGrants(): Promise<Array<{ permissionType; scopePattern; duration; grantedAt }>>

See Permissions → dynamic grants.

network

network.fetch(opts: FetchOptions): Promise<FetchResponse>   // CORS-bypassing fetch

Requires network with domains.

db (record storage)

db.collection<T>(name): DbCollection<T>   // add/set/update/get/query/watch/…
db.watch(cb) / db.listCollections() / db.deleteCollection(name)

Full guide + query builder + live queries: Record Storage.

Events

import { subscribeToHostEvent } from "@kunkunsh/sdk/runtime";
const unsub = subscribeToHostEvent("clipboard:change", (payload) => { /* … */ });

EventMap (from @kunkunsh/sdk/events) includes keyboard:*, mouse:*, clipboard:change, app:*, plugin:*, and db:changed. Keyboard/mouse subscriptions require input-monitor.

logger, env & preferences

logger.debug/info/warn/error(message, options?): Promise<void>
logger.captureException(error, attributes?): Promise<void>
getEnvironment(): Promise<{ extensionName; commandName; theme; isDevelopment; supportPath; … }>
getPreferenceValues(): Promise<Record<string, PreferenceValue>>
getPlatform() / getUserLanguage(): Promise<…>

Runtime & backends

import { getHostAPI, startKunkunHeadlessPlugin } from "@kunkunsh/sdk/runtime";
import { createServiceClient, createValidatedServiceClient } from "@kunkunsh/sdk/runtime";
import { spawnBackend } from "@kunkunsh/sdk";
import { exposeBackend } from "@kunkunsh/sdk/backend";

getHostAPI() — the typed host proxy (rarely needed directly).
startKunkunHeadlessPlugin({ init, onTrigger, destroy }) — headless entry.
Service clients — Services.
spawnBackend / exposeBackend — Backend Processes.

React hooks (`@kunkunsh/sdk/utils`)

useQuery<T>(collection, options?)   // live record query
useRecord<T>(collection, id)        // live single record
useForm<T>({ onSubmit, validation })
useCachedState / useCachedPromise / useFetch / useAI

This page lists the surface. For behaviour and examples, follow the topic links — Record Storage, Services, Backend Processes, and Permissions.

SDK API Reference