Eve library

@veritas/billing

Other

Revision 1

On this page

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