npm package: @jysperu/browser-cookie
Description: Utilidades modernas para gestión de cookies en el navegador usando Cookie Store API
Author: JYS Perú
Latest version: 1.0.1

# @jysperu/browser-cookie

[![npm version](https://badge.fury.io/js/@jysperu%2Fbrowser-cookie.svg)](https://badge.fury.io/js/@jysperu%2Fbrowser-cookie)
[![npm downloads](https://img.shields.io/npm/dm/@jysperu/browser-cookie)](https://www.npmjs.com/package/@jysperu/browser-cookie)
[![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-cookie)](https://bundlephobia.com/package/@jysperu/browser-cookie)

Utilidades modernas para gestión de cookies en el navegador usando la **Cookie Store API**.

## 🚀 Características

- 🍪 **Cookie Store API** moderna y asíncrona
- 🔧 **TypeScript** completamente tipado
- ✅ **Validaciones** robustas de entrada
- 🛡️ **Manejo de errores** comprehensivo
- 📱 **Compatibilidad** con navegadores modernos
- 🎯 **API intuitiva** y fácil de usar

## 📦 Instalación

```bash
npm install @jysperu/browser-cookie
```

## ⚡ Inicio Rápido

```typescript
import { getCookie, setCookie, delCookie } from "@jysperu/browser-cookie";

// Obtener una cookie
const valor = await getCookie("mi-cookie");
console.log(valor); // "valor-de-la-cookie" o null

// Establecer una cookie
await setCookie("usuario", "juan123", {
  expiresInSeconds: 3600, // 1 hora
  path: "/",
  secure: true,
  sameSite: "strict",
});

// Eliminar una cookie
await delCookie("usuario");
```

## 📚 API Reference

### 🔍 getCookie

Obtiene una cookie por su nombre.

```typescript
async function getCookie(name: string, returnValue?: boolean): Promise<string | CookieListItem | null>;
```

**Parámetros:**

- `name` - Nombre de la cookie
- `returnValue` - Si `true` retorna solo el valor, si `false` retorna el objeto completo (por defecto: `true`)

**Ejemplos:**

```typescript
// Obtener solo el valor
const valor = await getCookie("session-id");
console.log(valor); // "abc123" o null

// Obtener objeto completo de la cookie
const cookie = await getCookie("session-id", false);
console.log(cookie);
// {
//   name: "session-id",
//   value: "abc123",
//   domain: "example.com",
//   ...
// }
```

### 🔧 setCookie

Establece una cookie con opciones configurables.

```typescript
interface CookieOptions {
  expiresInSeconds?: number;
  path?: string;
  domain?: string;
  secure?: boolean;
  sameSite?: "strict" | "lax" | "none";
}

async function setCookie(name: string, value: string | null, options?: CookieOptions): Promise<CookieListItem | null>;
```

**Parámetros:**

- `name` - Nombre de la cookie
- `value` - Valor de la cookie (usar `null` para eliminar)
- `options` - Opciones de configuración

**Ejemplos:**

```typescript
// Cookie básica
await setCookie("usuario", "ana");

// Cookie con expiración
await setCookie("session", "xyz789", {
  expiresInSeconds: 1800, // 30 minutos
});

// Cookie segura para producción
await setCookie("auth-token", "token123", {
  expiresInSeconds: 86400, // 24 horas
  path: "/",
  secure: true,
  sameSite: "strict",
  domain: "miapp.com",
});

// Eliminar cookie (pasando null como valor)
await setCookie("old-cookie", null);
```

### 🗑️ delCookie

Elimina una cookie específica.

```typescript
async function delCookie(name: string, path?: string): Promise<boolean>;
```

**Parámetros:**

- `name` - Nombre de la cookie a eliminar
- `path` - Ruta de la cookie (por defecto: `"/"`)

**Ejemplo:**

```typescript
// Eliminar cookie
const eliminada = await delCookie("session-id");
console.log(eliminada); // true si se eliminó correctamente

// Eliminar cookie de una ruta específica
await delCookie("user-prefs", "/dashboard");
```

### 📋 getCookies

Obtiene todas las cookies disponibles.

```typescript
async function getCookies(url?: string): Promise<CookieListItem[]>;
```

**Parámetros:**

- `url` - URL opcional para filtrar cookies

**Ejemplo:**

```typescript
// Todas las cookies
const todasLasCookies = await getCookies();
console.log(todasLasCookies);

// Cookies de una URL específica
const cookiesEspecificas = await getCookies("https://api.miapp.com");
```

### ✅ cookieExists

Verifica si una cookie existe.

```typescript
async function cookieExists(name: string): Promise<boolean>;
```

**Ejemplo:**

```typescript
if (await cookieExists("usuario-logueado")) {
  console.log("Usuario está autenticado");
} else {
  console.log("Usuario necesita loguearse");
}
```

### 🧹 delCookies

Elimina todas las cookies del dominio actual.

```typescript
async function delCookies(): Promise<number>;
```

**Retorna:** Número de cookies eliminadas

**Ejemplo:**

```typescript
const eliminadas = await delCookies();
console.log(`Se eliminaron ${eliminadas} cookies`);
```

## 🎯 Casos de Uso Prácticos

### Manejo de Sesión

```typescript
import { getCookie, setCookie, delCookie } from "@jysperu/browser-cookie";

class SessionManager {
  private static SESSION_COOKIE = "user-session";

  static async login(userId: string, token: string) {
    await setCookie(this.SESSION_COOKIE, token, {
      expiresInSeconds: 86400, // 24 horas
      secure: true,
      sameSite: "strict",
      path: "/",
    });
  }

  static async getSession(): Promise<string | null> {
    return await getCookie(this.SESSION_COOKIE);
  }

  static async logout() {
    await delCookie(this.SESSION_COOKIE);
  }

  static async isLoggedIn(): Promise<boolean> {
    return await cookieExists(this.SESSION_COOKIE);
  }
}
```

### Preferencias de Usuario

```typescript
import { getCookie, setCookie } from "@jysperu/browser-cookie";

interface UserPreferences {
  theme: "light" | "dark";
  language: string;
  notifications: boolean;
}

class PreferencesManager {
  private static PREFS_COOKIE = "user-preferences";

  static async savePreferences(prefs: UserPreferences) {
    const prefsJson = JSON.stringify(prefs);
    await setCookie(this.PREFS_COOKIE, prefsJson, {
      expiresInSeconds: 365 * 24 * 3600, // 1 año
      path: "/",
    });
  }

  static async loadPreferences(): Promise<UserPreferences | null> {
    const prefsJson = await getCookie(this.PREFS_COOKIE);
    if (!prefsJson) return null;

    try {
      return JSON.parse(prefsJson);
    } catch {
      return null;
    }
  }

  static async resetPreferences() {
    await delCookie(this.PREFS_COOKIE);
  }
}
```

### Sistema de Carrito de Compras

```typescript
import { getCookie, setCookie } from "@jysperu/browser-cookie";

interface CartItem {
  id: string;
  name: string;
  price: number;
  quantity: number;
}

class ShoppingCart {
  private static CART_COOKIE = "shopping-cart";

  static async addItem(item: CartItem) {
    const cart = await this.getCart();
    const existingIndex = cart.findIndex((i) => i.id === item.id);

    if (existingIndex >= 0) {
      cart[existingIndex].quantity += item.quantity;
    } else {
      cart.push(item);
    }

    await this.saveCart(cart);
  }

  static async getCart(): Promise<CartItem[]> {
    const cartJson = await getCookie(this.CART_COOKIE);
    if (!cartJson) return [];

    try {
      return JSON.parse(cartJson);
    } catch {
      return [];
    }
  }

  private static async saveCart(cart: CartItem[]) {
    const cartJson = JSON.stringify(cart);
    await setCookie(this.CART_COOKIE, cartJson, {
      expiresInSeconds: 30 * 24 * 3600, // 30 días
      path: "/",
    });
  }

  static async removeItem(itemId: string) {
    const cart = await this.getCart();
    const updatedCart = cart.filter((item) => item.id !== itemId);
    await this.saveCart(updatedCart);
  }

  static async clearCart() {
    await delCookie(this.CART_COOKIE);
  }
}
```

## 🌐 Compatibilidad de Navegadores

La Cookie Store API es una tecnología moderna. Verifica la compatibilidad:

```typescript
import { getCookie } from "@jysperu/browser-cookie";

// Verificar soporte
if (typeof window !== "undefined" && window.cookieStore) {
  // Usar las funciones normalmente
  const cookie = await getCookie("mi-cookie");
} else {
  // Fallback a document.cookie o mostrar mensaje
  console.warn("Cookie Store API no está disponible");
}
```

**Navegadores soportados:**

- Chrome 87+
- Edge 87+
- Safari (soporte limitado)
- Firefox (detrás de flag experimental)

## 🔒 Mejores Prácticas de Seguridad

```typescript
// ✅ CORRECTO - Cookie segura para producción
await setCookie("auth-token", token, {
  secure: true, // Solo HTTPS
  sameSite: "strict", // Protección CSRF
  expiresInSeconds: 3600, // Expiración explícita
});

// ❌ INCORRECTO - Cookie insegura
await setCookie("auth-token", token); // Sin opciones de seguridad
```

### Configuraciones Recomendadas

```typescript
// Para tokens de autenticación
const authCookieOptions = {
  secure: true,
  sameSite: "strict" as const,
  expiresInSeconds: 1800, // 30 minutos
  path: "/",
};

// Para preferencias de usuario
const prefsCookieOptions = {
  sameSite: "lax" as const,
  expiresInSeconds: 365 * 24 * 3600, // 1 año
  path: "/",
};

// Para datos temporales
const tempCookieOptions = {
  sameSite: "lax" as const,
  expiresInSeconds: 900, // 15 minutos
  path: "/",
};
```

## 📦 Build y Distribución

```bash
# Construir el proyecto
npm run build

# Genera automáticamente:
# └── dist/
#     ├── cookie.esm.js     # ES Modules
#     ├── cookie.cjs.js     # CommonJS
#     ├── cookie.umd.js     # UMD
#     └── cookie.d.ts       # TypeScript definitions
```

## 🔗 Enlaces y Recursos

- 📘 **Repositorio**: [GitLab - browser-cookie](https://gitlab.com/tiny.node/browser/cookie)
- 🐛 **Issues**: [Reportar problemas](https://gitlab.com/tiny.node/browser/cookie/issues)
- 📦 **npm**: [@jysperu/browser-cookie](https://www.npmjs.com/package/@jysperu/browser-cookie)
- 📚 **Cookie Store API**: [MDN Documentation](https://developer.mozilla.org/en-US/docs/Web/API/Cookie_Store_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)