Cumulus SDK (TypeScript / JavaScript)

A small, typed client for the Cumulus Cloud Cost & Architecture Planner API. Works in Node 18+ and the browser. Zero runtime dependencies.

npm install cumulus-planner-sdk

Quick start

import { CumulusClient } from "cumulus-planner-sdk";

const cumulus = new CumulusClient({
  baseUrl: "https://cumulus.example.com", // your Cumulus site origin
});

const estimate = await cumulus.estimate({
  fields: { registered: 1_000_000, mau: 400_000, dau: 120_000, region: "use1" },
  components: [{ type: "api", proc: 40, ram: 4, stack: "node" }],
  databases: [{ engine: "postgresql", size: 500, mode: "managed" }],
  horizon_months: 12,
});

console.log(estimate.summary.monthly_net);     // e.g. 5421
console.log(estimate.projection.monthly);       // [m1, m2, …]
console.log(estimate.validation);               // any input-consistency notices

Fetch the pricing catalog (models, regions, rates, …):

const catalog = await cumulus.catalog();
console.log(catalog.rate.vcpu, catalog.models, catalog.regions.use1.m);

Configuration

new CumulusClient({
  baseUrl: "https://cumulus.example.com",
  basePath: "/cloud-planner/api", // default
  headers: { Authorization: "Bearer …" }, // sent on every request
  timeoutMs: 30_000,                       // per-request timeout
  retries: 2,                              // retry 429/5xx with backoff
  fetch: customFetch,                      // inject on Node < 18
});

On Node < 18 (no global fetch), pass one in:

import nodeFetch from "node-fetch";
const cumulus = new CumulusClient({ baseUrl, fetch: nodeFetch as any });

Errors

All failures throw a typed error you can branch on:

import {
  CumulusValidationError,
  CumulusRateLimitError,
  CumulusApiError,
  CumulusNetworkError,
} from "cumulus-planner-sdk";

try {
  await cumulus.estimate(input);
} catch (e) {
  if (e instanceof CumulusValidationError) {
    console.error("Bad input:", e.errors); // { "components": ["…"], … }
  } else if (e instanceof CumulusRateLimitError) {
    console.warn("Slow down, retry after", e.retryAfter, "s");
  } else if (e instanceof CumulusApiError) {
    console.error("API error", e.status, e.body);
  } else if (e instanceof CumulusNetworkError) {
    console.error("Transport failed", e.cause);
  }
}

Cancellation

const controller = new AbortController();
const p = cumulus.estimate(input, { signal: controller.signal });
controller.abort();

Types

Every request and response is typed — PlannerInput, Component, Database, Estimate, Catalog, Projection, ValidationNotice, etc. are exported.

Build from source

npm install
npm run build      # dist/index.js (ESM), dist/index.cjs (CJS), dist/index.d.ts
npm run typecheck