valtech-components 2.0.840 → 2.0.841

package/lib/services/errors/error-logging.interceptor.d.ts

@@ -0,0 +1,26 @@
+import { HttpInterceptorFn } from '@angular/common/http';
+/**
+ * Interceptor HTTP de observabilidad (Capa 1 del estándar de manejo de errores).
+ *
+ * Para CADA respuesta HTTP con error:
+ * 1. Normaliza el error con `interpretError`.
+ * 2. Loguea un evento estructurado a consola con el prefijo `[HTTP]`.
+ * 3. Reporta el error a Firebase Analytics (`source: 'http'`), si hay analytics.
+ *
+ * **NO traga el error** — lo re-lanza tal cual. Las páginas y servicios siguen
+ * recibiendo el error en su `catch` / `catchError` y deciden la UX (eso es
+ * Capa 3: `ValtechErrorService`).
+ *
+ * `AnalyticsService` se inyecta `@Optional()` — apps sin Firebase Analytics
+ * igual obtienen el log estructurado a consola.
+ *
+ * Decisión sobre 401: **se saltea** del tracking de Analytics. Un 401 es el
+ * disparador normal del flujo de refresh de token del `authInterceptor`; el
+ * token se renueva y la request se reintenta de forma transparente. Trackear
+ * cada 401 inundaría Analytics de ruido (cada sesión genera varios al expirar
+ * el access token). El 401 SÍ se loguea a consola (nivel `info`, no `error`)
+ * para no perder la traza en debugging local, pero no se reporta como error.
+ *
+ * Se registra vía {@link provideValtechErrorHandling}.
+ */
+export declare const errorLoggingInterceptor: HttpInterceptorFn;

package/lib/services/errors/index.d.ts

@@ -1,9 +1,16 @@
 /**
- * Error interpretation helpers.
+ * Estándar de manejo de errores del factory Valtech.
  *
- * `interpretError` normaliza cualquier error (HttpErrorResponse crudo,
- * AuthError aplanado, Error de JS, o un valor arbitrario) a un
- * `InterpretedError` con forma estable. Función pura, sin Angular DI.
+ * - `interpretError` (Capa 0) — normaliza cualquier error a `InterpretedError`.
+ *   Función pura, sin Angular DI.
+ * - `provideValtechErrorHandling` (Capa 1) — registra el interceptor HTTP de
+ *   observabilidad: log estructurado + reporte a Analytics, re-lanza el error.
+ * - `ValtechErrorService` (Capa 3) — punto único para el `catch` de una página:
+ *   normaliza, observa, resuelve un mensaje i18n y muestra un toast.
  */
 export { interpretError } from './interpret-error';
 export type { InterpretedError } from './interpret-error';
+export { errorLoggingInterceptor } from './error-logging.interceptor';
+export { provideValtechErrorHandling } from './provide-error-handling';
+export { ValtechErrorService, VALTECH_NETWORK_ERROR_KEY } from './valtech-error.service';
+export type { ValtechErrorHandleOptions } from './valtech-error.service';

package/lib/services/errors/provide-error-handling.d.ts

@@ -0,0 +1,34 @@
+import { EnvironmentProviders } from '@angular/core';
+/**
+ * Provee el manejo de errores estándar del factory Valtech.
+ *
+ * Registra el {@link errorLoggingInterceptor} (Capa 1 — observabilidad): toda
+ * respuesta HTTP con error se normaliza, se loguea de forma estructurada a
+ * consola y se reporta a Firebase Analytics. El interceptor **re-lanza** el
+ * error, así que las páginas siguen haciendo su `catch`.
+ *
+ * Se registra vía `withInterceptors`, igual que el `authInterceptor`. Angular
+ * fusiona los interceptores de múltiples llamadas a `provideHttpClient` dentro
+ * del mismo injector, así que esto compone con `provideValtechAuth()` sin
+ * pisarlo. El orden relativo lo determina Angular por orden de provisión;
+ * para una traza limpia, declarar `provideValtechErrorHandling()` **después**
+ * de `provideValtechAuth(...)` en `main.ts`.
+ *
+ * La Capa 3 ({@link ValtechErrorService}) es `providedIn: 'root'` — no
+ * requiere registro. La Capa 2 (`AnalyticsErrorHandler`, errores no
+ * capturados) la activa `provideValtechFirebase` con `enableErrorTracking`.
+ *
+ * @example
+ * ```typescript
+ * // main.ts
+ * import { provideValtechAuth, provideValtechErrorHandling } from 'valtech-components';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideValtechAuth({ apiUrl: environment.apiUrl }),
+ *     provideValtechErrorHandling(),
+ *   ],
+ * });
+ * ```
+ */
+export declare function provideValtechErrorHandling(): EnvironmentProviders;

package/lib/services/errors/valtech-error.service.d.ts

