update readme

This commit is contained in:
Philipp Kunz 2024-06-15 19:55:48 +02:00
parent f39f8cd33c
commit 5731150157
6 changed files with 265 additions and 64 deletions

21
LICENSE
View File

@ -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.

View File

@ -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"
]
}
}
}

View File

@ -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",

1
readme.hints.md Normal file
View File

@ -0,0 +1 @@
- unofficial TypeScript cloudflare api client coming with a lot of convenience.

264
readme.md
View File

@ -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

View File

@ -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"
]
}