@tinya-code/gas-admin-ui 0.2.0-alpha.15 → 0.2.0-alpha.18

package/src/lib/core/interceptors/api-error.interceptor.spec.ts

@@ -1,182 +0,0 @@
-import { HttpClient, provideHttpClient, withInterceptors } from '@angular/common/http';
-import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
-import { TestBed } from '@angular/core/testing';
-import { provideRouter } from '@angular/router';
-
-import { ApiError } from '../models/api.model';
-import { API_URL } from '../tokens';
-import { AuthService, SESSION_TOKEN_KEY, SESSION_USER_KEY } from '../services/auth.service';
-import { apiErrorInterceptor } from './api-error.interceptor';
-
-/**
- * Emite `body` en el canal de éxito (el backend responde 200 con el error
- * dentro) y devuelve el `ApiError` que el interceptor lanzó.
- * A nivel de módulo: lo usan el describe de mensajes y el de R2.9.
- */
-function errorFromBody(body: object): ApiError {
-  const http = TestBed.inject(HttpClient);
-  const mock = TestBed.inject(HttpTestingController);
-  let lanzado: unknown;
-  http.get('/recursos').subscribe({
-    error: (e: unknown) => {
-      lanzado = e;
-    },
-  });
-  mock.expectOne('/recursos').flush(body);
-  mock.verify();
-  return lanzado as ApiError;
-}
-
-/**
- * Plan 7.3 — mensajes en lenguaje humano (guía §2).
- *
- * Dos canales distintos: el body del backend (que ya escribe en español) y
- * el transporte (red caída, proxy, 5xx), que sin normalizar deja en pantalla
- * el texto crudo de Angular: «Http failure response for http://…».
- *
- * **R2.9** — desde que el interceptor entrega los `AUTH_*` a
- * `AuthService.applyAuthCode`, necesita poder inyectarlo: por eso acá hay
- * router y `API_URL`, que son las dependencias de ese servicio.
- */
-describe('apiErrorInterceptor — mensajes humanos', () => {
-  beforeEach(() => {
-    sessionStorage.clear();
-    TestBed.configureTestingModule({
-      providers: [
-        provideHttpClient(withInterceptors([apiErrorInterceptor])),
-        provideHttpClientTesting(),
-        provideRouter([]),
-        { provide: API_URL, useValue: '/api' },
-      ],
-    });
-  });
-
-  afterEach(() => sessionStorage.clear());
-
-  function failWith(status: number, body?: unknown): string {
-    const http = TestBed.inject(HttpClient);
-    const mock = TestBed.inject(HttpTestingController);
-    let message = '';
-    http.get('/recursos').subscribe({
-      error: (error: unknown) => {
-        message = error instanceof ApiError ? error.message : String(error);
-      },
-    });
-    const request = mock.expectOne('/recursos');
-    if (status === 0) {
-      // Red caída: el backend no llegó a responder.
-      request.error(new ErrorEvent('error'));
-    } else {
-      // `flush` con status fuera de 2xx materializa un `HttpErrorResponse`.
-      request.flush(body ?? '', { status, statusText: 'ERR' });
-    }
-    mock.verify();
-    return message;
-  }
-
-  it('un 5xx se explica en español, no con el texto crudo de Angular', () => {
-    expect(failWith(500)).toBe(
-      'El servidor tuvo un problema. Vuelve a intentarlo en unos segundos.',
-    );
-  });
-
-  it('la red caída (status 0) dice que no hubo conexión', () => {
-    expect(failWith(0)).toBe('No se pudo conectar con el servidor. Revisa tu conexión.');
-  });
-
-  it('un 403 habla de permisos', () => {
-    expect(failWith(403)).toBe('No tienes permisos para realizar esta acción.');
-  });
-
-  it('conserva el mensaje del backend cuando viene en el body (canal de éxito)', () => {
-    expect(
-      failWith(200, {
-        error: { status: 422, message: 'Ya existe un registro con este valor', path: 'name' },
-      }),
-    ).toBe('Ya existe un registro con este valor');
-  });
-
-  /**
-   * D42 — el422 manda sus rutas en `error.errors[]`, NO en `path`: sin
-   * modelar esa lista el form veía «Errores de validación» y no pintaba
-   * ningún campo (base.md §5, guía §10).
-   */
-  it('conserva errors[] completo (path, message, code) en el ApiError', () => {
-    const error = errorFromBody({
-      error: {
-        status: 422,
-        message: 'Errores de validación',
-        errors: [
-          {
-            path: 'sku',
-            message: 'Debe tener al menos 5 caracteres.',
-            code: 'VALIDATION_MIN_LENGTH',
-          },
-          { path: 'faq[2].answer', message: 'Campo obligatorio.', code: 'VALIDATION_REQUIRED' },
-        ],
-      },
-    });
-    expect(error.status).toBe(422);
-    expect(error.message).toBe('Errores de validación');
-    expect(error.issues).toEqual([
-      { path: 'sku', message: 'Debe tener al menos 5 caracteres.', code: 'VALIDATION_MIN_LENGTH' },
-      { path: 'faq[2].answer', message: 'Campo obligatorio.', code: 'VALIDATION_REQUIRED' },
-    ]);
-    // Sin `path` en el sobre no hay fieldPath: las rutas vienen en los issues.
-    expect(error.fieldPath).toBeUndefined();
-  });
-});
-
-/**
- * R2.9 — éste es el ÚNICO puente entre el sobre de error y la tabla de
- * §4.5. Si el interceptor dejara de llamar a `applyAuthCode`, el front se
- * quedaría en una pantalla caducada sin reloguear: por eso el puente se
- * prueba acá y las cinco filas de la tabla, en `auth.service.spec.ts`.
- */
-describe('apiErrorInterceptor — entrega de los códigos de sesión (R2.9)', () => {
-  beforeEach(() => {
-    sessionStorage.clear();
-    sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok-vigente');
-    sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role: 'admin' }));
-    TestBed.configureTestingModule({
-      providers: [
-        provideHttpClient(withInterceptors([apiErrorInterceptor])),
-        provideHttpClientTesting(),
-        provideRouter([]),
-        { provide: API_URL, useValue: '/api' },
-      ],
-    });
-  });
-
-  afterEach(() => sessionStorage.clear());
-
-  it('conserva el `code` en el ApiError que recibe el llamador', () => {
-    const error = errorFromBody({
-      error: { status: 401, message: 'No autorizado', code: 'AUTH_EXPIRED' },
-    });
-    expect(error.code).toBe('AUTH_EXPIRED');
-    expect(error.status).toBe(401);
-  });
-
-  it('un error SIN código de sesión no toca la sesión', () => {
-    errorFromBody({ error: { status: 422, message: 'Datos no válidos', path: 'name' } });
-    expect(sessionStorage.getItem(SESSION_TOKEN_KEY)).toBe('tok-vigente');
-    expect(TestBed.inject(AuthService).isAuthenticated()).toBe(true);
-  });
-
-  it('FORBIDDEN deja al usuario DENTRO de la sesión (§4.5)', () => {
-    errorFromBody({ error: { status: 403, message: 'Prohibido', code: 'FORBIDDEN' } });
-    expect(sessionStorage.getItem(SESSION_TOKEN_KEY)).toBe('tok-vigente');
-    expect(TestBed.inject(AuthService).isAuthenticated()).toBe(true);
-  });
-
-  it('AUTH_INVALID borra token y usuario ANTES de nada más (§5.4)', () => {
-    errorFromBody({ error: { status: 401, message: 'No autorizado', code: 'AUTH_INVALID' } });
-    expect(sessionStorage.getItem(SESSION_TOKEN_KEY)).toBeNull();
-    expect(sessionStorage.getItem(SESSION_USER_KEY)).toBeNull();
-    const auth = TestBed.inject(AuthService);
-    expect(auth.token()).toBeNull();
-    expect(auth.user()).toBeNull();
-    expect(auth.isAuthenticated()).toBe(false);
-  });
-});

