fostrom 0.0.12 → 0.0.15

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 HeadOn Labs LLP
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,73 @@
+# 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) => {
+  const {id, name, payload, mailbox_size} = mail
+  console.debug(`Received Mail (${mailbox_size}): ${name} ${id}`)
+
+  // You need to call `mail.ack()` to acknowledge the mail.
+  // Other options are: `mail.reject()` and `mail.requeue()`
+  // Note that if your function throws an error, the SDK will auto-reject the mail.
+  await mail.ack()
+}
+
+async function main() {
+  await fostrom.start()
+
+  // Send a message to Fostrom (payload can be null if schema has no payload)
+  await fostrom.sendMsg("<packet-schema-name>", { /* ...payload */ })
+
+  // Send a datapoint to Fostrom
+  await fostrom.sendDatapoint("<packet-schema-name>", { /* ...payload */ })
+}
+
+main()
+```
+
+> Requires Node.js 22.12+ or Bun 1.1+
+
+You can load the SDK via either syntax:
+
+```js
+import Fostrom from 'fostrom'
+```
+
+```js
+const { default: Fostrom } = require('fostrom')
+```
+
+## A Note on BigInts
+
+Fostrom's Packet Schemas support defining `u64` and `i64` integers. However, JavaScript's `Number` type is limited to `2^53 - 1`. To rectify this issue, we use the `bigint` type and handle JSON encoding and decoding automatically.
+
+Note that there's a caveat here. When Fostrom delivers a message to the SDK containing a `u64` or `i64` number, it will convert to the `Number` type if it is smaller than `2^53 - 1`, and convert to `bigint` if it is larger. This is because the SDK does not know if the field is a `u64` or `i64` type when converting. So for those fields you will need to check whether the type is `bigint` or not.
+
+## 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 starts when `fostrom.start()` is called and handles communication with the Fostrom platform.
+
+By default, the agent remains running in the background for fast reconnections. The SDK also installs a process exit handler; `fostrom.shutdown()` is called automatically on process exit, and if `stopAgentOnExit` is set to true in the config, the agent is stopped as well.
+
+## Logging
+
+By default, the SDK logs connection and handler messages to the console. Set
+`log: false` in the constructor config to silence SDK logs. Levels used:
+
+- `console.info` for successful connection events
+- `console.warn` for reconnection attempts
+- `console.error` for unauthorized/critical errors

package/dl-agent.sh

@@ -4,7 +4,7 @@
 #
 # Usage: ./dl-agent.sh <directory>
 
-VERSION="latest"
+VERSION="v0.0.13"
 
 # CDN URLs in order of preference
 CDN_PRIMARY="https://cdn.fostrom.dev/fostrom-device-agent/$VERSION"
@@ -138,7 +138,11 @@ main() {
             ;;
         Darwin*)
             OS="apple"
-            ARCH="universal"
+            case "$ARCH" in
+                x86_64|amd64)  ARCH="amd64" ;;
+                aarch64|arm64) ARCH="arm64" ;;
+                *)             die "Unsupported architecture: $ARCH" ;;
+            esac
             ;;
         *) die "Unsupported OS: $OS" ;;
     esac

package/index.js

@@ -1,6 +1,8 @@
 import { execSync } from "child_process"
 import { fileURLToPath } from "url"
 import path from "path"
+import http from "node:http"
+import { stringifyJSON, parseJSON } from "./json.js"
 
 function agent_path() {
   const __dirname = path.dirname(fileURLToPath(import.meta.url))
@@ -9,10 +11,8 @@ function agent_path() {
 
 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
+    super(`${atom}: ${msg}`)
+    this.error = atom
   }
 }
 
@@ -39,28 +39,39 @@ export class Mail {
 export default class Fostrom {
   #log = true
   #creds = {}
+  #sseBuffer = ""
+  #sseReq = null
+  #reconnectTimer = null
+  #stopped = true
+  #installedExitHandler = false
+  #stopAgentOnExit = false
+  #runtimeEnv = null
+
+  static #SOCK = "/tmp/fostrom/agent.sock"
 
   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")
+    if (this.#log) {
+      console.warn(`[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")
+    if (this.#log) console.info("[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...`)
+      const after_s = Math.floor((after || 0) / 1000);
+      console.error(`[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...`)
+      const after_s = Math.floor((after || 0) / 1000);
+      console.warn(`[Fostrom] Failed to connect: ${reason}. Reconnecting in ${after_s} seconds...`)
     }
   }
 
