@splito/sdk/README.md

Official JavaScript/TypeScript SDK for Splito - Split payments across multiple recipients

# Splito SDK

Official JavaScript/TypeScript SDK for [Splito](https://splito.net) - Split payments across multiple recipients with ease.

## Installation

```bash
npm install @splito/sdk
# or
yarn add @splito/sdk
```

## Quick Start

```typescript
import { Splito } from '@splito/sdk';

// Initialize the SDK
const splito = new Splito({
  apiKey: 'your-api-key-here'
});

// Create a product
const product = await splito.createProduct({
  name: 'Premium Subscription',
  description: 'Monthly premium subscription',
  price: 2999, // cents
  currency: 'USD'
});

// Create a payment intent
const paymentIntent = await splito.createPaymentIntent({
  amount: 2999, // cents
  currency: 'USD'
});

// Redirect customer to the hosted payment page
window.location.href = paymentIntent.hosted_url;
```

## API Reference

### Initialization

```typescript
const splito = new Splito({
  apiKey: string,     // Your Splito API key
  timeout?: number    // Request timeout in ms (default: 10000)
});
```

### Methods

#### `createProduct(data)`

Create a new product.

```typescript
const product = await splito.createProduct({
  name: string,
  description?: string,
  price: number,        // Amount in cents
  currency?: string,    // Default: 'USD'
  metadata?: object,
  external_product_id?: string  // Your unique product identifier
});
```

#### `createPaymentIntent(data)`

Create a new payment intent.

```typescript
const intent = await splito.createPaymentIntent({
  amount: number,       // Amount in cents
  currency: string,     // Default: 'USD'
  metadata?: object
});
```

**Returns:**
```typescript
{
  id: string,
  hosted_url: string,   // URL to redirect customers to
  // ... other fields
}
```

#### `getPaymentIntent(id)`

Retrieve a payment intent by ID.

```typescript
const intent = await splito.getPaymentIntent('intent_id');
```

#### `listPaymentIntents(params?)`

List payment intents with optional filtering.

```typescript
const intents = await splito.listPaymentIntents({
  limit?: number,
  offset?: number,
  status?: string,
  product_id?: string
});
```

#### `listProducts(params?)`

List products with optional filtering.

```typescript
const products = await splito.listProducts({
  limit?: number,
  offset?: number,
  search?: string,
  is_active?: boolean
});
```

#### `getProductByExternalId(externalProductId)`

Retrieve a product by its external product ID.

```typescript
const product = await splito.getProductByExternalId('your_external_id');
```

#### `listRecipients(params?)`

List recipients with optional filtering.

```typescript
const recipients = await splito.listRecipients({
  limit?: number,
  offset?: number,
  search?: string,
  status?: string
});
```

#### `getEvents(params?)`

Retrieve events with optional filtering.

```typescript
const events = await splito.getEvents({
  type?: string,
  limit?: number
});
```

#### `getAnalytics(params?)`

Get analytics data.

```typescript
const analytics = await splito.getAnalytics({
  start_date?: string,  // ISO format
  end_date?: string     // ISO format
});
```

#### `sendTestWebhook(webhookUrl, webhookSecret?)`

Send a test webhook event.

```typescript
const result = await splito.sendTestWebhook(
  'https://your-site.com/webhook',
  'optional_webhook_secret'
);
```

## Error Handling

All SDK methods throw errors when requests fail:

```typescript
try {
  const intent = await splito.createPaymentIntent({
    amount: 2999,
    currency: 'USD'
  });
} catch (error) {
  console.error('Payment creation failed:', error.message);
}
```

## TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

```typescript
import { Splito, SplitoConfig } from '@splito/sdk';
import type { 
  CreatePaymentIntentRequest,
  CreatePaymentIntentResponse,
  PaymentIntent 
} from '@splito/sdk';
```

## Examples

### React Integration

```typescript
import { useState } from 'react';
import { Splito } from '@splito/sdk';

const splito = new Splito({
  apiKey: process.env.REACT_APP_SPLITO_API_KEY
});

function CheckoutButton() {
  const [loading, setLoading] = useState(false);

  const handleCheckout = async () => {
    setLoading(true);
    try {
      const intent = await splito.createPaymentIntent({
        amount: 2999,
        currency: 'USD',
        metadata: { userId: '123' }
      });
      
      // Redirect to Splito hosted payment page
      window.location.href = intent.hosted_url;
    } catch (error) {
      console.error(error);
      setLoading(false);
    }
  };

  return (
    <button onClick={handleCheckout} disabled={loading}>
      {loading ? 'Loading...' : 'Pay $29.99'}
    </button>
  );
}
```

### Node.js Backend

```typescript
import express from 'express';
import { Splito } from '@splito/sdk';

const app = express();
const splito = new Splito({
  apiKey: process.env.SPLITO_API_KEY
});

app.post('/create-payment', async (req, res) => {
  try {
    const { amount, currency } = req.body;
    
    const intent = await splito.createPaymentIntent({
      amount,
      currency,
      metadata: { orderId: req.body.orderId }
    });
    
    res.json({ checkoutUrl: intent.hosted_url });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});
```

## Support

- 📧 Email: support@splito.net
- 📚 Documentation: https://splito.net/docs
- 🐛 Issues: https://github.com/your-org/splito-sdk/issues

## License

MIT License - see LICENSE file for details.