@dwast/verifactu-lib 0.1.0-beta.0 → 0.1.0-beta.2

package/src/core/hash/chain.ts

@@ -124,6 +124,64 @@ export function verifyRegistroAnulacion(
   return computeRegistroAnulacion(input).toLowerCase() === expectedHash.toLowerCase();
 }
 
+/**
+ * Campos de un registro de evento (RegistroEvento).
+ *
+ * Nota: el nombre `NIF` aparece DOS veces (posiciones 1 y 6): una para el
+ * sistema informático y otra para el obligado a emitir.
+ */
+export interface RegistroEventoInput {
+  /** NIF del sistema informático (NIF, posición 1). */
+  nifSistemaInformatico: string;
+  /** Identificador del evento (ID). */
+  id: string;
+  /** Identificador del sistema informático. */
+  idSistemaInformatico: string;
+  /** Versión del sistema informático. */
+  version: string;
+  /** Número de instalación. */
+  numeroInstalacion: string;
+  /** NIF del obligado a emitir (NIF, posición 6). */
+  nifObligado: string;
+  /** Tipo de evento. */
+  tipoEvento: string;
+  /** Huella (hash) del registro anterior, o null para el primero. */
+  huellaAnterior: string | null;
+  /** Fecha/hora de generación con huso horario. */
+  fechaHoraHusoGenEvento: string;
+}
+
+/**
+ * Construye la cadena canónica a hashear de un registro de evento.
+ */
+export function concatenateRegistroEvento(input: RegistroEventoInput): string {
+  return concatenateFields([
+    ['NIF', input.nifSistemaInformatico],
+    ['ID', input.id],
+    ['IdSistemaInformatico', input.idSistemaInformatico],
+    ['Version', input.version],
+    ['NumeroInstalacion', input.numeroInstalacion],
+    ['NIF', input.nifObligado],
+    ['TipoEvento', input.tipoEvento],
+    ['HuellaEvento', input.huellaAnterior],
+    ['FechaHoraHusoGenEvento', input.fechaHoraHusoGenEvento],
+  ]);
+}
+
+/**
+ * Calcula la huella (hash) de un registro de evento.
+ */
+export function computeRegistroEvento(input: RegistroEventoInput): string {
+  return sha256(concatenateRegistroEvento(input));
+}
+
+/**
+ * Verifica que el hash de un registro de evento coincide con el esperado.
+ */
+export function verifyRegistroEvento(input: RegistroEventoInput, expectedHash: string): boolean {
+  return computeRegistroEvento(input).toLowerCase() === expectedHash.toLowerCase();
+}
+
 /**
  * Cadena de hash con estado, para encadenar registros de forma secuencial.
  */
@@ -161,6 +219,16 @@ export class HashChain {
     return hash;
   }
 
