Nightmarish Pawnshop Mystic

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

    1.0.2 • Public • Published

    Octane Node.js Library

    Version GitHub Actions status

    Octane

    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. We recommend 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);

    CommonJS support

    The octane-node library is compatible with CommonJS-style imports, but unfortunately, node-fetch is not by default. To work around this, the library allows passing in any fetch library directly. node-fetch recommends using the async import() method to load their polyfill in CommonJS:

    const fetch = (...args) =>
      import('node-fetch').then(({ default: fetch }) => fetch(...args));
    
    const octane = require('octane-node')(process.env.OCTANE_API_KEY, {
      fetchApi: fetch,
    });

    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:

    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.

    Keywords

    Install

    npm i octane-node

    DownloadsWeekly Downloads

    2,698

    Version

    1.0.2

    License

    MIT

    Unpacked Size

    6.11 MB

    Total Files

    484

    Last publish

    Collaborators

    • oc-divanyuk
    • salemhilal
    • akshalaby