@@ -0,0 +1,102 @@
+import { InterpretedError } from './interpret-error';
+import * as i0 from "@angular/core";
+/**
+ * Key i18n fija de la librería para fallos de red. Las apps pueden definirla en
+ * su contenido i18n (namespace `_global`) para personalizar el texto; si no
+ * existe, se usa {@link NETWORK_FALLBACK_MESSAGE}.
+ */
+export declare const VALTECH_NETWORK_ERROR_KEY = "valtech.error.network";
+/**
+ * Opciones de {@link ValtechErrorService.handle}.
+ */
+export interface ValtechErrorHandleOptions {
+    /**
+     * Identificador del punto de fallo, ej. `'profile.save'`. Se incluye en el
+     * log de consola y en el reporte a Analytics para facilitar el tracing.
+     */
+    context?: string;
+    /**
+     * Mapa `código de backend → key i18n`. Lo provee la app, que conoce sus
+     * propias traducciones. Ej. `{ EMAIL_TAKEN: 'errors.emailTaken' }`.
+     */
+    i18nMap?: Record<string, string>;
+    /**
+     * Key i18n a usar cuando no hay match en `i18nMap` (y el error no es de red).
+     * Si se omite, se usa un mensaje genérico en español.
+     */
+    fallbackKey?: string;
+    /**
+     * Namespace i18n para resolver `i18nMap` / `fallbackKey` / la key de red.
+     * Default: `_global`.
+     */
+    i18nNamespace?: string;
+    /** Si mostrar un toast con el mensaje resuelto. Default: `true`. */
+    toast?: boolean;
+}
+/**
+ * Servicio de UX de errores capturados (Capa 3 del estándar de manejo de errores).
+ *
+ * Mientras la Capa 1 ({@link errorLoggingInterceptor}) observa TODAS las
+ * respuestas HTTP con error, y la Capa 2 (`AnalyticsErrorHandler`) captura los
+ * errores NO manejados, la Capa 3 es el punto único que una página usa en su
+ * `catch` para convertir un error en feedback al usuario.
+ *
+ * Responsabilidades de {@link handle}:
+ * 1. Normaliza el error (`interpretError`).
+ * 2. Loguea a consola + reporta a Analytics (`source: 'handled'`, con `context`).
+ * 3. Resuelve un mensaje localizado (ver orden de resolución en {@link handle}).
+ * 4. Muestra un toast (`color: 'dark'`, estándar Valtech) salvo `toast: false`.
+ * 5. Devuelve el {@link InterpretedError} para que la página decida lógica extra.
+ *
+ * **Nunca lanza.** `AnalyticsService` se inyecta `@Optional()`.
+ *
+ * @example
+ * ```ts
+ * private errors = inject(ValtechErrorService);
+ *
+ * async save() {
+ *   try {
+ *     await firstValueFrom(this.api.updateProfile(this.form.value));
+ *     this.toast.show({ message: 'Perfil actualizado', color: 'dark' });
+ *   } catch (err) {
+ *     this.errors.handle(err, {
+ *       context: 'profile.save',
+ *       i18nMap: { EMAIL_TAKEN: 'errors.emailTaken' },
+ *       fallbackKey: 'errors.profileSaveFailed',
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare class ValtechErrorService {
+    private readonly i18n;
+    private readonly toast;
+    private readonly analytics;
+    /**
+     * Maneja un error capturado: normaliza, observa y produce feedback de usuario.
+     *
+     * Orden de resolución del mensaje del toast:
+     * 1. `i18nMap[code]` definido → `i18n.t(esa key)`.
+     * 2. Sin match y `isNetwork` → key de red ({@link VALTECH_NETWORK_ERROR_KEY}),
+     *    con fallback al texto español si la app no la tradujo.
+     * 3. `fallbackKey` definido → `i18n.t(fallbackKey)`.
+     * 4. Genérico en español.
+     *
+     * @param err Cualquier error capturado.
+     * @param opts Opciones de contexto, mapeo i18n y toast.
+     * @returns El {@link InterpretedError} normalizado. Nunca lanza.
+     */
+    handle(err: unknown, opts?: ValtechErrorHandleOptions): InterpretedError;
+    /**
+     * Resuelve el mensaje a mostrar siguiendo el orden documentado en {@link handle}.
+     */
+    private resolveMessage;
+    /**
+     * Traduce una key i18n. Devuelve `null` si la key no está definida — el
+     * `I18nService` devuelve un placeholder `[namespace.key]` para keys faltantes;
+     * lo detectamos para poder caer a un fallback en lugar de mostrar el placeholder.
+     */
+    private translate;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ValtechErrorService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ValtechErrorService>;
+}

package/lib/version.d.ts

@@ -2,4 +2,4 @@
  * Current version of valtech-components.
  * This is automatically updated during the publish process.
  */
-export declare const VERSION = "2.0.840";
+export declare const VERSION = "2.0.841";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valtech-components",
-  "version": "2.0.840",
+  "version": "2.0.841",
   "private": false,
   "bin": {
     "valtech-firebase-config": "./src/lib/services/firebase/scripts/generate-sw-config.js"