iii-browser-sdk 0.10.0-beta.1

package/LICENSE.spdx

@@ -0,0 +1,22 @@
+SPDXVersion: SPDX-2.1
+DataLicense: CC0-1.0
+PackageName: iii
+DataFormat: SPDXRef-1
+PackageSupplier: Organization: Motia LLC
+PackageHomePage: https://iii.dev
+PackageLicenseDeclared: Elastic-2.0
+PackageLicenseDeclared: Apache-2.0
+PackageCopyrightText: 2024-present, Motia LLC
+PackageSummary: <text>iii is a single engine with three primitives (Function, Trigger, Discovery)
+that replaces API frameworks, task queues, cron schedulers, pub/sub, state stores,
+and observability pipelines.
+                </text>
+PackageComment: <text>The engine runtime (engine/) is licensed under Elastic License 2.0.
+All other components (sdk/, cli/, console/, frameworks/, docs/, website/)
+are licensed under Apache License 2.0.
+                </text>
+Created: 2024-01-01T00:00:00Z
+PackageDownloadLocation: git://github.com/iii-hq/iii
+PackageDownloadLocation: git+https://github.com/iii-hq/iii.git
+PackageDownloadLocation: git+ssh://github.com/iii-hq/iii.git
+Creator: Organization: Motia LLC

package/README.md

@@ -0,0 +1,118 @@
+[![iii](https://iii.dev/og-image.png)](https://iii.dev)
+
+This is an SDK for [iii](https://iii.dev) — unreasonably simple backend development.
+
+# iii-browser-sdk
+
+Browser SDK for the [iii engine](https://github.com/iii-hq/iii) — WebSocket-based, no Node.js dependencies, no OpenTelemetry.
+
+[![npm](https://img.shields.io/npm/v/iii-browser-sdk)](https://www.npmjs.com/package/iii-browser-sdk)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../../LICENSE)
+
+## Why the browser SDK
+
+The browser SDK turns your frontend into a **first-class iii worker**:
+
+- **Persistent connection** — one WebSocket replaces many HTTP round-trips.
+- **Bi-directional** — the engine can invoke functions registered in the browser. Backend workers push data to the frontend with `trigger()`, enabling real-time patterns without polling.
+- **Same API** — `registerFunction`, `trigger`, `registerTrigger`, `onFunctionsAvailable` — all the primitives you use server-side work identically in the browser.
+- **Zero Node.js dependencies** — runs in any browser environment with native `WebSocket`.
+
+## Install
+
+```bash
+npm install iii-browser-sdk
+```
+
+## Hello World
+
+```typescript
+import { registerWorker } from 'iii-browser-sdk'
+
+const iii = registerWorker('ws://localhost:49135', {
+  workerName: 'browser-client',
+})
+
+iii.registerFunction(
+  { id: 'ui::show-notification' },
+  async (data: { title: string; body: string }) => {
+    showToast(data.title, data.body)
+    return { displayed: true }
+  },
+)
+
+const users = await iii.trigger({
+  function_id: 'api::get::users',
+  payload: {},
+})
+```
+
+## API
+
+| Operation                | Signature                                                             | Description                                                  |
+| ------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Initialize               | `registerWorker(url, options?)`                                       | Connect to the engine via browser WebSocket. Returns `ISdk`  |
+| Register function        | `iii.registerFunction({ id }, handler)`                               | Register a function the engine (or backend) can invoke       |
+| Register trigger         | `iii.registerTrigger({ type, function_id, config })`                  | Bind a trigger to a function                                 |
+| Invoke (await)           | `await iii.trigger({ function_id, payload })`                         | Invoke a function and wait for the result                    |
+| Invoke (fire-and-forget) | `iii.trigger({ function_id, payload, action: TriggerAction.Void() })` | Invoke without waiting                                       |
+| Create channel           | `iii.createChannel()`                                                 | Create a streaming channel pair (writer + reader)            |
+| Functions available      | `iii.onFunctionsAvailable(fn)`                                        | Subscribe to function availability changes                   |
+| Shutdown                 | `iii.shutdown()`                                                      | Gracefully disconnect from the engine                        |
+
+### Registering Functions
+
+Register a function in the browser that backend workers can call:
+
+```typescript
+iii.registerFunction(
+  { id: 'ui::show-notification' },
+  async (data: { title: string; body: string }) => {
+    showToast(data.title, data.body)
+    return { displayed: true }
+  },
+)
+```
+
+### Calling Backend Functions
+
+Invoke any function registered in the engine directly from the browser:
+
+```typescript
+const users = await iii.trigger({
+  function_id: 'api::get::users',
+  payload: {},
+})
+```
+
+### Receiving Live Invocations
+
+Backend workers can push data to the browser in real time. No polling required:
+
+```typescript
+iii.registerFunction(
+  { id: 'ui::update-dashboard' },
+  async (metrics: { cpu: number; memory: number; requests: number }) => {
+    document.getElementById('cpu')!.textContent = `${metrics.cpu}%`
+    document.getElementById('memory')!.textContent = `${metrics.memory}MB`
+    document.getElementById('requests')!.textContent = `${metrics.requests}/s`
+    return null
+  },
+)
+```
+
+## Exports
+
+| Import                   | What it provides                      |
+| ------------------------ | ------------------------------------- |
+| `iii-browser-sdk`        | Core SDK (`registerWorker`, types)    |
+| `iii-browser-sdk/stream` | Stream types for real-time state      |
+| `iii-browser-sdk/state`  | State types for key-value operations  |
+
+## Resources
+
+- [Documentation](https://iii.dev/docs)
+- [Use iii in the Browser](https://iii.dev/docs/how-to/use-iii-in-the-browser)
+- [Browser SDK API Reference](https://iii.dev/docs/api-reference/sdk-browser)
+- [iii Engine](https://github.com/iii-hq/iii)
+- [Examples](https://github.com/iii-hq/iii-examples)