@dwast/verifactu-lib 0.1.0-beta.0

package/src/integration/repository.ts

@@ -0,0 +1,86 @@
+import type { Invoice } from '../core/models/invoice.js';
+import type { Event } from '../core/models/event.js';
+
+/**
+ * Estado de un registro de facturación en el sistema consumidor.
+ */
+export type RecordStatus =
+  | 'PENDING' // generado pero no enviado a AEAT
+  | 'SENT' // enviado a AEAT, pendiente de confirmación
+  | 'CONFIRMED' // confirmado por AEAT
+  | 'REJECTED' // rechazado por AEAT
+  | 'ANNULLED'; // anulado
+
+/**
+ * Registro de facturación persistido en el sistema consumidor.
+ */
+export interface StoredRecord {
+  /** Identificador interno del registro. */
+  id: string;
+  /** Referencia a la factura (serie + número). */
+  invoiceId: string;
+  /** XML Verifactu generado. */
+  xml: string;
+  /** Hash del propio registro (huella). */
+  hash: string;
+  /** Hash del registro anterior en la cadena. */
+  previousHash: string | null;
+  /** Payload del QR Verifactu (URL de verificación con el hash). */
+  qrPayload?: string;
+  /** Estado del registro. */
+  status: RecordStatus;
+  /** Fecha/hora de creación. */
+  createdAt: string;
+  /** Fecha/hora de última actualización. */
+  updatedAt: string;
+}
+
+/**
+ * Respuesta de AEAT persistida en el sistema consumidor.
+ *
+ * La AEAT exige conservar la respuesta de cada envío para poder acreditar
+ * la remisión. El sistema consumidor DEBE guardar estas respuestas en una
+ * tabla (ver `schema.sql`).
+ */
+export interface StoredResponse {
+  /** Identificador interno de la respuesta. */
+  id: string;
+  /** Referencia al registro enviado. */
+  recordId: string;
+  /** Identificador de la operación devuelto por AEAT. */
+  operationId: string;
+  /** Estado devuelto por AEAT. */
+  status: 'OK' | 'ERROR';
+  /** Mensaje de AEAT. */
+  message?: string;
+  /** Código de error de AEAT (si lo hay). */
+  errorCode?: string;
+  /** Cuerpo completo de la respuesta (para auditoría). */
+  rawResponse?: string;
+  /** Fecha/hora de la respuesta. */
+  receivedAt: string;
+}
+
+/**
+ * Repositorio que el sistema consumidor DEBE implementar para persistir
+ * los registros y las respuestas de Verifactu.
+ *
+ * La librería no impone un ORM concreto (Mongoose, Prisma, etc.): define
+ * esta interfaz y el sistema consumidor la adapta a su stack MERN.
+ */
+export interface VerifactuRepository {
+  /** Guarda un registro de facturación. */
+  saveRecord(record: StoredRecord): Promise<void>;
+  /** Actualiza el estado de un registro. */
+  updateRecordStatus(id: string, status: RecordStatus): Promise<void>;
+  /** Obtiene un registro por su id. */
+  getRecord(id: string): Promise<StoredRecord | null>;
+  /** Obtiene el último registro (para conocer el hash anterior). */
+  getLastRecord(): Promise<StoredRecord | null>;
+  /** Guarda la respuesta de AEAT. */
+  saveResponse(response: StoredResponse): Promise<void>;
+  /** Obtiene las respuestas de un registro. */
+  getResponses(recordId: string): Promise<StoredResponse[]>;
+  /** Guarda un evento. */
+  saveEvent(event: Event): Promise<void>;
+}

package/src/integration/schema.sql

