{"id":17795,"library":"meshblu-http","title":"Meshblu HTTP API Client","description":"meshblu-http is a Node.js client library for interacting with the Meshblu HTTP API, primarily associated with the Octoblu IoT platform. It provides a programmatic interface for common operations such as device registration, authentication, sending and receiving messages, and managing subscriptions and webhooks. The library is currently at version 10.2.0, with a history of minor and patch releases addressing features like `bearerToken` support and improved subscription management. While the broader Meshblu ecosystem has evolved significantly since 2017 into a microservices architecture (e.g., `meshblu-core-*` components), this client library largely targets the HTTP API of the original Meshblu 1.0 or compatible services. Its API predominantly uses a callback-based pattern, reflecting its origins as a CoffeeScript-driven project. It serves as a high-level abstraction for interacting with IoT devices and services connected to the Meshblu platform via HTTP.","status":"maintenance","version":"10.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/octoblu/node-meshblu-http","tags":["javascript","meshblu","http"],"install":[{"cmd":"npm install meshblu-http","lang":"bash","label":"npm"},{"cmd":"yarn add meshblu-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add meshblu-http","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library is primarily CommonJS-based. Direct ESM imports are not officially supported or documented, and attempts to use them may result in runtime errors.","wrong":"import MeshbluHttp from 'meshblu-http';","symbol":"MeshbluHttp","correct":"const MeshbluHttp = require('meshblu-http');"},{"note":"The constructor accepts an options object for configuration, including `uuid`, `token`, `hostname`, `port`, `protocol`, and `bearerToken`.","symbol":"MeshbluHttp Options","correct":"const meshbluHttp = new MeshbluHttp({ uuid: 'your-uuid', token: 'your-token' });"}],"quickstart":{"code":"const MeshbluHttp = require('meshblu-http');\n\n// Configure Meshblu connection details from environment variables for security\n// It's common to have a dedicated Meshblu service running, or use a cloud instance.\nconst MESHBLU_HOSTNAME = process.env.MESHBLU_HOSTNAME ?? 'localhost';\nconst MESHBLU_PORT = parseInt(process.env.MESHBLU_PORT ?? '3000', 10);\nconst MESHBLU_PROTOCOL = process.env.MESHBLU_PROTOCOL ?? 'http';\n\nconst meshbluHttp = new MeshbluHttp({\n  hostname: MESHBLU_HOSTNAME,\n  port: MESHBLU_PORT,\n  protocol: MESHBLU_PROTOCOL\n});\n\n// Register a new device with Meshblu\nconsole.log(`Attempting to register a new device with Meshblu at ${MESHBLU_PROTOCOL}://${MESHBLU_HOSTNAME}:${MESHBLU_PORT}...`);\nmeshbluHttp.register({}, function(error, device) {\n  if (error) {\n    console.error('Failed to register device:', error.message);\n    // Handle specific error codes or retry logic\n    return;\n  }\n  console.log('Device registered successfully!');\n  console.log('UUID:', device.uuid);\n  console.log('Token:', device.token);\n\n  // Example: Authenticate the newly registered device\n  const authenticatedMeshblu = new MeshbluHttp({\n    uuid: device.uuid,\n    token: device.token,\n    hostname: MESHBLU_HOSTNAME,\n    port: MESHBLU_PORT,\n    protocol: MESHBLU_PROTOCOL\n  });\n\n  authenticatedMeshblu.authenticate(function(authError, authResponse) {\n    if (authError) {\n      console.error('Failed to authenticate device:', authError.message);\n      return;\n    }\n    console.log('Device authenticated successfully:', authResponse.online ? 'Online' : 'Offline');\n    // Now you can use authenticatedMeshblu to send messages, create subscriptions, etc.\n  });\n});","lang":"javascript","description":"This quickstart registers a new device with Meshblu and then authenticates using the newly generated credentials. It demonstrates basic client initialization and a common device lifecycle operation, using environment variables for host configuration."},"warnings":[{"fix":"Consult the official GitHub repository's release notes or commit history for `v10.0.0` and higher to understand specific API changes and adapt your code accordingly. Test thoroughly after upgrading.","message":"The `v10.0.0` major version bump implies breaking changes, though specific API-level changes are not explicitly detailed in the provided release notes, beyond internal build process alterations ('pre-compile coffee before publish'). Users upgrading from `v9.x` should review the GitHub repository for detailed migration guides or changelogs to identify API incompatibilities.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Always use `const MeshbluHttp = require('meshblu-http');` for importing the library. If you are developing an ESM project, you may need to use a CommonJS wrapper or a build tool that handles CJS interoperability.","message":"This library is primarily written with CommonJS (`require()`) exports. While modern Node.js development favors ECMAScript Modules (`import`), `meshblu-http` does not officially support ESM, and attempting to use `import` syntax will likely lead to runtime errors or incorrect module resolution.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For new projects, consider whether `meshblu-http` aligns with the current Meshblu architecture or if direct interaction with `meshblu-core` components or other protocol clients would be more appropriate. Verify the active status and support for the specific Meshblu HTTP API endpoint you are targeting.","message":"The underlying Meshblu 1.0 platform, which `meshblu-http` is designed to interact with, is explicitly marked as 'preserved for historical reference' on its main GitHub repository, with new development focusing on 'meshblu-core' microservices. This suggests that the HTTP API wrapped by this client might not receive active development or new features, potentially limiting its long-term viability or feature set for new Meshblu deployments.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure that if your Meshblu instance requires authentication for registration, you provide valid `uuid` and `token` in the `MeshbluHttp` constructor, or that the Meshblu server is configured to allow anonymous registration for the `/devices` endpoint. For subsequent authenticated calls, always pass the device's `uuid` and `token`.","cause":"Attempting to register or perform other operations with invalid or missing `uuid` and `token` credentials, or connecting to a Meshblu instance that requires authentication for registration.","error":"Failed to register device: Unauthorized"},{"fix":"Ensure you are using the correct CommonJS import statement: `const MeshbluHttp = require('meshblu-http');`. Do not use `import MeshbluHttp from 'meshblu-http';` or similar ESM syntax.","cause":"This error typically occurs when trying to use `MeshbluHttp` as a class with the `new` keyword after incorrectly importing it, especially when mixing CommonJS `require` with expectations of an ESM default export.","error":"TypeError: MeshbluHttp is not a constructor"},{"fix":"Verify that the Meshblu server is running and listening on the specified hostname and port. Check network connectivity, firewall rules, and ensure the `hostname` and `port` values in the `MeshbluHttp` constructor are correct for your Meshblu instance.","cause":"The Meshblu server specified in the `hostname` and `port` options is not running, is inaccessible from the client's network, or the provided hostname/port are incorrect.","error":"Error: connect ECONNREFUSED <hostname>:<port>"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}