@@ -72,77 +83,85 @@ export default class Fostrom {
     this.#creds.device_id = config.device_id
     this.#creds.device_secret = config.device_secret
     if (config.log == false) this.#log = false
+    this.#stopAgentOnExit = Boolean(config.stopAgentOnExit || false)
+    this.#runtimeEnv = config.env || config.runtimeEnv || process.env.NODE_ENV || null
+  }
+
+  #installExitHandler() {
+    if (this.#installedExitHandler) return
+    process.on('exit', () => {
+      try { this.shutdown() } catch { }
+    })
+    this.#installedExitHandler = true
   }
 
   #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
-    ]
+    const env = {
+      ...process.env,
+      FOSTROM_FLEET_ID: fleet_id,
+      FOSTROM_DEVICE_ID: device_id,
+      FOSTROM_DEVICE_SECRET: device_secret,
+    }
+    if (this.#runtimeEnv && String(this.#runtimeEnv).trim() !== "") {
+      env["FOSTROM_RUNTIME_ENV"] = String(this.#runtimeEnv)
+    }
 
-    if (process.env.FOSTROM_AGENT_MODE === 'dev') args.push("--dev")
+    const args = ["start"]
 
     try {
-      const output = execSync(`${agent_path()} ${args.join(" ")}`, { encoding: "utf8" })
-
-      if (output.trim() == "started") {
-        return
-      }
+      const output = execSync(`${agent_path()} ${args.join(" ")}`, { encoding: "utf8", env })
+      const out = output.trim()
+      if (out.startsWith("started:")) return
+      if (out.startsWith("already_started:")) return
+      return
     } catch (error) {
-      let [err, msg] = error.stdout.trim().split(":", 2)
-      throw new FostromError(err, msg)
+      const out = (error.stdout || "").toString().trim()
+      if (out) {
+        const [atom, rest] = out.split(":", 2)
+        throw new FostromError(atom || "failed", (rest || "Failed to start Device Agent").trim())
+      }
+      throw new FostromError("failed", "Failed to start Device Agent")
     }
   }
 