@@ -0,0 +1,51 @@
+-- ============================================================================
+-- Esquema de persistencia para Verifactu
+-- ----------------------------------------------------------------------------
+-- El sistema consumidor DEBE disponer de estas tablas para cumplir con la
+-- obligación de conservar los registros y las respuestas de AEAT.
+--
+-- Esquema relacional de referencia (PostgreSQL/MySQL). Si el sistema usa
+-- MongoDB, adaptar a colecciones equivalentes (ver repository.ts).
+-- ============================================================================
+
+-- Registros de facturación (cada factura/evento generado en formato Verifactu)
+CREATE TABLE IF NOT EXISTS verifactu_records (
+    id            VARCHAR(64)  PRIMARY KEY,
+    invoice_id    VARCHAR(128) NOT NULL,          -- serie + número de factura
+    xml           TEXT         NOT NULL,          -- XML Verifactu generado
+    hash          VARCHAR(64)  NOT NULL,          -- huella (SHA-256) del registro
+    previous_hash VARCHAR(64),                    -- hash del registro anterior
+    status        VARCHAR(16)  NOT NULL DEFAULT 'PENDING',
+    created_at    TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at    TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Respuestas de AEAT (obligatorio conservarlas para acreditar la remisión)
+CREATE TABLE IF NOT EXISTS verifactu_responses (
+    id            VARCHAR(64)  PRIMARY KEY,
+    record_id     VARCHAR(64)  NOT NULL REFERENCES verifactu_records(id),
+    operation_id  VARCHAR(128) NOT NULL,          -- id de operación devuelto por AEAT
+    status        VARCHAR(8)   NOT NULL,           -- OK | ERROR
+    message       TEXT,
+    error_code    VARCHAR(16),
+    raw_response  TEXT,                            -- cuerpo completo (auditoría)
+    received_at   TIMESTAMP   NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Eventos (alta, anulación, modificación, eventos del sistema)
+CREATE TABLE IF NOT EXISTS verifactu_events (
+    id            VARCHAR(64)  PRIMARY KEY,
+    type          VARCHAR(16)  NOT NULL,           -- ALTA | ANULACION | MODIFICACION
+    fecha_hora    TIMESTAMP    NOT NULL,
+    invoice_id    VARCHAR(128),
+    motivo        TEXT,
+    factura_anulada VARCHAR(128),
+    hash          VARCHAR(64),
+    previous_hash VARCHAR(64),
+    created_at    TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Índices recomendados
+CREATE INDEX IF NOT EXISTS idx_records_invoice   ON verifactu_records (invoice_id);
+CREATE INDEX IF NOT EXISTS idx_responses_record  ON verifactu_responses (record_id);
+CREATE INDEX IF NOT EXISTS idx_events_invoice    ON verifactu_events (invoice_id);

package/src/integration/service.ts

@@ -0,0 +1,158 @@
+import type { Invoice } from '../core/models/invoice.js';
+import { generateInvoiceXml, generateAnulacionXml } from '../core/xml/generator.js';
+import { computeRegistroAlta, computeRegistroAnulacion } from '../core/hash/chain.js';
+import { buildQrPayload } from '../core/qr/qr.js';
+import type { VerifactuClient } from '../aeat/client.js';
+import type { VerifactuRepository, StoredRecord } from './repository.js';
+
+/**
+ * Servicio de orquestación de Verifactu.
+ *
+ * Une el núcleo puro (generación XML + hash) con el cliente AEAT y la
+ * persistencia. El sistema consumidor DEBE proporcionar un repositorio que
+ * implemente `VerifactuRepository` (ver `repository.ts` y `schema.sql`).
+ */
+export class VerifactuService {
+  constructor(
+    private readonly repository: VerifactuRepository,
+    private readonly client: VerifactuClient,
+  ) {}
+
+  /**
+   * Registra una factura: genera el XML, calcula el hash encadenado, guarda
+   * el registro y lo envía a AEAT, persistiendo la respuesta.
+   */
+  async registerInvoice(invoice: Invoice): Promise<StoredRecord> {
+    // 1. Obtener el hash del último registro para encadenar.
+    const last = await this.repository.getLastRecord();
+    const previousHash = last?.hash ?? null;
+
+    // 2. Generar XML y calcular la huella (hash) del registro.
+    const xml = generateInvoiceXml(invoice, previousHash);
+    const hash = computeRegistroAlta({
+      idEmisorFactura: invoice.emisor.nif,
+      numSerieFactura: `${invoice.id.serie ?? ''}${invoice.id.numero}`,
+      fechaExpedicionFactura: invoice.id.fechaExpedicion,
+      tipoFactura: invoice.tipoFactura,
+      cuotaTotal: invoice.desglose.cuotaTotal.toFixed(2),
+      importeTotal: invoice.desglose.importeTotal.toFixed(2),
+      huellaAnterior: previousHash,
+      fechaHoraHusoGenRegistro: new Date().toISOString(),
+    });
+
+    // 3. Persistir el registro como PENDING.
+    const now = new Date().toISOString();
+    const record: StoredRecord = {
+      id: `${invoice.id.serie ?? ''}${invoice.id.numero}`,
+      invoiceId: `${invoice.id.serie ?? ''}${invoice.id.numero}`,
+      xml,
+      hash,
+      previousHash,
+      qrPayload: buildQrPayload(hash),
+      status: 'PENDING',
+      createdAt: now,
+      updatedAt: now,
+    };
+    await this.repository.saveRecord(record);
+
+    // 4. Enviar a AEAT y persistir la respuesta.
+    const result = await this.client.sendRecord(xml);
+    await this.repository.saveResponse({
+      id: `${record.id}-${Date.now()}`,
+      recordId: record.id,
+      operationId: result.operationId,
+      status: result.status,
+      message: result.message,
+      receivedAt: new Date().toISOString(),
+    });
+
+    // 5. Actualizar el estado del registro según la respuesta.
+    const status = result.status === 'OK' ? 'CONFIRMED' : 'REJECTED';
+    await this.repository.updateRecordStatus(record.id, status);
+
+    return { ...record, status };
+  }
+
+  /**
+   * Anula una factura previamente registrada.
+   *
+   * Genera un registro de anulación que referencia la factura anulada,
+   * lo envía a AEAT y marca la factura original como ANNULLED.
+   */
+  async annulInvoice(invoiceId: string): Promise<StoredRecord> {
+    // 1. Obtener la factura original (para su huella) y el último registro.
+    const original = await this.repository.getRecord(invoiceId);
+    if (!original) {
+      throw new Error(`No existe el registro a anular: ${invoiceId}`);
+    }
+    const last = await this.repository.getLastRecord();
+    const previousHash = last?.hash ?? null;
+
+    // 2. Generar XML de anulación y calcular la huella.
+    const xml = generateAnulacionXml(
+      {
+        idEmisorFacturaAnulada: original.invoiceId,
+        numSerieFacturaAnulada: original.invoiceId,
+        fechaExpedicionFacturaAnulada: new Date().toISOString().slice(0, 10),
+        huellaFacturaAnulada: original.hash,
+      },
+      previousHash,
+    );
+    const hash = computeRegistroAnulacion({
+      idEmisorFacturaAnulada: original.invoiceId,
+      numSerieFacturaAnulada: original.invoiceId,
+      fechaExpedicionFacturaAnulada: new Date().toISOString().slice(0, 10),
+      huellaAnterior: previousHash,
+      fechaHoraHusoGenRegistro: new Date().toISOString(),
+    });
+
+    // 3. Persistir el registro de anulación como PENDING.
+    const now = new Date().toISOString();
+    const record: StoredRecord = {
+      id: `${invoiceId}-ANUL`,
+      invoiceId,
+      xml,
+      hash,
+      previousHash,
+      status: 'PENDING',
+      createdAt: now,
+      updatedAt: now,
+    };
+    await this.repository.saveRecord(record);
+
+    // 4. Enviar a AEAT y persistir la respuesta.
+    const result = await this.client.sendRecord(xml);
+    await this.repository.saveResponse({
+      id: `${record.id}-${Date.now()}`,
+      recordId: record.id,
+      operationId: result.operationId,
+      status: result.status,
+      message: result.message,
+      receivedAt: new Date().toISOString(),
+    });
+
+    // 5. Actualizar estados.
+    const status = result.status === 'OK' ? 'CONFIRMED' : 'REJECTED';
+    await this.repository.updateRecordStatus(record.id, status);
+    if (result.status === 'OK') {
+      await this.repository.updateRecordStatus(invoiceId, 'ANNULLED');
+    }
+
+    return { ...record, status };
+  }
+
+  /**
+   * Modifica una factura previamente registrada.
+   *
+   * Verifactu no tiene un tipo "modificación": se implementa como anulación
+   * del registro original + alta con los datos corregidos. El usuario solo
+   * envía la referencia a la factura original y la factura corregida.
+   */
+  async modifyInvoice(invoiceId: string, correctedInvoice: Invoice): Promise<StoredRecord> {
+    // 1. Anular la factura original.
+    await this.annulInvoice(invoiceId);
+
+    // 2. Emitir la factura corregida como un nuevo alta.
+    return this.registerInvoice(correctedInvoice);
+  }
+}