npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@bigcommerce/api-nodejs

v0.1.2-alpha

Published

A node module for authentication and communication with the BigCommerce API

Downloads

3,578

Readme

Bigcommerce for Node.js

A node module for authentication and communication with the BigCommerce API.

Installation (In Development)

  1. Clone this repository: git clone [email protected]:bigcommerce/bigcommerce-api-node.git
  2. Navigate into the cloned repository: cd bigcommerce-api-node
  3. Run npm link: npm link

Now, you can navigate into the directory of some other package (e.g., sample-app-nodejs) and run npm link bigcommerce-api-node which will then allow you to use and test this package as if it was downloaded from NPM.

Type Generation

The bigcommerce-api-node package automatically generates Typescript types from the Open API spec .yml files that power our public API documentation. While making contributions to the bigcommerce-api-node package, you may find it necessary to re-generate types from the spec.

In order to do so, simply run:

npm run generate

This command will:

  1. Run npm run init to compile the TypeGenerator.ts class
  2. Run dist/generate/TypeGenerator.js to generate types
  3. Run npm build to build the types into the distributed Node.js package

Usage

First, import the package into your project:

import BigCommerce from '@bigcommerce/api-nodejs';

Then, create a BigCommerce object with configuration options relevant to your use case.

The BigCommerce Object

The main BigCommerce import is an object that contains properties for different use cases of the BigCommerce Node Client. The properties available are described below:

  • Auth: This class can be instantiated and used to handle the OAuth flow that begins when a merchant clicks Install on a single-click app.
  • Rest: This class can be instantiated and used to make API requests to the BigCommerce Public REST API.

OAuth

The bigcommerce-api-node package can be used to handle the OAuth flow that begins when a merchant clicks Install on a single-click app.

First, create a BigCommerce object with clientId, clientSecret, and authCallback as required configuration options:

const bigcommerceAuth = new BigCommerce.Auth({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  authCallback: 'https://yourapplication.com/auth',
});

The bigcommerceAuth object created above exposes two public methods: authorize and verifyJWT.

The authorize method takes one parameter — an object containing string values for code, scope, and context, which are provided by the GET request to your store when a merchant installs your app.

const payload = await bigcommerceAuth.authorize({code, scope, context});

The object stored in the payload variable above will contain the following key/value pairs:

{
  access_token: '123abc',
  scope: 'store_v2_orders etc.',
  user: {
    id: 12345,
    username: '[email protected]',
    email: '[email protected]',
  },
  context: 'stores/{STORE_HASH}',
  account_uuid: 'uuid-string'
}

The verifyJWT method can be used to verify and return the payload returned by the load, uninstall, and remove User callbacks. Each event triggers a GET request from BigCommerce to your app's callback endpoints containing a signed_payload_jwt as a query parameter. Once you parse the signed_payload_jwt from the request parameters, you can pass it to the verifyJWT method as follows:

const payload = bigcommerceAuth.verifyJWT(signed_payload_jwt);

The object stored in the payload variable above will contain the following key/value pairs:

{
  aud: 'YOUR_CLIENT_ID',
  iss: 'bc',
  iat: 1646844813,
  nbf: 1646844808,
  exp: 1646931213,
  jti: 'uuid-value',
  sub: 'stores/{STORE_HASH}',
  user: { id: 1470672, email: '[email protected]' },
  owner: { id: 1470672, email: '[email protected]' },
  url: '/'
}

REST

The bigcommerce-api-node package can be used to communicate with the BigCommerce Public REST API.

const bigcommerceRest = new BigCommerce.Rest({
  storeHash: 'yourStoreHash',
  accessToken: 'yourStoreAccessToken',
})

// bigcommerceRest.<resource_name>.<method_name>

Each method returns a Promise that resolves to a response containing the resource data.

bigcommerceRest.v2.orders
  .list({ limit: 5 })
  .then(orders => console.log(orders))
  .catch(err => console.error(err));

