# busylib
[](https://nodejs.org) [](./LICENSE)
A TypeScript library for interacting with the [BUSY Bar](https://busy.app/) - a productivity multi-tool with an LED pixel screen for custom statuses, built-in Pomodoro timer, and apps.
The library currently features three modules:
- **`BusyBar`** - a typed client for the BUSY Bar [HTTP API](https://docs.busy.app/bar/dev/http-api)
- **`StateStream`** - real-time BUSY Bar state updates over WebSocket
- **`ScreenRenderer`** - WebGL2 BUSY Bar display renderer
Supports both ESM (import) and CommonJS (require), with full TypeScript type definitions.
## Table of contents
- [Install](#install)
- [BUSY Bar HTTP API](#busy-bar-http-api)
- [StateStream](#statestream---real-time-device-state-updates)
- [ScreenRenderer](#screenrenderer---rendering-busy-bar-display)
- [Links](#links)
- [License](#license)
## Install
```bash
npm i @busy-app/busy-lib
```
---
## BUSY Bar HTTP API
`BusyBar` is a single class that talks to the BUSY Bar over HTTP - a typed wrapper around the [HTTP API](https://docs.busy.app/bar/dev/http-api). It aggregates every namespace - `System*`, `Display*`, `Audio*`, `Wifi*`, `Storage*`, `Settings*`, `Ble*`, `Input*`, `SmartHome*`, `Account*`, `Assets*`, `Time*`, `Update*` - so everything can be called from one instance. All methods are async and return typed results.
### Quick start
```ts
import { BusyBar } from '@busy-app/busy-lib';
const bar = new BusyBar({
addr: '10.0.4.20' // the BUSY Bar's IP address
});
const status = await bar.SystemStatusGet();
```
Since every call is a network request to a physical device, any method may reject. What you catch depends on the error:
- **HTTP error** (4xx/5xx) - a custom error with `status`, `statusText`, and the
parsed `body` attached, plus a human-readable `message`
- **Timeout** - a `DOMException` with `name === 'TimeoutError'` (the default
timeout is 3000ms; see [Request options](#request-options))
- **Aborted via `signal`** - a `DOMException` with `name === 'AbortError'` (if `AbortController` is passed and request is aborted)
- **Unreachable device / network failure** - the native `fetch` error (e.g. `TypeError: Failed to fetch`)
### Request options
Methods that take an API payload accept it as the first argument, followed by an optional `options` object; methods without a payload take `options` as their only argument. Common options include `timeout` and `signal` for request cancellation (both optional):
```ts
const controller = new AbortController();
try {
await bar.SettingsNameSet(
{
name: 'My BUSY Bar' // the API payload
},
{
timeout: 1000, // ms; overrides the client default (3000)
signal: controller.signal // cancel the request via AbortController
}
);
} catch (err) {
// rejects with a TimeoutError or AbortError when the request is cut short
console.error(err);
}
```
You can also set a default `timeout` for all requests in the class constructor:
```ts
const bar = new BusyBar({
timeout: 5000
});
```
### Connection options
The `addr` you pass decides how the client connects. It accepts an IP address, a domain, or a full URL.
```ts
new BusyBar(); // defaults to http://10.0.4.20
new BusyBar({
addr: '10.0.4.20' // or http://192.168.13.37, https://example.com, etc.
});
new BusyBar({
addr: 'https://api.busy.app',
token: '' // API token required for the BUSY proxy, see Authentication section
});
```
### Authentication
You can set up remote proxy access to send requests to your BUSY Bar from anywhere in the world. This requires an API token, issued at https://cloud.busy.app/api-tokens. You can provide it in the constructor or at runtime with `setToken`:
```ts
const bar = new BusyBar({
addr: 'https://api.busy.app',
token: ''
});
bar.setToken(''); // change at runtime
```
For local network access, the BUSY Bar can optionally require an HTTP access password. Configure it in the web UI over USB-Ethernet (`10.0.4.20`) under Settings → HTTP Access. Provide the password in the constructor or at runtime with `setHTTPAccessPassword`:
```ts
const bar = new BusyBar({
addr: '192.168.13.37',
HTTPAccessPassword: ''
});
bar.setHTTPAccessPassword(''); // change at runtime
```
### Pitfalls
- **Protocol is auto-added.** `addr` defaults to `http://`, except the BUSY proxy host, which defaults to `https://`. Specify the protocol explicitly to override
---
## StateStream - real-time device state updates
`StateStream` receives the BUSY Bar's protobuf-encoded state updates over WebSocket. It runs in a Shared Worker to avoid overloading the BUSY Bar with multiple connections from multiple tabs.
`StateStream` decodes protobuf for you, so you get ready-to-use typed objects in your callbacks.
The worker is bundled inline; no bundler configuration is required on your side.
### Quick start
```ts
import { LocalStateStream } from '@busy-app/busy-lib';
const stream = new LocalStateStream({
addr: '10.0.4.20'
// use HTTPAccessPassword: '' for local network access with HTTP password enabled
});
try {
await stream.start({
dataCallback: (state) => {
// state.updates is an array; each update carries a `state` key
// for the module that changed (e.g. 'audio', 'wifi', 'brightness')
for (const update of state.updates ?? []) {
console.log(update.state, update);
}
},
statusCallback: (status) => {
console.log(status);
},
errorCallback: (err) => {
// typed lifecycle errors from the worker, websocket or protobuf decoder
console.error(err);
}
});
} catch (err) {
// start() rejects on the error during initial connection/authorization, or on timeout
console.error(err);
}
// close the connection and clean up callbacks;
// the worker remains alive, so you can start again
try {
await stream.stop();
} catch (err) {
// stop() rejects only if websocket failed to close gracefully. Worker is not terminated
console.error(err);
}
```
### Tuning reconnection & timeouts
Pass a config object as the second constructor argument:
```ts
new LocalStateStream(
{
addr: '10.0.4.20'
},
{
timeout: 5000, // connection timeout (ms)
dataTimeout: 15000, // how long to wait before marking the stream as STALE when no data is received (ms)
maxReconnectAttempts: 5,
reconnectDelay: 1000, // delay between reconnect attempts (ms)
workerName: 'my-worker' // override the shared-worker key
}
);
```
### Error handling
`errorCallback` always receives a `StateStreamError` carrying a machine-readable `code` from `StateStreamErrorCode`:
```ts
import { StateStreamErrorCode } from '@busy-app/busy-lib';
errorCallback: (err) => {
if (err.code === StateStreamErrorCode.CONNECTION_TIMEOUT) {
retryLater();
} else if (err.code === StateStreamErrorCode.AUTH_FAILED) {
promptLogin();
}
};
```
### Pitfalls
- **Browser only.** `StateStream` is designed for the browser and relies on `SharedWorker` with fallback to Web Workers. Node implementation on Worker Threads is possible but not currently planned
- **`STALE` ≠ websocket closed.** A live connection that simply stops sending messages flips `status.data` to `STALE` after `dataTimeout` - the websocket is still up, even if the device is no longer responding
- **Don't double-start.** If the stream is already starting or running, `start()` rejects with `STREAM_ALREADY_STARTED`. Call `stop()` first
- **Stop vs Destroy.** `stop()` closes the websocket gracefully and clears callbacks; `destroy()` does the same and also terminates the worker
---
## ScreenRenderer - rendering BUSY Bar display
`ScreenRenderer` paints a display frame onto a `
