@omirion/orbit-sdk 0.1.1 → 0.3.0

package/examples/webhook-listener/index.ts

@@ -0,0 +1,110 @@
+/**
+ * webhook-listener, the smallest useful Orbit webhook receiver.
+ *
+ * Starts an HTTP server, verifies the HMAC signature of every delivery with
+ * `parseWebhookEvent`, ACKs it, and prints what arrived: the event type plus
+ * a one-line, type-specific summary.
+ *
+ * Run with:  ORBIT_WEBHOOK_SECRET=whsec_… pnpm start
+ */
+
+import { createServer } from 'node:http'
+import { parseWebhookEvent, type OrbitWebhookEvent } from '@omirion/orbit-sdk'
+
+const secret = process.env.ORBIT_WEBHOOK_SECRET
+if (!secret) {
+  console.error('Set ORBIT_WEBHOOK_SECRET to your subscription signing secret (whsec_…).')
+  process.exit(1)
+}
+
+const port = Number(process.env.PORT ?? 3900)
+
+// ANSI helpers, enough color to scan the feed, no dependency.
+const dim = (s: string) => `\x1b[2m${s}\x1b[0m`
+const bold = (s: string) => `\x1b[1m${s}\x1b[0m`
+const green = (s: string) => `\x1b[32m${s}\x1b[0m`
+const red = (s: string) => `\x1b[31m${s}\x1b[0m`
+const cyan = (s: string) => `\x1b[36m${s}\x1b[0m`
+const yellow = (s: string) => `\x1b[33m${s}\x1b[0m`
+
+const TYPE_COLOR: Record<string, (s: string) => string> = {
+  'device.online': green,
+  'device.offline': red,
+  'telemetry.metric_changed': cyan,
+  'command.result': yellow,
+  'deployment.status_changed': cyan,
+  'admission.requested': yellow,
+}
+
+/** One line that tells you what actually happened, per event type. */
+function summarize(event: OrbitWebhookEvent): string {
+  const d = event.data as Record<string, any>
+  switch (event.type) {
+    case 'device.online':
+    case 'device.offline':
+      return `device ${d.deviceName ?? d.deviceId}`
+    case 'telemetry.metric_changed': {
+      const changes = Object.entries(d.changes ?? {})
+        .map(([key, c]: [string, any]) => `${key}: ${c.previous} → ${c.current}`)
+        .join(', ')
+      return `device ${d.deviceId} · ${changes}`
+    }
+    case 'command.result':
+      return `device ${d.deviceId} · ${d.command?.name} → ${d.success ? 'ok' : `failed (exit ${d.exitCode})`}`
+    case 'deployment.status_changed':
+      return `device ${d.deviceId} · deployment ${d.deploymentId} · ${d.previousStatus ?? '∅'} → ${d.status}`
+    case 'admission.requested':
+      return `host ${d.hostname ?? 'unknown'} · fingerprint ${d.fingerprint}`
+    default:
+      return JSON.stringify(d)
+  }
+}
+
+const seen = new Set<string>() // event-id dedup, deliveries are at-least-once
+
+const server = createServer((req, res) => {
+  if (req.method !== 'POST') {
+    res.writeHead(405).end()
+    return
+  }
+
+  const chunks: Buffer[] = []
+  req.on('data', (chunk) => chunks.push(chunk))
+  req.on('end', async () => {
+    // parseWebhookEvent needs the EXACT bytes that were signed, never
+    // re-serialize parsed JSON.
+    const rawBody = Buffer.concat(chunks).toString('utf8')
+
+    const event = await parseWebhookEvent({
+      secret,
+      rawBody,
+      signature: String(req.headers['x-orbit-signature'] ?? ''),
+      timestamp: String(req.headers['x-orbit-timestamp'] ?? ''),
+    })
+
+    if (!event) {
+      console.log(red('✗ rejected delivery (bad signature or outside the replay window)'))
+      res.writeHead(401).end()
+      return
+    }
+
+    // ACK fast (any 2xx within 10 s), process after responding.
+    res.writeHead(204).end()
+
+    if (seen.has(event.id)) {
+      console.log(dim(`↻ duplicate delivery of ${event.id}, ignored`))
+      return
+    }
+    seen.add(event.id)
+
+    const paint = TYPE_COLOR[event.type] ?? ((s: string) => s)
+    console.log(
+      `${dim(new Date(event.createdAt).toLocaleTimeString())} ${paint(bold(event.type.padEnd(27)))} ${summarize(event)}`
+    )
+  })
+})
+
+server.listen(port, () => {
+  console.log(`Listening for Orbit webhooks on ${bold(`http://localhost:${port}`)}`)
+  console.log(dim('Waiting for events, toggle a device, run a command, or deploy firmware…\n'))
+})

package/examples/webhook-listener/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@omirion/example-webhook-listener",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Minimal Orbit webhook receiver: verify each delivery's signature and print the event type.",
+  "scripts": {
+    "start": "tsx index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@omirion/orbit-sdk": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}

package/examples/webhook-listener/tsconfig.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omirion/orbit-sdk",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Official TypeScript SDK for the Omirion Orbit public API (/api/v1).",
   "license": "MIT",
   "type": "module",
@@ -16,6 +16,7 @@
   },
   "files": [
     "dist",
+    "examples",
     "README.md",
     "LICENSE"
   ],