Los dominios personalizados son una característica estándar de SaaS. Sin embargo, cada plataforma de hosting les expone una API diferente. OpenCoreDev ha publicado Domain SDK, un cliente TypeScript que normaliza ese trabajo. La versión 0.2.0 llegó a npm un día después del primer lanzamiento.
¿Qué es el SDK de dominio?
Domain SDK cubre Vercel, Cloudflare para SaaS, Railway, Render y Netlify. Agrega un nombre de host, muestra los registros DNS exactos y luego realiza un seguimiento del estado del proveedor hasta que esté listo.
No registra dominios, aloja DNS, implementa aplicaciones, tráfico de proxy ni almacena datos de inquilinos. Su solicitud mantiene la autorización y el estado del inquilino. El proveedor sigue siendo la fuente de la verdad.
El paquete es sólo del lado del servidor, por lo que las credenciales nunca llegan al código del navegador. Engines.node es >=20 y Bun es compatible. Es solo ESM y incluye una dependencia de tiempo de ejecución, tldts.
La superficie del cliente
Dentro de ese alcance, la API es pequeña. createDomainClient() devuelve un cliente sin estado con siete miembros: agregar, obtener, actualizar, enumerar, verificar, eliminar y esperar hasta que se active. Cada método acepta una AbortSignal. Agregar y quitar son idempotentes, por lo que los reintentos son seguros.
Cada adaptador es un punto de entrada independiente: ./vercel, ./cloudflare, ./railway, ./render, ./netlify y ./testing. Cambiar de plataforma significa cambiar la importación, no el flujo de trabajo.
El estado es una unión, no un booleano.
Debido a que DNS, propiedad y TLS finalizan en momentos diferentes, el SDK los modela por separado. DomainStatus lleva ocho valores:
pendiente, pendiente_dns, pendiente_verificación, pendiente_certificado, activo, mal configurado, fallido, desconocido.
Un dominio también contiene verificación (pendiente | verificado | fallido | desconocido), certificado (pendiente | activo | venciendo | fallido | desconocido) y una matriz de problemas. Cada problema tiene un código, un mensaje, un registro opcional y una marca reintentable.
Los registros se escriben de la misma manera. DnsRecord tiene tipo, nombre, valor, ttl opcional, propósito, requerido, estado y descripción opcional. El propósito es enrutamiento, propiedad, certificado u otro. el estado es pendiente, válido, no válido o desconocido.
En consecuencia, un nombre de host de Vercel muestra tres registros separados:
Compatibilidad de proveedores
Si bien el ciclo de vida está normalizado, los límites de la plataforma no lo son:
Cloudflare para SaaS requiere un destino CNAME, por lo que el adaptador no afirma ser compatible con Apex. El renderizado por sí solo acepta nombres de host comodín. Ningún adaptador edita el DNS del cliente automáticamente.
En lugar de codificar esos límites, lea client.capabilities en tiempo de ejecución. Expone lista, verificación explícita, certificados administrados, dominios apex y dominios comodín.
Trabajando con el cliente
El siguiente fragmento de código verifica y se ejecuta en comparación con 0.2.0:
El sondeo es secuencial. El valor predeterminado es un tiempo de espera de 300.000 ms y un intervalo de 5.000 ms. Se rechazan los intervalos inferiores a 250 ms y cada estado se informa a través de onStatus. Cuando un proveedor devuelve retryAfter, el cliente espera al menos ese tiempo antes de volver a intentarlo.
Pruebas y soporte para agentes
Para CI, un adaptador en memoria nunca llama a un proveedor real:
También admite transiciones (), latencia M inyectada, fallas por operación y un registro de llamadas. createMockDomain, createMockDnsRecord y createFailingProvider se encuentran junto a él.
Por separado, una habilidad de agente instala el flujo de trabajo en Codex, Claude Code, Cursor y otros agentes compatibles:
Casos de uso
SaaS multiinquilino en Vercel: una aplicación de mapas para clientes.customer.com. Su página de configuración muestra los registros CNAME y TXT requeridos con estado activo. Cloudflare para SaaS a escala: los nombres de host personalizados viven dentro de una zona. El adaptador mantiene explícito ese alcance. Subdominios de inquilinos de su propiedad: createSubdomainClient asigna etiquetas bajo un dominio base. reserveLabels bloquea www, api y admin. Migración de proveedores: intercambie la importación del adaptador y mantenga las mismas llamadas del ciclo de vida.