Octane Node.js Library

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

• Octane Node.js Library
  • Getting started
    • CommonJS support
  • Configuring the SDK
  • Example apps
  • Making API calls
    • Customers API
      • Example: Creating a new customer
      • Example: Subscribe a customer to a price plan
    • Meters API
      • Example: Creating a new meter
    • Price Plans API
      • Example: Creating a new price plan
    • Measurements API
      • Example: Sending a measurement
  • TypeScript support
    • Types example
  • Development
  • Contributing

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 }) => {
        logResponse(response.clone());
        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:

• antler-db-cloud-shop - Enable your customers to self-service various cloud resources
• customer-hours-tracker - Track hours spent working on freelance projects

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 = {
  name,
  displayName,
};

octane.customers.create(customer).catch(crash);

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,
};

octane.meters.create(meter).catch(crash);

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',
      },
    },
  ],
};

octane.pricePlans.create(pricePlan).catch(crash);

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 = {
  meterName,
  customerName,
  value: 1,
};

octane.measurements.create(measurement).catch(crash);

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) => {
  console.error(errorResponse.status);
  process.exit(1);
});

Development

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

Contributing

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.