@solti/sdk 0.0.0-stage → 0.2.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.
- package/LICENSE +21 -0
- package/README.md +97 -2
- package/dist/client.d.ts +48 -0
- package/dist/client.js +109 -0
- package/dist/errors.d.ts +73 -0
- package/dist/errors.js +101 -0
- package/dist/index.d.ts +27 -0
- package/dist/index.js +20 -0
- package/dist/resources/connections.d.ts +66 -0
- package/dist/resources/connections.js +43 -0
- package/dist/resources/cronjobs.d.ts +50 -0
- package/dist/resources/cronjobs.js +71 -0
- package/dist/resources/jobs.d.ts +165 -0
- package/dist/resources/jobs.js +175 -0
- package/dist/resources/keys.d.ts +35 -0
- package/dist/resources/keys.js +41 -0
- package/dist/resources/shared.d.ts +39 -0
- package/dist/resources/shared.js +23 -0
- package/dist/resources/workflows.d.ts +164 -0
- package/dist/resources/workflows.js +153 -0
- package/package.json +30 -4
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cronjobs resource — periodic task definitions with UTC crontab schedules
|
|
3
|
+
* and a strict `jobDefinition` template (api spec §3.3).
|
|
4
|
+
*
|
|
5
|
+
* All methods accept either the cronjob's unique UUID (`id`) or its unique
|
|
6
|
+
* `name`. The create payload must not contain a fixed `name` inside
|
|
7
|
+
* `jobDefinition` — each trigger spawns `<cronjob-name>-<UTC timestamp>`.
|
|
8
|
+
*/
|
|
9
|
+
import { rawString } from "./shared.js";
|
|
10
|
+
function mapCronjob(raw) {
|
|
11
|
+
const { cron_spec: cronSpec, is_active: isActive, last_triggered_at: lastTriggeredAt, created_at: createdAt, ...rest } = raw;
|
|
12
|
+
return {
|
|
13
|
+
...rest,
|
|
14
|
+
id: rawString(raw, "id") ?? "",
|
|
15
|
+
name: rawString(raw, "name") ?? "",
|
|
16
|
+
cronSpec: typeof cronSpec === "string" ? cronSpec : "",
|
|
17
|
+
isActive: isActive === true,
|
|
18
|
+
lastTriggeredAt: lastTriggeredAt,
|
|
19
|
+
jobDefinition: raw.job_definition,
|
|
20
|
+
createdAt: createdAt,
|
|
21
|
+
};
|
|
22
|
+
}
|
|
23
|
+
export class CronjobsResource {
|
|
24
|
+
client;
|
|
25
|
+
constructor(client) {
|
|
26
|
+
this.client = client;
|
|
27
|
+
}
|
|
28
|
+
async create(request) {
|
|
29
|
+
const body = {
|
|
30
|
+
name: request.name,
|
|
31
|
+
cron_spec: request.cronSpec,
|
|
32
|
+
is_active: request.isActive ?? true,
|
|
33
|
+
job_definition: request.jobDefinition,
|
|
34
|
+
};
|
|
35
|
+
const raw = (await this.client.request("cronjobs", { method: "POST", body }));
|
|
36
|
+
return mapCronjob(raw);
|
|
37
|
+
}
|
|
38
|
+
/** Accepts either the cronjob's unique UUID or its unique name. */
|
|
39
|
+
async get(idOrName) {
|
|
40
|
+
const raw = (await this.client.request(`cronjobs/${encodeURIComponent(idOrName)}`));
|
|
41
|
+
return mapCronjob(raw);
|
|
42
|
+
}
|
|
43
|
+
async list() {
|
|
44
|
+
const data = (await this.client.request("cronjobs"));
|
|
45
|
+
const items = Array.isArray(data) ? data : (data.cronjobs ?? []);
|
|
46
|
+
return items.map(mapCronjob);
|
|
47
|
+
}
|
|
48
|
+
/** Updates schedule / active flag / job template without recreating the resource. */
|
|
49
|
+
async patch(idOrName, request) {
|
|
50
|
+
const body = {};
|
|
51
|
+
if (request.cronSpec !== undefined)
|
|
52
|
+
body.cron_spec = request.cronSpec;
|
|
53
|
+
if (request.isActive !== undefined)
|
|
54
|
+
body.is_active = request.isActive;
|
|
55
|
+
if (request.jobDefinition !== undefined)
|
|
56
|
+
body.job_definition = request.jobDefinition;
|
|
57
|
+
const raw = (await this.client.request(`cronjobs/${encodeURIComponent(idOrName)}`, {
|
|
58
|
+
method: "PATCH",
|
|
59
|
+
body,
|
|
60
|
+
}));
|
|
61
|
+
return mapCronjob(raw);
|
|
62
|
+
}
|
|
63
|
+
/** Alias for {@link CronjobsResource.patch} (sdk.md §2 `.update`). */
|
|
64
|
+
async update(idOrName, request) {
|
|
65
|
+
return this.patch(idOrName, request);
|
|
66
|
+
}
|
|
67
|
+
/** Accepts either the cronjob's unique UUID or its unique name. */
|
|
68
|
+
async delete(idOrName) {
|
|
69
|
+
await this.client.request(`cronjobs/${encodeURIComponent(idOrName)}`, { method: "DELETE" });
|
|
70
|
+
}
|
|
71
|
+
}
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Jobs resource — submit, inspect, list, cancel workloads, and block on
|
|
3
|
+
* completion with `waitUntilComplete` (sdk.md §4.1).
|
|
4
|
+
*
|
|
5
|
+
* Request payloads use camelCase wire keys (`namePrefix`, `maxRetries`,
|
|
6
|
+
* `mountPath` — api spec §3.0); responses are snake_case and are mapped to
|
|
7
|
+
* camelCase SDK types (`vmStatus`, `estimatedCost`, `exitCode`).
|
|
8
|
+
*/
|
|
9
|
+
import type { SoltiClient } from "../client.js";
|
|
10
|
+
import { type CloudProvider, type RawRecord, type VmStatus, type WorkloadStatus } from "./shared.js";
|
|
11
|
+
/** Default client-side polling interval (sdk.md §3.1: 10s). */
|
|
12
|
+
export declare const DEFAULT_POLL_INTERVAL_MS = 10000;
|
|
13
|
+
/** A storage volume mount, keyed by volume name in the `volumes` map. */
|
|
14
|
+
export interface VolumeMount {
|
|
15
|
+
/** Required: source bucket. */
|
|
16
|
+
bucket: string;
|
|
17
|
+
/** Required: in-container mount path. */
|
|
18
|
+
mountPath: string;
|
|
19
|
+
/** Optional: connection name (defaults to the first connection with bucket access). */
|
|
20
|
+
connection?: string;
|
|
21
|
+
/** Optional: bucket prefix (defaults to the bucket root). */
|
|
22
|
+
prefix?: string;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Nested GPU request (api spec §3.2 `resources.gpu` long form). Hard
|
|
26
|
+
* constraints are never silently relaxed: unsatisfiable requests fail at
|
|
27
|
+
* scheduling with an explicit configuration error.
|
|
28
|
+
*/
|
|
29
|
+
export interface GpuRequest {
|
|
30
|
+
/** Minimum aggregate GPU VRAM (e.g. `"24Gi"`); required unless `model` is given. */
|
|
31
|
+
vram?: string;
|
|
32
|
+
/** Hard constraint on GPU model (e.g. `"A100"`); matched case-insensitively. */
|
|
33
|
+
model?: string;
|
|
34
|
+
/** Hard constraint on the minimum number of physical GPUs (requires `model`). */
|
|
35
|
+
count?: number;
|
|
36
|
+
}
|
|
37
|
+
/** Compute resources; `gpu` is the VRAM shorthand or a nested {@link GpuRequest}. */
|
|
38
|
+
export interface JobResources {
|
|
39
|
+
cpu?: number;
|
|
40
|
+
memory?: string;
|
|
41
|
+
gpu?: string | GpuRequest;
|
|
42
|
+
}
|
|
43
|
+
export interface CreateJobRequest {
|
|
44
|
+
/** Optional unique job name (unique per project). */
|
|
45
|
+
name?: string;
|
|
46
|
+
/** Optional prefix — auto-generates a unique `<prefix>-<random_suffix>` name. */
|
|
47
|
+
namePrefix?: string;
|
|
48
|
+
image: string;
|
|
49
|
+
command?: string[];
|
|
50
|
+
args?: string[];
|
|
51
|
+
env?: Record<string, string>;
|
|
52
|
+
/** Map keyed by volume name. */
|
|
53
|
+
volumes?: Record<string, VolumeMount>;
|
|
54
|
+
resources?: JobResources;
|
|
55
|
+
/** Optional provider constraints (e.g. `["aws", "gcp"]`). */
|
|
56
|
+
cloud?: CloudProvider | CloudProvider[];
|
|
57
|
+
/** Optional specific region(s) or macro-region. */
|
|
58
|
+
region?: string | string[];
|
|
59
|
+
/** Container retries inside the VM. */
|
|
60
|
+
maxRetries?: number;
|
|
61
|
+
/**
|
|
62
|
+
* Optional ISO 8601 datetime (e.g. `"2026-11-25T02:00:00Z"`): the job is
|
|
63
|
+
* submitted immediately but stays `queued` at zero cost (no VM) until the
|
|
64
|
+
* instant passes; the scheduler then provisions it normally. Timezone-aware
|
|
65
|
+
* values are normalized to UTC; past values start immediately. Cancel works
|
|
66
|
+
* normally while waiting. Immutable after submission.
|
|
67
|
+
*/
|
|
68
|
+
runAfter?: string;
|
|
69
|
+
labels?: Record<string, string>;
|
|
70
|
+
tags?: string[];
|
|
71
|
+
}
|
|
72
|
+
/** Cronjob job template — a standard job definition without `name` (api spec
|
|
73
|
+
* §3.3: each trigger spawns `<cronjob-name>-<UTC timestamp>`). */
|
|
74
|
+
export type JobDefinition = Omit<CreateJobRequest, "name" | "namePrefix">;
|
|
75
|
+
export interface JobListFilters {
|
|
76
|
+
status?: WorkloadStatus;
|
|
77
|
+
/** Tag filter (single value). */
|
|
78
|
+
tag?: string;
|
|
79
|
+
/** Label filter in the `key:value` form. */
|
|
80
|
+
label?: string;
|
|
81
|
+
/** Page size (default 50, max 200). */
|
|
82
|
+
limit?: number;
|
|
83
|
+
offset?: number;
|
|
84
|
+
}
|
|
85
|
+
/** Mapped job state (camelCase view of the snake_case API response). */
|
|
86
|
+
export interface JobData {
|
|
87
|
+
id: string;
|
|
88
|
+
name: string;
|
|
89
|
+
status: WorkloadStatus;
|
|
90
|
+
image?: string;
|
|
91
|
+
vmStatus?: VmStatus;
|
|
92
|
+
estimatedCost?: number;
|
|
93
|
+
actualCost?: number;
|
|
94
|
+
retryCount?: number;
|
|
95
|
+
maxRetries?: number;
|
|
96
|
+
errorSummary?: string;
|
|
97
|
+
exitCode?: number;
|
|
98
|
+
/** OOM flag reported by the Task Manager. */
|
|
99
|
+
oom?: boolean;
|
|
100
|
+
/** OOM-killed flag (alternate wire key for the same signal). */
|
|
101
|
+
oomKilled?: boolean;
|
|
102
|
+
labels?: Record<string, string>;
|
|
103
|
+
tags?: string[];
|
|
104
|
+
/** Scheduled start instant (`run_after` wire field); absent = immediate. */
|
|
105
|
+
runAfter?: string;
|
|
106
|
+
createdAt?: string;
|
|
107
|
+
startedAt?: string;
|
|
108
|
+
finishedAt?: string;
|
|
109
|
+
}
|
|
110
|
+
export interface WaitUntilCompleteOptions {
|
|
111
|
+
/** Client-side wait timeout; a `TimeoutError` is thrown when exceeded. */
|
|
112
|
+
timeoutMs?: number;
|
|
113
|
+
/** Polling interval. Default 10s. */
|
|
114
|
+
pollIntervalMs?: number;
|
|
115
|
+
/** Invoked whenever the reported status changes. */
|
|
116
|
+
onProgress?: (status: WorkloadStatus) => void;
|
|
117
|
+
/** Best-effort `jobs.cancel` when the timeout fires. Default false. */
|
|
118
|
+
cancelOnTimeout?: boolean;
|
|
119
|
+
}
|
|
120
|
+
export declare function mapJob(raw: RawRecord): JobData;
|
|
121
|
+
/** A submitted/fetched job; carries `waitUntilComplete` for lifecycle control. */
|
|
122
|
+
export declare class Job implements JobData {
|
|
123
|
+
private readonly client;
|
|
124
|
+
readonly id: string;
|
|
125
|
+
readonly name: string;
|
|
126
|
+
readonly status: WorkloadStatus;
|
|
127
|
+
readonly image?: string;
|
|
128
|
+
readonly vmStatus?: VmStatus;
|
|
129
|
+
readonly estimatedCost?: number;
|
|
130
|
+
readonly actualCost?: number;
|
|
131
|
+
readonly retryCount?: number;
|
|
132
|
+
readonly maxRetries?: number;
|
|
133
|
+
readonly errorSummary?: string;
|
|
134
|
+
readonly exitCode?: number;
|
|
135
|
+
readonly oom?: boolean;
|
|
136
|
+
readonly oomKilled?: boolean;
|
|
137
|
+
readonly labels?: Record<string, string>;
|
|
138
|
+
readonly tags?: string[];
|
|
139
|
+
readonly runAfter?: string;
|
|
140
|
+
readonly createdAt?: string;
|
|
141
|
+
readonly startedAt?: string;
|
|
142
|
+
readonly finishedAt?: string;
|
|
143
|
+
constructor(data: JobData, client: SoltiClient);
|
|
144
|
+
/**
|
|
145
|
+
* Polls until the job reaches a terminal state (default interval 10s).
|
|
146
|
+
* Throws `WorkloadFailedError` on a terminal `failed` state (non-zero exit,
|
|
147
|
+
* execution error, or OOM) and `TimeoutError` when `timeoutMs` is exceeded
|
|
148
|
+
* (optionally cancelling the job first via `cancelOnTimeout`).
|
|
149
|
+
*/
|
|
150
|
+
waitUntilComplete(options?: WaitUntilCompleteOptions): Promise<Job>;
|
|
151
|
+
}
|
|
152
|
+
/** Shared polling loop used by `Job.waitUntilComplete` and `jobs.waitUntilComplete`. */
|
|
153
|
+
export declare function waitUntilComplete(client: SoltiClient, idOrName: string, options?: WaitUntilCompleteOptions): Promise<Job>;
|
|
154
|
+
export declare class JobsResource {
|
|
155
|
+
private readonly client;
|
|
156
|
+
constructor(client: SoltiClient);
|
|
157
|
+
create(request: CreateJobRequest): Promise<Job>;
|
|
158
|
+
/** Accepts either the job's unique UUID or its unique name. */
|
|
159
|
+
get(idOrName: string): Promise<Job>;
|
|
160
|
+
list(filters?: JobListFilters): Promise<Job[]>;
|
|
161
|
+
/** Cancels a running, booting, or queued job (by UUID or name). */
|
|
162
|
+
cancel(idOrName: string): Promise<void>;
|
|
163
|
+
/** Polls `jobs.get` until the job reaches a terminal state. See {@link Job.waitUntilComplete}. */
|
|
164
|
+
waitUntilComplete(idOrName: string, options?: WaitUntilCompleteOptions): Promise<Job>;
|
|
165
|
+
}
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Jobs resource — submit, inspect, list, cancel workloads, and block on
|
|
3
|
+
* completion with `waitUntilComplete` (sdk.md §4.1).
|
|
4
|
+
*
|
|
5
|
+
* Request payloads use camelCase wire keys (`namePrefix`, `maxRetries`,
|
|
6
|
+
* `mountPath` — api spec §3.0); responses are snake_case and are mapped to
|
|
7
|
+
* camelCase SDK types (`vmStatus`, `estimatedCost`, `exitCode`).
|
|
8
|
+
*/
|
|
9
|
+
import { TimeoutError, WorkloadFailedError } from "../errors.js";
|
|
10
|
+
import { TERMINAL_STATUSES, rawBoolean, rawNumber, rawString, rawUnion, } from "./shared.js";
|
|
11
|
+
/** Default client-side polling interval (sdk.md §3.1: 10s). */
|
|
12
|
+
export const DEFAULT_POLL_INTERVAL_MS = 10_000;
|
|
13
|
+
export function mapJob(raw) {
|
|
14
|
+
return {
|
|
15
|
+
id: rawString(raw, "id") ?? rawString(raw, "job_id") ?? "",
|
|
16
|
+
name: rawString(raw, "name") ?? "",
|
|
17
|
+
status: rawUnion(raw, "status") ?? "",
|
|
18
|
+
image: rawString(raw, "image"),
|
|
19
|
+
vmStatus: rawUnion(raw, "vm_status"),
|
|
20
|
+
estimatedCost: rawNumber(raw, "estimated_cost"),
|
|
21
|
+
actualCost: rawNumber(raw, "actual_cost"),
|
|
22
|
+
retryCount: rawNumber(raw, "retry_count"),
|
|
23
|
+
maxRetries: rawNumber(raw, "max_retries"),
|
|
24
|
+
errorSummary: rawString(raw, "error_summary"),
|
|
25
|
+
exitCode: rawNumber(raw, "exit_code"),
|
|
26
|
+
oom: rawBoolean(raw, "oom"),
|
|
27
|
+
oomKilled: rawBoolean(raw, "oom_killed"),
|
|
28
|
+
labels: raw.labels,
|
|
29
|
+
tags: raw.tags,
|
|
30
|
+
runAfter: rawString(raw, "run_after"),
|
|
31
|
+
createdAt: rawString(raw, "created_at"),
|
|
32
|
+
startedAt: rawString(raw, "started_at"),
|
|
33
|
+
finishedAt: rawString(raw, "finished_at"),
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
/** A submitted/fetched job; carries `waitUntilComplete` for lifecycle control. */
|
|
37
|
+
export class Job {
|
|
38
|
+
client;
|
|
39
|
+
id;
|
|
40
|
+
name;
|
|
41
|
+
status;
|
|
42
|
+
image;
|
|
43
|
+
vmStatus;
|
|
44
|
+
estimatedCost;
|
|
45
|
+
actualCost;
|
|
46
|
+
retryCount;
|
|
47
|
+
maxRetries;
|
|
48
|
+
errorSummary;
|
|
49
|
+
exitCode;
|
|
50
|
+
oom;
|
|
51
|
+
oomKilled;
|
|
52
|
+
labels;
|
|
53
|
+
tags;
|
|
54
|
+
runAfter;
|
|
55
|
+
createdAt;
|
|
56
|
+
startedAt;
|
|
57
|
+
finishedAt;
|
|
58
|
+
constructor(data, client) {
|
|
59
|
+
this.client = client;
|
|
60
|
+
this.id = data.id;
|
|
61
|
+
this.name = data.name;
|
|
62
|
+
this.status = data.status;
|
|
63
|
+
this.image = data.image;
|
|
64
|
+
this.vmStatus = data.vmStatus;
|
|
65
|
+
this.estimatedCost = data.estimatedCost;
|
|
66
|
+
this.actualCost = data.actualCost;
|
|
67
|
+
this.retryCount = data.retryCount;
|
|
68
|
+
this.maxRetries = data.maxRetries;
|
|
69
|
+
this.errorSummary = data.errorSummary;
|
|
70
|
+
this.exitCode = data.exitCode;
|
|
71
|
+
this.oom = data.oom;
|
|
72
|
+
this.oomKilled = data.oomKilled;
|
|
73
|
+
this.labels = data.labels;
|
|
74
|
+
this.tags = data.tags;
|
|
75
|
+
this.runAfter = data.runAfter;
|
|
76
|
+
this.createdAt = data.createdAt;
|
|
77
|
+
this.startedAt = data.startedAt;
|
|
78
|
+
this.finishedAt = data.finishedAt;
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Polls until the job reaches a terminal state (default interval 10s).
|
|
82
|
+
* Throws `WorkloadFailedError` on a terminal `failed` state (non-zero exit,
|
|
83
|
+
* execution error, or OOM) and `TimeoutError` when `timeoutMs` is exceeded
|
|
84
|
+
* (optionally cancelling the job first via `cancelOnTimeout`).
|
|
85
|
+
*/
|
|
86
|
+
async waitUntilComplete(options = {}) {
|
|
87
|
+
return waitUntilComplete(this.client, this.id, options);
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
/** Shared polling loop used by `Job.waitUntilComplete` and `jobs.waitUntilComplete`. */
|
|
91
|
+
export async function waitUntilComplete(client, idOrName, options = {}) {
|
|
92
|
+
const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
|
|
93
|
+
const deadline = options.timeoutMs !== undefined ? Date.now() + options.timeoutMs : undefined;
|
|
94
|
+
let lastStatus;
|
|
95
|
+
for (;;) {
|
|
96
|
+
const job = await client.jobs.get(idOrName);
|
|
97
|
+
if (job.status !== lastStatus) {
|
|
98
|
+
options.onProgress?.(job.status);
|
|
99
|
+
lastStatus = job.status;
|
|
100
|
+
}
|
|
101
|
+
if (TERMINAL_STATUSES.includes(job.status)) {
|
|
102
|
+
if (job.status === "failed") {
|
|
103
|
+
throw new WorkloadFailedError({
|
|
104
|
+
exitCode: job.exitCode,
|
|
105
|
+
errorSummary: job.errorSummary,
|
|
106
|
+
oom: job.oom === true || job.oomKilled === true ? true : undefined,
|
|
107
|
+
job: {
|
|
108
|
+
id: job.id,
|
|
109
|
+
name: job.name,
|
|
110
|
+
status: job.status,
|
|
111
|
+
exitCode: job.exitCode,
|
|
112
|
+
errorSummary: job.errorSummary,
|
|
113
|
+
},
|
|
114
|
+
});
|
|
115
|
+
}
|
|
116
|
+
return job;
|
|
117
|
+
}
|
|
118
|
+
if (deadline !== undefined) {
|
|
119
|
+
const remaining = deadline - Date.now();
|
|
120
|
+
if (remaining <= 0) {
|
|
121
|
+
if (options.cancelOnTimeout === true) {
|
|
122
|
+
// Best-effort: the TimeoutError is the primary outcome; a failing
|
|
123
|
+
// cancel (e.g. job completed between polls) must not mask it.
|
|
124
|
+
try {
|
|
125
|
+
await client.jobs.cancel(idOrName);
|
|
126
|
+
}
|
|
127
|
+
catch {
|
|
128
|
+
// ignored deliberately
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
throw new TimeoutError(`Job ${idOrName} did not complete within the client-side timeout (${options.timeoutMs}ms).`);
|
|
132
|
+
}
|
|
133
|
+
await new Promise((resolve) => setTimeout(resolve, Math.min(pollIntervalMs, remaining)));
|
|
134
|
+
}
|
|
135
|
+
else {
|
|
136
|
+
await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
export class JobsResource {
|
|
141
|
+
client;
|
|
142
|
+
constructor(client) {
|
|
143
|
+
this.client = client;
|
|
144
|
+
}
|
|
145
|
+
async create(request) {
|
|
146
|
+
const raw = (await this.client.request("jobs", { method: "POST", body: request }));
|
|
147
|
+
return new Job(mapJob(raw), this.client);
|
|
148
|
+
}
|
|
149
|
+
/** Accepts either the job's unique UUID or its unique name. */
|
|
150
|
+
async get(idOrName) {
|
|
151
|
+
const raw = (await this.client.request(`jobs/${encodeURIComponent(idOrName)}`));
|
|
152
|
+
return new Job(mapJob(raw), this.client);
|
|
153
|
+
}
|
|
154
|
+
async list(filters = {}) {
|
|
155
|
+
const data = (await this.client.request("jobs", {
|
|
156
|
+
query: {
|
|
157
|
+
status: filters.status,
|
|
158
|
+
tag: filters.tag,
|
|
159
|
+
label: filters.label,
|
|
160
|
+
limit: filters.limit,
|
|
161
|
+
offset: filters.offset,
|
|
162
|
+
},
|
|
163
|
+
}));
|
|
164
|
+
const items = Array.isArray(data) ? data : (data.jobs ?? []);
|
|
165
|
+
return items.map((raw) => new Job(mapJob(raw), this.client));
|
|
166
|
+
}
|
|
167
|
+
/** Cancels a running, booting, or queued job (by UUID or name). */
|
|
168
|
+
async cancel(idOrName) {
|
|
169
|
+
await this.client.request(`jobs/${encodeURIComponent(idOrName)}/cancel`, { method: "POST" });
|
|
170
|
+
}
|
|
171
|
+
/** Polls `jobs.get` until the job reaches a terminal state. See {@link Job.waitUntilComplete}. */
|
|
172
|
+
async waitUntilComplete(idOrName, options = {}) {
|
|
173
|
+
return waitUntilComplete(this.client, idOrName, options);
|
|
174
|
+
}
|
|
175
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Keys resource — API key management (admin-only; api spec §3.4). Proxies
|
|
3
|
+
* Zitadel machine users / PATs. The clear-text token is returned exactly once
|
|
4
|
+
* at creation.
|
|
5
|
+
*/
|
|
6
|
+
import type { SoltiClient } from "../client.js";
|
|
7
|
+
import { type KeyRole } from "./shared.js";
|
|
8
|
+
export interface Key {
|
|
9
|
+
name: string;
|
|
10
|
+
role?: KeyRole;
|
|
11
|
+
createdAt?: string;
|
|
12
|
+
[key: string]: unknown;
|
|
13
|
+
}
|
|
14
|
+
export interface CreateKeyRequest {
|
|
15
|
+
name: string;
|
|
16
|
+
/** Role assigned to the machine user (`admin` | `developer` | `viewer`). */
|
|
17
|
+
role: KeyRole;
|
|
18
|
+
/** Optional expiry (ISO 8601). */
|
|
19
|
+
expiresAt?: string;
|
|
20
|
+
}
|
|
21
|
+
export interface CreateKeyResponse {
|
|
22
|
+
name: string;
|
|
23
|
+
/** Clear-text PAT, shown only once. */
|
|
24
|
+
apiKey?: string;
|
|
25
|
+
/** Alternate wire key for the same token. */
|
|
26
|
+
token?: string;
|
|
27
|
+
}
|
|
28
|
+
export declare class KeysResource {
|
|
29
|
+
private readonly client;
|
|
30
|
+
constructor(client: SoltiClient);
|
|
31
|
+
create(request: CreateKeyRequest): Promise<CreateKeyResponse>;
|
|
32
|
+
list(): Promise<Key[]>;
|
|
33
|
+
/** Accepts either the key UUID or the key name. */
|
|
34
|
+
delete(idOrName: string): Promise<void>;
|
|
35
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Keys resource — API key management (admin-only; api spec §3.4). Proxies
|
|
3
|
+
* Zitadel machine users / PATs. The clear-text token is returned exactly once
|
|
4
|
+
* at creation.
|
|
5
|
+
*/
|
|
6
|
+
import { rawUnion, rawString } from "./shared.js";
|
|
7
|
+
function mapKey(raw) {
|
|
8
|
+
const { created_at: createdAt, ...rest } = raw;
|
|
9
|
+
return {
|
|
10
|
+
...rest,
|
|
11
|
+
name: rawString(raw, "name") ?? "",
|
|
12
|
+
role: rawUnion(raw, "role"),
|
|
13
|
+
createdAt: createdAt,
|
|
14
|
+
};
|
|
15
|
+
}
|
|
16
|
+
export class KeysResource {
|
|
17
|
+
client;
|
|
18
|
+
constructor(client) {
|
|
19
|
+
this.client = client;
|
|
20
|
+
}
|
|
21
|
+
async create(request) {
|
|
22
|
+
const body = { name: request.name, role: request.role };
|
|
23
|
+
if (request.expiresAt !== undefined)
|
|
24
|
+
body.expires_at = request.expiresAt;
|
|
25
|
+
const raw = (await this.client.request("keys", { method: "POST", body }));
|
|
26
|
+
return {
|
|
27
|
+
name: rawString(raw, "name") ?? "",
|
|
28
|
+
apiKey: rawString(raw, "api_key"),
|
|
29
|
+
token: rawString(raw, "token"),
|
|
30
|
+
};
|
|
31
|
+
}
|
|
32
|
+
async list() {
|
|
33
|
+
const data = (await this.client.request("keys"));
|
|
34
|
+
const items = Array.isArray(data) ? data : (data.keys ?? []);
|
|
35
|
+
return items.map(mapKey);
|
|
36
|
+
}
|
|
37
|
+
/** Accepts either the key UUID or the key name. */
|
|
38
|
+
async delete(idOrName) {
|
|
39
|
+
await this.client.request(`keys/${encodeURIComponent(idOrName)}`, { method: "DELETE" });
|
|
40
|
+
}
|
|
41
|
+
}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared resource types — deep typing: nested interfaces plus string-union
|
|
3
|
+
* types for every finite value set (api spec §3, scheduler spec lifecycles).
|
|
4
|
+
*/
|
|
5
|
+
/**
|
|
6
|
+
* Well-known workload statuses reported by the Task Manager / scheduler
|
|
7
|
+
* (scheduler spec — `queued` → `booting` → `running` → terminal).
|
|
8
|
+
*/
|
|
9
|
+
export type WorkloadStatus = "queued" | "booting" | "running" | "succeeded" | "failed" | "cancelled";
|
|
10
|
+
/** Statuses from which no further transitions occur. */
|
|
11
|
+
export type TerminalStatus = "succeeded" | "failed" | "cancelled";
|
|
12
|
+
/**
|
|
13
|
+
* Workflow lifecycle status (api 0.3.0): `running` until every node job is
|
|
14
|
+
* terminal; the scheduler finalizes to `succeeded`/`failed`/`cancelled`.
|
|
15
|
+
*/
|
|
16
|
+
export type WorkflowStatus = "running" | "succeeded" | "failed" | "cancelled";
|
|
17
|
+
/**
|
|
18
|
+
* Infrastructure lifecycle (`vm_status`) — strictly monotonic (scheduler
|
|
19
|
+
* spec): `nonassigned` → `provisioning` → `provisioned` → `terminating` →
|
|
20
|
+
* `terminated`; `error` is reachable only from pre-`terminating` states.
|
|
21
|
+
*/
|
|
22
|
+
export type VmStatus = "nonassigned" | "provisioning" | "provisioned" | "terminating" | "terminated" | "error";
|
|
23
|
+
/** Cloud providers accepted by job routing and connections (api spec §3.2). */
|
|
24
|
+
export type CloudProvider = "aws" | "gcp" | "azure";
|
|
25
|
+
/** Connection integration types (cli `solti connection create --type`). */
|
|
26
|
+
export type ConnectionType = "aws" | "gcp" | "azure" | "r2" | "github";
|
|
27
|
+
/** Key roles (api `keys/models.py`: `Role = Literal["admin", "developer", "viewer"]`). */
|
|
28
|
+
export type KeyRole = "admin" | "developer" | "viewer";
|
|
29
|
+
/** Macro-regions accepted as `region` routing constraints (api spec §3.2). */
|
|
30
|
+
export type MacroRegion = "americas" | "europe" | "apac" | "africa" | "middle-east";
|
|
31
|
+
/** Statuses from which no further transitions occur (typed constant). */
|
|
32
|
+
export declare const TERMINAL_STATUSES: readonly TerminalStatus[];
|
|
33
|
+
/** Raw API responses are snake_case; helpers below map to camelCase SDK types. */
|
|
34
|
+
export type RawRecord = Record<string, unknown>;
|
|
35
|
+
export declare function rawString(raw: RawRecord, key: string): string | undefined;
|
|
36
|
+
export declare function rawNumber(raw: RawRecord, key: string): number | undefined;
|
|
37
|
+
export declare function rawBoolean(raw: RawRecord, key: string): boolean | undefined;
|
|
38
|
+
/** Narrows an unknown raw value to a string-union type (wire values are exact). */
|
|
39
|
+
export declare function rawUnion<T extends string>(raw: RawRecord, key: string): T | undefined;
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared resource types — deep typing: nested interfaces plus string-union
|
|
3
|
+
* types for every finite value set (api spec §3, scheduler spec lifecycles).
|
|
4
|
+
*/
|
|
5
|
+
/** Statuses from which no further transitions occur (typed constant). */
|
|
6
|
+
export const TERMINAL_STATUSES = ["succeeded", "failed", "cancelled"];
|
|
7
|
+
export function rawString(raw, key) {
|
|
8
|
+
const value = raw[key];
|
|
9
|
+
return typeof value === "string" ? value : undefined;
|
|
10
|
+
}
|
|
11
|
+
export function rawNumber(raw, key) {
|
|
12
|
+
const value = raw[key];
|
|
13
|
+
return typeof value === "number" ? value : undefined;
|
|
14
|
+
}
|
|
15
|
+
export function rawBoolean(raw, key) {
|
|
16
|
+
const value = raw[key];
|
|
17
|
+
return typeof value === "boolean" ? value : undefined;
|
|
18
|
+
}
|
|
19
|
+
/** Narrows an unknown raw value to a string-union type (wire values are exact). */
|
|
20
|
+
export function rawUnion(raw, key) {
|
|
21
|
+
const value = raw[key];
|
|
22
|
+
return typeof value === "string" ? value : undefined;
|
|
23
|
+
}
|