@jysperu/browser-api

Librería moderna para realizar peticiones HTTP con TypeScript, manejo de errores robusto y configuración flexible.

🚀 Características

• 🔧 TypeScript completamente tipado con generics
• ⚡ API moderna basada en fetch con timeout configurable
• 🛡️ Manejo de errores comprehensivo y normalizado
• 🎯 Flexible - Soporta GET, POST, PUT, DELETE, PATCH
• 📦 Sin dependencias externas
• 🔄 Cache control personalizable
• ⚙️ Configurable globalmente
• 🌐 Detección automática del tag <base> HTML

📦 Instalación

npm install @jysperu/browser-api

⚡ Inicio Rápido

import { configure } from "@jysperu/browser-api";

// Configuración global (opcional)
configure({
  base: "https://api.ejemplo.com",
  timeout: 5000,
});

import { api, api_get, api_post } from "@jysperu/browser-api";

// GET request simple
const usuarios = await api_get<User[]>("/usuarios");
if (usuarios.success) {
  console.log("Usuarios:", usuarios.data);
}

// POST request
const nuevoUsuario = await api_post<User>("/usuarios", {
  nombre: "Juan Pérez",
  email: "[email protected]",
});

// Usando la función principal
const result = await api<User>("/usuarios", { nombre: "Juan" }, null, "GET");

📚 API Reference

🌐 detectBaseUrl

Detecta automáticamente la URL base desde el tag <base> del documento.

function detectBaseUrl(): string;

Comportamiento:

• Si existe un tag <base href="..."> en el documento, usa esa URL
• Si no existe, usa window.location.origin como fallback
• En entornos sin DOM (SSR), retorna cadena vacía
• Normaliza la URL removiendo barras finales

Ejemplo:

<!-- En tu HTML -->
<base href="https://api.miapp.com/v1/" />

import { detectBaseUrl } from "@jysperu/browser-api";

const baseUrl = detectBaseUrl();
console.log(baseUrl); // "https://api.miapp.com/v1"

🔧 configure

Configura los ajustes globales de la API.

interface RequestConfig {
  timeout?: number; // Timeout en milisegundos
  base?: string; // URL base para las peticiones
}

function configure(config: Partial<RequestConfig>): void;

🌐 api_get

Realiza peticiones GET con parámetros de consulta.

function api_get<T = unknown>(endpoint: string, params?: ApiParams, cachecode?: string | number | null): Promise<ApiResponse<T>>;

📤 api_post

Realiza peticiones POST con datos en el cuerpo.

function api_post<T = unknown>(endpoint: string, body?: ApiBody): Promise<ApiResponse<T>>;

🔄 api_request

Función genérica para cualquier método HTTP.

function api_request<T = unknown>(
  endpoint: string,
  method?: HttpMethod,
  data?: ApiParams | ApiBody,
  cacheCode?: string | number | null
): Promise<ApiResponse<T>>;

🎯 api (función principal)

Función principal con retrocompatibilidad.

function api<T = unknown>(
  endpoint: string,
  bodyOrParams?: ApiParams | ApiBody,
  cacheCode?: string | number | null,
  method?: HttpMethod
): Promise<ApiResponse<T>>;

🏗️ Funciones Auxiliares

buildUrl

Construye URLs con parámetros de consulta. Maneja diferentes tipos de endpoints:

function buildUrl(endpoint: string, params?: ApiParams, cachecode?: string | number | null): string;

Tipos de endpoints soportados:

// URL completa - se usa tal como está
buildUrl("https://otra-api.com/datos");

// Ruta absoluta - se concatena con la base configurada
buildUrl("/api/usuarios"); // → https://mibase.com/api/usuarios

// Ruta relativa - se agrega / automáticamente
buildUrl("usuarios"); // → https://mibase.com/usuarios

fetch2

Fetch con timeout configurable.

function fetch2(url: string, options: RequestInit, timeout?: number): Promise<Response>;

processFetchJsonResponse

Normaliza respuestas JSON.

function processFetchJsonResponse<T = unknown>(json: any): ApiResponse<T>;

📋 Tipos TypeScript

ApiResponse

interface ApiResponse<T = unknown> {
  success: boolean; // true si la operación fue exitosa
  log: string; // Mensaje de log/error
  data?: T; // Datos de respuesta (opcional)
  [key: string]: unknown;
}

ApiParams

interface ApiParams {
  [key: string]: string | number | boolean;
}

ApiBody

interface ApiBody {
  [key: string]: unknown;
}

HttpMethod

type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";

🌐 Detección Automática de Base URL

La librería detecta automáticamente la URL base de tu aplicación:

Tag Base HTML

<!DOCTYPE html>
<html>
  <head>
    <!-- La librería detecta automáticamente este tag -->
    <base href="https://api.miapp.com/v2/" />
  </head>
  <body>
    <!-- Tu aplicación -->
  </body>
</html>

import { detectBaseUrl, api_get } from "@jysperu/browser-api";

// Detecta automáticamente: "https://api.miapp.com/v2"
console.log(detectBaseUrl());

// Todas las peticiones usan esta base automáticamente
const datos = await api_get("/usuarios"); // → https://api.miapp.com/v2/usuarios

Sin Tag Base

Si no hay tag <base>, usa window.location.origin:

// En https://miapp.com/dashboard
console.log(detectBaseUrl()); // "https://miapp.com"

const datos = await api_get("/api/datos"); // → https://miapp.com/api/datos

Override Manual

import { configure } from "@jysperu/browser-api";

// Sobrescribir la detección automática
configure({
  base: "https://api-personalizada.com",
});

🌐 Compatibilidad

• ✅ Todos los navegadores modernos (con soporte para fetch)
• ✅ Compatible con frameworks (React, Vue, Angular, Svelte)
• ✅ SSR friendly
• ✅ TypeScript nativo
• ✅ ES Modules y CommonJS

🔗 Enlaces y Recursos

• 📘 Repositorio: GitLab - browser-api
• 🐛 Issues: Reportar problemas
• 📦 npm: @jysperu/browser-api
• 🏢 JYS Perú: www.jys.pe

📄 Licencia

MIT License - Consulta el archivo LICENSE para detalles completos.

MIT License - Copyright (c) 2025 JYS Perú

Desarrollado con ❤️ por JYS Perú