Reference

SDK

@doan-labs/duo-sdk is how an app talks to the phone: displays and the fold, storage, commands between its views, widgets and links. One client, os, and a React hook.

app.ts
1import { os } from '@doan-labs/duo-sdk'
2await os.connect() // handshake with the shell, before rendering
3os.ready() // first frame painted
4
5os.view // display, placement, width, height, angle…
6os.onView((view) => ...) // the fold, live
7
8await os.storage.set('lastTab', 'today') // durable when this resolves
9const snap = await os.storage.snapshot() // { rev, entries }, then
10os.storage.watch(snap.rev, (c) => ...) // every change after it, in order
11
12os.owner // { epoch } in the view that runs effects
13os.commands.send('refresh', '') // resolves when the owner acknowledged
14os.widget.set('small', { lines }) // owner only
15os.open('labs.doan.ipduo.maps', 'q=1')
16os.device.on('volume', (e) => ...) // the frame's buttons, pose and switches
17
18import { useKV } from '@doan-labs/duo-sdk/react'
19const note = useKV(os.storage, 'note') // { value, status, set, del }

PlatformErrorClass

No TSDoc on this export yet.

class PlatformError extends Error

packages/sdk/guards.ts:17

ManifestType

No TSDoc on this export yet.

type Manifest = {
  id: string
  name: string
  version: string
  lane: 'official' | 'community'
  entry: string
  icon: string
  light?: boolean
  edge?: boolean
  widgets?: ('small' | 'medium')[]
  network?: string[]
  permissions?: PermissionName[]
  author: string
  repo: string
  license: 'MIT'
}
MemberTypeDescription
idstring
namestring
versionstring
lane'official' | 'community'
entrystring
iconstring
light?boolean
edge?boolean
widgets?('small' | 'medium')[]
network?string[]
permissions?PermissionName[]
authorstring
repostring
license'MIT'

packages/sdk/manifest.ts:4

ReleaseType

No TSDoc on this export yet.

type Release = {
  manifest: Manifest
  build: { sdk: string; kit?: string; at: string; commit: string; hash: string }
  files: { path: string; bytes: number; sha256: string }[]
}
MemberTypeDescription
manifestManifest
build{ sdk: string; kit?: string; at: string; commit: string; hash: string }
files{ path: string; bytes: number; sha256: string }[]

packages/sdk/manifest.ts:21

ReleaseIdType

No TSDoc on this export yet.

type ReleaseId = `${string}+${string}`

packages/sdk/manifest.ts:20

PermissionNameType

No TSDoc on this export yet.

type PermissionName = keyof typeof PERMISSIONS

packages/sdk/permissions.ts:30

PhotoType

No TSDoc on this export yet.

type Photo = { id: string; takenAt: number; width: number; height: number }
MemberTypeDescription
idstring
takenAtnumber
widthnumber
heightnumber

packages/sdk/permissions.ts:34

DeviceEventType

No TSDoc on this export yet.

type DeviceEvent = keyof DeviceEvents

packages/sdk/protocol.ts:58

DeviceEventsType

What os.device.on(type, cb) hands cb, by type. Button events reach one view: the first listener whose view is visible and active when the button goes down, and that view also hears the slide and the release of that press.

type DeviceEvents = {
  /** Volume up or down. While a view hears it, the ringer level does not move. */
  volume: { action: 'press' | 'release'; button: 'up' | 'down' }
  /**
   * Camera Control. While a view hears it, the Camera app neither opens nor shoots.
   * `offset` is how far the finger has slid along the cap since the press, in
   * centimetres, positive toward the top of the phone.
   */
  'camera-control': { action: 'press' | 'release' } | { action: 'slide'; offset: number }
  /** The side button. Heard, not taken: it still sleeps, wakes and calls Siri. */
  side: { action: 'press' | 'release' }
  /**
   * The phone's pose, in degrees. `yaw` turns about its long axis, 0 facing you,
   * positive as the right edge swings away, in [-180, 180). `hinge` is `view.angle`.
   * Heard first as the current pose, then on each change, at most once a frame.
   */
  orientation: { yaw: number; hinge: number }
  /** Read-only. Heard first as the current switches, then on each flip. */
  switches: Switches
}
MemberTypeDescription
volume{ action: 'press' | 'release'; button: 'up' | 'down' }Volume up or down. While a view hears it, the ringer level does not move.
side{ action: 'press' | 'release' }The side button. Heard, not taken: it still sleeps, wakes and calls Siri.
orientation{ yaw: number; hinge: number }The phone's pose, in degrees. yaw turns about its long axis, 0 facing you, positive as the right edge swings away, in [-180, 180). hinge is view.angle. Heard first as the current pose, then on each change, at most once a frame.
switchesSwitchesRead-only. Heard first as the current switches, then on each flip.

packages/sdk/protocol.ts:38

ErrCodeType

No TSDoc on this export yet.

