OrderCloud JavaScript SDK

Common errors

• Error: Cannot find module 'axios' or its corresponding type declarations.

  cause The `axios` library, a required peer dependency, is not installed in the project.
  fix Install `axios` using your package manager: `npm install axios` or `yarn add axios`.

• TypeError: OrderCloudSDK.Auth.Login is not a function

  cause This error typically occurs if `Auth` was not correctly imported or accessed. Common causes include trying to use `OrderCloudSDK.Auth` after a named ESM import like `import { Auth } from 'ordercloud-javascript-sdk';` or attempting to destructure `Auth` from a CommonJS `require` call without first getting the main object.
  fix For ESM, ensure you use `import { Auth } from 'ordercloud-javascript-sdk';` and then directly call `Auth.Login(...)`. For CJS, use `const OrderCloudSDK = require('ordercloud-javascript-sdk');` and then call `OrderCloudSDK.Auth.Login(...)`.

Warnings

• breaking Major versions (e.g., v12.0.0) often introduce breaking changes. It is crucial to consult the `MIGRATION_GUIDE.md` for specific instructions when upgrading from older versions.
  Fix: Always review the `MIGRATION_GUIDE.md` document in the package's GitHub repository or documentation when upgrading to a new major version to understand and apply necessary code changes.
• gotcha The `axios` library is a peer dependency and is not automatically installed with the SDK. Failure to install `axios` separately will lead to runtime errors when making API calls.
  Fix: Ensure `axios` is installed in your project: `npm install axios` or `yarn add axios`.
• gotcha The SDK relies exclusively on named exports for its modules. Attempting to use a default import will result in `undefined` or runtime errors.
  Fix: Always use named imports (e.g., `import { Auth } from 'ordercloud-javascript-sdk';`) for ESM, or access properties on the `require`'d object (e.g., `OrderCloudSDK.Auth`) for CJS.

Install

• npm install ordercloud-javascript-sdk npm
• yarn add ordercloud-javascript-sdk yarn
• pnpm add ordercloud-javascript-sdk pnpm

Imports

• Products
  wrong:

  const Products = require('ordercloud-javascript-sdk').Products;

  correct:

  import { Products } from 'ordercloud-javascript-sdk';

  Recommended for browser environments to enable tree shaking, importing only the necessary API resource modules.
• Auth, Tokens
  wrong:

  import OrderCloudSDK from 'ordercloud-javascript-sdk'; // Auth is not a default export

  correct:

  import { Auth, Tokens } from 'ordercloud-javascript-sdk';

  Accesses authentication methods and token utilities. This SDK uses named exports exclusively for its modules.
• OrderCloudSDK (full object)
  wrong:

  import OrderCloudSDK from 'ordercloud-javascript-sdk'; // No default export for the entire SDK object

  correct:

  const OrderCloudSDK = require('ordercloud-javascript-sdk');

  Standard CommonJS import for Node.js environments or projects not using ESM. All resources are accessible via `OrderCloudSDK.ResourceName`.

Quickstart

Demonstrates how to authenticate with the OrderCloud API using a username/password flow, store the access token for subsequent API calls, and handles potential errors during the authentication process.

import { Auth, Tokens } from 'ordercloud-javascript-sdk';

// These should ideally come from environment variables or a secure configuration store.
// Using process.env.VAR_NAME ?? '' for illustration, replace with actual secure methods in production.
const username = process.env.ORDERCLOUD_USERNAME ?? 'YOUR_USERNAME';
const password = process.env.ORDERCLOUD_PASSWORD ?? 'YOUR_PASSWORD';
const clientID = process.env.ORDERCLOUD_CLIENT_ID ?? 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'; // Sign up for free at portal.ordercloud.io/register
const scope = ['FullAccess']; // Array of roles, e.g., ['FullAccess', 'BuyerAdmin', 'MeAdmin']

async function authenticateAndLogToken() {
  try {
    const response = await Auth.Login(username, password, clientID, scope);
    const token = response.access_token;
    Tokens.SetAccessToken(token); // Set the token globally for subsequent API calls
    console.log('Successfully authenticated!');
    console.log('Access Token:', token);

    // Example: After successful login, you can make other API calls
    // import { Products } from 'ordercloud-javascript-sdk';
    // const products = await Products.List();
    // console.log('First 20 products:', products.Items.map(p => p.Name));

  } catch (error: any) {
    console.error('Authentication failed:', error.message);
    if (error.response) {
      console.error('API Error Response:', error.response.data);
    }
  }
}

authenticateAndLogToken();