@omirion/orbit-sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,9 +1,6 @@
 # @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).
+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
 
@@ -33,15 +30,18 @@ for await (const device of orbit.devices.iterate({ status: 'online' })) {
 }
 ```
 
-`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`:
+`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'] })
+  // Commands are declared per device type, a name plus typed key/value args, no shell.
+  // `orbit.commands.manifest(deviceId)` lists what this device accepts.
+  const result = await orbit.commands.exec(deviceId, { name: 'state-request', timeoutMs: 10_000 })
+  if (result.queued) {
+    // Store-and-forward device: poll orbit.commands.get(deviceId, result.invocationId)
+  }
 } catch (err) {
   if (err instanceof InsufficientScopeError) {/* token missing api:command:exec */}
   else if (err instanceof DeviceRpcError) {/* device offline / transport failed */}
@@ -51,32 +51,29 @@ try {
 
 ### 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`
+Every collection has a cursor-paginated `list(params?)` and a lazy `iterate(params?)` async-generator twin that walks all pages.
+
+- `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.projects`. `list` / `iterate` / `get(id)`, plus `appToken.create(projectId)` / `appToken.rotate(projectId)` (the provisioning token is returned once and never again).
+- `orbit.deviceTypes`. `list` / `iterate` / `get(projectId, slug)` / `create` / `update` / `delete`, the models a fleet identifies as, with their telemetry and command manifests.
+- `orbit.devices`. `list` / `iterate` / `get(id)` / `delete(id)` / `resetToken(id)`.
+- `orbit.admissions`. `list` / `iterate` / `get(id)` / `accept` / `reject` / `dismiss`, the fleet-join requests.
+- `orbit.telemetry`. `latest(deviceId)`, `history(deviceId, { hours? })`, `manifest(deviceId)`.
+- `orbit.firmware`. `upload({ file, projectId, kind?, version?, compatible?, description? })` (version and target are decoded from the binary where it carries them), `deleteBundle(id)`, `bundles.list` / `iterate` / `get`, `deployments.trigger` / `list` / `iterate` / `get` / `cancel` / `rollback`.
+- `orbit.commands`. `exec(deviceId, { name, args?, timeoutMs? })`, `get(deviceId, invocationId)` (the pull path for a queued dispatch), `manifest(deviceId)`.
+- `orbit.webhooks`. `list` / `iterate` / `create` / `get` / `update` / `delete` / `deliveries` / `iterateDeliveries`. Receiver-side helpers `verifyWebhookSignature` and `parseWebhookEvent` validate incoming deliveries (HMAC + replay window).
+- `orbit.usb` / `orbit.terminal`. Single-use ticket minting for the USB/IP and device-shell WebSocket planes (`api:usb:attach` / `api:terminal:open`).
+- `decodeSample(sample, manifest)` / `decodeSamples(...)`, labelled telemetry rows.
+- Errors: `OrbitError` + `AuthenticationError`, `InsufficientScopeError`, `ResourceNotFoundError`, `BadRequestError`, `ValidationError`, `ConflictError`, `BundleExistsError`, `DeviceRpcError`, `RateLimitError`, `ServerError`, `NetworkError`
 
 The raw generated transport client is still available under `import { raw } from '@omirion/orbit-sdk'`.
 
-## Develop
+## Examples
 
-```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)
-```
+Two runnable examples ship in this package under `examples/`. Copy a folder anywhere, `pnpm install`, and follow its README.
 
-`src/generated/` is committed and must never be hand-edited, change the server
-spec and regenerate (`pnpm sdk:gen` from the repo root).
+- `examples/device-rpc-flow`. An Ink terminal UI walking the full read-then-act loop, list devices, decode their latest telemetry via the type manifest, then drive a device through a sequence of declared commands.
+- `examples/webhook-listener`. The smallest useful webhook receiver, verifies every delivery's signature with `parseWebhookEvent`, dedupes on the event id, and prints each event.
 
 ## License
 

package/dist/index.cjs

@@ -1109,7 +1109,9 @@ var ValidationError = class extends OrbitError {
     this.fieldErrors = options.fieldErrors ?? [];
   }
 };
-var BundleExistsError = class extends OrbitError {
+var ConflictError = class extends OrbitError {
+};
+var BundleExistsError = class extends ConflictError {
 };
 var DeviceRpcError = class extends OrbitError {
 };
@@ -1127,12 +1129,6 @@ var RateLimitError = class extends OrbitError {
 function extractErrorFields(body) {
   if (!body || typeof body !== "object") return {};
   const record = body;
-  if (typeof record.error === "string") {
-    return {
-      code: record.error,
-      message: typeof record.message === "string" ? record.message : record.error
-    };
-  }
   if (Array.isArray(record.errors) && record.errors.length > 0) {
     const first = record.errors[0];
     return {
@@ -1184,7 +1180,7 @@ function normalizeError(status, body, response) {
     case 404:
       return new ResourceNotFoundError(msg, base);
     case 409:
-      return new BundleExistsError(msg, base);
+      return code === "E_BUNDLE_ALREADY_EXISTS" ? new BundleExistsError(msg, base) : new ConflictError(msg, base);
     case 422:
       return new ValidationError(msg, { ...base, fieldErrors: extractFieldErrors(body) });
     case 429:
@@ -1661,6 +1657,7 @@ __export(generated_exports, {
 exports.AuthenticationError = AuthenticationError;
 exports.BadRequestError = BadRequestError;
 exports.BundleExistsError = BundleExistsError;
+exports.ConflictError = ConflictError;
 exports.DeviceRpcError = DeviceRpcError;
 exports.InsufficientScopeError = InsufficientScopeError;
 exports.NetworkError = NetworkError;