Update: nueva version Horux Despachos

packages/shared/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@horux/shared",
+  "version": "0.0.1",
+  "private": true,
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  }
+}

packages/shared/src/constants/despacho-plans.ts

@@ -0,0 +1,208 @@
+export const DESPACHO_PLANS = {
+  trial: {
+    name: 'Trial',
+    maxRfcs: 3,
+    maxUsers: 1,
+    maxCfdisPorContribuyente: 1_000_000,
+    timbresIncluidosMes: 20,
+    dbMode: 'MANAGED' as const,
+    permiteServidorBackup: false,
+    features: [
+      'dashboard', 'cfdi_basic', 'iva_isr', 'reportes', 'alertas',
+      'calendario', 'conciliacion', 'documentos', 'facturacion',
+      'forecasting', 'xml_sat',
+    ],
+  },
+  mi_empresa: {
+    name: 'Mi Empresa',
+    maxRfcs: 1,
+    maxUsers: 3,
+    maxCfdisPorContribuyente: 1_000_000,
+    timbresIncluidosMes: 50,
+    dbMode: 'MANAGED' as const,
+    permiteServidorBackup: false,
+    features: [
+      'dashboard', 'cfdi_basic', 'iva_isr', 'reportes', 'alertas',
+      'calendario', 'conciliacion', 'documentos', 'facturacion',
+      'forecasting', 'xml_sat',
+    ],
+  },
+  mi_empresa_plus: {
+    name: 'Mi Empresa +',
+    maxRfcs: 1,
+    maxUsers: 3,
+    maxCfdisPorContribuyente: 1_000_000,
+    timbresIncluidosMes: 50,
+    dbMode: 'MANAGED' as const,
+    permiteServidorBackup: false,
+    features: [
+      'dashboard', 'cfdi_basic', 'iva_isr', 'reportes', 'alertas',
+      'calendario', 'conciliacion', 'documentos', 'facturacion',
+      'forecasting', 'xml_sat', 'api', 'ia_lolita',
+    ],
+  },
+  business_control: {
+    name: 'Business Control',
+    maxRfcs: 100,
+    maxUsers: -1,
+    maxCfdisPorContribuyente: 1_000_000,
+    timbresIncluidosMes: 0,
+    dbMode: 'BYO' as const,
+    permiteServidorBackup: true,
+    features: [
+      'dashboard', 'cfdi_basic', 'iva_isr', 'reportes', 'alertas',
+      'calendario', 'conciliacion', 'documentos', 'facturacion',
+      'forecasting', 'xml_sat', 'api',
+    ],
+  },
+  // Custom — gratis, sin fecha fin, solo asignable por Admin Global.
+  // Reusa el enum `custom` (legacy "precio variable" tenía 0 tenants).
+  // Comportamiento idéntico a Mi Empresa (1 RFC, MANAGED, sin API ni Lolita)
+  // pero NO se incluye en DESPACHO_PLAN_PRICES — no genera Subscription ni
+  // cobro MP. Ningún cron lo expira (sin trialEndsAt, sin currentPeriodEnd).
+  // Oculto del catálogo user-facing, visible solo en `/clientes` admin.
+  custom: {
+    name: 'Custom',
+    maxRfcs: 1,
+    maxUsers: 3,
+    maxCfdisPorContribuyente: 1_000_000,
+    timbresIncluidosMes: 50,
+    dbMode: 'MANAGED' as const,
+    permiteServidorBackup: false,
+    features: [
+      'dashboard', 'cfdi_basic', 'iva_isr', 'reportes', 'alertas',
+      'calendario', 'conciliacion', 'documentos', 'facturacion',
+      'forecasting', 'xml_sat',
+    ],
+  },
+  // Identificador interno: business_cloud (no se renombra el enum por
+  // backward compat de suscripciones existentes). Nombre display: "Enterprise".
+  business_cloud: {
+    name: 'Enterprise',
+    maxRfcs: 100,
+    maxUsers: -1,
+    maxCfdisPorContribuyente: 3_000_000,
+    timbresIncluidosMes: 0,
+    dbMode: 'BYO' as const,
+    permiteServidorBackup: true,
+    features: [
+      'dashboard', 'cfdi_basic', 'iva_isr', 'reportes', 'alertas',
+      'calendario', 'conciliacion', 'documentos', 'facturacion',
+      'forecasting', 'xml_sat', 'api',
+    ],
+  },
+} as const;
+
+export type DespachoPlan = keyof typeof DESPACHO_PLANS;
+
+/**
+ * Precios MXN (IVA incluido) para planes despacho pagables.
+ *
+ * - `monthly`: precio mensual. Solo aplica a planes con `permiteMonthly=true`
+ *   (Mi Empresa, Mi Empresa+). Para Business Control y Enterprise es null.
+ * - `firstYear` / `renewal`: precios anuales. `firstYear` es lo que se cobra
+ *   al contratar; `renewal` lo que MP cobra automáticamente en renovaciones.
+ *   Cuando ambos son iguales no hay dualidad.
+ *
+ * Política de descuento (D1, 2026-04-26): Mi Empresa y Mi Empresa+ tienen
+ * descuento del ~17% al pagar el año adelantado — el cobro anual es
+ * equivalente a 10 meses (en lugar de 12).
+ *
+ *   mi_empresa:       $580/mes  → $5,800/año (10 meses)
+ *   mi_empresa_plus:  $900/mes  → $9,000/año (10 meses)
+ */
+export const DESPACHO_PLAN_PRICES = {
+  mi_empresa: {
+    monthly: 580,
+    firstYear: 5_800,
+    renewal: 5_800,
+    permiteMonthly: true,
+  },
+  mi_empresa_plus: {
+    monthly: 900,
+    firstYear: 9_000,
+    renewal: 9_000,
+    permiteMonthly: true,
+  },
+  business_control: {
+    monthly: null,
+    firstYear: 25_850,
+    renewal: 25_850,
+    permiteMonthly: false,
+  },
+  business_cloud: { // display: Enterprise
+    monthly: null,
+    firstYear: 43_000,
+    renewal: 43_000,
+    permiteMonthly: false,
+  },
+} as const;
+
+export type DespachoPaidPlan = keyof typeof DESPACHO_PLAN_PRICES;
+export type DespachoPricePhase = 'firstYear' | 'renewal';
+export type DespachoFrequency = 'monthly' | 'annual';
+
+/**
+ * Resuelve el precio MXN para un (plan, frequency, phase). Para monthly
+ * la fase se ignora (no hay dualidad mensual). Para annual aplica
+ * firstYear o renewal según corresponda. Throws si el plan no permite
+ * la frecuencia solicitada.
+ */
+export function getPrecioDespacho(
+  plan: DespachoPaidPlan,
+  frequency: DespachoFrequency,
+  phase: DespachoPricePhase = 'renewal',
+): number {
+  const cfg = DESPACHO_PLAN_PRICES[plan];
+  if (frequency === 'monthly') {
+    if (!cfg.permiteMonthly || cfg.monthly == null) {
+      throw new Error(`El plan ${plan} no permite frecuencia mensual`);
+    }
+    return cfg.monthly;
+  }
+  return cfg[phase];
+}
+
+/** True si el plan acepta frecuencia mensual (Mi Empresa y Mi Empresa+). */
+export function permiteFrecuenciaMensual(plan: string): boolean {
+  if (plan in DESPACHO_PLAN_PRICES) {
+    return DESPACHO_PLAN_PRICES[plan as DespachoPaidPlan].permiteMonthly;
+  }
+  return false;
+}
+
+/**
+ * Costo mensual MXN por contribuyente extra que excede `maxRfcs` del
+ * plan. Solo aplica a business_control y business_cloud (Enterprise).
+ * Mi Empresa tiene límite duro de 1 RFC; no permite extras.
+ */
+export const DESPACHO_OVERAGE_PRICE_MENSUAL = 45;
+
+/** True si el plan cobra distinto en el primer año vs renovaciones (anual). */
+export function despachoPlanTieneDualidad(plan: DespachoPaidPlan): boolean {
+  const p = DESPACHO_PLAN_PRICES[plan];
+  return p.firstYear !== p.renewal;
+}
+
+export function getDespachoPlanLimits(plan: DespachoPlan) {
+  return DESPACHO_PLANS[plan];
+}
+
+export function hasDespachoFeature(plan: DespachoPlan, feature: string): boolean {
+  return (DESPACHO_PLANS[plan]?.features as readonly string[])?.includes(feature) ?? false;
+}
+
+export function isDespachoTenant(tenantRfc: string | null | undefined): boolean {
+  return typeof tenantRfc === 'string' && tenantRfc.toUpperCase().startsWith('DESPACHO_');
+}
+
+/** True si el plan es uno pagable de despacho (excluye trial). */
+export function isDespachoPaidPlan(plan: string): plan is DespachoPaidPlan {
+  return plan === 'business_control' || plan === 'business_cloud'
+      || plan === 'mi_empresa' || plan === 'mi_empresa_plus';
+}
+
+/** Planes que permiten cobrar overage por contribuyente extra. */
+export function permiteOverage(plan: string): boolean {
+  return plan === 'business_control' || plan === 'business_cloud';
+}

