OrderEazi Commerce Headless API TypeScript SDK

TypeScript SDK for the OrderEazi Commerce Headless API.

Installation

From S3 (Production)

The SDK is automatically generated and hosted on AWS S3 for each release. Install it directly from CloudFront:

npm install https://content.storefront7.co.za/{VERSION}/sdk/ordereazi-commerce-sdk-{VERSION}.tgz

Example:

npm install https://content.storefront7.co.za/1.0.0/sdk/ordereazi-commerce-sdk-1.0.0.tgz

For detailed installation instructions, see INSTALLATION.md.

Local Development

For local development, you can install from the local path:

npm install file:../src/Tools/Storefront.Sdk/TypeScript

Or use npm link:

cd src/Tools/Storefront.Sdk/TypeScript
npm link
cd ../../../react-storefront
npm link @ordereazi/commerce-sdk

Usage

The SDK is generated by openapi-generator's typescript-axios template: a shared Configuration object plus one XxxApi class per resource (named from the API's OpenAPI tags), not a single unified client class. Exact class/method names are generated from the spec, so they'll shift as Storefront.Api's store OpenAPI document evolves - this is representative of the current shape:

import { Configuration, AuthApi, CatalogProductsApi, SearchApi, CartApi, CheckoutApi } from '@ordereazi/commerce-sdk';

const config = new Configuration({
  basePath: 'https://api.example.com',
  // Store Access Key (pk_store_.../sk_store_...) is required on every request; a JWT bearer token is
  // added once the customer logs in.
  baseOptions: { headers: { 'X-Commerce-Key': 'pk_store_...' } }
});

// Authentication
const authApi = new AuthApi(config);
const loginResponse = await authApi.authLoginApi({ email: '[email protected]', password: 'password' });

const authedConfig = new Configuration({
  ...config,
  accessToken: loginResponse.data.token
});

// Products
const searchApi = new SearchApi(config);
const results = await searchApi.searchGetProductsApi('laptop', 1, 20);

const productApi = new CatalogProductsApi(config);
const product = await productApi.productGetBySkuApi('SKU123');

// Cart
const cartApi = new CartApi(authedConfig);
const cart = await cartApi.cartGetCartApi();
await cartApi.cartAddItemApi({ productId: 123, qty: 1 });

// Checkout
const checkoutApi = new CheckoutApi(authedConfig);
const paymentOptions = await checkoutApi.checkoutGetPaymentOptionsApi();
await checkoutApi.checkoutSetPaymentOptionApi({ paymentSystemName: 'Stripe' });

const order = await checkoutApi.checkoutCreateOrderApi({ checksum: cart.data.checksum, paymentMethodName: 'Stripe' });

Every method name is {tagName}{ActionName}Api, generated directly from the OpenAPI operationId - so it's predictable and stable across regenerations as long as the underlying Store action isn't renamed.

Retry / backoff on 429

The generated client (plain axios) doesn't retry anything by default. createRetryingAxios() wraps axios with a response interceptor that retries only on 429, honoring Retry-After when present and falling back to exponential backoff with jitter otherwise - see ../RETRY_POLICY.md for the full policy and why it's safe to retry every HTTP method:

import { Configuration, CartApi, createRetryingAxios } from '@ordereazi/commerce-sdk';

const config = new Configuration({ basePath: 'https://api.example.com' });
const cartApi = new CartApi(config, undefined, createRetryingAxios({ maxRetries: 3 }));

Testing

tests/retry.test.ts verifies the retry wrapper against a real local HTTP server (no mocking library). tests/smoke.test.ts verifies the generated client against a real running Storefront.Api (skips if unreachable):

npm test               # both suites
npm run test:retry     # retry wrapper only, no running API needed
API_URL=http://localhost:5135 npm run test:smoke

Generating the SDK

The SDK is generated from the OpenAPI specification:

npm run generate

This will:

1. Fetch the OpenAPI spec from the running API
2. Generate TypeScript types and client code
3. Build the SDK

Development

# Install dependencies
npm install

# Generate SDK from OpenAPI spec
npm run generate

# Build TypeScript
npm run build