Sesiones y almacenamiento

Ciclo de vida de la sesión

Método	Qué hace
ensure(input?)	Reutiliza una sesión válida almacenada, o genera una nueva vía getBootstrapAssertion.
getStoredSession()	Devuelve los metadatos públicos de la sesión, o null.
clearStoredSession()	Elimina la sesión almacenada localmente.
revokeSession()	Revoca la sesión en el servidor.

const stored = await client.getStoredSession();
if (stored && stored.expiresAt < Date.now()) {
  await client.ensure({ forceRefresh: true });
}

getStoredSession() devuelve PublicStoredExternalAgentSession — el registro almacenado menos su sessionToken. No existe ningún método público que te devuelva el token portador.

Adaptadores de almacenamiento

Por defecto el SDK mantiene la sesión en memoria, así que se pierde al recargar. Proporciona un adaptador RuntimeStorage para conservarla:

import type { RuntimeStorage } from '@agentshelf/agent-runtime-sdk-core';
import type { ExternalAgentStoredSessionRecord } from '@agentshelf/external-agents-sdk';

const storage: RuntimeStorage<ExternalAgentStoredSessionRecord> = {
  get: async (key) => secureStore.get(key),
  set: async (key, value) => secureStore.set(key, value),
  remove: async (key) => secureStore.remove(key),
};

const client = createExternalAgentClient({
  externalAgentRef: 'ext_agent_public_12345678',
  getBootstrapAssertion,
  storage,
  storageKey: 'agentshelf:checkout-agent',
});

Los tres métodos pueden devolver un valor síncrono o una promesa.

Elige el almacén con cuidado

El registro almacenado incluye sessionToken, la credencial portadora que el SDK usa en cada llamada a la API pública. Cualquier cosa capaz de leer tu almacenamiento puede actuar como esa sesión hasta que expire.

En un navegador, localStorage es legible por cualquier script del origen, incluidos scripts de terceros inyectados. Prefiere un almacén de vida más corta, acota la sesión al mínimo y llama a revokeSession() cuando el usuario cierre sesión.

Usa un storageKey distinto por agente si una misma página integra más de uno; de lo contrario, el segundo cliente sobrescribirá la sesión del primero.

Qué contiene un registro de sesión

ExternalAgentStoredSessionRecord contiene externalAgentRef, sessionRef, sessionToken, expiresAt y, opcionalmente, externalAppRef, externalUserRef y workspaceBindingRef. Todos los identificadores que incluye son refs públicas.