@navegarti/rn-design-system 0.8.5 → 0.8.7

package/src/api/errors.ts

@@ -1,13 +1,34 @@
 /**
- * Base class for all API errors
- * Provides common structure and debugging information
+ * Base class for all API errors.
+ * Provides common structure and debugging information for HTTP-layer failures.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await api.get('/users/me');
+ * } catch (error) {
+ *   if (error instanceof ApiError) {
+ *     console.error(error.toDebugString());
+ *   }
+ * }
+ * ```
  */
 export class ApiError extends Error {
+  /** HTTP status code associated with the error (0 for network-layer failures). */
   public readonly statusCode: number;
+  /** URL of the request that produced this error. */
   public readonly url?: string;
+  /** HTTP method of the request that produced this error. */
   public readonly method?: string;
+  /** Timestamp at which the error was created. */
   public readonly timestamp: Date;
 
+  /**
+   * @param message Human-readable error description.
+   * @param statusCode HTTP status code (0 for network-level errors).
+   * @param url Request URL, if available.
+   * @param method HTTP method, if available.
+   */
   constructor(
     message: string,
     statusCode: number,
@@ -22,13 +43,22 @@ export class ApiError extends Error {
     this.timestamp = new Date();
 
     // Maintains proper stack trace for where our error was thrown (only available on V8)
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
-    }
+    (Error as any).captureStackTrace?.(this, this.constructor);
   }
 
   /**
-   * Returns a formatted error message for debugging
+   * Returns a formatted multi-line string with all error details, useful for
+   * logging and debugging.
+   *
+   * @example
+   * ```ts
+   * console.error(error.toDebugString());
+   * // [AuthError] Unauthorized
+   * // Status: 401
+   * // URL: /users/me
+   * // Method: GET
+   * // Time: 2026-05-06T12:00:00.000Z
+   * ```
    */
   toDebugString(): string {
     return `[${this.name}] ${this.message}\nStatus: ${this.statusCode}\nURL: ${this.url}\nMethod: ${this.method}\nTime: ${this.timestamp.toISOString()}`;
@@ -36,28 +66,49 @@ export class ApiError extends Error {
 }
 
 /**
- * Network-related errors (no internet, DNS failure, timeout)
- * HTTP Status: N/A (network layer)
+ * Network-layer errors: no internet connection, DNS failure, or connection refused.
+ * HTTP Status: N/A (statusCode is always 0).
  */
 export class NetworkError extends ApiError {
+  /**
+   * @param message Human-readable description of the network failure.
+   * @param url Request URL, if available.
+   * @param method HTTP method, if available.
+   */
   constructor(message: string, url?: string, method?: string) {
     super(message, 0, url, method);
   }
 }
 
 /**
- * Authentication errors (401, 403)
- * Client lacks valid credentials or permissions
+ * Authentication or authorisation errors (401, 403).
+ * The client either lacks valid credentials or does not have permission.
+ *
+ * On a **401**, the {@link NitroAdapter} automatically clears the stored
+ * auth token before throwing this error.
+ *
+ * @param message Human-readable description.
+ * @param statusCode 401 or 403.
+ * @param url Request URL, if available.
+ * @param method HTTP method, if available.
  */
 export class AuthError extends ApiError {}
 
 /**
- * Client validation errors (400, 422)
- * Request malformed or validation failed
+ * Client validation errors (400, 422).
+ * The request was malformed or failed server-side validation.
  */
 export class ValidationError extends ApiError {
+  /** Field-level validation error messages keyed by field name. */
   public readonly validationErrors?: Record<string, string[]>;
 
+  /**
+   * @param message Human-readable summary.
+   * @param statusCode 400 or 422.
+   * @param url Request URL, if available.
+   * @param method HTTP method, if available.
+   * @param validationErrors Optional map of field names to their error messages.
+   */
   constructor(
     message: string,
     statusCode: number,
@@ -71,36 +122,66 @@ export class ValidationError extends ApiError {
 }
 
 /**
- * Server errors (500, 502, 503, 504)
- * Something went wrong on the server
+ * Server errors (500, 502, 503, 504).
+ * Something went wrong on the server side.
+ *
+ * @param message Human-readable description.
+ * @param statusCode 5xx status code.
+ * @param url Request URL, if available.
+ * @param method HTTP method, if available.
  */
 export class ServerError extends ApiError {}
 
 /**
- * Request timeout errors
- * Request took too long to complete
+ * Request timeout errors.
+ * The server did not respond within the configured timeout window.
+ * HTTP Status: 408.
  */
 export class TimeoutError extends ApiError {
+  /**
+   * @param message Human-readable description.
+   * @param url Request URL, if available.
+   * @param method HTTP method, if available.
+   */
   constructor(message: string, url?: string, method?: string) {
     super(message, 408, url, method);
   }
 }
 
 /**
- * Resource not found errors (404)
+ * Resource not found errors.
+ * HTTP Status: 404.
  */
 export class NotFoundError extends ApiError {
+  /**
+   * @param message Human-readable description.
+   * @param url Request URL, if available.
+   * @param method HTTP method, if available.
+   */
   constructor(message: string, url?: string, method?: string) {
     super(message, 404, url, method);
   }
 }
 
 /**
- * Rate limit errors (429)
+ * Rate limit errors.
+ * The server has rejected the request because too many have been sent.
+ * HTTP Status: 429.
  */
 export class RateLimitError extends ApiError {
+  /**
+   * Number of seconds to wait before retrying, as advertised by the server
+   * in the `Retry-After` response header. May be `undefined` if the header
+   * was absent.
+   */
   public readonly retryAfter?: number;
 
+  /**
+   * @param message Human-readable description.
+   * @param url Request URL, if available.
+   * @param method HTTP method, if available.
+   * @param retryAfter Seconds until the rate limit resets, if provided by the server.
+   */
   constructor(
     message: string,
     url?: string,

package/src/api/index.ts

@@ -1,27 +1,27 @@
-import { AxiosAdapter } from './axios-adapter';
+import { NitroAdapter } from './nitro-adapter';
 
 /**
- * Default API request instance
- * Pre-configured with default settings
+ * Pre-configured default adapter instance.
  *
- * Usage:
- * ```typescript
- * import { apiRequest } from '@navegarti/rn-design-system/api';
+ * The `baseURL` placeholder is intentionally generic — consuming applications
+ * should create their own instance (or override it) with their actual API URL:
  *
- * const response = await apiRequest.get<User>('/users/123');
- * if (response.success) {
- *   console.log(response.data);
- * }
+ * ```ts
+ * import { NitroAdapter } from '@navegarti/rn-design-system/api';
+ *
+ * export const api = new NitroAdapter({
+ *   baseURL: 'https://api.myapp.com',
+ *   timeout: 10_000,
+ * });
  * ```
  */
-export const apiRequest = new AxiosAdapter({
-  baseURL: 'https://api.example.com', // Will be overridden by consumers
-  timeout: 30000,
+export const apiRequest = new NitroAdapter({
+  baseURL: 'https://api.example.com', // Override in your application
+  timeout: 30_000,
   retryAttempts: 3,
 });
 
-export { AxiosAdapter } from './axios-adapter';
 export * from './errors';
+export { NitroAdapter } from './nitro-adapter';
 export { useAuthStore } from './stores/auth-store';
-// Re-export types and classes for consumer use
 export * from './types';

package/src/api/nitro-adapter.ts

@@ -0,0 +1,357 @@
+import { fetch } from 'react-native-nitro-fetch';
+import {
+  AuthError,
+  NetworkError,
+  NotFoundError,
+  RateLimitError,
+  ServerError,
+  TimeoutError,
+  ValidationError,
+} from './errors';
+import { executeWithRetry } from './retry-strategy';
+import { useAuthStore } from './stores/auth-store';
+import type {
+  ApiConfig,
+  IHttpAdapter,
+  RequestConfig,
+  RetryConfig,
+} from './types';
+
+/**
+ * HTTP adapter powered by react-native-nitro-fetch.
+ *
+ * Features:
+ * - Automatic `Authorization: Bearer` token injection from the Zustand auth store.
+ * - Exponential back-off retry for transient failures (408, 429, 5xx).
+ * - AbortController-based request timeout with configurable duration.
+ * - Automatic 401 logout — clears the auth token so store subscribers can redirect.
+ * - Typed error hierarchy for precise error handling at call sites.
+ *
+ * @example
+ * ```ts
+ * const api = new NitroAdapter({ baseURL: 'https://api.example.com' });
+ * api.addToken(accessToken);
+ *
+ * const user = await api.get<User>('/users/me');
+ * const post = await api.post<Post>('/posts', { title: 'Hello world' });
+ * ```
+ */
+export class NitroAdapter implements IHttpAdapter {
+  private readonly baseURL: string;
+  private readonly timeout: number;
+  private readonly defaultHeaders: Record<string, string>;
+  private readonly retryConfig: RetryConfig;
+
+  /**
+   * @param config Adapter configuration: base URL, timeout, retry attempts,
+   *   and optional default headers merged into every request.
+   */
+  constructor(config: ApiConfig) {
+    this.baseURL = config.baseURL;
+    this.timeout = config.timeout ?? 30_000;
+    this.defaultHeaders = {
+      'Content-Type': 'application/json',
+      ...config.headers,
+    };
+    this.retryConfig = {
+      maxAttempts: config.retryAttempts ?? 3,
+      baseDelay: 1_000,
+      maxDelay: 10_000,
+      retryableStatusCodes: [408, 429, 500, 502, 503, 504],
+    };
+  }
+
+  /**
+   * Resolves a path or a full URL.
+   * Full URLs (starting with `http`) are used as-is; relative paths are
+   * prefixed with `baseURL`.
+   */
+  private resolveUrl(url: string): string {
+    return url.startsWith('http') ? url : `${this.baseURL}${url}`;
+  }
+
+  /**
+   * Builds the merged headers object for a single request.
+   * Merge priority (lowest → highest): defaults → auth token → per-request overrides.
+   * The token is read fresh from the auth store on every call.
+   */
+  private buildHeaders(extra?: Record<string, string>): Record<string, string> {
+    const token = useAuthStore.getState().token;
+    const auth: Record<string, string> = token
+      ? { Authorization: `Bearer ${token}` }
+      : {};
+    return { ...this.defaultHeaders, ...auth, ...extra };
+  }
+
+  /**
+   * Wraps the nitro-fetch `fetch` call with an AbortController-based timeout.
+   *
+   * - Throws {@link TimeoutError} when **our** timeout fires.
+   * - Propagates a user-provided `AbortSignal` so both explicit cancellation
+   *   and timeout work simultaneously.
+   * - Re-throws any other error untouched.
+   */
+  private async performFetch(
+    fullUrl: string,
+    init: RequestInit,
+    url: string,
+    method: string,
+  ): Promise<Response> {
+    const controller = new AbortController();
+    let didTimeout = false;
+
+    const timer = setTimeout(() => {
+      didTimeout = true;
+      controller.abort();
+    }, this.timeout);
+
+    // Propagate user's cancel signal so an explicit abort() also cancels the request.
+    const userSignal = init.signal;
+    if (userSignal) {
+      userSignal.addEventListener('abort', () => controller.abort(), {
+        once: true,
+      });
+    }
+
+    try {
+      // Pass our controller's signal; nitro-fetch honours the standard AbortSignal.
+      return await fetch(fullUrl, {
+        ...init,
+        signal: controller.signal,
+      } as Parameters<typeof fetch>[1]);
+    } catch (error) {
+      if (didTimeout) {
+        throw new TimeoutError(
+          'Request timeout - server took too long to respond',
+          url,
+          method,
+        );
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Reads a failed response body and throws the appropriate typed error.
+   *
+   * On **401 Unauthorized**, the auth token is cleared before throwing
+   * {@link AuthError} so that any Zustand subscriber watching `token` can
+   * redirect the user to the login screen automatically.
+   *
+   * @returns This method always throws — it never resolves.
+   */
+  private async parseErrorResponse(
+    response: Response,
+    url: string,
+    method: string,
+  ): Promise<never> {
+    let message = 'An error occurred';
+    let validationErrors: Record<string, string[]> | undefined;
+
+    try {
+      const body = (await response.json()) as {
+        message?: string;
+        errors?: Record<string, string[]>;
+      };
+      message = body.message ?? message;
+      validationErrors = body.errors;
+    } catch {
+      message = response.statusText || message;
+    }
+
+    const { status } = response;
+
+    if (status === 401) {
+      // Auto-logout: clear token so store subscribers can redirect.
+      useAuthStore.getState().clearToken();
+      throw new AuthError(message, status, url, method);
+    }
+
+    if (status === 403) {
+      throw new AuthError(message, status, url, method);
+    }
+
+    if (status === 404) {
+      throw new NotFoundError(message, url, method);
+    }
+
+    if (status === 429) {
+      const retryAfter =
+        Number(response.headers.get('retry-after')) || undefined;
+      throw new RateLimitError(message, url, method, retryAfter);
+    }
+
+    if (status === 400 || status === 422) {
+      throw new ValidationError(message, status, url, method, validationErrors);
+    }
+
+    if (status >= 500) {
+      throw new ServerError(message, status, url, method);
+    }
+
+    throw new NetworkError(message, url, method);
+  }
+
+  /**
+   * Core request runner: resolves the URL, builds headers, executes the
+   * request with retry logic, and parses the response into `T`.
+   *
+   * A user-initiated `AbortError` (signal not caused by our timeout) is
+   * surfaced as a {@link NetworkError} with the message "Request was cancelled".
+   */
+  private async executeRequest<T>(
+    url: string,
+    method: string,
+    init: { method: string; body?: string | null },
+    config?: RequestConfig,
+  ): Promise<T> {
+    const fullUrl = this.resolveUrl(url);
+    const headers = this.buildHeaders(config?.headers);
+
+    const mergedInit: RequestInit = { ...init, headers };
+
+    if (config?.signal !== undefined) {
+      mergedInit.signal = config.signal;
+    }
+
+    // `cache` and `credentials` are not in RN's RequestInit declaration but are
+    // accepted by react-native-nitro-fetch at runtime.
+    const extendedInit = mergedInit as Record<string, unknown>;
+    if (config?.cache !== undefined) {
+      extendedInit.cache = config.cache;
+    }
+    if (config?.credentials !== undefined) {
+      extendedInit.credentials = config.credentials;
+    }
+
+    let response: Response;
+    try {
+      response = await executeWithRetry(
+        () => this.performFetch(fullUrl, mergedInit, url, method),
+        this.retryConfig,
+        (attempt, delay, error) => {
+          console.log(
+            `[API Retry] Attempt ${attempt} failed, retrying in ${delay}ms…`,
+            error.message,
+          );
+        },
+      );
+    } catch (error) {
+      // User-initiated cancellation (our timeout converts its AbortError to TimeoutError,
+      // so any remaining AbortError here came from the caller's own signal).
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new NetworkError('Request was cancelled', url, method);
+      }
+      throw error;
+    }
+
+    if (!response.ok) {
+      return this.parseErrorResponse(response, url, method);
+    }
+
+    // 204 No Content or non-JSON response — return undefined typed as T.
+    const contentType = response.headers.get('content-type');
+    if (response.status === 204 || !contentType?.includes('application/json')) {
+      return undefined as T;
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  /**
+   * Performs a GET request.
+   *
+   * @template T Expected response body type.
+   * @param url Request path or full URL.
+   * @param config Optional per-request overrides (headers, signal, cache, credentials).
+   */
+  async get<T = unknown>(url: string, config?: RequestConfig): Promise<T> {
+    return this.executeRequest<T>(url, 'GET', { method: 'GET' }, config);
+  }
+
+  /**
+   * Performs a POST request.
+   *
+   * @template T Expected response body type.
+   * @param url Request path or full URL.
+   * @param data Request body — will be JSON-serialised if provided.
+   * @param config Optional per-request overrides.
+   */
+  async post<T = unknown>(
+    url: string,
+    data?: unknown,
+    config?: RequestConfig,
+  ): Promise<T> {
+    return this.executeRequest<T>(
+      url,
+      'POST',
+      {
+        method: 'POST',
+        body: data !== undefined ? JSON.stringify(data) : null,
+      },
+      config,
+    );
+  }
+
+  /**
+   * Performs a PUT request.
+   *
+   * @template T Expected response body type.
+   * @param url Request path or full URL.
+   * @param data Request body — will be JSON-serialised if provided.
+   * @param config Optional per-request overrides.
+   */
+  async put<T = unknown>(
+    url: string,
+    data?: unknown,
+    config?: RequestConfig,
+  ): Promise<T> {
+    return this.executeRequest<T>(
+      url,
+      'PUT',
+      {
+        method: 'PUT',
+        body: data !== undefined ? JSON.stringify(data) : null,
+      },
+      config,
+    );
+  }
+
+  /**
+   * Performs a DELETE request.
+   *
+   * @template T Expected response body type.
+   * @param url Request path or full URL.
+   * @param config Optional per-request overrides.
+   */
+  async delete<T = unknown>(url: string, config?: RequestConfig): Promise<T> {
+    return this.executeRequest<T>(url, 'DELETE', { method: 'DELETE' }, config);
+  }
+
+  /**
+   * Stores an auth token and attaches it as `Authorization: Bearer <token>`
+   * on all subsequent requests.
+   *
+   * @param token Bearer token value.
+   */
+  addToken(token: string): void {
+    useAuthStore.getState().setToken(token);
+  }
+
+  /**
+   * Clears the stored auth token, preventing it from being sent on
+   * subsequent requests.
+   */
+  removeToken(): void {
+    useAuthStore.getState().clearToken();
+  }
+
+  /**
+   * Returns the currently stored auth token, or `null` if none is set.
+   */
+  getToken(): string | null {
+    return useAuthStore.getState().token;
+  }
+}