npm package: @startbutton/node-sdk
Description: Official Node.js SDK for StartButton Payment API
Author: StartButton
Latest version: 1.0.1

# StartButton Node.js SDK

Official Node.js SDK for the StartButton Payment API. This SDK provides a clean, type-safe, and developer-friendly interface for integrating StartButton payment services into your Node.js applications.

## Features

- 🚀 **TypeScript Support**: Full TypeScript support with comprehensive type definitions
- 🔐 **Authentication**: Automatic API key management and authentication
- 🛡️ **Security**: Built-in webhook signature verification
- 🔄 **Retry Logic**: Automatic retry with exponential backoff
- 📝 **Validation**: Comprehensive input validation
- 🧪 **Testing**: High test coverage with Jest
- 📚 **Documentation**: Comprehensive JSDoc documentation

## Installation

```bash
npm install @startbutton/node-sdk
```

## Quick Start

```typescript
import { StartButtonSDK } from '@startbutton/node-sdk';

// Initialize the SDK
const sdk = new StartButtonSDK('your-secret-key', {
  environment: 'test' // or 'live'
});

// Initialize a transaction
const transaction = await sdk.transactions.initialize({
  email: 'customer@example.com',
  amount: 100000, // in kobo (1000 naira)
  currency: 'NGN',
  reference: 'unique-reference-123'
});

console.log('Transaction initialized:', transaction.data);
```

## Configuration

### Configuration Options

```typescript
const sdk = new StartButtonSDK('your-secret-key', {
  environment: 'test', // 'test' or 'live'
  timeout: 30000, // Request timeout in milliseconds
  baseUrl: 'https://api.startbutton.com' // Custom base URL (optional)
});
```

Note: the SDK does not auto-read environment variables. Pass your secret key and options explicitly when constructing `StartButtonSDK`.

## Core Modules

### Transactions

Handle payment transactions and collections.

```typescript
// Initialize a transaction
const transaction = await sdk.transactions.initialize({
  email: 'customer@example.com',
  amount: 100000,
  reference: 'unique-reference',
  currency: 'NGN',
  callbackUrl: 'https://your-site.com/callback'
});

// Verify a transaction
const verification = await sdk.transactions.verify('transaction-reference');


```

<!-- Collections and Transfers modules are currently not exposed in the SDK client -->

### Merchants

Access merchant account information.

```typescript
// Get wallet balance
const balance = await sdk.merchants.getWalletBalance();
```

### Webhooks

Verify and handle webhooks securely.

```typescript
// Verify webhook signature
const isValid = sdk.webhooks.verifySignature(
  typeof req.body === 'string' ? req.body : req.body.toString('utf8'),
  signature,
  'your-webhook-secret'
);

if (isValid) {
  // Transaction status query
  const webhookData = sdk.webhooks.transactionStatus(req.body.transactionReference);
  console.log('Webhook received:', webhookData);
}
```


### Default headers sent with each request

The SDK automatically sends these headers:

- Authorization: Bearer <secretKey>
- Content-Type: application/json
- User-Agent: <userAgent>/<version>
- X-SDK-Version: <version>
- X-SDK-Source: node-sdk

## Error Handling

The SDK provides comprehensive error handling with specific error types:

```typescript
try {
  const transaction = await sdk.transactions.initialize({
    email: 'invalid-email',
    amount: -100
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log('Validation failed:', error.errors);
  } else if (error instanceof AuthenticationError) {
    console.log('Authentication failed');
  } else if (error instanceof RateLimitError) {
    console.log('Rate limit exceeded');
  } else {
    console.log('Unexpected error:', error.message);
  }
}
```


## Testing

Run the test suite:

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage
```

## Development

### Building the SDK

```bash
# Build for production
npm run build

# Build TypeScript declarations
npm run build:types

# Clean build artifacts
npm run clean
```

### Code Quality

```bash
# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format
```

## API Reference

For detailed API documentation, see the [API Reference](./docs/API.md).


## License

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

## Support

- Documentation: [https://startbutton.gitbook.io](https://startbutton.gitbook.io)