fostrom 0.0.5 → 0.0.7

package/index.js

@@ -0,0 +1,289 @@
+import { execSync } from "child_process"
+import { fileURLToPath } from "url"
+import path from "path"
+
+function agent_path() {
+  const __dirname = path.dirname(fileURLToPath(import.meta.url))
+  return path.join(__dirname, ".agent", "fostrom-device-agent")
+}
+
+class FostromError extends Error {
+  constructor(atom, msg) {
+    const formattedMessage = `\x1b[31m\x1b[1mFostrom Error\x1b[0m \x1b[34m[${atom}]\x1b[0m ${msg}`
+    super(formattedMessage)
+    this.name = ""
+    this.stack = null
+  }
+}
+
+export class Mail {
+  id
+  name
+  payload = undefined
+  mailbox_size
+  #instance
+
+  constructor(fostrom_instance, id, name, payload, mailbox_size) {
+    this.#instance = fostrom_instance
+    this.id = id
+    this.name = name
+    this.payload = payload
+    this.mailbox_size = mailbox_size
+  }
+
+  async ack() { return await this.#instance.__mail_op("ack", this.id) }
+  async reject() { return await this.#instance.__mail_op("reject", this.id) }
+  async requeue() { return await this.#instance.__mail_op("requeue", this.id) }
+}
+
+export default class Fostrom {
+  #log = true
+  #creds = {}
+
+  onMail = async mail => {
+    console.log(`[Fostrom] Received Mail (Mailbox Size: ${mail.mailbox_size}): ${mail.name} -> ID ${mail.id}`)
+    console.warn("              Auto-Acknowledging Mail. Define Mail Handler to handle incoming mail.\n              `fostrom.on_mail = async (mail) => { ...; await mail.ack(); }`\n")
+    await mail.ack()
+  }
+
+  connected = () => {
+    if (this.#log) console.log("[Fostrom] Connected")
+  }
+
+  unauthorized = (reason, after) => {
+    if (this.#log) {
+      const after_s = Math.floor(after / 1000);
+      console.log(`[Fostrom] Unauthorized: ${reason}. Reconnecting in ${after_s} seconds...`)
+    }
+  }
+
+  reconnecting = (reason, after) => {
+    if (this.#log) {
+      const after_s = Math.floor(after / 1000);
+      console.log(`[Fostrom] Failed to connect: ${reason}. Reconnecting in ${after_s} seconds...`)
+    }
+  }
+
+  constructor(config = {}) {
+    if (!config.fleet_id) throw "[Fostrom] Fleet ID required."
+    if (!config.device_id) throw "[Fostrom] Device ID required."
+    if (!config.device_secret) throw "[Fostrom] Device Secret required."
+    this.#creds.fleet_id = config.fleet_id
+    this.#creds.device_id = config.device_id
+    this.#creds.device_secret = config.device_secret
+    if (config.log == false) this.#log = false
+  }
+
+  #start_agent() {
+    const { fleet_id, device_id, device_secret } = this.#creds
+
+    let args = [
+      "start",
+      "--fleet-id", fleet_id,
+      "--device-id", device_id,
+      "--device-secret", device_secret
+    ]
+
+    if (process.env.FOSTROM_AGENT_MODE === 'dev') args.push("--dev")
+
+    try {
+      const output = execSync(`${agent_path()} ${args.join(" ")}`, { encoding: "utf8" })
+
+      if (output.trim() == "starting") {
+        execSync(`sleep 0.25`)
+        return
+      }
+    } catch (error) {
+      let [err, msg] = error.stdout.trim().split(":", 2)
+      throw new FostromError(err, msg)
+    }
+  }
+
+  async #req(path = "/", method = "GET", payload = null, additional_options = {}) {
+    if (method != "GET" && method != "PUT" && method != "POST" && method != "DELETE") {
+      throw new Error(`Unsupported ${method} Request for path ${path}`)
+    }
+
+    const headers = new Headers()
+    headers.set("Content-Type", "application/json")
+    headers.set("Accept", "application/json")
+
+    const base_options = {
+      method,
+      headers,
+    }
+
+    if ((method == "POST" || method == "PUT") && payload) {
+      base_options.body = JSON.stringify(payload)
+    }
+
+    const options = {
+      ...base_options,
+      ...additional_options
+    }
+
+    let resp
+    let body
+
+    try {
+      resp = await fetch(`http://localhost:8585${path}`, options)
+    } catch (e) {
+      throw new FostromError("req_failed", "Communicating with the device agent is failing.")
+    }
+
+    const fleet_id = resp.headers.get('x-fleet-id')
+    const device_id = resp.headers.get('x-device-id')
+
+    if (this.#creds.fleet_id != fleet_id || this.#creds.device_id != device_id) {
+      console.warn("Restarting Agent due to credential mismatch.")
+      this.stop_agent()
+      this.#start_agent()
+      return await this.#req(path, options)
+    } else {
+      try {
+        body = await resp.json()
+      }
+      catch (e) {
+        console.error(e)
+        throw new FostromError("req_failed", "Communicating with the device agent is failing.")
+      }
+    }
+
+    if (body.error && body.msg) {
+      throw new FostromError(body.error, body.msg)
+    } else {
+      return body
+    }
+  }
+
+  static stopAgent() {
+    try {
+      execSync(`${agent_path()} stop`, { encoding: "utf8" })
+    } catch (e) {
+      console.error("[Fostrom] Failed to stop the Fostrom Device Agent")
+    }
+  }
+
+  async connect() {
+    this.#start_agent()
+    const resp = await this.#req()
+    const status = resp.connect_status
+
+    if (!status.connected) {
+      console.error(new FostromError(status.error, status.msg))
+    } else {
+      this.#open_event_stream()
+      return true
+    }
+  }
+
+  async sendDatapoint(name, payload) {
+    return await this.#req(`/pulse/datapoint/${name}`, "POST", payload)
+  }
+
+  async sendMsg(name, payload) {
+    return await this.#req(`/pulse/msg/${name}`, "POST", payload)
+  }
+
+  async mailboxStatus() {
+    const resp = await this.#req(`/mailbox/status`)
+
+    if (resp.mailbox_empty == true) {
+      return {
+        mailbox_size: 0,
+        next_mail_id: null,
+        next_mail_name: null
+      }
+    } else {
+      return {
+        mailbox_size: resp.mailbox_size,
+        next_mail_id: resp.pulse_id,
+        next_mail_name: resp.name,
+      }
+    }
+  }
+
+  async nextMail() {
+    const resp = await this.#req(`/mailbox/next`)
+
+    if (resp.mailbox_empty == true) {
+      return null
+    }
+
+    return new Mail(this, resp.pulse_id, resp.name, resp.payload, resp.mailbox_size)
+  }
+
+  async __mail_op(op, mail_id) {
+    if (op != "ack" && op != "reject" && op != "requeue") {
+      throw new Error("Invalid Mailbox Operation")
+    }
+
+    return await this.#req(`/mailbox/${op}/${mail_id}`, "PUT")
+  }
+
+  async #event_handler(event_object) {
+    const { event, _timestamp } = event_object
+    const data = event_object.data
+
+    switch (event) {
+      case 'connected': this.connected(); break;
+      case 'unauthorized': this.unauthorized(data.reason, data.reconnecting_in); break;
+      case 'connect_failed': this.reconnecting(data.reason, data.reconnecting_in); break;
+      case 'next_mail': this.#dispatch_next_mail(data); break;
+      default: null
+    }
+  }
+
+  async #dispatch_next_mail(data) {
+    const mail = new Mail(this, data.pulse_id, data.name, data.payload, data.mailbox_size)
+    this.onMail(mail)
+  }
+
+  async #open_event_stream() {
+    const td = new TextDecoder()
+
+    const resp = await fetch(`http://localhost:8585/events`, {
+      headers: { 'Accept': 'text/event-stream' }
+    })
+
+    const reader = resp.body.getReader()
+    let buffer = ''
+
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) { this.connect() }
+      const decoded = td.decode(value)
+      parse_events(buffer, decoded, this.#event_handler.bind(this))
+    }
+  }
+}
+
+function parse_events(buffer, chunk, event_handler) {
+  buffer += chunk
+  const lines = buffer.split('\n')
+
+  // Keep the last incomplete line in buffer
+  buffer = lines.pop() || ''
+
+  let event = {}
+
+  for (const line of lines) {
+    // Empty line indicates end of event
+    if (line === '') {
+      if (event.data && event.data != '') {
+        event.data = JSON.parse(event.data)
+      }
+
+      event_handler(event)
+      event = {}
+    } else if (line.startsWith('data: ')) {
+      event.data = (event.data || '') + line.slice(6)
+    } else if (line.startsWith('event: ')) {
+      event.event = line.slice(7)
+    } else if (line.startsWith('id: ')) {
+      event.timestamp = new Date(parseInt(line.slice(4)))
+    } else if (line.startsWith('retry: ')) {
+      event.retry = parseInt(line.slice(7))
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fostrom",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Fostrom's Official Device SDK for JS. Fostrom (https://fostrom.io) is an IoT Cloud Platform.",
   "keywords": [
     "fostrom",
@@ -22,8 +22,11 @@
   "author": "Fostrom <support@fostrom.io> (https://fostrom.io)",
   "files": [
     "index.js",
-    "dl-agent.sh"
+    "dl-agent.sh",
+    "readme.md"
   ],
+  "main": "index.js",
+  "type": "module",
   "scripts": {
     "postinstall": "sh dl-agent.sh .agent"
   },

package/readme.md

@@ -0,0 +1,42 @@
+# Fostrom Device SDK
+
+[Fostrom](https://fostrom.io) is an IoT Cloud Platform built for developers. Monitor and control your fleet of devices, from microcontrollers to industrial IoT. Designed to be simple, secure, and fast. Experience first-class tooling with Device SDKs, type-safe schemas, programmable actions, and more.
+
+The Fostrom Device SDK for JavaScript works in Node.js and Bun, on Linux and macOS, and helps you quickly integrate, start monitoring, and controlling your IoT devices in just a few lines of code.
+
+## Example
+
+```js
+import Fostrom from 'fostrom';
+
+const fostrom = new Fostrom({
+  fleet_id: "<fleet-id>",
+  device_id: "<device-id>",
+  device_secret: "<device-secret>",
+})
+
+// Setup the on_mail handler, to process incoming mail.
+fostrom.onMail = async (mail) => {
+  {id, name, payload, mailbox_size} = mail
+  console.debug(`Received Mail (${mailbox_size}): ${name} ${id}`)
+  await mail.ack()
+}
+
+async function main() {
+  await fostrom.connect()
+
+  // To send a message to Fostrom
+  await fostrom.sendMsg("<packet-schema-name>", { ...payload })
+
+  // To send a datapoint to Fostrom
+  await fostrom.sendDatapoint("<packet-schema-name>", { ...payload })
+}
+
+main()
+```
+
+## A Note on the Device Agent
+
+The Fostrom Device SDK downloads and runs the Fostrom Device Agent in the background. The Agent is downloaded when the package is installed through `npm`. The Device Agent is started when `fostrom.connect()` is called, and it remains running in the background forever.
+
+We recommend you allow the Device Agent to run continously, even if your program has exited or crashed, so that when your program is automatically restarted by a process manager, the reconnection to Fostrom is nearly instant. However, if you wish to stop the Device Agent, you can call `Fostrom.stopAgent()` in your code before terminating your program.