npm package: @jysperu/browser-api
Description: Librería moderna para realizar peticiones HTTP con manejo de errores y configuración flexible
Author: JYS Perú
Latest version: 1.0.2

# @jysperu/browser-api

[![npm version](https://badge.fury.io/js/@jysperu%2Fbrowser-api.svg)](https://badge.fury.io/js/@jysperu%2Fbrowser-api)
[![npm downloads](https://img.shields.io/npm/dm/@jysperu/browser-api)](https://www.npmjs.com/package/@jysperu/browser-api)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@jysperu/browser-api)](https://bundlephobia.com/package/@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

```bash
npm install @jysperu/browser-api
```

## ⚡ Inicio Rápido

```typescript
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: "juan@ejemplo.com",
});

// 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.

```typescript
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:**

```html
<!-- En tu HTML -->
<base href="https://api.miapp.com/v1/" />
```

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
function api_post<T = unknown>(endpoint: string, body?: ApiBody): Promise<ApiResponse<T>>;
```

### 🔄 api_request

Función genérica para cualquier método HTTP.

```typescript
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.

```typescript
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:

```typescript
function buildUrl(endpoint: string, params?: ApiParams, cachecode?: string | number | null): string;
```

**Tipos de endpoints soportados:**

```typescript
// 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.

```typescript
function fetch2(url: string, options: RequestInit, timeout?: number): Promise<Response>;
```

### processFetchJsonResponse

Normaliza respuestas JSON.

```typescript
function processFetchJsonResponse<T = unknown>(json: any): ApiResponse<T>;
```

## 📋 Tipos TypeScript

### ApiResponse

```typescript
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

```typescript
interface ApiParams {
  [key: string]: string | number | boolean;
}
```

### ApiBody

```typescript
interface ApiBody {
  [key: string]: unknown;
}
```

### HttpMethod

```typescript
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

```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>
```

```typescript
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`:

```typescript
// 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

```typescript
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](https://gitlab.com/tiny.node/browser/api)
- 🐛 **Issues**: [Reportar problemas](https://gitlab.com/tiny.node/browser/api/issues)
- 📦 **npm**: [@jysperu/browser-api](https://www.npmjs.com/package/@jysperu/browser-api)
- 🏢 **JYS Perú**: [www.jys.pe](https://www.jys.pe)

## 📄 Licencia

**MIT License** - Consulta el archivo [LICENSE](./LICENSE) para detalles completos.

```text
MIT License - Copyright (c) 2025 JYS Perú
```

---

Desarrollado con ❤️ por [**JYS Perú**](https://www.jys.pe)