Almacenamiento

El SDK usa un StorageProvider intercambiable para persistir los tokens de autenticación. Por defecto, los tokens solo viven en memoria y se pierden al recargar la página.

Comportamiento por defecto

El SDK incluye un noopStorageProvider que no hace nada:

const noopStorageProvider: StorageProvider = {
  getItem: async () => null,
  setItem: async () => {},
  removeItem: async () => {},
};

Esto significa que los tokens no se persisten por defecto. Debes configurar un StorageProvider si quieres que los tokens sobrevivan a recargas de página o reinicios de la aplicación.

Interfaz StorageProvider

type StorageProvider = {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
};

Todos los métodos son async para soportar backends de almacenamiento del lado del servidor (cookies, bases de datos, etc.).

Claves de almacenamiento

El SDK usa dos claves para almacenar los tokens:

Clave	Valor
heuristikAuth_accessToken	Token de acceso
heuristikAuth_refreshToken	Token de refresco

Adaptador localStorage

El adaptador más sencillo envuelve localStorage:

import { setStorageProvider } from '@heuristik/hhjssdk';

setStorageProvider({
  getItem: async (key) => localStorage.getItem(key),
  setItem: async (key, value) => localStorage.setItem(key, value),
  removeItem: async (key) => localStorage.removeItem(key),
});

aviso

localStorage almacena los tokens como texto plano accesible para cualquier JavaScript en la página. Es adecuado para desarrollo pero no se recomienda para producción.

Adaptador basado en cookies

Para mayor seguridad, usa un adaptador de cookies HttpOnly que delega en tu servidor:

import { setStorageProvider } from '@heuristik/hhjssdk';

setStorageProvider({
  getItem: async (key) => {
    // Leer desde una cookie no HttpOnly (o llamar a tu servidor)
    const match = document.cookie.match(new RegExp(`${key}=([^;]+)`));
    return match ? decodeURIComponent(match[1]) : null;
  },
  setItem: async (key, value) => {
    document.cookie = `${key}=${encodeURIComponent(value)}; path=/; SameSite=Strict`;
  },
  removeItem: async (key) => {
    document.cookie = `${key}=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT`;
  },
});

Recomendación para producción

En producción, usa cookies HttpOnly gestionadas por tu backend. El StorageProvider en el cliente debería llamar a endpoints del servidor que establezcan, lean y borren cookies HttpOnly. Esto evita que ataques XSS accedan a los tokens.

Orden de configuración

Importante

Llama a setStorageProvider() antes de crear el HeuristikClient. El proveedor se lee cuando client.init() llama a loadAuthTokens().

import { HeuristikClient, setStorageProvider } from '@heuristik/hhjssdk';

// 1. Configurar el almacenamiento PRIMERO
setStorageProvider({ /* ... */ });

// 2. Luego crear el cliente
const client = new HeuristikClient({ /* ... */ });

// 3. Init cargará los tokens desde tu proveedor
await client.init();

Manejo de errores

Las operaciones de almacenamiento están envueltas en try/catch internamente. Si el proveedor lanza un error, el SDK lo envuelve en un SDKError con el mensaje apropiado:

Operación	Clave de mensaje de error
Guardar tokens	STORAGE_SAVE_TOKENS_FAILED
Cargar tokens	STORAGE_LOAD_TOKENS_FAILED
Borrar tokens	STORAGE_CLEAR_TOKENS_FAILED