@omirion/orbit-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omirion
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @omirion/orbit-sdk
+
+Official TypeScript SDK for the [Omirion Orbit](https://orbit.omirion.com)
+public API (`/api/v1`). Works in Node 18+, Deno, Bun, Cloudflare Workers, and
+browsers. ESM + CJS, fully typed, zero runtime dependencies (the fetch client is
+bundled).
+
+## Install
+
+```bash
+npm install @omirion/orbit-sdk     # or pnpm add / yarn add
+```
+
+## Quickstart
+
+Create a token in the dashboard (**Account → API tokens**), then:
+
+```ts
+import { OrbitClient, decodeSample } from '@omirion/orbit-sdk'
+
+const orbit = new OrbitClient({ token: process.env.ORBIT_TOKEN! })
+// baseUrl defaults to https://orbit.omirion.com; sends `Authorization: Bearer oat_…`
+
+// Cursor pagination is automatic, iterate every device, online only:
+for await (const device of orbit.devices.iterate({ status: 'online' })) {
+  const sample = await orbit.telemetry.latest(device.id)
+  if (!sample) continue
+
+  // Join abbreviated metric keys to their labels/units via the manifest:
+  const manifest = await orbit.telemetry.manifest(device.id)
+  const rows = manifest ? decodeSample(sample, manifest) : []
+  for (const r of rows) console.log(`${device.name} · ${r.label}: ${r.value}${r.unit ?? ''}`)
+}
+```
+
+`OrbitClient` wraps the generated transport client with bearer auth, automatic
+retries (429/502/503/504 + network) with backoff, response unwrapping, cursor
+auto-pagination, and **typed errors** you can `catch`:
+
+```ts
+import { InsufficientScopeError, DeviceRpcError } from '@omirion/orbit-sdk'
+
+try {
+  await orbit.commands.exec(deviceId, { argv: ['systemctl', 'status', 'orbit-agent'] })
+} catch (err) {
+  if (err instanceof InsufficientScopeError) {/* token missing api:command:exec */}
+  else if (err instanceof DeviceRpcError) {/* device offline / transport failed */}
+  else throw err
+}
+```
+
+### Surface
+
+- `orbit.me()`. Who the token authenticates as, its abilities and project
+  scope, and the projects it reaches. Requires no ability: the cheapest way to
+  verify a token works and to discover valid `projectId` values.
+- `orbit.devices`. `list(params?)`, `get(id)`, `iterate(params?)` (async generator)
+- `orbit.telemetry`. `latest(deviceId)`, `history(deviceId, { hours? })`, `manifest(deviceId)`
+- `orbit.firmware`. `upload({ file, projectId, version, compatible, description? })`
+- `orbit.commands`. `exec(deviceId, { argv, elevate?, timeoutMs? })`
+- `decodeSample(sample, manifest)` / `decodeSamples(...)`, labelled telemetry rows
+- Errors: `OrbitError` + `AuthenticationError`, `InsufficientScopeError`,
+  `ResourceNotFoundError`, `BadRequestError`, `ValidationError`,
+  `BundleExistsError`, `DeviceRpcError`, `RateLimitError`, `ServerError`, `NetworkError`
+
+The raw generated transport client is still available under `import { raw } from '@omirion/orbit-sdk'`.
+
+## Develop
+
+```bash
+pnpm install --ignore-workspace
+pnpm generate     # regenerate src/generated/ from ../spec/openapi.json
+pnpm typecheck
+pnpm test         # vitest (ergonomics layer)
+pnpm build        # tsup → dist/ (ESM + CJS + .d.ts)
+```
+
+`src/generated/` is committed and must never be hand-edited, change the server
+spec and regenerate (`pnpm sdk:gen` from the repo root).
+
+## License
+
+MIT