npm package: @lipana/sdk
Description: Official Node.js SDK for Lipana M-Pesa API
Author: Lipana
Latest version: 1.0.3

# @lipana/sdk

Official Node.js SDK for the Lipana M-Pesa API. Type-safe, well-documented, and production-ready.

**Version**: 1.0.2  
**npm**: https://www.npmjs.com/package/@lipana/sdk  
**Documentation**: https://lipana.dev/docs

## Installation

```bash
npm install @lipana/sdk
# or
yarn add @lipana/sdk
# or
pnpm add @lipana/sdk
```

## Quick Start

```typescript
import { Lipana } from '@lipana/sdk';

// Initialize the SDK
const lipana = new Lipana({
  apiKey: process.env.LIPANA_SECRET_KEY, // Use secret key for server-side
  environment: 'production' // or 'sandbox' for testing
});

// Create a payment link
const paymentLink = await lipana.paymentLinks.create({
  title: 'Premium Subscription',
  description: 'Monthly subscription to our premium features',
  amount: 5000,
  currency: 'KES',
  allowCustomAmount: false,
  successRedirectUrl: 'https://yourwebsite.com/success'
});

console.log('Payment link created:', paymentLink.url);

// Initiate STK push payment
const stkResponse = await lipana.transactions.initiateStkPush({
  phone: '+254712345678',
  amount: 5000
});

console.log('STK push initiated:', stkResponse.transactionId);
```

## Features

- ✅ **Type Safety**: Full TypeScript support with autocomplete and type checking
- ✅ **Error Handling**: Comprehensive error handling with detailed error messages
- ✅ **Async/Await**: Modern async/await syntax for cleaner, readable code
- ✅ **Webhooks**: Built-in webhook signature verification utilities

## API Reference

### Transactions

```typescript
// List all transactions
const transactions = await lipana.transactions.list({
  status: 'success',
  limit: 50,
  startDate: '2024-01-01',
  endDate: '2024-12-31'
});

// Get a specific transaction
const transaction = await lipana.transactions.retrieve('txn_123456');

// Initiate STK push
const stkResponse = await lipana.transactions.initiateStkPush({
  phone: '+254712345678',
  amount: 5000
});
```

### Payment Links

```typescript
// Create a payment link
const paymentLink = await lipana.paymentLinks.create({
  title: 'Premium Subscription',
  amount: 5000,
  currency: 'KES'
});

// List payment links
const paymentLinks = await lipana.paymentLinks.list({
  status: 'active',
  limit: 10
});

// Update a payment link
const updatedLink = await lipana.paymentLinks.update('link_123456', {
  status: 'inactive'
});

// Delete a payment link
await lipana.paymentLinks.delete('link_123456');
```

### Webhooks

```typescript
// Get webhook settings
const settings = await lipana.webhooks.getSettings();

// Update webhook settings
await lipana.webhooks.updateSettings({
  webhookUrl: 'https://yourwebsite.com/webhooks',
  enabled: true
});

// Verify webhook signature
const isValid = lipana.webhooks.verify(
  request.body,
  request.headers['x-lipana-signature'],
  process.env.LIPANA_WEBHOOK_SECRET
);
```

### API Keys

```typescript
// List all API keys
const apiKeys = await lipana.apiKeys.list();

// Create a new API key
const apiKey = await lipana.apiKeys.create({
  name: 'Production Key',
  environment: 'production'
});
```

## Error Handling

```typescript
import { Lipana, LipanaError } from '@lipana/sdk';

try {
  const payment = await lipana.transactions.initiateStkPush({
    phone: '+254712345678',
    amount: 5000
  });
} catch (error) {
  if (error instanceof LipanaError) {
    if (error.isAuthenticationError()) {
      console.error('Authentication failed:', error.message);
    } else if (error.isValidationError()) {
      console.error('Validation error:', error.errors);
    } else {
      console.error('Error:', error.message);
    }
  }
}
```

## Configuration

### Environment

The SDK supports two environments:

- `production`: For live transactions
- `sandbox`: For testing

```typescript
const lipana = new Lipana({
  apiKey: process.env.LIPANA_SECRET_KEY,
  environment: 'sandbox' // or 'production'
});
```

### Custom Base URL

You can override the default base URL:

```typescript
const lipana = new Lipana({
  apiKey: process.env.LIPANA_SECRET_KEY,
  baseUrl: 'https://custom-api.example.com/api'
});
```

### Default Base URLs

The SDK automatically uses the correct base URL based on environment:

- **Production**: `https://api.lipana.dev/v1`
- **Sandbox**: `https://api-sandbox.lipana.dev/v1`

## Requirements

- Node.js >= 14.0.0
- TypeScript >= 4.0.0 (optional, but recommended)

## License

MIT

## Changelog

### Version 1.0.2
- ✅ Updated base URLs to use `/v1` endpoint
- ✅ Production: `https://api.lipana.dev/v1`
- ✅ Sandbox: `https://api-sandbox.lipana.dev/v1`

### Version 1.0.1
- ✅ Updated production base URLs
- ✅ Production: `https://api.lipana.dev/v1`
- ✅ Sandbox: `https://api-sandbox.lipana.dev/v1`

### Version 1.0.0
- 🎉 Initial release
- ✅ Full TypeScript support
- ✅ All API endpoints implemented
- ✅ Webhook signature verification
- ✅ Comprehensive error handling

## Support

- **Documentation**: [https://lipana.dev/docs](https://lipana.dev/docs)
- **npm Package**: [https://www.npmjs.com/package/@lipana/sdk](https://www.npmjs.com/package/@lipana/sdk)
- **Issues**: [https://github.com/lipana/lipana-node/issues](https://github.com/lipana/lipana-node/issues)
- **Website**: [https://lipana.dev](https://lipana.dev)