@acontplus/ng-common 1.0.4 → 1.0.6

package/types/acontplus-ng-common.d.ts

@@ -106,17 +106,17 @@ interface ReportOptions<T = any> {
     data: T;
     format?: 'pdf' | 'excel' | 'word';
     useV1Api?: boolean;
-    forceDownload?: boolean;
-    returnBlob?: boolean;
 }
 /**
  * Puerto para generación de reportes
  * Solo se encarga de generar reportes, no de impresión
  */
 interface ReportPort {
-    generate<T>(options: ReportOptions<T>): Observable<HttpResponse<Blob>> | void;
-    saveFile(response: any, format?: string, forceDownload?: boolean): void;
-    getFileName(response: any): string;
+    /**
+     * Genera un reporte y devuelve el Observable
+     * El consumidor decide si descargar, abrir o procesar el blob
+     */
+    generate<T>(options: ReportOptions<T>): Observable<HttpResponse<Blob>>;
 }
 
 /**
@@ -275,13 +275,198 @@ declare const WHATSAPP_MESSAGING_PORT: InjectionToken<WhatsAppMessagingPort>;
 
 declare const PRINTER_PORT: InjectionToken<PrinterPort>;
 
+/**
+ * Facade para generación de reportes
+ *
+ * Proporciona una API de alto nivel para generar reportes con manejo automático de archivos.
+ * Todos los métodos devuelven Observables - el consumidor debe hacer subscribe().
+ *
+ * @example
+ * ```typescript
+ * // Control total del blob
+ * this.reportFacade.generate(options).subscribe(response => {
+ *   const blob = response.body;
+ *   // Procesar blob manualmente
+ * });
+ *
+ * // Descarga automática
+ * this.reportFacade.download(options).subscribe();
+ *
+ * // Abrir PDF automáticamente
+ * this.reportFacade.open(options).subscribe();
+ * ```
+ */
 declare class ReportFacade {
     private readonly reportPort;
-    generate<T>(options: ReportOptions<T>): Observable<any> | void;
-    generatePDF<T>(data: T, forceDownload?: boolean): void;
-    generateExcel<T>(data: T, forceDownload?: boolean): void;
-    generateWord<T>(data: T, forceDownload?: boolean): void;
-    generateBlob<T>(data: T, format?: 'pdf' | 'excel' | 'word'): Observable<any>;
+    /**
+     * Genera un reporte y devuelve el Observable con el blob
+     *
+     * Este método proporciona control total sobre el blob generado.
+     * No realiza ninguna acción automática (descarga/apertura).
+     * Útil cuando necesitas procesar el blob manualmente (enviar por WhatsApp, guardar en servidor, etc.)
+     *
+     * @template T - Tipo de datos del reporte
+     * @param options - Opciones de generación del reporte
+     * @param options.data - Datos del reporte (usar ReportParamsBuilder.build())
+     * @param options.format - Formato del reporte: 'pdf' | 'excel' | 'word'
+     * @param options.useV1Api - Si debe usar la API v1 (por defecto false)
+     * @returns Observable con la respuesta HTTP que contiene el blob
+     *
+     * @example
+     * ```typescript
+     * const options = ReportParamsBuilder.build(
+     *   { codDoc: ELECTRONIC_DOCUMENT_CODE.FV, id: 123 },
+     *   'pdf'
+     * );
+     *
+     * this.reportFacade.generate(options).subscribe({
+     *   next: (response) => {
+     *     const blob = response.body;
+     *     const fileName = FileMapperUtil.extractFileName(response);
+     *     // Procesar blob según necesidad
+     *   },
+     *   error: (err) => console.error('Error:', err)
+     * });
+     * ```
+     */
+    generate<T>(options: ReportOptions<T>): Observable<HttpResponse<Blob>>;
+    /**
+     * Genera un reporte y lo descarga automáticamente
+     *
+     * Extrae el nombre del archivo desde los headers HTTP y descarga el archivo automáticamente.
+     * Funciona para cualquier formato (PDF, Excel, Word).
+     * El Observable se completa después de iniciar la descarga.
+     *
+     * @template T - Tipo de datos del reporte
+     * @param options - Opciones de generación del reporte
+     * @returns Observable que se completa después de iniciar la descarga
+     *
+     * @example
+     * ```typescript
+     * // Con formato dinámico
+     * const options = ReportParamsBuilder.build(
+     *   { codDoc: SALE_CODE_REPORT.FG },
+     *   this.selectedFormat // 'pdf' | 'excel' | 'word'
+     * );
+     * this.reportFacade.download(options).subscribe();
+     *
+     * // Con formato fijo
+     * const options = ReportParamsBuilder.build(
+     *   { codDoc: INVENTORY_CODE_REPORT.RCD },
+     *   'excel'
+     * );
+     * this.reportFacade.download(options).subscribe();
+     * ```
+     */
+    download<T>(options: ReportOptions<T>): Observable<HttpResponse<Blob>>;
+    /**
+     * Genera un reporte y lo abre en nueva ventana (o descarga en navegadores legacy)
+     *
+     * Comportamiento inteligente según el navegador:
+     * - Navegadores modernos: Abre el archivo en nueva ventana/pestaña
+     * - Navegadores legacy (IE, Edge antiguo): Descarga el archivo
+     *
+     * Ideal para PDFs que el usuario quiere visualizar inmediatamente.
+     * También funciona con Excel/Word pero la experiencia puede variar según el navegador.
+     *
+     * @template T - Tipo de datos del reporte
+     * @param options - Opciones de generación del reporte
+     * @returns Observable que se completa después de abrir/descargar el archivo
+     *
+     * @example
+     * ```typescript
+     * // Abrir PDF
+     * const options = ReportParamsBuilder.build(
+     *   { codDoc: ELECTRONIC_DOCUMENT_CODE.FV, id: 123 },
+     *   'pdf'
+     * );
+     * this.reportFacade.open(options).subscribe();
+     *
+     * // Con formato dinámico
+     * const format = this.isPDF ? 'pdf' : 'excel';
+     * const options = ReportParamsBuilder.build({ codDoc: code }, format);
+     * this.reportFacade.open(options).subscribe();
+     * ```
+     */
+    open<T>(options: ReportOptions<T>): Observable<HttpResponse<Blob>>;
+    /**
+     * Genera un PDF y lo abre automáticamente (shortcut)
+     *
+     * Método de conveniencia para el caso común de generar y abrir PDFs.
+     * Equivalente a llamar open() con format: 'pdf'.
+     *
+     * @template T - Tipo de datos del reporte
+     * @param data - Datos del reporte (resultado de ReportParamsBuilder.build().data)
+     * @param useV1Api - Si debe usar la API v1 (por defecto false)
+     * @returns Observable que se completa después de abrir el PDF
+     *
+     * @example
+     * ```typescript
+     * const reportOptions = ReportParamsBuilder.build(
+     *   { codDoc: ELECTRONIC_DOCUMENT_CODE.FV, id: 123 },
+     *   'pdf'
+     * );
+     *
+     * // Forma corta
+     * this.reportFacade.openPDF(
+     *   reportOptions.data,
+     *   reportOptions.useV1Api
+     * ).subscribe();
+     * ```
+     */
+    openPDF<T>(data: T, useV1Api?: boolean): Observable<HttpResponse<Blob>>;
+    /**
+     * Genera un Excel y lo descarga automáticamente (shortcut)
+     *
+     * Método de conveniencia para el caso común de generar y descargar archivos Excel.
+     * Equivalente a llamar download() con format: 'excel'.
+     *
+     * @template T - Tipo de datos del reporte
+     * @param data - Datos del reporte (resultado de ReportParamsBuilder.build().data)
+     * @param useV1Api - Si debe usar la API v1 (por defecto false)
+     * @returns Observable que se completa después de iniciar la descarga
+     *
+     * @example
+     * ```typescript
+     * const reportOptions = ReportParamsBuilder.build(
+     *   { codDoc: SALE_CODE_REPORT.FG, fechaInicio: '2024-01-01' },
+     *   'excel'
+     * );
+     *
+     * // Forma corta
+     * this.reportFacade.downloadExcel(
+     *   reportOptions.data,
+     *   reportOptions.useV1Api
+     * ).subscribe();
+     * ```
+     */
+    downloadExcel<T>(data: T, useV1Api?: boolean): Observable<HttpResponse<Blob>>;
+    /**
+     * Genera un Word y lo descarga automáticamente (shortcut)
+     *
+     * Método de conveniencia para el caso común de generar y descargar archivos Word.
+     * Equivalente a llamar download() con format: 'word'.
+     *
+     * @template T - Tipo de datos del reporte
+     * @param data - Datos del reporte (resultado de ReportParamsBuilder.build().data)
+     * @param useV1Api - Si debe usar la API v1 (por defecto false)
+     * @returns Observable que se completa después de iniciar la descarga
+     *
+     * @example
+     * ```typescript
+     * const reportOptions = ReportParamsBuilder.build(
+     *   { codDoc: CUSTOMER_CODE_REPORT.RCL },
+     *   'word'
+     * );
+     *
+     * // Forma corta
+     * this.reportFacade.downloadWord(
+     *   reportOptions.data,
+     *   reportOptions.useV1Api
+     * ).subscribe();
+     * ```
+     */
+    downloadWord<T>(data: T, useV1Api?: boolean): Observable<HttpResponse<Blob>>;
     static ɵfac: i0.ɵɵFactoryDeclaration<ReportFacade, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<ReportFacade>;
 }