type ErrCode =
  | 'E_ARGS'
  | 'E_QUOTA'
  | 'E_RATE'
  | 'E_CLOSED'
  | 'E_TIMEOUT'
  | 'E_PROTOCOL'
  | 'E_DENIED'
  | 'E_STALE'
  | 'E_GONE'
  | 'E_STORAGE'
  | 'E_UNSUPPORTED'
  | 'E_CONFLICT'

packages/sdk/protocol.ts:118

KVType

No TSDoc on this export yet.

type KV = {
  get(k: string): Promise<string | null>
  /** The value and precondition token to `set`/`del` with `expect`. */
  entry(k: string): Promise<Entry>
  /**
   * `expect` is the `{ rev, gen }` token the new value was computed from
   * (from `entry`). The host checks it inside the write's own transaction:
   * a moved space rejects `E_CONFLICT`, a dead generation rejects `E_GONE`,
   * and either way nothing mutates. Omit it for an unconditional write.
   */
  set(k: string, v: string, expect?: Expect): Promise<{ rev: number }>
  del(k: string, expect?: Expect): Promise<{ rev: number }>
  keys(cursor?: string): Promise<{ keys: string[]; cursor?: string }>
  snapshot(cursor?: string): Promise<Snapshot>
  watch(since: number, cb: (e: Change) => void): () => void
}

packages/sdk/protocol.ts:186

LimitsType

No TSDoc on this export yet.

type Limits = typeof LIMITS

packages/sdk/protocol.ts:71

MicResultType

mic.stop's take: the captured audio, its container and what the shell measured.

type MicResult = { mime: string; durationMs: number; blob: Blob }
MemberTypeDescription
mimestring
durationMsnumber
blobBlob

packages/sdk/protocol.ts:115

MicStatusType

What mic.status returns and { ev: 'mic' } pushes to the owning session's views. level is the meter's latest peak in [0,1]; elapsed is milliseconds and runs only while recording, so a paused take's clock stops like the one on screen. denied/unavailable/ended are terminal for that take.

type MicStatus = {
  state: 'idle' | 'recording' | 'paused' | 'ended' | 'denied' | 'unavailable'
  elapsed: number
  level: number
  detail?: string
}
MemberTypeDescription
state'idle' | 'recording' | 'paused' | 'ended' | 'denied' | 'unavailable'
elapsednumber
levelnumber
detail?string

packages/sdk/protocol.ts:108

NoticeType

What os.notify.post takes: the OS shows name and title, body under it, and hands arg back to the app when the notice is opened, like os.open's arg.

type Notice = { title: string; body?: string; arg?: string }
MemberTypeDescription
titlestring
body?string
arg?string

packages/sdk/protocol.ts:101

StoredFileType

A file.list/file.put row: an app-owned blob in the durable appfiles store.

type StoredFile = { name: string; size: number; type: string; at: number }
MemberTypeDescription
namestring
sizenumber
typestring
atnumber

packages/sdk/protocol.ts:117

SwitchesType

The device switches Control Center and Settings both flip. One definition, so the shell's store (springboard/toggles.ts), the baked Settings app and the switches device event cannot drift apart. Apps only read them.

type Switches = {
  airplane: boolean
  cell: boolean
  wifi: boolean
  bt: boolean
  drop: boolean
  hotspot: boolean
  rotate: boolean
  mirror: boolean
  focus: boolean
  torch: boolean
  /** Dark Mode: light apps wear the kit's dark theme; always-dark apps are untouched. */
  darkMode: boolean
}
MemberTypeDescription
airplaneboolean
cellboolean
wifiboolean
btboolean
dropboolean
hotspotboolean
rotateboolean
mirrorboolean
focusboolean
torchboolean
darkModebooleanDark Mode: light apps wear the kit's dark theme; always-dark apps are untouched.

packages/sdk/protocol.ts:19

ViewInfoType

No TSDoc on this export yet.

type ViewInfo = {
  display: 'inner' | 'cover'
  placement: 'full' | 'left' | 'right'
  width: number
  height: number
  visible: boolean
  active: boolean
  focused: boolean
  angle: number
}
MemberTypeDescription
display'inner' | 'cover'
placement'full' | 'left' | 'right'
widthnumber
heightnumber
visibleboolean
activeboolean
focusedboolean
anglenumber

packages/sdk/protocol.ts:4

WidgetSnapshotType

No TSDoc on this export yet.

type WidgetSnapshot = {
  arg?: string
  lines: { text: string; role: 'label' | 'value' | 'caption' }[]
  tint?: 'glass' | 'dark'
}
MemberTypeDescription
arg?string
lines{ text: string; role: 'label' | 'value' | 'caption' }[]
tint?'glass' | 'dark'

packages/sdk/protocol.ts:66

transitionFunction

Runs fn inside a same-document view transition, so whatever it changes on screen cross-fades instead of snapping. Falls back to a plain call where the API is missing or the user asked for reduced motion. Concurrent calls are fine: the browser skips the one in flight.

function transition(fn: () => void)

Also accepts () => void. Raw style and className are refused.

packages/sdk/transition.ts:7

osValue

No TSDoc on this export yet.

os = createClient()

packages/sdk/index.ts:22