E EmDash CMS Everything Guides, use cases, plugins, templates
Español

Consultar el registro

En esta página

Este es un tema avanzado para construir tu propio software contra el registro de plugins. Si solo quieres instalar plugins en un sitio EmDash, no necesitas nada de esto — habilita el registro en tu configuración y usa el panel de administración.

El lado de descubrimiento del registro es una API pública de solo lectura. El paquete @emdash-cms/registry-client lo envuelve, para que puedas construir un directorio de plugins, una página de búsqueda o un feed de releases fuera de EmDash. El cliente funciona donde sea que fetch esté disponible — Node, Workers, el navegador o un sitio Astro.

Instalación

El subpath discovery no tiene dependencias de autenticación u OAuth. Instala el cliente y fíjalo a una versión exacta:

npm install @emdash-cms/[email protected]

Listar y resolver paquetes

La siguiente página Astro lista todos los plugins en un registro:

---
import { DiscoveryClient } from "@emdash-cms/registry-client/discovery";

const discovery = new DiscoveryClient({
  aggregatorUrl: "https://registry.emdashcms.com",
});

const { packages } = await discovery.searchPackages({ q: "", limit: 50 });
---

<ul>
  {
    packages.map((pkg) => (
      <li>
        <a href={`/plugins/${pkg.did}/${pkg.slug}`}>
          {pkg.profile?.name ?? pkg.slug}
        </a>
        {pkg.latestVersion && <span>v{pkg.latestVersion}</span>}
        <p>{pkg.profile?.description}</p>
      </li>
    ))
  }
</ul>

El enlace usa pkg.did, que siempre está presente. El handle del publicador es de mejor esfuerzo y puede estar ausente, así que no construyas URLs a partir de él.

Una página de detalle del paquete obtiene un plugin por su DID y slug, luego obtiene el último release:

import { DiscoveryClient } from "@emdash-cms/registry-client/discovery";

const discovery = new DiscoveryClient({
  aggregatorUrl: "https://registry.emdashcms.com",
});

export async function getPlugin(did: string, slug: string) {
  const pkg = await discovery.getPackage({ did, slug });
  const latest = await discovery.getLatestRelease({
    did: pkg.did,
    package: pkg.slug,
  });
  return { pkg, latest };
}

Métodos de descubrimiento

El cliente expone un método por consulta al agregador:

  • searchPackages({ q, capability?, limit?, cursor? }) — búsqueda de texto libre, opcionalmente filtrada a paquetes que declaran una categoría de acceso dada. Devuelve { packages, cursor? }.
  • resolvePackage({ handle, slug }) — resolver un paquete a partir de un handle y slug.
  • getPackage({ did, slug }) — obtener un paquete por su DID y slug.
  • listReleases({ did, package, limit?, cursor? }) — todos los releases de un paquete, versión más nueva primero.
  • getLatestRelease({ did, package }) — la versión de release más alta no retirada.

Manejo de registros no confiables

El agregador es un índice no confiable que retransmite registros que no escribió, así que el cliente valida cada uno en la frontera. Dos reglas derivan de eso:

  • Los campos profile y release pueden ser null. Cuando un registro retransmitido falla la validación, el cliente lo presenta como null en lugar de fallar toda la llamada, así un registro malformado no deja en blanco una página de búsqueda. Siempre verifica null antes de leer pkg.profile?.name o latest.release?.artifacts.package.
  • Valida los esquemas de URL tú mismo antes de renderizar. La validación verifica estructura, no seguridad de URL — un campo uri puede llevar un esquema javascript:. Aplica tu propia lista de permitidos http/https antes de poner cualquier URL proporcionada por el registro en un href o src.

Una respuesta no-2xx lanza ClientResponseError (re-exportado del paquete), con .error, .description, .status y .headers.

Filtrado por compatibilidad de host

Un release puede declarar requisitos de entorno (un rango de versión de EmDash o Astro) en su bloque requires. El subpath @emdash-cms/registry-client/env los evalúa, para que un directorio pueda marcar releases que no se ejecutarán en un host dado:

import { checkEnvCompatibility, hostEnvFromVersions } from "@emdash-cms/registry-client/env";
import type { ValidatedReleaseView } from "@emdash-cms/registry-client/discovery";

const host = hostEnvFromVersions("0.17.0", "5.6.0");

// Pasa un resultado de getLatestRelease(). El array devuelto está vacío cuando
// el release se ejecuta en este host.
export function envMismatches(latest: ValidatedReleaseView) {
  return checkEnvCompatibility(latest.release?.requires, host);
}

Qué leer a continuación