packages/shared/src/constants/plans.ts

@@ -0,0 +1,46 @@
+export const PLANS = {
+  starter: {
+    name: 'Starter',
+    cfdiLimit: 0,
+    usersLimit: 1,
+    features: ['dashboard', 'cfdi_basic', 'iva_isr'],
+  },
+  business: {
+    name: 'Business',
+    cfdiLimit: 50,
+    usersLimit: 3,
+    features: ['dashboard', 'cfdi_basic', 'iva_isr', 'reportes', 'alertas', 'calendario', 'conciliacion', 'forecasting', 'xml_sat', 'documentos'],
+  },
+  business_ia: {
+    name: 'Business + IA',
+    cfdiLimit: 50,
+    usersLimit: 3,
+    features: ['dashboard', 'cfdi_basic', 'iva_isr', 'reportes', 'alertas', 'calendario', 'conciliacion', 'forecasting', 'xml_sat', 'documentos', 'ia_lolita'],
+  },
+  custom: {
+    name: 'Custom',
+    cfdiLimit: 50,
+    usersLimit: 3,
+    features: ['dashboard', 'cfdi_basic', 'iva_isr', 'reportes', 'alertas', 'calendario', 'conciliacion', 'forecasting', 'xml_sat', 'documentos', 'ia_lolita'],
+  },
+  enterprise: {
+    name: 'Enterprise',
+    cfdiLimit: 100,
+    usersLimit: -1,
+    features: ['dashboard', 'cfdi_basic', 'iva_isr', 'reportes', 'alertas', 'calendario', 'conciliacion', 'forecasting', 'xml_sat', 'documentos', 'api', 'ia_lolita'],
+  },
+} as const;
+
+export type Plan = keyof typeof PLANS;
+
+export function getPlanLimits(plan: Plan) {
+  return PLANS[plan];
+}
+
+export function hasFeature(plan: Plan, feature: string): boolean {
+  // Defensive: un plan desconocido (típicamente un valor que no pertenece
+  // al catálogo Horux 360 — p.ej. un plan despacho usado por error)
+  // retorna false en vez de crashear con "Cannot read properties of undefined".
+  // El caller debe usar el catálogo correcto según la vertical del tenant.
+  return (PLANS[plan]?.features as readonly string[] | undefined)?.includes(feature) ?? false;
+}

