doomain 0.1.0

package/dist/lib/providers/cloudflare/index.js

@@ -0,0 +1,219 @@
+import { normalizeDomain } from '../../validate.js';
+import { createProviderHttpClient } from '../core/http.js';
+import { assertNoConflicts, planDnsChanges } from '../core/planner.js';
+import { ProviderError } from '../core/errors.js';
+const CLOUDFLARE_API_URL = 'https://api.cloudflare.com/client/v4';
+const capabilities = {
+    defaultTtl: 3600,
+    maxTtl: 86_400,
+    minTtl: 60,
+    recordTypes: ['A', 'AAAA', 'CNAME', 'MX', 'TXT'],
+    supportsApexCname: false,
+    supportsBulkWrites: false,
+    supportsPagination: true,
+    supportsProxying: true,
+    supportsRecordIds: true,
+};
+function cloudflareErrorMessage(response) {
+    return response.errors?.find((error) => error.message)?.message ?? 'Cloudflare API error.';
+}
+function isSupportedRecordType(type) {
+    return capabilities.recordTypes.includes(type);
+}
+function cleanDnsRecordName(name) {
+    return name.trim().toLowerCase().replace(/\.$/, '');
+}
+function relativeRecordName(name, zoneName) {
+    const normalized = cleanDnsRecordName(name);
+    const normalizedZone = normalizeDomain(zoneName);
+    if (normalized === normalizedZone)
+        return '@';
+    if (normalized.endsWith(`.${normalizedZone}`))
+        return normalized.slice(0, -(normalizedZone.length + 1));
+    return normalized;
+}
+function absoluteRecordName(record, zone) {
+    return record.name === '@' ? zone.name : `${record.name}.${zone.name}`;
+}
+function toDnsRecord(record, zone) {
+    if (!record.id || !record.name || !record.type || !record.content || !isSupportedRecordType(record.type))
+        return null;
+    const dnsRecord = {
+        id: record.id,
+        metadata: { cloudflare: record },
+        name: relativeRecordName(record.name, zone.name),
+        type: record.type,
+        value: record.content,
+    };
+    if (record.priority !== undefined)
+        dnsRecord.priority = record.priority;
+    if (record.proxied !== undefined)
+        dnsRecord.proxied = record.proxied;
+    if (record.ttl !== undefined)
+        dnsRecord.ttl = record.ttl;
+    return dnsRecord;
+}
+function toCloudflareRecord(record, zone) {
+    return {
+        content: record.value,
+        name: absoluteRecordName(record, zone),
+        ttl: record.ttl ?? capabilities.defaultTtl,
+        type: record.type,
+        ...(record.priority === undefined ? {} : { priority: record.priority }),
+        ...(record.proxied === undefined || !['A', 'AAAA', 'CNAME'].includes(record.type) ? {} : { proxied: record.proxied }),
+    };
+}
+function toZone(zone) {
+    if (!zone.id || !zone.name)
+        return null;
+    try {
+        const name = normalizeDomain(zone.name);
+        return { id: zone.id, metadata: { cloudflare: zone }, name };
+    }
+    catch {
+        return null;
+    }
+}
+export class CloudflareProvider {
+    capabilities = capabilities;
+    id = 'cloudflare';
+    name = 'Cloudflare';
+    accountId;
+    http;
+    constructor(context) {
+        this.accountId = context.credentials.accountId;
+        this.http = createProviderHttpClient({
+            baseUrl: CLOUDFLARE_API_URL,
+            errorMessages: {
+                401: 'Cloudflare rejected the API token.',
+                403: 'Cloudflare API token is missing required permissions. Enable Zone:Read and DNS:Edit for the account.',
+                429: 'Cloudflare rate limit exceeded. Try again later.',
+            },
+            headers: { Authorization: `Bearer ${context.credentials.apiToken}` },
+            providerId: this.id,
+            signal: context.signal,
+        });
+    }
+    async verifyCredentials() {
+        await this.listZones();
+        return { ok: true };
+    }
+    async listZones() {
+        const zones = [];
+        for (let page = 1; page <= 100; page += 1) {
+            const response = await this.request('/zones', {
+                query: { 'account.id': this.accountId, direction: 'asc', order: 'name', page, 'per_page': 50 },
+            });
+            for (const zone of response.result ?? []) {
+                const dnsZone = toZone(zone);
+                if (dnsZone)
+                    zones.push(dnsZone);
+            }
+            const totalPages = response.result_info?.total_pages ?? page;
+            if (page >= totalPages || (response.result ?? []).length === 0)
+                break;
+        }
+        return zones;
+    }
+    async getZone(domain) {
+        const normalized = normalizeDomain(domain);
+        const zones = await this.listZones();
+        return zones.find((zone) => zone.name === normalized) ?? null;
+    }
+    async listRecords(zone) {
+        const records = [];
+        for (let page = 1; page <= 100; page += 1) {
+            const response = await this.request(`/zones/${zone.id}/dns_records`, {
+                query: { page, 'per_page': 100 },
+            });
+            for (const record of response.result ?? []) {
+                const dnsRecord = toDnsRecord(record, zone);
+                if (dnsRecord)
+                    records.push(dnsRecord);
+            }
+            const totalPages = response.result_info?.total_pages ?? page;
+            if (page >= totalPages || (response.result ?? []).length === 0)
+                break;
+        }
+        return records;
+    }
+    async planChanges(zone, desired, opts = {}) {
+        return planDnsChanges({ desired, existing: await this.listRecords(zone), force: opts.force, providerId: this.id, zone });
+    }
+    async applyChanges(zone, plan) {
+        assertNoConflicts(this.id, plan);
+        const applied = [];
+        const skipped = [];
+        for (const change of plan.changes) {
+            if (change.action === 'skip') {
+                skipped.push(change.record);
+                continue;
+            }
+            if (change.action === 'delete')
+                await this.deleteRecord(zone, change.existing);
+            else if (change.action === 'update')
+                await this.updateRecord(zone, change.existing, change.record);
+            else
+                await this.createRecord(zone, change.record);
+            applied.push(change);
+        }
+        return { applied, skipped };
+    }
+    async upsertRecord(zone, record) {
+        const existing = (await this.listRecords(zone)).find((item) => item.name === record.name && item.type === record.type);
+        if (existing)
+            return this.updateRecord(zone, existing, record);
+        return this.createRecord(zone, record);
+    }
+    async deleteRecord(zone, record) {
+        if (!record.id)
+            throw new ProviderError(this.id, 'PROVIDER_API_ERROR', 'Cloudflare DNS record id is required to delete a record.');
+        await this.request(`/zones/${zone.id}/dns_records/${record.id}`, { method: 'DELETE' });
+    }
+    async createRecord(zone, record) {
+        const response = await this.request(`/zones/${zone.id}/dns_records`, {
+            body: toCloudflareRecord(record, zone),
+            method: 'POST',
+        });
+        const created = response.result ? toDnsRecord(response.result, zone) : null;
+        return created ?? { ...record, ttl: record.ttl ?? capabilities.defaultTtl };
+    }
+    async updateRecord(zone, existing, record) {
+        if (!existing.id)
+            throw new ProviderError(this.id, 'PROVIDER_API_ERROR', 'Cloudflare DNS record id is required to update a record.');
+        const response = await this.request(`/zones/${zone.id}/dns_records/${existing.id}`, {
+            body: toCloudflareRecord(record, zone),
+            method: 'PUT',
+        });
+        const updated = response.result ? toDnsRecord(response.result, zone) : null;
+        return updated ?? { ...record, id: existing.id, ttl: record.ttl ?? capabilities.defaultTtl };
+    }
+    async request(path, init = {}) {
+        const response = await this.http.request(path, init);
+        if (response.success === false) {
+            throw new ProviderError(this.id, 'PROVIDER_API_ERROR', cloudflareErrorMessage(response), response.errors);
+        }
+        return response;
+    }
+}
+export const cloudflareProviderDefinition = {
+    capabilities,
+    credentials: [
+        { env: 'CLOUDFLARE_API_TOKEN', key: 'apiToken', label: 'API token', required: true, secret: true },
+        { env: 'CLOUDFLARE_ACCOUNT_ID', key: 'accountId', label: 'Account ID', required: true },
+    ],
+    displayName: 'Cloudflare',
+    docsUrl: 'https://developers.cloudflare.com/api/',
+    id: 'cloudflare',
+    name: 'Cloudflare',
+    setup: {
+        notes: [
+            'Create a Cloudflare API token with Zone:Read and DNS:Edit permissions for the account.',
+            'Use the Cloudflare account ID that owns the DNS zones you want Doomain to manage.',
+            'Doomain creates Vercel records as DNS-only records, not proxied records.',
+        ],
+    },
+    create(context) {
+        return new CloudflareProvider(context);
+    },
+};

