feat(billing): implement billing module with Stripe and Mercado Pago integration

- Add Stripe and Mercado Pago providers for handling subscriptions.
- Create billing repository and access services for managing billing records.
- Implement webhook handlers for processing events from Stripe and Mercado Pago.
- Add routes for checkout, canceling subscriptions, and retrieving billing status.
- Introduce billing status management with appropriate state transitions.
- Create tests for billing functionalities including webhook idempotency and provider resolution.
- Document the billing module architecture, environment variables, and API endpoints.

packages/api-contract/src/billing.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+
+export const billingProviderSchema = z.enum(['STRIPE', 'MERCADOPAGO', 'PAYPAL']);
+export const billingStatusSchema = z.enum(['TRIAL', 'ACTIVE', 'PAST_DUE', 'CANCELED', 'SUSPENDED']);
+
+export const createCheckoutSchema = z.object({
+  planCode: z.string().trim().min(1).max(10),
+});
+
+export const checkoutResponseSchema = z.object({
+  checkoutUrl: z.string(),
+  subscriptionId: z.string(),
+});
+
+export const cancelSubscriptionSchema = z.object({});
+
+export const billingStatusResponseSchema = z.object({
+  complexId: z.string(),
+  status: billingStatusSchema,
+  planCode: z.string(),
+  currency: z.string(),
+  provider: billingProviderSchema.nullable(),
+  currentPeriodEnd: z.string().nullable(),
+  currentPeriodStart: z.string().nullable(),
+  trialEndsAt: z.string().nullable(),
+  canceledAt: z.string().nullable(),
+  suspendedAt: z.string().nullable(),
+});
+
+export type BillingProvider = z.infer<typeof billingProviderSchema>;
+export type BillingStatus = z.infer<typeof billingStatusSchema>;
+export type CreateCheckoutInput = z.infer<typeof createCheckoutSchema>;
+export type CheckoutResponse = z.infer<typeof checkoutResponseSchema>;
+export type BillingStatusResponse = z.infer<typeof billingStatusResponseSchema>;

packages/api-contract/src/index.ts

@@ -155,6 +155,20 @@ export {
   adminGeoCountrySchema,
   adminGeoStatsSchema,
 } from './admin';
+export {
+  billingProviderSchema,
+  billingStatusSchema,
+  billingStatusResponseSchema,
+  createCheckoutSchema,
+  checkoutResponseSchema,
+} from './billing';
+export type {
+  BillingProvider,
+  BillingStatus,
+  BillingStatusResponse,
+  CreateCheckoutInput,
+  CheckoutResponse,
+} from './billing';
 export type {
   AdminComplexListItem,
   AdminComplexStats,