JavaScript SDK

npm package

The Fostrom Device SDK for JavaScript is built to work 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.

Installation

You can install the package using npm:

npm install fostrom

npm install fostrom

The npm package runs a post-install script download the Fostrom Device Agent. If you aren't using npm, ensure that the alternate package manager executes the post-install script.

Fostrom Device SDK for JavaScript requires Node.js 22.12+ or Bun 1.2+

Usage

import Fostrom from 'fostrom';
// or for importing via CommonJS, use:
//     const { default: Fostrom } = require('fostrom')

const fostrom = new Fostrom({
  fleet_id: "<fleet-id>",
  device_id: "<device-id>",
  device_secret: "<device-secret>",
})

// Setup the onMail 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.
  // You can also call: `mail.reject()` or `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 datapoint to Fostrom
  await fostrom.sendDatapoint("<packet-schema-name>", { ...payload })

  // Send a message to Fostrom (payload can be null)
  await fostrom.sendMsg("<packet-schema-name>", { ...payload })
}

main()

import Fostrom from 'fostrom';
// or for importing via CommonJS, use:
//     const { default: Fostrom } = require('fostrom')

const fostrom = new Fostrom({
  fleet_id: "<fleet-id>",
  device_id: "<device-id>",
  device_secret: "<device-secret>",
})

// Setup the onMail 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.
  // You can also call: `mail.reject()` or `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 datapoint to Fostrom
  await fostrom.sendDatapoint("<packet-schema-name>", { ...payload })

  // Send a message to Fostrom (payload can be null)
  await fostrom.sendMsg("<packet-schema-name>", { ...payload })
}

main()

If you prefer to use CommonJS instead of the import module syntax, you can require the module like this:

 const { default: Fostrom } = require('fostrom')

 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, as operating on Numbers and BigInts differs in JavaScript.

Logging

By default, the SDK logs connection and handler messages to the console.

Set log: false in the config to silence SDK logs. Levels used:

• console.info for successful connection events
• console.warn for reconnection attempts
• console.error for unauthorized/critical errors

About the Device Agent

The Fostrom Device SDK downloads and runs the Fostrom Device Agent in the background. The Device Agent is downloaded when the package is installed through npm using a post-install script. 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 quick reconnecting. The SDK also installs a process exit handler; fostrom.shutdown() is called automatically on process exit. If you want to stop the Device Agent, you can call fostrom.shutdown(true) or set stopAgentOnExit: true in the config.

SDK API Reference

Fostrom {
  // --- Functions ---
  async start()
  async sendDatapoint(name, payload)
  async sendMsg(name, payload)

  // Usually, there's no need to use the following
  // functions, as mail will be delivered to the
  // handler you define automatically.
  async mailboxStatus()
    // returns {mailbox_size, next_mail_id, next_mail_name}
  async nextMail()
    // returns FostromMail{}

  // --- Replacable Callbacks ---
  connected()
  unauthorized(reason, reconnecting_in_ms)
  reconnecting(reason, reconnecting_in_ms)
  async onMail(mail = FostromMail{})
}

FostromMail {
  // --- Data ---
  id: string
  name: string
  payload: object
  mailbox_size: integer

  // --- Functions ---
  async ack()
  async reject()
  async requeue()
}

Fostrom {
  // --- Functions ---
  async start()
  async sendDatapoint(name, payload)
  async sendMsg(name, payload)

  // Usually, there's no need to use the following
  // functions, as mail will be delivered to the
  // handler you define automatically.
  async mailboxStatus()
    // returns {mailbox_size, next_mail_id, next_mail_name}
  async nextMail()
    // returns FostromMail{}

  // --- Replacable Callbacks ---
  connected()
  unauthorized(reason, reconnecting_in_ms)
  reconnecting(reason, reconnecting_in_ms)
  async onMail(mail = FostromMail{})
}

FostromMail {
  // --- Data ---
  id: string
  name: string
  payload: object
  mailbox_size: integer

  // --- Functions ---
  async ack()
  async reject()
  async requeue()
}