package/dist/lib/providers/core/config.d.ts

@@ -0,0 +1,5 @@
+import { type DoomainConfig } from '../../config.js';
+import type { CredentialDefinition, DnsProviderDefinition, ProviderContext } from './types.js';
+export declare function getProviderCredentials(config: DoomainConfig, providerId: string): Record<string, string>;
+export declare function getProviderCredential(config: DoomainConfig, providerId: string, credential: CredentialDefinition): string | undefined;
+export declare function createProviderContext(definition: DnsProviderDefinition): Promise<ProviderContext>;

package/dist/lib/providers/core/config.js

@@ -0,0 +1,33 @@
+import { loadConfig } from '../../config.js';
+import { DoomainError } from '../../errors.js';
+function legacyCredential(config, providerId, key) {
+    if (providerId !== 'spaceship')
+        return undefined;
+    const legacy = config.providers?.spaceship;
+    if (!legacy || typeof legacy !== 'object')
+        return undefined;
+    return legacy[key];
+}
+export function getProviderCredentials(config, providerId) {
+    const providerConfig = config.providers?.[providerId];
+    const credentials = providerConfig && typeof providerConfig === 'object' && 'credentials' in providerConfig
+        ? (providerConfig.credentials ?? {})
+        : {};
+    return { ...credentials };
+}
+export function getProviderCredential(config, providerId, credential) {
+    return process.env[credential.env] || getProviderCredentials(config, providerId)[credential.key] || legacyCredential(config, providerId, credential.key);
+}
+export async function createProviderContext(definition) {
+    const config = await loadConfig();
+    const credentials = {};
+    for (const credential of definition.credentials) {
+        const value = getProviderCredential(config, definition.id, credential);
+        if (value)
+            credentials[credential.key] = value;
+        else if (credential.required !== false) {
+            throw new DoomainError('MISSING_CREDENTIALS', `Missing ${definition.displayName} ${credential.label}. Run \`doomain providers connect ${definition.id}\` or set ${credential.env}.`);
+        }
+    }
+    return { credentials, debug: process.env.DOOMAIN_DEBUG === '1' };
+}

