@unitpay/sdk/README.md

Official Node.js SDK for UnitPay - usage-based billing, invoicing, and analytics

# @unitpay/sdk

[![npm version](https://badge.fury.io/js/%40unitpay%2Fsdk.svg)](https://badge.fury.io/js/%40unitpay%2Fsdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official Node.js SDK for UnitPay. Simplify integration with UnitPay's billing, customer management, and usage tracking services.

## Installation

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

## Quick Start

```typescript
import { UnitPayClient } from '@unitpay/sdk';

const client = new UnitPayClient('revx_pk_your_api_key');

// Track an event
await client.trackEvent({
  agentId: 'agent_123',
  customerExternalId: 'customer_456',
  signalName: 'meeting_booked',
  metadata: {
    usageCost: [
      {
        serviceName: 'SST-DeepGram', // Service name
        units: 10, // Units consumed
      },
      {
        serviceName: 'TTS-ElevanLabs', // Service name
        units: 10, // Units consumed
      },
    ],
  },
});
```

## Documentation

- [Configuration Options](#configuration)
- [Event Tracking Examples](#event-tracking)
- [Usage Cost Tracking](#usage-cost-tracking)
- [Customer Management](#customer-management)
- [Error Handling](#error-handling)
- [Advanced Features](#advanced-features)
- [API Reference](https://docs.useunitpay.com)

## Configuration

```typescript
const client = new UnitPayClient('revx_pk_your_api_key', {
  baseURL: 'https://api.custom-domain.com/v1',
  timeout: 10000,
  retries: 3,
  retryDelay: 300,
  logging: {
    enabled: true,
    level: 'info',
  },
  telemetry: {
    enabled: true,
    sampleRate: 1,
  },
});

await client.connect();
```

## Usage Examples

### Event Tracking

```typescript
// Simple event tracking
await client.trackEvent({
  agentId: 'agent_123',
  customerExternalId: 'customer_456',
  signalName: 'api_call',
  quantity: 1,
});

// Event with metadata and usage cost tracking
await client.trackEvent({
  agentId: 'agent_123',
  customerExternalId: 'customer_456',
  signalName: 'email_sent',
  quantity: 1,
  metadata: {
    eventId: 'email_sent',
    usageCost: [
      {
        serviceName: 'LLM',
        units: 7,
      },
      {
        serviceName: 'Intuit',
        units: 1,
      },
    ],
  },
});

// Batch tracking
await client.trackEvent({
  records: [
    {
      customerExternalId: 'customer_456',
      agentId: 'agent_123',
      signalName: 'api_call',
      quantity: 10,
      metadata: {
        endpoint: '/api/v1/search',
      },
    },
    {
      customerExternalId: 'customer_789',
      agentId: 'agent_123',
      signalName: 'storage',
      quantity: 100,
      usageDate: new Date('2023-08-15'),
      metadata: {
        storageType: 'object',
      },
    },
  ],
});
```

### Usage Cost Tracking

Track detailed cost breakdown through the `usageCost` field in metadata:

```typescript
await client.trackEvent({
  agentId: 'agent_123',
  customerExternalId: 'customer_456',
  signalName: 'lead_generated',
  quantity: 1,
  metadata: {
    eventId: 'lead_generated',
    usageCost: [
      {
        serviceName: 'wfloengine', // Service name
        units: 1, // Units consumed
      },
    ],
  },
});
```

The `usageCost` field structure:

| Field       | Type   | Description                              |
| ----------- | ------ | ---------------------------------------- |
| serviceName | string | Name of the service (e.g., 'LLM', 'TTS') |
| units       | number | Number of units consumed                 |

### Customer Management

```typescript
// Create a customer
const customer = await client.customers.create({
  name: 'Acme Corp',
  email: 'billing@acmecorp.com',
  externalId: 'acme-123',
});

// List customers
const customers = await client.customers.list({
  limit: 10,
  page: 1,
});

// Get, update and delete customers
const customer = await client.customers.get('customer_id');
await client.customers.update('customer_id', { name: 'Updated Name' });
await client.customers.delete('customer_id');
```

### Invoices (UnitPay Exclusive)

```typescript
// List invoices with filters
const { invoices, totalResults } = await client.invoices.list({
  customerId: 'cust_123',
  status: 'pending',
  page: 1,
  limit: 20,
});

// Get a specific invoice
const invoice = await client.invoices.get('inv_abc');
console.log(`Invoice ${invoice.invoiceNumber}: $${invoice.totalAmount}`);
```

### Analytics (UnitPay Exclusive)

```typescript
const analytics = await client.analytics.usage({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  groupBy: 'daily',
  customerId: 'cust_123',
});

console.log(`Total usage: ${analytics.summary.totalQuantity}`);
console.log(`Total cost: $${analytics.summary.totalCost}`);

// Time series data
analytics.data.forEach((point) => {
  console.log(`${point.date}: ${point.quantity} units, $${point.cost}`);
});
```

### Subscriptions (UnitPay Exclusive)

```typescript
// List subscriptions
const { subscriptions } = await client.subscriptions.list({
  status: 'active',
  customerId: 'cust_123',
});

// Get subscription with usage details
const sub = await client.subscriptions.get('sub_abc');
console.log(`Usage this period: ${sub.usage.totalQuantity}`);
```

## Error Handling

```typescript
import {
  UnitPayClient,
  UnitPayError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
} from '@unitpay/sdk';

try {
  await client.connect();
  await client.trackEvent({
    /* ... */
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error(`Authentication failed. Request ID: ${error.requestId}`);
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limit exceeded. Retry after ${error.retryAfter}s`);
  } else if (error instanceof ValidationError) {
    console.error(`Validation error: ${error.message}`);
  } else if (error instanceof UnitPayError) {
    console.error(`API Error (${error.statusCode}): ${error.message}`);
  }
}
```

## Advanced Features

### Request Retries

```typescript
const client = new UnitPayClient('revx_pk_your_api_key', {
  retries: 3,
  retryDelay: 300,
});
```

### Logging & Telemetry

The SDK includes a telemetry system that tracks API request performance and usage patterns:

```typescript
const client = new UnitPayClient('revx_pk_your_api_key', {
  logging: {
    enabled: true,
    level: 'debug',
    handler: (level, message, data) => {
      myLoggingSystem.log(level, message, data);
    },
  },
  telemetry: {
    enabled: true,
    sampleRate: 0.5, // Track 50% of requests
    handler: (metrics) => {
      myMonitoringSystem.trackApiRequest(metrics);
    },
  },
});
```

You can access telemetry statistics programmatically:

```typescript
// Get current statistics
const stats = client.getTelemetryStats();
console.log(`Total Requests: ${stats.requestCount}`);
console.log(`Success Rate: ${(stats.successRate * 100).toFixed(2)}%`);
```

## API Reference

Complete documentation available at [docs.useunitpay.com](https://docs.useunitpay.com).

## License

MIT License. See [LICENSE](./LICENSE) for details.