npm package: @hotpayments/nodejs-sdk
Description: Node.js SDK for HotPayments API - Handle payments, subscriptions, PIX transactions with a clean, Promise-based interface
Author: Andre Felipe
Latest version: 1.0.0

# HotPayments Node.js SDK

Node.js SDK for HotPayments API - Handle payments, subscriptions, PIX transactions with a clean, Promise-based interface.

## Installation

```bash
npm install @hotpayments/nodejs-sdk
```

## Quick Start

```javascript
import { Hotpayments } from '@hotpayments/nodejs-sdk';

// Initialize the SDK
Hotpayments.auth('your-api-key');

// Create a PIX QR Code
const qrCode = await Hotpayments.transactions().createPixQrCode({
  amount: 100.50,
  description: 'Payment for order #123',
  customer: {
    name: 'João Silva',
    email: 'joao@email.com',
    document: '12345678901'
  }
});

console.log(qrCode);
```

## TypeScript Support

This SDK is written in TypeScript and includes full type definitions:

```typescript
import { Hotpayments, type CreateCustomerRequest, type CreateQrCodeRequest } from '@hotpayments/nodejs-sdk';

Hotpayments.auth('your-api-key');

const customerData: CreateCustomerRequest = {
  name: 'João Silva',
  email: 'joao@email.com',
  document: '12345678901',
  phone_number: '+5511999999999'
};

const customer = await Hotpayments.customers().create(customerData);
```

## API Reference

### Authentication

```javascript
import { Hotpayments } from '@hotpayments/sdk';

// Set your API key
Hotpayments.auth('your-api-key');
```

### Transactions

#### Create PIX QR Code

```javascript
const qrCode = await Hotpayments.transactions().createPixQrCode({
  amount: 100.50,
  description: 'Payment description',
  customer: {
    name: 'Customer Name',
    email: 'customer@email.com',
    document: '12345678901'
  }
});
```

#### PIX Cashout

```javascript
const cashout = await Hotpayments.transactions().pixCashout({
  amount: 50.00,
  pix_key: 'user@email.com',
  description: 'Cashout description'
});
```

#### Check Transaction Status

```javascript
const transaction = await Hotpayments.transactions().check('transaction-id');
console.log(transaction.status);
```

### Customers

#### Create Customer

```javascript
const customer = await Hotpayments.customers().create({
  name: 'João Silva',
  email: 'joao@email.com',
  document: '12345678901',
  phone: '+5511999999999',
  address: {
    street: 'Rua das Flores',
    number: '123',
    neighborhood: 'Centro',
    city: 'São Paulo',
    state: 'SP',
    zip_code: '01234567'
  }
});
```

#### List Customers

```javascript
const customers = await Hotpayments.customers().list({
  page: 1,
  per_page: 20,
  search: 'João'
});

console.log(customers.data);
```

### Subscriptions

#### Create Subscription

```javascript
const subscription = await Hotpayments.subscriptions().create({
  customer_id: 'customer-id',
  plan_id: 'plan-id',
  trial_days: 7,
  start_date: '2024-01-01'
});
```

#### Get Subscription

```javascript
const subscription = await Hotpayments.subscriptions().show('subscription-id');
```

#### Cancel Subscription

```javascript
const subscription = await Hotpayments.subscriptions().cancel('subscription-id', {
  reason: 'Customer request',
  cancel_at_period_end: true
});
```

#### Suspend Subscription

```javascript
const subscription = await Hotpayments.subscriptions().suspend('subscription-id', {
  reason: 'Payment failure',
  suspend_until: '2024-02-01'
});
```

#### Reactivate Subscription

```javascript
const subscription = await Hotpayments.subscriptions().reactivate('subscription-id');
```

### Subscription Plans

#### List Subscription Plans

```javascript
const plans = await Hotpayments.subscriptionPlans().list({
  page: 1,
  per_page: 10
});

console.log(plans.data);
```

#### Get All Plans (alias for list)

```javascript
const plans = await Hotpayments.subscriptionPlans().all();
```

## Error Handling

The SDK uses standard JavaScript Error objects for error handling:

```javascript
try {
  const customer = await Hotpayments.customers().create({
    name: 'João Silva',
    email: 'invalid-email'
  });
} catch (error) {
  console.log('Error:', error.message);
}
```

## Environment Support

- **Node.js**: 16+ (ES2020)
- **Browsers**: Modern browsers with ES2020 support
- **TypeScript**: 5.0+

## License

MIT License - see LICENSE file for details.

## Support

- Documentation: [GitHub Repository](https://github.com/hotpayments/nodejs-sdk)
- Issues: [GitHub Issues](https://github.com/hotpayments/nodejs-sdk/issues)
- Email: contato@hotpayments.net