package/dist/lib/providers/core/errors.d.ts

@@ -0,0 +1,6 @@
+import { DoomainError, type DoomainErrorCode } from '../../errors.js';
+export declare class ProviderError extends DoomainError {
+    readonly providerId: string;
+    constructor(providerId: string, code: DoomainErrorCode, message: string, details?: unknown);
+}
+export declare function providerCodeFromStatus(status: number): DoomainErrorCode;

package/dist/lib/providers/core/errors.js

@@ -0,0 +1,18 @@
+import { DoomainError } from '../../errors.js';
+export class ProviderError extends DoomainError {
+    providerId;
+    constructor(providerId, code, message, details) {
+        super(code, message, details);
+        this.name = 'ProviderError';
+        this.providerId = providerId;
+    }
+}
+export function providerCodeFromStatus(status) {
+    if (status === 401)
+        return 'PROVIDER_AUTH_FAILED';
+    if (status === 403)
+        return 'PROVIDER_PERMISSION_DENIED';
+    if (status === 429)
+        return 'PROVIDER_RATE_LIMITED';
+    return 'PROVIDER_API_ERROR';
+}

package/dist/lib/providers/core/http.d.ts

@@ -0,0 +1,17 @@
+export interface ProviderHttpClientOptions {
+    baseUrl: string;
+    errorMessages?: Partial<Record<number, string>>;
+    headers?: Record<string, string>;
+    providerId: string;
+    signal?: AbortSignal;
+}
+export interface ProviderRequestOptions extends Omit<RequestInit, 'body'> {
+    body?: unknown;
+    query?: Record<string, number | string | undefined>;
+}
+export declare class ProviderHttpClient {
+    private readonly opts;
+    constructor(opts: ProviderHttpClientOptions);
+    request<T>(path: string, init?: ProviderRequestOptions): Promise<T>;
+}
+export declare function createProviderHttpClient(opts: ProviderHttpClientOptions): ProviderHttpClient;

