Typescript SDK for the Commerce API

Official TypeScript SDK for the Zebo Commerce API. Build powerful commerce applications with type-safe, modern JavaScript/TypeScript.

Features

• ✨ Full TypeScript support with comprehensive type definitions
• 🔄 Automatic retry logic with exponential backoff
• ⚡ Modern async/await API
• 🛡️ Built-in error handling with custom error classes
• 🔌 Request/response interceptors for middleware functionality
• 📦 Dual module support (CommonJS and ESM)
• 🧪 Thoroughly tested with >80% code coverage
• 📝 Comprehensive JSDoc documentation

Installation

npm install @preciousewusi/commerce-sdk-typescript

Or with yarn:

yarn add @preciousewusi/commerce-sdk-typescript

Or with pnpm:

pnpm add @preciousewusi/commerce-sdk-typescript

Quick Start

import { CommerceClient } from '@zebo/commerce-sdk';

// Initialize the client
const commerce = new CommerceClient({
  apiKey: 'your-api-key',
});

// Create an order
const order = await commerce.orders.create({
  customer_data: {
    name: 'John Doe',
    email_address: '[email protected]',
    phone_number: '0559714200',
  },
  line_items: [
    {
      type: 'product',
      product: {
        type: 'physical',
        quantity: 1,
        name: 'Premium Widget',
        price: { currency: 'ghs', value: 20000 }, // GHS 200.00
      },
    },
  ],
  billing_details: {
    email_address: '[email protected]',
    phone_number: '0559714200',
    name: 'John Doe',
    address: {
      name: 'John Doe',
      phone_number: '0559714200',
      line1: '123 Main Street',
      town: 'Accra',
      region: 'Greater Accra',
      country: 'GH',
    },
  },
  execute_payment: true,
});

console.log('Order created:', order.order.id);

Configuration

Basic Configuration

const commerce = new CommerceClient({
  apiKey: 'your-api-key', // Required
  baseUrl: 'https://api.zebo.dev', // Optional, defaults to production
  timeout: 30000, // Optional, request timeout in milliseconds
  debug: false, // Optional, enable debug logging
});

Retry Configuration

The SDK automatically retries failed requests with exponential backoff:

const commerce = new CommerceClient({
  apiKey: 'your-api-key',
  retry: {
    maxRetries: 3, // Maximum retry attempts
    initialDelay: 1000, // Initial delay in milliseconds
    maxDelay: 10000, // Maximum delay in milliseconds
    backoffMultiplier: 2, // Exponential backoff multiplier
  },
});

Dynamic Configuration Updates

// Update configuration after initialization
commerce.updateConfig({
  timeout: 60000,
  debug: true,
});

API Reference

Orders

The Orders resource allows you to create and manage orders.

Create Order

Create a new order with either a new customer or existing customer ID.

With new customer:

const order = await commerce.orders.create({
  customer_data: {
    name: 'John Doe',
    email_address: '[email protected]',
    phone_number: '0559714200',
    reference: 'customer-ref-123', // Optional
    metadata: { source: 'web' }, // Optional
  },
  line_items: [
    {
      type: 'product',
      product: {
        type: 'physical', // or 'digital'
        quantity: 2,
        name: 'Premium Widget',
        about: 'High-quality widget', // Optional
        reference: 'WIDGET-001', // Optional
        price: { currency: 'ghs', value: 20000 },
        tax_code: 'TAX001', // Optional
        metadata: { sku: 'WIDGET-001' }, // Optional
      },
    },
    {
      type: 'fee',
      fee: {
        amount: { currency: 'ghs', value: 1000 },
        description: 'Processing fee',
      },
    },
  ],
  billing_details: {
    email_address: '[email protected]',
    phone_number: '0559714200',
    name: 'John Doe',
    address: {
      name: 'John Doe',
      phone_number: '0559714200',
      line1: '123 Main Street',
      line2: 'Apt 4B', // Optional
      town: 'Accra',
      region: 'Greater Accra',
      country: 'GH',
      district: 'Accra Metro', // Optional
      post_code: '00233', // Optional
    },
  },
  shipping: {
    // Required for physical products
    address: {
      name: 'John Doe',
      phone_number: '0559714200',
      line1: '456 Delivery St',
      town: 'Accra',
      region: 'Greater Accra',
      country: 'GH',
    },
  },
  number: 'ORD-2024-001', // Optional custom order number
  statement_descriptor: 'MYSHOP*ORDER', // Optional
  execute_payment: true, // Optional, immediately execute payment
  send_invoice: false, // Optional, send invoice to customer
  idempotency_key: 'unique-key-123', // Optional
  redirect_url: 'https://myapp.com/return', // Optional
});

With existing customer:

const order = await commerce.orders.create({
  customer_id: 'cus_123456789',
  payment_method_id: 'pm_123456789', // Optional
  line_items: [
    /* ... */
  ],
  billing_details: {
    /* ... */
  },
});

