npm package: @preciousewusi/commerce-sdk-typescript
Description: Official TypeScript SDK for the Zebo Commerce API
Author: Zebo
Latest version: 0.4.0

# Typescript SDK for the Commerce API

Official TypeScript SDK for the [Zebo Commerce API](https://api.zebo.dev). 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

```bash
npm install @preciousewusi/commerce-sdk-typescript
```

Or with yarn:

```bash
yarn add @preciousewusi/commerce-sdk-typescript
```

Or with pnpm:

```bash
pnpm add @preciousewusi/commerce-sdk-typescript
```

## Quick Start

```typescript
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: 'john@example.com',
    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: 'john@example.com',
    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

```typescript
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:

```typescript
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

```typescript
// 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:**

```typescript
const order = await commerce.orders.create({
  customer_data: {
    name: 'John Doe',
    email_address: 'john@example.com',
    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: 'john@example.com',
    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:**

```typescript
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:

```typescript
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:**

```typescript
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:**

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

#### Confirm Payment

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

```typescript
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):

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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):

```typescript
// 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:

```typescript
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:

```bash
npm test
```

Run tests with coverage:

```bash
npm run test:coverage
```

Run tests in watch mode:

```bash
npm run test:watch
```

## Development

### Building

```bash
npm run build
```

### Linting

```bash
npm run lint
npm run lint:fix
```

### Type Checking

```bash
npm run typecheck
```

## Examples

Check out the [examples](./examples) directory for complete working examples:

- [Basic order creation](./examples/basic-order.ts)
- [Mobile money payment](./examples/mobile-money-payment.ts)
- [Payment confirmation flow](./examples/payment-confirmation.ts)
- [Error handling](./examples/error-handling.ts)

## API Versioning

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

## Support

- 📧 Email: support@zebo.dev
- 📚 Documentation: https://docs.zebo.dev
- 🐛 Issues: https://github.com/zebo/commerce-sdk-typescript/issues

## Contributing

Contributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) for details.

## License

MIT License - see [LICENSE](./LICENSE) for details.

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for a list of changes.