package/dist/lib/providers/core/http.js

@@ -0,0 +1,43 @@
+import { ProviderError, providerCodeFromStatus } from './errors.js';
+function appendQuery(path, query) {
+    if (!query)
+        return path;
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined)
+            params.set(key, String(value));
+    }
+    if (params.size === 0)
+        return path;
+    const separator = path.includes('?') ? '&' : '?';
+    return `${path}${separator}${params.toString()}`;
+}
+export class ProviderHttpClient {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async request(path, init = {}) {
+        const { body, headers, query, ...rest } = init;
+        const response = await fetch(`${this.opts.baseUrl}${appendQuery(path, query)}`, {
+            ...rest,
+            body: body === undefined ? undefined : JSON.stringify(body),
+            headers: {
+                'Content-Type': 'application/json',
+                ...this.opts.headers,
+                ...headers,
+            },
+            signal: init.signal ?? this.opts.signal,
+        });
+        if (!response.ok) {
+            const details = await response.json().catch(() => undefined);
+            throw new ProviderError(this.opts.providerId, providerCodeFromStatus(response.status), this.opts.errorMessages?.[response.status] ?? `${this.opts.providerId} API error (${response.status}).`, details);
+        }
+        if (response.status === 204)
+            return undefined;
+        return (await response.json().catch(() => undefined));
+    }
+}
+export function createProviderHttpClient(opts) {
+    return new ProviderHttpClient(opts);
+}

package/dist/lib/providers/core/pagination.d.ts

@@ -0,0 +1,12 @@
+export interface SkipPaginationInput<T> {
+    fetchPage(input: {
+        skip: number;
+        take: number;
+    }): Promise<{
+        items: T[];
+        total: number;
+    }>;
+    maxPages?: number;
+    take: number;
+}
+export declare function paginateBySkip<T>(input: SkipPaginationInput<T>): Promise<T[]>;

package/dist/lib/providers/core/pagination.js

@@ -0,0 +1,15 @@
+export async function paginateBySkip(input) {
+    const items = [];
+    const maxPages = input.maxPages ?? 100;
+    let skip = 0;
+    let total = Number.POSITIVE_INFINITY;
+    for (let page = 0; skip < total && page < maxPages; page += 1) {
+        const result = await input.fetchPage({ skip, take: input.take });
+        items.push(...result.items);
+        total = result.total;
+        if (result.items.length === 0)
+            break;
+        skip += result.items.length;
+    }
+    return items;
+}

package/dist/lib/providers/core/planner.d.ts

@@ -0,0 +1,19 @@
+import type { DnsChange, DnsChangePlan, DnsRecord, DnsRecordInput, DnsZone, PlanOptions } from './types.js';
+export declare function planDnsChanges(input: {
+    desired: DnsRecordInput[];
+    existing: DnsRecord[];
+    force?: boolean;
+    providerId: string;
+    zone: DnsZone;
+}): DnsChangePlan;
+export declare function assertNoConflicts(providerId: string, plan: DnsChangePlan): void;
+export declare function applyDnsChanges(input: {
+    deleteRecord(record: DnsRecord): Promise<void>;
+    plan: DnsChangePlan;
+    providerId: string;
+    upsertRecord(record: DnsRecordInput): Promise<DnsRecord>;
+    opts?: PlanOptions;
+}): Promise<{
+    applied: DnsChange[];
+    skipped: DnsRecordInput[];
+}>;

package/dist/lib/providers/core/planner.js