packages/shared/src/constants/roles.ts

@@ -0,0 +1,76 @@
+import type { Role, PlatformRole } from '../types/auth';
+
+export const GLOBAL_ADMIN_RFC = 'HTS240708LJA';
+
+/** Roles que son superset (implican todos los demás platform roles). */
+const SUPERSET_ROLES: PlatformRole[] = ['platform_admin', 'platform_ti'];
+
+/**
+ * "Admin global" = staff interno de Horux 360 con rol `platform_admin` o `platform_ti`.
+ *
+ * Primero checa `platformRoles` del user (nueva fuente de verdad post-migración).
+ * Si no hay platformRoles (JWT viejo, sesión pre-deploy), cae al check legacy
+ * por RFC + rol owner del tenant HTS240708LJA.
+ *
+ * Código nuevo debería preferir `hasPlatformRoleFromArray(platformRoles, 'platform_admin')`.
+ */
+export function isGlobalAdminRfc(
+  tenantRfc: string | undefined,
+  role: string | undefined,
+  platformRoles?: PlatformRole[] | null,
+): boolean {
+  // Nueva fuente: platform_admin o platform_ti en user_platform_roles
+  if (platformRoles && SUPERSET_ROLES.some(r => platformRoles.includes(r))) return true;
+  // Fallback legacy: owner del tenant con RFC admin global
+  return role === 'owner' && tenantRfc === GLOBAL_ADMIN_RFC;
+}
+
+/** ¿El user tiene algún rol de plataforma (staff interno)? */
+export function isPlatformStaffFromRoles(platformRoles?: PlatformRole[] | null): boolean {
+  return !!platformRoles && platformRoles.length > 0;
+}
+
+/** ¿El user tiene el rol de plataforma indicado? admin y ti implican todos. */
+export function hasPlatformRoleFromArray(
+  platformRoles: PlatformRole[] | undefined | null,
+  role: PlatformRole,
+): boolean {
+  if (!platformRoles) return false;
+  if (SUPERSET_ROLES.some(r => platformRoles.includes(r))) return true;
+  return platformRoles.includes(role);
+}
+
+export const ROLES = {
+  owner: {
+    name: 'Dueño',
+    permissions: ['read', 'write', 'delete', 'manage_users', 'manage_settings'],
+  },
+  cfo: {
+    name: 'CFO',
+    permissions: ['read', 'write', 'delete', 'manage_users', 'manage_settings'],
+  },
+  contador: {
+    name: 'Contador',
+    permissions: ['read', 'write', 'resolve_alertas'],
+  },
+  auxiliar: {
+    name: 'Auxiliar',
+    permissions: ['read', 'write', 'resolve_alertas'],
+  },
+  visor: {
+    name: 'Visor',
+    permissions: ['read'],
+  },
+  supervisor: {
+    name: 'Supervisor',
+    permissions: ['read', 'write', 'resolve_alertas', 'manage_carteras'],
+  },
+  cliente: {
+    name: 'Cliente',
+    permissions: ['read'],
+  },
+} as const;
+
+export function hasPermission(role: Role, permission: string): boolean {
+  return ROLES[role].permissions.includes(permission as any);
+}

packages/shared/src/index.ts

@@ -0,0 +1,18 @@
+// Types
+export * from './types/auth';
+export * from './types/tenant';
+export * from './types/user';
+export * from './types/cfdi';
+export * from './types/dashboard';
+export * from './types/impuestos';
+export * from './types/alertas';
+export * from './types/reportes';
+export * from './types/calendario';
+export * from './types/sat';
+export * from './types/documentos';
+export * from './types/despacho';
+
+// Constants
+export * from './constants/plans';
+export * from './constants/despacho-plans';
+export * from './constants/roles';

packages/shared/src/types/alertas.ts

