From 57311501579bd91721b178609437de7a0186dcc4 Mon Sep 17 00:00:00 2001 From: Philipp Kunz Date: Sat, 15 Jun 2024 19:55:48 +0200 Subject: [PATCH] update readme --- LICENSE | 21 ---- npmextra.json | 16 ++- package.json | 16 ++- readme.hints.md | 1 + readme.md | 264 ++++++++++++++++++++++++++++++++++++++++++------ tsconfig.json | 11 +- 6 files changed, 265 insertions(+), 64 deletions(-) delete mode 100644 LICENSE create mode 100644 readme.hints.md diff --git a/LICENSE b/LICENSE deleted file mode 100644 index eb3beb5..0000000 --- a/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -The MIT License (MIT) - -Copyright (c) 2016 Lossless GmbH - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/npmextra.json b/npmextra.json index 0945667..43d9784 100644 --- a/npmextra.json +++ b/npmextra.json @@ -9,9 +9,21 @@ "githost": "gitlab.com", "gitscope": "mojoio", "gitrepo": "cloudflare", - "description": "easy cloudflare management", + "description": "A TypeScript client for managing Cloudflare accounts, zones, DNS records, and workers with ease.", "npmPackagename": "@apiclient.xyz/cloudflare", - "license": "MIT" + "license": "MIT", + "keywords": [ + "Cloudflare", + "DNS management", + "zone management", + "worker management", + "TypeScript", + "API client", + "cloud infrastructure", + "automated DNS", + "CDN management", + "open source" + ] } } } \ No newline at end of file diff --git a/package.json b/package.json index 5e8fec4..215ca97 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@apiclient.xyz/cloudflare", "version": "6.0.4", "private": false, - "description": "easy cloudflare management", + "description": "A TypeScript client for managing Cloudflare accounts, zones, DNS records, and workers with ease.", "main": "dist_ts/index.js", "typings": "dist_ts/index.d.ts", "type": "module", @@ -17,8 +17,16 @@ "url": "git+https://gitlab.com/pushrocks/cflare.git" }, "keywords": [ - "Push.Rocks", - "cloudflare" + "Cloudflare", + "DNS management", + "zone management", + "worker management", + "TypeScript", + "API client", + "cloud infrastructure", + "automated DNS", + "CDN management", + "open source" ], "author": "Lossless GmbH", "license": "MIT", @@ -59,4 +67,4 @@ "browserslist": [ "last 1 chrome versions" ] -} +} \ No newline at end of file diff --git a/readme.hints.md b/readme.hints.md new file mode 100644 index 0000000..bb3ec6a --- /dev/null +++ b/readme.hints.md @@ -0,0 +1 @@ +- unofficial TypeScript cloudflare api client coming with a lot of convenience. \ No newline at end of file diff --git a/readme.md b/readme.md index 82033c3..a3e081d 100644 --- a/readme.md +++ b/readme.md @@ -1,52 +1,250 @@ # @apiclient.xyz/cloudflare easy cloudflare management -## Availabililty and Links -* [npmjs.org (npm package)](https://www.npmjs.com/package/@apiclient.xyz/cloudflare) -* [gitlab.com (source)](https://gitlab.com/mojoio/cloudflare) -* [github.com (source mirror)](https://github.com/mojoio/cloudflare) -* [docs (typedoc)](https://mojoio.gitlab.io/cloudflare/) +## Install +To install the `@apiclient.xyz/cloudflare` package, you can use npm. Simply run the following command: -## Status for master +```bash +npm install @apiclient.xyz/cloudflare +``` -Status Category | Status Badge --- | -- -GitLab Pipelines | [![pipeline status](https://gitlab.com/mojoio/cloudflare/badges/master/pipeline.svg)](https://lossless.cloud) -GitLab Pipline Test Coverage | [![coverage report](https://gitlab.com/mojoio/cloudflare/badges/master/coverage.svg)](https://lossless.cloud) -npm | [![npm downloads per month](https://badgen.net/npm/dy/@apiclient.xyz/cloudflare)](https://lossless.cloud) -Snyk | [![Known Vulnerabilities](https://badgen.net/snyk/mojoio/cloudflare)](https://lossless.cloud) -TypeScript Support | [![TypeScript](https://badgen.net/badge/TypeScript/>=%203.x/blue?icon=typescript)](https://lossless.cloud) -node Support | [![node](https://img.shields.io/badge/node->=%2010.x.x-blue.svg)](https://nodejs.org/dist/latest-v10.x/docs/api/) -Code Style | [![Code Style](https://badgen.net/badge/style/prettier/purple)](https://lossless.cloud) -PackagePhobia (total standalone install weight) | [![PackagePhobia](https://badgen.net/packagephobia/install/@apiclient.xyz/cloudflare)](https://lossless.cloud) -PackagePhobia (package size on registry) | [![PackagePhobia](https://badgen.net/packagephobia/publish/@apiclient.xyz/cloudflare)](https://lossless.cloud) -BundlePhobia (total size when bundled) | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@apiclient.xyz/cloudflare)](https://lossless.cloud) -Platform support | [![Supports Windows 10](https://badgen.net/badge/supports%20Windows%2010/yes/green?icon=windows)](https://lossless.cloud) [![Supports Mac OS X](https://badgen.net/badge/supports%20Mac%20OS%20X/yes/green?icon=apple)](https://lossless.cloud) +Make sure to include it in your `dependencies` in `package.json`. ## Usage -Use TypeScript for best in class instellisense. +### Initial Setup -```javascript +First, let's start by importing the required modules and setting up an instance of `CloudflareAccount` with your API token. This instance will be used to interact with the Cloudflare API. + +```typescript import * as cflare from '@apiclient.xyz/cloudflare'; -const myCflareAccount = new cflare.CflareAccount('mySuperAwesomeAccountToken'); +// Initialize Cloudflare Account +const myCflareAccount = new cflare.CloudflareAccount('mySuperAwesomeAccountToken'); +``` -const myAsyncCflareManagement = async () => { - // get things - const myZones = await myCflareAccount.listZones(); // zones are fully typed - const myIdForADomain = await myCflareAccount.getZoneId('example.com'); // type number - const myRecordsForADomain = await myCflareAccount.listRecords('example.com'); // records are fully typed +### Managing Zones + +#### List All Zones + +To list all zones in your Cloudflare account, you can use the `listZones` method: + +```typescript +const listAllZones = async () => { + const myZones = await myCflareAccount.convenience.listZones(); + console.log(myZones); }; ``` -## Contribution +#### Get Zone ID -We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :) +To get the ID of a specific zone (domain), use the `getZoneId` method: -For further information read the linked docs at the top of this readme. +```typescript +const getZoneId = async (domainName: string) => { + try { + const zoneId = await myCflareAccount.convenience.getZoneId(domainName); + console.log(`Zone ID for ${domainName}:`, zoneId); + } catch (error) { + console.error('Error getting zone ID:', error); + } +}; +``` -> MIT licensed | **©** [Lossless GmbH](https://lossless.gmbh) -| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy) +#### Purge Cache for a Zone -[![repo-footer](https://lossless.gitlab.io/publicrelations/repofooter.svg)](https://maintainedby.lossless.com) +To purge all cache for a specific zone: + +```typescript +const purgeZoneCache = async (domainName: string) => { + await myCflareAccount.convenience.purgeZone(domainName); + console.log(`Purged cache for ${domainName}`); +}; +``` + +### Managing DNS Records + +#### List DNS Records + +To list all DNS records for a specific zone: + +```typescript +const listDnsRecords = async (domainName: string) => { + try { + const records = await myCflareAccount.convenience.listRecords(domainName); + console.log(`DNS Records for ${domainName}:`, records); + } catch (error) { + console.error('Error listing DNS records:', error); + } +}; +``` + +#### Get a Specific Record + +To get a specific DNS record by type (e.g., A, AAAA, CNAME, etc.): + +```typescript +const getDnsRecord = async (domainName: string, recordType: string) => { + try { + const record = await myCflareAccount.convenience.getRecord(domainName, recordType); + console.log(`DNS Record (${recordType}) for ${domainName}:`, record); + } catch (error) { + console.error('Error getting DNS record:', error); + } +}; +``` + +#### Create a DNS Record + +To create a new DNS record: + +```typescript +const createDnsRecord = async (domainName: string, recordType: string, content: string) => { + try { + const response = await myCflareAccount.convenience.createRecord(domainName, recordType, content, 120); + console.log(`Created DNS record (${recordType}) for ${domainName}:`, response); + } catch (error) { + console.error('Error creating DNS record:', error); + } +}; +``` + +#### Remove a DNS Record + +To remove a DNS record: + +```typescript +const removeDnsRecord = async (domainName: string, recordType: string) => { + try { + await myCflareAccount.convenience.removeRecord(domainName, recordType); + console.log(`Removed DNS record (${recordType}) for ${domainName}`); + } catch (error) { + console.error('Error removing DNS record:', error); + } +}; +``` + +#### Clean a DNS Record + +To clean (remove) all records of a specific type for a domain: + +```typescript +const cleanDnsRecord = async (domainName: string, recordType: string) => { + try { + await myCflareAccount.convenience.cleanRecord(domainName, recordType); + console.log(`Cleaned DNS records (${recordType}) for ${domainName}`); + } catch (error) { + console.error('Error cleaning DNS record:', error); + } +}; +``` + +### Managing Workers + +#### Create a Worker + +To create a new Cloudflare Worker: + +```typescript +const createWorker = async (workerName: string, workerScript: string) => { + try { + const worker = await myCflareAccount.workerManager.createWorker(workerName, workerScript); + console.log(`Created Worker (${workerName}):`, worker); + } catch (error) { + console.error('Error creating Worker:', error); + } +}; +``` + +#### List Workers + +To list all workers in your Cloudflare account: + +```typescript +const listWorkers = async () => { + try { + const workers = await myCflareAccount.workerManager.listWorkers(); + console.log('Workers:', workers); + } catch (error) { + console.error('Error listing workers:', error); + } +}; +``` + +#### Set Worker Routes + +To set routes for a Cloudflare Worker: + +```typescript +import { CloudflareWorker } from '@apiclient.xyz/cloudflare'; + +const setWorkerRoutes = async (worker: CloudflareWorker, routes: Array<{ zoneName: string, pattern: string }>) => { + try { + await worker.setRoutes(routes); + console.log('Routes set successfully for Worker:', worker.id); + } catch (error) { + console.error('Error setting routes for Worker:', error); + } +}; +``` + +#### Sample Complete Workflow + +Below is a sample workflow that includes all the above features: + +```typescript +import * as cflare from '@apiclient.xyz/cloudflare'; + +const myCflareAccount = new cflare.CloudflareAccount('mySuperAwesomeAccountToken'); + +const manageCloudflare = async () => { + try { + // List all zones + const myZones = await myCflareAccount.convenience.listZones(); + console.log('Zones:', myZones); + + // Get Zone ID for a specific domain + const myZoneId = await myCflareAccount.convenience.getZoneId('example.com'); + console.log('Zone ID:', myZoneId); + + // Purge cache for a zone + await myCflareAccount.convenience.purgeZone('example.com'); + console.log('Cache purged for example.com'); + + // List DNS records for a domain + const myRecords = await myCflareAccount.convenience.listRecords('example.com'); + console.log('DNS Records:', myRecords); + + // Get a specific DNS record + const myRecord = await myCflareAccount.convenience.getRecord('sub.example.com', 'A'); + console.log('Specific DNS Record:', myRecord); + + // Create a DNS record + const createResponse = await myCflareAccount.convenience.createRecord('sub.example.com', 'A', '127.0.0.1'); + console.log('Created DNS Record:', createResponse); + + // Clean DNS records + await myCflareAccount.convenience.cleanRecord('sub.example.com', 'A'); + console.log('Cleaned DNS Records for sub.example.com'); + + // Create a Cloudflare Worker + const myWorker = await myCflareAccount.workerManager.createWorker('myWorker', `addEventListener('fetch', event => { event.respondWith(fetch(event.request)) })`); + console.log('Created Worker:', myWorker); + + // Set routes for the Worker + await myWorker.setRoutes([{ zoneName: 'example.com', pattern: 'https://*example.com/*' }]); + console.log('Routes set for Worker'); + + // List all Workers + const workers = await myCflareAccount.workerManager.listWorkers(); + console.log('Workers:', workers); + } catch (error) { + console.error('Error managing Cloudflare:', error); + } +}; + +manageCloudflare(); +``` + +This complete guide covers initialization, managing Cloudflare zones, DNS records, and Cloudflare Workers comprehensively using TypeScript for enhanced type safety and intellisense. Always ensure to keep your API keys secure and avoid hardcoding them directly in your scripts. +undefined \ No newline at end of file diff --git a/tsconfig.json b/tsconfig.json index f5fa78c..dfe5a55 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -3,9 +3,12 @@ "experimentalDecorators": true, "useDefineForClassFields": false, "target": "ES2022", - "module": "ES2022", - "moduleResolution": "nodenext", + "module": "NodeNext", + "moduleResolution": "NodeNext", "esModuleInterop": true, - "verbatimModuleSyntax": true, - } + "verbatimModuleSyntax": true + }, + "exclude": [ + "dist_*/**/*.d.ts" + ] }