Carroted Data SDK for Node.js

A modern, production-ready SDK for sending telemetry data to the Carroted Data service from any Node.js or TypeScript application.

This library simplifies sending data by handling HTTP communication, JSON serialization, and robust error handling with automatic retries.

Repo Link: https://github.com/harborscale/harbor-sdk-js

Features

• ✅ TypeScript First: Written in TypeScript for strong typing and excellent editor autocompletion.
• 📦 Batching Support: Efficiently send multiple readings in a single request.
• ⚙️ Robust Retries: Implements exponential backoff to automatically retry sending data on network or server errors.
• Modern: Uses async/await and is built on top of the popular axios library.
• 🌐 Universal: Works in any modern Node.js environment.

Installation

npm install harborscalesdk

Quickstart Guide

Here is a basic example of how to use the SDK.

import { HarborClient, GeneralReading } from 'harborscalesdk';

// 1. Initialize the client
const client = new HarborClient(
  'YOUR_API_ENDPOINT',
  'YOUR_API_KEY'
);

async function main() {
  // 2. Create a reading object
  const reading: GeneralReading = {
    ship_id: 'node-freighter-01',
    cargo_id: 'cpu-load',
    value: 42.5,
  };

  try {
    // 3. Send the reading
    const response = await client.send(reading);
    console.log('Successfully sent data!', { status: response.status });

    // --- Or send a batch ---
    const readings: GeneralReading[] = [
      { ship_id: 'node-freighter-01', cargo_id: 'ram-usage', value: 8192 },
      { ship_id: 'node-freighter-01', cargo_id: 'disk-io', value: 512.7 },
    ];
    const batchResponse = await client.sendBatch(readings);
    console.log('Successfully sent batch!', { status: batchResponse.status });
  } catch (error) {
    console.error('Failed to send data:', error.message);
  }
}

main();

API Reference

HarborClient(endpoint, apiKey, [maxRetries], [initialBackoff])

The constructor for the client.

• endpoint (string): The URL of your Carroted Data ingestion endpoint.
• apiKey (string): Your unique API key for authentication.
• maxRetries (number, optional): The maximum number of retries. Defaults to 5.
• initialBackoff (number, optional): The initial backoff delay in milliseconds. Defaults to 1000.

async send(reading)

Sends a single telemetry reading.

async sendBatch(readings)

Sends an array of readings in a single HTTP request.