# @veritas/billing

Usage billing system for the Veritas B2B API.

## Overview

This package provides a complete billing solution including:

- Pricing tiers (Free, Basic, Pro, Enterprise)
- Usage tracking and metering
- Invoice generation
- Stripe integration for payment processing
- Self-service billing portal

## Installation

```bash
pnpm add @veritas/billing
```

## Quick Start

```typescript
import {
  createSubscriptionManager,
  createUsageTracker,
  createInvoiceManager,
  getPricingTier,
} from '@veritas/billing';

// Create billing services
const subscriptionManager = createSubscriptionManager({
  stripeSecretKey: process.env.STRIPE_SECRET_KEY!,
  stripeWebhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
  defaultCurrency: 'usd',
  taxRatePercent: 0,
  trialPeriodDays: 14,
  gracePeriodDays: 7,
});

const usageTracker = createUsageTracker();
const invoiceManager = createInvoiceManager();

// Create a customer
const customer = await subscriptionManager.createCustomer({
  apiKeyId: 'key_123',
  email: 'dev@example.com',
  tier: 'basic',
});
```

## Pricing Tiers

| Tier       | Monthly Price | Included Requests | Rate Limit |
| ---------- | ------------- | ----------------- | ---------- |
| Free       | $0            | 1,000             | 20/min     |
| Basic      | $49           | 10,000            | 100/min    |
| Pro        | $199          | 100,000           | 500/min    |
| Enterprise | Custom        | Custom            | Custom     |

### Getting Tier Configuration

```typescript
import { getPricingTier, getVisibleTiers, formatPrice } from '@veritas/billing';

// Get a specific tier
const proTier = getPricingTier('pro');
console.log(proTier.includedRequests); // 100000

// Get all visible tiers for pricing page
const tiers = getVisibleTiers();

// Format prices
console.log(formatPrice(19900, 'usd')); // '$199.00'
```

### Tier Recommendations

```typescript
import { recommendTier, getNextTierUp } from '@veritas/billing';

// Recommend tier based on usage
const recommended = recommendTier(50000); // 'pro'

// Get next tier up
const nextTier = getNextTierUp('basic'); // 'pro'
```

## Usage Tracking

Track API usage in real-time for billing:

```typescript
import { createUsageTracker } from '@veritas/billing';

const tracker = createUsageTracker();

// Record API request
await tracker.recordRequest({
  customerId: customer.id,
  apiKeyId: customer.apiKeyId,
  endpoint: 'feed.list',
  statusCode: 200,
  responseTimeMs: 150,
  dataTransferBytes: 5000,
});

// Get usage summary
const summary = await tracker.getUsageSummary(customer);
console.log('Total requests:', summary.totalRequests);
console.log('Overage requests:', summary.overageRequests);
console.log('Estimated overage charges:', summary.estimatedOverageChargeCents);

// Check overage status
const isOverage = await tracker.isInOverage(customer);
const usagePercent = await tracker.getUsagePercentage(customer);
```

### Usage Alerts

Set up alerts when usage thresholds are reached:

```typescript
import { createUsageAlertManager } from '@veritas/billing';

const alertManager = createUsageAlertManager();

// Create alert at 80% usage
alertManager.createAlert({
  customerId: customer.id,
  thresholdPercent: 80,
  enabled: true,
  notifyEmail: 'billing@example.com',
  notifyWebhook: true,
});

// Check and trigger alerts
await alertManager.checkAlerts(customerId, usagePercent, async (alert) => {
  // Send notification
  console.log(`Alert triggered: ${alert.thresholdPercent}% usage reached`);
});
```

## Invoice Management

Create and manage invoices:

```typescript
import { createInvoiceManager } from '@veritas/billing';

const invoiceManager = createInvoiceManager({
  invoicePrefix: 'INV',
  taxRatePercent: 0,
});

// Create invoice
const invoice = await invoiceManager.createInvoice(customer, usageSummary, {
  dueInDays: 30,
});

// Finalize and send
await invoiceManager.finalizeInvoice(invoice.id);

// Record payment
await invoiceManager.markPaid(invoice.id);

// Or partial payment
await invoiceManager.recordPayment(invoice.id, 5000);

// Add credit
await invoiceManager.addCredit(invoice.id, 1000, 'Promotional credit');

// Void invoice
await invoiceManager.voidInvoice(invoice.id);

// Get customer invoices
const invoices = await invoiceManager.getCustomerInvoices(customer.id);

// Get overdue invoices
const overdue = await invoiceManager.getOverdueInvoices();
```

## Subscription Management

Full subscription lifecycle management with Stripe:

