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

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

@@ -0,0 +1,1142 @@
+import { provideHttpClient } from '@angular/common/http';
+import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
+import { TestBed } from '@angular/core/testing';
+import { provideRouter } from '@angular/router';
+import { firstValueFrom } from 'rxjs';
+
+import { API_DRIVER, API_URL, VALUE_SOURCES, FIREBASE_AUTH_ADAPTER, DEFAULT_RESPONSE_UNWRAP } from '../tokens';
+import type { FirebaseAuthAdapter } from '../tokens';
+import { ApiService } from './api.service';
+import { AuthService, SESSION_TOKEN_KEY, SESSION_USER_KEY } from './auth.service';
+import { ConfigService } from './config.service';
+
+interface Row {
+  slug: string;
+}
+
+const ENDPOINTS = { list: '/admin/products' };
+
+describe('ApiService — desarrollo del envelope de listado (F7-3)', () => {
+  let api: ApiService;
+  let http: HttpTestingController;
+
+  beforeEach(() => {
+    // La sesión se restaura desde `sessionStorage` (R2.12): sembrarla antes
+    // de inyectar es lo mismo que hacer login y recargar la pestaña.
+    sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok');
+    sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role: 'admin' }));
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(),
+        provideHttpClientTesting(),
+        provideRouter([]),
+        { provide: API_URL, useValue: '/api' },
+      ],
+    });
+    api = TestBed.inject(ApiService);
+    http = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    http.verify();
+    sessionStorage.clear();
+  });
+
+  it('pide POST text/plain con el envelope y desenvuelve { items, total }', async () => {
+    const pending = firstValueFrom(api.list<Row>(ENDPOINTS));
+
+    const req = http.expectOne('/api');
+    expect(req.request.method).toBe('POST');
+    expect(req.request.headers.get('Content-Type')).toBe('text/plain');
+    expect(req.request.body).toEqual({
+      token: 'tok',
+      method: 'GET',
+      path: '/admin/products',
+      payload: {},
+    });
+    req.flush({ items: [{ slug: 'a' }], total: 1 });
+
+    expect(await pending).toEqual([{ slug: 'a' }]);
+  });
+
+  it('el sobre estándar R6.4 { items, nextCursor, total } desenvuelve sólo los items', async () => {
+    const pending = firstValueFrom(api.list<Row>(ENDPOINTS));
+    http
+      .expectOne('/api')
+      .flush({ items: [{ slug: 'a' }, { slug: 'b' }], nextCursor: 'eyJ2IjoxLCJvIjoyfQ', total: 7 });
+    expect(await pending).toEqual([{ slug: 'a' }, { slug: 'b' }]);
+  });
+
+  it('nextCursor null (última página) desenvuelve igual: nadie tiene que comprobarlo', async () => {
+    const pending = firstValueFrom(api.list<Row>(ENDPOINTS));
+    http.expectOne('/api').flush({ items: [{ slug: 'c' }], nextCursor: null, total: 3 });
+    expect(await pending).toEqual([{ slug: 'c' }]);
+  });
+
+  it('arreglo plano (contrato histórico, sin envelope) pasa tal cual', async () => {
+    const pending = firstValueFrom(api.list<Row>(ENDPOINTS));
+    http.expectOne('/api').flush([{ slug: 'b' }]);
+    expect(await pending).toEqual([{ slug: 'b' }]);
+  });
+
+  it('respuesta inesperada ⇒ lista vacía (defensivo, nunca rompe)', async () => {
+    const pending = firstValueFrom(api.list<Row>(ENDPOINTS));
+    http.expectOne('/api').flush({ otra_clave: true });
+    expect(await pending).toEqual([]);
+  });
+
+  it('GET con {key} sustituye el segmento y codifica', async () => {
+    const pending = firstValueFrom(
+      api.get<Row>({ ...ENDPOINTS, get: '/admin/products/{key}' }, 'a b'),
+    );
+    const req = http.expectOne('/api');
+    expect((req.request.body as { path: string }).path).toBe('/admin/products/a%20b');
+    req.flush({ slug: 'a b' });
+    expect(await pending).toEqual({ slug: 'a b' });
+  });
+
+  // ── Caracterización (plan doc/context-sources-plan.md · Fase 0) ──────────
+  // Congelan el request ACTUAL con paths sin marcadores: son la base
+  // diferencial (R9) que debe seguir coincidiendo byte a byte.
+  it('get sin {key} (singleton): la path viaja literal dentro del envelope', async () => {
+    const pending = firstValueFrom(api.get<Row>({ get: '/admin/site' }));
+
+    const req = http.expectOne('/api');
+    expect(req.request.method).toBe('POST');
+    expect(req.request.headers.get('Content-Type')).toBe('text/plain');
+    expect(req.request.body).toEqual({
+      token: 'tok',
+      method: 'GET',
+      path: '/admin/site',
+      payload: {},
+    });
+    req.flush({ slug: 'site' });
+    expect(await pending).toEqual({ slug: 'site' });
+  });
+
+  it('create: payload declarado dentro del envelope con method POST', async () => {
+    const pending = firstValueFrom(
+      api.create<Row>({ ...ENDPOINTS, create: '/admin/products' }, { slug: 'nuevo' }),
+    );
+
+    const req = http.expectOne('/api');
+    expect(req.request.method).toBe('POST');
+    expect(req.request.body).toEqual({
+      token: 'tok',
+      method: 'POST',
+      path: '/admin/products',
+      payload: { slug: 'nuevo' },
+    });
+    req.flush({ slug: 'nuevo' });
+    expect(await pending).toEqual({ slug: 'nuevo' });
+  });
+
+  it('update sin {key}: conserva la path literal y manda PUT en el envelope', async () => {
+    const pending = firstValueFrom(
+      api.update<Row>({ update: '/admin/site' }, undefined, { slug: 'cambiado' }),
+    );
+
+    const req = http.expectOne('/api');
+    expect(req.request.method).toBe('POST');
+    expect(req.request.body).toEqual({
+      token: 'tok',
+      method: 'PUT',
+      path: '/admin/site',
+      payload: { slug: 'cambiado' },
+    });
+    req.flush({ slug: 'cambiado' });
+    expect(await pending).toEqual({ slug: 'cambiado' });
+  });
+
+  it('remove sin {key}: DELETE con la path literal en el envelope', async () => {
+    const pending = firstValueFrom(api.remove({ remove: '/admin/site' }));
+
+    const req = http.expectOne('/api');
+    expect(req.request.method).toBe('POST');
+    expect(req.request.body).toEqual({
+      token: 'tok',
+      method: 'DELETE',
+      path: '/admin/site',
+      payload: {},
+    });
+    req.flush(null);
+    await pending;
+  });
+
+  it('request: operación genérica conserva método, path y payload declarados', async () => {
+    const pending = firstValueFrom(
+      api.request<{ ok: boolean }>('PUT', '/admin/orders', { reorder: ['a', 'b'] }),
+    );
+
+    const req = http.expectOne('/api');
+    expect(req.request.method).toBe('POST');
+    expect(req.request.body).toEqual({
+      token: 'tok',
+      method: 'PUT',
+      path: '/admin/orders',
+      payload: { reorder: ['a', 'b'] },
+    });
+    req.flush({ ok: true });
+    expect(await pending).toEqual({ ok: true });
+  });
+});
+
+describe('ApiService — REST driver', () => {
+  let api: ApiService;
+  let http: HttpTestingController;
+
+  beforeEach(() => {
+    sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok');
+    sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role: 'admin' }));
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(),
+        provideHttpClientTesting(),
+        provideRouter([]),
+        { provide: API_URL, useValue: '/api' },
+        { provide: API_DRIVER, useValue: 'rest' },
+      ],
+    });
+    api = TestBed.inject(ApiService);
+    http = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    http.verify();
+    sessionStorage.clear();
+  });
+
+  it('list: ejecuta GET a ${apiUrl}${path} con cabecera Authorization y desenvuelve', async () => {
+    const pending = firstValueFrom(api.list<Row>(ENDPOINTS));
+
+    const req = http.expectOne('/api/admin/products');
+    expect(req.request.method).toBe('GET');
+    expect(req.request.headers.get('Authorization')).toBe('Bearer tok');
+    expect(req.request.body).toBeNull();
+    req.flush({ items: [{ slug: 'item-rest' }] });
+
+    expect(await pending).toEqual([{ slug: 'item-rest' }]);
+  });
+
+  it('list con payload: serializa claves como query params y aplana objetos anidados', async () => {
+    const pending = firstValueFrom(
+      api.list<Row>(ENDPOINTS, { view: 'active', params: { sort: 'asc', limit: 10 } }),
+    );
+
+    const req = http.expectOne((r) => r.url === '/api/admin/products');
+    expect(req.request.method).toBe('GET');
+    expect(req.request.headers.get('Authorization')).toBe('Bearer tok');
+    expect(req.request.params.get('view')).toBe('active');
+    expect(req.request.params.get('sort')).toBe('asc');
+    expect(req.request.params.get('limit')).toBe('10');
+    expect(req.request.params.has('params')).toBe(false);
+    req.flush([{ slug: 'item-filtered' }]);
+
+    expect(await pending).toEqual([{ slug: 'item-filtered' }]);
+  });
+
+  it('get: ejecuta GET a ${apiUrl}${path} sustituyendo {key}', async () => {
+    const pending = firstValueFrom(
+      api.get<Row>({ ...ENDPOINTS, get: '/admin/products/{key}' }, 'item 1'),
+    );
+
+    const req = http.expectOne('/api/admin/products/item%201');
+    expect(req.request.method).toBe('GET');
+    expect(req.request.headers.get('Authorization')).toBe('Bearer tok');
+    req.flush({ slug: 'item 1' });
+
+    expect(await pending).toEqual({ slug: 'item 1' });
+  });
+
+  it('create: ejecuta POST a ${apiUrl}${path} con body JSON y cabeceras correctas', async () => {
+    const pending = firstValueFrom(
+      api.create<Row>({ ...ENDPOINTS, create: '/admin/products' }, { slug: 'nuevo' }),
+    );
+
+    const req = http.expectOne('/api/admin/products');
+    expect(req.request.method).toBe('POST');
+    expect(req.request.headers.get('Authorization')).toBe('Bearer tok');
+    expect(req.request.headers.get('Content-Type')).toBe('application/json');
+    expect(req.request.body).toEqual({ slug: 'nuevo' });
+    req.flush({ slug: 'nuevo' });
+
+    expect(await pending).toEqual({ slug: 'nuevo' });
+  });
+
+  it('update: ejecuta PUT a ${apiUrl}${path} con {key} resuelta y body JSON', async () => {
+    const pending = firstValueFrom(
+      api.update<Row>({ ...ENDPOINTS, update: '/admin/products/{key}' }, 'prod-1', { slug: 'modificado' }),
+    );
+
+    const req = http.expectOne('/api/admin/products/prod-1');
+    expect(req.request.method).toBe('PUT');
+    expect(req.request.headers.get('Authorization')).toBe('Bearer tok');
+    expect(req.request.headers.get('Content-Type')).toBe('application/json');
+    expect(req.request.body).toEqual({ slug: 'modificado' });
+    req.flush({ slug: 'modificado' });
+
+    expect(await pending).toEqual({ slug: 'modificado' });
+  });
+
+  it('remove: ejecuta DELETE a ${apiUrl}${path} con {key} resuelta y Authorization', async () => {
+    const pending = firstValueFrom(
+      api.remove({ ...ENDPOINTS, remove: '/admin/products/{key}' }, 'prod-1'),
+    );
+
+    const req = http.expectOne('/api/admin/products/prod-1');
+    expect(req.request.method).toBe('DELETE');
+    expect(req.request.headers.get('Authorization')).toBe('Bearer tok');
+    req.flush(null);
+
+    await pending;
+  });
+
+  it('renovación deslizante: adopta meta.renewedToken en modo REST', async () => {
+    const auth = TestBed.inject(AuthService);
+    const pending = firstValueFrom(api.get<Row>({ ...ENDPOINTS, get: '/admin/products/{key}' }, '1'));
+
+    const req = http.expectOne('/api/admin/products/1');
+    req.flush({ slug: '1', meta: { renewedToken: 'nuevo-token-rest' } });
+
+    await pending;
+    expect(auth.token()).toBe('nuevo-token-rest');
+    expect(sessionStorage.getItem(SESSION_TOKEN_KEY)).toBe('nuevo-token-rest');
+  });
+
+  // ── Caracterización (plan doc/context-sources-plan.md · Fase 0) ──────────
+  // Misma base diferencial (R9) en modo REST: paths sin marcadores.
+  it('get sin {key} (singleton): GET a ${apiUrl}${path} con Authorization', async () => {
+    const pending = firstValueFrom(api.get<Row>({ get: '/admin/site' }));
+
+    const req = http.expectOne('/api/admin/site');
+    expect(req.request.method).toBe('GET');
+    expect(req.request.headers.get('Authorization')).toBe('Bearer tok');
+    expect(req.request.body).toBeNull();
+    req.flush({ slug: 'site' });
+    expect(await pending).toEqual({ slug: 'site' });
+  });
+
+  it('update sin {key}: PUT a la path literal con body JSON', async () => {
+    const pending = firstValueFrom(
+      api.update<Row>({ update: '/admin/site' }, undefined, { slug: 'cambiado' }),
+    );
+
+    const req = http.expectOne('/api/admin/site');
+    expect(req.request.method).toBe('PUT');
+    expect(req.request.headers.get('Authorization')).toBe('Bearer tok');
+    expect(req.request.headers.get('Content-Type')).toBe('application/json');
+    expect(req.request.body).toEqual({ slug: 'cambiado' });
+    req.flush({ slug: 'cambiado' });
+    expect(await pending).toEqual({ slug: 'cambiado' });
+  });
+
+  it('remove sin {key}: DELETE a la path literal con Authorization', async () => {
+    const pending = firstValueFrom(api.remove({ remove: '/admin/site' }));
+
+    const req = http.expectOne('/api/admin/site');
+    expect(req.request.method).toBe('DELETE');
+    expect(req.request.headers.get('Authorization')).toBe('Bearer tok');
+    req.flush(null);
+    await pending;
+  });
+
+  it('request: operación genérica respeta método, URL y headers declarados', async () => {
+    const pending = firstValueFrom(
+      api.request<{ ok: boolean }>('PATCH', '/admin/site', { campo: 'valor' }),
+    );
+
+    const req = http.expectOne('/api/admin/site');
+    expect(req.request.method).toBe('PATCH');
+    expect(req.request.headers.get('Authorization')).toBe('Bearer tok');
+    expect(req.request.headers.get('Content-Type')).toBe('application/json');
+    expect(req.request.body).toEqual({ campo: 'valor' });
+    req.flush({ ok: true });
+    expect(await pending).toEqual({ ok: true });
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────
+// Firebase ID token refresh (plan doc/firebase-token-refresh-plan.md · Fase 2)
+// ─────────────────────────────────────────────────────────────────────────
+describe('ApiService — Firebase ID token refresh · driver rest', () => {
+  let api: ApiService;
+  let http: HttpTestingController;
+  let getIdTokenSpy: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok');
+    sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role: 'admin' }));
+    getIdTokenSpy = vi.fn();
+    const firebaseAdapter = {
+      signInWithGoogle: async () => 'google-id-token',
+      signInWithEmailAndPassword: async () => 'email-id-token',
+      signOut: async () => undefined,
+      getIdToken: getIdTokenSpy,
+    } as unknown as FirebaseAuthAdapter;
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(),
+        provideHttpClientTesting(),
+        provideRouter([]),
+        { provide: API_URL, useValue: '/api' },
+        { provide: API_DRIVER, useValue: 'rest' },
+        { provide: FIREBASE_AUTH_ADAPTER, useValue: firebaseAdapter },
+      ],
+    });
+    api = TestBed.inject(ApiService);
+    http = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    http.verify();
+    sessionStorage.clear();
+  });
+
+  it('llama a getIdToken() antes de enviar y usa el valor refrescado en Authorization', async () => {
+    getIdTokenSpy.mockResolvedValue('refreshed-id-token');
+
+    const pending = firstValueFrom(api.get<Row>({ get: '/admin/site' }));
+
+    // Flush microtasks: from(promise) → switchMap → doRestRequest → http.request
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(getIdTokenSpy).toHaveBeenCalledTimes(1);
+
+    const req = http.expectOne('/api/admin/site');
+    expect(req.request.method).toBe('GET');
+    expect(req.request.headers.get('Authorization')).toBe('Bearer refreshed-id-token');
+    req.flush({ slug: 'site' });
+    expect(await pending).toEqual({ slug: 'site' });
+  });
+
+  it('getIdToken() que lanza ⇒ error en el canal de errores y ninguna petición sale', async () => {
+    getIdTokenSpy.mockRejectedValue(new Error('no hay usuario de Firebase'));
+
+    const pending = firstValueFrom(api.get<Row>({ get: '/admin/site' }));
+
+    await expect(pending).rejects.toThrow('no hay usuario de Firebase');
+    http.expectNone(() => true);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────
+// Marcadores de contexto (plan doc/context-sources-plan.md · Fase 3)
+// ─────────────────────────────────────────────────────────────────────
+describe('ApiService — marcadores de contexto · driver gas', () => {
+  let api: ApiService;
+  let http: HttpTestingController;
+
+  /** Path del envelope GAS: el cuerpo es { token, method, path, payload }. */
+  const pathDe = (req: { request: { body: unknown } }): string =>
+    (req.request.body as { path: string }).path;
+
+  beforeEach(() => {
+    sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok');
+    sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role: 'admin' }));
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(),
+        provideHttpClientTesting(),
+        provideRouter([]),
+        { provide: API_URL, useValue: '/api' },
+        { provide: VALUE_SOURCES, useValue: { tenant: () => 'acme' } },
+      ],
+    });
+    api = TestBed.inject(ApiService);
+    http = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    http.verify();
+    sessionStorage.clear();
+  });
+
+  it('list: resuelve {auth.user.id} dentro del path del envelope', async () => {
+    const pending = firstValueFrom(api.list<Row>({ list: '/businesses/{auth.user.id}/orders' }));
+
+    const req = http.expectOne('/api');
+    expect(pathDe(req)).toBe('/businesses/u_1/orders');
+    req.flush([]);
+    expect(await pending).toEqual([]);
+  });
+
+  it('get: resuelve la fuente de contexto Y {key} en el mismo path', async () => {
+    const pending = firstValueFrom(
+      api.get<Row>({ get: '/businesses/{auth.user.id}/orders/{key}' }, 'o 1'),
+    );
+
+    const req = http.expectOne('/api');
+    expect(pathDe(req)).toBe('/businesses/u_1/orders/o%201');
+    req.flush({ slug: 'o 1' });
+    await pending;
+  });
+
+  it('create: el marcador se resuelve también en operaciones sin clave', async () => {
+    const pending = firstValueFrom(
+      api.create<Row>({ create: '/businesses/{auth.user.id}/orders' }, { slug: 'nuevo' }),
+    );
+
+    const req = http.expectOne('/api');
+    expect(pathDe(req)).toBe('/businesses/u_1/orders');
+    req.flush({ slug: 'nuevo' });
+    await pending;
+  });
+
+  it('update: resuelve marcador y clave juntos', async () => {
+    const pending = firstValueFrom(
+      api.update<Row>({ update: '/businesses/{auth.user.id}/orders/{key}' }, 'o1', { slug: 'x' }),
+    );
+
+    const req = http.expectOne('/api');
+    expect(pathDe(req)).toBe('/businesses/u_1/orders/o1');
+    req.flush({ slug: 'x' });
+    await pending;
+  });
+
+  it('remove: resuelve marcador y clave juntos', async () => {
+    const pending = firstValueFrom(
+      api.remove({ remove: '/businesses/{auth.user.id}/orders/{key}' }, 'o1'),
+    );
+
+    const req = http.expectOne('/api');
+    expect(pathDe(req)).toBe('/businesses/u_1/orders/o1');
+    req.flush(null);
+    await pending;
+  });
+
+  it('request: operación genérica resuelve marcadores de fuentes registradas', async () => {
+    const pending = firstValueFrom(
+      api.request<{ ok: boolean }>('PUT', '/tenants/{tenant}/reorder', { orden: [1, 2] }),
+    );
+
+    const req = http.expectOne('/api');
+    expect(pathDe(req)).toBe('/tenants/acme/reorder');
+    req.flush({ ok: true });
+    await pending;
+  });
+
+  it('config: {config.public_base_url} se lee de forma perezosa, sin ciclo de DI (R2)', async () => {
+    const esperado = String(TestBed.inject(ConfigService).globalConfig()['public_base_url']);
+    const pending = firstValueFrom(api.list<Row>({ list: '/x/{config.public_base_url}' }));
+
+    const req = http.expectOne('/api');
+    expect(pathDe(req)).toBe(`/x/${encodeURIComponent(esperado)}`);
+    req.flush([]);
+    await pending;
+  });
+
+  it('fuente no registrada ⇒ error en el canal de errores y NINGUNA petición', async () => {
+    const pending = firstValueFrom(api.list<Row>({ list: '/x/{desconocida.id}/y' }));
+
+    await expect(pending).rejects.toThrow('desconocida');
+    http.expectNone(() => true);
+  });
+
+  it('valor ausente ⇒ error en el canal de errores y NINGUNA petición', async () => {
+    const pending = firstValueFrom(api.list<Row>({ list: '/x/{auth.user.nope}' }));
+
+    await expect(pending).rejects.toThrow('auth.user.nope');
+    http.expectNone(() => true);
+  });
+});
+
+describe('ApiService — marcadores de contexto · driver rest', () => {
+  let api: ApiService;
+  let http: HttpTestingController;
+
+  beforeEach(() => {
+    sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok');
+    sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role: 'admin' }));
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(),
+        provideHttpClientTesting(),
+        provideRouter([]),
+        { provide: API_URL, useValue: '/api' },
+        { provide: API_DRIVER, useValue: 'rest' },
+        { provide: VALUE_SOURCES, useValue: { tenant: () => 'acme' } },
+      ],
+    });
+    api = TestBed.inject(ApiService);
+    http = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    http.verify();
+    sessionStorage.clear();
+  });
+
+  it('list: el marcador queda resuelto en la URL saliente', async () => {
+    const pending = firstValueFrom(api.list<Row>({ list: '/businesses/{auth.user.id}/orders' }));
+
+    const req = http.expectOne('/api/businesses/u_1/orders');
+    expect(req.request.method).toBe('GET');
+    req.flush([]);
+    expect(await pending).toEqual([]);
+  });
+
+  it('get: resuelve la fuente de contexto Y {key} en la URL', async () => {
+    const pending = firstValueFrom(
+      api.get<Row>({ get: '/businesses/{auth.user.id}/orders/{key}' }, 'o 1'),
+    );
+
+    const req = http.expectOne('/api/businesses/u_1/orders/o%201');
+    expect(req.request.method).toBe('GET');
+    req.flush({ slug: 'o 1' });
+    await pending;
+  });
+
+  it('create: POST a la URL con el marcador resuelto', async () => {
+    const pending = firstValueFrom(
+      api.create<Row>({ create: '/businesses/{auth.user.id}/orders' }, { slug: 'nuevo' }),
+    );
+
+    const req = http.expectOne('/api/businesses/u_1/orders');
+    expect(req.request.method).toBe('POST');
+    req.flush({ slug: 'nuevo' });
+    await pending;
+  });
+
+  it('update: PUT con marcador y clave resueltos', async () => {
+    const pending = firstValueFrom(
+      api.update<Row>({ update: '/businesses/{auth.user.id}/orders/{key}' }, 'o1', { slug: 'x' }),
+    );
+
+    const req = http.expectOne('/api/businesses/u_1/orders/o1');
+    expect(req.request.method).toBe('PUT');
+    req.flush({ slug: 'x' });
+    await pending;
+  });
+
+  it('remove: DELETE con marcador y clave resueltos', async () => {
+    const pending = firstValueFrom(
+      api.remove({ remove: '/businesses/{auth.user.id}/orders/{key}' }, 'o1'),
+    );
+
+    const req = http.expectOne('/api/businesses/u_1/orders/o1');
+    expect(req.request.method).toBe('DELETE');
+    req.flush(null);
+    await pending;
+  });
+
+  it('request: operación genérica resuelve fuentes registradas por el consumidor', async () => {
+    const pending = firstValueFrom(
+      api.request<{ ok: boolean }>('PATCH', '/tenants/{tenant}/reorder', { orden: [1, 2] }),
+    );
+
+    const req = http.expectOne('/api/tenants/acme/reorder');
+    expect(req.request.method).toBe('PATCH');
+    req.flush({ ok: true });
+    await pending;
+  });
+});
+
+describe('ApiService — precedencia de fuentes (documentado en el README)', () => {
+  let api: ApiService;
+  let http: HttpTestingController;
+
+  beforeEach(() => {
+    sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok');
+    sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role: 'admin' }));
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(),
+        provideHttpClientTesting(),
+        provideRouter([]),
+        { provide: API_URL, useValue: '/api' },
+        // El registro intenta pisar `auth`: el motor es dueño de sus fuentes.
+        { provide: VALUE_SOURCES, useValue: { auth: () => ({ user: { id: 'pirata' } }) } },
+      ],
+    });
+    api = TestBed.inject(ApiService);
+    http = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    http.verify();
+    sessionStorage.clear();
+  });
+
+  it('valueSources no puede sombrear `auth` ni `config`: manda la fuente del motor', async () => {
+    const pending = firstValueFrom(api.list<Row>({ list: '/x/{auth.user.id}' }));
+
+    const req = http.expectOne('/api');
+    expect((req.request.body as { path: string }).path).toBe('/x/u_1');
+    req.flush([]);
+    await pending;
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────
+// Respuesta: caracterización de unwrapping (plan doc/engine-flexibility-plan.md · Fase 0)
+// Congela el comportamiento ACTUAL de respuesta para ser la base diferencial (R9)
+// antes de agregar declaraciones de unwrap y endpoints personalizados.
+// ─────────────────────────────────────────────────────────────────────────
+describe('ApiService — respuesta: caracterización de unwrapping', () => {
+  let api: ApiService;
+  let http: HttpTestingController;
+
+  beforeEach(() => {
+    sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok');
+    sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role: 'admin' }));
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(),
+        provideHttpClientTesting(),
+        provideRouter([]),
+        { provide: API_URL, useValue: '/api' },
+        { provide: API_DRIVER, useValue: 'rest' },
+      ],
+    });
+    api = TestBed.inject(ApiService);
+    http = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    http.verify();
+    sessionStorage.clear();
+  });
+
+  it('list: respuesta { items } devuelve solo los items (contrato actual)', async () => {
+    const pending = firstValueFrom(api.list<Row>(ENDPOINTS));
+    const req = http.expectOne('/api/admin/products');
+    expect(req.request.method).toBe('GET');
+    req.flush({ items: [{ slug: 'a' }, { slug: 'b' }], total: 2 });
+    expect(await pending).toEqual([{ slug: 'a' }, { slug: 'b' }]);
+  });
+
+  it('list: { items, nextCursor, total } desenvuelve items y descarta cursor (baseline)', async () => {
+    const pending = firstValueFrom(api.list<Row>(ENDPOINTS));
+    const req = http.expectOne('/api/admin/products');
+    req.flush({ items: [{ slug: 'a' }], nextCursor: 'tok', total: 1 });
+    expect(await pending).toEqual([{ slug: 'a' }]);
+  });
+
+  it('list: arreglo plano pasa tal cual (contrato histórico)', async () => {
+    const pending = firstValueFrom(api.list<Row>(ENDPOINTS));
+    const req = http.expectOne('/api/admin/products');
+    expect(req.request.method).toBe('GET');
+    req.flush([{ slug: 'a' }]);
+    expect(await pending).toEqual([{ slug: 'a' }]);
+  });
+
+  it('list: respuesta { data } envuelta devuelve [] hoy (unwrapList busca items)', async () => {
+    const pending = firstValueFrom(api.list<Row>(ENDPOINTS));
+    const req = http.expectOne('/api/admin/products');
+    expect(req.request.method).toBe('GET');
+    req.flush({ data: [{ slug: 'a' }], meta: { total: 1 } });
+    expect(await pending).toEqual([]);
+  });
+
+  it('get: objeto plano devuelve tal cual', async () => {
+    const pending = firstValueFrom(api.get<Row>({ get: '/admin/site' }));
+    const req = http.expectOne('/api/admin/site');
+    expect(req.request.method).toBe('GET');
+    req.flush({ slug: 'site', id: '1' });
+    expect(await pending).toEqual({ slug: 'site', id: '1' });
+  });
+
+  it('get: respuesta { data } envuelta devuelve el sobre entero hoy', async () => {
+    const pending = firstValueFrom(api.get<Row>({ get: '/admin/site' }));
+    const req = http.expectOne('/api/admin/site');
+    expect(req.request.method).toBe('GET');
+    req.flush({ data: { slug: 'site' }, meta: {} });
+    expect(await pending).toEqual({ data: { slug: 'site' }, meta: {} });
+  });
+
+  it('create: devuelve el cuerpo raw del servidor', async () => {
+    const pending = firstValueFrom(
+      api.create<Row>({ create: '/admin/products' }, { slug: 'nuevo' }),
+    );
+    const req = http.expectOne('/api/admin/products');
+    expect(req.request.method).toBe('POST');
+    req.flush({ slug: 'nuevo', id: 'p1' });
+    expect(await pending).toEqual({ slug: 'nuevo', id: 'p1' });
+  });
+
+  it('update: devuelve el cuerpo raw del servidor', async () => {
+    const pending = firstValueFrom(
+      api.update<Row>({ update: '/admin/products/{key}' }, 'p1', { slug: 'x' }),
+    );
+    const req = http.expectOne('/api/admin/products/p1');
+    expect(req.request.method).toBe('PUT');
+    req.flush({ slug: 'x', id: 'p1' });
+    expect(await pending).toEqual({ slug: 'x', id: 'p1' });
+  });
+
+  it('remove: no devuelve contenido (void)', async () => {
+    const pending = firstValueFrom(
+      api.remove({ remove: '/admin/products/{key}' }, 'p1'),
+    );
+    const req = http.expectOne('/api/admin/products/p1');
+    expect(req.request.method).toBe('DELETE');
+    req.flush(null);
+    await pending;
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────
+// Engine flexibility — response unwrapping + custom endpoints (plan Phase 3)
+// ─────────────────────────────────────────────────────────────────────────
+describe('ApiService — response unwrapping declarado', () => {
+  let api: ApiService;
+  let http: HttpTestingController;
+
+  beforeEach(() => {
+    sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok');
+    sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role: 'admin' }));
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(),
+        provideHttpClientTesting(),
+        provideRouter([]),
+        { provide: API_URL, useValue: '/api' },
+        { provide: API_DRIVER, useValue: 'rest' },
+      ],
+    });
+    api = TestBed.inject(ApiService);
+    http = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    http.verify();
+    sessionStorage.clear();
+  });
+
+  it('list: con responseUnwrap dataKey "data" devuelve el array envuelto', async () => {
+    const endpoints = { list: '/admin/products', responseUnwrap: { dataKey: 'data', metaKey: 'meta' } };
+    const pending = firstValueFrom(api.list<Row>(endpoints));
+    const req = http.expectOne('/api/admin/products');
+    req.flush({ data: [{ slug: 'a' }, { slug: 'b' }], meta: { total: 2 } });
+    expect(await pending).toEqual([{ slug: 'a' }, { slug: 'b' }]);
+  });
+
+  it('get: con responseUnwrap dataKey "data" devuelve el objeto envuelto', async () => {
+    const endpoints = { get: '/admin/site', responseUnwrap: { dataKey: 'data' } };
+    const pending = firstValueFrom(api.get<Row>(endpoints));
+    const req = http.expectOne('/api/admin/site');
+    req.flush({ data: { slug: 'site' }, meta: {} });
+    expect(await pending).toEqual({ slug: 'site' });
+  });
+
+  it('get: clave de unwrap ausente lanza error descriptivo', async () => {
+    const endpoints = { get: '/admin/site', responseUnwrap: { dataKey: 'data' } };
+    const pending = firstValueFrom(api.get<Row>(endpoints));
+    const req = http.expectOne('/api/admin/site');
+    req.flush({ slug: 'site' });
+    await expect(pending).rejects.toThrow(/dataKey 'data'/);
+  });
+
+  it('sin declaración mantiene el comportamiento actual (passthrough)', async () => {
+    const pending = firstValueFrom(api.get<Row>({ get: '/admin/site' }));
+    const req = http.expectOne('/api/admin/site');
+    req.flush({ slug: 'site', id: '1' });
+    expect(await pending).toEqual({ slug: 'site', id: '1' });
+  });
+});
+
+describe('ApiService — endpoints personalizados', () => {
+  let api: ApiService;
+  let http: HttpTestingController;
+
+  beforeEach(() => {
+    sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok');
+    sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role: 'admin' }));
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(),
+        provideHttpClientTesting(),
+        provideRouter([]),
+        { provide: API_URL, useValue: '/api' },
+        { provide: API_DRIVER, useValue: 'rest' },
+      ],
+    });
+    api = TestBed.inject(ApiService);
+    http = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    http.verify();
+    sessionStorage.clear();
+  });
+
+  it('custom endpoint con PATCH envía el verbo correcto', async () => {
+    const def = { name: 'recalc', method: 'PATCH' as const, path: '/admin/products/{key}/rank' };
+    const pending = firstValueFrom(api.invokeCustomEndpoint<{ ok: boolean }>(def, { value: 5 }, undefined, 'p1'));
+    const req = http.expectOne('/api/admin/products/p1/rank');
+    expect(req.request.method).toBe('PATCH');
+    expect(req.request.body).toEqual({ value: 5 });
+    req.flush({ ok: true });
+    expect(await pending).toEqual({ ok: true });
+  });
+
+  it('custom endpoint multipart envía FormData sin Content-Type application/json', async () => {
+    const def = { name: 'upload', method: 'POST' as const, path: '/admin/upload', payloadMode: 'multipart' as const };
+    const fd = new FormData();
+    fd.append('file', new Blob(['hello']), 'hello.txt');
+    const pending = firstValueFrom(api.invokeCustomEndpoint<{ ok: boolean }>(def, fd));
+    const req = http.expectOne('/api/admin/upload');
+    expect(req.request.method).toBe('POST');
+    expect(req.request.body instanceof FormData).toBe(true);
+    expect(req.request.headers.get('Content-Type')).not.toBe('application/json');
+    req.flush({ ok: true });
+    expect(await pending).toEqual({ ok: true });
+  });
+
+  it('custom endpoint con responseUnwrap aplica el unwrap', async () => {
+    const def = {
+      name: 'summary',
+      method: 'GET' as const,
+      path: '/admin/summary',
+      responseUnwrap: { dataKey: 'data' },
+    };
+    const pending = firstValueFrom(api.invokeCustomEndpoint<{ total: number }>(def));
+    const req = http.expectOne('/api/admin/summary');
+    req.flush({ data: { total: 42 }, meta: {} });
+    expect(await pending).toEqual({ total: 42 });
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────
+// Unwrap global + unwrapList ruidoso (plan doc/engine-refactor-plan.md · Fase 2)
+// ─────────────────────────────────────────────────────────────────────────
+describe('ApiService — default global de unwrap (Fase 2)', () => {
+  let api: ApiService;
+  let http: HttpTestingController;
+
+  beforeEach(() => {
+    sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok');
+    sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role: 'admin' }));
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(),
+        provideHttpClientTesting(),
+        provideRouter([]),
+        { provide: API_URL, useValue: '/api' },
+        { provide: API_DRIVER, useValue: 'rest' },
+        { provide: DEFAULT_RESPONSE_UNWRAP, useValue: { dataKey: 'data', metaKey: 'meta' } },
+      ],
+    });
+    api = TestBed.inject(ApiService);
+    http = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    http.verify();
+    sessionStorage.clear();
+  });
+
+  it('list: el default global se aplica aunque el recurso no declare unwrap', async () => {
+    const pending = firstValueFrom(api.list<Row>(ENDPOINTS));
+    const req = http.expectOne('/api/admin/products');
+    req.flush({ data: [{ slug: 'a' }, { slug: 'b' }], meta: { total: 2 } });
+    expect(await pending).toEqual([{ slug: 'a' }, { slug: 'b' }]);
+  });
+
+  it('get: el default global también aplica a get sin declaración por recurso', async () => {
+    const pending = firstValueFrom(api.get<Row>({ get: '/admin/site' }));
+    const req = http.expectOne('/api/admin/site');
+    req.flush({ data: { slug: 'site' }, meta: {} });
+    expect(await pending).toEqual({ slug: 'site' });
+  });
+});
+
+describe('ApiService — el recurso pisa el default global (Fase 2)', () => {
+  let api: ApiService;
+  let http: HttpTestingController;
+
+  beforeEach(() => {
+    sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok');
+    sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role: 'admin' }));
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(),
+        provideHttpClientTesting(),
+        provideRouter([]),
+        { provide: API_URL, useValue: '/api' },
+        { provide: API_DRIVER, useValue: 'rest' },
+        // Default global distinto al del recurso: el recurso debe ganar.
+        { provide: DEFAULT_RESPONSE_UNWRAP, useValue: { dataKey: 'payload' } },
+      ],
+    });
+    api = TestBed.inject(ApiService);
+    http = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    http.verify();
+    sessionStorage.clear();
+  });
+
+  it('list: el dataKey del recurso tiene prioridad sobre el del default global', async () => {
+    const endpoints = { list: '/admin/products', responseUnwrap: { dataKey: 'data' } };
+    const pending = firstValueFrom(api.list<Row>(endpoints));
+    const req = http.expectOne('/api/admin/products');
+    req.flush({ data: [{ slug: 'x' }], payload: [{ slug: 'IGNORED' }] });
+    expect(await pending).toEqual([{ slug: 'x' }]);
+  });
+
+  it('list: sin declaración por recurso se usa el dataKey del default global', async () => {
+    const pending = firstValueFrom(api.list<Row>(ENDPOINTS));
+    const req = http.expectOne('/api/admin/products');
+    req.flush({ payload: [{ slug: 'g' }] });
+    expect(await pending).toEqual([{ slug: 'g' }]);
+  });
+});
+
+describe('ApiService — unwrapList ruidoso (Fase 2)', () => {
+  let api: ApiService;
+  let http: HttpTestingController;
+
+  beforeEach(() => {
+    sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok');
+    sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role: 'admin' }));
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(),
+        provideHttpClientTesting(),
+        provideRouter([]),
+        { provide: API_URL, useValue: '/api' },
+        { provide: API_DRIVER, useValue: 'rest' },
+      ],
+    });
+    api = TestBed.inject(ApiService);
+    http = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    http.verify();
+    sessionStorage.clear();
+  });
+
+  it('list: cuerpo que no es array ni objeto lanza error descriptivo (no devuelve [])', async () => {
+    const pending = firstValueFrom(api.list<Row>(ENDPOINTS));
+    const req = http.expectOne('/api/admin/products');
+    req.flush('boom');
+    await expect(pending).rejects.toThrow(/list/i);
+  });
+
+  it('list: con { items } sigue funcionando igual (regresión)', async () => {
+    const pending = firstValueFrom(api.list<Row>(ENDPOINTS));
+    const req = http.expectOne('/api/admin/products');
+    req.flush({ items: [{ slug: 'a' }], total: 1 });
+    expect(await pending).toEqual([{ slug: 'a' }]);
+  });
+
+  it('list: objeto sin claves reconocidas mantiene [] (compat R9 congelada)', async () => {
+    const pending = firstValueFrom(api.list<Row>(ENDPOINTS));
+    const req = http.expectOne('/api/admin/products');
+    req.flush({ data: [{ slug: 'a' }], meta: { total: 1 } });
+    expect(await pending).toEqual([]);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────
+// listPage() — paginación opt-in (plan doc/engine-refactor-plan.md · Fase 3)
+// ─────────────────────────────────────────────────────────────────────────
+describe('ApiService — listPage (Fase 3)', () => {
+  let api: ApiService;
+  let http: HttpTestingController;
+
+  beforeEach(() => {
+    sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok');
+    sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role: 'admin' }));
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(),
+        provideHttpClientTesting(),
+        provideRouter([]),
+        { provide: API_URL, useValue: '/api' },
+        { provide: API_DRIVER, useValue: 'rest' },
+      ],
+    });
+    api = TestBed.inject(ApiService);
+    http = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    http.verify();
+    sessionStorage.clear();
+  });
+
+  it('3.1: devuelve { items, nextCursor, total, hasMore } desde { items, nextCursor, total }', async () => {
+    const pending = firstValueFrom(api.listPage<Row>(ENDPOINTS));
+    const req = http.expectOne('/api/admin/products');
+    expect(req.request.method).toBe('GET');
+    req.flush({ items: [{ slug: 'a' }], nextCursor: 'tok1', total: 25 });
+    expect(await pending).toEqual({
+      items: [{ slug: 'a' }],
+      nextCursor: 'tok1',
+      total: 25,
+      hasMore: true,
+    });
+  });
+
+  it('3.2: con unwrap declarado extrae items de dataKey y paginación de meta', async () => {
+    const endpoints = {
+      list: '/admin/products',
+      responseUnwrap: { dataKey: 'data', metaKey: 'meta' },
+    };
+    const pending = firstValueFrom(api.listPage<Row>(endpoints));
+    const req = http.expectOne('/api/admin/products');
+    req.flush({ data: [{ slug: 'a' }], meta: { nextCursor: 'c9', total: 3 } });
+    expect(await pending).toEqual({
+      items: [{ slug: 'a' }],
+      nextCursor: 'c9',
+      total: 3,
+      hasMore: true,
+    });
+  });
+
+  it('3.3: cursor ausente ⇒ hasMore = false y nextCursor = null', async () => {
+    const pending = firstValueFrom(api.listPage<Row>(ENDPOINTS));
+    const req = http.expectOne('/api/admin/products');
+    req.flush({ items: [{ slug: 'a' }], total: 1 });
+    expect(await pending).toEqual({
+      items: [{ slug: 'a' }],
+      nextCursor: null,
+      total: 1,
+      hasMore: false,
+    });
+  });
+
+  it('3.5: payload de paginación (cursor, limit) viaja como payload normal en GET', async () => {
+    const pending = firstValueFrom(api.listPage<Row>(ENDPOINTS, { cursor: 'c1', limit: 20 }));
+    const req = http.expectOne('/api/admin/products?cursor=c1&limit=20');
+    expect(req.request.method).toBe('GET');
+    req.flush({ items: [], nextCursor: 'c2', total: 40 });
+    expect((await pending).nextCursor).toBe('c2');
+  });
+
+  it('arreglo plano también pagina (hasMore false sin cursor)', async () => {
+    const pending = firstValueFrom(api.listPage<Row>(ENDPOINTS));
+    const req = http.expectOne('/api/admin/products');
+    req.flush([{ slug: 'a' }]);
+    expect(await pending).toEqual({
+      items: [{ slug: 'a' }],
+      nextCursor: null,
+      total: 0,
+      hasMore: false,
+    });
+  });
+
+  it('claves de paginación custom vía responseUnwrap.pagination', async () => {
+    const endpoints = {
+      list: '/admin/products',
+      responseUnwrap: {
+        dataKey: 'results',
+        pagination: { cursorKey: 'after', totalKey: 'count', hasMoreKey: 'remaining' },
+      },
+    };
+    const pending = firstValueFrom(api.listPage<Row>(endpoints));
+    const req = http.expectOne('/api/admin/products');
+    req.flush({ results: [{ slug: 'a' }], after: 'z1', count: 9, remaining: true });
+    expect(await pending).toEqual({
+      items: [{ slug: 'a' }],
+      nextCursor: 'z1',
+      total: 9,
+      hasMore: true,
+    });
+  });
+});