-  async #req(path = "/", method = "GET", payload = null, additional_options = {}) {
-    if (method != "GET" && method != "PUT" && method != "POST" && method != "DELETE") {
+  async #req(path = "/", method = "GET", payload = null) {
+    if (!["GET", "PUT", "POST", "DELETE", "HEAD"].includes(method)) {
       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 { fleet_id, device_id } = this.#creds
+    const headers = {
+      "X-Fleet-ID": fleet_id,
+      "X-Device-ID": device_id,
     }
 
-    const options = {
-      ...base_options,
-      ...additional_options
+    let bodyString = null
+    if (method === "POST" || method === "PUT") {
+      headers["Content-Type"] = "application/json; charset=utf-8"
+      headers["Accept"] = "application/json"
+      if (payload === undefined || payload === null) {
+        bodyString = "null"
+      } else {
+        bodyString = stringifyJSON(payload)
+      }
+      headers["Content-Length"] = Buffer.byteLength(bodyString, 'utf8')
+    } else {
+      headers["Accept"] = "application/json"
     }
 
-    let resp
-    let body
+    const res = await Fostrom.#unix_request({ path, method, headers, body: bodyString })
 
-    try {
-      resp = await fetch(`http://localhost:8585${path}`, options)
-    } catch (e) {
-      throw new FostromError("req_failed", "Communicating with the device agent is failing.")
-    }
-
-    try {
-      body = await resp.json()
-    }
-    catch (e) {
-      console.error(e)
-      throw new FostromError("req_failed", "Communicating with the device agent is failing.")
+    if (res.statusCode < 200 || res.statusCode >= 300) {
+      if (res.bodyJson && res.bodyJson.error) {
+        const msg = res.bodyJson.msg || "Request failed"
+        throw new FostromError(res.bodyJson.error, msg)
+      }
+      throw new FostromError("request_failed", "Communicating with the Device Agent failed")
     }
 
-    if (body.error && body.msg) {
-      throw new FostromError(body.error, body.msg)
-    } else {
-      return body
-    }
+    return res
   }
 
   static stopAgent() {
@@ -153,53 +172,68 @@ export default class Fostrom {
     }
   }
 
-  async connect() {
+  async start() {
+    if (!this.#stopped) return
+    this.#installExitHandler()
     this.#start_agent()
-    const resp = await this.#req()
-    const status = resp.connect_status
+    this.#stopped = false
+    this.#open_event_stream()
+  }
 
-    if (!status.connected) {
-      console.error(new FostromError(status.error, status.msg))
-    } else {
-      this.#open_event_stream()
-      return true
-    }
+  async shutdown(stopAgent = null) {
+    this.#stopped = true
+    try {
+      if (this.#reconnectTimer) {
+        clearTimeout(this.#reconnectTimer)
+        this.#reconnectTimer = null
+      }
+      if (this.#sseReq && typeof this.#sseReq.destroy === 'function') {
+        this.#sseReq.destroy()
+      }
+    } catch { }
+    this.#sseReq = null
+    const doStop = (stopAgent === null) ? this.#stopAgentOnExit : Boolean(stopAgent)
+    if (doStop) Fostrom.stopAgent()
   }
 
   async sendDatapoint(name, payload) {
-    return await this.#req(`/pulse/datapoint/${name}`, "POST", payload)
+    Fostrom.#validate_pulse_name(name)
+    const res = await this.#req(`/pulse/datapoint/${name}`, "POST", payload)
+    return
   }
 
   async sendMsg(name, payload) {
-    return await this.#req(`/pulse/msg/${name}`, "POST", payload)
+    Fostrom.#validate_pulse_name(name)
+    const res = await this.#req(`/pulse/msg/${name}`, "POST", payload)
+    return
   }
 
   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,
-      }
+    const res = await this.#req(`/mailbox/next`, "HEAD")
+    const h = res.headers
+    const empty = Fostrom.#parse_bool(h["x-mailbox-empty"]) === true
+    if (empty) {
+      return { mailbox_size: 0, next_mail_id: null, next_mail_name: null }
+    }
+    return {
+      mailbox_size: Number(h["x-mailbox-size"]) || 0,
+      next_mail_id: Number(h["x-mail-id"]) || null,
+      next_mail_name: h["x-mail-name"] || null,
     }
   }
 
   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)
+    const res = await this.#req(`/mailbox/next`, "GET")
+    const h = res.headers
+    const empty = Fostrom.#parse_bool(h["x-mailbox-empty"]) === true
+    if (empty) return null
+
+    const mailbox_size = Number(h["x-mailbox-size"]) || 0
+    const id = Number(h["x-mail-id"]) || null
+    const name = h["x-mail-name"] || null
+    const hasPayload = Fostrom.#parse_bool(h["x-mail-has-payload"]) === true
+    const payload = hasPayload ? (res.bodyJson ?? null) : null
+    return new Mail(this, id, name, payload, mailbox_size)
   }
 
   async __mail_op(op, mail_id) {
@@ -207,72 +241,185 @@ export default class Fostrom {
       throw new Error("Invalid Mailbox Operation")
     }
 
-    return await this.#req(`/mailbox/${op}/${mail_id}`, "PUT")
+    const res = await this.#req(`/mailbox/${op}/${mail_id}`, "PUT")
+    const more = Fostrom.#parse_bool(res.headers["x-mail-available"]) === true
+    if (more) {
+      const mail = await this.nextMail()
+      if (mail) await this.#deliverMail(mail)
+    }
+    return true
   }
 
   async #event_handler(event_object) {
-    const { event, _timestamp } = event_object
+    const { event } = 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
+      case 'connected':
+        this.connected()
+        break
+      case 'disconnected': {
+        if (data && typeof data.error === 'string') {
+          const err = data.error
+          const after = Number(data.reconnecting_in_ms || 0)
+          const reason = (typeof err === 'string') ? err.split(':', 2)[0].trim() : ''
+          if (reason === "unauthorized") this.unauthorized(err, after)
+          else this.reconnecting(err, after)
+        }
+        break
+      }
+      case 'new_mail': {
+        const mail = await this.nextMail()
+        if (mail) await this.#deliverMail(mail)
+        break
+      }
+      default:
+        break
     }
   }
 