Some resources contain a listAll() method which returns an Iterator allowing you to loop through every single resource available, with pagination handled for you.

for await (const order of bigcommerceRest.v2.orders.listAll()) {
  console.log(order);
}

Rate Limiting Management

The RestClient class provides information on its status in relation to the BigCommerce API rate limiter. The available information includes:

  • msToReset: Time (in milliseconds) until rate limiting window resets
  • nextWindowTime: Date object for the start of the next rate limiting window
  • windowSize: Total size of the current rate limiting window
  • requestsRemaining: Number of requests remaining in the current window before rate limiting is enforced
  • requestsQuota: Total requests allowed per window

This information is updated on every request. It can be accessed via the rateLimitManager property and used to avoid receiving a 429 error from the server.

bigcommerceRest.rateLimitManager.status  // <-- { msToReset, windowSize, requestsRemaining, requestsQuota }

RestClient can be optionally configured to delay requests until the next rate limiting window when a minimum request threshold is met.

  const bigcommerceRest = new BigCommerce.Rest({
    storeHash: STORE_HASH,
    accessToken: ACCESS_TOKEN,
    rateLimitConfig: {
      enableWait: true,
      minRequestsRemaining: 10,
    },

Additionally, a custom callback can be provided with optional params object to be run when the request threshold is met.

  const limitCallback = params => console.log(params.message);

  const bigcommerceRest = new BigCommerce.Rest({
    storeHash: STORE_HASH,
    accessToken: ACCESS_TOKEN,
    rateLimitConfig: {
      enableWait: false,
      minRequestsRemaining: 10,
      callbackParams: { message: 'request threshold reached' },
      callback: limitCallback  // <-- function called with callbackParams when minRequestsRemaining threashold is met
    },

Available Resources and Methods

  • v2
    • v2.orders
      • get(orderId): Get an Order
      • update(orderId, data): Update an Order
      • archive(orderId): Archive an Order
      • count(): Get a Count of Orders
      • list([params]): Get All Orders
      • listAll([params]): Get All Orders (Paginated)
      • create(data): Create an Order
      • archiveAll(): Archive All Orders
    • v2.orders.orderCoupons
      • list(orderId[, params]): List Order Coupons
      • listAll(orderId[, params]): List Order Coupons (Paginated)
    • v2.orders.orderProducts
      • list(orderId[, params]): List Order Products
      • listAll(orderId[, params]): List Order Products (Paginated)
      • get(orderId, productId): Get an Order Product
    • v2.orders.orderTaxes
      • list(orderId[, params]): Get All Order Taxes
      • listAll(orderId[, params]): Get All Order Taxes (Paginated)
    • v2.orders.orderStatus
      • list(): Get All Order Statuses
      • get(statusId): Get a Single Order Status
    • v2.orders.orderShipments
      • list(orderId[, params]): Get Order Shipments
      • listAll(orderId[, params]): Get Order Shipments (Paginated)
      • create(orderId, data): Create Order Shipment
      • deleteAll(orderId): Delete All Order Shipments
      • count(orderId)Get a Count of Order Shipments
      • get(orderId, shipmentId): Get a Shipment
      • update(orderId, shipmentId, data): Update a Shipment
      • delete(orderId, shipmentId): Delete an Order Shipment
    • v2.orders.orderShippingAddresses
      • list(orderId[, params]): Get Order Shipping Addresses
      • listAll(orderId[, params]): Get Order Shipping Addresses (Paginated)
      • get(orderId, addressId): Get a Shipping Address
      • update(orderId, addressId, data): Update a Shipping Address
    • v2.orders.orderMessages
      • list(orderId[, params]): Get Order Messages
      • listAll(orderId[, params]): Get Order Messages (Paginated)
    • v2.orders.orderShippingQuotes
      • list(orderId, addressId): Get Order Shipping Quotes