Lookup Order

Retrieve order details by ID:

const orderDetails = await commerce.orders.lookup({
  order_id: 'ord_123456789',
});

console.log('Order status:', orderDetails.order.status);
console.log('Payment status:', orderDetails.order.payment_status);

Pay for Order

Pay for an existing order, either with inline payment method data or a saved payment method.

With mobile money:

const payment = await commerce.orders.pay({
  order_id: 'ord_123456789',
  payment_method_data: {
    type: 'mobile_money',
    mobile_money: {
      issuer: 'mtn', // 'mtn', 'vodafone', 'airteltigo'
      number: '0544998605',
    },
  },
});

if (payment.requires_confirmation) {
  console.log('Confirmation required. Redirect:', payment.redirect_url);
}

With saved payment method:

const payment = await commerce.orders.pay({
  order_id: 'ord_123456789',
});

Confirm Payment

Confirm a payment that requires additional verification (e.g., OTP):

const result = await commerce.orders.confirmPayment({
  order_id: 'ord_123456789',
  token: '123456', // OTP or confirmation token
});

if (result.success) {
  console.log('Payment confirmed!');
}

Request Confirmation

Request a new confirmation token (e.g., resend OTP):

const result = await commerce.orders.requestConfirmation({
  order_id: 'ord_123456789',
});

console.log(result.message);

Error Handling

The SDK provides comprehensive error handling with custom error classes:

import {
  CommerceAPIError,
  CommerceValidationError,
  CommerceNetworkError,
  CommerceAuthenticationError,
  CommerceRateLimitError,
} from '@zebo/commerce-sdk';

try {
  const order = await commerce.orders.create({
    /* ... */
  });
} catch (error) {
  if (error instanceof CommerceValidationError) {
    console.error('Validation error:', error.message);
    console.error('Field:', error.param);
    console.error('Details:', error.details);
  } else if (error instanceof CommerceAuthenticationError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof CommerceRateLimitError) {
    console.error('Rate limited. Retry after:', error.retryAfter);
  } else if (error instanceof CommerceNetworkError) {
    console.error('Network error:', error.message);
    console.error('Is timeout:', error.isTimeout);
  } else if (error instanceof CommerceAPIError) {
    console.error('API error:', error.message);
    console.error('Status code:', error.statusCode);
    console.error('Error code:', error.code);
  } else {
    console.error('Unexpected error:', error);
  }
}

Advanced Usage

Request Interceptors

Add custom logic before requests are sent:

commerce.addRequestInterceptor((url, options) => {
  // Add custom headers
  options.headers = {
    ...options.headers,
    'X-Custom-Header': 'value',
  };

  // Log requests in debug mode
  console.log(`Making request to: ${url}`);

  return { url, options };
});

Response Interceptors

Process responses before they're returned:

commerce.addResponseInterceptor((response) => {
  // Log response status
  console.log('Response status:', response.status);

  // Track API usage
  const requestId = response.headers.get('x-request-id');
  if (requestId) {
    console.log('Request ID:', requestId);
  }

  return response;
});

Idempotency

Use idempotency keys to safely retry requests:

import { generateIdempotencyKey } from '@zebo/commerce-sdk';

const idempotencyKey = generateIdempotencyKey();

const order = await commerce.orders.create({
  // ... order data
  idempotency_key: idempotencyKey,
});

Money Amounts

All monetary values use minor units (e.g., pesewas for GHS):

// GHS 100.50 = 10050 pesewas
const price = {
  currency: 'ghs',
  value: 10050,
};

// GHS 200.00 = 20000 pesewas
const amount = {
  currency: 'ghs',
  value: 20000,
};

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import type {
  Order,
  CreateOrderRequest,
  PaymentMethodData,
  MoneyAmount,
  LineItem,
} from '@zebo/commerce-sdk';

// Full IntelliSense support
const lineItem: LineItem = {
  type: 'product',
  product: {
    type: 'physical',
    quantity: 1,
    name: 'Product',
    price: { currency: 'ghs', value: 10000 },
  },
};

Testing

Run the test suite:

npm test

Run tests with coverage:

npm run test:coverage

Run tests in watch mode:

npm run test:watch

Development

Building

npm run build

Linting

npm run lint
npm run lint:fix

Type Checking

npm run typecheck

Examples

Check out the examples directory for complete working examples:

• Basic order creation
• Mobile money payment
• Payment confirmation flow
• Error handling

API Versioning

The SDK targets API version v1. Future versions will be supported through separate package versions.

Support

• 📧 Email: [email protected]
• 📚 Documentation: https://docs.zebo.dev
• 🐛 Issues: https://github.com/zebo/commerce-sdk-typescript/issues

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT License - see LICENSE for details.

Changelog

See CHANGELOG.md for a list of changes.