@navegarti/rn-design-system 0.8.5 → 0.8.7

package/lib/module/api/errors.js

@@ -1,10 +1,35 @@
 "use strict";
 
 /**
- * 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). */
+
+  /** URL of the request that produced this error. */
+
+  /** HTTP method of the request that produced this error. */
+
+  /** Timestamp at which the error was created. */
+
+  /**
+   * @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, statusCode, url, method) {
     super(message);
     this.name = this.constructor.name;
@@ -14,13 +39,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.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() {
     return `[${this.name}] ${this.message}\nStatus: ${this.statusCode}\nURL: ${this.url}\nMethod: ${this.method}\nTime: ${this.timestamp.toISOString()}`;
@@ -28,26 +62,48 @@ 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, url, method) {
     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. */
+
+  /**
+   * @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, statusCode, url, method, validationErrors) {
     super(message, statusCode, url, method);
     this.validationErrors = validationErrors;
@@ -55,34 +111,65 @@ 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, url, method) {
     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, url, method) {
     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.
+   */
+
+  /**
+   * @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, url, method, retryAfter) {
     super(message, 429, url, method);
     this.retryAfter = retryAfter;

package/lib/module/api/index.js

@@ -1,30 +1,30 @@
 "use strict";
 
-import { AxiosAdapter } from "./axios-adapter.js";
+import { NitroAdapter } from "./nitro-adapter.js";
 
 /**
- * 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({
+export const apiRequest = new NitroAdapter({
   baseURL: 'https://api.example.com',
-  // Will be overridden by consumers
-  timeout: 30000,
+  // Override in your application
+  timeout: 30_000,
   retryAttempts: 3
 });
-export { AxiosAdapter } from "./axios-adapter.js";
 export * from "./errors.js";
+export { NitroAdapter } from "./nitro-adapter.js";
 export { useAuthStore } from "./stores/auth-store.js";
-// Re-export types and classes for consumer use
 export * from "./types.js";
 //# sourceMappingURL=index.js.map

package/lib/module/api/nitro-adapter.js

@@ -0,0 +1,290 @@
+"use strict";
+
+import { fetch } from 'react-native-nitro-fetch';
+import { AuthError, NetworkError, NotFoundError, RateLimitError, ServerError, TimeoutError, ValidationError } from "./errors.js";
+import { executeWithRetry } from "./retry-strategy.js";
+import { useAuthStore } from "./stores/auth-store.js";
+/**
+ * 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 {
+  /**
+   * @param config Adapter configuration: base URL, timeout, retry attempts,
+   *   and optional default headers merged into every request.
+   */
+  constructor(config) {
+    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`.
+   */
+  resolveUrl(url) {
+    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.
+   */
+  buildHeaders(extra) {
+    const token = useAuthStore.getState().token;
+    const auth = 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.
+   */
+  async performFetch(fullUrl, init, url, method) {
+    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
+      });
+    } 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.
+   */
+  async parseErrorResponse(response, url, method) {
+    let message = 'An error occurred';
+    let validationErrors;
+    try {
+      const body = await response.json();
+      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".
+   */
+  async executeRequest(url, method, init, config) {
+    const fullUrl = this.resolveUrl(url);
+    const headers = this.buildHeaders(config?.headers);
+    const mergedInit = {
+      ...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;
+    if (config?.cache !== undefined) {
+      extendedInit.cache = config.cache;
+    }
+    if (config?.credentials !== undefined) {
+      extendedInit.credentials = config.credentials;
+    }
+    let 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;
+    }
+    return response.json();
+  }
+
+  /**
+   * 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(url, config) {
+    return this.executeRequest(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(url, data, config) {
+    return this.executeRequest(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(url, data, config) {
+    return this.executeRequest(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(url, config) {
+    return this.executeRequest(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) {
+    useAuthStore.getState().setToken(token);
+  }
+
+  /**
+   * Clears the stored auth token, preventing it from being sent on
+   * subsequent requests.
+   */
+  removeToken() {
+    useAuthStore.getState().clearToken();
+  }
+
+  /**
+   * Returns the currently stored auth token, or `null` if none is set.
+   */
+  getToken() {
+    return useAuthStore.getState().token;
+  }
+}
+//# sourceMappingURL=nitro-adapter.js.map

package/lib/module/api/retry-strategy.js

@@ -1,30 +1,46 @@
 "use strict";
 
 /**
- * Calculates exponential backoff delay
- * Formula: min(baseDelay * (2 ^ attempt), maxDelay)
+ * Calculates exponential back-off delay.
+ * Formula: `min(baseDelay × 2^attempt, maxDelay)`
+ *
+ * @param attempt Zero-based attempt index.
+ * @param baseDelay Starting delay in milliseconds.
+ * @param maxDelay Upper ceiling for the delay in milliseconds.
  */
 export function calculateBackoffDelay(attempt, baseDelay, maxDelay) {
-  const exponentialDelay = baseDelay * 2 ** attempt;
-  return Math.min(exponentialDelay, maxDelay);
+  return Math.min(baseDelay * 2 ** attempt, maxDelay);
 }
 
 /**
- * Determines if an error is retryable based on configuration
+ * Determines whether an error should trigger another retry attempt.
+ *
+ * Uses duck-typing on the `statusCode` property so it works with any
+ * error class that carries an HTTP status code — no dependency on a
+ * specific HTTP library's error type.
+ *
+ * @param error The thrown error.
+ * @param retryConfig Retry configuration.
  */
 export function isRetryableError(error, retryConfig) {
-  // Network errors (no response) are always retryable
-  if (!error.response) {
-    return true;
+  const statusCode = error.statusCode;
+
+  // Unknown error type (e.g. user-initiated AbortError) — do not retry.
+  if (statusCode === undefined) {
+    return false;
   }
-  const statusCode = error.response.status;
 
-  // Check if status code is in retryable list
+  // Network-layer errors (statusCode 0) are always retried.
+  if (statusCode === 0) {
+    return true;
+  }
   return retryConfig.retryableStatusCodes.includes(statusCode);
 }
 
 /**
- * Sleep utility for retry delays
+ * Pauses execution for the specified duration.
+ *
+ * @param ms Duration in milliseconds.
  */
 export function sleep(ms) {
   return new Promise(resolve => {
@@ -33,8 +49,15 @@ export function sleep(ms) {
 }
 
 /**
- * Executes a request with retry logic
- * @template T - The expected response type
+ * Executes `requestFn` with exponential back-off retry logic.
+ * Retries only when `isRetryableError` returns `true` and there are
+ * remaining attempts.
+ *
+ * @template T The expected resolved type of `requestFn`.
+ * @param requestFn Async function to call on each attempt.
+ * @param retryConfig Retry strategy configuration.
+ * @param onRetry Optional callback invoked before each retry,
+ *   receiving the attempt number (1-based), delay in ms, and the error.
  */
 export async function executeWithRetry(requestFn, retryConfig, onRetry) {
   let lastError;
@@ -42,27 +65,21 @@ export async function executeWithRetry(requestFn, retryConfig, onRetry) {
     try {
       return await requestFn();
     } catch (error) {
-      const axiosError = error;
-      lastError = axiosError;
-
-      // Don't retry if not retryable or if this was the last attempt
+      const err = error;
+      lastError = err;
       const isLastAttempt = attempt === retryConfig.maxAttempts - 1;
-      if (!isRetryableError(axiosError, retryConfig) || isLastAttempt) {
-        throw error;
+      if (!isRetryableError(err, retryConfig) || isLastAttempt) {
+        throw err;
       }
-
-      // Calculate delay and wait before retrying
       const delay = calculateBackoffDelay(attempt, retryConfig.baseDelay, retryConfig.maxDelay);
-
-      // Notify callback if provided
       if (onRetry) {
-        onRetry(attempt + 1, delay, axiosError);
+        onRetry(attempt + 1, delay, err);
       }
       await sleep(delay);
     }
   }
 
-  // This should never be reached, but TypeScript needs it
+  // Unreachable — the loop always returns or throws before exhausting attempts.
   throw lastError;
 }
 //# sourceMappingURL=retry-strategy.js.map

package/lib/module/api/stores/auth-store.js

@@ -3,12 +3,26 @@
 import { create } from 'zustand';
 
 /**
- * Authentication store state
+ * Shape of the authentication store state.
  */
 
 /**
- * Zustand store for managing authentication token
- * Token is stored in memory and used for Authorization header
+ * Zustand store for managing the authentication token.
+ *
+ * The token is kept in memory and automatically injected as an
+ * `Authorization: Bearer` header by {@link NitroAdapter} on every request.
+ *
+ * Subscribe to `token` changes to trigger navigation to the login screen
+ * when the user is logged out:
+ *
+ * ```ts
+ * useAuthStore.subscribe(
+ *   (state) => state.token,
+ *   (token) => {
+ *     if (!token) navigation.replace('Login');
+ *   },
+ * );
+ * ```
  */
 export const useAuthStore = create(set => ({
   token: null,

package/lib/module/api/types.js

@@ -1,4 +1,2 @@
 "use strict";
-
-export {};
 //# sourceMappingURL=types.js.map

package/lib/module/api.js

@@ -6,5 +6,5 @@
  */
 
 export { ApiError, AuthError, NetworkError, NotFoundError, RateLimitError, ServerError, TimeoutError, ValidationError } from "./api/errors.js";
-export { AxiosAdapter, apiRequest, useAuthStore } from "./api/index.js";
+export { apiRequest, NitroAdapter, useAuthStore } from "./api/index.js";
 //# sourceMappingURL=api.js.map