@krovacloud/sdk 0.4.0 → 0.4.1
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.
- package/dist/index.cjs +563 -538
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +2336 -2333
- package/dist/index.d.ts +2336 -2333
- package/dist/index.js +539 -532
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/dist/index.js
CHANGED
|
@@ -1,545 +1,552 @@
|
|
|
1
|
-
import createClient from
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
1
|
+
import createClient from "openapi-fetch";
|
|
2
|
+
//#region src/error.ts
|
|
3
|
+
/**
|
|
4
|
+
* Error thrown by the ergonomic {@link KrovaClient} helpers when the API
|
|
5
|
+
* responds with a non-2xx status.
|
|
6
|
+
*
|
|
7
|
+
* The raw openapi-fetch client (`client.raw`) never throws — it returns
|
|
8
|
+
* `{ data, error, response }`. The helpers wrap that and throw `KrovaError`
|
|
9
|
+
* so callers can `try/catch`.
|
|
10
|
+
*/
|
|
11
|
+
var KrovaError = class KrovaError extends Error {
|
|
12
|
+
/** HTTP status code of the failing response. */
|
|
13
|
+
status;
|
|
14
|
+
/**
|
|
15
|
+
* A machine-readable error code, when the API surfaces one via the
|
|
16
|
+
* `X-Error-Code` response header. The documented error body only carries a
|
|
17
|
+
* human-readable `error` string, so this is best-effort.
|
|
18
|
+
*/
|
|
19
|
+
code;
|
|
20
|
+
/**
|
|
21
|
+
* The request id from the `X-Request-Id` response header, when present.
|
|
22
|
+
* Useful when contacting Krova Cloud support about a specific failure.
|
|
23
|
+
*/
|
|
24
|
+
requestId;
|
|
25
|
+
/** The parsed JSON error body, when the response had one. */
|
|
26
|
+
body;
|
|
27
|
+
/** The raw `Response` object, for callers that need headers/url/etc. */
|
|
28
|
+
response;
|
|
29
|
+
constructor(message, init) {
|
|
30
|
+
super(message);
|
|
31
|
+
this.name = "KrovaError";
|
|
32
|
+
this.status = init.status;
|
|
33
|
+
this.code = init.code;
|
|
34
|
+
this.requestId = init.requestId;
|
|
35
|
+
this.body = init.body;
|
|
36
|
+
this.response = init.response;
|
|
37
|
+
Object.setPrototypeOf(this, KrovaError.prototype);
|
|
38
|
+
}
|
|
34
39
|
};
|
|
40
|
+
/**
|
|
41
|
+
* Build a {@link KrovaError} from a failing response + parsed error body.
|
|
42
|
+
*/
|
|
35
43
|
function krovaErrorFrom(response, body) {
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
});
|
|
44
|
+
return new KrovaError(typeof body?.error === "string" && body.error || response.statusText || `Request failed with status ${response.status}`, {
|
|
45
|
+
status: response.status,
|
|
46
|
+
code: response.headers.get("x-error-code") ?? void 0,
|
|
47
|
+
requestId: response.headers.get("x-request-id") ?? void 0,
|
|
48
|
+
body,
|
|
49
|
+
response
|
|
50
|
+
});
|
|
44
51
|
}
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
+
//#endregion
|
|
53
|
+
//#region src/client.ts
|
|
54
|
+
/** Default API base URL — the single `servers[0].url` from the OpenAPI spec. */
|
|
55
|
+
const DEFAULT_BASE_URL = "https://krova.cloud/api/v1";
|
|
56
|
+
/** Statuses the retry middleware treats as transient. */
|
|
57
|
+
const RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 503]);
|
|
58
|
+
/** Fallback backoff (ms) when the server sends no `Retry-After` header. */
|
|
59
|
+
const BASE_BACKOFF_MS = 500;
|
|
60
|
+
/** Cap on any single backoff wait (ms), to keep retries "small but real". */
|
|
61
|
+
const MAX_BACKOFF_MS = 1e4;
|
|
62
|
+
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
63
|
+
/**
|
|
64
|
+
* Parse a `Retry-After` header (RFC 7231): either delta-seconds or an
|
|
65
|
+
* HTTP-date. Returns milliseconds to wait, or `null` if absent/unparseable.
|
|
66
|
+
*/
|
|
52
67
|
function parseRetryAfterMs(headerValue) {
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
68
|
+
if (!headerValue) return null;
|
|
69
|
+
const seconds = Number(headerValue);
|
|
70
|
+
if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
|
|
71
|
+
const dateMs = Date.parse(headerValue);
|
|
72
|
+
if (Number.isFinite(dateMs)) return Math.max(0, dateMs - Date.now());
|
|
73
|
+
return null;
|
|
59
74
|
}
|
|
60
75
|
function authMiddleware(apiKey, scheme) {
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
request.headers.set("X-API-KEY", apiKey);
|
|
67
|
-
}
|
|
68
|
-
return request;
|
|
69
|
-
}
|
|
70
|
-
};
|
|
76
|
+
return { onRequest({ request }) {
|
|
77
|
+
if (scheme === "bearer") request.headers.set("Authorization", `Bearer ${apiKey}`);
|
|
78
|
+
else request.headers.set("X-API-KEY", apiKey);
|
|
79
|
+
return request;
|
|
80
|
+
} };
|
|
71
81
|
}
|
|
82
|
+
/**
|
|
83
|
+
* Retry middleware: on a retryable status, wait (honoring `Retry-After` when
|
|
84
|
+
* present, else exponential backoff) and re-issue the request.
|
|
85
|
+
*
|
|
86
|
+
* A retried request may have a body (POST/PUT/DELETE — exactly the mutating,
|
|
87
|
+
* rate-limited endpoints). By the time `onResponse` runs, the request that was
|
|
88
|
+
* handed to `fetch` has had its body stream consumed, so `request.clone()` here
|
|
89
|
+
* throws `TypeError: unusable`. To re-issue it we stash a *pristine* clone in
|
|
90
|
+
* `onRequest` — captured before the body is read — keyed by openapi-fetch's
|
|
91
|
+
* per-request `id`, and clone from that pristine copy on each attempt.
|
|
92
|
+
*/
|
|
72
93
|
function retryMiddleware(maxRetries, doFetch) {
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
}
|
|
98
|
-
};
|
|
94
|
+
const pristine = /* @__PURE__ */ new Map();
|
|
95
|
+
return {
|
|
96
|
+
onRequest({ request, id }) {
|
|
97
|
+
pristine.set(id, request.clone());
|
|
98
|
+
return request;
|
|
99
|
+
},
|
|
100
|
+
onError({ id }) {
|
|
101
|
+
pristine.delete(id);
|
|
102
|
+
},
|
|
103
|
+
async onResponse({ request, response, id }) {
|
|
104
|
+
const original = pristine.get(id) ?? request;
|
|
105
|
+
pristine.delete(id);
|
|
106
|
+
if (maxRetries <= 0 || !RETRYABLE_STATUSES.has(response.status)) return response;
|
|
107
|
+
let current = response;
|
|
108
|
+
for (let attempt = 1; attempt <= maxRetries; attempt++) {
|
|
109
|
+
if (!RETRYABLE_STATUSES.has(current.status)) break;
|
|
110
|
+
const retryAfterMs = parseRetryAfterMs(current.headers.get("retry-after"));
|
|
111
|
+
const backoff = Math.min(BASE_BACKOFF_MS * 2 ** (attempt - 1), MAX_BACKOFF_MS);
|
|
112
|
+
await sleep(Math.min(retryAfterMs ?? backoff, MAX_BACKOFF_MS));
|
|
113
|
+
current = await doFetch(original.clone());
|
|
114
|
+
}
|
|
115
|
+
return current;
|
|
116
|
+
}
|
|
117
|
+
};
|
|
99
118
|
}
|
|
119
|
+
/**
|
|
120
|
+
* A typed client for the Krova Cloud API.
|
|
121
|
+
*
|
|
122
|
+
* @example
|
|
123
|
+
* ```ts
|
|
124
|
+
* const krova = new KrovaClient({ apiKey: "kro_..." });
|
|
125
|
+
* const cubes = await krova.cubes.list("space_123");
|
|
126
|
+
* ```
|
|
127
|
+
*/
|
|
100
128
|
var KrovaClient = class {
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
if (data === void 0)
|
|
521
|
-
throw krovaErrorFrom(response, { error: "Regions response was empty." });
|
|
522
|
-
return data;
|
|
523
|
-
},
|
|
524
|
-
/** List available OS images. */
|
|
525
|
-
images: async () => {
|
|
526
|
-
const { data, error, response } = await this.raw.GET("/images");
|
|
527
|
-
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
528
|
-
if (data === void 0)
|
|
529
|
-
throw krovaErrorFrom(response, { error: "Images response was empty." });
|
|
530
|
-
return data;
|
|
531
|
-
},
|
|
532
|
-
/** Per-resource hourly rates and volume pricing tiers. */
|
|
533
|
-
pricing: async () => {
|
|
534
|
-
const { data, error, response } = await this.raw.GET("/pricing");
|
|
535
|
-
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
536
|
-
if (data === void 0)
|
|
537
|
-
throw krovaErrorFrom(response, { error: "Pricing response was empty." });
|
|
538
|
-
return data;
|
|
539
|
-
}
|
|
540
|
-
};
|
|
129
|
+
/**
|
|
130
|
+
* The underlying openapi-fetch client — a fully typed escape hatch to every
|
|
131
|
+
* path in the spec. Returns `{ data, error, response }` and never throws.
|
|
132
|
+
*
|
|
133
|
+
* @example
|
|
134
|
+
* ```ts
|
|
135
|
+
* const { data, error } = await krova.raw.GET(
|
|
136
|
+
* "/spaces/{spaceId}/cubes/{cubeId}",
|
|
137
|
+
* { params: { path: { spaceId, cubeId } } },
|
|
138
|
+
* );
|
|
139
|
+
* ```
|
|
140
|
+
*/
|
|
141
|
+
raw;
|
|
142
|
+
/** The resolved base URL in use. */
|
|
143
|
+
baseUrl;
|
|
144
|
+
constructor(options) {
|
|
145
|
+
if (!options?.apiKey) throw new Error("KrovaClient: `apiKey` is required.");
|
|
146
|
+
this.baseUrl = options.baseUrl ?? "https://krova.cloud/api/v1";
|
|
147
|
+
const doFetch = options.fetch ?? globalThis.fetch;
|
|
148
|
+
const maxRetries = options.maxRetries ?? 2;
|
|
149
|
+
this.raw = createClient({
|
|
150
|
+
baseUrl: this.baseUrl,
|
|
151
|
+
redirect: "manual",
|
|
152
|
+
...options.fetch ? { fetch: options.fetch } : {}
|
|
153
|
+
});
|
|
154
|
+
this.raw.use(authMiddleware(options.apiKey, options.authScheme ?? "x-api-key"));
|
|
155
|
+
if (maxRetries > 0) this.raw.use(retryMiddleware(maxRetries, doFetch));
|
|
156
|
+
}
|
|
157
|
+
cubes = {
|
|
158
|
+
/** List Cubes in a Space, with pagination metadata. */
|
|
159
|
+
list: async (spaceId) => {
|
|
160
|
+
const { data, error, response } = await this.raw.GET("/spaces/{spaceId}/cubes", { params: { path: { spaceId } } });
|
|
161
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
162
|
+
if (data === void 0) throw krovaErrorFrom(response, { error: "List Cubes response was empty." });
|
|
163
|
+
return data;
|
|
164
|
+
},
|
|
165
|
+
/**
|
|
166
|
+
* Create a Cube. Returns the created {@link Cube}.
|
|
167
|
+
*
|
|
168
|
+
* @param spaceId Target Space id.
|
|
169
|
+
* @param body Cube spec — `{ name, image, resources, sshPublicKey, ... }`.
|
|
170
|
+
* @param opts Optional `idempotencyKey` (max 255 chars, scoped per space).
|
|
171
|
+
*/
|
|
172
|
+
create: async (spaceId, body, opts) => {
|
|
173
|
+
const { data, error, response } = await this.raw.POST("/spaces/{spaceId}/cubes", {
|
|
174
|
+
params: {
|
|
175
|
+
path: { spaceId },
|
|
176
|
+
...opts?.idempotencyKey ? { header: { "Idempotency-Key": opts.idempotencyKey } } : {}
|
|
177
|
+
},
|
|
178
|
+
body
|
|
179
|
+
});
|
|
180
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
181
|
+
const cube = data?.cube;
|
|
182
|
+
if (!cube) throw krovaErrorFrom(response, { error: "Create Cube response had no `cube`." });
|
|
183
|
+
return cube;
|
|
184
|
+
},
|
|
185
|
+
/** Get a single Cube. Returns the {@link Cube}. */
|
|
186
|
+
get: async (spaceId, cubeId) => {
|
|
187
|
+
const { data, error, response } = await this.raw.GET("/spaces/{spaceId}/cubes/{cubeId}", { params: { path: {
|
|
188
|
+
spaceId,
|
|
189
|
+
cubeId
|
|
190
|
+
} } });
|
|
191
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
192
|
+
const cube = data?.cube;
|
|
193
|
+
if (!cube) throw krovaErrorFrom(response, { error: "Get Cube response had no `cube`." });
|
|
194
|
+
return cube;
|
|
195
|
+
},
|
|
196
|
+
/**
|
|
197
|
+
* Update the IN-CUBE port that SSH is forwarded to.
|
|
198
|
+
*
|
|
199
|
+
* `cubePort` is the port **inside** the Cube that sshd listens on — NOT the
|
|
200
|
+
* host port you connect to. The host port is allocated by Krova and is not
|
|
201
|
+
* changed by this call. Pointing this at a port nothing is listening on
|
|
202
|
+
* inside the Cube will silently make SSH unreachable; the default is 22.
|
|
203
|
+
*
|
|
204
|
+
* The Krova Cloud API exposes no general Cube-mutation endpoint; the only
|
|
205
|
+
* mutable Cube field over the API is this port, via
|
|
206
|
+
* `PUT /spaces/{spaceId}/cubes/{cubeId}/ssh-port`. This helper maps to that
|
|
207
|
+
* endpoint. (Compute resize / rename are not part of the public API.)
|
|
208
|
+
*/
|
|
209
|
+
update: async (spaceId, cubeId, body) => {
|
|
210
|
+
const { data, error, response } = await this.raw.PUT("/spaces/{spaceId}/cubes/{cubeId}/ssh-port", {
|
|
211
|
+
params: { path: {
|
|
212
|
+
spaceId,
|
|
213
|
+
cubeId
|
|
214
|
+
} },
|
|
215
|
+
body
|
|
216
|
+
});
|
|
217
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
218
|
+
return data;
|
|
219
|
+
},
|
|
220
|
+
/** Delete a Cube (asynchronous — deletion is enqueued). */
|
|
221
|
+
delete: async (spaceId, cubeId) => {
|
|
222
|
+
const { data, error, response } = await this.raw.DELETE("/spaces/{spaceId}/cubes/{cubeId}", { params: { path: {
|
|
223
|
+
spaceId,
|
|
224
|
+
cubeId
|
|
225
|
+
} } });
|
|
226
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
227
|
+
if (data === void 0) throw krovaErrorFrom(response, { error: "Delete Cube response was empty." });
|
|
228
|
+
return data;
|
|
229
|
+
},
|
|
230
|
+
/** Power off a running Cube (asynchronous — power-off is enqueued). The Cube
|
|
231
|
+
* becomes `stopped` (its host RAM is freed); start it again with `wake`. */
|
|
232
|
+
powerOff: async (spaceId, cubeId) => {
|
|
233
|
+
const { data, error, response } = await this.raw.POST("/spaces/{spaceId}/cubes/{cubeId}/power-off", { params: { path: {
|
|
234
|
+
spaceId,
|
|
235
|
+
cubeId
|
|
236
|
+
} } });
|
|
237
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
238
|
+
return data;
|
|
239
|
+
},
|
|
240
|
+
/** Start a stopped Cube (asynchronous — start is enqueued). */
|
|
241
|
+
/**
|
|
242
|
+
* Restart a Cube (COLD restart).
|
|
243
|
+
*
|
|
244
|
+
* The hypervisor process is stopped and relaunched, so the Cube boots
|
|
245
|
+
* against the host's current kernel. This is the only way a Cube picks up a
|
|
246
|
+
* refreshed guest kernel after a platform image update — a `reboot` issued
|
|
247
|
+
* INSIDE the Cube cannot do it, because Firecracker treats a guest reboot as
|
|
248
|
+
* a shutdown and the kernel is supplied externally by the host.
|
|
249
|
+
*
|
|
250
|
+
* Disk state is preserved; only the kernel changes. The Cube must be
|
|
251
|
+
* `running`. Concurrent restarts of the same Cube are rejected (409) rather
|
|
252
|
+
* than queued twice.
|
|
253
|
+
*/
|
|
254
|
+
restart: async (spaceId, cubeId) => {
|
|
255
|
+
const { data, error, response } = await this.raw.POST("/spaces/{spaceId}/cubes/{cubeId}/restart", { params: { path: {
|
|
256
|
+
spaceId,
|
|
257
|
+
cubeId
|
|
258
|
+
} } });
|
|
259
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
260
|
+
return data;
|
|
261
|
+
},
|
|
262
|
+
wake: async (spaceId, cubeId) => {
|
|
263
|
+
const { data, error, response } = await this.raw.POST("/spaces/{spaceId}/cubes/{cubeId}/wake", { params: { path: {
|
|
264
|
+
spaceId,
|
|
265
|
+
cubeId
|
|
266
|
+
} } });
|
|
267
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
268
|
+
return data;
|
|
269
|
+
},
|
|
270
|
+
/**
|
|
271
|
+
* Get a Cube's SSH connection info — host, port, login user, and (when
|
|
272
|
+
* available) the pinned host public keys for strict host-key verification.
|
|
273
|
+
*/
|
|
274
|
+
ssh: async (spaceId, cubeId) => {
|
|
275
|
+
const { data, error, response } = await this.raw.GET("/spaces/{spaceId}/cubes/{cubeId}/ssh", { params: { path: {
|
|
276
|
+
spaceId,
|
|
277
|
+
cubeId
|
|
278
|
+
} } });
|
|
279
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
280
|
+
if (data === void 0) throw krovaErrorFrom(response, { error: "Cube SSH-info response was empty." });
|
|
281
|
+
return data;
|
|
282
|
+
},
|
|
283
|
+
/**
|
|
284
|
+
* Restore a Cube's disk from one of its {@link Snapshot}s (asynchronous —
|
|
285
|
+
* the restore is enqueued). The Cube's current disk is replaced.
|
|
286
|
+
*/
|
|
287
|
+
restore: async (spaceId, cubeId, snapshotId) => {
|
|
288
|
+
const { data, error, response } = await this.raw.POST("/spaces/{spaceId}/cubes/{cubeId}/restore", {
|
|
289
|
+
params: { path: {
|
|
290
|
+
spaceId,
|
|
291
|
+
cubeId
|
|
292
|
+
} },
|
|
293
|
+
body: { snapshotId }
|
|
294
|
+
});
|
|
295
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
296
|
+
return data;
|
|
297
|
+
}
|
|
298
|
+
};
|
|
299
|
+
/**
|
|
300
|
+
* Resolve the {@link Space} this API key is scoped to — so you don't have to
|
|
301
|
+
* hardcode a `spaceId`. Handy right after constructing the client:
|
|
302
|
+
*
|
|
303
|
+
* @example
|
|
304
|
+
* ```ts
|
|
305
|
+
* const space = await krova.getSpace();
|
|
306
|
+
* const cubes = await krova.cubes.list(space.id);
|
|
307
|
+
* ```
|
|
308
|
+
*/
|
|
309
|
+
async getSpace() {
|
|
310
|
+
const { data, error, response } = await this.raw.GET("/space");
|
|
311
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
312
|
+
if (data === void 0) throw krovaErrorFrom(response, { error: "Space response was empty." });
|
|
313
|
+
return data;
|
|
314
|
+
}
|
|
315
|
+
domains = {
|
|
316
|
+
/** List the custom domains attached to a Cube. */
|
|
317
|
+
list: async (spaceId, cubeId) => {
|
|
318
|
+
const { data, error, response } = await this.raw.GET("/spaces/{spaceId}/cubes/{cubeId}/domains", { params: { path: {
|
|
319
|
+
spaceId,
|
|
320
|
+
cubeId
|
|
321
|
+
} } });
|
|
322
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
323
|
+
return data?.domains ?? [];
|
|
324
|
+
},
|
|
325
|
+
/**
|
|
326
|
+
* Attach a custom domain to a Cube. `domain` + `port` are required.
|
|
327
|
+
*
|
|
328
|
+
* Returns the domain AND the DNS records you must publish for it to work —
|
|
329
|
+
* so you can create them in the same run, without a second call and without
|
|
330
|
+
* hard-coding record shapes. A wildcard needs three; an exact host needs one.
|
|
331
|
+
*
|
|
332
|
+
* ⛔ BREAKING in 0.4.0: this used to resolve to `Domain`. It now resolves to
|
|
333
|
+
* `{ domain, records }`, because for a wildcard two of the three records
|
|
334
|
+
* (the ownership TXT and the `_acme-challenge` delegation) were not
|
|
335
|
+
* derivable from anything the SDK returned — an integration had to read
|
|
336
|
+
* them out of the docs and hope they still matched the server.
|
|
337
|
+
*/
|
|
338
|
+
create: async (spaceId, cubeId, body) => {
|
|
339
|
+
const { data, error, response } = await this.raw.POST("/spaces/{spaceId}/cubes/{cubeId}/domains", {
|
|
340
|
+
params: { path: {
|
|
341
|
+
spaceId,
|
|
342
|
+
cubeId
|
|
343
|
+
} },
|
|
344
|
+
body
|
|
345
|
+
});
|
|
346
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
347
|
+
if (!data?.domain) throw krovaErrorFrom(response, { error: "Create domain response had no `domain`." });
|
|
348
|
+
return {
|
|
349
|
+
domain: data.domain,
|
|
350
|
+
records: data.records ?? []
|
|
351
|
+
};
|
|
352
|
+
},
|
|
353
|
+
/**
|
|
354
|
+
* The DNS records a domain needs, each checked against live DNS.
|
|
355
|
+
*
|
|
356
|
+
* Poll this after publishing them: `summary.complete` turns true only once
|
|
357
|
+
* every record is `found`. Each call performs real DNS lookups and is rate
|
|
358
|
+
* limited, so poll on an interval rather than in a tight loop.
|
|
359
|
+
*/
|
|
360
|
+
records: async (spaceId, cubeId, mappingId) => {
|
|
361
|
+
const { data, error, response } = await this.raw.GET("/spaces/{spaceId}/cubes/{cubeId}/domains/{mappingId}/records", { params: { path: {
|
|
362
|
+
spaceId,
|
|
363
|
+
cubeId,
|
|
364
|
+
mappingId
|
|
365
|
+
} } });
|
|
366
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
367
|
+
if (!data) throw krovaErrorFrom(response, { error: "Domain records response was empty." });
|
|
368
|
+
return data;
|
|
369
|
+
},
|
|
370
|
+
/** Update a domain's per-domain proxy settings. */
|
|
371
|
+
update: async (spaceId, cubeId, mappingId, body) => {
|
|
372
|
+
const { data, error, response } = await this.raw.PATCH("/spaces/{spaceId}/cubes/{cubeId}/domains/{mappingId}", {
|
|
373
|
+
params: { path: {
|
|
374
|
+
spaceId,
|
|
375
|
+
cubeId,
|
|
376
|
+
mappingId
|
|
377
|
+
} },
|
|
378
|
+
body
|
|
379
|
+
});
|
|
380
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
381
|
+
if (!data?.domain) throw krovaErrorFrom(response, { error: "Update domain response had no `domain`." });
|
|
382
|
+
return data.domain;
|
|
383
|
+
},
|
|
384
|
+
/** Detach a custom domain from a Cube. */
|
|
385
|
+
delete: async (spaceId, cubeId, mappingId) => {
|
|
386
|
+
const { data, error, response } = await this.raw.DELETE("/spaces/{spaceId}/cubes/{cubeId}/domains/{mappingId}", { params: { path: {
|
|
387
|
+
spaceId,
|
|
388
|
+
cubeId,
|
|
389
|
+
mappingId
|
|
390
|
+
} } });
|
|
391
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
392
|
+
return data;
|
|
393
|
+
}
|
|
394
|
+
};
|
|
395
|
+
snapshots = {
|
|
396
|
+
/** List a Cube's snapshots. */
|
|
397
|
+
list: async (spaceId, cubeId) => {
|
|
398
|
+
const { data, error, response } = await this.raw.GET("/spaces/{spaceId}/cubes/{cubeId}/snapshots", { params: { path: {
|
|
399
|
+
spaceId,
|
|
400
|
+
cubeId
|
|
401
|
+
} } });
|
|
402
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
403
|
+
return data?.snapshots ?? [];
|
|
404
|
+
},
|
|
405
|
+
/** Create a snapshot of a Cube's disk (asynchronous — enqueued). */
|
|
406
|
+
create: async (spaceId, cubeId, body) => {
|
|
407
|
+
const { data, error, response } = await this.raw.POST("/spaces/{spaceId}/cubes/{cubeId}/snapshots", {
|
|
408
|
+
params: { path: {
|
|
409
|
+
spaceId,
|
|
410
|
+
cubeId
|
|
411
|
+
} },
|
|
412
|
+
body: body ?? {}
|
|
413
|
+
});
|
|
414
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
415
|
+
if (!data?.snapshot) throw krovaErrorFrom(response, { error: "Create snapshot response had no `snapshot`." });
|
|
416
|
+
return data.snapshot;
|
|
417
|
+
},
|
|
418
|
+
/** Delete a snapshot. */
|
|
419
|
+
delete: async (spaceId, cubeId, snapshotId) => {
|
|
420
|
+
const { data, error, response } = await this.raw.DELETE("/spaces/{spaceId}/cubes/{cubeId}/snapshots/{snapshotId}", { params: { path: {
|
|
421
|
+
spaceId,
|
|
422
|
+
cubeId,
|
|
423
|
+
snapshotId
|
|
424
|
+
} } });
|
|
425
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
426
|
+
return data;
|
|
427
|
+
}
|
|
428
|
+
};
|
|
429
|
+
tcpMappings = {
|
|
430
|
+
/** List a Cube's TCP port mappings. */
|
|
431
|
+
list: async (spaceId, cubeId) => {
|
|
432
|
+
const { data, error, response } = await this.raw.GET("/spaces/{spaceId}/cubes/{cubeId}/tcp-mappings", { params: { path: {
|
|
433
|
+
spaceId,
|
|
434
|
+
cubeId
|
|
435
|
+
} } });
|
|
436
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
437
|
+
return data?.tcpMappings ?? [];
|
|
438
|
+
},
|
|
439
|
+
/**
|
|
440
|
+
* Create a TCP port mapping exposing a Cube port on the host. `cubePort` is
|
|
441
|
+
* required; `whitelistIps` optionally restricts who can reach it.
|
|
442
|
+
*/
|
|
443
|
+
create: async (spaceId, cubeId, body) => {
|
|
444
|
+
const { data, error, response } = await this.raw.POST("/spaces/{spaceId}/cubes/{cubeId}/tcp-mappings", {
|
|
445
|
+
params: { path: {
|
|
446
|
+
spaceId,
|
|
447
|
+
cubeId
|
|
448
|
+
} },
|
|
449
|
+
body
|
|
450
|
+
});
|
|
451
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
452
|
+
if (!data?.tcpMapping) throw krovaErrorFrom(response, { error: "Create TCP mapping response had no `tcpMapping`." });
|
|
453
|
+
return data.tcpMapping;
|
|
454
|
+
},
|
|
455
|
+
/** Delete a TCP port mapping. */
|
|
456
|
+
delete: async (spaceId, cubeId, mappingId) => {
|
|
457
|
+
const { data, error, response } = await this.raw.DELETE("/spaces/{spaceId}/cubes/{cubeId}/tcp-mappings/{mappingId}", { params: { path: {
|
|
458
|
+
spaceId,
|
|
459
|
+
cubeId,
|
|
460
|
+
mappingId
|
|
461
|
+
} } });
|
|
462
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
463
|
+
return data;
|
|
464
|
+
}
|
|
465
|
+
};
|
|
466
|
+
imports = {
|
|
467
|
+
/**
|
|
468
|
+
* Start importing a `.cube` archive into a new Cube. Returns the multipart
|
|
469
|
+
* upload target (`importId`, `uploadId`, presigned `parts`, …). Upload the
|
|
470
|
+
* archive to those URLs, then call {@link imports.complete}.
|
|
471
|
+
*/
|
|
472
|
+
create: async (spaceId, body) => {
|
|
473
|
+
const { data, error, response } = await this.raw.POST("/spaces/{spaceId}/cubes/imports", {
|
|
474
|
+
params: { path: { spaceId } },
|
|
475
|
+
body
|
|
476
|
+
});
|
|
477
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
478
|
+
return data;
|
|
479
|
+
},
|
|
480
|
+
/** Get an in-progress or completed import by id. */
|
|
481
|
+
get: async (spaceId, importId) => {
|
|
482
|
+
const { data, error, response } = await this.raw.GET("/spaces/{spaceId}/cubes/imports/{importId}", { params: { path: {
|
|
483
|
+
spaceId,
|
|
484
|
+
importId
|
|
485
|
+
} } });
|
|
486
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
487
|
+
return data;
|
|
488
|
+
},
|
|
489
|
+
/**
|
|
490
|
+
* Finish an import after the archive has been uploaded — provisions the
|
|
491
|
+
* Cube. Pass the uploaded `parts` (partNumber + etag) and the resolved
|
|
492
|
+
* `config`.
|
|
493
|
+
*/
|
|
494
|
+
complete: async (spaceId, importId, body) => {
|
|
495
|
+
const { data, error, response } = await this.raw.POST("/spaces/{spaceId}/cubes/imports/{importId}/complete", {
|
|
496
|
+
params: { path: {
|
|
497
|
+
spaceId,
|
|
498
|
+
importId
|
|
499
|
+
} },
|
|
500
|
+
body
|
|
501
|
+
});
|
|
502
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
503
|
+
return data;
|
|
504
|
+
},
|
|
505
|
+
/** Cancel an in-progress import. */
|
|
506
|
+
cancel: async (spaceId, importId) => {
|
|
507
|
+
const { data, error, response } = await this.raw.DELETE("/spaces/{spaceId}/cubes/imports/{importId}", { params: { path: {
|
|
508
|
+
spaceId,
|
|
509
|
+
importId
|
|
510
|
+
} } });
|
|
511
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
512
|
+
return data;
|
|
513
|
+
}
|
|
514
|
+
};
|
|
515
|
+
backups = {
|
|
516
|
+
/** Get a time-limited download URL for a backup `.cube` archive. */
|
|
517
|
+
download: async (spaceId, backupId) => {
|
|
518
|
+
const { data, error, response } = await this.raw.GET("/spaces/{spaceId}/backups/{backupId}/download", { params: { path: {
|
|
519
|
+
spaceId,
|
|
520
|
+
backupId
|
|
521
|
+
} } });
|
|
522
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
523
|
+
return data;
|
|
524
|
+
} };
|
|
525
|
+
catalog = {
|
|
526
|
+
/** List regions with available capacity. */
|
|
527
|
+
regions: async () => {
|
|
528
|
+
const { data, error, response } = await this.raw.GET("/regions");
|
|
529
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
530
|
+
if (data === void 0) throw krovaErrorFrom(response, { error: "Regions response was empty." });
|
|
531
|
+
return data;
|
|
532
|
+
},
|
|
533
|
+
/** List available OS images. */
|
|
534
|
+
images: async () => {
|
|
535
|
+
const { data, error, response } = await this.raw.GET("/images");
|
|
536
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
537
|
+
if (data === void 0) throw krovaErrorFrom(response, { error: "Images response was empty." });
|
|
538
|
+
return data;
|
|
539
|
+
},
|
|
540
|
+
/** Per-resource hourly rates and volume pricing tiers. */
|
|
541
|
+
pricing: async () => {
|
|
542
|
+
const { data, error, response } = await this.raw.GET("/pricing");
|
|
543
|
+
if (error !== void 0 || !response.ok) throw krovaErrorFrom(response, error);
|
|
544
|
+
if (data === void 0) throw krovaErrorFrom(response, { error: "Pricing response was empty." });
|
|
545
|
+
return data;
|
|
546
|
+
}
|
|
547
|
+
};
|
|
541
548
|
};
|
|
542
|
-
|
|
549
|
+
//#endregion
|
|
543
550
|
export { DEFAULT_BASE_URL, KrovaClient, KrovaError, krovaErrorFrom };
|
|
544
|
-
|
|
551
|
+
|
|
545
552
|
//# sourceMappingURL=index.js.map
|