@tinya-code/gas-admin-ui 0.2.0-alpha.1 → 0.2.0-alpha.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinya-code/gas-admin-ui",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.11",
   "description": "Motor de render Angular para admin CRUD: declará ResourceSchema y el motor dibuja vistas, campos y widgets.",
   "repository": {
     "type": "git",

package/types/tinya-code-gas-admin-ui.d.ts

@@ -2,7 +2,7 @@ import * as i0 from "@angular/core";
 import { EnvironmentProviders, InjectionToken, Provider, Signal, TemplateRef, Type } from "@angular/core";
 import { CanActivateFn, Route, Router, Routes } from "@angular/router";
 import { Observable } from "rxjs";
-import { HttpEvent, HttpInterceptorFn } from "@angular/common/http";
+import { HttpClient, HttpEvent, HttpHeaders, HttpInterceptorFn, HttpParams } from "@angular/common/http";
 import { CdkDragDrop } from "@angular/cdk/drag-drop";
 import { LucideIcon } from "@lucide/angular";
 import { FieldTree, PathKind, SchemaFn, SchemaPath, SchemaPathRules } from "@angular/forms/signals";
@@ -44,17 +44,25 @@ export interface FieldValidators {
 }
 /** Propiedades comunes a todo campo (base.md §4). */
 export interface FieldBase<T> {
-  /** Nombre de la propiedad en el JSON. */
+  /** Nombre de la propiedad en el JSON que envía/recibe el back. */
   key: string;
+  /** Rótulo visible para el usuario en el formulario y la ficha. */
   label: string;
+  /** Texto corto de ayuda que se muestra debajo del campo. */
   help?: string;
+  /** Texto sugerente que se muestra dentro del input cuando está vacío. */
   placeholder?: string;
+  /** Si es obligatorio. El back también lo valida (R7.4). */
   required?: boolean;
+  /** Valor por defecto si el registro no trae este campo (ej. `default: 'none'` en un `select`/`dropdown`). */
   default?: T;
+  /** Si el campo es solo lectura (no editable en el formulario). */
   readonly?: boolean;
-  /** Ciclo de vida: bloquea el campo solo en creación, solo en edición o siempre. */
+  /** Bloquea el campo solo en creación, solo en edición o siempre. */
   readonlyOn?: 'create' | 'update' | 'always';
+  /** Condición bajo la cual el campo es solo lectura (expresión sobre otros campos). */
   readonlyWhen?: FieldCondition;
+  /** Condición bajo la cual el campo se muestra u oculta. */
   visibleWhen?: FieldCondition;
   /**
    * Ciclo de vida de la VISIBILIDAD: oculta el campo en creación, en edición
@@ -75,7 +83,9 @@ export interface FieldBase<T> {
    * defecto (plan 6.6).
    */
   dependsOn?: string;
+  /** Reglas de validación (mínimo, máximo, patrón, unicidad, etc.). */
   validators?: FieldValidators;
+  /** Ancho en la grilla del formulario (1–12), igual que un widget del dashboard. */
   width?: GridWidth;
   /** Id de la sección/pestaña del layout a la que pertenece (base.md §4). */
   section?: string;
@@ -84,9 +94,18 @@ export interface FieldBase<T> {
    * verificar en cada petición.
    */
   access?: {
+    /** Código de nivel de acceso requerido para leer el campo. */
     read?: string;
+    /** Código de nivel de acceso requerido para escribir el campo. */
     write?: string;
   };
+  /**
+   * Descripción corta de para qué sirve este campo. Se muestra como tooltip
+   * al pasar el cursor sobre el rótulo en el formulario y la ficha.
+   */
+  description?: string;
+  /** URL de documentación externa para este campo (se abre al hacer clic en el tooltip). */
+  docLink?: string;
 }
 export interface SelectOption {
   value: string;
@@ -98,6 +117,9 @@ export interface TextField extends FieldBase<string> {
   maxLength?: number;
   pattern?: string;
 }
+export interface ColorField extends FieldBase<string> {
+  type: 'color';
+}
 export interface TextareaField extends FieldBase<string> {
   type: 'textarea';
   rows?: number;
@@ -169,6 +191,55 @@ export type SelectField = FieldBase<string> & {
 export type MultiselectField = FieldBase<string[]> & {
   type: 'multiselect';
 } & SelectData;
+/**
+ * Desplegable nativo (`<select>`) que SIEMPRE se renderiza como lista
+ * desplegable, independientemente de cuántas opciones tenga.
+ *
+ * A diferencia de `select` (que usa radio buttons para 2–4 opciones
+ * estáticas por la guía de control §1), este tipo nunca muta a radios.
+ * Úsalo cuando necesites un dropdown verdadero aunque tenga pocas opciones.
+ */
+export interface DropdownField extends FieldBase<string> {
+  type: 'dropdown';
+  options: SelectOption[];
+}
+/**
+ * Opción de un selector visual enriquecido (`rich-select`).
+ *
+ * Además de `value`/`label`, cada opción puede declarar una `preview` con
+ * HTML seguro que el motor renderiza como tarjeta visual (badge, chip con
+ * icono, color swatch, etc.). El HTML viaja en el schema y el motor lo
+ * pinta tal cual tras pasar por el sanitizador de Angular.
+ */
+export interface RichSelectOption {
+  value: string;
+  label: string;
+  disabled?: boolean;
+  /** HTML seguro para pintar como preview de la opción (ej. `<span class="chip">…</span>`). */
+  preview?: string;
+}
+/**
+ * Selector visual enriquecido: cada opción se renderiza como tarjeta con su
+ * `preview` HTML en vez de un `<select>` nativo o radio buttons planos.
+ * Sólo opciones estáticas (sin `source`).
+ */
+export interface RichSelectField extends FieldBase<string> {
+  type: 'rich-select';
+  options: RichSelectOption[];
+  /**
+   * Ancho de cada tarjeta de opción en la grilla (1–12), igual que `width`
+   * de un campo. Por defecto `4` (3 tarjetas por fila en escritorio).
+   * Úsalo para opciones con preview larga (menos tarjetas por fila) o
+   * preview corta (más tarjetas).
+   */
+  cardWidth?: GridWidth;
+  /**
+   * Cuántas tarjetas mostrar por fila en el punto de ruptura `lg`.
+   * Sobrescribe el cálculo automático basado en `cardWidth`.
+   * Ejemplo: `2` obliga a 2 columnas grandes sin importar el ancho.
+   */
+  cardCols?: 1 | 2 | 3 | 4 | 5 | 6;
+}
 export interface UrlField extends FieldBase<string> {
   type: 'url';
 }
@@ -322,6 +393,12 @@ export interface WidgetBase {
   help?: string;
   /** Ancho en la grilla del panel (1–12), igual que un campo. */
   width?: GridWidth;
+  /**
+   * Ancho en la grilla en mobile (1–12). Por defecto `12` (ancho completo,
+   * apilado). Declararlo permite controlar el layout responsive en pantallas
+   * chicas sin tocar el ancho de escritorio (`width`).
+   */
+  mobileWidth?: GridWidth;
   /**
    * De dónde saca sus datos (F8 · R6.5).
    *
@@ -400,7 +477,7 @@ export interface StatusProgressWidget extends WidgetBase {
 }
 export type WidgetSchema = MetricCardWidget | BarChartWidget | ChartLineWidget | RecordListWidget | QuickActionsWidget | StatusProgressWidget;
 export type WidgetType = WidgetSchema['type'];
-export type FieldSchema = TextField | TextareaField | SlugField | NumberField | CurrencyField | BooleanField | SelectField | MultiselectField | UrlField | EmailField | PhoneField | DateField | TimeField | ReadonlyTextField | RelationField | ImageField | FileField | GroupField | ListField | StringListField | KeyValueField;
+export type FieldSchema = TextField | TextareaField | SlugField | NumberField | CurrencyField | BooleanField | SelectField | MultiselectField | RichSelectField | DropdownField | UrlField | EmailField | PhoneField | DateField | TimeField | ReadonlyTextField | RelationField | ImageField | FileField | GroupField | ListField | StringListField | KeyValueField | ColorField;
 export type FieldType = FieldSchema['type'];
 export type ListColumnFormat = 'text' | 'badge' | 'thumbnail' | 'boolean' | 'number' | 'currency' | 'date';
 export interface ListColumn {
@@ -496,8 +573,19 @@ export interface ResourcePermissions {
 }
 /**
  * Rutas de la API relativas a `API_URL` (base.md §3, api.md §6 Opción A).
- * Pueden incluir el marcador `{key}`. Los singleton solo usan
- * `get` / `update`.
+ *
+ * Marcadores que un path acepta — se resuelven ANTES de despachar la petición
+ * (y para ambos drivers):
+ *
+ * - `{key}` — clave del registro actual; sólo aplica a las operaciones con
+ *   clave (`get`, `update`, `remove`). Si llega sin resolver, es error.
+ * - `{<fuente>}` / `{<fuente>.<ruta.anidada>}` — valor de una fuente de
+ *   contexto: las construidas `auth` (sesión) y `config` (config global), o
+ *   cualquier fuente registrada en `provideGasAdmin({ valueSources })`.
+ *
+ * El valor se codifica como segmento de URL. Un marcador sin valor, o con una
+ * fuente no registrada, lanza un error que nombra el path y el marcador: nunca
+ * se envía un segmento vacío. Los singleton solo usan `get` / `update`.
  */
 export interface ResourceEndpoints {
   list?: string;
@@ -505,6 +593,79 @@ export interface ResourceEndpoints {
   create?: string;
   update?: string;
   remove?: string;
+  /**
+   * Declaración opcional de cómo unwrappear la respuesta de esta operación.
+   * Cuando se declara, el motor extrae el contenido de `dataKey` antes de
+   * devolverlo al consumidor (ej.: `{ data: [...] }` → `[...]`).
+   * Si no se declara, el motor mantiene el comportamiento actual:
+   * respuesta pasada tal cual (array plano, `{ items }`, o objeto crudo).
+   * Esta declaración es por operación; si se desea un valor global, usarlo
+   * en cada operación o considerar un default a nivel de config en futuro.
+   */
+  responseUnwrap?: ResponseUnwrap;
+}
+/**
+ * Cómo el motor debe desempaquetar la respuesta HTTP antes de entregarla.
+ * Opcional y opt-in: schemas sin este campo siguen el contrato actual.
+ *
+ * - `dataKey`: clave en el body que contiene el payload real (ej. `data`,
+ *   `items`, `result`). Si el body no tiene esta clave, se devuelve `undefined`
+ *   para lista / objeto vacío según corresponda, y se lanza error en modo
+ *   estricto si se configura.
+ * - `metaKey`: clave con metadatos (paginación, total, etc.). Se ignora en
+ *   el valor devuelto al consumidor pero puede leerse si el motor la expone
+ *   en futuro.
+ * - `apply`: `'list' | 'get' | 'create' | 'update' | 'remove' | 'all'`.
+ *   Qué operaciones aplican el unwrap. Por defecto `'all'` cuando se declara.
+ */
+export interface ResponseUnwrap {
+  dataKey: string;
+  metaKey?: string;
+  apply?: 'list' | 'get' | 'create' | 'update' | 'remove' | 'all';
+  /**
+   * Claves de metadata de paginación dentro del sobre. Usadas por
+   * `ApiService.listPage()` para armar `PageResult<T>`. Opcional: sin
+   * declaración, el motor intenta auto-detectar claves comunes
+   * (`nextCursor`, `total`, `hasMore`) y, si no hay, `hasMore = false`.
+   */
+  pagination?: {
+    /** Clave del cursor siguiente dentro de `meta` (o del body si no hay `metaKey`). */
+    cursorKey?: string;
+    /** Clave del total de registros. */
+    totalKey?: string;
+    /** Clave del flag booleano "hay más páginas". */
+    hasMoreKey?: string;
+  };
+}
+/**
+ * Método HTTP soportado por endpoints personalizados.
+ * Declarado aquí (y no en api.service.ts) para evitar ciclos de importación
+ * entre modelos y servicios.
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Definición de un endpoint personalizado más allá de los cinco estándar
+ * (list/get/create/update/remove). Permite al consumidor declarar rutas con
+ * verbos arbitrarios, segmentos extra, payloads JSON o multipart, y unwrap de
+ * respuesta propio.
+ *
+ * Ejemplo:
+ *   name: 'recalculate-ranks'
+ *   method: 'POST'
+ *   path: '/admin/businesses/{businessId}/ranks/recalculate'
+ *   payloadMode: 'json'
+ */
+export interface CustomEndpointDefinition {
+  /** Nombre único del endpoint dentro del recurso. Se usa para invocarlo. */
+  name: string;
+  /** Método HTTP de la petición. */
+  method: HttpMethod;
+  /** Ruta relativa a `API_URL`. Puede incluir marcadores {key}, {auth.user.id}, etc. */
+  path: string;
+  /** Modo de payload: 'json' (default) o 'multipart' para FormData. */
+  payloadMode?: 'json' | 'multipart';
+  /** Unwrap de respuesta override para este endpoint. Si no se declara, se usa el del recurso. */
+  responseUnwrap?: ResponseUnwrap;
 }
 export interface ResourceSchema {
   /** Identificador interno (`categories`). */
@@ -522,6 +683,8 @@ export interface ResourceSchema {
   keyField: string;
   /** Campo que se muestra como nombre del registro. */
   titleField: string;
+  /** Endpoints personalizados más allá de list/get/create/update/remove. */
+  customEndpoints?: Record<string, CustomEndpointDefinition>;
   /** Si el listado se reordena (requiere `positionField`). */
   sortable?: boolean;
   positionField?: string;
@@ -799,24 +962,99 @@ export interface AuthSchema {
   firebase?: FirebaseAuthConfig;
 }
 /**
- * Narrow surface the library uses from Firebase Auth.
- * Implemented by the consumer app; injected via FIREBASE_AUTH_ADAPTER token.
- * Keeping the interface thin avoids coupling to any specific Firebase version.
+ * URL base de la API (baseapi §2.3): es la URL directa del Web App de Apps
+ * Script; ahí se hace el `POST` del envelope `{ token, method, path, payload }`.
+ * OBLIGATORIO proporcionarlo en `app.config.ts`:
+ * `{ provide: API_URL, useValue: 'https://…' }` (Fase 3). Vacío = mismo origen.
+ */
+export declare const API_URL: InjectionToken<string>;
+/**
+ * Superficie mínima que `gas-admin-ui` usa de Firebase Auth.
+ * Implementada por la aplicación consumidora; inyectada vía `FIREBASE_AUTH_ADAPTER`.
+ * Mantener la interfaz fina evita acoplar la librería a una versión específica de Firebase.
  */
 interface FirebaseAuthAdapter {
   /**
-   * Opens a Google sign-in popup and resolves to the Firebase ID token.
-   * Rejects on cancellation or error.
+   * Abre un popup de Google sign-in y resuelve al ID token de Firebase.
+   * Rechaza si el usuario cancela o hay error.
    */
   signInWithGoogle(): Promise<string>;
   /**
-   * Signs in with email and password via Firebase and resolves to the ID token.
-   * Used when provider === 'password' AND firebase is configured (Firebase email auth).
+   * Inicia sesión con email y contraseña vía Firebase y resuelve al ID token.
+   * Se usa cuando provider === 'password' Y firebase está configurado (Firebase email auth).
    */
   signInWithEmailAndPassword(email: string, password: string): Promise<string>;
-  /** Signs out from Firebase (called alongside the app session clear). */
+  /**
+   * Cierra sesión en Firebase (llamado junto al clear de la sesión de la app).
+   */
   signOut(): Promise<void>;
+  /**
+   * Obtiene un ID token de Firebase FRESCO para usarlo en la cabecera
+   * `Authorization: Bearer <token>` de las peticiones REST.
+   *
+   * OPCIONAL: si el adaptador no lo implementa, `gas-admin-ui` envía el token
+   * de sesión almacenado tal cual (comportamiento actual). Implementarlo
+   * permite refrescar el ID token antes de cada petición REST, evitando
+   * errores "ID token inválido" tras la expiración de Firebase (1 hora).
+   *
+   * El adaptador decide cuándo refrescar (p. ej. `getIdToken(true)` de Firebase
+   * SDK fuerza la renovación; sin argumento devuelve el cacheado si aún es válido).
+   */
+  getIdToken?(): Promise<string>;
 }
+/**
+ * Token DI opcional para el adaptador de Firebase Auth.
+ * Proporcionado por la aplicación consumidora cuando usa proveedores federados o Firebase Auth.
+ */
+export declare const FIREBASE_AUTH_ADAPTER: InjectionToken<FirebaseAuthAdapter>;
+/**
+ * Driver de transporte HTTP del motor.
+ *
+ * Vive acá (capa de infraestructura) y NO en `ResourceSchema` (capa de dominio)
+ * porque es una decisión de red, no de modelo de datos. Cambiar el driver
+ * no debería requerir tocar ningún schema de recursos.
+ *
+ * - `'gas'` (default): tunnel `POST text/plain` con envelope
+ *   `{ token, method, path, payload }` — contrato de Google Apps Script.
+ * - `'rest'`: verbos HTTP reales (`GET`, `POST`, `PUT`, `DELETE`) con
+ *   `Authorization: Bearer <token>` en cabeceras y params en la URL (GET/DELETE)
+ *   o en el body JSON (POST/PUT/PATCH).
+ *
+ * Se fija en `provideGasAdmin({ driver })`. Sin declaración explícita el
+ * motor usa `'gas'` — cero impacto para consumidores existentes.
+ */
+export declare const API_DRIVER: InjectionToken<"gas" | "rest">;
+/**
+ * Registro de FUENTES DE CONTEXTO para marcadores en paths de endpoints.
+ *
+ * Cada clave es el nombre de una fuente — `{ <fuente> }` o
+ * `{ <fuente>.<ruta.anidada> }` dentro de un path declarado en
+ * `ResourceEndpoints` — y cada valor es un getter sin argumentos que devuelve
+ * el dato ACTUAL en el momento de la petición (no al registrar).
+ *
+ * El motor ya aporta dos fuentes construidas y éstas NO se declaran acá:
+ *
+ * - `auth`  → la sesión que dueña `AuthService` (usuario y token).
+ * - `config` → el mapa global que puebla `ConfigService` desde los singletons.
+ *
+ * Este registro es sólo para fuentes que aporta el consumidor, para que el
+ * motor no conozca nombres de dominio: qué campo se lee lo decide el schema,
+ * no el engine.
+ *
+ * Un marcador que apunte a una fuente no registrada, o a un valor ausente,
+ * revienta con un error que nombra el path y el marcador — jamás se manda un
+ * segmento vacío al backend.
+ */
+type ValueSources = Readonly<Record<string, () => unknown>>;
+export declare const VALUE_SOURCES: InjectionToken<Readonly<Record<string, () => unknown>>>;
+/**
+ * Unwrap de respuesta global por defecto (`GasAdminConfig.defaultResponseUnwrap`).
+ *
+ * Se fusiona con la declaración `endpoint.responseUnwrap` de cada recurso:
+ * la del recurso tiene prioridad en las claves que declara. Sin token, sólo
+ * aplica lo declarado por recurso — cero impacto en schemas existentes.
+ */
+export declare const DEFAULT_RESPONSE_UNWRAP: InjectionToken<ResponseUnwrap>;
 /** Fija el catálogo (uso interno de `provideGasAdmin`; testable directo). */
 export declare function setSchemaCatalog(schemas: readonly ResourceSchema[], auth?: AuthSchema): void;
 /** Busca un schema por `id`; `undefined` si no existe. */
@@ -842,6 +1080,23 @@ interface GasAdminConfig {
    * Sin declaración el motor usa `'gas'` — cero impacto en consumidores existentes.
    */
   driver?: 'gas' | 'rest';
+  /**
+   * Fuentes de contexto que el consumidor aporta para marcadores en paths de
+   * endpoints: `{ <fuente> }` / `{ <fuente>.<ruta> }` se resuelven en el
+   * momento de la petición contra este registro más las fuentes construidas
+   * `auth` (sesión) y `config` (config global).
+   *
+   * Opcional: sin él, sólo existen `auth` y `config`. Declararlo no cambia
+   * ningún path que no lleve marcadores — cero impacto en schemas existentes.
+   */
+  valueSources?: ValueSources;
+  /**
+   * Unwrap de respuesta global por defecto. Se fusiona con la declaración
+   * `endpoint.responseUnwrap` de cada recurso (la del recurso tiene prioridad
+   * en claves declaradas). Opcional: sin él, sólo aplica lo declarado por
+   * recurso — cero impacto en schemas existentes (R2).
+   */
+  defaultResponseUnwrap?: ResponseUnwrap;
 }
 /**
  * Wiring completo del motor: catálogo + HTTP con el interceptor de
@@ -926,34 +1181,22 @@ export declare class ApiError extends Error {
  */
 export declare function renewedTokenOf(body: unknown): string | null;
 /**
- * URL base de la API (baseapi §2.3): es la URL directa del Web App de Apps
- * Script; ahí se hace el `POST` del envelope `{ token, method, path, payload }`.
- * OBLIGATORIO proporcionarlo en `app.config.ts`:
- * `{ provide: API_URL, useValue: 'https://…' }` (Fase 3). Vacío = mismo origen.
- */
-export declare const API_URL: InjectionToken<string>;
-/**
- * Token DI opcional para el adaptador de Firebase Auth.
- * Proporcionado por la aplicación consumidora cuando usa proveedores federados o Firebase Auth.
- */
-export declare const FIREBASE_AUTH_ADAPTER: InjectionToken<FirebaseAuthAdapter>;
-/**
- * Driver de transporte HTTP del motor.
- *
- * Vive acá (capa de infraestructura) y NO en `ResourceSchema` (capa de dominio)
- * porque es una decisión de red, no de modelo de datos. Cambiar el driver
- * no debería requerir tocar ningún schema de recursos.
+ * Resultado de una página para `ApiService.listPage()`.
  *
- * - `'gas'` (default): tunnel `POST text/plain` con envelope
- *   `{ token, method, path, payload }` — contrato de Google Apps Script.
- * - `'rest'`: verbos HTTP reales (`GET`, `POST`, `PUT`, `DELETE`) con
- *   `Authorization: Bearer <token>` en cabeceras y params en la URL (GET/DELETE)
- *   o en el body JSON (POST/PUT/PATCH).
- *
- * Se fija en `provideGasAdmin({ driver })`. Sin declaración explícita el
- * motor usa `'gas'` — cero impacto para consumidores existentes.
+ * 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 declare const API_DRIVER: InjectionToken<"gas" | "rest">;
+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;
+}
 /**
  * Guards de sesión (auth.md §5.3).
  *
@@ -1062,6 +1305,40 @@ export declare class NotificationService {
 }
 /** Métodos que entiende el envelope del backend (baseapi §2.3). */
 type EnvelopeMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** Dependencias del transporte, aportadas por la fachada (no hay singleton acá). */
+interface TransportDeps {
+  http: HttpClient;
+  /** URL base (`API_URL`): el Web App de Apps Script o el origen REST. */
+  apiUrl: string;
+  /** Getter del token de SESIÓN, leído en CADA petición (R2.8). */
+  sessionToken: () => string | null;
+  /**
+   * Refresco opcional de ID token (Fase Firebase): si existe, se llama antes
+   * de armar la cabecera Authorization. Un rechazo viaja por el canal de
+   * errores — nunca se manda una petición con token inválido.
+   */
+  getIdToken?: () => Promise<string>;
+}
+/** `POST text/plain` a `apiUrl` con el envelope GAS. */
+declare function sendGas<T>(deps: TransportDeps, path: string, method: EnvelopeMethod, payload?: Record<string, unknown> | FormData, multipart?: boolean): Observable<T>;
+/**
+ * Verbo HTTP real con `Authorization: Bearer`. Si el adaptador provee
+ * `getIdToken()`, se resuelve el token fresco ANTES de la cabecera; si no,
+ * se usa el de sesión almacenado (fallback). Cualquier error de `getIdToken()`
+ * se propaga por el canal de errores.
+ */
+declare function sendRest<T>(deps: TransportDeps, path: string, method: EnvelopeMethod, payload?: Record<string, unknown> | FormData, multipart?: boolean): Observable<T>;
+/** Despacho REST concreto sobre una URL ya construida. */
+declare function doRestRequest<T>(deps: TransportDeps, url: string, method: EnvelopeMethod, payload: Record<string, unknown> | FormData | undefined, headers?: HttpHeaders, multipart?: boolean): Observable<T>;
+/** `${apiUrl}${path}` normalizada: sin dobles slashes ni path sin slash inicial. */
+declare function buildUrl(apiUrl: string, path: string): string;
+/**
+ * Convierte un payload en HttpParams para peticiones GET y DELETE en modo REST.
+ * Si un valor es un objeto plano (ej: `{ view: 'calendar', params: { orden: 'es' } }`),
+ * lo aplana un nivel para que sus claves viajen como query params reales
+ * en lugar de serializarse como `params=[object Object]`.
+ */
+declare function toHttpParams(payload?: Record<string, unknown>): HttpParams;
 /**
  * CRUD genérico sobre el contrato v2 (baseapi §2.3) con soporte dual-driver:
  *
@@ -1077,6 +1354,28 @@ export declare class ApiService {
   private readonly apiUrl;
   private readonly auth;
   private readonly driver;
+  /** Fuentes que aporta el consumidor (`provideGasAdmin({ valueSources })`). */
+  private readonly valueSources;
+  /** Adaptador opcional de Firebase Auth para refrescar el ID token antes de peticiones REST. */
+  private readonly firebaseAuthAdapter;
+  /**
+   * Acceso PEREZOSO a `ConfigService` (R2 · plan doc/context-sources-plan.md).
+   *
+   * `config` es fuente construida del motor, pero inyectarla en el constructor
+   * formaría un ciclo: `ConfigService` inyecta `ApiService` (opcional) para
+   * cargar los singletons ⇒ NG0200 en el arranque. Se pide en el momento de la
+   * petición, cuando ambos servicios ya están vivos. Si no existe (TestBed
+   * parcial), devuelve `null` y el resolver falla ruidoso con «sin valor».
+   */
+  private readonly injector;
+  /** Unwrap global por defecto (`GasAdminConfig.defaultResponseUnwrap`); opcional. */
+  private readonly defaultUnwrap;
+  /**
+   * Declaración de unwrap EFECTIVA para un endpoint: fusión del default
+   * global con la declaración por recurso (recurso gana en las claves que
+   * declara). Sin ninguna de las dos ⇒ `undefined` (comportamiento actual).
+   */
+  private effectiveUnwrap;
   /**
    * Listado. El backend envuelve la respuesta cuando la operación declara
    * `shape.envelope: 'list'` (F5) ⇒ `{ items, nextCursor, total }` (R6.4);
@@ -1092,6 +1391,21 @@ export declare class ApiService {
    * llamada es la de siempre — la lectura llana del recurso.
    */
   list<T>(endpoint: ResourceEndpoints, payload?: Record<string, unknown>): Observable<T[]>;
+  /**
+   * Listado paginado OPT-IN (plan doc/engine-refactor-plan.md · Fase 3).
+   *
+   * Misma petición que `list()` pero devuelve `PageResult<T>` con la metadata
+   * de paginación que el backend envía en el sobre (`{ items, nextCursor,
+   * total }` o dentro de `meta` con unwrap declarado). Las claves se leen
+   * según `responseUnwrap.pagination` (cursorKey/totalKey/hasMoreKey) o se
+   * auto-detectan (`nextCursor`, `total`, `hasMore`).
+   *
+   * `payload` acepta normalmente `{ cursor, limit }` para pedir la página
+   * siguiente; viaja como cualquier otro payload (query params en GET REST,
+   * campo `payload` del envelope en GAS). `list()` no cambia: sigue
+   * devolviendo `T[]` (R11).
+   */
+  listPage<T>(endpoint: ResourceEndpoints, payload?: Record<string, unknown>): Observable<PageResult<T>>;
   /** `key` solo aplica a colecciones (`{key}` en la plantilla); los singleton no la llevan. */
   get<T>(endpoint: ResourceEndpoints, key?: string): Observable<T>;
   create<T>(endpoint: ResourceEndpoints, payload: Record<string, unknown>): Observable<T>;
@@ -1103,10 +1417,34 @@ export declare class ApiService {
    * `/admin/upload-signature`, etc.
    */
   request<T>(method: EnvelopeMethod, path: string | undefined, payload?: Record<string, unknown>): Observable<T>;
+  /**
+   * Invoca un endpoint personalizado declarado por el consumidor.
+   *
+   * Acepta bien la definición directa (`CustomEndpointDefinition`) o un schema
+   * + nombre (resuelve en `schema.customEndpoints`). El despacho respeta el
+   * método, la ruta, el modo de payload (json/multipart) y el unwrap propios
+   * de la declaración.
+   */
+  invokeCustomEndpoint<T>(definitionOrSchema: CustomEndpointDefinition | ResourceSchema, nameOrPayload?: string | Record<string, unknown> | FormData, payload?: Record<string, unknown> | FormData, key?: string): Observable<T>;
+  /** Alias corto de `invokeCustomEndpoint`. */
+  invokeCustom<T>(schemaOrDefinition: ResourceSchema | CustomEndpointDefinition, nameOrPayload?: string | Record<string, unknown> | FormData, payload?: Record<string, unknown> | FormData, key?: string): Observable<T>;
+  /** Alias adicional por compatibilidad. */
+  custom<T>(schemaOrDefinition: ResourceSchema | CustomEndpointDefinition, nameOrPayload?: string | Record<string, unknown> | FormData, payload?: Record<string, unknown> | FormData, key?: string): Observable<T>;
   private send;
-  private sendGas;
-  private sendRest;
-  private buildUrl;
+  /**
+   * Dependencias del transporte (Fase 4): la fachada sólo arma este objeto y
+   * delega en `transport.ts`. El token de sesión y el ID token fresco se
+   * resuelven vía getters en el momento de la petición (R2.8 / refresh).
+   */
+  private transportDeps;
+  /**
+   * Fuentes de contexto de ESTA petición: getters, no valores — se evalúan
+   * sólo si el path trae marcadores.
+   *
+   * Las construidas del motor (`auth`, `config`) van ÚLTIMAS: el motor es
+   * dueño de sus fuentes y el registro del consumidor no las pisa.
+   */
+  private buildSources;
   private withKey;
   static ɵfac: i0.ɵɵFactoryDeclaration<ApiService, never>;
   static ɵprov: i0.ɵɵInjectableDeclaration<any>;
@@ -1204,10 +1542,6 @@ export declare class AuthService {
    * que deja una sesión muerta en el servidor.
    */
   logout(): Observable<void>;
-  /** Revoca las sesiones del usuario en todos sus dispositivos. */
-  logoutAll(): Observable<{
-    effectiveWithinSeconds: number;
-  }>;
   /** Revalida la sesión restaurada contra `/auth/me`; sin token ⇒ sin viaje. */
   restore(): Observable<void>;
   /**
@@ -1454,14 +1788,14 @@ export declare class Sidebar {
   private readonly auth;
   private readonly notifications;
   readonly isAuthenticated: import("@angular/core").Signal<boolean>;
-  readonly closingAllSessions: import("@angular/core").WritableSignal<boolean>;
+  readonly loggingOut: import("@angular/core").WritableSignal<boolean>;
   /**
    * R2.10 — el menú se corta dos veces: `isVisible` (permisos declarados
    * en el schema) y `canAccess` (auth.md §5.3, `access` de la sesión).
    * Sólo UX: filtrar acá no protege nada, el back re-verifica en R2.6.
    */
   readonly menuItems: import("@angular/core").Signal<MenuEntry[]>;
-  closeAllSessions(): Promise<void>;
+  closeSession(): Promise<void>;
   static ɵfac: i0.ɵɵFactoryDeclaration<Sidebar, never>;
   static ɵcmp: i0.ɵɵComponentDeclaration<Sidebar, "app-sidebar", never, {
     "open": {
@@ -2949,7 +3283,7 @@ export declare class Toast {
  * aserción en el **mismo archivo**: añadir un tipo toca una carpeta y una
  * línea de este manifiesto, y el host no se entera.
  */
-export declare const SUPPORTED_FIELD_TYPE_LIST: readonly ["text", "textarea", "slug", "number", "currency", "boolean", "select", "multiselect", "url", "email", "phone", "date", "time", "readonly-text", "group", "list", "string-list", "key-value", "relation", "image", "file"];
+export declare const SUPPORTED_FIELD_TYPE_LIST: readonly ["text", "textarea", "slug", "number", "currency", "boolean", "select", "multiselect", "url", "email", "phone", "date", "time", "readonly-text", "group", "list", "string-list", "key-value", "relation", "image", "file", "color", "rich-select", "dropdown"];
 /**
  * Manifiesto de descriptores de campo (R3.3 · registro único de render).
  *
@@ -3186,4 +3520,4 @@ export declare function actionsFor(surface: ActionSurface): ActionDescriptor[];
 export declare function actionType(action: ResourceAction): string;
 /** Tipos registrados. Sólo para comprobaciones y tests. */
 export declare function actionTypes(): string[];
-export { type ComponentRenderKind, type FirebaseAuthAdapter, type GasAdminConfig, type RenderKind, type ResolvedShare, type ValidatorName, get as getRenderDescriptor, isSupported as isRenderSupported, register as registerRenderDescriptor, unregister as unregisterRenderDescriptor };
+export { type ComponentRenderKind, type FirebaseAuthAdapter, type GasAdminConfig, type RenderKind, type ResolvedShare, type ValidatorName, type ValueSources, get as getRenderDescriptor, isSupported as isRenderSupported, register as registerRenderDescriptor, unregister as unregisterRenderDescriptor };