@omirion/orbit-sdk 0.1.1 → 0.3.0

package/examples/device-rpc-flow/README.md

@@ -0,0 +1,43 @@
+# device-rpc-flow (TypeScript / Ink)
+
+A terminal UI demo of `@omirion/orbit-sdk` built with [Ink](https://github.com/vadimdemedes/ink) (React for CLIs). It walks the full read-then-act loop against a real device:
+
+1. **List devices**. `orbit.devices.list()`
+2. **Select the first one**. `orbit.devices.get(id)` (the full device carries the `deviceTypeSlug` needed to decode telemetry)
+3. **Show latest telemetry**. `orbit.telemetry.latest(id)` joined to the type manifest via `decodeSample()`
+4. **Run the RPC command flow**. A sequence of `orbit.commands.exec(id, { name, args })` calls, run in order, stopping at the first failure
+
+The command flow drives an attached Android device over adb:
+
+```
+input-text  text="0321"                          → types the text
+keyevent    code=66                               → KEYCODE_ENTER
+input-text  text="14110108"                       → types the text
+keyevent    code=66                               → KEYCODE_ENTER
+launch-app  package="com.example.app"             → launches the app
+```
+
+> Commands are **declared per device type**, a name plus typed args, validated against the type's command manifest before dispatch. `input-text` / `keyevent` / `launch-app` are **exec commands**. The device type's manifest declares a `runtime` (`adb`) and an `argvTemplate`; the server substitutes the validated args into a concrete argv, Ed25519-signs it, and the device runs it with no shell, nothing to quote or escape. Edit the values (and package) for your device.
+
+## Run
+
+Copy this folder anywhere, then:
+
+```bash
+pnpm install     # or npm install
+ORBIT_TOKEN=oat_your_token pnpm start
+```
+
+Point it at a non-production server with `ORBIT_BASE_URL`:
+
+```bash
+ORBIT_TOKEN=oat_… ORBIT_BASE_URL=http://localhost:1411 pnpm start
+```
+
+The RPC steps run with a fixed pause between them, purely for watchability. It defaults to 750 ms, tune it with `ORBIT_CMD_DELAY_MS`:
+
+```bash
+ORBIT_TOKEN=oat_… ORBIT_CMD_DELAY_MS=1200 pnpm start
+```
+
+The token is a personal access token minted in the dashboard at **Account → API tokens**; it needs the `api:devices:read`, `api:telemetry:read`, and `api:command:exec` abilities for the steps above.

package/examples/device-rpc-flow/index.tsx

@@ -0,0 +1,502 @@
+/**
+ * device-rpc-flow, an Ink (React-for-CLIs) demo of the Omirion Orbit SDK.
+ *
+ * Flow:
+ *   1. List devices
+ *   2. Take the first one (full fetch, for its device-type + telemetry slug)
+ *   3. Show its latest telemetry, decoded against the type manifest
+ *   4. Drive an Android device over adb, type input, send key events, launch
+ *      an app, via exec commands (server-resolved argv, signed, no shell)
+ *
+ * Run with:  ORBIT_TOKEN=oat_… pnpm start
+ */
+import React, { useEffect, useReducer } from "react";
+import { render, Box, Text, useApp } from "ink";
+import Spinner from "ink-spinner";
+import { OrbitClient, decodeSample } from "@omirion/orbit-sdk";
+import type { CommandResult, DecodedMetric, Device } from "@omirion/orbit-sdk";
+
+const BASE_URL = process.env.ORBIT_BASE_URL ?? "https://orbit.omirion.com";
+
+/** Fixed pause between RPC commands, purely for watchability. */
+const COMMAND_DELAY_MS = Number(process.env.ORBIT_CMD_DELAY_MS ?? 750);
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+type CommandArgs = Record<string, string | number | boolean>;
+
+/**
+ * The RPC flow. Commands are **declared per device type**, a name plus typed
+ * args, validated against the type's command manifest before dispatch. Exec
+ * commands (like these adb verbs) carry a `runtime` + `argvTemplate` in the
+ * manifest; the server substitutes the args into a concrete argv, signs it, and
+ * the device runs it with no shell. Edit the values for your own device.
+ */
+const COMMANDS: Array<{ label: string; name: string; args?: CommandArgs }> = [
+  { label: "Type text", name: "input-text", args: { text: "14110108" } },
+  { label: "Press Enter", name: "keyevent", args: { code: 66 } },
+  {
+    label: "Launch app",
+    name: "launch-app",
+    args: { package: "com.omirion.clients.gtmsgc" },
+  },
+];
+
+const renderCommand = (c: { name: string; args?: CommandArgs }): string =>
+  c.args
+    ? `${c.name} ${Object.entries(c.args)
+        .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+        .join(" ")}`
+    : c.name;
+
+type Status = "pending" | "active" | "ok" | "fail" | "skip";
+
+interface Step {
+  id: string;
+  label: string;
+  status: Status;
+  note?: string;
+}
+
+interface CmdState {
+  label: string;
+  name: string;
+  args?: CommandArgs;
+  status: Status;
+  result?: CommandResult;
+  error?: string;
+}
+
+interface State {
+  steps: Step[];
+  commands: CmdState[];
+  deviceCount?: number;
+  device?: Device;
+  metrics?: DecodedMetric[];
+  telemetryAt?: string;
+  telemetryEmpty?: boolean;
+  fatal?: string;
+  finished: boolean;
+}
+
+type Action =
+  | { type: "step"; id: string; status: Status; note?: string }
+  | {
+      type: "cmd";
+      i: number;
+      status: Status;
+      result?: CommandResult;
+      error?: string;
+    }
+  | { type: "set"; patch: Partial<State> };
+
+const initialState: State = {
+  steps: [
+    { id: "list", label: "List devices", status: "pending" },
+    { id: "select", label: "Select first device", status: "pending" },
+    { id: "telemetry", label: "Read latest telemetry", status: "pending" },
+    { id: "commands", label: "Run RPC command flow", status: "pending" },
+  ],
+  commands: COMMANDS.map((c) => ({ ...c, status: "pending" as Status })),
+  finished: false,
+};
+
+function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case "step":
+      return {
+        ...state,
+        steps: state.steps.map((s) =>
+          s.id === action.id
+            ? { ...s, status: action.status, note: action.note ?? s.note }
+            : s,
+        ),
+      };
+    case "cmd":
+      return {
+        ...state,
+        commands: state.commands.map((c, idx) =>
+          idx === action.i
+            ? {
+                ...c,
+                status: action.status,
+                result: action.result,
+                error: action.error,
+              }
+            : c,
+        ),
+      };
+    case "set":
+      return { ...state, ...action.patch };
+  }
+}
+
+const GLYPH: Record<Status, string> = {
+  pending: "○",
+  active: "",
+  ok: "✔",
+  fail: "✖",
+  skip: "⏭",
+};
+
+const COLOR: Record<Status, string> = {
+  pending: "gray",
+  active: "cyan",
+  ok: "green",
+  fail: "red",
+  skip: "gray",
+};
+
+function StatusIcon({ status }: { status: Status }) {
+  if (status === "active") {
+    return (
+      <Text color="cyan">
+        <Spinner type="dots" />
+      </Text>
+    );
+  }
+  return <Text color={COLOR[status]}>{GLYPH[status]}</Text>;
+}
+
+function formatValue(m: DecodedMetric): string {
+  const v = m.value;
+  if (typeof v === "boolean") return v ? "yes" : "no";
+  const num =
+    typeof v === "number" ? String(Math.round(v * 1000) / 1000) : String(v);
+  return m.unit ? `${num} ${m.unit}` : num;
+}
+
+function Header() {
+  return (
+    <Box
+      borderStyle="round"
+      borderColor="cyan"
+      paddingX={1}
+      flexDirection="column"
+      marginBottom={1}
+    >
+      <Text color="cyan" bold>
+        ◍ Omirion Orbit · Device RPC Flow
+      </Text>
+      <Text color="gray">{BASE_URL}</Text>
+    </Box>
+  );
+}
+
+function Steps({ steps }: { steps: Step[] }) {
+  return (
+    <Box flexDirection="column">
+      {steps.map((s) => (
+        <Box key={s.id}>
+          <Box width={3}>
+            <StatusIcon status={s.status} />
+          </Box>
+          <Text color={s.status === "pending" ? "gray" : undefined}>
+            {s.label}
+          </Text>
+          {s.note ? <Text color="gray">. {s.note}</Text> : null}
+        </Box>
+      ))}
+    </Box>
+  );
+}
+
+function DevicePanel({ device }: { device: Device }) {
+  const row = (label: string, value: string) => (
+    <Box>
+      <Box width={16}>
+        <Text color="gray">{label}</Text>
+      </Box>
+      <Text>{value}</Text>
+    </Box>
+  );
+  return (
+    <Box
+      borderStyle="round"
+      borderColor="magenta"
+      paddingX={1}
+      flexDirection="column"
+      marginY={1}
+    >
+      <Text color="magenta" bold>
+        Selected device
+      </Text>
+      {row("Name", device.name)}
+      {row("ID", device.id)}
+      {row("Status", device.isOnline ? "● online" : "○ offline")}
+      {row(
+        "Type",
+        `${device.deviceTypeName ?? "–"} (${device.deviceTypeSlug ?? "–"})`,
+      )}
+      {row("Firmware", device.firmwareVersion ?? "–")}
+    </Box>
+  );
+}
+
+function TelemetryPanel({
+  metrics,
+  at,
+  empty,
+}: {
+  metrics?: DecodedMetric[];
+  at?: string;
+  empty?: boolean;
+}) {
+  return (
+    <Box
+      borderStyle="round"
+      borderColor="blue"
+      paddingX={1}
+      flexDirection="column"
+      marginBottom={1}
+    >
+      <Text color="blue" bold>
+        Latest telemetry {at ? <Text color="gray">· {at}</Text> : null}
+      </Text>
+      {empty ? (
+        <Text color="gray">No samples reported yet.</Text>
+      ) : (
+        (metrics ?? []).slice(0, 8).map((m) => (
+          <Box key={m.key}>
+            <Box width={22}>
+              <Text color="gray">{m.label}</Text>
+            </Box>
+            <Text bold>{formatValue(m)}</Text>
+          </Box>
+        ))
+      )}
+    </Box>
+  );
+}
+
+function CommandPanel({ commands }: { commands: CmdState[] }) {
+  return (
+    <Box
+      borderStyle="round"
+      borderColor="yellow"
+      paddingX={1}
+      flexDirection="column"
+    >
+      <Text color="yellow" bold>
+        RPC command flow
+      </Text>
+      {commands.map((c, i) => (
+        <Box key={i} flexDirection="column" marginTop={i === 0 ? 0 : 1}>
+          <Box>
+            <Box width={3}>
+              <StatusIcon status={c.status} />
+            </Box>
+            <Text color={c.status === "pending" ? "gray" : undefined}>
+              {i + 1}. {c.label}
+            </Text>
+            {c.result ? (
+              <Text color={c.result.exitCode === 0 ? "green" : "red"}>
+                {" "}
+                exit {c.result.exitCode} · {c.result.durationMs}ms
+              </Text>
+            ) : null}
+          </Box>
+          <Box paddingLeft={3}>
+            <Text color="gray">→ {renderCommand(c)}</Text>
+          </Box>
+          {c.result && c.result.output.trim() ? (
+            <Box paddingLeft={3} flexDirection="column">
+              {c.result.output
+                .trim()
+                .split("\n")
+                .slice(0, 5)
+                .map((line, k) => (
+                  <Text key={k} color="greenBright">
+                    {line}
+                  </Text>
+                ))}
+            </Box>
+          ) : null}
+          {c.result && c.result.error.trim() ? (
+            <Box paddingLeft={3} flexDirection="column">
+              {c.result.error
+                .trim()
+                .split("\n")
+                .slice(0, 5)
+                .map((line, k) => (
+                  <Text key={k} color="red">
+                    {line}
+                  </Text>
+                ))}
+            </Box>
+          ) : null}
+          {c.error ? (
+            <Box paddingLeft={3}>
+              <Text color="red">{c.error}</Text>
+            </Box>
+          ) : null}
+        </Box>
+      ))}
+    </Box>
+  );
+}
+
+function App() {
+  const { exit } = useApp();
+  const [state, dispatch] = useReducer(reducer, initialState);
+
+  useEffect(() => {
+    let cancelled = false;
+    const errMsg = (e: unknown) => (e instanceof Error ? e.message : String(e));
+
+    (async () => {
+      const token = process.env.ORBIT_TOKEN;
+      if (!token) {
+        dispatch({
+          type: "set",
+          patch: {
+            fatal:
+              "Set ORBIT_TOKEN (an oat_… token from Account → API tokens).",
+            finished: true,
+          },
+        });
+        return;
+      }
+
+      const orbit = new OrbitClient({ token, baseUrl: BASE_URL });
+      let activeStep = "list";
+
+      try {
+        // 1. List devices
+        activeStep = "list";
+        dispatch({ type: "step", id: "list", status: "active" });
+        const page = await orbit.devices.list({ limit: 25 });
+        dispatch({ type: "set", patch: { deviceCount: page.data.length } });
+        if (page.data.length === 0)
+          throw new Error("No devices visible to this token.");
+        dispatch({
+          type: "step",
+          id: "list",
+          status: "ok",
+          note: `${page.data.length} device(s)`,
+        });
+
+        // 2. Take the first one (full fetch → device-type slug)
+        activeStep = "select";
+        dispatch({ type: "step", id: "select", status: "active" });
+        const device = await orbit.devices.get(page.data[0].id);
+        dispatch({ type: "set", patch: { device } });
+        dispatch({
+          type: "step",
+          id: "select",
+          status: "ok",
+          note: device.name,
+        });
+
+        // 3. Latest telemetry, decoded against the manifest
+        activeStep = "telemetry";
+        dispatch({ type: "step", id: "telemetry", status: "active" });
+        const sample = await orbit.telemetry.latest(device.id);
+        if (!sample) {
+          dispatch({ type: "set", patch: { telemetryEmpty: true } });
+          dispatch({
+            type: "step",
+            id: "telemetry",
+            status: "ok",
+            note: "no samples yet",
+          });
+        } else {
+          const manifest = await orbit.telemetry.manifest(device.id);
+          const metrics = manifest
+            ? decodeSample(sample, manifest)
+            : Object.entries(
+                sample.metrics as Record<string, number | boolean | string>,
+              ).map(
+                ([key, value]) => ({ key, label: key, value }) as DecodedMetric,
+              );
+          dispatch({
+            type: "set",
+            patch: { metrics, telemetryAt: sample.recordedAt },
+          });
+          dispatch({
+            type: "step",
+            id: "telemetry",
+            status: "ok",
+            note: `${metrics.length} metric(s)`,
+          });
+        }
+
+        // 4. RPC command flow (stops on the first non-zero / failed step)
+        activeStep = "commands";
+        dispatch({ type: "step", id: "commands", status: "active" });
+        let stopped = false;
+        for (let i = 0; i < COMMANDS.length; i++) {
+          if (stopped) {
+            dispatch({ type: "cmd", i, status: "skip" });
+            continue;
+          }
+          if (i > 0 && COMMAND_DELAY_MS > 0) await sleep(COMMAND_DELAY_MS);
+          dispatch({ type: "cmd", i, status: "active" });
+          try {
+            const result = await orbit.commands.exec(device.id, {
+              name: COMMANDS[i].name,
+              args: COMMANDS[i].args,
+              timeoutMs: 15000,
+            });
+            if (result.success) {
+              dispatch({ type: "cmd", i, status: "ok", result });
+            } else {
+              dispatch({ type: "cmd", i, status: "fail", result });
+              stopped = true;
+            }
+          } catch (e) {
+            dispatch({ type: "cmd", i, status: "fail", error: errMsg(e) });
+            stopped = true;
+          }
+        }
+        dispatch({
+          type: "step",
+          id: "commands",
+          status: stopped ? "fail" : "ok",
+        });
+        dispatch({ type: "set", patch: { finished: true } });
+      } catch (e) {
+        if (cancelled) return;
+        // Mark the in-flight step failed so the UI shows where it stopped.
+        dispatch({ type: "set", patch: { fatal: errMsg(e), finished: true } });
+        dispatch({ type: "step", id: activeStep, status: "fail" });
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    if (state.finished) {
+      // Let the final frame paint before tearing down the app.
+      const t = setTimeout(() => exit(), 50);
+      return () => clearTimeout(t);
+    }
+  }, [state.finished, exit]);
+
+  return (
+    <Box flexDirection="column">
+      <Header />
+      <Steps steps={state.steps} />
+      {state.device ? <DevicePanel device={state.device} /> : null}
+      {state.metrics || state.telemetryEmpty ? (
+        <TelemetryPanel
+          metrics={state.metrics}
+          at={state.telemetryAt}
+          empty={state.telemetryEmpty}
+        />
+      ) : null}
+      {state.device ? <CommandPanel commands={state.commands} /> : null}
+      {state.fatal ? (
+        <Box marginTop={1}>
+          <Text color="red">✖ {state.fatal}</Text>
+        </Box>
+      ) : null}
+    </Box>
+  );
+}
+
+render(<App />);

package/examples/device-rpc-flow/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@omirion/example-device-rpc-flow",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Ink TUI demo of the Omirion Orbit SDK: list \u2192 select \u2192 telemetry \u2192 RPC command flow.",
+  "scripts": {
+    "start": "tsx index.tsx",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@omirion/orbit-sdk": "^0.1.1",
+    "ink": "^5.0.1",
+    "ink-spinner": "^5.0.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^18.3.12",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}

package/examples/device-rpc-flow/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["index.tsx"]
+}

package/examples/webhook-listener/README.md

@@ -0,0 +1,41 @@
+# webhook-listener (TypeScript)
+
+The smallest useful Orbit webhook receiver. It starts an HTTP server, verifies every delivery's HMAC signature with the SDK's `parseWebhookEvent`, ACKs it, and prints **what type of event arrived** with a one-line summary:
+
+```
+14:31:07 device.online              device gateway-lab-01
+14:31:22 telemetry.metric_changed   device a3b8d1f2-… · door_open: false → true
+14:31:40 command.result             device a3b8d1f2-… · lock → ok
+14:32:05 deployment.status_changed  device a3b8d1f2-… · deployment 7f9c… · installing → succeeded
+```
+
+It also demonstrates the two receiver-side rules that matter in production: verify against the **exact raw body bytes**, and dedupe on the event `id` (deliveries are at-least-once).
+
+## Run
+
+Copy this folder anywhere, then:
+
+```bash
+pnpm install     # or npm install
+ORBIT_WEBHOOK_SECRET=whsec_your_secret pnpm start   # listens on :3900 (PORT to change)
+```
+
+## Point Orbit at it
+
+Orbit only delivers to **public HTTPS** endpoints, so for local testing expose the port with a tunnel (any of `cloudflared tunnel --url http://localhost:3900`, `ngrok http 3900`, …), then create the subscription, dashboard (**Project → Webhooks**) or SDK:
+
+```ts
+import { OrbitClient } from '@omirion/orbit-sdk'
+
+const orbit = new OrbitClient({ token: process.env.ORBIT_TOKEN! }) // needs api:webhooks:manage
+const sub = await orbit.webhooks.create({
+  projectId: '<PROJECT_UUID>',
+  url: 'https://your-tunnel-host/orbit/webhooks',
+  eventTypes: ['device.online', 'device.offline', 'telemetry.metric_changed', 'command.result'],
+})
+console.log(sub.secret) // whsec_…, shown exactly once, this is your ORBIT_WEBHOOK_SECRET
+```
+
+Then trigger anything on a device in the project, toggle its power, run a command, deploy firmware, and watch the events land.
+
+Delivery not arriving? Check the subscription's delivery log: `orbit.webhooks.deliveries(sub.id)` or the dashboard's Deliveries tab.