@@ -0,0 +1,35 @@
+export type TipoAlerta = 'vencimiento' | 'discrepancia' | 'iva_favor' | 'declaracion' | 'limite_cfdi' | 'custom';
+export type PrioridadAlerta = 'alta' | 'media' | 'baja';
+
+export interface AlertaCreate {
+  tipo: TipoAlerta;
+  titulo: string;
+  mensaje: string;
+  prioridad: PrioridadAlerta;
+  fechaVencimiento?: string;
+}
+
+export interface AlertaUpdate {
+  leida?: boolean;
+  resuelta?: boolean;
+}
+
+export interface AlertaFull {
+  id: number;
+  tipo: TipoAlerta;
+  titulo: string;
+  mensaje: string;
+  prioridad: PrioridadAlerta;
+  fechaVencimiento: string | null;
+  leida: boolean;
+  resuelta: boolean;
+  createdAt: string;
+}
+
+export interface AlertasStats {
+  total: number;
+  noLeidas: number;
+  alta: number;
+  media: number;
+  baja: number;
+}

packages/shared/src/types/auth.ts

@@ -0,0 +1,78 @@
+export interface LoginRequest {
+  email: string;
+  password: string;
+}
+
+export interface LoginResponse {
+  accessToken: string;
+  refreshToken: string;
+  user: UserInfo;
+}
+
+export interface RegisterRequest {
+  empresa: {
+    nombre: string;
+    rfc: string;
+  };
+  usuario: {
+    nombre: string;
+    email: string;
+    password: string;
+  };
+}
+
+export interface TenantMembership {
+  id: string;
+  nombre: string;
+  rfc: string;
+  plan: string;
+  role: Role;
+  isOwner: boolean;
+}
+
+export interface UserInfo {
+  id: string;
+  email: string;
+  nombre: string;
+  /** Rol en el tenant ACTIVO (el que resolvió el JWT). */
+  role: Role;
+  /** Tenant activo (el que resolvió el JWT). */
+  tenantId: string;
+  tenantName: string;
+  tenantRfc: string;
+  plan: string;
+  platformRoles?: PlatformRole[];
+  /**
+   * Todos los tenants a los que pertenece este user. Si len > 1, la UI muestra
+   * el tenant switcher. Derivado de la tabla tenant_memberships (active=true).
+   */
+  tenants?: TenantMembership[];
+}
+
+export interface JWTPayload {
+  userId: string;
+  email: string;
+  role: Role;
+  tenantId: string;
+  platformRoles?: PlatformRole[];
+  /**
+   * Version del user al emitir el JWT. Si el user incrementa su tokenVersion
+   * (cambio de password, logout-all), todos los JWT con version menor dejan
+   * de validar. Default 0 para compat con JWT emitidos antes del rollout.
+   */
+  tokenVersion?: number;
+  iat?: number;
+  exp?: number;
+}
+
+export type Role = 'owner' | 'cfo' | 'contador' | 'auxiliar' | 'visor' | 'supervisor' | 'cliente';
+
+/**
+ * Roles de plataforma (staff interno de Horux 360). Ortogonal al `Role` per-tenant.
+ * Un user puede tener 0, 1 o varios.
+ *
+ * Superset roles (implican todos los otros):
+ *   - `platform_admin` — admin global
+ *   - `platform_ti` — equipo de TI, mismos permisos que admin. Diferencia semántica para trazabilidad.
+ */
+export type PlatformRole = 'platform_admin' | 'platform_ti' | 'platform_support' | 'platform_sales' | 'platform_finance';

packages/shared/src/types/calendario.ts

@@ -0,0 +1,37 @@
+export type TipoEvento = 'declaracion' | 'pago' | 'obligacion' | 'informativa' | 'custom' | 'tarea';
+export type Recurrencia = 'mensual' | 'bimestral' | 'trimestral' | 'anual' | 'unica';
+
+export interface EventoFiscal {
+  id?: number;
+  titulo: string;
+  descripcion: string;
+  tipo: TipoEvento;
+  fechaLimite: string;
+  recurrencia: Recurrencia | string;
+  completado: boolean;
+  notas?: string | null;
+  createdAt?: string;
+}
+
+export interface EventoCreate {
+  titulo: string;
+  descripcion: string;
+  tipo: TipoEvento;
+  fechaLimite: string;
+  recurrencia: Recurrencia;
+  notas?: string;
+}
+
+export interface EventoUpdate {
+  titulo?: string;
+  descripcion?: string;
+  fechaLimite?: string;
+  completado?: boolean;
+  notas?: string;
+}
+
+export interface CalendarioMes {
+  año: number;
+  mes: number;
+  eventos: EventoFiscal[];
+}

packages/shared/src/types/cfdi.ts

