BREAKING CHANGE(core): Introduce RecordManager and ConvenientDnsProvider; rename list/get methods for consistent API and deprecate convenience namespace

This commit is contained in:
2025-11-18 20:39:08 +00:00
parent 39d53da4e6
commit 5ce1520e2b
12 changed files with 617 additions and 79 deletions

View File

@@ -3,6 +3,6 @@
*/
export const commitinfo = {
name: '@apiclient.xyz/cloudflare',
version: '6.4.3',
version: '7.0.0',
description: 'A TypeScript client for managing Cloudflare accounts, zones, DNS records, and workers with ease.'
}

View File

@@ -5,6 +5,8 @@ import * as interfaces from './interfaces/index.js';
// interfaces
import { WorkerManager } from './cloudflare.classes.workermanager.js';
import { ZoneManager } from './cloudflare.classes.zonemanager.js';
import { RecordManager } from './cloudflare.classes.recordmanager.js';
import { ConvenientDnsProvider } from './cloudflare.classes.convenientdnsprovider.js';
export class CloudflareAccount implements plugins.tsclass.network.IConvenientDnsProvider {
private authToken: string;
@@ -12,6 +14,7 @@ export class CloudflareAccount implements plugins.tsclass.network.IConvenientDns
public workerManager = new WorkerManager(this);
public zoneManager = new ZoneManager(this);
public recordManager = new RecordManager(this);
public apiAccount: plugins.cloudflare.Cloudflare;
@@ -133,6 +136,16 @@ export class CloudflareAccount implements plugins.tsclass.network.IConvenientDns
}
}
/**
* Returns a ConvenientDnsProvider instance that implements IConvenientDnsProvider
* This allows third-party modules to use the standard DNS provider interface
* while internally delegating to the clean RecordManager and ZoneManager structure
* @returns ConvenientDnsProvider instance
*/
public getConvenientDnsProvider(): ConvenientDnsProvider {
return new ConvenientDnsProvider(this);
}
public convenience = {
/**
* Lists all accounts accessible with the current API token
@@ -157,6 +170,7 @@ export class CloudflareAccount implements plugins.tsclass.network.IConvenientDns
/**
* gets a zone id of a domain from cloudflare
* @param domainName
* @deprecated Use zoneManager.getZoneId() instead
*/
getZoneId: async (domainName: string) => {
const domain = new plugins.smartstring.Domain(domainName);
@@ -175,6 +189,7 @@ export class CloudflareAccount implements plugins.tsclass.network.IConvenientDns
* gets a record
* @param domainNameArg
* @param typeArg
* @deprecated Use recordManager.getRecord() or getConvenientDnsProvider().getRecord() instead
*/
getRecord: async (
domainNameArg: string,
@@ -204,6 +219,7 @@ export class CloudflareAccount implements plugins.tsclass.network.IConvenientDns
},
/**
* creates a record
* @deprecated Use recordManager.createRecord() or getConvenientDnsProvider().createRecord() instead
*/
createRecord: async (
domainNameArg: string,
@@ -226,6 +242,7 @@ export class CloudflareAccount implements plugins.tsclass.network.IConvenientDns
* removes a record from Cloudflare
* @param domainNameArg
* @param typeArg
* @deprecated Use recordManager.deleteRecord() or getConvenientDnsProvider().removeRecord() instead
*/
removeRecord: async (
domainNameArg: string,
@@ -251,6 +268,7 @@ export class CloudflareAccount implements plugins.tsclass.network.IConvenientDns
/**
* cleanrecord allows the cleaning of any previous records to avoid unwanted sideeffects
* @deprecated Use recordManager.cleanRecords() or getConvenientDnsProvider().cleanRecord() instead
*/
cleanRecord: async (domainNameArg: string, typeArg: plugins.tsclass.network.TDnsRecordType) => {
try {
@@ -312,6 +330,7 @@ export class CloudflareAccount implements plugins.tsclass.network.IConvenientDns
* @param contentArg New content for the record
* @param ttlArg Time to live in seconds (optional)
* @returns Updated record
* @deprecated Use recordManager.updateRecord() or getConvenientDnsProvider().updateRecord() instead
*/
updateRecord: async (
domainNameArg: string,
@@ -348,6 +367,7 @@ export class CloudflareAccount implements plugins.tsclass.network.IConvenientDns
/**
* list all records of a specified domain name
* @param domainNameArg - the domain name that you want to get the records from
* @deprecated Use recordManager.listRecords() or getConvenientDnsProvider().listRecords() instead
*/
listRecords: async (domainNameArg: string) => {
try {
@@ -372,6 +392,7 @@ export class CloudflareAccount implements plugins.tsclass.network.IConvenientDns
/**
* list all zones in the associated authenticated account
* @param domainName optional filter by domain name
* @deprecated Use zoneManager.listZones() instead
*/
listZones: async (domainName?: string) => {
try {
@@ -401,6 +422,7 @@ export class CloudflareAccount implements plugins.tsclass.network.IConvenientDns
* Determines whether the given domain can be managed by this account
* @param domainName Full domain name to check (e.g., "sub.example.com")
* @returns True if the zone for the domain exists in the account, false otherwise
* @deprecated Use getConvenientDnsProvider().isDomainSupported() instead
*/
isDomainSupported: async (domainName: string): Promise<boolean> => {
try {
@@ -417,6 +439,7 @@ export class CloudflareAccount implements plugins.tsclass.network.IConvenientDns
},
/**
* purges a zone
* @deprecated Use zoneManager.purgeZone() instead
*/
purgeZone: async (domainName: string): Promise<void> => {
const domain = new plugins.smartstring.Domain(domainName);
@@ -428,6 +451,9 @@ export class CloudflareAccount implements plugins.tsclass.network.IConvenientDns
},
// acme convenience functions
/**
* @deprecated Use getConvenientDnsProvider().acmeSetDnsChallenge() instead
*/
acmeSetDnsChallenge: async (dnsChallenge: plugins.tsclass.network.IDnsChallenge) => {
await this.convenience.cleanRecord(dnsChallenge.hostName, 'TXT');
await this.convenience.createRecord(
@@ -437,6 +463,9 @@ export class CloudflareAccount implements plugins.tsclass.network.IConvenientDns
120,
);
},
/**
* @deprecated Use getConvenientDnsProvider().acmeRemoveDnsChallenge() instead
*/
acmeRemoveDnsChallenge: async (dnsChallenge: plugins.tsclass.network.IDnsChallenge) => {
await this.convenience.removeRecord(dnsChallenge.hostName, 'TXT');
},

View File

@@ -0,0 +1,178 @@
import * as plugins from './cloudflare.plugins.js';
import { logger } from './cloudflare.logger.js';
/**
* Adapter class that implements IConvenientDnsProvider interface
* Delegates to RecordManager and ZoneManager internally for clean architecture
* This allows third-party modules to use the standard DNS provider interface
*/
export class ConvenientDnsProvider implements plugins.tsclass.network.IConvenientDnsProvider {
/**
* The convenience property is required by IConvenientDnsProvider interface
* It returns this instance to maintain interface compatibility
*/
public convenience = this;
constructor(private cfAccount: any) {}
/**
* Creates a new DNS record
* @param domainNameArg - The domain name for the record
* @param typeArg - The DNS record type
* @param contentArg - The record content (IP address, CNAME target, etc.)
* @param ttlArg - Time to live in seconds (default: 1 = automatic)
* @returns Created record as raw API object
*/
public async createRecord(
domainNameArg: string,
typeArg: plugins.tsclass.network.TDnsRecordType,
contentArg: string,
ttlArg: number = 1,
): Promise<any> {
const record = await this.cfAccount.recordManager.createRecord(
domainNameArg,
typeArg,
contentArg,
ttlArg,
);
// Return raw API object format for interface compatibility
return this.recordToApiObject(record);
}
/**
* Updates an existing DNS record, or creates it if it doesn't exist
* @param domainNameArg - The domain name
* @param typeArg - The DNS record type
* @param contentArg - The new record content
* @param ttlArg - Time to live in seconds (default: 1 = automatic)
* @returns Updated record as raw API object
*/
public async updateRecord(
domainNameArg: string,
typeArg: plugins.tsclass.network.TDnsRecordType,
contentArg: string,
ttlArg: number = 1,
): Promise<any> {
const record = await this.cfAccount.recordManager.updateRecord(
domainNameArg,
typeArg,
contentArg,
ttlArg,
);
return this.recordToApiObject(record);
}
/**
* Removes a DNS record
* @param domainNameArg - The domain name
* @param typeArg - The DNS record type
*/
public async removeRecord(
domainNameArg: string,
typeArg: plugins.tsclass.network.TDnsRecordType,
): Promise<any> {
await this.cfAccount.recordManager.deleteRecord(domainNameArg, typeArg);
}
/**
* Gets a specific DNS record by domain and type
* @param domainNameArg - The domain name
* @param typeArg - The DNS record type
* @returns Record as raw API object or undefined if not found
*/
public async getRecord(
domainNameArg: string,
typeArg: plugins.tsclass.network.TDnsRecordType,
): Promise<any | undefined> {
const record = await this.cfAccount.recordManager.getRecord(domainNameArg, typeArg);
return record ? this.recordToApiObject(record) : undefined;
}
/**
* Lists all DNS records for a domain
* @param domainNameArg - The domain name to list records for
* @returns Array of records as raw API objects
*/
public async listRecords(domainNameArg: string): Promise<any[]> {
const records = await this.cfAccount.recordManager.listRecords(domainNameArg);
return records.map((record: any) => this.recordToApiObject(record));
}
/**
* Removes all DNS records of a specific type for a domain
* @param domainNameArg - The domain name
* @param typeArg - The DNS record type to clean
*/
public async cleanRecord(
domainNameArg: string,
typeArg: plugins.tsclass.network.TDnsRecordType,
): Promise<void> {
await this.cfAccount.recordManager.cleanRecords(domainNameArg, typeArg);
}
/**
* Determines whether the given domain can be managed by this account
* @param domainName - Full domain name to check (e.g., "sub.example.com")
* @returns True if the zone for the domain exists in the account, false otherwise
*/
public async isDomainSupported(domainName: string): Promise<boolean> {
try {
// Parse out the apex/zone name from the full domain
const domain = new plugins.smartstring.Domain(domainName);
// List zones filtered by the zone name
const zones = await this.cfAccount.zoneManager.listZones(domain.zoneName);
// If any zone matches, we can manage this domain
return Array.isArray(zones) && zones.length > 0;
} catch (error) {
logger.log('error', `Error checking domain support for ${domainName}: ${error.message}`);
return false;
}
}
/**
* Sets an ACME DNS challenge for domain verification
* @param dnsChallenge - The DNS challenge object
*/
public async acmeSetDnsChallenge(
dnsChallenge: plugins.tsclass.network.IDnsChallenge,
): Promise<void> {
await this.cfAccount.recordManager.cleanRecords(dnsChallenge.hostName, 'TXT');
await this.cfAccount.recordManager.createRecord(
dnsChallenge.hostName,
'TXT',
dnsChallenge.challenge,
120,
);
}
/**
* Removes an ACME DNS challenge
* @param dnsChallenge - The DNS challenge object
*/
public async acmeRemoveDnsChallenge(
dnsChallenge: plugins.tsclass.network.IDnsChallenge,
): Promise<void> {
await this.cfAccount.recordManager.deleteRecord(dnsChallenge.hostName, 'TXT');
}
/**
* Helper method to convert CloudflareRecord instance to raw API object format
* This ensures compatibility with the IConvenientDnsProvider interface
*/
private recordToApiObject(record: any): any {
return {
id: record.id,
type: record.type,
name: record.name,
content: record.content,
proxiable: record.proxiable,
proxied: record.proxied,
ttl: record.ttl,
locked: record.locked,
zone_id: record.zone_id,
zone_name: record.zone_name,
created_on: record.created_on,
modified_on: record.modified_on,
};
}
}

View File

@@ -0,0 +1,198 @@
import * as plugins from './cloudflare.plugins.js';
import { logger } from './cloudflare.logger.js';
import { CloudflareRecord } from './cloudflare.classes.record.js';
export class RecordManager {
constructor(private cfAccount: any) {}
/**
* Lists all DNS records for a domain
* @param domainNameArg - The domain name to list records for
* @returns Array of CloudflareRecord instances
*/
public async listRecords(domainNameArg: string): Promise<CloudflareRecord[]> {
try {
const domain = new plugins.smartstring.Domain(domainNameArg);
const zoneId = await this.cfAccount.zoneManager.getZoneId(domain.zoneName);
const records: plugins.ICloudflareTypes['Record'][] = [];
// Collect all records using async iterator
for await (const record of this.cfAccount.apiAccount.dns.records.list({
zone_id: zoneId,
})) {
records.push(record);
}
logger.log('info', `Found ${records.length} DNS records for ${domainNameArg}`);
// Convert to CloudflareRecord instances
return records.map(record => CloudflareRecord.createFromApiObject(record));
} catch (error) {
logger.log('error', `Failed to list records for ${domainNameArg}: ${error.message}`);
return [];
}
}
/**
* Gets a specific DNS record by domain and type
* @param domainNameArg - The domain name
* @param typeArg - The DNS record type (A, AAAA, CNAME, TXT, etc.)
* @returns CloudflareRecord instance or undefined if not found
*/
public async getRecord(
domainNameArg: string,
typeArg: plugins.tsclass.network.TDnsRecordType,
): Promise<CloudflareRecord | undefined> {
try {
const domain = new plugins.smartstring.Domain(domainNameArg);
const recordArray = await this.listRecords(domain.zoneName);
const filteredRecords = recordArray.filter((recordArg) => {
return recordArg.type === typeArg && recordArg.name === domainNameArg;
});
return filteredRecords.length > 0 ? filteredRecords[0] : undefined;
} catch (error) {
logger.log('error', `Error getting record for ${domainNameArg}: ${error.message}`);
return undefined;
}
}
/**
* Creates a new DNS record
* @param domainNameArg - The domain name for the record
* @param typeArg - The DNS record type
* @param contentArg - The record content (IP address, CNAME target, etc.)
* @param ttlArg - Time to live in seconds (default: 1 = automatic)
* @returns Created CloudflareRecord instance
*/
public async createRecord(
domainNameArg: string,
typeArg: plugins.tsclass.network.TDnsRecordType,
contentArg: string,
ttlArg: number = 1,
): Promise<CloudflareRecord> {
const domain = new plugins.smartstring.Domain(domainNameArg);
const zoneId = await this.cfAccount.zoneManager.getZoneId(domain.zoneName);
const response = await this.cfAccount.apiAccount.dns.records.create({
zone_id: zoneId,
type: typeArg as any,
name: domain.fullName,
content: contentArg,
ttl: ttlArg,
});
logger.log('info', `Created ${typeArg} record for ${domainNameArg}`);
return CloudflareRecord.createFromApiObject(response);
}
/**
* Updates an existing DNS record, or creates it if it doesn't exist
* @param domainNameArg - The domain name
* @param typeArg - The DNS record type
* @param contentArg - The new record content
* @param ttlArg - Time to live in seconds (default: 1 = automatic)
* @returns Updated CloudflareRecord instance
*/
public async updateRecord(
domainNameArg: string,
typeArg: plugins.tsclass.network.TDnsRecordType,
contentArg: string,
ttlArg: number = 1,
): Promise<CloudflareRecord> {
const domain = new plugins.smartstring.Domain(domainNameArg);
const zoneId = await this.cfAccount.zoneManager.getZoneId(domain.zoneName);
// Find existing record
const existingRecord = await this.getRecord(domainNameArg, typeArg);
if (!existingRecord) {
logger.log(
'warn',
`Record ${domainNameArg} of type ${typeArg} not found for update, creating instead`,
);
return this.createRecord(domainNameArg, typeArg, contentArg, ttlArg);
}
// Update the record
const updatedRecord = await this.cfAccount.apiAccount.dns.records.edit(existingRecord.id, {
zone_id: zoneId,
type: typeArg as any,
name: domain.fullName,
content: contentArg,
ttl: ttlArg,
});
logger.log('info', `Updated ${typeArg} record for ${domainNameArg}`);
return CloudflareRecord.createFromApiObject(updatedRecord);
}
/**
* Deletes a DNS record
* @param domainNameArg - The domain name
* @param typeArg - The DNS record type
*/
public async deleteRecord(
domainNameArg: string,
typeArg: plugins.tsclass.network.TDnsRecordType,
): Promise<void> {
const domain = new plugins.smartstring.Domain(domainNameArg);
const zoneId = await this.cfAccount.zoneManager.getZoneId(domain.zoneName);
const record = await this.getRecord(domainNameArg, typeArg);
if (record) {
await this.cfAccount.apiAccount.dns.records.delete(record.id, {
zone_id: zoneId,
});
logger.log('info', `Deleted ${typeArg} record for ${domainNameArg}`);
} else {
logger.log('warn', `Record ${domainNameArg} of type ${typeArg} not found for deletion`);
}
}
/**
* Removes all DNS records of a specific type for a domain
* @param domainNameArg - The domain name
* @param typeArg - The DNS record type to clean
*/
public async cleanRecords(
domainNameArg: string,
typeArg: plugins.tsclass.network.TDnsRecordType,
): Promise<void> {
try {
logger.log('info', `Cleaning ${typeArg} records for ${domainNameArg}`);
const domain = new plugins.smartstring.Domain(domainNameArg);
const zoneId = await this.cfAccount.zoneManager.getZoneId(domain.zoneName);
// List all records in the zone for this domain
const records = await this.listRecords(domain.zoneName);
// Only delete records matching the specified name and type
const recordsToDelete = records.filter((recordArg) => {
return recordArg.type === typeArg && recordArg.name === domainNameArg;
});
logger.log(
'info',
`Found ${recordsToDelete.length} ${typeArg} records to delete for ${domainNameArg}`,
);
for (const recordToDelete of recordsToDelete) {
try {
await this.cfAccount.apiAccount.dns.records.delete(recordToDelete.id, {
zone_id: zoneId,
});
logger.log('info', `Deleted ${typeArg} record ${recordToDelete.id} for ${domainNameArg}`);
} catch (deleteError) {
logger.log('error', `Failed to delete record: ${deleteError.message}`);
}
}
} catch (error) {
logger.log(
'error',
`Error cleaning ${typeArg} records for ${domainNameArg}: ${error.message}`,
);
}
}
}

View File

@@ -20,7 +20,7 @@ export class CloudflareWorker {
): Promise<CloudflareWorker> {
const newWorker = new CloudflareWorker(workerManager);
Object.assign(newWorker, apiObject);
await newWorker.getRoutes();
await newWorker.listRoutes();
return newWorker;
}
@@ -41,9 +41,9 @@ export class CloudflareWorker {
}
/**
* gets all routes for a worker
* Lists all routes for this worker
*/
public async getRoutes() {
public async listRoutes() {
try {
this.routes = []; // Reset routes before fetching
@@ -102,7 +102,7 @@ export class CloudflareWorker {
*/
public async setRoutes(routeArray: IWorkerRouteDefinition[]) {
// First get all existing routes to determine what we need to create/update
await this.getRoutes();
await this.listRoutes();
for (const newRoute of routeArray) {
// Determine whether a route is new, needs an update, or is already up to date
@@ -156,7 +156,7 @@ export class CloudflareWorker {
}
// Refresh routes after all changes
await this.getRoutes();
await this.listRoutes();
}
/**

View File

@@ -39,7 +39,7 @@ export class WorkerManager {
// Initialize the worker and get its routes
try {
await worker.getRoutes();
await worker.listRoutes();
} catch (routeError) {
logger.log('warn', `Failed to get routes for worker ${workerName}: ${routeError.message}`);
// Continue anyway since the worker was created
@@ -79,7 +79,7 @@ export class WorkerManager {
// Initialize the worker and get its routes
try {
await worker.getRoutes();
await worker.listRoutes();
} catch (routeError) {
logger.log('warn', `Failed to get routes for worker ${workerName}: ${routeError.message}`);
// Continue anyway since we found the worker
@@ -96,7 +96,7 @@ export class WorkerManager {
* Lists all worker scripts
* @returns Array of worker scripts
*/
public async listWorkerScripts() {
public async listWorkers() {
if (!this.cfAccount.preselectedAccountId) {
throw new Error('No account selected. Please select it first on the account.');
}

View File

@@ -12,11 +12,11 @@ export class ZoneManager {
}
/**
* Get all zones, optionally filtered by name
* Lists all zones, optionally filtered by name
* @param zoneName Optional zone name to filter by
* @returns Array of CloudflareZone instances
*/
public async getZones(zoneName?: string): Promise<CloudflareZone[]> {
public async listZones(zoneName?: string): Promise<CloudflareZone[]> {
try {
const options: any = { per_page: 50 };
@@ -37,13 +37,33 @@ export class ZoneManager {
}
}
/**
* Gets the zone ID for a domain name
* @param domainName Domain name to get the zone ID for
* @returns Zone ID string
* @throws Error if domain is not found in this account
*/
public async getZoneId(domainName: string): Promise<string> {
const domain = new plugins.smartstring.Domain(domainName);
const zoneArray = await this.listZones(domain.zoneName);
const filteredResponse = zoneArray.filter((zoneArg) => {
return zoneArg.name === domainName;
});
if (filteredResponse.length >= 1) {
return filteredResponse[0].id;
} else {
logger.log('error', `the domain ${domainName} does not appear to be in this account!`);
throw new Error(`the domain ${domainName} does not appear to be in this account!`);
}
}
/**
* Get a single zone by name
* @param zoneName Zone name to find
* @returns CloudflareZone instance or undefined if not found
*/
public async getZoneByName(zoneName: string): Promise<CloudflareZone | undefined> {
const zones = await this.getZones(zoneName);
const zones = await this.listZones(zoneName);
return zones.find((zone) => zone.name === zoneName);
}
@@ -130,7 +150,7 @@ export class ZoneManager {
* @returns True if the zone exists
*/
public async zoneExists(zoneName: string): Promise<boolean> {
const zones = await this.getZones(zoneName);
const zones = await this.listZones(zoneName);
return zones.some((zone) => zone.name === zoneName);
}
@@ -180,4 +200,18 @@ export class ZoneManager {
return undefined;
}
}
/**
* Purges all cached files for a zone
* @param domainName Domain name to purge cache for
*/
public async purgeZone(domainName: string): Promise<void> {
const domain = new plugins.smartstring.Domain(domainName);
const zoneId = await this.getZoneId(domain.zoneName);
await this.cfAccount.apiAccount.cache.purge({
zone_id: zoneId,
purge_everything: true,
});
logger.log('info', `Purged cache for zone ${domainName}`);
}
}

View File

@@ -6,8 +6,10 @@ export {
} from './cloudflare.classes.worker.js';
export { WorkerManager } from './cloudflare.classes.workermanager.js';
export { CloudflareRecord, type ICloudflareRecordInfo } from './cloudflare.classes.record.js';
export { RecordManager } from './cloudflare.classes.recordmanager.js';
export { CloudflareZone } from './cloudflare.classes.zone.js';
export { ZoneManager } from './cloudflare.classes.zonemanager.js';
export { ConvenientDnsProvider } from './cloudflare.classes.convenientdnsprovider.js';
export { CloudflareUtils } from './cloudflare.utils.js';
export { commitinfo } from './00_commitinfo_data.js';