TypeScript icon, indicating that this package has built-in type declarations

1.1.7 • Public • Published

Octane Node.js Library

Version GitHub Actions status


The Octane Node.js library provides programmatic access to the Octane API for server-side JavaScript apps.

Getting started

First, install octane-node and add it to your package.json dependencies:

npm install octane-node --save

We use the fetch API to handle making all of our requests. If your environment doesn't have fetch available, you'll need to polyfill it using something like node-fetch:

npm install node-fetch --save

Next, obtain an API key from within the Octane portal, and set it in your environment:

export OCTANE_API_KEY="<insert_octane_api_key_here>"

Then, from within your application, import the module (and optionally the fetch polyfill):

import fetch from 'node-fetch';
import Octane from 'octane-node';
const octane = new Octane(process.env.OCTANE_API_KEY, {
  // If your fetch polyfill isn't on the global scope,
  // provide it to the SDK explicitly.
  fetchApi: fetch,

CommonJS support

The octane-node library is compatible with CommonJS-style imports, but unfortunately, node-fetch is not by default. If you need to use CommonJS and do not have fetch available on the global scope, octane-node allows passing in any fetch library directly. For example, you can provide a copy of node-fetch v2, which supports CommonJS-style imports:

const fetch = require('node-fetch');

const octane = require('octane-node')(process.env.OCTANE_API_KEY, {
  fetchApi: fetch,

For more details on compatibility between node-fetch and CommonJS, check out this section in their docs.

Configuring the SDK

The SDK accepts an optional configuration object. You can use it to point the SDK at a different host or to enable experimental features.

import Octane from 'octane-node';

// This is the full config object and its default values.
const config = {
  // 'host', 'port', and 'protocol' modify the connection to the API, although
  // it isn't likely that you'll need to set these.
  host: 'api.cloud.getoctane.io',
  port: 443,
  protocol: 'https',
  // You can override the global `fetch` or directly provide access to a
  // fetch API using `fetchApi`. The global fetch is used by default.
  fetchApi: fetch,
  // Our SDK supports middleware for intercepting requests before they go
  // out and responses before they come back.
  middlewares: [
      pre: ({ fetch, url, init }) => {
        logRequest(url, init);
        return Promise.resolve({ url, init });
      post: ({ fetch, url, init, response }) => {
        return Promise.resolve(response);
const octane = new Octane(process.env.OCTANE_API_KEY, config);

Example apps

The following demo applications found in the examples/ directory display how to use the Octane Node.js library in real-world settings:

Making API calls

The Octane class provides programmatic access to the Octane API.

Note: Throughout several of the examples, we will reference a predefined sample function, crash, which can be used to handle API errors:

const crash = (errorResponse) => {
  return errorResponse.json().then((data) => {
    console.error(`Code:    ${data['code']}`);
    console.error(`Status:  ${data['status']}`);
    console.error(`Message: ${data['message']}`);

Customers API

The customers namespace on an Octane class instance provides the ability to make calls to the Octane Customers API.

Example: Creating a new customer

const name = 'r2d2';
const displayName = 'Artoo-Detoo';

const customer = {


Example: Subscribe a customer to a price plan

const customerName = 'r2d2';

const subscription = {
  pricePlanName: 'droidplan',

octane.customers.createSubscription(customerName, subscription).catch(crash);

Meters API

The meters namespace on an Octane class instance provides the ability to make calls to the Octane Meters API.

Example: Creating a new meter

const meterName = 'droidrepairs';

const meter = {
  name: meterName,
  meterType: 'COUNTER',
  isIncremental: true,


Price Plans API

The pricePlans namespace on an Octane class instance provides the ability to make calls to the Octane Price Plans API.

Example: Creating a new price plan

const pricePlanName = 'droidplan';
const pricePlanRate = 10000; // $100.00
const meterName = 'droidrepairs';

const pricePlan = {
  name: pricePlanName,
  period: 'month',
  meteredComponents: [
      meterName: meterName,
      priceScheme: {
        prices: [
            price: pricePlanRate,
        schemeType: 'FLAT',


Measurements API

The measurements namespace on an Octane class instance provides the ability to make calls to the Octane Measurements API.

Example: Sending a measurement

const meterName = 'droidrepairs';
const customerName = 'r2d2';

const measurement = {
  value: 1,


TypeScript support

The library itself is written first in TypeScript, and thus, TypeScript is fully supported (v3.6 and later).

The octane-node/types submodule contains all of the type defintions used for various method arguments and return values when making API requests, etc.

Types example

Here is a full example of using types while creating a customer:

import fetch from 'node-fetch';
import Octane from 'octane-node';
import { CreateCustomerArgs } from 'octane-node/types';

const octane = new Octane(process.env.OCTANE_API_KEY!);

const customerName = 'r2d2';

const customer: CreateCustomerArgs = {
  name: customerName,
  measurementMappings: [
      label: 'customer_name',
      valueRegex: customerName,

octane.customers.create(customer).catch((errorResponse: Response) => {


In the root of this repo, download required dependencies from npm:

npm install

To regenerate files in src/codegen/ from latest Octane OpenAPI spec, run the following:

npm run-script codegen

These files should then be checked into git:

git add src/codegen/

To compile TypeScript to JavaScript, creating the build/ directory, run the following:

npm run-script build


Contributions are welcome!

Prior to submitting a pull request, please check the list of open issues. If there is not an existing issue related to your changes, please open a new issue to first discuss your thoughts with the project maintainers.



npm i octane-node

DownloadsWeekly Downloads






Unpacked Size

12.2 MB

Total Files


Last publish


  • oc-divanyuk
  • salemhilal
  • akshalaby