cloudflare-ddns-sync 4.0.0-beta.2 → 4.0.0-rc.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## v4
+
+### v4.0.0
+
+- ⬆️ Update dependencies, including Cloudflare 2 → 7, node-cron 3 → 4 and public-ip 6 → 8.
+- ♻️ Preserve public auth fields, key/token precedence, record types, sync methods and DNS defaults while adapting to the new SDK.
+- ♻️ Fetch all zone and DNS record pages; report zone-loading failures through the awaited operation.
+- 🚨 Add a DDNS-oriented API with `createDdns()`, `sync()`, `schedule()`, `watch()`, `list()`, `remove()` and `ip()`
+- 🚨 Allow records to be configured as hostnames; A and AAAA records automatically resolve the matching public IP
+- 🚨 Return a dedicated controllable job from schedules and watchers
+- 🐛 Respect the requested DNS type when listing records with the same hostname
+- ♻️ Validate configuration before network access, make jobs safe to stop and add `sync({ipv4, ipv6})` for configured records
+
 ## v3
 
 ### 3.0.2

package/MIGRATION-V4.md

@@ -0,0 +1,64 @@
+# Migrating from v3 to v4
+
+v4 replaces the class-based API with `createDdns()` and consolidates related methods. Node.js 20 remains the minimum requirement.
+
+## Initialization
+
+```ts
+// v3
+const ddns = new CloudflareDDNSSync({token});
+
+// v4
+const ddns = createDdns({token, records: ['home.example.com']});
+```
+
+If `token` is omitted, v4 reads `CLOUDFLARE_API_TOKEN`. `email`/`key` and user service keys remain supported.
+
+## Synchronizing
+
+```ts
+// v3
+await ddns.syncRecord({name: 'home.example.com'});
+await ddns.syncRecords(records, '203.0.113.10');
+
+// v4
+await ddns.sync('home.example.com');
+await ddns.sync(records, {ipv4: '203.0.113.10'});
+await ddns.sync({ipv4: '203.0.113.10'}); // configured records
+```
+
+`sync()` always returns an array. For a single record, use the first entry: `const [record] = await ddns.sync('home.example.com')`.
+
+For configured records, pass fixed addresses directly as the first argument. The former placeholder form `sync(undefined, {ipv4})` remains supported for compatibility.
+
+A and AAAA records automatically use the matching IP family. Non-IP records now require explicit `content`.
+
+## Scheduling and watching
+
+```ts
+// v3
+const task = ddns.syncByCronTime('*/5 * * * *', records, callback);
+const id = await ddns.syncOnIpChange(records, callback);
+ddns.stopSyncOnIpChange(id);
+
+// v4
+const task = ddns.schedule('*/5 * * * *', {records, onSync: callback});
+const watcher = await ddns.watch({records, onSync: callback});
+await watcher.stop();
+```
+
+`schedule()` and `watch()` return a `SyncJob` with `run()`, `start()` and `stop()`. A v4 job replaces both the listener ID and the direct `node-cron` return value.
+
+## Listing, removing and retrieving IPs
+
+| v3 | v4 |
+| --- | --- |
+| `getRecordDataForRecord(record)` | `list({records: record})` |
+| `getRecordDataForRecords(records)` | `list({records})` |
+| `getRecordDataForDomain(domain)` | `list({domains: domain})` |
+| `getRecordDataForDomains(domains)` | `list({domains, groupBy: 'domain'})` |
+| `removeRecord(name, type?)` | `remove(name)` oder `remove({name, type})` |
+| `getIp()` | `ip()` |
+| `getIpv6()` | `ip(6)` |
+
+`list()` without filters uses the configured records. Without that configuration, a filter is required.

package/README.md

@@ -1,160 +1,134 @@
 <table>
   <tr>
-    <td width="25%"><img src="./logo.png" alt="Logo" width="100%"></td>
+    <td width="25%"><img src="./logo.png" alt="Cloudflare DDNS Sync logo" width="100%"></td>
     <td><h1>Cloudflare DDNS Sync</h1></td>
   </tr>
 </table>
 