package/src/lib/core/interceptors/api-error.interceptor.ts

@@ -1,87 +0,0 @@
-import { HttpErrorResponse, HttpInterceptorFn, HttpResponse } from '@angular/common/http';
-import { inject } from '@angular/core';
-import { catchError, map, throwError } from 'rxjs';
-
-import { ApiError } from '../models/api.model';
-import type { ApiErrorBody } from '../models/api.model';
-import { AuthService } from '../services/auth.service';
-
-/**
- * Mensaje humano para un error HTTP real (§2).
- *
- * El backend siempre responde 200 con el error dentro del body —eso ya
- * viene en español—, así que esto sólo cubre lo que el transporte falla:
- * red caída, proxy y 5xx. Sin esto el usuario ve el texto crudo de Angular
- * («Http failure response for http://…»), que es inglés técnico.
- */
-function httpMessage(status: number): string {
-  switch (status) {
-    case 0:
-      return 'No se pudo conectar con el servidor. Revisa tu conexión.';
-    case 401:
-      return 'Tu sesión ha expirado. Vuelve a iniciar sesión.';
-    case 403:
-      return 'No tienes permisos para realizar esta acción.';
-    case 404:
-      return 'No se encontró el recurso solicitado.';
-    case 409:
-      return 'El registro cambió o ya existe. Recarga la página y vuelve a intentarlo.';
-    case 413:
-      return 'El archivo es demasiado grande.';
-    case 422:
-      return 'Los datos enviados no son válidos.';
-    default:
-      if (status >= 500) {
-        return 'El servidor tuvo un problema. Vuelve a intentarlo en unos segundos.';
-      }
-      return status >= 400 ? 'No se pudo completar la operación.' : 'Error inesperado.';
-  }
-}
-
-function isErrorBody(body: unknown): body is ApiErrorBody {
-  if (typeof body !== 'object' || body === null) {
-    return false;
-  }
-  const error = (body as ApiErrorBody).error;
-  return typeof error === 'object' && error !== null && typeof error.message === 'string';
-}
-
-/**
- * El backend responde SIEMPRE HTTP 200 y pone los errores en el body
- * (api.md §7), así que se detectan en el canal de **éxito** y se relanzan
- * como `ApiError` (con `fieldPath` cuando el backend envía `path`).
- * Los errores HTTP reales (red caída, proxy) también se normalizan.
- *
- * **R2.9 — paso dos de dos.** Éste archivo es el ÚNICO punto donde el
- * sobre de error se abre; lo que decide qué ocurre con un `AUTH_*` es
- * `AuthService.applyAuthCode` (la tabla de §4.5). Aquí sólo se le entrega
- * el código y se propaga el `ApiError` con él — un segundo sitio que
- * «interprete» el código sería una regla duplicada y, a la larga, una que
- * se contradiga con la primera.
- */
-export const apiErrorInterceptor: HttpInterceptorFn = (req, next) => {
-  const auth = inject(AuthService);
-
-  return next(req).pipe(
-    map((event) => {
-      if (event instanceof HttpResponse && isErrorBody(event.body)) {
-        const { status, message, path, code, errors } = event.body.error;
-        // R2.9: ésta es la ÚNICA llamada a la tabla de §4.5.
-        auth.applyAuthCode(code);
-        // `errors[]` es el422 con rutas (D42): va entero al ApiError para que
-        // `ErrorMapperService` lo convierta en `serverErrors[prefix + key]`.
-        throw new ApiError(status, message, path, code, errors ?? []);
-      }
-      return event;
-    }),
-    catchError((err: unknown) => {
-      if (err instanceof ApiError) {
-        return throwError(() => err);
-      }
-      if (err instanceof HttpErrorResponse) {
-        return throwError(() => new ApiError(err.status, httpMessage(err.status)));
-      }
-      return throwError(() => err);
-    }),
-  );
-};

