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

package/src/lib/core/services/api.service.ts

@@ -0,0 +1,371 @@
+import { HttpClient } from '@angular/common/http';
+import { inject, Injector, Service } from '@angular/core';
+import { map, Observable, tap, throwError } from 'rxjs';
+
+import { renewedTokenOf } from '../models/api.model';
+import type { PageResult } from '../models/api.model';
+import type { CustomEndpointDefinition, ResourceEndpoints, ResourceSchema, ResponseUnwrap } from '../models/schema.model';
+import { extractPagination, unwrapResponse } from '../utils/response-unwrapper';
+import { DEFAULT_RESPONSE_UNWRAP, API_DRIVER, API_URL, FIREBASE_AUTH_ADAPTER, VALUE_SOURCES } from '../tokens';
+import type { ValueSources } from '../tokens';
+import { resolveEndpointPath } from '../utils/context-resolver';
+import { sendGas, sendRest, type EnvelopeMethod, type TransportDeps } from './transport';
+import { ConfigService } from './config.service';
+import { AuthService } from './auth.service';
+
+export type { EnvelopeMethod } from './transport';
+
+/**
+ * CRUD genérico sobre el contrato v2 (baseapi §2.3) con soporte dual-driver:
+ *
+ * - **`gas` (default)**: TODA llamada a la API es un `POST` a `API_URL` con cuerpo
+ *   `text/plain` y el JSON `{ token, method, path, payload }`.
+ * - **`rest`**: Verbos HTTP reales (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) hacia
+ *   `${API_URL}${path}` con `Authorization: Bearer ${token}`. `payload` va como query
+ *   params en GET/DELETE (aplanando objetos anidados como `params`) o como body JSON
+ *   en POST/PUT/PATCH.
+ */
+@Service()
+export class ApiService {
+  private readonly http = inject(HttpClient);
+  private readonly apiUrl = inject(API_URL);
+  private readonly auth = inject(AuthService);
+  private readonly driver = inject(API_DRIVER, { optional: true }) ?? 'gas';
+  /** Fuentes que aporta el consumidor (`provideGasAdmin({ valueSources })`). */
+  private readonly valueSources: ValueSources = inject(VALUE_SOURCES, { optional: true }) ?? {};
+  /** Adaptador opcional de Firebase Auth para refrescar el ID token antes de peticiones REST. */
+  private readonly firebaseAuthAdapter = inject(FIREBASE_AUTH_ADAPTER, { optional: true });
+  /**
+   * 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 = inject(Injector);
+  /** Unwrap global por defecto (`GasAdminConfig.defaultResponseUnwrap`); opcional. */
+  private readonly defaultUnwrap: ResponseUnwrap | undefined = inject(
+    DEFAULT_RESPONSE_UNWRAP,
+    { optional: true },
+  ) ?? undefined;
+
+  /**
+   * 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(endpoint: ResourceEndpoints): ResponseUnwrap | undefined {
+    const global = this.defaultUnwrap;
+    const local = endpoint.responseUnwrap;
+    if (!global) return local;
+    if (!local) return global;
+    return { ...global, ...local };
+  }
+
+  /**
+   * Listado. El backend envuelve la respuesta cuando la operación declara
+   * `shape.envelope: 'list'` (F5) ⇒ `{ items, nextCursor, total }` (R6.4);
+   * la UI consume `T[]` en todos lados (F7-3) y este es el ÚNICO punto que
+   * habla de listas, así que el desenvolvimiento vive acá. `nextCursor` es
+   * el token de la página siguiente y `null` en la última — éste servicio
+   * lo descarta hoy porque la lista no pagina todavía (backlog-ui-ux).
+   * Un listado sin envelope (arreglo plano, el contrato histórico) pasa
+   * tal cual.
+   *
+   * `payload` sólo lo usa una fuente declarada (F8 · R6.5): `{ view, params }`
+   * pide el listado filtrado por una vista y sus parámetros. Sin él, la
+   * llamada es la de siempre — la lectura llana del recurso.
+   */
+  list<T>(endpoint: ResourceEndpoints, payload?: Record<string, unknown>): Observable<T[]> {
+    const unwrap = this.effectiveUnwrap(endpoint);
+    return this.send<unknown>(endpoint.list, 'GET', payload).pipe(
+      map((raw) => {
+        if (unwrap && (unwrap.apply === 'list' || unwrap.apply === 'all' || !unwrap.apply)) {
+          return unwrapResponse(raw, unwrap, 'list') as T[];
+        }
+        return unwrapList<T>(raw);
+      }),
+    );
+  }
+
+  /**
+   * 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>> {
+    const unwrap = this.effectiveUnwrap(endpoint);
+    const applies = !unwrap || unwrap.apply === 'list' || unwrap.apply === 'all' || !unwrap.apply;
+    return this.send<unknown>(endpoint.list, 'GET', payload).pipe(
+      map((raw) => {
+        const items =
+          unwrap && applies
+            ? (unwrapResponse(raw, unwrap, 'list') as T[])
+            : unwrapList<T>(raw);
+        return { items, ...extractPagination(raw, unwrap) };
+      }),
+    );
+  }
+
+  /** `key` solo aplica a colecciones (`{key}` en la plantilla); los singleton no la llevan. */
+  get<T>(endpoint: ResourceEndpoints, key?: string): Observable<T> {    const unwrap = this.effectiveUnwrap(endpoint);
+    return this.send<unknown>(this.withKey(endpoint.get, key), 'GET').pipe(
+      map((raw) => {
+        if (unwrap && (unwrap.apply === 'get' || unwrap.apply === 'all' || !unwrap.apply)) {
+          return unwrapResponse(raw, unwrap, 'get') as T;
+        }
+        return raw as T;
+      }),
+    );
+  }
+
+  create<T>(endpoint: ResourceEndpoints, payload: Record<string, unknown>): Observable<T> {
+    const unwrap = this.effectiveUnwrap(endpoint);
+    return this.send<unknown>(endpoint.create, 'POST', payload).pipe(
+      map((raw) => {
+        if (unwrap && (unwrap.apply === 'create' || unwrap.apply === 'all' || !unwrap.apply)) {
+          return unwrapResponse(raw, unwrap, 'create') as T;
+        }
+        return raw as T;
+      }),
+    );
+  }
+
+  update<T>(
+    endpoint: ResourceEndpoints,
+    key: string | undefined,
+    payload: Record<string, unknown>,
+  ): Observable<T> {
+    const unwrap = this.effectiveUnwrap(endpoint);
+    return this.send<unknown>(this.withKey(endpoint.update, key), 'PUT', payload).pipe(
+      map((raw) => {
+        if (unwrap && (unwrap.apply === 'update' || unwrap.apply === 'all' || !unwrap.apply)) {
+          return unwrapResponse(raw, unwrap, 'update') as T;
+        }
+        return raw as T;
+      }),
+    );
+  }
+
+  remove(endpoint: ResourceEndpoints, key?: string): Observable<void> {
+    const unwrap = endpoint.responseUnwrap;
+    return this.send<unknown>(this.withKey(endpoint.remove, key), 'DELETE').pipe(
+      map(() => void 0),
+    );
+  }
+
+  /**
+   * Operación genérica sobre una ruta ya resuelta: reorder de colección
+   * (`PUT /admin/x` con `{ reorder: … }`), `/admin/schema`,
+   * `/admin/upload-signature`, etc.
+   */
+  request<T>(
+    method: EnvelopeMethod,
+    path: string | undefined,
+    payload?: Record<string, unknown>,
+  ): Observable<T> {
+    const dataKey = this.defaultUnwrap?.dataKey ?? 'data';
+    return this.send<T>(path, method, payload).pipe(
+      map((raw: unknown) => {
+        // Desenvolvimiento passthrough (como el interceptor viejo): sólo si la
+        // respuesta trae la clave `data`, se desenvuelve; si no, pasa tal cual.
+        // Evita romper endpoints que no envuelven (ej. upload-signature).
+        if (raw !== null && typeof raw === 'object' && !Array.isArray(raw)) {
+          const rec = raw as Record<string, unknown>;
+          if (Object.prototype.hasOwnProperty.call(rec, dataKey)) {
+            return rec[dataKey] as T;
+          }
+        }
+        return raw as 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> {
+    let definition: CustomEndpointDefinition | undefined;
+    let actualPayload: Record<string, unknown> | FormData | undefined;
+    let actualKey: string | undefined = key;
+
+    if (isResourceSchema(definitionOrSchema)) {
+      const name = typeof nameOrPayload === 'string' ? nameOrPayload : undefined;
+      if (!name) {
+        throw new Error('invokeCustomEndpoint requires an endpoint name when given a schema');
+      }
+      definition = definitionOrSchema.customEndpoints?.[name];
+      if (!definition) {
+        throw new Error(`Custom endpoint '${name}' is not declared for resource '${definitionOrSchema.id}'`);
+      }
+      actualPayload = (typeof nameOrPayload === 'string' ? payload : (nameOrPayload as Record<string, unknown> | FormData | undefined)) ?? payload;
+    } else {
+      definition = definitionOrSchema;
+      actualPayload =
+        (nameOrPayload as Record<string, unknown> | FormData | undefined) ?? payload;
+    }
+
+    if (!definition) {
+      return throwError(() => new Error('Custom endpoint definition is required'));
+    }
+
+    const multipart = definition.payloadMode === 'multipart' || actualPayload instanceof FormData;
+    const path = this.withKey(definition.path, actualKey);
+    const method = definition.method;
+
+    const unwrap = definition.responseUnwrap;
+    return this.send<unknown>(path, method, actualPayload, multipart).pipe(
+      map((raw) => {
+        if (unwrap) {
+          return unwrapResponse(raw, unwrap, 'get') as T;
+        }
+        return raw as 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> {
+    return this.invokeCustomEndpoint<T>(schemaOrDefinition, nameOrPayload, payload, key);
+  }
+
+  /** Alias adicional por compatibilidad. */
+  custom<T>(
+    schemaOrDefinition: ResourceSchema | CustomEndpointDefinition,
+    nameOrPayload?: string | Record<string, unknown> | FormData,
+    payload?: Record<string, unknown> | FormData,
+    key?: string,
+  ): Observable<T> {
+    return this.invokeCustomEndpoint<T>(schemaOrDefinition, nameOrPayload, payload, key);
+  }
+
+  private send<T>(
+    path: string | undefined,
+    method: EnvelopeMethod,
+    payload?: Record<string, unknown> | FormData,
+    multipart = false,
+  ): Observable<T> {
+    if (!path) {
+      return throwError(() => new Error('Operación no disponible para este recurso'));
+    }
+
+    // Resolución de marcadores de contexto ANTES del despacho (plan Fase 3):
+    // un solo punto para todas las operaciones y para ambos drivers. Sin
+    // marcadores el path vuelve intacto y ninguna fuente se evalúa.
+    let resolvedPath: string;
+    try {
+      resolvedPath = resolveEndpointPath(path, this.buildSources());
+    } catch (error) {
+      // Fail loud por el CANAL de errores (no como throw síncrono): el
+      // consumidor lo trata como cualquier otro fallo de petición y JAMÁS
+      // sale un request con un segmento vacío o el marcador literal.
+      return throwError(() => error);
+    }
+
+    const deps = this.transportDeps();
+    const request$ =
+      this.driver === 'rest'
+        ? sendRest<T>(deps, resolvedPath, method, payload, multipart)
+        : sendGas<T>(deps, resolvedPath, method, payload, multipart);
+
+    return request$.pipe(
+      // Renovación deslizante (§3.2): si el back adjuntó `meta.renewedToken`
+      // se adopta YA, con lo que la siguiente petición ya va firmada nueva.
+      tap((res) => {
+        const renewed = renewedTokenOf(res);
+        if (renewed !== null) this.auth.applyRenewedToken(renewed);
+      }),
+    );
+  }
+
+  /**
+   * 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(): TransportDeps {
+    const adapter = this.firebaseAuthAdapter;
+    return {
+      http: this.http,
+      apiUrl: this.apiUrl,
+      sessionToken: () => this.auth.token(),
+      getIdToken: adapter?.getIdToken ? () => adapter.getIdToken!() : undefined,
+    };
+  }
+
+  /**
+   * 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(): Readonly<Record<string, () => unknown>> {
+    return {
+      ...this.valueSources,
+      auth: () => ({ user: this.auth.user(), token: this.auth.token() }),
+      config: () => this.injector.get(ConfigService, null)?.globalConfig() ?? null,
+    };
+  }
+
+  private withKey(path: string | undefined, key?: string): string | undefined {
+    if (!path) {
+      return undefined;
+    }
+    return path.includes('{key}') ? path.replace('{key}', encodeURIComponent(key ?? '')) : path;
+  }
+}
+
+/** Guard de forma: ¿es un `ResourceSchema` completo (endpoint + fields)? */
+function isResourceSchema(value: unknown): value is ResourceSchema {
+  return typeof value === 'object' && value !== null && 'endpoint' in value && 'fields' in value;
+}
+
+/** `{ items, nextCursor, total }` (F5/R6.4) → `T[]`; arreglo plano → tal cual. */
+function unwrapList<T>(raw: unknown): T[] {
+  if (Array.isArray(raw)) {
+    return raw as T[];
+  }
+  if (raw !== null && typeof raw === 'object') {
+    const items = (raw as { items?: unknown }).items;
+    if (Array.isArray(items)) {
+      return items as T[];
+    }
+    // Objeto sin clave reconocida: compat con el baseline (R9) ⇒ [].
+    return [];
+  }
+  // Cuerpo ni array ni objeto (null, string, número): el contrato de listado
+  // está roto — fallar ruidoso en vez de devolver [] silenciosamente.
+  throw new Error(
+    `List response must be an array or an object with an 'items' array; received ${raw === null ? 'null' : typeof raw}`,
+  );
+}