-  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()
+    if (this.#stopped) return
+    if (this.#sseReq) return
+    const { fleet_id, device_id } = this.#creds
+    const options = {
+      socketPath: Fostrom.#SOCK,
+      path: "/events",
+      method: "GET",
+      headers: {
+        "Accept": "text/event-stream",
+        "X-Fleet-ID": fleet_id,
+        "X-Device-ID": device_id,
+        "Connection": "keep-alive",
+      }
+    }
 
-    const resp = await fetch(`http://localhost:8585/events`, {
-      headers: { 'Accept': 'text/event-stream' }
+    const req = http.request(options, (res) => {
+      res.setEncoding('utf8')
+      res.on('data', (chunk) => {
+        this.#sseBuffer = Fostrom.#parse_events(this.#sseBuffer, chunk, this.#event_handler.bind(this))
+      })
+      res.on('error', () => {
+        this.#sseReq = null
+        if (!this.#stopped) {
+          this.#reconnectTimer = setTimeout(() => this.#open_event_stream(), 500)
+        }
+      })
+      res.on('aborted', () => {
+        this.#sseReq = null
+        if (!this.#stopped) {
+          this.#reconnectTimer = setTimeout(() => this.#open_event_stream(), 500)
+        }
+      })
+      res.on('end', () => {
+        this.#sseReq = null
+        if (!this.#stopped) {
+          this.#reconnectTimer = setTimeout(() => this.#open_event_stream(), 250)
+        }
+      })
     })
 
-    const reader = resp.body.getReader()
-    let buffer = ''
+    req.on('error', (_err) => {
+      this.#sseReq = null
+      if (!this.#stopped) {
+        this.#reconnectTimer = setTimeout(() => this.#open_event_stream(), 500)
+      }
+    })
 
-    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))
-    }
+    req.end()
+    this.#sseReq = req
+  }
+
+  // --- Static helpers ---
+  static #parse_bool(v) {
+    if (typeof v !== 'string') return false
+    const s = v.toLowerCase()
+    return s === 'true' || s === '1' || s === 'yes'
   }
-}
 
-function parse_events(buffer, chunk, event_handler) {
-  buffer += chunk
-  const lines = buffer.split('\n')
+  static #validate_pulse_name(name) {
+    if (typeof name !== 'string') name = String(name)
+    if (name.length === 0 || name.length > 255) {
+      throw new FostromError('invalid_name', 'Pulse name must be 1..255 characters')
+    }
+    if (!/^[A-Za-z0-9_-]+$/.test(name)) {
+      throw new FostromError('invalid_name', 'Pulse name may contain only A-Za-z0-9_-')
+    }
+  }
 
-  // Keep the last incomplete line in buffer
-  buffer = lines.pop() || ''
+  static async #unix_request({ path, method, headers = {}, body = null }) {
+    return new Promise((resolve, reject) => {
+      const opts = {
+        socketPath: Fostrom.#SOCK,
+        path,
+        method,
+        headers,
+      }
 
-  let event = {}
+      const req = http.request(opts, (res) => {
+        const chunks = []
+        res.on('data', (chunk) => chunks.push(Buffer.from(chunk)))
+        res.on('end', () => {
+          const bodyBuf = Buffer.concat(chunks)
+          const bodyText = bodyBuf.toString('utf8')
+          const ct = res.headers['content-type'] || ''
+          let bodyJson = null
+          if (ct.toLowerCase().includes('application/json') && bodyText.length > 0) {
+            try { bodyJson = parseJSON(bodyText) } catch { bodyJson = null }
+          }
+          resolve({
+            statusCode: res.statusCode || 0,
+            headers: res.headers || {},
+            bodyText,
+            bodyJson,
+          })
+        })
+      })
+
+      req.on('error', (err) => {
+        reject(new FostromError('req_failed', `Communicating with the Device Agent failed: ${err.message}`))
+      })
+
+      if (body !== null && body !== undefined && method !== 'HEAD') {
+        req.write(body)
+      }
+      req.end()
+    })
+  }
 