package/src/lib/core/models/api.model.ts

@@ -1,104 +0,0 @@
-/**
- * Contrato HTTP con el backend (doc/baseapi.md §8 «Errores»).
- *
- * El backend responde SIEMPRE HTTP 200; los errores viajan en el body
- * con `{ error: { status, message, errors?: [{ path, message }] } }`.
- * El interceptor (Fase 3) los convierte en `ApiError`.
- */
-
-/**
- * Un error con ruta del422 (auth.md §6): `path` para pintarlo en el campo y
- * `code` MAYUS_SNAKE (`VALIDATION_MIN_LENGTH`) para mapearlo sin leer texto.
- */
-export interface ApiIssue {
-  /** Ruta del campo afectado (`faq[2].answer`, `sku`). */
-  path: string;
-  /** Mensaje en español, listo para pintar. */
-  message: string;
-  /** Código estable del validador (B11); el mensaje puede cambiar, el código no. */
-  code?: string;
-}
-
-/** Shape del body de error (doc/baseapi.md §8 «Errores»). */
-export interface ApiErrorBody {
-  error: {
-    status: number;
-    message: string;
-    /** Ruta del campo afectado cuando el backend la envía (base.md §10). */
-    path?: string;
-    /**
-     * Código de sesión de §4.5 (R2.9): `AUTH_REQUIRED` · `AUTH_INVALID` ·
-     * `AUTH_EXPIRED` · `FORBIDDEN` · `RATE_LIMITED`. Aparece SÓLO en esas
-     * cinco respuestas — el sobre de error es aditivo (O7 / D10-5).
-     */
-    code?: string;
-    /**
-     * Errores de validación con ruta (base.md §5, guía §10): el 422 los manda
-     * ACÁ (`error.errors[]`), no en `path`. Sin modelarlos el form veía
-     * «Errores de validación» genérico y ningún campo se pintaba (D42).
-     */
-    errors?: ApiIssue[];
-  };
-}
-
-/** Error de API estandarizado que lanza el interceptor de errores. */
-export class ApiError extends Error {
-  readonly status: number;
-  /** Ruta del campo que provocó el error (ej. `faq[2].answer`), si existe. */
-  readonly fieldPath?: string;
-  /** Código de sesión de §4.5 si el backend lo envió; `undefined` en el resto. */
-  readonly code?: string;
-  /** Issues con ruta (422); vacío cuando el error no trae `errors[]`. */
-  readonly issues: readonly ApiIssue[];
-
-  constructor(
-    status: number,
-    message: string,
-    fieldPath?: string,
-    code?: string,
-    issues: readonly ApiIssue[] = [],
-  ) {
-    super(message);
-    this.name = 'ApiError';
-    this.status = status;
-    this.fieldPath = fieldPath;
-    this.code = code;
-    this.issues = issues;
-  }
-}
-
-/**
- * `meta.renewedToken` (auth.md §3.2/§3.4): el back lo adjunta a la respuesta
- * cuando la vida del token bajó del umbral de renovación. Es el ÚNICO modo
- * de que el front se entere — el token nuevo no viaja en cabeceras ni en la
- * URL. Devuelve `null` cuando no hay renovación (que es lo normal).
- *
- * Vive acá y no en el `ApiService` porque lo consumen DOS servicios
- * (`ApiService` y `AuthService`) y éste modelo no importa a ninguno de los
- * dos: sin este archivo no hay ciclo de imports.
- */
-export function renewedTokenOf(body: unknown): string | null {
-  if (body === null || typeof body !== 'object') return null;
-  const meta = (body as { meta?: unknown }).meta;
-  if (meta === null || typeof meta !== 'object') return null;
-  const token = (meta as { renewedToken?: unknown }).renewedToken;
-  return typeof token === 'string' && token !== '' ? token : null;
-}
-
-/**
- * Resultado de una página para `ApiService.listPage()`.
- *
- * El backend envía la metadata de paginación dentro del sobre (típicamente
- * en `meta`); el motor la extrae según la declaración `responseUnwrap.pagination`
- * y la entrega en este shape. `list()` NO usa este tipo: sigue devolviendo `T[]`.
- */
-export interface PageResult<T> {
-  /** Registros de la página actual. */
-  items: T[];
-  /** Cursor para pedir la página siguiente; `null` cuando no hay más. */
-  nextCursor: string | null;
-  /** Total de registros del conjunto, si el backend lo informa; `0` si no. */
-  total: number;
-  /** `true` si hay al menos una página más. `false` sin cursor informativo. */
-  hasMore: boolean;
-}