+  /**
+   * Encadena un nuevo registro de evento y devuelve su huella.
+   */
+  pushEvento(input: Omit<RegistroEventoInput, 'huellaAnterior'>): string {
+    const hash = computeRegistroEvento({ ...input, huellaAnterior: this._lastHash });
+    this._lastHash = hash;
+    this._count += 1;
+    return hash;
+  }
+
   /** Reinicia la cadena. */
   reset(): void {
     this._lastHash = null;

package/src/core/index.ts

@@ -2,3 +2,5 @@ export * from './models/index.js';
 export * from './hash/index.js';
 export * from './xml/index.js';
 export * from './qr/index.js';
+export * from './validation/index.js';
+export * from './utils/index.js';

package/src/core/models/invoice.ts

@@ -51,39 +51,51 @@ export type TipoFactura =
 export type TipoDesglose = 'S1' | 'S2' | 'S3' | 'S4' | 'S5' | 'S6';
 
 /**
- * Detalle de IVA de una línea de desglose.
+ * Detalle de desglose de una línea (DetalleType del XSD de AEAT).
  */
-export interface DetalleIva {
+export interface DetalleDesglose {
+  /** Calificación de la operación (p. ej. '01'). */
+  calificacionOperacion: string;
+  /** Clave de régimen (obligatoria si Impuesto es IVA/IPSI/IGIC). */
+  claveRegimen?: string;
   /** Tipo impositivo (%). */
-  tipoImpositivo: number;
-  /** Base imponible. */
+  tipoImpositivo?: number;
+  /** Base imponible o importe no sujeto. */
   baseImponible: number;
   /** Cuota repercutida. */
-  cuotaRepercutida: number;
+  cuotaRepercutida?: number;
 }
 
 /**
- * Desglose de la operación por tipo de operación e IVA.
- */
-export interface DesgloseTipoOperacion {
-  /** Clave de tipo de operación (p. ej. '01'). */
-  tipoOperacion: string;
-  /** Detalles de IVA. */
-  detallesIva: DetalleIva[];
-}
-
-/**
- * Desglose completo de la factura.
+ * Desglose completo de la factura (DesgloseType del XSD de AEAT).
  */
 export interface Desglose {
-  /** Desglose por tipo de operación. */
-  tipoOperaciones: DesgloseTipoOperacion[];
+  /** Detalles de desglose (DetalleDesglose). */
+  detalles: DetalleDesglose[];
   /** Cuota total de la factura. */
   cuotaTotal: number;
   /** Importe total de la factura. */
   importeTotal: number;
 }
 
+/**
+ * Sistema informático que genera el registro (SistemaInformaticoType del XSD).
+ */
+export interface SistemaInformatico {
+  /** Nombre o razón social del titular. */
+  nombreRazon: string;
+  /** NIF del titular. */
+  nif: string;
+  /** Nombre del sistema informático. */
+  nombreSistemaInformatico: string;
+  /** Identificador del sistema informático. */
+  idSistemaInformatico: string;
+  /** Versión del sistema informático. */
+  version: string;
+  /** Número de instalación. */
+  numeroInstalacion: string;
+}
+
 /**
  * Factura en el modelo de datos Verifactu.
  */
@@ -100,6 +112,16 @@ export interface Invoice {
   tipoDesglose: TipoDesglose;
   /** Descripción de la operación. */
   descripcion?: string;
+  /** Destinatarios de la operación (obligatorio para F1/F3/R1-R4). */
+  destinatarios?: { nombreRazon: string; nif: string }[];
+  /** Sistema informático que genera el registro. */
+  sistemaInformatico: SistemaInformatico;
+  /** Fecha/hora de generación con huso horario (ISO 8601). */
+  fechaHoraHusoGenRegistro: string;
+  /** Huella (hash) del registro. */
+  huella: string;
+  /** Versión del esquema (por defecto '1.0'). */
+  idVersion?: string;
   /** Metadatos adicionales libres. */
   metadata?: Record<string, unknown>;
 }

package/src/core/utils/date.ts

@@ -0,0 +1,27 @@
+/**
+ * Utilidades de fecha/hora para Verifactu.
+ *
+ * AEAT exige que `FechaHoraHusoGenRegistro` sea la fecha/hora actual del
+ * sistema con su huso horario (margen de 240 segundos). Este helper genera
+ * ese valor detectando automáticamente el offset de zona, sin asumir un
+ * huso fijo (p. ej. `+02:00`).
+ */
+
+const pad = (n: number) => String(n).padStart(2, '0');
+
+/**
+ * Devuelve la fecha/hora actual en formato ISO 8601 con el offset de zona
+ * detectado automáticamente, p. ej. `2026-09-07T10:12:41+02:00`.
+ *
+ * @param date Fecha a formatear (por defecto, ahora).
+ */
+export function nowIsoWithOffset(date: Date = new Date()): string {
+  const off = -date.getTimezoneOffset();
+  const sign = off >= 0 ? '+' : '-';
+  const abs = Math.abs(off);
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+    `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}` +
+    `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`
+  );
+}

package/src/core/utils/index.ts

@@ -0,0 +1 @@
+export * from './date.js';

package/src/core/validation/index.ts

@@ -0,0 +1 @@
+export * from './validate.js';

package/src/core/validation/validate.ts

@@ -0,0 +1,71 @@
+import type { Invoice } from '../models/invoice.js';
+
+/**
+ * Resultado de la validación de una factura.
+ */
+export interface ValidationResult {
+  /** `true` si la factura es válida. */
+  valid: boolean;
+  /** Lista de errores (campos obligatorios o con formato incorrecto). */
+  errors: string[];
+}
+
+/**
+ * Valida una factura antes de enviarla a AEAT.
+ *
+ * Comprueba los campos obligatorios y el formato de las fechas (el XSD
+ * `fecha` de AEAT usa `DD-MM-YYYY`). Devuelve `{ valid, errors }`.
+ */
+export function validateInvoice(invoice: Invoice): ValidationResult {
+  const errors: string[] = [];
+
+  // Identificación de la factura.
+  if (!invoice.id?.numero) errors.push('id.numero es obligatorio');
+  if (!invoice.id?.fechaExpedicion) {
+    errors.push('id.fechaExpedicion es obligatorio');
+  } else if (!/^\d{2}-\d{2}-\d{4}$/.test(invoice.id.fechaExpedicion)) {
+    errors.push('id.fechaExpedicion debe tener formato DD-MM-YYYY');
+  }
+
+  // Emisor.
+  if (!invoice.emisor?.nif) errors.push('emisor.nif es obligatorio');
+  if (!invoice.emisor?.nombreRazon) errors.push('emisor.nombreRazon es obligatorio');
+
+  // Tipo de factura.
+  if (!invoice.tipoFactura) errors.push('tipoFactura es obligatorio');
+
+  // Desglose.
+  if (!invoice.desglose?.detalles?.length) {
+    errors.push('desglose.detalles debe tener al menos un detalle');
+  } else {
+    invoice.desglose.detalles.forEach((d, i) => {
+      if (!d.calificacionOperacion) errors.push(`desglose.detalles[${i}].calificacionOperacion es obligatorio`);
+      if (d.baseImponible === undefined || d.baseImponible === null) {
+        errors.push(`desglose.detalles[${i}].baseImponible es obligatorio`);
+      }
+      if (d.tipoImpositivo !== undefined && !d.claveRegimen) {
+        errors.push(`desglose.detalles[${i}].claveRegimen es obligatorio si hay tipoImpositivo`);
+      }
+    });
+  }
+  if (invoice.desglose?.cuotaTotal === undefined) errors.push('desglose.cuotaTotal es obligatorio');
+  if (invoice.desglose?.importeTotal === undefined) errors.push('desglose.importeTotal es obligatorio');
+
+  // Destinatarios obligatorios para F1/F3 (según AEAT).
+  if (['F1', 'F3'].includes(invoice.tipoFactura) && !invoice.destinatarios?.length) {
+    errors.push('destinatarios es obligatorio para tipoFactura F1/F3');
+  }
+
+  // Sistema informático.
+  if (!invoice.sistemaInformatico?.nif) errors.push('sistemaInformatico.nif es obligatorio');
+  if (!invoice.sistemaInformatico?.idSistemaInformatico) {
+    errors.push('sistemaInformatico.idSistemaInformatico es obligatorio');
+  }
+
+  // Fecha/hora de generación.
+  if (!invoice.fechaHoraHusoGenRegistro) {
+    errors.push('fechaHoraHusoGenRegistro es obligatorio');
+  }
+
+  return { valid: errors.length === 0, errors };
+}