@@ -0,0 +1,176 @@
+export type TipoCfdi = 'EMITIDO' | 'RECIBIDO';
+export type TipoComprobante = 'I' | 'E' | 'T' | 'P' | 'N';
+export type EstadoCfdi = 'Vigente' | 'Cancelado' | '0' | '1';
+
+export interface Cfdi {
+  id: number;
+  year: string | null;
+  month: string | null;
+  type: TipoCfdi;
+  uuid: string;
+  serie: string | null;
+  folio: string | null;
+  status: EstadoCfdi;
+  fechaEmision: string;
+  rfcEmisor: string;
+  nombreEmisor: string;
+  rfcReceptor: string;
+  nombreReceptor: string;
+  subtotal: number;
+  subtotalMxn: number;
+  descuento: number;
+  descuentoMxn: number;
+  total: number;
+  totalMxn: number;
+  saldoInsoluto: string | null;
+  moneda: string;
+  tipoCambio: number;
+  tipoComprobante: string | null;
+  metodoPago: string | null;
+  formaPago: string | null;
+  usoCfdi: string | null;
+  pac: string | null;
+  fechaCertSat: string | null;
+  fechaCancelacion: string | null;
+  uuidRelacionado: string | null;
+  // Impuestos del comprobante
+  isrRetencion: number;
+  isrRetencionMxn: number;
+  ivaTraslado: number;
+  ivaTrasladoMxn: number;
+  ivaRetencion: number;
+  ivaRetencionMxn: number;
+  iepsTraslado: number;
+  iepsTrasladoMxn: number;
+  iepsRetencion: number;
+  iepsRetencionMxn: number;
+  impuestosLocalesTrasladado: number;
+  impuestosLocalesTrasladoMxn: number;
+  impuestosLocalesRetenidos: number;
+  impuestosLocalesRetenidosMxn: number;
+  // Complemento de pagos
+  montoPago: number;
+  montoPagoMxn: number;
+  fechaPagoP: string | null;
+  numParcialidad: string | null;
+  isrRetencionPago: number;
+  isrRetencionPagoMxn: number;
+  ivaTrasladoPago: number;
+  ivaTrasladoPagoMxn: number;
+  ivaRetencionPago: number;
+  ivaRetencionPagoMxn: number;
+  iepsTrasladoPago: number;
+  iepsTrasladoPagoMxn: number;
+  iepsRetencionPago: number;
+  iepsRetencionPagoMxn: number;
+  saldoPendiente: number;
+  saldoPendienteMxn: number;
+  fechaLiquidacion: string | null;
+  fechaPago: string | null;
+  fechaInicialPago: string | null;
+  fechaFinalPago: string | null;
+  numDiasPagados: number;
+  // Nómina
+  numSeguroSocial: string | null;
+  puesto: string | null;
+  salarioBaseCotApor: number;
+  salarioBaseCotAporMxn: number;
+  salarioDiarioIntegrado: number;
+  salarioDiarioIntegradoMxn: number;
+  totalPercepciones: number;
+  totalPercepcionesMxn: number;
+  totalDeducciones: number;
+  totalDeduccionesMxn: number;
+  impRetenidosNomina: number;
+  impRetenidosNominaMxn: number;
+  otrasDeduccionesNomina: number;
+  otrasDeduccionesNominaMxn: number;
+  subsidioCausado: number;
+  subsidioCausadoMxn: number;
+  // Conciliación
+  conciliado: string | null;
+  // Régimen fiscal
+  regimenFiscalEmisor: string | null;
+  regimenFiscalReceptor: string | null;
+  // FK a tabla rfcs
+  rfcEmisorId: number | null;
+  rfcReceptorId: number | null;
+  // Archivos y sync
+  xmlUrl: string | null;
+  pdfUrl: string | null;
+  xmlOriginal: string | null;
+  cfdiTipoRelacion: string | null;
+  cfdisRelacionados: string | null;
+  lastSatSync: string | null;
+  satSyncJobId: string | null;
+  source: string | null;
+  facturapiId: string | null;
+  contribuyenteId: string | null;
+  creadoEn: string;
+  actualizadoEn: string;
+}
+
+export interface CfdiFilters {
+  tipo?: TipoCfdi;
+  tipoComprobante?: TipoComprobante;
+  estado?: EstadoCfdi;
+  fechaInicio?: string;
+  fechaFin?: string;
+  rfc?: string;
+  emisor?: string;
+  receptor?: string;
+  search?: string;
+  contribuyenteId?: string;
+  page?: number;
+  limit?: number;
+}
+
+export interface CfdiConcepto {
+  id: number;
+  cfdiId: number;
+  claveProdServ: string | null;
+  noIdentificacion: string | null;
+  descripcion: string;
+  cantidad: number;
+  claveUnidad: string | null;
+  unidad: string | null;
+  valorUnitario: number;
+  valorUnitarioMxn: number;
+  importe: number;
+  importeMxn: number;
+  descuento: number;
+  descuentoMxn: number;
+  isrRetencion: number;
+  isrRetencionMxn: number;
+  ivaTraslado: number;
+  ivaTrasladoMxn: number;
+  ivaRetencion: number;
+  ivaRetencionMxn: number;
+  iepsTraslado: number;
+  iepsTrasladoMxn: number;
+  iepsRetencion: number;
+  iepsRetencionMxn: number;
+  impuestosLocalesTrasladado: number;
+  impuestosLocalesTrasladoMxn: number;
+  impuestosLocalesRetenidos: number;
+  impuestosLocalesRetenidosMxn: number;
+  totalPercepciones: number;
+  totalPercepcionesMxn: number;
+  totalDeducciones: number;
+  totalDeduccionesMxn: number;
+  impRetenidosNomina: number;
+  impRetenidosNominaMxn: number;
+  otrasDeduccionesNomina: number;
+  otrasDeduccionesNominaMxn: number;
+  subsidioCausado: number;
+  subsidioCausadoMxn: number;
+  creadoEn: string;
+}
+
+export interface CfdiListResponse {
+  data: Cfdi[];
+  total: number;
+  page: number;
+  limit: number;
+  totalPages: number;
+}