package/src/lib/core/models/schema-descriptions.ts

@@ -1,118 +0,0 @@
-/**
- * Descripciones centralizadas del catálogo de campos del motor `@tinya-code/gas-admin-ui`.
- *
- * Este archivo es el único lugar donde se editan los textos descriptivos de
- * cada propiedad del schema. Los JSDoc de `schema.model.ts` usan estos mismos
- * textos para que el editor (VSCode) muestre tooltips al pasar el cursor
- * sobre una propiedad del schema del consumidor.
- *
- * Estructura: clave de propiedad → descripción en español.
- *
- * Uso en el consumidor (loyalty-admin, etc.):
- *   import { schemaDescriptions } from '@tinya-code/gas-admin-ui';
- *   schemaDescriptions['docLink']; // 'URL de documentación externa para este campo.'
- *
- * Nota: este objeto no se renderiza en la UI; solo existe para documentación
- * y tooltips del editor. Para renderizar tooltips en el formulario usa
- * `description` en cada campo del schema del consumidor.
- */
-
-export const schemaDescriptions = {
-  // ── Propiedades comunes a todo campo (FieldBase) ───────────────────────
-  key: 'Nombre de la propiedad en el JSON que envía/recibe el back.',
-  label: 'Rótulo visible para el usuario en el formulario y la ficha.',
-  help: 'Texto corto de ayuda que se muestra debajo del campo.',
-  placeholder: 'Texto sugerente que se muestra dentro del input cuando está vacío.',
-  required: 'Si es obligatorio. El back también lo valida (R7.4).',
-  default: 'Valor por defecto si el registro no trae este campo (ej. `default: "none"` en un `select`/`dropdown`).',
-  readonly: 'Si el campo es solo lectura (no editable en el formulario).',
-  readonlyOn: 'Bloquea el campo solo en creación, solo en edición o siempre.',
-  readonlyWhen: 'Condición bajo la cual el campo es solo lectura (expresión sobre otros campos).',
-  visibleWhen: 'Condición bajo la cual el campo se muestra u oculta.',
-  hiddenOn: 'Oculta el campo en creación, en edición o siempre.',
-  dependsOn: 'Selección dependiente (guía §1: país → ciudad). Clave del campo padre del mismo nivel.',
-  validators: 'Reglas de validación (mínimo, máximo, patrón, unicidad, etc.).',
-  width: 'Ancho en la grilla del formulario (1–12), igual que un widget del dashboard.',
-  section: 'Id de la sección/pestaña del layout a la que pertenece (base.md §4).',
-  read: 'Código de nivel de acceso requerido para leer el campo.',
-  write: 'Código de nivel de acceso requerido para escribir el campo.',
-  description: 'Descripción corta de para qué sirve este campo. Se muestra como tooltip al pasar el cursor sobre el rótulo.',
-  docLink: 'URL de documentación externa para este campo (se abre al hacer clic en el tooltip).',
-
-  // ── Opciones de select/dropdown ───────────────────────────────────────
-  value: 'Valor que se envía al back cuando se elige esta opción.',
-  labelOption: 'Texto visible de la opción.',
-  disabled: 'Si la opción está deshabilitada (no se puede elegir).',
-
-  // ── Campos específicos ─────────────────────────────────────────────────
-  type: 'Tipo de campo: `text`, `color`, `number`, `currency`, `boolean`, `select`, `dropdown`, `rich-select`, `multiselect`, `url`, `email`, `phone`, `date`, `time`, `readonly-text`, `slug`, `textarea`, `relation`, `image`, `file`, `group`, `list`, `string-list`, `key-value`.',
-  maxLength: 'Longitud máxima de caracteres permitida.',
-  pattern: 'Expresión regular que debe cumplir el valor.',
-  rows: 'Número de filas visibles del textarea.',
-  minWords: 'Cantidad mínima de palabras.',
-  maxWords: 'Cantidad máxima de palabras.',
-  tokens: 'Marcadores insertables como chips bajo el área (plantillas de mensaje).',
-  from: 'Campo del registro del que se autogenera el slug.',
-  lockAfterCreate: 'Bloquea el campo una vez creado el registro (por defecto: sí).',
-  min: 'Valor mínimo permitido.',
-  max: 'Valor máximo permitido.',
-  step: 'Incremento entre valores permitidos.',
-  decimals: 'Número de decimales mostrados.',
-  currencyFrom: 'Campo del registro del que se toma la moneda (ej. `currency`).',
-  trueLabel: 'Texto que se muestra cuando el valor es verdadero.',
-  falseLabel: 'Texto que se muestra cuando el valor es falso.',
-  source: 'De dónde salen las opciones: `{ resource, view?, params?, … }` (F8 · R6.5).',
-  resource: 'Recurso declarado (`resource.id`): su listado es el de las opciones.',
-  view: 'Vista declarada en `resource.views` (opcional): filtra en el back.',
-  params: 'Valores interpolados para la vista (`{campo}` ← contexto).',
-  labelField: 'Etiqueta por defecto de las filas (si no, `titleField` del recurso).',
-  valueField: 'Valor por defecto de las filas (si no, `keyField` del recurso).',
-  secondaryField: 'Segundo dato a mostrar junto a la etiqueta (ej. "Juan Pérez · DNI 123").',
-  onlyActive: 'Cargar solo registros activos (lo exige además la FK en el back).',
-  accept: 'Tipos aceptados (ej. `image/*`, `image/png,image/jpeg` o `pdf,docx`).',
-  maxSizeMB: 'Tamaño máximo del archivo en megabytes.',
-  aspectRatio: 'Relación de aspecto de la vista previa (ej. `16/9`).',
-  previewSize: 'Tamaño de la vista previa.',
-  formatCurrency: 'Campo del registro del que se toma la moneda (ej. `currency`).',
-  display: 'Presentación del grupo: `card`, `collapsible` o `inline`.',
-  fields: 'Campos de cada item (cualquier tipo, incluso `group` o `list`).',
-  minItems: 'Cantidad mínima de items.',
-  maxItems: 'Cantidad máxima de items.',
-  sortable: 'Si se puede reordenar (por defecto: sí).',
-  positionField: 'Campo donde se guarda el orden dentro de cada item (`position`).',
-  addLabel: 'Etiqueta del botón para agregar un item nuevo.',
-  emptyText: 'Texto que se muestra cuando no hay items.',
-  itemDisplay: 'Cómo se muestra cada item: `card`, `row` o `accordion`.',
-  itemFields: 'Campos de cada item (cualquier tipo, incluso `group` o `list`).',
-  itemTitle: 'Campo del item usado como título cuando está colapsado.',
-  primaryFirst: 'El primer item tiene significado especial (ej. imagen principal).',
-  itemType: 'Tipo permitido de cada item (base.md §9: solo `text`, `url` o `email`).',
-  sort: 'Si la lista se ordena alfabéticamente o por posición.',
-  filter: 'Si el listado permite filtrado por texto.',
-  search: 'Campos buscables en el listado.',
-  filters: 'Filtros declarados para el listado.',
-  listColumns: 'Columnas que se muestran en el listado.',
-  searchable: 'Si el campo es buscable.',
-  filterable: 'Si el campo es filtrable.',
-  sortableItems: 'Si los items de la lista se pueden reordenar.',
-  groupBy: 'Campo por el que agrupar los items.',
-  cardWidth: 'Ancho de cada tarjeta de opción en la grilla (1–12). Por defecto `4` (3 tarjetas por fila en escritorio).',
-  cardCols: 'Cuántas tarjetas mostrar por fila en el punto de ruptura `lg`. Sobrescribe el cálculo automático basado en `cardWidth`.',
-  hintMetric: 'Texto secundario bajo la cifra (estático, va en el schema).',
-  unitChart: 'Sufijo de las cifras del eje («unidades», «S/»).',
-  segments: 'Segmentos de la barra de distribución porcentual.',
-  actions: 'Acciones de navegación por fila.',
-  labelAction: 'Etiqueta de la acción.',
-  icon: 'Icono de la acción.',
-  navigateTo: 'Ruta de destino de la acción.',
-  variant: 'Variante visual: `primary`, `secondary` u `outline`.',
-
-  // ── Widgets de dashboard ──────────────────────────────────────────────
-  widgets: 'Widgets del panel. Se declara en `ResourceSchema.widgets` — no en `fields`, porque un KPI no es un campo.',
-  mobileWidth: 'Ancho en la grilla en mobile (1–12). Por defecto `12` (ancho completo, apilado).',
-  sourceWidget: 'De dónde saca sus datos: `DataSource` o `{ kind: "payload" }`.',
-  hintWidget: 'Texto secundario bajo la cifra (estático, va en el schema).',
-  unitWidget: 'Sufijo de las cifras del eje.',
-} as const;
-
-export type SchemaDescriptionKey = keyof typeof schemaDescriptions;