@ordercloud/catalyst

ordercloud-javascript-catalyst

Starter middleware, extensions, and tools for building APIs when working with OrderCloud.

Installation

npm i @ordercloud/catalyst

Webhook Verification

Protect your webhook API routes by blocking requests that are not from OrderCloud.

next.js example

express.js example

Usage

import { withOcWebhookAuth } from '@ordercloud/catalyst';

router.post('api/checkout/shippingRates', 
  // Verifies that the request header "x-oc-hash" is valid given the secret key.
  withOcWebhookAuth(shippingRatesHandler, 'my-secret-hash-key')
);

router.post('api/webhooks/shippingRates', 
  // If a hashKey parameter is not included, it defaults to process.env.OC_WEBHOOK_HASH_KEY. 
  withOcWebhookAuth(shippingRatesHandler)
);

function shippingRatesHandler(req, res, next) { ... }

User Verification

Protect your API routes by using OrderCloud's user authentication - require an OrderCloud token with correct permissions.

next.js example

express.js example

Usage

import { withOcUserAuth, FullDecodedToken } from '@ordercloud/catalyst';

router.post('api/checkout/payment',
  // Verifies the request has an active OrderCloud bearer token with the "Shopper" role, the user type "Buyer"
  // and an api client ID of "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  withOcUserAuth(createPaymentHandler, ["Shopper"], ["Buyer"], ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"])
)

// Permission parameters are optional. A token with any roles and user type can access this. 
// However, process.env.OC_API_CLIENTS_WITH_ACCESS must be defined (comma-separated). 
router.post('api/checkout/payment', withOcUserAuth(createPaymentHandler)) 

// Same as above except the "*" character gives access to any client ID. 
// This can be a serious security hole, so only use if you understand the consequences. 
router.post('api/checkout/payment', withOcUserAuth(createPaymentHandler, [], [], ["*"])) 

function createPaymentHandler(req, res, next) { 
  // req.ocToken property has been added by withOcUserAuth.
  var token: FullDecodedToken = req.ocToken;
  ...
}

Error Handling

Create custom errors that will result in JSON responses matching OrderCloud's format.

next.js example

express.js example

Usage

import { CatalystBaseError } from '@ordercloud/catalyst';

export class CardTypeNotAcceptedError extends CatalystBaseError {
    constructor(type: string) {
        super("CardTypeNotAccepted", `This merchant does not accept ${type} type credit cards`, 400)
    }
}
...

if (!acceptedCardTypes.includes(type)) {
  throw new CardTypeNotAcceptedError(type);
}