-![](https://github.com/SteffenKn/cloudflare-ddns-sync/actions/workflows/push.yml/badge.svg)
-[![npm version](https://badge.fury.io/js/cloudflare-ddns-sync.svg)](https://www.npmjs.com/package/cloudflare-ddns-sync)
-[![Downloads](https://img.shields.io/npm/dm/cloudflare-ddns-sync.svg)](https://www.npmjs.com/package/cloudflare-ddns-sync)
-[![CLI](https://img.shields.io/badge/CLI-npm-important.svg)](https://www.npmjs.com/package/cloudflare-ddns-sync-cli)
+Cloudflare DDNS Sync synchronizes DNS records with the current public IP address. Version 4 provides a small, DDNS-oriented API.
 
-## Overview
+## Voraussetzungen
 
-Cloudflare-DDNS-Sync is a simple module that updates Cloudflare DNS records.
+- Node.js 20 or newer
+- A Cloudflare API token with permission to read zones and edit DNS records
 
-For a more detailed overview, have a look at the [Documentation](https://cddnss.knaup.pw/)
+```sh
+npm install cloudflare-ddns-sync
+```
 
-You may also have a look at the **official** [CLI version](https://www.npmjs.com/package/cloudflare-ddns-sync-cli) of Cloudflare-DDNS-Sync.
+## Einstieg
 
-## How do I set this project up?
+Set `CLOUDFLARE_API_TOKEN` and configure the hostnames once:
 
-### Prerequisites
+```ts
+import {createDdns} from 'cloudflare-ddns-sync';
 
-- Node
-- Cloudflare Account
+const ddns = createDdns({
+  records: ['home.example.com', {name: 'app.example.com', proxied: true}],
+});
 
-### Installation
+await ddns.sync();
+```
 
-To install Cloudflare-DDNS-Sync simply run:
+A string represents an A record. Missing A and AAAA records are created; existing records with the same name and type are updated. A records automatically receive the public IPv4 address, and AAAA records receive the IPv6 address.
 
-```
-npm install cloudflare-ddns-sync
+```ts
+const ddns = createDdns({
+  token: process.env.CLOUDFLARE_API_TOKEN,
+  records: [
+    'home.example.com',
+    {name: 'home.example.com', type: 'AAAA'},
+    {name: 'alias.example.com', type: 'CNAME', content: 'home.example.com'},
+  ],
+});
+
+await ddns.sync();
 ```
 
-in your project folder.
+Explicit `token`, `email`/`key` and user service keys remain supported. If no credentials are provided, only `CLOUDFLARE_API_TOKEN` is used.
 
-## Usage
+## Synchronizing
 
-> Hint: If a record is not existing, CDS will automatically create it when
-> syncing.
+```ts
+await ddns.sync();
+await ddns.sync('temporary.example.com');
+await ddns.sync(['home.example.com', {name: 'vpn.example.com', proxied: true}]);
 
-### Javascript Example
+await ddns.sync({
+  ipv4: '203.0.113.10',
+  ipv6: '2001:db8::1',
+});
+```
 
-```javascript
-const Cddnss = require('cloudflare-ddns-sync').default;
+`sync()` always returns an array of updated DNS records. Explicit `content` on a record takes precedence. Record types other than A and AAAA require `content`.
 
-// either email and key or token
-const cddnss = new Cddnss({
-  email: 'your@email.com',
-  key: '<your-cloudflare-api-key>',
-  token: '<your-cloudflare-api-token>',
-});
+Use `plan()` to inspect the same operation without writing DNS records. Each entry has an `action` of `create`, `update` or `unchanged`. `sync()` leaves unchanged records untouched. If one or more writes fail, it throws `SyncError` with `succeeded` and `failed` entries.
 
-const records = [
-  {
-    name: 'test-1.domain.com',
-    type: 'A', // optional
-    proxied: true, // optional
-    ttl: 1, // optional
-    priority: 0, // optional
-    content: '1.2.3.4', // optional
-  },
-  {
-    name: 'test-2.domain.com',
-  },
-];
-
-cddnss.syncRecords(records).then((result) => {
-  console.log(result);
-});
+```ts
+const changes = await ddns.plan();
 ```
 
-### Typescript Example
+## Scheduling and IP watching
 
-```typescript
-import Cddnss, {Record, RecordData} from 'cloudflare-ddns-sync';
+```ts
+const scheduled = ddns.schedule('*/5 * * * *');
+await scheduled.stop();
 
-// either email and key or token
-const cddnss = new Cddnss({
-  email: 'your@email.com',
-  key: '<your-cloudflare-api-key>',
-  token: '<your-cloudflare-api-token>',
+const watching = await ddns.watch({
+  onError: error => console.error(error),
 });
 
-const records: Array<Record> = [
-  {
-    name: 'test-1.yourdomain.com',
-    type: 'A', // optional
-    proxied: true, // optional
-    ttl: 1, // optional
-    priority: 0, // optional
-    content: '1.2.3.4', // optional
-  },
-  {
-    name: 'test-2.yourdomain.com',
-  },
-];
-
-cddnss.syncRecords(records).then((result: Array<RecordData>) => {
-  console.log(result);
-});
+await watching.stop();
 ```
 
-### Cron Expression Syntax
+`schedule()` starts immediately and synchronizes at the next cron interval. `watch()` synchronizes first and then watches only the required IP families; the default interval is ten seconds. Fixed addresses and records with explicit `content` are not polled. Both return a job with `run()`, `start()` and `stop()` methods. Errors from `run()` reject its promise; automatic runs call `onError` once.
 
-Cron expressions have the following syntax:
+Configuration errors are `DdnsError`s with `code: 'INVALID_CONFIG'`; errors while looking up a public address have `code: 'IP_UNAVAILABLE'`.
 
+## Listing and removing records
+
+```ts
+const records = await ddns.list({records: 'home.example.com'});
+const ipv6Records = await ddns.list({records: {name: 'home.example.com', type: 'AAAA'}});
+const domainRecords = await ddns.list({domains: 'example.com'});
+const grouped = await ddns.list({domains: ['example.com', 'example.org'], groupBy: 'domain'});
+
+await ddns.remove('home.example.com');
+await ddns.remove({name: 'home.example.com', type: 'AAAA'});
 ```
-* * * * * *
-┬ ┬ ┬ ┬ ┬ ┬
-│ │ │ │ │ │
-│ │ │ │ │ └──── weekday (0-7, sunday is 0 or 7)
-│ │ │ │ └────── month (1-12)
-│ │ │ └──────── day (1-31)
-│ │ └────────── hour (0-23)
-│ └──────────── minute (0-59)
-└────────────── second (0-59) [optional]
+
+`remove('name')` removes an A record. Use a record object for other types. `list()` without filters uses the records configured when creating the DDNS instance. A record filter with `type` returns only that DNS type.
+
+## Public IP
+
+```ts
+const ipv4 = await ddns.ip();
+const ipv6 = await ddns.ip(6);
 ```
 
-## Methods
-
-- getIp(): Promise\<string\>
-- getIpv6(): Promise\<string\>
-- getRecordDataForDomain(domain: string): Promise\<Array\<[RecordData](https://cddnss.knaup.pw/types/recorddata)\>\>
-- getRecordDataForDomains(domains: Array\<string\>): Promise\<[DomainRecordList](https://cddnss.knaup.pw/types/domainrecordlist)\>
-- getRecordDataForRecord(record: [Record](https://cddnss.knaup.pw/types/record)): Promise\<[RecordData](https://cddnss.knaup.pw/types/recorddata)\>
-- getRecordDataForRecords(records: Array\<[Record](https://cddnss.knaup.pw/types/record)\>): Promise\<Array\<[RecordData](https://cddnss.knaup.pw/types/recorddata)\>\>
-- removeRecord(recordName: string, recordType?: string): Promise\<void\>
-- stopSyncOnIpChange(changeListenerId: string): void
-- syncByCronTime(cronExpression: string, records: Array\<[Record](https://cddnss.knaup.pw/types/recorddata)\>, callback: [MultiSyncCallback](https://cddnss.knaup.pw/types/multisynccallback), ip?: string): [ScheduledTask](https://www.npmjs.com/package/node-cron#scheduledtask-methods)
-- syncOnIpChange(records: Array\<[Record](https://cddnss.knaup.pw/types/record)\>, callback: multisynccallback): Promise\<string\>
-- syncRecord(record: [Record](https://cddnss.knaup.pw/types/record), ip?: string): Promise\<[RecordData](https://cddnss.knaup.pw/types/recorddata)\>
-- syncRecords(records: Array\<[Record](https://cddnss.knaup.pw/types/record)\>, ip?: string): Promise\<Array\<[RecordData](https://cddnss.knaup.pw/types/recorddata)\>\>
-
-For a more detailed view, have a look at the [Documentation](https://cddnss.knaup.pw/)
-
-## Get Your Cloudflare API Key
-
-- Go to **[Cloudflare](https://www.cloudflare.com)**
-- **Log In**
-- In the upper right corner: **click on the user icon**
-- Go to **"My Profile"**
-- In the "API Tokens"-Section: **click on the "View"-Button of the Global Key**
-- **Enter your password** and **fill the captcha**
-- **Copy the API Key**
+## Optional: eigene IP-Quelle und Zone
 
-## Tests
+```ts
+const ddns = createDdns({
+  zone: 'example.com',
+  records: ['@', 'home'],
+  resolveIp: family => readAddressFromRouter(family),
+});
+
+await ddns.close();
+```
 
-In order to run the tests there are two ways to do so
+With `zone`, `@` means the zone apex and simple labels are expanded. `resolveIp` is used by both `sync()` and `watch()`.
 
-### Use `test-data.json`
+## Migrating from v3
 
-- Open the `test-data.json` which can be found under `src/tests/test-service/`
-- Configure the email, cloudflare api key and the domain
-- Run `npm test`
+v4 is a breaking release. See [MIGRATION-V4.md](./MIGRATION-V4.md) for the complete mapping of the previous API.
 
-### Use `npm test` Only
+## Tests
+
+The integration tests create and remove records in a Cloudflare test zone:
 
-- Run `npm test -- --email="your@email.com" --key="your_cloudflare_api_key" --domain="yourdomain.com"`
+```sh
+npm run build
+npm test -- --token="$CLOUDFLARE_API_TOKEN" --domain="example.com"
+```

package/dist/index.d.ts

@@ -1,18 +1,43 @@
-import { Auth, MultiSyncCallback, Record } from './types/index.js';
-export default class CloudflareDDNSSync {
-    private cloudflareClient;
-    constructor(auth: Auth);
-    getIp(): Promise<string>;
-    getIpv6(): Promise<string>;
-    getRecordDataForDomain(domain: string): Promise<import("cloudflare/resources/dns/records.mjs").DNSRecord[]>;
-    getRecordDataForDomains(domains: Array<string>): Promise<{}>;
-    getRecordDataForRecord(record: Record): Promise<import("cloudflare/resources/dns/records.mjs").DNSRecord>;
-    getRecordDataForRecords(records: Array<Record>): Promise<any[]>;
-    removeRecord(recordName: string, recordType?: string): Promise<void>;
-    stopSyncOnIpChange(changeListenerId: string): void;
-    syncByCronTime(cronExpression: string, records: Array<Record>, callback: MultiSyncCallback, ip?: string): import("node-cron").ScheduledTask;
-    syncOnIpChange(records: Array<Record>, callback: MultiSyncCallback): Promise<string>;
-    syncRecord(record: Record, ip?: string): any;
-    syncRecords(records: Array<Record>, ip?: string): Promise<import("cloudflare/resources/dns/records.mjs").DNSRecord[]>;
+import { SyncError } from './lib/sync-error.js';
+import { DdnsOptions, DnsRecord, DomainListOptions, GroupedDomainListOptions, JobOptions, RecordListOptions, RecordSelection, SyncJob, SyncChange, SyncOptions, WatchOptions } from './types/index.js';
+export type DdnsErrorCode = 'INVALID_CONFIG' | 'IP_UNAVAILABLE';
+export declare class DdnsError extends Error {
+    readonly code: DdnsErrorCode;
+    readonly cause?: unknown;
+    constructor(code: DdnsErrorCode, message: string, cause?: unknown);
 }
+export { SyncError };
+export declare class Ddns {
+    private readonly cloudflareClient;
+    private readonly configuredRecords?;
+    private readonly zone?;
+    private readonly resolveIp?;
+    private readonly jobs;
+    private closed;
+    constructor(options?: DdnsOptions);
+    sync(): Promise<Array<DnsRecord>>;
+    sync(options: SyncOptions): Promise<Array<DnsRecord>>;
+    sync(records: RecordSelection, options?: SyncOptions): Promise<Array<DnsRecord>>;
+    sync(records: undefined, options: SyncOptions): Promise<Array<DnsRecord>>;
+    plan(): Promise<Array<SyncChange>>;
+    plan(options: SyncOptions): Promise<Array<SyncChange>>;
+    plan(records: RecordSelection, options?: SyncOptions): Promise<Array<SyncChange>>;
+    schedule(expression: string, options?: JobOptions): SyncJob;
+    watch(options?: WatchOptions): Promise<SyncJob>;
+    list(): Promise<Array<DnsRecord>>;
+    list(filter: RecordListOptions): Promise<Array<DnsRecord>>;
+    list(filter: DomainListOptions): Promise<Array<DnsRecord>>;
+    list(filter: GroupedDomainListOptions): Promise<{
+        [domain: string]: Array<DnsRecord>;
+    }>;
+    remove(records: RecordSelection): Promise<void>;
+    ip(family?: 4 | 6): Promise<string>;
+    close(): Promise<void>;
+    private resolveRecords;
+    private ensureOpen;
+    private dynamicFamilies;
+    private withContent;
+}
+export declare function createDdns(options?: DdnsOptions): Ddns;
 export * from './types/index.js';
+export default createDdns;