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',
withOcWebhookAuth(shippingRatesHandler, 'my-secret-hash-key')
);
router.post('api/webhooks/shippingRates',
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',
withOcUserAuth(createPaymentHandler, ["Shopper"], ["Buyer"], ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"])
)
router.post('api/checkout/payment', withOcUserAuth(createPaymentHandler))
router.post('api/checkout/payment', withOcUserAuth(createPaymentHandler, [], [], ["*"]))
function createPaymentHandler(req, res, next) {
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);
}