24fire-api 1.0.8 β†’ 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/LICENSE +201 -201
  2. package/README.md +146 -110
  3. package/package.json +33 -24
  4. package/src/index.d.ts +135 -0
  5. package/src/index.js +290 -207
package/README.md CHANGED
@@ -3,181 +3,217 @@
3
3
 
4
4
  # 24fire-api
5
5
 
6
+ Ein einfacher Node.js-Wrapper fΓΌr die **24fire REST-API v2**.
7
+ Verwalte deinen Account, KVM-Server, Domains und Webspaces direkt aus deinem Code.
6
8
 
7
- Die 24fire-api soll die Interaktion mit der 24fire Kunden Api vereinfachen und verbessern.
9
+ ## Features
8
10
 
11
+ - πŸ”— Kommunikation ΓΌber SSL (`https://manage.24fire.de/api`)
12
+ - πŸ“¦ **Keine AbhΓ€ngigkeiten** nutzt das eingebaute `fetch` von Node.js
13
+ - 🧩 Intuitive, verschachtelte Bedienung (`fire.kvm(id).backup.list()`)
14
+ - 🟦 Mitgelieferte TypeScript-Typen
15
+ - ⚑ Schnell & leichtgewichtig
9
16
 
10
- ## Features
17
+ > **Hinweis:** Dies ist Version **2.0**. Die API-Struktur hat sich gegenΓΌber v1 komplett geΓ€ndert
18
+ > (neue Base-URL, neuer Auth-Header, `internal_id` pro Dienst). Siehe [Migration von v1](#migration-von-v1).
11
19
 
12
- - πŸ”— Kommunikation ΓΌber SSL
13
- - πŸƒ Schnelle interaktion
14
- - ➑️ Direkte Anfragen ohne Middelware
15
- - ℹ️ Einfache Bedienung
16
- - πŸ†• Neuste Version
20
+ ## Voraussetzungen
17
21
 
22
+ - Node.js **18 oder neuer** (wegen des globalen `fetch`)
18
23
 
19
- ## Optimierungen & Feedback
24
+ ## Installation
20
25
 
21
- Welche Optimierungen hast du in deinem Code vorgenommen? Z.B. Refactoring, Performance-Verbesserungen
26
+ ```bash
27
+ npm install 24fire-api
28
+ ```
22
29
 
23
- Wenn du Feedback hast, wenden dich an mich unter support@flostechnikwelt.de
30
+ ## API-Key erstellen
24
31
 
25
- ## Author & Credits
26
- - Flostechnikwelt
27
- - Lars.1309
28
- ## Empfehlenswert
32
+ 1. Logge dich im [24fire Control Panel](https://manage.24fire.de) ein.
33
+ 2. Gehe zu **Einstellungen β†’ API-Keys** und klicke auf β€žAPI-Key erstellenβ€œ.
34
+ 3. Speichere den Key sicher ab – er wird nur **einmal** angezeigt.
29
35
 
30
- - [Offizielle API Dokumentation](https://documenter.getpostman.com/view/18955936/2s93zB6hJu)
31
- - [24fire](https://24fire.de/)
32
- - [Discord](https://discord.gg/24fire)
36
+ ## Schnellstart
33
37
 
38
+ ```javascript
39
+ const FireAPI = require('24fire-api');
40
+ // oder: import FireAPI from '24fire-api';
34
41
 
35
- ## Wie wird es installiert?
42
+ const fire = new FireAPI('DEIN_API_KEY');
36
43
 
37
- Um die 24fire-api in deinem Projekt zu installieren, fΓΌhre bitte den folgenden Befehl aus
44
+ // Account-Infos abrufen
45
+ const account = await fire.account.info();
46
+ console.log(account.data);
38
47
 
39
- ```bash
40
- npm install 24fire-api
48
+ // Alle Dienste anzeigen (hier findest du die internal_id jedes Dienstes)
49
+ const services = await fire.account.services();
50
+ console.log(services.data);
51
+
52
+ // Einen Server starten
53
+ await fire.kvm('INTERNAL_ID').start();
41
54
  ```
42
55
 
56
+ Jede Methode gibt die API-Antwort im Format `{ status, message, data }` zurΓΌck.
57
+ Bei Fehlern wird ein `FireAPIError` geworfen (siehe [Fehlerbehandlung](#fehlerbehandlung)).
58
+
59
+ ---
43
60
 
44
- ## Wie bekomme ich einen API Key?
61
+ ## Account
45
62
 
46
- Jeder Kunde hat die mΓΆglichkeit fΓΌr seine VM einen API-Key zu bekommen.
47
- #### 1. WΓ€hle deinen Server aus
48
- ![Bild1](https://i.imgur.com/F5k2Z2s.png)
49
- #### 2. Γ–ffne das Menu durch den Buttn mit den drei Strichen
50
- ![Bild2](https://i.imgur.com/YPkNMX7.png)
51
- #### 3. Klicke auf "API-Key anzeigen"
52
- ![Bild3](https://i.imgur.com/Qq95Ojo.png)
53
- #### 4. Nun sollte dieses Modal erscheinen, hier kannst du den API-Key kopieren
54
- ![Bild4](https://i.imgur.com/s2llq6W.png)## Wie verwende ich fireapi-24fire?
63
+ ```javascript
64
+ await fire.account.info(); // Account-Informationen (Name, E-Mail, Guthaben …)
65
+ await fire.account.services(); // Übersicht aller aktiven Dienste (mit internal_id)
66
+ await fire.account.donations(); // Daten zur Spendenseite
67
+ await fire.account.affiliate(); // Daten zum Affiliate-System
68
+ ```
55
69
 
70
+ ## KVM-Server
56
71
 
57
- ### Einen fireApi Client erstellen
72
+ Zuerst einen Server ΓΌber seine `internal_id` auswΓ€hlen:
58
73
 
59
74
  ```javascript
60
- const fireApi = require("24fire-api")
61
- const apiKey = 'DEIN_API_SCHLÜSSEL';
62
- const myFireApi = new fireApi(apiKey);
75
+ const vm = fire.kvm('INTERNAL_ID');
63
76
  ```
64
77
 
78
+ ### Allgemein
65
79
 
80
+ ```javascript
81
+ await vm.config(); // Konfiguration (Hardware, IPs, OS …)
82
+ await vm.status(); // Status & Auslastung (running / stopped / …)
66
83
 
67
- ### VM
84
+ await vm.power('start'); // Power-Aktion: 'start' | 'stop' | 'restart'
85
+ await vm.start(); // Kurzform fΓΌr power('start')
86
+ await vm.stop(); // Kurzform fΓΌr power('stop')
87
+ await vm.restart(); // Kurzform fΓΌr power('restart')
88
+ ```
68
89
 
69
- #### -> Zeige die VM Konfiguration an
90
+ ### Backups
70
91
 
71
92
  ```javascript
72
- myFireApi.vm().getVMconfig().then(data => {
73
- console.log('VM config:', data);
74
- }).catch(error => {
75
- console.error('Fehler:', error);
76
- });
93
+ await vm.backup.list(); // Alle Backups auflisten
94
+ await vm.backup.create('Notiz'); // Backup erstellen (24fire+), Notiz optional, max. 24 Zeichen
95
+ await vm.backup.createStatus('BACKUP_ID'); // Status der Erstellung abfragen
96
+ await vm.backup.restore('BACKUP_ID'); // Backup wiederherstellen (24fire+)
97
+ await vm.backup.restoreStatus('BACKUP_ID'); // Status der Wiederherstellung abfragen
98
+ await vm.backup.delete('BACKUP_ID'); // Backup lΓΆschen
77
99
  ```
78
100
 
79
- #### -> Den aktuellen VM Status Abrufen
101
+ ### Traffic
80
102
 
81
103
  ```javascript
82
- myFireApi.vm().getVMstatus().then(data => {
83
- console.log('Aktueller VM Status:', data);
84
- }).catch(error => {
85
- console.error('Fehler:', error);
86
- });
104
+ await vm.traffic.current(); // Aktueller Traffic-Verbrauch des Monats
105
+ await vm.traffic.log(); // Traffic-Log (Messung alle 10 Minuten)
106
+
107
+ // Traffic-Diagramm generieren (24fire+)
108
+ await vm.traffic.chart({
109
+ type: 'both', // Eingehend / Ausgehend / Beides
110
+ summary: 'DAILY', // DAILY | HOURLY | NONE
111
+ output: 'apexcharts', // chartjs | apexcharts | base64
112
+ datapoints: 30,
113
+ size: '900x300',
114
+ });
87
115
  ```
88
116
 
89
- #### -> Die VM Starten
117
+ ### Monitoring
90
118
 
91
119
  ```javascript
92
- myFireApi.vm().startVM().then(data => {
93
- console.log('Antwort: ', data);
94
- }).catch(error => {
95
- console.error('Fehler: ', error);
96
- });
120
+ await vm.monitoring.timings(); // Messungen abrufen
121
+ await vm.monitoring.incidences(); // AusfΓ€lle abrufen
97
122
  ```
98
123
 
99
- #### -> Die VM herunterfahren
124
+ ### DDoS (24fire+)
100
125
 
101
126
  ```javascript
102
- myFireApi.vm().stopVM().then(data => {
103
- console.log('Antwort: ', data);
104
- }).catch(error => {
105
- console.error('Fehler: ', error);
106
- });
127
+ await vm.ddos.get(); // Aktuelle DDoS-Einstellungen abrufen
128
+ await vm.ddos.change({
129
+ layer4: 'permanent',
130
+ layer7: 'on',
131
+ ip_address: '88.151.194.253', // optional; ohne Angabe gilt es fΓΌr alle IPv4 der VM
132
+ });
107
133
  ```
108
134
 
109
-
110
- #### -> Die VM neustarten
135
+ ## Domains
111
136
 
112
137
  ```javascript
113
- myFireApi.vm().restartVM().then(data => {
114
- console.log('Antwort:', data);
115
- }).catch(error => {
116
- console.error('Fehler:', error);
117
- });
118
- ```
138
+ const domain = fire.domain('INTERNAL_ID');
119
139
 
120
- ### Backup
140
+ await domain.info(); // Domain-Informationen
141
+ await domain.dns.list(); // Alle DNS-EintrΓ€ge
121
142
 
122
- #### -> Alle Backups auflisten
143
+ // DNS-Eintrag hinzufΓΌgen (24fire+)
144
+ await domain.dns.add({ type: 'A', name: '*', data: '1.2.3.4' });
123
145
 
124
- ```javascript
125
- myFireApi.backup().listBackups().then(data => {
126
- console.log('Backup List:', data);
127
- }).catch(error => {
128
- console.error('Fehler:', error);
129
- });
146
+ // DNS-Eintrag bearbeiten (24fire+)
147
+ await domain.dns.edit({ record_id: 'RECORD_ID', data: '5.6.7.8' });
148
+
149
+ // DNS-Eintrag entfernen
150
+ await domain.dns.remove('RECORD_ID');
130
151
  ```
131
152
 
132
- #### -> Ein neues Backup erstellen
153
+ ## Webspace
133
154
 
134
155
  ```javascript
135
- myFireApi.backup().createBackup(description).then(data => {
136
- console.log('Antwort:', data);
137
- }).catch(error => {
138
- console.error('Fehler:', error);
139
- });
156
+ await fire.webspace('INTERNAL_ID').info(); // Webspace-Daten abrufen
140
157
  ```
141
- | Parameter | Type | Description |
142
- | :-------- | :------- | :-------------------------------- |
143
- | `description` | `string` | **Optional**. Es kann optional ein Beschreibung hinzugefΓΌgt werden. |
144
158
 
159
+ ---
160
+
161
+ ## Fehlerbehandlung
145
162
 
146
- #### -> Ein Backup LΓΆschen
163
+ SchlΓ€gt eine Anfrage fehl (HTTP-Fehler oder `status: "error"`), wird ein `FireAPIError` geworfen:
147
164
 
148
165
  ```javascript
149
- myFireApi.backup().deleteBackup(backupId).then(data => {
150
- console.log('Antwort: ', data);
151
- }).catch(error => {
152
- console.error('Fehler: ', error);
153
- });
166
+ const { FireAPIError } = require('24fire-api');
167
+
168
+ try {
169
+ await fire.kvm('INTERNAL_ID').start();
170
+ } catch (err) {
171
+ if (err instanceof FireAPIError) {
172
+ console.error('API-Fehler:', err.message);
173
+ console.error('HTTP-Status:', err.status);
174
+ console.error('Antwort:', err.response);
175
+ }
176
+ }
154
177
  ```
155
178
 
156
- | Parameter | Type | Description |
157
- | :-------- | :------- | :-------------------------------- |
158
- | `backupId` | `string` | **BenΓΆtigt**. Die ID vom Backup welches gelΓΆscht werden soll. |
179
+ ## Migration von v1
159
180
 
181
+ | | v1 (alt) | v2 (neu) |
182
+ |---|---|---|
183
+ | Base-URL | `https://api.24fire.de` | `https://manage.24fire.de/api` |
184
+ | Auth-Header | `X-FIRE-APIKEY` | `X-Fire-Apikey` |
185
+ | Server-Auswahl | global ΓΌber den Key | pro Dienst ΓΌber die `internal_id` |
186
+ | AbhΓ€ngigkeiten | `axios` | keine (eingebautes `fetch`) |
160
187
 
161
- ### Monitoring
162
-
163
- #### -> Alle Messungen vom Server Abrufen
188
+ **Beispiel:**
164
189
 
165
190
  ```javascript
166
- myFireApi.monitoring().getStats().then(data => {
167
- console.log('Alle Messungen:', data);
168
- }).catch(error => {
169
- console.error('Fehler:', error);
170
- });
191
+ // v1
192
+ myFireApi.vm().getVMstatus();
193
+ myFireApi.vm().startVM();
194
+ myFireApi.backup().listBackups();
195
+
196
+ // v2
197
+ fire.kvm('INTERNAL_ID').status();
198
+ fire.kvm('INTERNAL_ID').start();
199
+ fire.kvm('INTERNAL_ID').backup.list();
171
200
  ```
172
201
 
173
- #### -> Alle AusfΓ€lle abrufen
202
+ > Manche Endpunkte (z. B. DNS-Verwaltung, Backups erstellen/wiederherstellen, DDoS, Traffic-Chart)
203
+ > erfordern ein aktives **24fire+** Abonnement.
174
204
 
175
- ```javascript
176
- myFireApi.monitoring().retieceOutages().then(data => {
177
- console.log('Antwort:', data);
178
- }).catch(error => {
179
- console.error('Fehler:', error);
180
- });
181
- ```
205
+ ## Author & Credits
206
+
207
+ - Florian Linde <florian.linde@flostechnikwelt.de> (FlosTechnikwelt)
208
+
209
+ ## Empfehlenswert
210
+
211
+ - [Offizielle API-Dokumentation (v2)](https://apidocs.24fire.de/v2)
212
+ - [24fire](https://24fire.de/)
213
+ - [Discord](https://discord.gg/24fire)
214
+
215
+ ## Feedback
216
+
217
+ Wenn du Feedback hast, wende dich an mich unter support@flostechnikwelt.de
182
218
 
183
219
 
package/package.json CHANGED
@@ -1,24 +1,33 @@
1
- {
2
- "name": "24fire-api",
3
- "version": "1.0.8",
4
- "description": "Nutze die 24fire api in Nodejs, sicher und schnell",
5
- "main": "src/index.js",
6
- "repository": {
7
- "type": "git",
8
- "url": "git+https://github.com/FlosTechnikwelt/24fire-api.git"
9
- },
10
- "homepage": "https://github.com/FlosTechnikwelt/24fire-api.git",
11
- "keywords": [
12
- "24fire",
13
- "24fireAPI",
14
- "api",
15
- "Hosting",
16
- "wrapper",
17
- "flostechnikwelt"
18
- ],
19
- "author": "FlosTechnikwelt",
20
- "license": "Apache-2.0",
21
- "dependencies": {
22
- "axios": "^1.6.4"
23
- }
24
- }
1
+ {
2
+ "name": "24fire-api",
3
+ "version": "2.0.0",
4
+ "description": "Einfacher, abhΓ€ngigkeitsfreier Node.js-Wrapper fΓΌr die 24fire REST-API v2",
5
+ "main": "src/index.js",
6
+ "types": "src/index.d.ts",
7
+ "files": [
8
+ "src/index.js",
9
+ "src/index.d.ts"
10
+ ],
11
+ "engines": {
12
+ "node": ">=18"
13
+ },
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/FlosTechnikwelt/24fire-api.git"
17
+ },
18
+ "homepage": "https://github.com/FlosTechnikwelt/24fire-api.git",
19
+ "keywords": [
20
+ "24fire",
21
+ "24fireAPI",
22
+ "fireapi",
23
+ "api",
24
+ "v2",
25
+ "Hosting",
26
+ "kvm",
27
+ "wrapper",
28
+ "flostechnikwelt"
29
+ ],
30
+ "author": "Florian Linde <florian.linde@flostechnikwelt.de>",
31
+ "license": "Apache-2.0",
32
+ "dependencies": {}
33
+ }
package/src/index.d.ts ADDED
@@ -0,0 +1,135 @@
1
+ //β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ•—
2
+ //β–ˆβ–ˆβ•”β•β•β•β•β•β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β•β•β•β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•‘
3
+ //β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•‘
4
+ //β–ˆβ–ˆβ•”β•β•β• β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β• β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β•β•β•β• β–ˆβ–ˆβ•‘
5
+ //β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘
6
+ //β•šβ•β• β•šβ•β•β•šβ•β• β•šβ•β•β•šβ•β•β•β•β•β•β•β•šβ•β• β•šβ•β•β•šβ•β• β•šβ•β•
7
+ // TypeScript-Definitionen fΓΌr 24fire-api v2
8
+ // Doku: https://apidocs.24fire.de/v2
9
+ // Made by FlosTechnikwelt <florian.linde@flostechnikwelt.de>
10
+ // https://apidocs.24fire.de/v2
11
+
12
+ /** Standard-Antwortformat der 24fire REST-API */
13
+ export interface FireResponse<T = unknown> {
14
+ status: 'success' | 'error';
15
+ message: string;
16
+ data: T;
17
+ }
18
+
19
+ /** Fehler, der bei einer fehlgeschlagenen Anfrage geworfen wird */
20
+ export class FireAPIError extends Error {
21
+ name: 'FireAPIError';
22
+ /** HTTP-Statuscode */
23
+ status?: number;
24
+ /** Rohe API-Antwort */
25
+ response?: unknown;
26
+ }
27
+
28
+ export interface FireAPIOptions {
29
+ /** Abweichende Base-URL (Standard: https://manage.24fire.de/api) */
30
+ baseUrl?: string;
31
+ }
32
+
33
+ /** Power-Aktionen fΓΌr einen KVM-Server */
34
+ export type PowerMode = 'start' | 'stop' | 'restart' | (string & {});
35
+
36
+ export interface DnsRecordInput {
37
+ type: string;
38
+ name: string;
39
+ data: string;
40
+ }
41
+
42
+ export interface DnsEditInput {
43
+ record_id: string;
44
+ type?: string;
45
+ name?: string;
46
+ data?: string;
47
+ }
48
+
49
+ export interface TrafficChartOptions {
50
+ type?: string;
51
+ summary?: string;
52
+ output?: string;
53
+ dataset_in_label?: string;
54
+ dataset_out_label?: string;
55
+ dataset_in_color?: string;
56
+ dataset_out_color?: string;
57
+ axes_y_label?: string;
58
+ datapoints?: number;
59
+ size?: string;
60
+ [key: string]: unknown;
61
+ }
62
+
63
+ export interface DdosChangeOptions {
64
+ layer4?: string;
65
+ layer7?: string;
66
+ ip_address?: string;
67
+ [key: string]: unknown;
68
+ }
69
+
70
+ export interface KVM {
71
+ config(): Promise<FireResponse>;
72
+ status(): Promise<FireResponse>;
73
+ power(mode: PowerMode): Promise<FireResponse>;
74
+ start(): Promise<FireResponse>;
75
+ stop(): Promise<FireResponse>;
76
+ restart(): Promise<FireResponse>;
77
+ backup: {
78
+ list(): Promise<FireResponse>;
79
+ create(description?: string): Promise<FireResponse>;
80
+ createStatus(backupId: string): Promise<FireResponse>;
81
+ restore(backupId: string): Promise<FireResponse>;
82
+ restoreStatus(backupId: string): Promise<FireResponse>;
83
+ delete(backupId: string): Promise<FireResponse>;
84
+ };
85
+ traffic: {
86
+ current(): Promise<FireResponse>;
87
+ log(): Promise<FireResponse>;
88
+ chart(opts?: TrafficChartOptions): Promise<FireResponse>;
89
+ };
90
+ monitoring: {
91
+ timings(): Promise<FireResponse>;
92
+ incidences(): Promise<FireResponse>;
93
+ };
94
+ ddos: {
95
+ get(): Promise<FireResponse>;
96
+ change(opts?: DdosChangeOptions): Promise<FireResponse>;
97
+ };
98
+ }
99
+
100
+ export interface Domain {
101
+ info(): Promise<FireResponse>;
102
+ dns: {
103
+ list(): Promise<FireResponse>;
104
+ add(record: DnsRecordInput): Promise<FireResponse>;
105
+ edit(record: DnsEditInput): Promise<FireResponse>;
106
+ remove(recordId: string): Promise<FireResponse>;
107
+ };
108
+ }
109
+
110
+ export interface Webspace {
111
+ info(): Promise<FireResponse>;
112
+ }
113
+
114
+ export default class FireAPI {
115
+ constructor(apiKey: string, options?: FireAPIOptions);
116
+
117
+ apiKey: string;
118
+ baseUrl: string;
119
+
120
+ account: {
121
+ info(): Promise<FireResponse>;
122
+ services(): Promise<FireResponse>;
123
+ donations(): Promise<FireResponse>;
124
+ affiliate(): Promise<FireResponse>;
125
+ };
126
+
127
+ /** Low-Level-Anfrage gegen die API. */
128
+ request(method: string, path: string, body?: Record<string, unknown>): Promise<FireResponse>;
129
+
130
+ kvm(internalId: string | number): KVM;
131
+ domain(internalId: string | number): Domain;
132
+ webspace(internalId: string | number): Webspace;
133
+ }
134
+
135
+ export { FireAPI };