@omirion/orbit-sdk 0.1.1 → 0.3.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,20 +51,30 @@ 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'`.
 
+## Examples
+
+Two runnable examples ship in this package under `examples/`. Copy a folder anywhere, `pnpm install`, and follow its README.
+
+- `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
 
 MIT

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:
@@ -1299,28 +1295,53 @@ var OrbitClient = class {
     this.#retryBaseDelayMs = options.retryBaseDelayMs ?? 500;
     const client2 = this.#client;
     const run = this.#run.bind(this);
-    this.me = () => run(() => getIdentity({ client: client2, throwOnError: false }));
+    this.me = () => run(() => getIdentity({ client: client2, throwOnError: false })).then(
+      (result) => result.data
+    );
     this.projects = {
       list: (params = {}) => run(() => listProjects({ client: client2, query: params, throwOnError: false })),
       iterate: (params = {}) => paginate(async (cursor) => {
         const page = await run(
-          () => listProjects({ client: client2, query: { ...params, cursor }, throwOnError: false })
+          () => listProjects({
+            client: client2,
+            query: { ...params, cursor },
+            throwOnError: false
+          })
         );
-        return { data: page.data, nextCursor: page.meta.nextCursor, hasMore: page.meta.hasMore };
+        return {
+          data: page.data,
+          nextCursor: page.meta.nextCursor,
+          hasMore: page.meta.hasMore
+        };
       }),
-      get: (id) => run(() => getProject({ client: client2, path: { id }, throwOnError: false })),
+      get: (id) => run(() => getProject({ client: client2, path: { id }, throwOnError: false })).then(
+        (result) => result.data
+      ),
       appToken: {
         create: (projectId) => run(
-          () => createProjectAppToken({ client: client2, path: { id: projectId }, throwOnError: false })
-        ),
+          () => createProjectAppToken({
+            client: client2,
+            path: { id: projectId },
+            throwOnError: false
+          })
+        ).then((result) => result.data),
         rotate: (projectId) => run(
-          () => rotateProjectAppToken({ client: client2, path: { id: projectId }, throwOnError: false })
-        )
+          () => rotateProjectAppToken({
+            client: client2,
+            path: { id: projectId },
+            throwOnError: false
+          })
+        ).then((result) => result.data)
       }
     };
     this.deviceTypes = {
       list: (projectId, params = {}) => run(
-        () => listDeviceTypes({ client: client2, path: { projectId }, query: params, throwOnError: false })
+        () => listDeviceTypes({
+          client: client2,
+          path: { projectId },
+          query: params,
+          throwOnError: false
+        })
       ),
       iterate: (projectId, params = {}) => paginate(async (cursor) => {
         const page = await run(
@@ -1331,36 +1352,70 @@ var OrbitClient = class {
             throwOnError: false
           })
         );
-        return { data: page.data, nextCursor: page.meta.nextCursor, hasMore: page.meta.hasMore };
+        return {
+          data: page.data,
+          nextCursor: page.meta.nextCursor,
+          hasMore: page.meta.hasMore
+        };
       }),
       get: (projectId, slug) => run(
-        () => getDeviceType({ client: client2, path: { projectId, slug }, throwOnError: false })
-      ),
+        () => getDeviceType({
+          client: client2,
+          path: { projectId, slug },
+          throwOnError: false
+        })
+      ).then((result) => result.data),
       create: (projectId, body) => run(
-        () => createDeviceType({ client: client2, path: { projectId }, body, throwOnError: false })
-      ),
+        () => createDeviceType({
+          client: client2,
+          path: { projectId },
+          body,
+          throwOnError: false
+        })
+      ).then((result) => result.data),
       update: (projectId, slug, body) => run(
-        () => updateDeviceType({ client: client2, path: { projectId, slug }, body, throwOnError: false })
-      ),
+        () => updateDeviceType({
+          client: client2,
+          path: { projectId, slug },
+          body,
+          throwOnError: false
+        })
+      ).then((result) => result.data),
       delete: async (projectId, slug) => {
         await run(
-          () => deleteDeviceType({ client: client2, path: { projectId, slug }, throwOnError: false })
+          () => deleteDeviceType({
+            client: client2,
+            path: { projectId, slug },
+            throwOnError: false
+          })
         );
       }
     };
     this.devices = {
       list: (params = {}) => run(() => listDevices({ client: client2, query: params, throwOnError: false })),
-      get: (id) => run(() => getDevice({ client: client2, path: { id }, throwOnError: false })),
+      get: (id) => run(() => getDevice({ client: client2, path: { id }, throwOnError: false })).then(
+        (result) => result.data
+      ),
       iterate: (params = {}) => paginate(async (cursor) => {
         const page = await run(
-          () => listDevices({ client: client2, query: { ...params, cursor }, throwOnError: false })
+          () => listDevices({
+            client: client2,
+            query: { ...params, cursor },
+            throwOnError: false
+          })
         );
-        return { data: page.data, nextCursor: page.meta.nextCursor, hasMore: page.meta.hasMore };
+        return {
+          data: page.data,
+          nextCursor: page.meta.nextCursor,
+          hasMore: page.meta.hasMore
+        };
       }),
       delete: async (id) => {
         await run(() => deleteDevice({ client: client2, path: { id }, throwOnError: false }));
       },
-      resetToken: (id) => run(() => resetDeviceToken({ client: client2, path: { id }, throwOnError: false }))
+      resetToken: (id) => run(
+        () => resetDeviceToken({ client: client2, path: { id }, throwOnError: false })
+      ).then((result) => result.data)
     };
     this.admissions = {
       list: (params = {}) => run(
@@ -1368,34 +1423,68 @@ var OrbitClient = class {
       ),
       iterate: (params = {}) => paginate(async (cursor) => {
         const page = await run(
-          () => listAdmissions({ client: client2, query: { ...params, cursor }, throwOnError: false })
+          () => listAdmissions({
+            client: client2,
+            query: { ...params, cursor },
+            throwOnError: false
+          })
         );
-        return { data: page.data, nextCursor: page.meta.nextCursor, hasMore: page.meta.hasMore };
+        return {
+          data: page.data,
+          nextCursor: page.meta.nextCursor,
+          hasMore: page.meta.hasMore
+        };
       }),
-      get: (id) => run(() => getAdmission({ client: client2, path: { id }, throwOnError: false })),
+      get: (id) => run(
+        () => getAdmission({ client: client2, path: { id }, throwOnError: false })
+      ).then((result) => result.data),
       accept: (id, params) => run(
-        () => acceptAdmission({ client: client2, path: { id }, body: params, throwOnError: false })
-      ),
-      reject: (id) => run(() => rejectAdmission({ client: client2, path: { id }, throwOnError: false })),
-      dismiss: (id) => run(() => dismissAdmission({ client: client2, path: { id }, throwOnError: false }))
+        () => acceptAdmission({
+          client: client2,
+          path: { id },
+          body: params,
+          throwOnError: false
+        })
+      ).then((result) => result.data),
+      reject: (id) => run(
+        () => rejectAdmission({ client: client2, path: { id }, throwOnError: false })
+      ).then((result) => result.data),
+      dismiss: (id) => run(
+        () => dismissAdmission({ client: client2, path: { id }, throwOnError: false })
+      ).then((result) => result.data)
     };
     this.telemetry = {
       latest: (deviceId) => run(
-        () => getLatestTelemetry({ client: client2, path: { id: deviceId }, throwOnError: false })
-      ),
+        () => getLatestTelemetry({
+          client: client2,
+          path: { id: deviceId },
+          throwOnError: false
+        })
+      ).then((result) => result.data),
       history: (deviceId, params = {}) => run(
-        () => getTelemetryHistory({ client: client2, path: { id: deviceId }, query: params, throwOnError: false })
+        () => getTelemetryHistory({
+          client: client2,
+          path: { id: deviceId },
+          query: params,
+          throwOnError: false
+        })
       ).then((result) => result.data),
       manifest: (deviceId) => run(
-        () => getTelemetryManifest({ client: client2, path: { id: deviceId }, throwOnError: false })
-      )
+        () => getTelemetryManifest({
+          client: client2,
+          path: { id: deviceId },
+          throwOnError: false
+        })
+      ).then((result) => result.data)
     };
     this.firmware = {
       upload: (params) => run(
         () => uploadFirmware({ client: client2, body: params, throwOnError: false })
-      ).then((result) => result.bundle),
+      ).then((result) => result.data),
       deleteBundle: async (id) => {
-        await run(() => deleteFirmwareBundle({ client: client2, path: { id }, throwOnError: false }));
+        await run(
+          () => deleteFirmwareBundle({ client: client2, path: { id }, throwOnError: false })
+        );
       },
       bundles: {
         list: (params = {}) => run(
@@ -1403,22 +1492,44 @@ var OrbitClient = class {
         ),
         iterate: (params = {}) => paginate(async (cursor) => {
           const page = await run(
-            () => listFirmwareBundles({ client: client2, query: { ...params, cursor }, throwOnError: false })
+            () => listFirmwareBundles({
+              client: client2,
+              query: { ...params, cursor },
+              throwOnError: false
+            })
           );
-          return { data: page.data, nextCursor: page.meta.nextCursor, hasMore: page.meta.hasMore };
+          return {
+            data: page.data,
+            nextCursor: page.meta.nextCursor,
+            hasMore: page.meta.hasMore
+          };
         }),
-        get: (id) => run(() => getFirmwareBundle({ client: client2, path: { id }, throwOnError: false }))
+        get: (id) => run(
+          () => getFirmwareBundle({ client: client2, path: { id }, throwOnError: false })
+        ).then((result) => result.data)
       },
       deployments: {
         trigger: (params) => run(
-          () => triggerFirmwareDeployment({ client: client2, body: params, throwOnError: false })
-        ).then((result) => result.deployments),
+          () => triggerFirmwareDeployment({
+            client: client2,
+            body: params,
+            throwOnError: false
+          })
+        ).then((result) => result.data),
         list: (params = {}) => run(
-          () => listFirmwareDeployments({ client: client2, query: params, throwOnError: false })
+          () => listFirmwareDeployments({
+            client: client2,
+            query: params,
+            throwOnError: false
+          })
         ),
         iterate: (params = {}) => paginate(async (cursor) => {
           const page = await run(
-            () => listFirmwareDeployments({ client: client2, query: { ...params, cursor }, throwOnError: false })
+            () => listFirmwareDeployments({
+              client: client2,
+              query: { ...params, cursor },
+              throwOnError: false
+            })
           );
           return {
             data: page.data,
@@ -1427,39 +1538,64 @@ var OrbitClient = class {
           };
         }),
         get: (id) => run(
-          () => getFirmwareDeployment({ client: client2, path: { id }, throwOnError: false })
-        ),
+          () => getFirmwareDeployment({
+            client: client2,
+            path: { id },
+            throwOnError: false
+          })
+        ).then((result) => result.data),
         cancel: (id, params = {}) => run(
-          () => cancelFirmwareDeployment({ client: client2, path: { id }, body: params, throwOnError: false })
-        ),
+          () => cancelFirmwareDeployment({
+            client: client2,
+            path: { id },
+            body: params,
+            throwOnError: false
+          })
+        ).then((result) => result.data),
         rollback: (id, params = {}) => run(
-          () => rollbackFirmwareDeployment({ client: client2, path: { id }, body: params, throwOnError: false })
-        )
+          () => rollbackFirmwareDeployment({
+            client: client2,
+            path: { id },
+            body: params,
+            throwOnError: false
+          })
+        ).then((result) => result.data)
       }
     };
     this.commands = {
       exec: (deviceId, command) => run(
-        () => execDeviceCommand({ client: client2, path: { id: deviceId }, body: command, throwOnError: false })
-      ),
+        () => execDeviceCommand({
+          client: client2,
+          path: { id: deviceId },
+          body: command,
+          throwOnError: false
+        })
+      ).then((result) => result.data),
       get: (deviceId, invocationId) => run(
         () => getDeviceCommandInvocation({
           client: client2,
           path: { id: deviceId, invocationId },
           throwOnError: false
         })
-      ),
+      ).then((result) => result.data),
       manifest: (deviceId) => run(
-        () => getDeviceCommands({ client: client2, path: { id: deviceId }, throwOnError: false })
-      )
+        () => getDeviceCommands({
+          client: client2,
+          path: { id: deviceId },
+          throwOnError: false
+        })
+      ).then((result) => result.data)
     };
     this.usb = {
-      list: (deviceId) => run(() => listExportable(client2, deviceId)).then(
-        (result) => result.exports
-      ),
-      ticket: (params) => run(() => createTicket(client2, params))
+      list: (deviceId) => run(() => listExportable(client2, deviceId)).then((result) => result.data),
+      ticket: (params) => run(() => createTicket(client2, params)).then(
+        (result) => result.data
+      )
     };
     this.terminal = {
-      ticket: (params) => run(() => createTicket2(client2, params))
+      ticket: (params) => run(() => createTicket2(client2, params)).then(
+        (result) => result.data
+      )
     };
     this.webhooks = {
       list: (params = {}) => run(
@@ -1467,22 +1603,42 @@ var OrbitClient = class {
       ),
       iterate: (params = {}) => paginate(async (cursor) => {
         const page = await run(
-          () => listWebhooks({ client: client2, query: { ...params, cursor }, throwOnError: false })
+          () => listWebhooks({
+            client: client2,
+            query: { ...params, cursor },
+            throwOnError: false
+          })
         );
-        return { data: page.data, nextCursor: page.meta.nextCursor, hasMore: page.meta.hasMore };
+        return {
+          data: page.data,
+          nextCursor: page.meta.nextCursor,
+          hasMore: page.meta.hasMore
+        };
       }),
       create: (params) => run(
         () => createWebhook({ client: client2, body: params, throwOnError: false })
-      ),
-      get: (id) => run(() => getWebhook({ client: client2, path: { id }, throwOnError: false })),
+      ).then((result) => result.data),
+      get: (id) => run(
+        () => getWebhook({ client: client2, path: { id }, throwOnError: false })
+      ).then((result) => result.data),
       update: (id, params) => run(
-        () => updateWebhook({ client: client2, path: { id }, body: params, throwOnError: false })
-      ),
+        () => updateWebhook({
+          client: client2,
+          path: { id },
+          body: params,
+          throwOnError: false
+        })
+      ).then((result) => result.data),
       delete: async (id) => {
         await run(() => deleteWebhook({ client: client2, path: { id }, throwOnError: false }));
       },
       deliveries: (id, params = {}) => run(
-        () => listWebhookDeliveries({ client: client2, path: { id }, query: params, throwOnError: false })
+        () => listWebhookDeliveries({
+          client: client2,
+          path: { id },
+          query: params,
+          throwOnError: false
+        })
       ),
       iterateDeliveries: (id, params = {}) => paginate(async (cursor) => {
         const page = await run(
@@ -1493,7 +1649,11 @@ var OrbitClient = class {
             throwOnError: false
           })
         );
-        return { data: page.data, nextCursor: page.meta.nextCursor, hasMore: page.meta.hasMore };
+        return {
+          data: page.data,
+          nextCursor: page.meta.nextCursor,
+          hasMore: page.meta.hasMore
+        };
       })
     };
   }
@@ -1661,6 +1821,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;