refreshSnapshot

refreshSnapshot permite actualizar el contenido que está usando un cliente en modo snapshot sin reiniciar la aplicación.

Cuando llamas a este método, el cliente ejecuta de nuevo el snapshotLoader. Si el loader devuelve un snapshot más reciente que el actual, el cliente lo adopta inmediatamente y las siguientes lecturas empiezan a usarlo.

Esto resulta útil en aplicaciones que permanecen encendidas durante mucho tiempo, como servidores SSR, workers, procesos backend o aplicaciones que no se reinician después de cada publicación.

Por ejemplo, puedes publicar un nuevo snapshot en un almacenamiento remoto y pedirle después al cliente que lo recargue:

import { createClient } from '@content-island/api-client';

const client = createClient({
  accessToken: 'TU_TOKEN_DE_ACCESO',
  mode: 'snapshot',
  snapshotLoader: async () => {
    const response = await fetch('https://storage.example.com/content-island-snapshot.json');

    return response.text();
  },
});

const result = await client.refreshSnapshot();

console.log(result);

Si el snapshot remoto es más reciente, el resultado tendrá este aspecto:

{
  status: 'updated',
  meta: {
    schemaVersion: 1,
    exportedAt: '2026-06-22T10:30:00.000Z',
    projectId: '1',
    view: 'published',
  },
}

Desde ese momento, el cliente empieza a servir el contenido del nuevo snapshot.

Consejo

Consulta la guía Modo snapshot para aprender a configurar el snapshotLoader.

También puedes usar getSnapshotInfo para consultar los metadatos del snapshot que está activo en ese momento.

Interfaz

refreshSnapshot no recibe parámetros.

Devuelve una promesa con un objeto de tipo SnapshotRefreshResult:

export interface ApiClient {
  refreshSnapshot: () => Promise<SnapshotRefreshResult>;
}

Resultado

type SnapshotRefreshResult = {
  status: 'updated' | 'unchanged';
  meta: SnapshotMeta;
};

El campo status indica si el snapshot activo ha cambiado:

status	Significado
'updated'	Se encontró un snapshot más reciente y ya está activo
'unchanged'	El snapshot recibido era igual o más antiguo que el actual y se ignoró

Cuando el resultado es 'unchanged', no se lanza ningún error. El cliente continúa usando el snapshot que ya tenía cargado.

Esto evita que una respuesta retrasada o una actualización fuera de orden sustituya contenido reciente por contenido antiguo.

El campo meta contiene los metadatos del snapshot que queda activo después del refresco:

interface SnapshotMeta {
  schemaVersion: number;
  exportedAt: string;
  projectId: string;
  view: 'published' | 'preview';
}

Estos metadatos tienen la misma estructura que los devueltos por getSnapshotInfo.

Cuándo puede fallar

refreshSnapshot lanza un ApiClientError con código SNAPSHOT_MODE cuando no puede cargar o aceptar el nuevo snapshot.

En todos estos casos, el snapshot anterior se conserva y las lecturas pueden seguir utilizándolo.

El refresco falla cuando:

Situación	Motivo
el nuevo snapshot pertenece a otro projectId	un refresco no puede cambiar de proyecto
el nuevo snapshot usa otro view	un refresco no puede cambiar entre published y preview
el snapshotLoader falla	no se ha podido obtener el snapshot
el contenido no es JSON válido	el cliente no puede interpretarlo
la estructura del snapshot es incorrecta	el contenido no cumple el formato esperado
la versión de esquema no es compatible	el cliente no puede usar ese snapshot
el cliente está en modo 'api'	ese cliente no utiliza snapshots
no se configuró un snapshotLoader	no existe ninguna fuente desde la que recargar

Si el error se produce dentro del loader, el error original queda disponible en error.cause.

import { createClient, ApiClientError } from '@content-island/api-client';

const client = createClient({
  accessToken: 'TU_TOKEN_DE_ACCESO',
  mode: 'snapshot',
  snapshotLoader: async () => fetchSnapshotFromStorage(),
});

try {
  const result = await client.refreshSnapshot();

  if (result.status === 'updated') {
    console.log('El cliente ya está usando el nuevo snapshot');
  }
} catch (error) {
  if (error instanceof ApiClientError && error.code === 'SNAPSHOT_MODE') {
    console.error('No se pudo actualizar el snapshot');

    // El snapshot anterior continúa activo.
  }
}

Seguridad durante la actualización

Actualizar el snapshot no deja al cliente en un estado intermedio.

Mientras se ejecuta refreshSnapshot, una lectura utiliza el snapshot anterior completo o el snapshot nuevo completo. Nunca se sirve un snapshot cargado solo parcialmente.

También es seguro llamar a refreshSnapshot() varias veces al mismo tiempo. El cliente agrupa las llamadas concurrentes y termina conservando el snapshot más reciente que sea válido.

Si el cliente todavía no había cargado ningún snapshot, la primera llamada a refreshSnapshot() carga el snapshot inicial y lo establece como activo.