-  for (const line of lines) {
-    // Empty line indicates end of event
-    if (line === '') {
-      if (event.data && event.data != '') {
-        event.data = JSON.parse(event.data)
+  static #parse_events(buffer, chunk, event_handler) {
+    buffer += chunk
+    const lines = buffer.split('\n')
+    buffer = lines.pop() || ''
+
+    let event = {}
+    for (const raw of lines) {
+      const line = raw.replace(/\r$/, '')
+      if (line === '') {
+        if (event.data && event.data !== '') {
+          try { event.data = parseJSON(event.data) } catch { /* ignore */ }
+        }
+        if (event.event) 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: ')) {
+        const ts = parseInt(line.slice(4))
+        if (!Number.isNaN(ts)) event.timestamp = new Date(ts)
       }
+    }
 
-      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))
+    return buffer
+  }
+
+  async #deliverMail(mail) {
+    try {
+      await this.onMail(mail)
+    } catch (e) {
+      if (this.#log) console.error(`[Fostrom] onMail handler threw; auto-rejecting mail ${mail.id} (${mail.name})`, e)
+      try { await mail.reject() } catch { }
     }
   }
 }

package/json.js

@@ -0,0 +1,31 @@
+// JSON functions to correctly handle BigInts
+
+function stringifyJSON(value) {
+  if (typeof JSON.rawJSON !== 'function') {
+    throw new Error('JSON.rawJSON not available; requires Node.js 22+/Bun 1.1+')
+  }
+  return JSON.stringify(value, (_key, v) => {
+    if (typeof v === 'bigint') {
+      return JSON.rawJSON(v.toString())
+    }
+    return v
+  })
+}
+
+function parseJSON(text) {
+  if (typeof JSON.rawJSON !== 'function') {
+    throw new Error('JSON.rawJSON not available; requires Node.js 22+/Bun 1.1+')
+  }
+  return JSON.parse(text, (_key, v, ctx) => {
+    if (typeof v === 'number' && Number.isInteger(v) && !Number.isSafeInteger(v) && ctx?.source) {
+      try {
+        return BigInt(ctx.source)
+      } catch {
+        return v
+      }
+    }
+    return v
+  })
+}
+
+export { stringifyJSON, parseJSON }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fostrom",
-  "version": "0.0.12",
+  "version": "0.0.15",
   "description": "Fostrom's Official Device SDK for JS. Fostrom (https://fostrom.io) is an IoT Cloud Platform.",
   "keywords": [
     "fostrom",
@@ -18,17 +18,31 @@
     "raspberry"
   ],
   "homepage": "https://docs.fostrom.io/sdk/js",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "author": "Fostrom <support@fostrom.io> (https://fostrom.io)",
   "files": [
     "index.js",
+    "json.js",
     "dl-agent.sh",
-    "readme.md"
+    "README.md",
+    "LICENSE"
   ],
   "main": "index.js",
   "type": "module",
+  "exports": {
+    ".": {
+      "module-sync": "./index.js",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json",
+    "./dl-agent.sh": "./dl-agent.sh"
+  },
   "scripts": {
     "postinstall": "sh dl-agent.sh .agent"
   },
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "dependencies": {}
 }

package/readme.md

@@ -1,44 +0,0 @@
-# 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) => {
-  const {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()
-```
-
-Please note, to use `import Fostrom from 'fostrom';` you'll need to set `"type": "module"` in `package.json`.
-
-## 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.