Merge pull request #3 from cloudnode-pro/api-client

Implement API methods

Author: zefir-git

.gitignore

@@ -106,6 +106,8 @@ dist
 # Ignore .idea folder
 .idea
 
-# Ignore .js and .d.ts files
+# Ignore TypeScript build output
 *.js
 *.d.ts
+*.js.map
+*.d.ts.map

DOCS.md

@@ -1,2 +1,68 @@
-# hetzner-dns-client
+# Node.js Hetzner DNS API Client
+
+[![Hetzner DNS API Version](https://shields.io/badge/v1-%23D50C2D?label=Hetnzner%20DNS%20API&logo=hetzner&labelColor=%2324292E)](https://dns.hetzner.com/api-docs/)
+[![Version](https://img.shields.io/npm/v/hetzner-dns-client.svg)](https://npmjs.org/package/hetzner-dns-client)
+[![Downloads](https://img.shields.io/npm/dm/hetzner-dns-client.svg)](https://npmjs.org/package/hetzner-dns-client)
+
 Hetzner DNS API client for Node.js
+
+## Installation
+```bash
+npm i hetzner-dns-client
+```
+
+## Usage
+You can use this client library with your Node.js project.
+
+### JavaScript Example
+```js
+import {HetznerDnsClient, DnsRecord} from 'hetzner-dns-client';
+
+// create client instance
+const client = new HetznerDnsClient("YOUR_API_TOKEN");
+// get zone by ID
+const zone = await client.zones.get("ZONE_ID");
+// create apex/root zone record of type "A" to 127.0.0.1
+const record = await zone.createRecord("@", DnsRecord.Type.A, "127.0.0.1");
+```
+
+### TypeScript Example
+
+```ts
+import {HetznerDnsClient, DnsRecord, Zone} from 'hetzner-dns-client';
+
+// create client instance
+const client: HetznerDnsClient = new HetznerDnsClient("YOUR_API_TOKEN");
+// get zone by ID
+const zone: Zone = await client.zones.get("ZONE_ID");
+// create apex/root zone record of type "A" to 127.0.0.1
+const record: DnsRecord = await zone.createRecord("@", DnsRecord.Type.A, "127.0.0.1");
+```
+
+### Handling Errors
+Methods that may throw an error are marked with `throws` in the documentation and specify what error types may be thrown. You can catch these errors with a `try/catch` block.
+
+For example:
+
+```js
+try {
+    const zone = await client.zones.get("ID that does not exist");
+}
+catch (err) {
+    if (err instanceof ApiError)
+        console.error(err); // the Hetzner API returned an error, e.g. "Zone not found"
+    else if (err instanceof ClientParseError)
+        console.error(err); // the client could not understand or parse the response from the Hetzner API
+    else
+        console.error(err); // some other error occurred
+}
+```
+
+## API Documentation
+The official Hetzner DNS API documentation can be found on [https://dns.hetzner.com/api-docs/](https://dns.hetzner.com/api-docs/).
+
+> **Note**: The Hetzner DNS API documentation appears to be incomplete and contains a few errors. The documentation of this client library is a separate documentation and some functionality may be described differently.
+> 
+> If you find any errors in the documentation, or think that further clarification is needed, please open an issue or pull request.
+
+The client library documentation is available in DOCS.md in this repository.

README.md

@@ -0,0 +1,47 @@
+import HetznerDnsClient from "./lib/HetznerDnsClient.js";
+import Zone from "./lib/Zone.js";
+import DnsRecord from "./lib/DnsRecord.js";
+import PrimaryServer from "./lib/PrimaryServer.js";
+import ApiResponse from "./lib/ApiResponse.js";
+import Zones from "./lib/Zones.js";
+import ClientObject from "./lib/ClientObject.js";
+import BulkCreateRecordsPretty from "./lib/BulkCreateRecordsPretty.js";
+import BulkUpdateRecordsPretty from "./lib/BulkUpdateRecordsPretty.js";
+import ZoneValidationPretty from "./lib/ZoneValidationPretty.js";
+import ApiError from "./lib/errors/ApiError.js";
+import ClientParseError from "./lib/errors/ClientParseError.js";
+import ErrorModel from "./lib/models/ErrorModel";
+import ZoneModel from "./lib/models/ZoneModel";
+import BulkCreateRecords from "./lib/models/BulkCreateRecords";
+import BulkUpdateRecords from "./lib/models/BulkUpdateRecords";
+import BaseRecordModel from "./lib/models/BaseRecordModel";
+import RecordModel from "./lib/models/RecordModel";
+import PrimaryServerModel from "./lib/models/PrimaryServerModel";
+import PaginatedZones from "./lib/models/PaginatedZones";
+import PaginatedData from "./lib/models/PaginatedData";
+import ZoneValidation from "./lib/models/ZoneValidation";
+
+export default HetznerDnsClient;
+export {
+    Zone,
+    DnsRecord,
+    PrimaryServer,
+    ApiResponse,
+    Zones,
+    ClientObject,
+    BulkCreateRecordsPretty,
+    BulkUpdateRecordsPretty,
+    ZoneValidationPretty,
+    ApiError,
+    ClientParseError,
+    ErrorModel,
+    ZoneModel,
+    BulkCreateRecords,
+    BulkUpdateRecords,
+    BaseRecordModel,
+    RecordModel,
+    PrimaryServerModel,
+    PaginatedZones,
+    PaginatedData,
+    ZoneValidation
+};

index.ts

@@ -0,0 +1,77 @@
+import HetznerDnsClient from "./HetznerDnsClient.js";
+import {Response, RequestInit} from "node-fetch";
+import ErrorModel from "./models/ErrorModel.js";
+
+/**
+ * API response object
+ * @class
+ * @template T - Response data model
+ */
+export default class ApiResponse<T extends ErrorModel> {
+
+    /**
+     * Fetch response
+     * @type {Response}
+     * @readonly
+     */
+    public readonly response: Response;
+
+    /**
+     * Raw response body
+     * @type {ArrayBuffer}
+     * @readonly
+     */
+    public readonly raw: ArrayBuffer;
+
+    /**
+     * Request options
+     * @type {RequestInit}
+     * @readonly
+     */
+    public readonly options: RequestInit;
+
+    /**
+     * API client instance used to make the request
+     * @type {HetznerDnsClient}
+     * @readonly
+     */
+    public readonly client: HetznerDnsClient;
+
+    /**
+     * Create a new API response object
+     * @param {Response} response - Fetch response
+     * @param {ArrayBuffer} raw - Raw response body
+     * @param {RequestInit} options - Request options
+     * @param {HetznerDnsClient} client - API client instance used to make the request
+     * @internal
+     */
+    public constructor(response: Response, raw: ArrayBuffer, options: RequestInit, client: HetznerDnsClient) {
+        this.response = response;
+        this.raw = raw;
+        this.options = options;
+        this.client = client;
+    }
+
+    /**
+     * Get response body as string
+     * @type {string}
+     * @readonly
+     */
+    public get body(): string {
+        return Buffer.from(this.raw).toString();
+    }
+
+    /**
+     * Get parsed response body (if JSON). `null` if not JSON or parsing fails.
+     * @type {T | null}
+     * @readonly
+     */
+    public get json(): T | null {
+        try {
+            return JSON.parse(this.body) as T;
+        }
+        catch (e) {
+            return null;
+        }
+    }
+}

lib/ApiResponse.ts

@@ -0,0 +1,31 @@
+import ClientObject from "./ClientObject.js";
+import BulkCreateRecords from "./models/BulkCreateRecords";
+import DnsRecord from "./DnsRecord.js";
+
+/**
+ * Response from bulk creating records
+ * @class
+ * @extends {ClientObject<BulkCreateRecords>}
+ */
+export default class BulkCreateRecordsPretty extends ClientObject<BulkCreateRecords> {
+    /**
+     * Invalid records
+     * @type {BaseRecordModel[]}
+     * @readonly
+     */
+    public readonly invalidRecords = this._data.invalid_records;
+
+    /**
+     * Records that were created
+     * @type {Record[]}
+     * @readonly
+     */
+    public readonly records = this._data.records.map(record => new DnsRecord(this.client, record));
+
+    /**
+     * Valid records
+     * @type {BaseRecordModel[]}
+     * @readonly
+     */
+    public readonly validRecords = this._data.valid_records;
+}

lib/BulkCreateRecordsPretty.ts

@@ -0,0 +1,24 @@
+import ClientObject from "./ClientObject.js";
+import DnsRecord from "./DnsRecord.js";
+import BulkUpdateRecords from "./models/BulkUpdateRecords";
+
+/**
+ * Response from bulk updating records
+ * @class
+ * @extends {ClientObject<BulkCreateRecords>}
+ */
+export default class BulkUpdateRecordsPretty extends ClientObject<BulkUpdateRecords> {
+    /**
+     * Failed records
+     * @type {BaseRecordModel[]}
+     * @readonly
+     */
+    public readonly failedRecords = this._data.failed_records;
+
+    /**
+     * Records that were updated
+     * @type {Record[]}
+     * @readonly
+     */
+    public readonly records = this._data.records.map(record => new DnsRecord(this.client, record));
+}

lib/BulkUpdateRecordsPretty.ts

@@ -0,0 +1,53 @@
+import HetznerDnsClient from "./HetznerDnsClient.js";
+
+/**
+ * Client object
+ * @class
+ * @template T - Raw data model
+ */
+export default class ClientObject<T> {
+    /**
+     * API client instance
+     * @type {HetznerDnsClient}
+     * @readonly
+     * @private
+     */
+    readonly #client: HetznerDnsClient;
+
+    /**
+     * API client instance
+     * @type {HetznerDnsClient}
+     * @readonly
+     */
+    public get client(): HetznerDnsClient {
+        return this.#client;
+    }
+
+    /**
+     * Raw data
+     * @type {T}
+     * @readonly
+     * @private
+     */
+    readonly #data: T;
+
+    /**
+     * Raw data
+     * @type {T}
+     * @readonly
+     */
+    public get _data(): T {
+        return this.#data;
+    }
+
+    /**
+     * Constructor
+     * @param {HetznerDnsClient} client - API client instance
+     * @param {T} data - Raw data
+     * @internal
+     */
+    public constructor(client: HetznerDnsClient, data: T) {
+        this.#client = client;
+        this.#data = data;
+    }
+}