packages/shared/src/types/dashboard.ts

@@ -0,0 +1,73 @@
+export interface IngresoRegimen {
+  regimenClave: string;
+  regimenDescripcion: string;
+  monto: number;
+}
+
+export interface EgresoRegimen {
+  regimenClave: string;
+  regimenDescripcion: string;
+  monto: number;
+}
+
+export interface IvaBalanceRegimen {
+  regimenClave: string;
+  regimenDescripcion: string;
+  monto: number;
+}
+
+export interface KpiData {
+  ingresos: number;
+  ingresosPorRegimen: IngresoRegimen[];
+  egresos: number;
+  egresosPorRegimen: EgresoRegimen[];
+  adquisicionMercancias: number;
+  adquisicionMercanciasPorRegimen?: { regimenClave: string; monto: number }[];
+  utilidad: number;
+  margen: number;
+  ivaBalance: number;
+  ivaBalancePorRegimen: IvaBalanceRegimen[];
+  ivaAFavorAcumulado: number;
+  ivaAFavorHistorico: number;
+  cfdisEmitidos: number;
+  cfdisEmitidosPorRegimen: { regimen: string; total: number }[];
+  cfdisRecibidos: number;
+  cfdisRecibidosPorRegimen: { regimen: string; total: number }[];
+}
+
+export interface IngresosEgresosData {
+  mes: string;
+  ingresos: number;
+  egresos: number;
+}
+
+export interface ResumenFiscal {
+  ivaPorPagar: number;
+  ivaAFavor: number;
+  isrPorPagar: number;
+  declaracionesPendientes: number;
+  proximaObligacion: {
+    titulo: string;
+    fecha: string;
+  } | null;
+}
+
+export interface Alerta {
+  id: number;
+  tipo: 'vencimiento' | 'discrepancia' | 'iva_favor' | 'declaracion';
+  titulo: string;
+  mensaje: string;
+  prioridad: 'alta' | 'media' | 'baja';
+  fechaVencimiento: string | null;
+  leida: boolean;
+  resuelta: boolean;
+  createdAt: string;
+}
+
+export type PeriodoFiltro = 'semana' | 'mes' | 'trimestre' | 'año' | 'custom';
+
+export interface DashboardFilters {
+  periodo: PeriodoFiltro;
+  fechaInicio?: string;
+  fechaFin?: string;
+}

packages/shared/src/types/despacho.ts

@@ -0,0 +1,42 @@
+export type DespachoRole = 'owner' | 'supervisor' | 'auxiliar' | 'cliente';
+
+export type VerticalProfile = 'CONTABLE' | 'JURIDICO' | 'ARQUITECTURA';
+
+export type DbMode = 'BYO' | 'MANAGED';
+
+export interface DespachoInfo {
+  id: string;
+  nombre: string;
+  rfc: string;
+  verticalProfile: VerticalProfile;
+  dbMode: DbMode | null;
+  plan: string;
+}
+
+export type DespachoSignupPlan = 'trial' | 'business_control' | 'business_cloud';
+
+export interface DespachoSignupRequest {
+  despacho: {
+    nombre: string;
+    rfc?: string;
+    regimenFiscal?: string;
+    codigoPostal?: string;
+    verticalProfile: VerticalProfile;
+    plan?: DespachoSignupPlan;
+  };
+  owner: {
+    nombre: string;
+    email: string;
+    password: string;
+  };
+}
+
+export interface ContribuyenteInfo {
+  id: string;
+  rfc: string;
+  razonSocial: string;
+  regimenFiscal: string;
+  codigoPostal?: string;
+  supervisorUserId?: string;
+  active: boolean;
+}

packages/shared/src/types/documentos.ts

@@ -0,0 +1,14 @@
+export interface OpinionCumplimiento {
+  id: number;
+  rfc: string;
+  razonSocial: string;
+  estatus: string;
+  folio: string;
+  cadenaOriginal: string;
+  fechaConsulta: string;
+  createdAt: string;
+}
+
+export interface OpinionCumplimientoFull extends OpinionCumplimiento {
+  pdf: Buffer;
+}

packages/shared/src/types/impuestos.ts

