OpenCoreDev ha rilasciato Domain SDK, una libreria TypeScript di ultima generazione, progettata per normalizzare il workflow relativo ai domini custom negli sviluppi SaaS. Disponibile come client open source, il package opera su piattaforme come Vercel, Cloudflare, Railway, Render e Netlify. Versione 0.2.0 è già pubblicata su npm, un aggiornamento importante rispetto alla prima versione.

Che cos'è Domain SDK?

Domain SDK si focalizza su host custom e DNS records, offrendo un'API unificata che non necessita di registrare domini, né memorizzare dati tenants. L'autorizzazione e lo stato restano sempre sostenuti dall'applicazione, e i dettagli veri e propri vengono preservati nel provider.

La libreria non è compatibile con browser; è esclusivamente di tipo server-side, e richiede engine Node.js >=20 e supporta anche l’uso con l’estensione Bun. Si presenta in formato ESM-only, senza supporto commonJS, e possiede una sola dipendenza esterna, tldts.

API e funzionalità principali

La sua interfaccia di base non è vasta. La funzione createDomainClient() genera un client senza stato con sette metodi principali: add, get, refresh, list, verify, remove, e waitUntilActive. Ogni metodo accetta il tipo AbortSignal. I metodi add e remove sono idempotenti, rendendo le ripetizioni dell’esecuzione sicure per il sistema.

Struttura e adattatori

Ogni adattatore per dominio è un punto d'ingresso separato: ./vercel, ./cloudflare, ./railway, ./render, ./netlify e ./testing. Cambiare piattaforma richiede quindi solo un cambiamento di import, senza modifiche di logica.

Stati e errori del dominio

L'SDK modella gli stati con un unione dettagliata e non con un semplice booleano. DomainStatus include otto stati possibili: pending, pendingdns, pendingverification, pending_certificate, active, misconfigured, failed, unknown.

Ogni Domain contiene un campo verification, un campo certificate e un elenco issues per registrare errori eventuali. Ogni problema specifica codice, descrizione, record coinvolto, e un flag indicante se il problema è ripristinabile.

Struttura dei record DNS

I record DNS sono ben tipizzati. Il tipo DnsRecord include type, name, e value, e aggiunge informazioni come ttl, purpose, required, status, e description.

I record DNS sono suddivisi a seconda della finalità: routing, ownership, certificate, e altri. In particolare, per Vercel, si distinguono tre tipi di record:

CNAME per routing
TXT per verifiche di proprietà
TXT per certificati SSL (acme challenge)

Compatibilità tra piattaforme

Sebbene Domain SDK normalizzi il ciclo di vita del dominio, alcune limitazioni sono legate al provider. Si può riferire una tabella di compatibilità per comprendere meglio le differenze, inclusa la non gestione di apex domini per Cloudflare o wildcard per Render.

Uso della libreria

Ecco uno snippet che si avvia correttamente con Domain SDK 0.2.0:

import { createDomainClient } from "@opencoredev/domain-sdk";
import { vercel } from "@opencoredev/domain-sdk/vercel";

export const domains = createDomainClient({
provider: vercel({
token: process.env.VERCEL_TOKEN!,
projectId: process.env.VERCELPROJECTID!,
}),
});

const domain = await domains.add("app.customer.com");
const required = domain.records.filter((item) => item.required);

const active = await domains.waitUntilActive(domain.hostname, {
timeoutMs: 300_000,
intervalMs: 5_000,
onStatus: (current) => console.log(current.status),
});

console.log(active.certificate.status, active.verification.status);

Esegue polling sequenziale per verificare lo stato del dominio. Le opzioni di polling predefinite includono timeout a 300000 ms ed un intervallo a 5000 ms. L'API espone la funzionalità di onStatus per rilevare gli status in tempo reale. Ogni provider può restituire il periodo di tempo ideale per ritentare tramite il campo retryAfter.

Supporto testing e agenti

Per i test di integrazione, esiste un adattatore in-memory, che esegue solo operazioni fittizie. Il modulo ./testing offre opzioni avanzate come transition(), aggiunta di latencyMs, log su chiamate effettive per ogni operazione, e supporto all'erogazione manuale o automatica di fallimenti.

Un'altro punto forte è l'integrazione con agenti di sviluppo. Grazie all'abilitazione di skill specifiche tramite npx skills add opencoredev/domain-sdk --skill domain-sdk, il modulo si trova compatibile con Codex, Claude Code, Cursor, e altri agenti compatibili.

Casi d’uso

Il modulo si presta bene per:

SaaS multisitenza su Vercel: permette di aggiungere app.customer.com e visualizzare record DNS necessari in tempo reale.
Cloudflare SaaS su larga scala: gestisce domini personalizzati all’interno di una zona unica, con scoping esplicito.
Creazione di sottodomini: la funzione createSubdomainClient consente di mappare sottodomini con etichette bloccandone alcune come www, api, admin.
Migration tra provider: semplice cambio di import adattatore mantiene il workflow e la logica di controllo attivo senza interventi sull'API.

Conclusione

Domain SDK si presenta come una soluzione estremamente utile per sviluppatori SaaS. Unifica l'esperienza di lavoro con domini custom su cinque piattaforme con una sola API TypeScript, rendendo l'implementazione e la gestione molto più efficiente. Attualmente su versione 0.2.0, la libreria presenta un'API giovane e ha bisogno di configurazione moduleResolution: "bundler" per funzionare corrett