npm package: @suipay/api
Description: Official TypeScript SDK for SuiPay API
Author: SuiPay
Latest version: 1.0.3

# SuiPay SDK

Official TypeScript SDK for the SuiPay API. Accept cryptocurrency payments and manage withdrawals with type safety and ease.

## Installation

```bash
npm install @suipay/api
# or
yarn add @suipay/api
```

## Quick Start

```typescript
import { SuiPayClient, PaymentDestinationType } from '@suipay/api';

const client = new SuiPayClient({
  apiKey: 'sk_your_api_key_here',
  baseUrl: 'https://api.suipay.net/api/v1' // optional, defaults to production
});

// Create a payment link
const paymentLink = await client.paymentLinks.create({
  amount_usdc: 100,
  description: 'Test payment',
  destination_type: PaymentDestinationType.POLAR_BALANCE
});

console.log(`Payment URL: ${paymentLink.url}`);
```

## Configuration

### Environment Variables

You can set environment variables to configure the SDK:

```bash
SUIPAY_API_KEY=sk_your_api_key_here
SUIPAY_API_URL=https://api.suipay.net/api/v1
```

### Client Options

```typescript
const client = new SuiPayClient({
  apiKey: process.env.SUIPAY_API_KEY!,
  baseUrl: process.env.SUIPAY_API_URL, // optional
  timeout: 30000 // optional, request timeout in ms (default: 30000)
});
```

## API Reference

### User Operations

```typescript
// Get user information
const user = await client.user.get();

// Get user's bank accounts
const bankAccounts = await client.user.getBankAccounts();

// Get user's Shopify sessions
const sessions = await client.user.getSessions();
```

### Payment Links

```typescript
import { PaymentDestinationType } from '@suipay/api';

// Create payment link with POLAR_BALANCE destination
const paymentLink = await client.paymentLinks.create({
  amount_usdc: 100,
  description: 'Test payment',
  destination_type: PaymentDestinationType.POLAR_BALANCE
});

// Create payment link with bank account destination
const bankPaymentLink = await client.paymentLinks.create({
  amount_usdc: 200,
  description: 'Payment to bank',
  destination_type: PaymentDestinationType.BANK_ACCOUNT,
  bank_account_id: 'bank_account_id_here'
});

// Create payment link with custom Sui address
const customPaymentLink = await client.paymentLinks.create({
  amount_usdc: 150,
  description: 'Payment to custom address',
  destination_type: PaymentDestinationType.CUSTOM_ADDRESS,
  custom_sui_address: '0x1234567890abcdef1234567890abcdef12345678'
});

// List all payment links
const paymentLinks = await client.paymentLinks.list();

// Get specific payment link
const paymentLink = await client.paymentLinks.get('payment_link_id');
```

### Withdrawals

```typescript
import { WithdrawDestinationType } from '@suipay/api';

// Create withdrawal to bank account
const bankWithdrawal = await client.withdrawals.create({
  amount_usdc: 50,
  destination_type: WithdrawDestinationType.BANK_ACCOUNT,
  bank_account_id: 'bank_account_id_here'
});

// Create withdrawal to wallet address
const walletWithdrawal = await client.withdrawals.create({
  amount_usdc: 25,
  destination_type: WithdrawDestinationType.WALLET,
  wallet_address: '0x1234567890abcdef1234567890abcdef12345678'
});

// List all withdrawals
const withdrawals = await client.withdrawals.list();

// Get specific withdrawal
const withdrawal = await client.withdrawals.get('withdrawal_id');
```

## Error Handling

The SDK provides specific error types for different scenarios:

```typescript
import { 
  SuiPayError, 
  SuiPayValidationError, 
  SuiPayAuthenticationError,
  SuiPayRateLimitError,
  SuiPayServerError 
} from '@suipay/api';

try {
  const paymentLink = await client.paymentLinks.create({
    amount_usdc: 100,
    description: 'Test payment',
    destination_type: 'INVALID_TYPE' as any
  });
} catch (error) {
  if (error instanceof SuiPayValidationError) {
    console.error('Validation error:', error.response?.error);
  } else if (error instanceof SuiPayAuthenticationError) {
    console.error('Authentication failed - check your API key');
  } else if (error instanceof SuiPayRateLimitError) {
    console.error('Rate limit exceeded - please wait before retrying');
  } else if (error instanceof SuiPayServerError) {
    console.error('Server error:', error.status, error.message);
  } else if (error instanceof SuiPayError) {
    console.error('SuiPay API error:', error.message);
  }
}
```

## Types

### Enums

```typescript
// Payment destination types
enum PaymentDestinationType {
  POLAR_BALANCE = 'POLAR_BALANCE',
  BANK_ACCOUNT = 'BANK_ACCOUNT',
  CUSTOM_ADDRESS = 'CUSTOM_ADDRESS'
}

// Withdrawal destination types
enum WithdrawDestinationType {
  BANK_ACCOUNT = 'BANK_ACCOUNT',
  WALLET = 'WALLET'
}

// Status enums
enum OffRampStatus {
  PENDING = 'PENDING',
  CCTP_TRANSFER_INITIATED = 'CCTP_TRANSFER_INITIATED',
  CCTP_TRANSFER_COMPLETED = 'CCTP_TRANSFER_COMPLETED',
  BRIDGE_TRANSFER_INITIATED = 'BRIDGE_TRANSFER_INITIATED',
  BRIDGE_TRANSFER_COMPLETED = 'BRIDGE_TRANSFER_COMPLETED',
  COMPLETED = 'COMPLETED',
  FAILED = 'FAILED'
}

enum WithdrawStatus {
  PENDING = 'PENDING',
  PROCESSING = 'PROCESSING',
  COMPLETED = 'COMPLETED',
  FAILED = 'FAILED'
}
```

## Testing Connection

```typescript
// Test if the API key and connection are valid
const result = await client.ping();
if (result.success) {
  console.log(`Connected successfully! User ID: ${result.user_id}`);
} else {
  console.log('Connection failed - check your API key');
}
```

## Rate Limits

The SuiPay API has the following rate limits:
- **General API**: 60 requests per minute
- **Authentication endpoints**: 5 requests per minute

The SDK will automatically throw a `SuiPayRateLimitError` when rate limits are exceeded.

## Requirements

- Node.js 16.0.0 or higher
- TypeScript 4.5 or higher (for TypeScript projects)

## Support

For API documentation and support, visit:
- [SuiPay Documentation](https://docs.suipay.net)
- [API Reference](https://api.suipay.net/docs)

## License

MIT License