```typescript
import { createSubscriptionManager } from '@veritas/billing';

const manager = createSubscriptionManager({
  stripeSecretKey: process.env.STRIPE_SECRET_KEY!,
  stripeWebhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
  defaultCurrency: 'usd',
  taxRatePercent: 0,
  trialPeriodDays: 14,
  gracePeriodDays: 7,
});

// Create customer with subscription
const customer = await manager.createCustomer({
  apiKeyId: 'key_123',
  email: 'dev@example.com',
  companyName: 'Acme Inc',
  tier: 'pro',
  billingInterval: 'monthly',
});

// Preview tier change
const preview = await manager.previewTierChange(customer.id, 'enterprise');
console.log('Net amount:', preview.netAmountCents);

// Change tier
await manager.changeTier(customer.id, 'enterprise', { immediate: true });

// Cancel subscription
await manager.cancelSubscription(customer.id, {
  immediate: false, // Cancel at period end
  reason: 'Customer requested',
});

// Reactivate
await manager.reactivateSubscription(customer.id);
```

### Self-Service Portal

Create Stripe customer portal sessions:

```typescript
// Create portal session
const portal = await manager.createPortalSession(
  customer.id,
  'https://your-app.com/billing'
);

// Redirect user to portal.url
```

### Checkout Sessions

Create checkout sessions for new signups:

```typescript
const checkout = await manager.createCheckoutSession({
  tier: 'pro',
  billingInterval: 'monthly',
  email: 'new@customer.com',
  successUrl: 'https://your-app.com/success',
  cancelUrl: 'https://your-app.com/cancel',
  metadata: { source: 'website' },
});

// Redirect to checkout.url
```

### Stripe Webhooks

Handle Stripe webhooks:

```typescript
// Express example
app.post(
  '/webhooks/stripe',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const result = await manager.handleStripeWebhook(
      req.body.toString(),
      req.headers['stripe-signature']
    );

    if (result.handled) {
      res.sendStatus(200);
    } else {
      res.sendStatus(400);
    }
  }
);
```

## Billing Events

Subscribe to billing events:

```typescript
manager.onEvent(async (event) => {
  switch (event.type) {
    case 'subscription.created':
      console.log('New subscription:', event.data);
      break;
    case 'invoice.paid':
      console.log('Invoice paid:', event.data);
      break;
    case 'payment.failed':
      console.log('Payment failed:', event.data);
      break;
  }
});
```

## Enterprise Customers

Set custom terms for enterprise customers:

```typescript
await manager.setCustomTerms(customer.id, {
  customPriceCents: 99900, // $999/month
  customIncludedRequests: 500000,
  customOveragePriceCents: 0.1, // $0.001/request
  volumeDiscountPercent: 10,
  minimumCommitmentCents: 1199800, // $11,998/year
  contractStart: new Date('2024-01-01'),
  contractEnd: new Date('2024-12-31'),
  notes: 'Annual enterprise contract',
});
```

## API Reference

### Pricing

- `getPricingTier(tier)` - Get tier configuration
- `getVisibleTiers()` - Get all visible tiers
- `getMonthlyPrice(tier, interval)` - Calculate monthly price
- `calculateOverageCharges(tier, requests)` - Calculate overage
- `isFeatureAvailable(tier, featureId)` - Check feature access
- `getFeatureLimit(tier, featureId)` - Get feature limit
- `recommendTier(monthlyRequests)` - Recommend tier for usage
- `formatPrice(cents, currency)` - Format price for display

### Usage Tracking

- `tracker.recordRequest(params)` - Record API request
- `tracker.getUsageSummary(customer)` - Get usage summary
- `tracker.getUsagePercentage(customer)` - Get usage percentage
- `tracker.isInOverage(customer)` - Check overage status
- `tracker.flush()` - Flush batched records
- `tracker.stop()` - Stop tracker

### Invoice Management

- `invoiceManager.createInvoice(customer, usage)` - Create invoice
- `invoiceManager.finalizeInvoice(id)` - Finalize invoice
- `invoiceManager.markPaid(id)` - Mark as paid
- `invoiceManager.recordPayment(id, amount)` - Record partial payment
- `invoiceManager.addCredit(id, amount, description)` - Add credit
- `invoiceManager.voidInvoice(id)` - Void invoice
- `invoiceManager.getOverdueInvoices()` - Get overdue invoices

### Subscription Management

- `manager.createCustomer(params)` - Create customer
- `manager.getCustomer(id)` - Get customer
- `manager.changeTier(id, tier)` - Change tier
- `manager.previewTierChange(id, tier)` - Preview tier change
- `manager.cancelSubscription(id)` - Cancel subscription
- `manager.reactivateSubscription(id)` - Reactivate
- `manager.createPortalSession(id, returnUrl)` - Create portal
- `manager.createCheckoutSession(params)` - Create checkout
- `manager.handleStripeWebhook(payload, signature)` - Handle webhook

## License

UNLICENSED - Private package