# @brookesia/service

JavaScript RPC wrappers for **ESP-Brookesia JS runtime apps** to call device-side `brookesia_service_*` components.

## Install

```bash
npm install @brookesia/service
```

## Quick example

```javascript
import storage from '@brookesia/service/storage';

if (storage.available()) {
  storage.write('my_app', { theme: 'dark' });
  brookesia.print(storage.get('my_app', 'theme'));
  storage.close();
}
```

## Subpath exports

| Import                             | Description                                       |
| ---------------------------------- | ------------------------------------------------- |
| `@brookesia/service/storage`       | KV storage and file system queries                |
| `@brookesia/service/wifi`          | Wi-Fi STA / scan / SoftAP                         |
| `@brookesia/service/device`        | Board info, battery, network status               |
| `@brookesia/service/display`       | Display outputs, backlight, touch gestures        |
| `@brookesia/service/sntp`          | NTP time sync                                     |
| `@brookesia/service/http`          | HTTP/HTTPS client                                 |
| `@brookesia/service/audio`         | Audio playback and volume                         |
| `@brookesia/service/video/encoder` | Video capture / encode                            |
| `@brookesia/service/video/decoder` | Video stream decode                               |
| `@brookesia/service/nes`           | NES emulator control                              |
| `@brookesia/service/ota`           | OTA updates                                       |
| `@brookesia/service/custom`        | Dynamically registered RPC                        |
| `@brookesia/service/manager`       | Service manager — discover services, schemas      |
| `@brookesia/service/utils`         | Debug utilities — memory, threads, snapshots      |
| `@brookesia/service/emote`         | Expression emote — emoji, animation, QR code      |
| `@brookesia/service/agent-manager` | Agent manager — chat, suspend, resume             |
| `@brookesia/service/agent-coze`    | Coze agent — robot selection                      |
| `@brookesia/service/agent-openai`  | OpenAI agent — general chat functions             |
| `@brookesia/service/agent-xiaozhi` | XiaoZhi agent — MCP tools, image explanation      |
| `@brookesia/service/hosts/*`       | Node/vitest memory hosts (not for device runtime) |

## API documentation

### 1. IDE hover (recommended while developing)

After installing `@brookesia/service`, hover methods such as `storage.write()` in VS Code / Cursor to see TSDoc (`@param`, `@returns`, `@example`).

Comments live in `packages/service/src/*/*.ts`; published npm packages include them in `dist/*.d.mts`.

### 2. HTML reference (TypeDoc)

From the **esp-brookesia-toolkit** monorepo root:

```bash
pnpm install
pnpm run docs:service
# open packages/service/docs/html/index.html
```

### 3. Examples and guides (esp-brookesia-apps)

| Resource       | Link                                                                                                           |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| Runnable demos | [examples/service](https://github.com/espressif/esp-brookesia-apps/tree/master/examples/service)               |
| API guide      | [examples/service/API.md](https://github.com/espressif/esp-brookesia-apps/blob/master/examples/service/API.md) |

Chinese README: [README_CN.md](./README_CN.md)

## Development and testing

```bash
# Unit tests for this package (memory host)
pnpm --filter @brookesia/service test

# Example demo regression (esp-brookesia-apps repo)
npm run test:service
```

## C++ reference

RPC schemas and runtime behavior follow the C++ components:

[esp-brookesia/service](https://github.com/espressif/esp-brookesia/tree/master/service)