@@ -0,0 +1,79 @@
+import { ProviderError } from './errors.js';
+function cleanDnsValue(value) {
+    return value.toLowerCase().replace(/\.$/, '');
+}
+function sameRecord(a, b) {
+    if (b.proxied !== undefined && a.proxied !== b.proxied)
+        return false;
+    return a.type === b.type && a.name === b.name && cleanDnsValue(a.value) === cleanDnsValue(b.value);
+}
+function sameDnsValue(a, b) {
+    return a.type === b.type && a.name === b.name && cleanDnsValue(a.value) === cleanDnsValue(b.value);
+}
+function sameSlot(a, b) {
+    return a.type === b.type && a.name === b.name;
+}
+function cnameSlotConflict(a, b) {
+    return a.name === b.name && (a.type === 'CNAME' || b.type === 'CNAME');
+}
+export function planDnsChanges(input) {
+    const changes = [];
+    const conflicts = [];
+    for (const record of input.desired) {
+        const exact = input.existing.find((existing) => sameRecord(existing, record));
+        if (exact) {
+            changes.push({ action: 'skip', existing: exact, reason: 'already_exists', record });
+            continue;
+        }
+        const sameValue = input.existing.find((existing) => sameDnsValue(existing, record));
+        if (sameValue && record.proxied !== undefined && sameValue.proxied !== record.proxied) {
+            changes.push({ action: 'update', existing: sameValue, record });
+            continue;
+        }
+        if (record.type === 'TXT') {
+            changes.push({ action: 'create', record });
+            continue;
+        }
+        const sameTyped = input.existing.find((existing) => sameSlot(existing, record));
+        if (sameTyped) {
+            if (input.force)
+                changes.push({ action: 'update', existing: sameTyped, record });
+            else
+                conflicts.push({ existing: sameTyped, reason: 'same_type_record_exists', record });
+            continue;
+        }
+        const cnameConflict = input.existing.find((existing) => cnameSlotConflict(existing, record));
+        if (cnameConflict) {
+            if (input.force) {
+                changes.push({ action: 'delete', existing: cnameConflict, reason: 'cname_slot_conflict' }, { action: 'create', record });
+            }
+            else {
+                conflicts.push({ existing: cnameConflict, reason: 'cname_slot_conflict', record });
+            }
+            continue;
+        }
+        changes.push({ action: 'create', record });
+    }
+    return { changes, conflicts, desired: input.desired, existing: input.existing, zone: input.zone };
+}
+export function assertNoConflicts(providerId, plan) {
+    if (plan.conflicts.length === 0)
+        return;
+    throw new ProviderError(providerId, 'PROVIDER_RECORD_CONFLICT', 'DNS record conflicts must be resolved before applying changes.', {
+        conflicts: plan.conflicts,
+    });
+}
+export async function applyDnsChanges(input) {
+    assertNoConflicts(input.providerId, input.plan);
+    const applied = [];
+    const skipped = [];
+    for (const change of input.plan.changes) {
+        if (change.action === 'skip') {
+            skipped.push(change.record);
+            continue;
+        }
+        await (change.action === 'delete' ? input.deleteRecord(change.existing) : input.upsertRecord(change.record));
+        applied.push(change);
+    }
+    return { applied, skipped };
+}

package/dist/lib/providers/core/types.d.ts