@@ -358,11 +543,13 @@ declare class GreenWhatsAppAdapter implements WhatsAppMessagingPort {
     static ɵprov: i0.ɵɵInjectableDeclaration<GreenWhatsAppAdapter>;
 }
 
+/**
+ * Adapter para generación de reportes
+ * Siempre devuelve Observable - el consumidor decide qué hacer con el blob
+ */
 declare class ReportAdapter implements ReportPort {
     private readonly http;
-    generate<T>(options: ReportOptions<T>): Observable<HttpResponse<Blob>> | void;
-    getFileName(response: any): string;
-    saveFile(response: any, format?: string, forceDownload?: boolean): void;
+    generate<T>(options: ReportOptions<T>): Observable<HttpResponse<Blob>>;
     static ɵfac: i0.ɵɵFactoryDeclaration<ReportAdapter, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<ReportAdapter>;
 }
@@ -411,43 +598,181 @@ declare class ReportParamsBuilder {
     private static readonly reportConfigs;
     /**
      * Construye los parámetros de reporte según el tipo de documento
+     *
+     * @param docData - Datos del documento con codDoc y parámetros adicionales
+     * @param format - Formato del reporte: 'pdf' | 'excel' | 'word'
+     * @returns Objeto con hasService, reportParams (string JSON) y dataParams (string JSON)
+     *
+     * @example
+     * ```typescript
+     * const params = ReportParamsBuilder.buildParams(
+     *   { codDoc: ELECTRONIC_DOCUMENT_CODE.FV, id: 123, codEstab: '001' },
+     *   'pdf'
+     * );
+     * // Resultado:
+     * // {
+     * //   hasService: true,
+     * //   reportParams: "{\"codigo\":\"FV\",\"format\":\"pdf\",\"hasParams\":true,...}",
+     * //   dataParams: "{\"id\":123,\"codEstab\":\"001\",\"codigo\":\"FV\"}"
+     * // }
+     * ```
      */
     static buildParams(docData: ReportDocumentData, format?: 'pdf' | 'excel' | 'word'): ReportParams;
     /**
      * Determina si debe usar la API v1 según el tipo de documento
+     *
+     * @param codDoc - Código del documento (FV, NE, NC, etc.)
+     * @returns true si debe usar API v1, false para API v2
+     *
+     * @example
+     * ```typescript
+     * const useV1 = ReportParamsBuilder.shouldUseV1Api(ELECTRONIC_DOCUMENT_CODE.FV);
+     * // useV1 = true (documentos electrónicos usan v1)
+     *
+     * const useV1Sales = ReportParamsBuilder.shouldUseV1Api(SALE_CODE_REPORT.FG);
+     * // useV1Sales = false (reportes de ventas usan v2)
+     * ```
      */
     static shouldUseV1Api(codDoc: string): boolean;
     /**
      * Obtiene la configuración para un tipo de documento
+     *
+     * @param codDoc - Código del documento
+     * @returns Configuración del reporte
+     * @throws Error si el tipo de documento no está soportado
+     * @private
      */
     private static getReportConfig;
     /**
-     * Construye los parámetros del reporte
+     * Construye los parámetros del reporte (reportParams)
+     *
+     * Genera un string JSON con la configuración del reporte:
+     * - codigo: Código del reporte
+     * - format: Formato de salida (pdf, excel, word)
+     * - hasParams: Si el reporte acepta parámetros adicionales
+     * - codEstab: Código de establecimiento (si aplica)
+     * - aditionalParams: Array vacío para parámetros adicionales (si aplica)
+     *
+     * @param docData - Datos del documento
+     * @param config - Configuración del tipo de reporte
+     * @param format - Formato de salida
+     * @returns String JSON con los parámetros del reporte
+     * @private
      */
     private static buildReportParams;
     /**
-     * Construye los parámetros de datos
+     * Construye los parámetros de datos (dataParams)
+     *
+     * Genera un string JSON con los datos específicos del reporte.
+     * NO incluye hasParams ni configuración, solo datos puros.
+     *
+     * Incluye automáticamente:
+     * - id: ID del documento (si existe)
+     * - codEstab: Código de establecimiento (según configuración)
+     * - codigo: Código del reporte (según configuración)
+     * - Parámetros extra específicos del tipo (extraDataParams)
+     * - Todos los parámetros adicionales del docData (excepto codDoc, codEstab, id, serie)
+     *
+     * @param docData - Datos del documento con parámetros adicionales
+     * @param config - Configuración del tipo de reporte
+     * @returns String JSON con los datos del reporte (sin hasParams anidado)
+     * @private
+     *
+     * @example
+     * ```typescript
+     * // Input:
+     * docData = { codDoc: 'FG', tipo: 2, codEstab: '001', fechaInicio: '2024-01-01' }
+     * config = { idField: 'id', includeEstabInData: false, ... }
+     *
+     * // Output:
+     * "{\"tipo\":2,\"fechaInicio\":\"2024-01-01\"}"
+     * ```
      */
     private static buildDataParams;
     /**
      * Construye las opciones completas para generar un reporte
-     */
-    static build(docData: ReportDocumentData, format?: 'pdf' | 'excel' | 'word', returnBlob?: boolean): {
+     *
+     * @param docData - Datos del documento con codDoc y parámetros adicionales
+     * @param format - Formato del reporte: 'pdf' | 'excel' | 'word'
+     * @returns Objeto con data (para enviar al backend), format y useV1Api
+     *
+     * @example
+     * ```typescript
+     * const options = ReportParamsBuilder.build(
+     *   { codDoc: ELECTRONIC_DOCUMENT_CODE.FV, id: 123, codEstab: '001' },
+     *   'pdf'
+     * );
+     * // Resultado:
+     * // {
+     * //   data: { hasService: true, reportParams: "{...}", dataParams: "{...}" },
+     * //   format: 'pdf',
+     * //   useV1Api: true
+     * // }
+     *
+     * // Usar con facade
+     * this.reportFacade.generate(options).subscribe();
+     * ```
+     */
+    static build(docData: ReportDocumentData, format?: 'pdf' | 'excel' | 'word'): {
         data: ReportParams;
         format: "pdf" | "excel" | "word";
         useV1Api: boolean;
-        returnBlob: boolean;
     };
     /**
      * Obtiene la lista de tipos de documento soportados
+     *
+     * @returns Array con todos los códigos de documento soportados
+     *
+     * @example
+     * ```typescript
+     * const types = ReportParamsBuilder.getSupportedDocumentTypes();
+     * // ['FV', 'NE', 'NC', 'ND', 'GR', 'SRR', 'SRRC', 'FG', ...]
+     * ```
      */
     static getSupportedDocumentTypes(): string[];
     /**
      * Verifica si un tipo de documento está soportado
+     *
+     * @param codDoc - Código del documento a verificar
+     * @returns true si el documento está soportado, false en caso contrario
+     *
+     * @example
+     * ```typescript
+     * if (ReportParamsBuilder.isDocumentTypeSupported('FV')) {
+     *   // Generar reporte
+     * } else {
+     *   console.error('Tipo de documento no soportado');
+     * }
+     * ```
      */
     static isDocumentTypeSupported(codDoc: string): boolean;
     /**
      * Registra un nuevo tipo de reporte dinámicamente
+     *
+     * Permite agregar soporte para nuevos tipos de reportes en runtime
+     * sin modificar el código fuente de la librería.
+     *
+     * @param codDoc - Código único del documento
+     * @param config - Configuración completa del reporte
+     *
+     * @example
+     * ```typescript
+     * // Agregar un nuevo tipo de reporte personalizado
+     * ReportParamsBuilder.registerReportType('CUSTOM_REPORT', {
+     *   codigo: 'CUSTOM_REPORT',
+     *   hasService: true,
+     *   useV1Api: false,
+     *   idField: 'id',
+     *   hasParams: true,
+     *   extraDataParams: { customField: 'value' }
+     * });
+     *
+     * // Ahora se puede usar
+     * const options = ReportParamsBuilder.build(
+     *   { codDoc: 'CUSTOM_REPORT', id: 123 },
+     *   'pdf'
+     * );
+     * ```
      */
     static registerReportType(codDoc: string, config: ReportConfig): void;
 }