client-behavior.test.ts

import { describe, expect, it, vi } from 'vitest';

import {
  BaseClient,
  LilyAuthenticationError,
  LilyApiError,
  LilySdk,
  createFetchHttpClient,
  LilyTransportError,
  resolveLilySdkConfig,
} from '../src/index';
import { createMockHttpClient } from './helpers/mock-http-client';

describe('client behavior', () => {
  it('exposes transport primitives from the root entrypoint', () => {
    expect(createFetchHttpClient).toBeInstanceOf(Function);
    expect(BaseClient).toBeInstanceOf(Function);
  });

  it('allows subclassing BaseClient with a custom HTTP client', async () => {
    const requestSpy = vi.fn(() =>
      Promise.resolve({
        status: 200,
        headers: new Headers(),
        data: { ok: true },
      }),
    );

    class TestClient extends BaseClient {
      async probe() {
        return this.request<{ ok: boolean }>({ method: 'GET', path: '/probe' });
      }
    }

    const client = new TestClient(createMockHttpClient(requestSpy));
    const result = await client.probe();

    expect(requestSpy).toHaveBeenCalledWith({ method: 'GET', path: '/probe' });
    expect(result.ok).toBe(true);
  });

  it('calls system health endpoint through the system client', async () => {
    const requestSpy = vi.fn(() =>
      Promise.resolve({
        status: 200,
        headers: new Headers(),
        data: {
          status: 'ok',
          version: '0.1.0',
          timestamp: new Date().toISOString(),
          checks: {
            api: 'ok',
          },
        },
      }),
    );

    const sdk = new LilySdk(
      {
        baseUrl: 'https://api.lily.test',
        fetch: globalThis.fetch,
      },
      createMockHttpClient(requestSpy),
    );

    const health: HealthStatus = await sdk.system.health();

    expect(requestSpy).toHaveBeenCalledWith({
      method: 'GET',
      path: '/v1/system/health',
    });
    expect(health).toEqual({
      status: 'ok',
      version: '0.1.0',
      timestamp: expect.any(String),
      checks: {
        api: 'ok',
      },
    });
  });

  it('calls system info endpoint and returns service information', async () => {
    const serviceInfo: ServiceInfo = {
      name: 'lily-api',
      version: '0.1.0',
      environment: 'staging',
      docsUrl: 'https://docs.lily.test',
    };
    const requestSpy = vi.fn(() =>
      Promise.resolve({
        status: 200,
        headers: new Headers(),
        data: serviceInfo,
      }),
    );

    const sdk = new LilySdk(
      {
        baseUrl: 'https://api.lily.test',
        fetch: globalThis.fetch,
      },
      createMockHttpClient(requestSpy),
    );

    const info: ServiceInfo = await sdk.system.info();

    expect(requestSpy).toHaveBeenCalledWith({
      method: 'GET',
      path: '/v1/system/info',
    });
    expect(info).toEqual(serviceInfo);
  });

  it.each([
    {
      name: 'api key only',
      credentials: { apiKey: 'secret-key' },
      authHeaders: { 'x-api-key': 'secret-key' },
    },
    {
      name: 'auth token only',
      credentials: { authToken: 'secret-token' },
      authHeaders: { authorization: 'Bearer secret-token' },
    },
    {
      name: 'both credentials',
      credentials: { apiKey: 'secret-key', authToken: 'secret-token' },
      authHeaders: {
        'x-api-key': 'secret-key',
        authorization: 'Bearer secret-token',
      },
    },
    {
      name: 'no credentials',
      credentials: {},
      authHeaders: {},
    },
  ])(
    'forwards the correct auth headers with $name',
    async ({ credentials, authHeaders }) => {
      const fetchSpy = vi.fn((input: URL | RequestInfo, init?: RequestInit) => {
        expect(input).toEqual(
          new URL('https://api.lily.test/v1/system/health'),
        );
        expect(init?.method).toBe('GET');

        return Promise.resolve(
          new Response(null, {
            status: 200,
          }),
        );
      });

      const httpClient = createFetchHttpClient({
        baseUrl: new URL('https://api.lily.test/'),
        timeoutMs: 2_000,
        retry: {
          retries: 0,
          retryDelayMs: 0,
          retryableStatusCodes: [],
        },
        defaultHeaders: {},
        userAgent: 'lily-sdk/test',
        fetch: fetchSpy,
        ...credentials,
      });

    const httpClient = createFetchHttpClient({
      baseUrl: new URL('https://api.lily.test/'),
      apiKey: 'secret-key',
      authToken: 'secret-token',
      timeoutMs: 2_000,
      retry: {
        retries: 0,
        retryDelayMs: 0,
        retryableStatusCodes: [],
      },
      defaultHeaders: {},
      userAgent: 'lily-sdk/test',
    validateResponses: false,
      fetch: fetchSpy,
    });

      expect(fetchSpy).toHaveBeenCalledOnce();
      expect(fetchSpy.mock.calls[0]?.[1]?.headers).toEqual({
        accept: 'application/json',
        'content-type': 'application/json',
        'user-agent': 'lily-sdk/test',
        ...authHeaders,
      });
    },
  );

  it('maps authentication failures to a typed error with full payload', async () => {
    const httpClient = createFetchHttpClient({
      baseUrl: new URL('https://api.lily.test/'),
      timeoutMs: 2_000,
      retry: {
        retries: 0,
        retryDelayMs: 0,
        retryableStatusCodes: [],
      },
      defaultHeaders: {},
      userAgent: 'lily-sdk/test',
    validateResponses: false,
      fetch: vi.fn(() =>
        Promise.resolve(
          new Response(JSON.stringify({ message: 'nope', code: 'INVALID_TOKEN' }), {
            status: 401,
            headers: {
              'content-type': 'application/json',
            },
          }),
        ),
      ),
    });

    try {
      await httpClient.request({
        method: 'GET',
        path: '/v1/system/health',
      });
      expect.fail('should have thrown');
    } catch (error) {
      expect(error).toBeInstanceOf(LilyAuthenticationError);
      const authError = error as LilyAuthenticationError;
      expect(authError.request).toEqual({
        method: 'GET',
        path: '/v1/system/health',
        url: 'https://api.lily.test/v1/system/health',
      });
    }
  });

  it('attaches request metadata to api errors', async () => {
    const httpClient = createFetchHttpClient({
      baseUrl: new URL('https://api.lily.test/'),
      timeoutMs: 2_000,
      retry: {
        retries: 0,
        retryDelayMs: 0,
        retryableStatusCodes: [],
      },
      defaultHeaders: {},
      userAgent: 'lily-sdk/test',
      fetch: vi.fn(() =>
        Promise.resolve(
          new Response(JSON.stringify({ message: 'fail' }), {
            status: 500,
            headers: {
              'content-type': 'application/json',
            },
          }),
        ),
      ),
    });

    try {
      await httpClient.request({
        method: 'GET',
        path: '/v1/items',
      });
      expect.fail('should have thrown');
    } catch (error) {
      expect(error).toBeInstanceOf(LilyApiError);
      const apiError = error as LilyApiError;
      expect(apiError.request).toEqual({
        method: 'GET',
        path: '/v1/items',
        url: 'https://api.lily.test/v1/items',
      });
    }
  });

  it('attaches request metadata to transport timeout errors', async () => {
    const httpClient = createFetchHttpClient({
      baseUrl: new URL('https://api.lily.test/'),
      timeoutMs: 10,
      retry: {
        retries: 0,
        retryDelayMs: 0,
        retryableStatusCodes: [],
      },
      defaultHeaders: {},
      userAgent: 'lily-sdk/test',
      fetch: vi.fn((...args: unknown[]) => {
        const init = args[1] as RequestInit | undefined;
        return new Promise<Response>((_resolve, reject) => {
          init?.signal?.addEventListener('abort', () => {
            const abortError = new Error('The operation was aborted');
            abortError.name = 'AbortError';
            reject(abortError);
          });
        });
      }),
    });

    try {
      await httpClient.request({
        method: 'GET',
        path: '/v1/system/health',
      });
      expect.fail('request should have thrown');
    } catch (error) {
      expect(error).toBeInstanceOf(LilyTransportError);
      const transportError = error as LilyTransportError;
      expect(transportError.code).toBe('TIMEOUT');
      expect(transportError.request).toEqual({
        method: 'GET',
        path: '/v1/system/health',
        url: 'https://api.lily.test/v1/system/health',
      });
    }
  });

  it('propagates full error payload on non-retryable API errors', async () => {
    const errorBody = {
      code: 'INVALID_REQUEST',
      message: 'Missing required field',
      field: 'amount',
    };

    const httpClient = createFetchHttpClient({
      baseUrl: new URL('https://api.lily.test/'),
      timeoutMs: 2_000,
      retry: {
        retries: 0,
        retryDelayMs: 0,
        retryableStatusCodes: [],
      },
      defaultHeaders: {},
      userAgent: 'lily-sdk/test',
      fetch: vi.fn(() =>
        Promise.resolve(
          new Response(JSON.stringify(errorBody), {
            status: 400,
            headers: {
              'content-type': 'application/json',
            },
          }),
        ),
      ),
    });

    try {
      await httpClient.request({
        method: 'POST',
        path: '/v1/payments',
        body: {},
      });
      expect.fail('Expected LilyApiError to be thrown');
    } catch (error) {
      expect(error).toBeInstanceOf(LilyApiError);
      const apiError = error as LilyApiError;
      expect(apiError.statusCode).toBe(400);
      expect(apiError.code).toBe('API_ERROR');
      expect(apiError.details).toEqual(errorBody);
    }
  });

  describe.each([
    {
      scenario: 'apiKey only',
      config: { apiKey: 'my-api-key' },
      expectedHeaders: { 'x-api-key': 'my-api-key' },
      disallowedHeaders: ['authorization'],
    },
    {
      scenario: 'authToken only',
      config: { authToken: 'my-token' },
      expectedHeaders: { authorization: 'Bearer my-token' },
      disallowedHeaders: ['x-api-key'],
    },
    {
      scenario: 'both apiKey and authToken',
      config: { apiKey: 'my-api-key', authToken: 'my-token' },
      expectedHeaders: {
        authorization: 'Bearer my-token',
        'x-api-key': 'my-api-key',
      },
      disallowedHeaders: [],
    },
    {
      scenario: 'neither credential',
      config: {},
      expectedHeaders: {},
      disallowedHeaders: ['authorization', 'x-api-key'],
    },
  ])('auth credential forwarding ($scenario)', ({ config, expectedHeaders, disallowedHeaders }) => {
    it(`forwards the expected authentication headers for ${config}`, async () => {
      const fetchSpy = vi.fn((_input: URL | RequestInfo, init?: RequestInit) => {
        const headers = (init?.headers ?? {}) as Record<string, string>;

        for (const [key, value] of Object.entries(expectedHeaders)) {
          expect(headers[key]).toBe(value);
        }

        for (const key of disallowedHeaders) {
          expect(headers[key]).toBeUndefined();
        }

        return Promise.resolve(
          new Response(
            JSON.stringify({ status: 'ok' }),
            {
              status: 200,
              headers: { 'content-type': 'application/json' },
            },
          ),
        );
      });

      const httpClient = createFetchHttpClient({
        baseUrl: new URL('https://api.lily.test/'),
        ...config,
        timeoutMs: 2_000,
        retry: {
          retries: 0,
          retryDelayMs: 0,
          retryableStatusCodes: [],
        },
        defaultHeaders: {},
        userAgent: 'lily-sdk/test',
        fetch: fetchSpy,
      });

      const response = await httpClient.request({
        method: 'GET',
        path: '/v1/system/health',
      });

      expect(response.status).toBe(200);
      expect(fetchSpy).toHaveBeenCalledOnce();
    });
  });

  it('merges defaultHeaders with per-request headers', async () => {
    const fetchSpy = vi.fn((_input: RequestInfo | URL, init?: RequestInit) => {
      expect(init?.headers).toMatchObject({
        accept: 'application/json',
        'content-type': 'application/json',
        'user-agent': 'lily-sdk/test',
        'x-tenant': 'acme',
        'x-request-id': 'req-123',
      });

      return Promise.resolve(
        new Response(JSON.stringify({ ok: true }), {
          status: 200,
          headers: {
            'content-type': 'application/json',
          },
        }),
      );
    });

    const httpClient = createFetchHttpClient({
      baseUrl: new URL('https://api.lily.test/'),
      timeoutMs: 2_000,
      retry: {
        retries: 0,
        retryDelayMs: 0,
        retryableStatusCodes: [],
      },
      defaultHeaders: {
        'x-tenant': 'acme',
      },
      userAgent: 'lily-sdk/test',
      fetch: fetchSpy,
    });

    await httpClient.request({
      method: 'GET',
      path: '/v1/items',
      headers: {
        'x-request-id': 'req-123',
      },
    });

    expect(fetchSpy).toHaveBeenCalledOnce();
  });

  it('allows per-request headers to override defaultHeaders', async () => {
    const fetchSpy = vi.fn((_input: RequestInfo | URL, init?: RequestInit) => {
      expect(init?.headers).toMatchObject({
        'x-tenant': 'override',
      });

      return Promise.resolve(
        new Response(JSON.stringify({ ok: true }), {
          status: 200,
          headers: {
            'content-type': 'application/json',
          },
        }),
      );
    });

    const httpClient = createFetchHttpClient({
      baseUrl: new URL('https://api.lily.test/'),
      timeoutMs: 2_000,
      retry: {
        retries: 0,
        retryDelayMs: 0,
        retryableStatusCodes: [],
      },
      defaultHeaders: {
        'x-tenant': 'acme',
      },
      userAgent: 'lily-sdk/test',
      fetch: fetchSpy,
    });

    await httpClient.request({
      method: 'GET',
      path: '/v1/items',
      headers: {
        'x-tenant': 'override',
      },
    });

    expect(fetchSpy).toHaveBeenCalledOnce();
  });

  it('does not retry POST requests on retryable statuses', async () => {
    const fetchSpy = vi.fn(() =>
      Promise.resolve(
        new Response(JSON.stringify({ message: 'fail' }), {
          status: 500,
          headers: {
            'content-type': 'application/json',
          },
        }),
      ),
    );

    const httpClient = createFetchHttpClient({
      baseUrl: new URL('https://api.lily.test/'),
      timeoutMs: 2_000,
      retry: {
        retries: 3,
        retryDelayMs: 0,
        retryableStatusCodes: [408, 409, 425, 429, 500, 502, 503, 504],
      },
      defaultHeaders: {},
      userAgent: 'lily-sdk/test',
      fetch: fetchSpy,
    });

    try {
      await httpClient.request({
        method: 'POST',
        path: '/v1/payments',
      });
      expect.fail('should have thrown');
    } catch (error) {
      expect(error).toBeInstanceOf(LilyApiError);
      const apiError = error as LilyApiError;
      expect(apiError.statusCode).toBe(500);
    }

    expect(fetchSpy).toHaveBeenCalledTimes(1);
  });

  it('retries GET requests on retryable statuses', async () => {
    const fetchSpy = vi.fn(() =>
      Promise.resolve(
        new Response(JSON.stringify({ message: 'fail' }), {
          status: 500,
          headers: {
            'content-type': 'application/json',
          },
        }),
      ),
    );

    const httpClient = createFetchHttpClient({
      baseUrl: new URL('https://api.lily.test/'),
      timeoutMs: 2_000,
      retry: {
        retries: 2,
        retryDelayMs: 0,
        retryableStatusCodes: [408, 409, 425, 429, 500, 502, 503, 504],
      },
      defaultHeaders: {},
      userAgent: 'lily-sdk/test',
      fetch: fetchSpy,
    });

    try {
      await httpClient.request({
        method: 'GET',
        path: '/v1/items',
      });
      expect.fail('should have thrown');
    } catch (error) {
      expect(error).toBeInstanceOf(LilyApiError);
      const apiError = error as LilyApiError;
      expect(apiError.statusCode).toBe(500);
    }

    // Initial attempt + 2 retries = 3 total calls
    expect(fetchSpy).toHaveBeenCalledTimes(3);
  });

  it('surfaces LilyApiError after retry exhaustion', async () => {
    const fetchSpy = vi.fn(() =>
      Promise.resolve(
        new Response(JSON.stringify({ message: 'unavailable' }), {
          status: 503,
          headers: {
            'content-type': 'application/json',
          },
        }),
      ),
    );

    const httpClient = createFetchHttpClient({
      baseUrl: new URL('https://api.lily.test/'),
      timeoutMs: 2_000,
      retry: {
        retries: 2,
        retryDelayMs: 0,
        retryableStatusCodes: [503],
      },
      defaultHeaders: {},
      userAgent: 'lily-sdk/test',
      fetch: fetchSpy,
    });

    let caught: unknown;

    try {
      await httpClient.request({
        method: 'GET',
        path: '/v1/system/health',
      });
    } catch (error) {
      caught = error;
    }

    expect(fetchSpy).toHaveBeenCalledTimes(3);
    expect(caught).toBeInstanceOf(LilyApiError);
    expect(caught).toMatchObject({ statusCode: 503 });
  });

  it('preserves the original fetch rejection as the transport error cause', async () => {
    const networkError = new Error('connection refused');
    const httpClient = createFetchHttpClient({
      baseUrl: new URL('https://api.lily.test/'),
      timeoutMs: 2_000,
      retry: {
        retries: 0,
        retryDelayMs: 0,
        retryableStatusCodes: [],
      },
      defaultHeaders: {},
      userAgent: 'lily-sdk/test',
      fetch: vi.fn(() => Promise.reject(networkError)),
    });

    try {
      await httpClient.request({
        method: 'GET',
        path: '/v1/system/health',
      });
      expect.unreachable('request should reject with LilyTransportError');
    } catch (error) {
      expect(error).toBeInstanceOf(LilyTransportError);
      expect(error).toMatchObject({
        code: 'TRANSPORT_ERROR',
        cause: networkError,
      });
    }
  });

  it('preserves the AbortError as the timeout transport error cause', async () => {
    let abortError: DOMException | undefined;
    const httpClient = createFetchHttpClient({
      baseUrl: new URL('https://api.lily.test/'),
      timeoutMs: 1,
      retry: {
        retries: 0,
        retryDelayMs: 0,
        retryableStatusCodes: [],
      },
      defaultHeaders: {},
      userAgent: 'lily-sdk/test',
      fetch: vi.fn(
        (_input: URL | RequestInfo, init?: RequestInit) =>
          new Promise<Response>((_resolve, reject) => {
            init?.signal?.addEventListener('abort', () => {
              abortError = new DOMException(
                'The operation was aborted.',
                'AbortError',
              );
              reject(abortError);
            });
          }),
      ),
    });

    try {
      await httpClient.request({
        method: 'GET',
        path: '/v1/system/health',
      });
      expect.unreachable('request should reject with LilyTransportError');
    } catch (error) {
      expect(error).toBeInstanceOf(LilyTransportError);
      expect(error).toMatchObject({
        code: 'TIMEOUT',
        cause: abortError,
      });
    }
  });

  describe('baseUrl path prefixes', () => {
    async function requestedHref(
      baseUrl: string,
      path: string,
      query?: Record<string, string | number | boolean | undefined>,
    ): Promise<string> {
      const fetchSpy = vi.fn((_input: URL | RequestInfo) =>
        Promise.resolve(
          new Response(JSON.stringify({ ok: true }), {
            status: 200,
            headers: {
              'content-type': 'application/json',
            },
          }),
        ),
      );

      const httpClient = createFetchHttpClient(
        resolveLilySdkConfig({
          baseUrl,
          fetch: fetchSpy,
        }),
      );

      await httpClient.request({
        method: 'GET',
        path,
        ...(query === undefined ? {} : { query }),
      });

      expect(fetchSpy).toHaveBeenCalledOnce();
      return String(fetchSpy.mock.calls[0]?.[0]);
    }

    it('keeps a path prefix when baseUrl has no trailing slash', async () => {
      await expect(
        requestedHref('https://host/lily/api', '/v1/system/health'),
      ).resolves.toBe('https://host/lily/api/v1/system/health');
    });

    it('keeps a path prefix when baseUrl already has a trailing slash', async () => {
      await expect(
        requestedHref('https://host/lily/api/', '/v1/system/health'),
      ).resolves.toBe('https://host/lily/api/v1/system/health');
    });

    it('joins request paths onto a host-root baseUrl', async () => {
      await expect(
        requestedHref('https://api.lily.test', '/v1/system/health'),
      ).resolves.toBe('https://api.lily.test/v1/system/health');
    });

    it('appends query parameters onto a path-prefixed URL', async () => {
      await expect(
        requestedHref('https://host/lily/api', '/v1/agents', {
          limit: 10,
          status: 'active',
        }),
      ).resolves.toBe('https://host/lily/api/v1/agents?limit=10&status=active');
    });
  });

  it('maps an empty JSON response to a validation error without retrying', async () => {
    const fetchSpy = vi.fn(() =>
      Promise.resolve(
        new Response(null, {
          status: 200,
          headers: {
            'content-type': 'application/json',
          },
        }),
      ),
    );
    const httpClient = createFetchHttpClient({
      baseUrl: new URL('https://api.lily.test/'),
      timeoutMs: 2_000,
      retry: {
        retries: 2,
        retryDelayMs: 0,
        retryableStatusCodes: [],
      },
      defaultHeaders: {},
      userAgent: 'lily-sdk/test',
      fetch: fetchSpy,
    });

    const request = httpClient.request({
      method: 'GET',
      path: '/v1/system/health',
    });

    await expect(request).rejects.toMatchObject({
      name: 'LilyValidationError',
      code: 'RESPONSE_VALIDATION_ERROR',
      statusCode: 200,
      message:
        'Failed to parse response body as JSON (status 200, content-type: application/json).',
    } satisfies Partial<LilyValidationError>);
    expect(fetchSpy).toHaveBeenCalledOnce();
  });

  it('surfaces the last API error after exhausting retries', async () => {
    const fetchSpy = vi.fn(() =>
      Promise.resolve(
        new Response(JSON.stringify({ message: 'unavailable' }), {
          status: 503,
          headers: {
            'content-type': 'application/json',
          },
        }),
      ),
    );
    const httpClient = createFetchHttpClient({
      baseUrl: new URL('https://api.lily.test/'),
      timeoutMs: 2_000,
      retry: {
        retries: 2,
        retryDelayMs: 0,
        retryableStatusCodes: [503],
      },
      defaultHeaders: {},
      userAgent: 'lily-sdk/test',
      fetch: fetchSpy,
    });

    const error = await httpClient
      .request({
        method: 'GET',
        path: '/v1/system/health',
      })
      .catch((reason: unknown) => reason);

    expect(error).toBeInstanceOf(LilyApiError);
    expect(error).toMatchObject({ statusCode: 503 });
    expect(fetchSpy).toHaveBeenCalledTimes(3);
  });
});

function createTestHttpClient(
  fetch: typeof globalThis.fetch,
  timeoutMs = 2_000,
) {
  return createFetchHttpClient({
    baseUrl: new URL('https://api.lily.test/'),
    timeoutMs,
    retry: {
      retries: 0,
      retryDelayMs: 0,
      retryableStatusCodes: [],
    },
    defaultHeaders: {},
    userAgent: 'lily-sdk/test',
    fetch,
  });
}