@@ -0,0 +1,123 @@
+export type DnsRecordType = 'A' | 'AAAA' | 'CNAME' | 'MX' | 'TXT';
+export interface CredentialDefinition {
+    description?: string;
+    env: string;
+    hint?: string;
+    key: string;
+    label: string;
+    placeholder?: string;
+    required?: boolean;
+    secret?: boolean;
+}
+export interface ProviderSetupGuide {
+    notes?: string[];
+}
+export interface ProviderCapabilities {
+    defaultTtl: number;
+    maxTtl?: number;
+    minTtl?: number;
+    recordTypes: DnsRecordType[];
+    supportsApexCname: boolean;
+    supportsBulkWrites: boolean;
+    supportsPagination: boolean;
+    supportsProxying: boolean;
+    supportsRecordIds: boolean;
+}
+export interface DnsZone {
+    id: string;
+    name: string;
+    metadata?: Record<string, unknown>;
+}
+export interface DnsRecord {
+    id?: string;
+    metadata?: Record<string, unknown>;
+    name: string;
+    priority?: number;
+    proxied?: boolean;
+    ttl?: number;
+    type: DnsRecordType;
+    value: string;
+}
+export interface DnsRecordInput {
+    metadata?: Record<string, unknown>;
+    name: string;
+    priority?: number;
+    proxied?: boolean;
+    ttl?: number;
+    type: DnsRecordType;
+    value: string;
+}
+export type DnsChange = {
+    action: 'create';
+    record: DnsRecordInput;
+} | {
+    action: 'delete';
+    existing: DnsRecord;
+    reason?: string;
+} | {
+    action: 'skip';
+    existing: DnsRecord;
+    reason: string;
+    record: DnsRecordInput;
+} | {
+    action: 'update';
+    existing: DnsRecord;
+    record: DnsRecordInput;
+};
+export interface DnsConflict {
+    existing: DnsRecord;
+    reason: string;
+    record: DnsRecordInput;
+}
+export interface DnsChangePlan {
+    changes: DnsChange[];
+    conflicts: DnsConflict[];
+    desired: DnsRecordInput[];
+    existing: DnsRecord[];
+    zone: DnsZone;
+}
+export interface DnsChangeResult {
+    applied: DnsChange[];
+    skipped: DnsRecordInput[];
+}
+export interface ListZonesInput {
+    search?: string;
+}
+export interface ProviderHealth {
+    ok: boolean;
+    message?: string;
+}
+export interface PlanOptions {
+    force?: boolean;
+}
+export interface ApplyOptions {
+    force?: boolean;
+}
+export interface ProviderContext {
+    credentials: Record<string, string>;
+    debug?: boolean;
+    signal?: AbortSignal;
+}
+export interface DnsProvider {
+    capabilities: ProviderCapabilities;
+    id: string;
+    name: string;
+    applyChanges(zone: DnsZone, plan: DnsChangePlan, opts?: ApplyOptions): Promise<DnsChangeResult>;
+    deleteRecord(zone: DnsZone, record: DnsRecord): Promise<void>;
+    getZone(domain: string): Promise<DnsZone | null>;
+    listRecords(zone: DnsZone): Promise<DnsRecord[]>;
+    listZones(input?: ListZonesInput): Promise<DnsZone[]>;
+    planChanges(zone: DnsZone, desired: DnsRecordInput[], opts?: PlanOptions): Promise<DnsChangePlan>;
+    upsertRecord(zone: DnsZone, record: DnsRecordInput): Promise<DnsRecord>;
+    verifyCredentials(): Promise<ProviderHealth>;
+}
+export interface DnsProviderDefinition {
+    capabilities: ProviderCapabilities;
+    credentials: CredentialDefinition[];
+    displayName: string;
+    docsUrl?: string;
+    id: string;
+    name: string;
+    setup?: ProviderSetupGuide;
+    create(context: ProviderContext): DnsProvider;
+}

package/dist/lib/providers/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/providers/namecheap/index.d.ts

@@ -0,0 +1,28 @@
+import type { DnsChange, DnsChangePlan, DnsProvider, DnsProviderDefinition, DnsRecord, DnsRecordInput, DnsZone, ProviderCapabilities, ProviderContext, ProviderHealth } from '../types.js';
+export declare class NamecheapProvider implements DnsProvider {
+    readonly capabilities: ProviderCapabilities;
+    readonly id = "namecheap";
+    readonly name = "Namecheap";
+    private readonly apiKey;
+    private readonly apiUser;
+    private readonly baseUrl;
+    private readonly clientIp;
+    private readonly username;
+    constructor(context: ProviderContext);
+    verifyCredentials(): Promise<ProviderHealth>;
+    listZones(): Promise<DnsZone[]>;
+    getZone(domain: string): Promise<DnsZone | null>;
+    listRecords(zone: DnsZone): Promise<DnsRecord[]>;
+    planChanges(zone: DnsZone, desired: DnsRecordInput[], opts?: {
+        force?: boolean;
+    }): Promise<DnsChangePlan>;
+    applyChanges(zone: DnsZone, plan: DnsChangePlan): Promise<{
+        applied: DnsChange[];
+        skipped: DnsRecordInput[];
+    }>;
+    upsertRecord(zone: DnsZone, record: DnsRecordInput): Promise<DnsRecord>;
+    deleteRecord(zone: DnsZone, record: DnsRecord): Promise<void>;
+    private setHosts;
+    private request;
+}
+export declare const namecheapProviderDefinition: DnsProviderDefinition;