@@ -0,0 +1,100 @@
+export type EstadoDeclaracion = 'pendiente' | 'declarado' | 'acreditado';
+
+export interface IvaMensual {
+  id: number;
+  año: number;
+  mes: number;
+  ivaTrasladado: number;
+  ivaAcreditable: number;
+  ivaRetenido: number;
+  resultado: number;
+  acumulado: number;
+  estado: EstadoDeclaracion;
+  fechaDeclaracion: string | null;
+}
+
+export interface IsrMensual {
+  id: number;
+  año: number;
+  mes: number;
+  ingresosAcumulados: number; // mensual — naming legacy, no se renombra en este spec
+  deducciones: number;        // mensual
+  baseGravable: number;       // mensual — sigue retornándose para no romper consumidores externos, pero ya no se muestra en la UI
+  // Nuevos: running totals desde enero hasta el mes de esta fila
+  ingresosAcum: number;
+  deduccionesAcum: number;
+  baseGravableAcum: number;   // sin clamp; puede ser negativo
+  isrCausado: number;
+  isrRetenido: number;
+  isrAPagar: number;
+  estado: EstadoDeclaracion;
+  fechaDeclaracion: string | null;
+}
+
+export interface IvaRegimenDetalle {
+  regimenClave: string;
+  regimenDescripcion: string;
+  monto: number;
+}
+
+export interface ResumenIva {
+  trasladado: number;
+  trasladadoPorRegimen: IvaRegimenDetalle[];
+  acreditable: number;
+  acreditablePorRegimen: IvaRegimenDetalle[];
+  retenido: number;
+  retenidoPorRegimen: IvaRegimenDetalle[];
+  resultado: number;
+  acumuladoAnual: number;
+}
+
+export interface IsrRegimenDetalle {
+  regimenClave: string;
+  regimenDescripcion: string;
+  monto: number;
+}
+
+export interface BaseGravableRegimen {
+  regimenClave: string;
+  regimenDescripcion: string;
+  ingresos: number;
+  deducciones: number;
+  baseGravable: number;
+  isrCausado: number;
+  formula: 'ingresos' | 'ingresos-deducciones';
+}
+
+export interface ResumenIsr {
+  ingresosAcumulados: number;
+  ingresosPorRegimen: IsrRegimenDetalle[];
+  deducciones: number;
+  deduccionesPorRegimen: IsrRegimenDetalle[];
+  baseGravable: number;
+  baseGravablePorRegimen: BaseGravableRegimen[];
+  isrCausado: number;
+  isrRetenido: number;
+  isrAPagar: number;
+}
+
+/**
+ * Desglose del cálculo provisional ISR del mes final del filtro:
+ *   delPeriodo  = solo el mes final del filtro (1 mes)
+ *   anteriores  = enero hasta el mes anterior al final (puede estar vacío)
+ *   total       = enero hasta el mes final inclusive
+ *
+ * Reglas:
+ * - delPeriodo + anteriores = total para campos aditivos (ingresos, deducciones, retenciones).
+ * - Para baseGravable e isrCausado el total se calcula sobre el rango entero
+ *   (no es la suma algebraica de delPeriodo + anteriores).
+ * - baseGravable puede ser negativa en cualquiera de los tres rangos.
+ * - isrCausado se clampa a 0 cuando la baseGravable acumulada es negativa.
+ */
+export interface ResumenIsrDesglosado {
+  delPeriodo: ResumenIsr;
+  anteriores: ResumenIsr;
+  total: ResumenIsr;
+  /** Mes final del filtro (1-12) */
+  mesFinal: number;
+  /** Año fiscal del filtro */
+  anio: number;
+}

packages/shared/src/types/reportes.ts

@@ -0,0 +1,46 @@
+export interface EstadoResultados {
+  periodo: { inicio: string; fin: string };
+  ingresos: { concepto: string; monto: number }[];
+  egresos: { concepto: string; monto: number }[];
+  totalIngresos: number;
+  totalEgresos: number;
+  utilidadBruta: number;
+  impuestos: number;
+  utilidadNeta: number;
+}
+
+export interface FlujoEfectivo {
+  periodo: { inicio: string; fin: string };
+  saldoInicial: number;
+  entradas: { concepto: string; monto: number }[];
+  salidas: { concepto: string; monto: number }[];
+  totalEntradas: number;
+  totalSalidas: number;
+  flujoNeto: number;
+  saldoFinal: number;
+}
+
+export interface ComparativoPeriodos {
+  periodos: string[];
+  ingresos: number[];
+  egresos: number[];
+  utilidad: number[];
+  variacionIngresos: number;
+  variacionEgresos: number;
+  variacionUtilidad: number;
+}
+
+export interface ConcentradoRfc {
+  rfc: string;
+  nombre: string;
+  tipo: 'cliente' | 'proveedor';
+  totalFacturado: number;
+  totalIva: number;
+  cantidadCfdis: number;
+}
+
+export interface ReporteFilters {
+  fechaInicio: string;
+  fechaFin: string;
+  tipo?: 'mensual' | 'trimestral' | 'anual';
+}

packages/shared/src/types/sat.ts

