workspace-v1/shared/modules/billing/README.md

Billing - Core Module

Modulo: shared/modules/billing/ Version: 0.1.0 Fecha: 2026-01-03 Owner: Backend-Agent Estado: desarrollo

---

Descripcion

Modulo de facturacion compartido que provee logica de negocio para planes, pricing, invoices y metricas de uso. Trabaja en conjunto con el modulo de payments para la parte transaccional.

---

Instalacion

Prerequisitos

# El modulo de billing depende de payments
npm install stripe

Configuracion de Paths

{
  "compilerOptions": {
    "paths": {
      "@shared/modules/*": ["../../shared/modules/*"]
    }
  }
}

---

API Publica (Planificada)

Servicios

Servicio	Descripcion
PlanService	Gestion de planes y pricing
InvoiceService	Generacion y gestion de facturas
UsageService	Tracking de metricas de uso
QuotaService	Verificacion de limites y cuotas

Tipos

interface Plan {
  id: string;
  name: string;
  description: string;
  price: number;
  currency: string;
  interval: 'monthly' | 'yearly';
  features: PlanFeature[];
  limits: PlanLimits;
  isActive: boolean;
}

interface PlanLimits {
  users: number;
  storage: number;  // GB
  apiCalls: number; // per month
  projects: number;
}

interface Invoice {
  id: string;
  customerId: string;
  subscriptionId: string;
  amount: number;
  currency: string;
  status: 'draft' | 'open' | 'paid' | 'void';
  dueDate: Date;
  paidAt?: Date;
  lineItems: InvoiceLineItem[];
}

interface UsageRecord {
  subscriptionId: string;
  metric: string;
  quantity: number;
  timestamp: Date;
}

---

Ejemplos de Uso

Ejemplo 1: Verificar Cuota

import { QuotaService } from '@shared/modules/billing';

@Injectable()
export class ProjectService {
  constructor(private quota: QuotaService) {}

  async createProject(orgId: string, data: CreateProjectDto) {
    // Verificar si la organizacion puede crear mas proyectos
    const canCreate = await this.quota.check(orgId, 'projects', 1);

    if (!canCreate) {
      throw new QuotaExceededException('Project limit reached');
    }

    // Crear proyecto...
    const project = await this.projectRepo.save(data);

    // Incrementar uso
    await this.quota.increment(orgId, 'projects', 1);

    return project;
  }
}

Ejemplo 2: Obtener Plan Actual

import { PlanService, UsageService } from '@shared/modules/billing';

@Controller('billing')
export class BillingController {
  constructor(
    private plans: PlanService,
    private usage: UsageService,
  ) {}

  @Get('current-plan')
  async getCurrentPlan(@CurrentOrg() orgId: string) {
    const subscription = await this.plans.getActiveSubscription(orgId);
    const plan = await this.plans.getPlan(subscription.planId);
    const usage = await this.usage.getCurrentPeriodUsage(subscription.id);

    return {
      plan,
      subscription,
      usage,
      limits: plan.limits,
    };
  }
}

---

Dependencias

Internas

Modulo	Uso
@shared/modules/payments	Transacciones
@shared/modules/utils	Formateo

Externas (npm)

Paquete	Version	Uso
stripe	^14.0	Billing API

---

Estado Actual

- [ ] PlanService
- [ ] InvoiceService
- [ ] UsageService
- [ ] QuotaService
- [ ] Integracion con payments
- [ ] Metricas de uso
- [ ] Tests unitarios

---

Changelog

v0.1.0 (2026-01-03)

• Estructura inicial
• README con planificacion

---

Modulo: shared/modules/billing/ | Owner: Backend-Agent