valtech-components 2.0.839 → 2.0.841

package/lib/components/organisms/change-password-modal/change-password-modal.component.d.ts

@@ -49,7 +49,6 @@ export declare class ChangePasswordModalComponent {
     /** Modo actual — `loading` mientras se consulta `checkHasPassword()`. */
     readonly mode: import("@angular/core").Signal<PasswordModalMode>;
     private readonly _formState;
-    constructor();
     /** Traduce una clave del namespace `_auth`. */
     t(key: string): string;
     readonly formProps: import("@angular/core").Signal<FormMetadata>;

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

@@ -0,0 +1,16 @@
+/**
+ * Estándar de manejo de errores del factory Valtech.
+ *
+ * - `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/interpret-error.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Error interpretation helper for the Valtech factory.
+ *
+ * Todos los frontends del factory consumen la misma API (backend Go) y la misma
+ * librería. La lógica de interpretar errores debe vivir una sola vez, acá.
+ *
+ * El backend Go (`apperrors`) SIEMPRE devuelve errores como JSON:
+ *   { "code": string, "message": string, "operationId": string }
+ * donde `message` ya viene en español y es user-friendly.
+ *
+ * En Angular un error HTTP llega como `HttpErrorResponse` (body en `.error`).
+ * Un fallo de red es un `HttpErrorResponse` con `status === 0`.
+ *
+ * Además `AuthService.handleAuthError` aplana el `HttpErrorResponse` a un
+ * `AuthError { code, message }` (code/message al nivel superior). Por eso este
+ * helper acepta AMBAS formas — el crudo y el aplanado.
+ */
+/**
+ * Resultado normalizado de cualquier error. Garantiza una forma estable y
+ * predecible para que las webapps no tengan que hacer narrowing manual.
+ */
+export interface InterpretedError {
+    /** Código del backend, o el sentinel `'NETWORK'` / `'UNKNOWN'`. */
+    code: string;
+    /** Mensaje del backend (español, user-friendly) o un genérico en español. */
+    message: string;
+    /** `operationId` del backend, si vino. Útil para soporte / tracing. */
+    operationId?: string;
+    /** HTTP status, si aplica (`0` para fallos de red). */
+    status?: number;
+    /** `true` si fue un fallo de red (status 0 / sin respuesta). */
+    isNetwork: boolean;
+}
+/**
+ * Normaliza CUALQUIER error a un `InterpretedError`.
+ *
+ * Función pura — sin dependencias de Angular DI, testeable y usable desde
+ * cualquier lado (componentes, servicios, interceptores, scripts).
+ *
+ * Nunca lanza: siempre devuelve un `InterpretedError` válido.
+ *
+ * Casos cubiertos:
+ * - `HttpErrorResponse` con `status === 0` (o sin respuesta) → fallo de red.
+ * - `HttpErrorResponse` con body `{ code, message, operationId }` del backend.
+ * - `AuthError` aplanado `{ code, message }` (code/message top-level).
+ * - `Error` plano de JS → `code: 'UNKNOWN'`, `message: err.message`.
+ * - Cualquier otra cosa (string, null, undefined, objeto raro) → genérico.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await firstValueFrom(this.http.get(url));
+ * } catch (err) {
+ *   const e = interpretError(err);
+ *   if (e.isNetwork) {
+ *     this.toast.show({ message: e.message, color: 'dark' });
+ *   } else {
+ *     this.errorCode.set(e.code);
+ *   }
+ * }
+ * ```
+ */
+export declare function interpretError(err: unknown): InterpretedError;

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.839";
+export declare const VERSION = "2.0.841";

package/package.json

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

package/public-api.d.ts

@@ -255,6 +255,7 @@ export * from './lib/services/navigation';
 export * from './lib/services/theme.service';
 export * from './lib/services/toast.service';
 export * from './lib/services/types';
+export * from './lib/services/errors';
 export * from './lib/services/confirmation-dialog/confirmation-dialog.service';
 export * from './lib/services/confirmation-dialog/types';
 export * from './lib/services/qr-generator/qr-generator.service';