@@ -0,0 +1,132 @@
+// ============================================
+// FIEL (e.firma) Types
+// ============================================
+
+export interface FielUploadRequest {
+  cerFile: string;  // Base64
+  keyFile: string;  // Base64
+  password: string;
+}
+
+export interface FielStatus {
+  configured: boolean;
+  rfc?: string;
+  serialNumber?: string;
+  validFrom?: string;
+  validUntil?: string;
+  isExpired?: boolean;
+  daysUntilExpiration?: number;
+}
+
+// ============================================
+// SAT Sync Types
+// ============================================
+
+export type SatSyncType = 'initial' | 'daily' | 'incremental';
+export type SatSyncStatus = 'pending' | 'running' | 'completed' | 'failed';
+export type CfdiSyncType = 'emitidos' | 'recibidos';
+
+export interface SatSyncJob {
+  id: string;
+  tenantId: string;
+  type: SatSyncType;
+  status: SatSyncStatus;
+  dateFrom: string;
+  dateTo: string;
+  cfdiType?: CfdiSyncType;
+  satRequestId?: string;
+  satPackageIds: string[];
+  cfdisFound: number;
+  cfdisDownloaded: number;
+  cfdisInserted: number;
+  cfdisUpdated: number;
+  progressPercent: number;
+  errorMessage?: string;
+  startedAt?: string;
+  completedAt?: string;
+  createdAt: string;
+  retryCount: number;
+}
+
+export interface SatSyncStatusResponse {
+  hasActiveSync: boolean;
+  currentJob?: SatSyncJob;
+  lastCompletedJob?: SatSyncJob;
+  totalCfdisSynced: number;
+}
+
+export interface SatSyncHistoryResponse {
+  jobs: SatSyncJob[];
+  total: number;
+  page: number;
+  limit: number;
+}
+
+export interface StartSyncRequest {
+  type?: SatSyncType;
+  dateFrom?: string;
+  dateTo?: string;
+}
+
+export interface StartSyncResponse {
+  jobId: string;
+  message: string;
+}
+
+// ============================================
+// SAT Web Service Types
+// ============================================
+
+export interface SatAuthResponse {
+  token: string;
+  expiresAt: Date;
+}
+
+export interface SatDownloadRequest {
+  rfcSolicitante: string;
+  fechaInicio: Date;
+  fechaFin: Date;
+  tipoSolicitud: 'CFDI' | 'Metadata';
+  tipoComprobante?: 'I' | 'E' | 'T' | 'N' | 'P';
+  rfcEmisor?: string;
+  rfcReceptor?: string;
+}
+
+export interface SatDownloadRequestResponse {
+  idSolicitud: string;
+  codEstatus: string;
+  mensaje: string;
+}
+
+export interface SatVerifyResponse {
+  codEstatus: string;
+  estadoSolicitud: number;  // 1=Aceptada, 2=EnProceso, 3=Terminada, 4=Error, 5=Rechazada, 6=Vencida
+  codigoEstadoSolicitud: string;
+  numeroCfdis: number;
+  mensaje: string;
+  paquetes: string[];
+}
+
+export interface SatPackageResponse {
+  paquete: string;  // Base64 ZIP
+}
+
+// ============================================
+// SAT Error Codes
+// ============================================
+
+export const SAT_STATUS_CODES: Record<string, string> = {
+  '5000': 'Solicitud recibida con éxito',
+  '5002': 'Se agotó el límite de solicitudes',
+  '5004': 'No se encontraron CFDIs',
+  '5005': 'Solicitud duplicada',
+};
+
+export const SAT_REQUEST_STATUS: Record<number, string> = {
+  1: 'Aceptada',
+  2: 'En proceso',
+  3: 'Terminada',
+  4: 'Error',
+  5: 'Rechazada',
+  6: 'Vencida',
+};

packages/shared/src/types/tenant.ts

@@ -0,0 +1,48 @@
+import type { Plan } from '../constants/plans';
+
+export interface Tenant {
+  id: string;
+  nombre: string;
+  rfc: string;
+  plan: Plan;
+  databaseName: string;
+  cfdiLimit: number;
+  usersLimit: number;
+  active: boolean;
+  createdAt: Date;
+  expiresAt: Date | null;
+}
+
+export interface TenantUsage {
+  cfdiCount: number;
+  cfdiLimit: number;
+  usersCount: number;
+  usersLimit: number;
+  plan: Plan;
+}
+
+export interface Subscription {
+  id: string;
+  tenantId: string;
+  plan: Plan;
+  mpPreapprovalId?: string;
+  status: 'pending' | 'authorized' | 'paused' | 'cancelled';
+  amount: number;
+  frequency: 'monthly' | 'yearly';
+  currentPeriodStart?: string;
+  currentPeriodEnd?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Payment {
+  id: string;
+  tenantId: string;
+  subscriptionId?: string;
+  mpPaymentId?: string;
+  amount: number;
+  status: 'approved' | 'pending' | 'rejected' | 'refunded';
+  paymentMethod?: string;
+  paidAt?: string;
+  createdAt: string;
+}

packages/shared/src/types/user.ts

@@ -0,0 +1,61 @@
+import type { Role } from './auth';
+
+export interface User {
+  id: string;
+  tenantId: string;
+  email: string;
+  nombre: string;
+  role: Role;
+  active: boolean;
+  lastLogin: Date | null;
+  createdAt: Date;
+}
+
+export interface CreateUserRequest {
+  email: string;
+  nombre: string;
+  role: Role;
+  password: string;
+}
+
+export interface UpdateUserRequest {
+  nombre?: string;
+  role?: Role;
+  active?: boolean;
+}
+
+export interface UserInvite {
+  email: string;
+  nombre: string;
+  role: 'contador' | 'visor' | 'auxiliar' | 'supervisor' | 'cliente';
+  supervisorUserId?: string;
+}
+
+export interface UserListItem {
+  id: string;
+  email: string;
+  nombre: string;
+  role: Role;
+  active: boolean;
+  lastLogin: string | null;
+  createdAt: string;
+  tenantId?: string;
+  tenantName?: string;
+}
+
+export interface UserUpdate {
+  nombre?: string;
+  role?: Role;
+  active?: boolean;
+  tenantId?: string;
+}
+
+export interface AuditLog {
+  id: number;
+  userId: string;
+  userName: string;
+  action: string;
+  details: string;
+  ip: string;
+  createdAt: string;
+}

packages/shared/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}