@solti/sdk 0.1.1 → 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 +5 -5
- package/dist/client.d.ts +3 -0
- package/dist/client.js +4 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +1 -0
- package/dist/resources/jobs.d.ts +11 -0
- package/dist/resources/jobs.js +3 -0
- package/dist/resources/shared.d.ts +5 -0
- package/dist/resources/workflows.d.ts +164 -0
- package/dist/resources/workflows.js +153 -0
- package/package.json +2 -2
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Solti
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -20,8 +20,8 @@ Requires Node.js >= 20 (native `fetch`).
|
|
|
20
20
|
import { SoltiClient } from "@solti/sdk";
|
|
21
21
|
|
|
22
22
|
// apiKey falls back to the SOLTI_API_KEY environment variable.
|
|
23
|
-
// The project is selected via the X-Solti-Project-Id header — the SDK
|
|
24
|
-
// targets the global API host
|
|
23
|
+
// The project is selected via the X-Solti-Project-Id header — the SDK
|
|
24
|
+
// always targets the global API host.
|
|
25
25
|
const client = new SoltiClient({
|
|
26
26
|
apiKey: process.env.SOLTI_API_KEY,
|
|
27
27
|
projectId: "<project-id>",
|
|
@@ -72,7 +72,7 @@ Error mapping per the client tools spec:
|
|
|
72
72
|
|
|
73
73
|
| Error | Condition |
|
|
74
74
|
| --- | --- |
|
|
75
|
-
| `AuthenticationError` | HTTP 401 — invalid or expired API key
|
|
75
|
+
| `AuthenticationError` | HTTP 401 — invalid or expired API key |
|
|
76
76
|
| `PermissionDeniedError` | HTTP 403 — key role too weak (e.g. `viewer` on a write) |
|
|
77
77
|
| `ValidationError` | HTTP 422 — invalid payload configuration |
|
|
78
78
|
| `RateLimitError` | HTTP 429 — exposes `retryAfter` and the `X-RateLimit-*` headers |
|
|
@@ -93,6 +93,6 @@ Idempotent reads (GET) are auto-retried on 429 honoring `Retry-After`
|
|
|
93
93
|
|
|
94
94
|
| Option | Default | Description |
|
|
95
95
|
| --- | --- | --- |
|
|
96
|
-
| `apiKey` | `SOLTI_API_KEY` env |
|
|
97
|
-
| `apiUrl` | `https://api.solti.run/1` (`SOLTI_API_URL_GLOBAL` env overrides) | API base URL
|
|
96
|
+
| `apiKey` | `SOLTI_API_KEY` env | Solti API key |
|
|
97
|
+
| `apiUrl` | `https://api.solti.run/1` (`SOLTI_API_URL_GLOBAL` env overrides) | API base URL |
|
|
98
98
|
| `projectId` | — | Sent as `X-Solti-Project-Id` |
|
package/dist/client.d.ts
CHANGED
|
@@ -13,6 +13,7 @@ import { ConnectionsResource } from "./resources/connections.js";
|
|
|
13
13
|
import { CronjobsResource } from "./resources/cronjobs.js";
|
|
14
14
|
import { JobsResource } from "./resources/jobs.js";
|
|
15
15
|
import { KeysResource } from "./resources/keys.js";
|
|
16
|
+
import { WorkflowsResource } from "./resources/workflows.js";
|
|
16
17
|
/** Global API host — same default as the CLI (`SOLTI_API_URL_GLOBAL` override supported). */
|
|
17
18
|
export declare const GLOBAL_API_URL: string;
|
|
18
19
|
export interface SoltiClientOptions {
|
|
@@ -35,6 +36,8 @@ export declare class SoltiClient {
|
|
|
35
36
|
readonly cronjobs: CronjobsResource;
|
|
36
37
|
/** API keys (admin-only endpoints). */
|
|
37
38
|
readonly keys: KeysResource;
|
|
39
|
+
/** Workflow DAG orchestration (api 0.3.0): create / get / list / cancel. */
|
|
40
|
+
readonly workflows: WorkflowsResource;
|
|
38
41
|
constructor(options?: SoltiClientOptions);
|
|
39
42
|
/** Performs an API request. `path` is relative to the `/1` base (e.g. `jobs`). */
|
|
40
43
|
request(path: string, options?: {
|
package/dist/client.js
CHANGED
|
@@ -14,6 +14,7 @@ import { ConnectionsResource } from "./resources/connections.js";
|
|
|
14
14
|
import { CronjobsResource } from "./resources/cronjobs.js";
|
|
15
15
|
import { JobsResource } from "./resources/jobs.js";
|
|
16
16
|
import { KeysResource } from "./resources/keys.js";
|
|
17
|
+
import { WorkflowsResource } from "./resources/workflows.js";
|
|
17
18
|
/** Global API host — same default as the CLI (`SOLTI_API_URL_GLOBAL` override supported). */
|
|
18
19
|
export const GLOBAL_API_URL = process.env.SOLTI_API_URL_GLOBAL ?? "https://api.solti.run/1";
|
|
19
20
|
export class SoltiClient {
|
|
@@ -28,6 +29,8 @@ export class SoltiClient {
|
|
|
28
29
|
cronjobs;
|
|
29
30
|
/** API keys (admin-only endpoints). */
|
|
30
31
|
keys;
|
|
32
|
+
/** Workflow DAG orchestration (api 0.3.0): create / get / list / cancel. */
|
|
33
|
+
workflows;
|
|
31
34
|
constructor(options = {}) {
|
|
32
35
|
const apiKey = options.apiKey ?? process.env.SOLTI_API_KEY;
|
|
33
36
|
if (apiKey === undefined || apiKey === "") {
|
|
@@ -40,6 +43,7 @@ export class SoltiClient {
|
|
|
40
43
|
this.connections = new ConnectionsResource(this);
|
|
41
44
|
this.cronjobs = new CronjobsResource(this);
|
|
42
45
|
this.keys = new KeysResource(this);
|
|
46
|
+
this.workflows = new WorkflowsResource(this);
|
|
43
47
|
}
|
|
44
48
|
/** Performs an API request. `path` is relative to the `/1` base (e.g. `jobs`). */
|
|
45
49
|
async request(path, options = {}) {
|
package/dist/index.d.ts
CHANGED
|
@@ -18,7 +18,10 @@ export type { Connection, ConnectionCreateRequest, ConnectionCredentials, AwsCre
|
|
|
18
18
|
export { ConnectionsResource } from "./resources/connections.js";
|
|
19
19
|
export type { Cronjob, CreateCronjobRequest, PatchCronjobRequest } from "./resources/cronjobs.js";
|
|
20
20
|
export { CronjobsResource } from "./resources/cronjobs.js";
|
|
21
|
+
export type { CreateWorkflowRequest, WorkflowJobDefinition, WorkflowListData, WorkflowListFilters, WorkflowNodeData, WorkflowNodeRef, WorkflowTemplate, WorkflowWithSequence, WorkflowData, WorkflowDetailData, } from "./resources/workflows.js";
|
|
22
|
+
export { WorkflowsResource, mapWorkflow, mapWorkflowDetail } from "./resources/workflows.js";
|
|
21
23
|
export type { Key, CreateKeyRequest, CreateKeyResponse } from "./resources/keys.js";
|
|
22
24
|
export { KeysResource } from "./resources/keys.js";
|
|
23
25
|
export { TERMINAL_STATUSES } from "./resources/shared.js";
|
|
26
|
+
export type { WorkflowStatus } from "./resources/shared.js";
|
|
24
27
|
export type { WorkloadStatus, TerminalStatus, VmStatus, CloudProvider, ConnectionType, KeyRole, MacroRegion, } from "./resources/shared.js";
|
package/dist/index.js
CHANGED
|
@@ -15,5 +15,6 @@ export { SoltiApiError, AuthenticationError, PermissionDeniedError, ValidationEr
|
|
|
15
15
|
export { Job, JobsResource, DEFAULT_POLL_INTERVAL_MS } from "./resources/jobs.js";
|
|
16
16
|
export { ConnectionsResource } from "./resources/connections.js";
|
|
17
17
|
export { CronjobsResource } from "./resources/cronjobs.js";
|
|
18
|
+
export { WorkflowsResource, mapWorkflow, mapWorkflowDetail } from "./resources/workflows.js";
|
|
18
19
|
export { KeysResource } from "./resources/keys.js";
|
|
19
20
|
export { TERMINAL_STATUSES } from "./resources/shared.js";
|
package/dist/resources/jobs.d.ts
CHANGED
|
@@ -58,6 +58,14 @@ export interface CreateJobRequest {
|
|
|
58
58
|
region?: string | string[];
|
|
59
59
|
/** Container retries inside the VM. */
|
|
60
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;
|
|
61
69
|
labels?: Record<string, string>;
|
|
62
70
|
tags?: string[];
|
|
63
71
|
}
|
|
@@ -93,6 +101,8 @@ export interface JobData {
|
|
|
93
101
|
oomKilled?: boolean;
|
|
94
102
|
labels?: Record<string, string>;
|
|
95
103
|
tags?: string[];
|
|
104
|
+
/** Scheduled start instant (`run_after` wire field); absent = immediate. */
|
|
105
|
+
runAfter?: string;
|
|
96
106
|
createdAt?: string;
|
|
97
107
|
startedAt?: string;
|
|
98
108
|
finishedAt?: string;
|
|
@@ -126,6 +136,7 @@ export declare class Job implements JobData {
|
|
|
126
136
|
readonly oomKilled?: boolean;
|
|
127
137
|
readonly labels?: Record<string, string>;
|
|
128
138
|
readonly tags?: string[];
|
|
139
|
+
readonly runAfter?: string;
|
|
129
140
|
readonly createdAt?: string;
|
|
130
141
|
readonly startedAt?: string;
|
|
131
142
|
readonly finishedAt?: string;
|
package/dist/resources/jobs.js
CHANGED
|
@@ -27,6 +27,7 @@ export function mapJob(raw) {
|
|
|
27
27
|
oomKilled: rawBoolean(raw, "oom_killed"),
|
|
28
28
|
labels: raw.labels,
|
|
29
29
|
tags: raw.tags,
|
|
30
|
+
runAfter: rawString(raw, "run_after"),
|
|
30
31
|
createdAt: rawString(raw, "created_at"),
|
|
31
32
|
startedAt: rawString(raw, "started_at"),
|
|
32
33
|
finishedAt: rawString(raw, "finished_at"),
|
|
@@ -50,6 +51,7 @@ export class Job {
|
|
|
50
51
|
oomKilled;
|
|
51
52
|
labels;
|
|
52
53
|
tags;
|
|
54
|
+
runAfter;
|
|
53
55
|
createdAt;
|
|
54
56
|
startedAt;
|
|
55
57
|
finishedAt;
|
|
@@ -70,6 +72,7 @@ export class Job {
|
|
|
70
72
|
this.oomKilled = data.oomKilled;
|
|
71
73
|
this.labels = data.labels;
|
|
72
74
|
this.tags = data.tags;
|
|
75
|
+
this.runAfter = data.runAfter;
|
|
73
76
|
this.createdAt = data.createdAt;
|
|
74
77
|
this.startedAt = data.startedAt;
|
|
75
78
|
this.finishedAt = data.finishedAt;
|
|
@@ -9,6 +9,11 @@
|
|
|
9
9
|
export type WorkloadStatus = "queued" | "booting" | "running" | "succeeded" | "failed" | "cancelled";
|
|
10
10
|
/** Statuses from which no further transitions occur. */
|
|
11
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";
|
|
12
17
|
/**
|
|
13
18
|
* Infrastructure lifecycle (`vm_status`) — strictly monotonic (scheduler
|
|
14
19
|
* spec): `nonassigned` → `provisioning` → `provisioned` → `terminating` →
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Workflows resource — DAG orchestration over job templates (api 0.3.0,
|
|
3
|
+
* change 091 WS2). A workflow is a `templates` list, each entry a standard
|
|
4
|
+
* job definition wired with `dependencies` edges referencing other template
|
|
5
|
+
* names: root templates (no dependencies) provision immediately, dependents
|
|
6
|
+
* wait for ALL upstream nodes. Fan-out via `withItems` (static list) or
|
|
7
|
+
* `withSequence` (numeric range) materializes one node per item (≤50 nodes).
|
|
8
|
+
*
|
|
9
|
+
* Request payloads use camelCase wire keys (`namePrefix`, `withItems`,
|
|
10
|
+
* `withSequence`); responses are snake_case and are mapped to camelCase SDK
|
|
11
|
+
* types (`workflowId`, `nodeCount`, `ondemandCost`) exactly like `JobData`.
|
|
12
|
+
*
|
|
13
|
+
* Workflows spawned by a cronjob carry `cronjob_name` (api 0.3.2, change 092)
|
|
14
|
+
* and are listable per cronjob via {@link WorkflowsResource.listForCronjob}.
|
|
15
|
+
*/
|
|
16
|
+
import type { SoltiClient } from "../client.js";
|
|
17
|
+
import { type RawRecord, type VmStatus, type WorkloadStatus, type WorkflowStatus } from "./shared.js";
|
|
18
|
+
import type { JobDefinition } from "./jobs.js";
|
|
19
|
+
/**
|
|
20
|
+
* Workflow-node job definition: `name`/`namePrefix`/`runAfter` are not
|
|
21
|
+
* accepted — node identity comes from the template name (api spec
|
|
22
|
+
* `WorkflowTemplate.job`).
|
|
23
|
+
*/
|
|
24
|
+
export type WorkflowJobDefinition = Omit<JobDefinition, "runAfter">;
|
|
25
|
+
/** Numeric fan-out range: one node per integer from `start` to `end` (inclusive), stepping by `step`. */
|
|
26
|
+
export interface WorkflowWithSequence {
|
|
27
|
+
/** Inclusive range start. */
|
|
28
|
+
start: number;
|
|
29
|
+
/** Inclusive range end. */
|
|
30
|
+
end: number;
|
|
31
|
+
/** Step between items (minimum 1, default 1). */
|
|
32
|
+
step?: number;
|
|
33
|
+
}
|
|
34
|
+
/** One DAG node template: a job definition plus optional dependency edges and static fan-out. */
|
|
35
|
+
export interface WorkflowTemplate {
|
|
36
|
+
/** Node template name, unique within the workflow (slug charset, at most 63 characters). */
|
|
37
|
+
name: string;
|
|
38
|
+
/** Standard job definition for the node. */
|
|
39
|
+
job: WorkflowJobDefinition;
|
|
40
|
+
/** Upstream template names (absent = root node that provisions immediately). */
|
|
41
|
+
dependencies?: string[];
|
|
42
|
+
/** Static fan-out: one node per item with the literal `{{item}}` substituted into string values. */
|
|
43
|
+
withItems?: string[];
|
|
44
|
+
/** Numeric fan-out range (mutually exclusive with `withItems`). */
|
|
45
|
+
withSequence?: WorkflowWithSequence;
|
|
46
|
+
}
|
|
47
|
+
export interface CreateWorkflowRequest {
|
|
48
|
+
/** Optional unique workflow name (slug); 409 Conflict on collision. */
|
|
49
|
+
name?: string;
|
|
50
|
+
/** Optional prefix — generates a unique `<prefix>-<random suffix>` name. */
|
|
51
|
+
namePrefix?: string;
|
|
52
|
+
/** DAG node templates (the workflow materializes at most 50 node jobs). */
|
|
53
|
+
templates: WorkflowTemplate[];
|
|
54
|
+
}
|
|
55
|
+
export interface WorkflowListFilters {
|
|
56
|
+
status?: WorkflowStatus;
|
|
57
|
+
/** Number of items to skip (default 0). */
|
|
58
|
+
offset?: number;
|
|
59
|
+
/** Page size (default 50). */
|
|
60
|
+
limit?: number;
|
|
61
|
+
}
|
|
62
|
+
/** One materialized node-job reference on the create response (`nodes` map value). */
|
|
63
|
+
export interface WorkflowNodeRef {
|
|
64
|
+
jobId: string;
|
|
65
|
+
name: string;
|
|
66
|
+
}
|
|
67
|
+
/** One workflow node job (live projection of the jobs row on `get`). */
|
|
68
|
+
export interface WorkflowNodeData {
|
|
69
|
+
jobId: string;
|
|
70
|
+
name: string;
|
|
71
|
+
status: WorkloadStatus;
|
|
72
|
+
vmStatus?: VmStatus;
|
|
73
|
+
errorMessage?: string;
|
|
74
|
+
startedAt?: string;
|
|
75
|
+
endedAt?: string;
|
|
76
|
+
estimatedCost?: number;
|
|
77
|
+
actualCost?: number;
|
|
78
|
+
ondemandCost?: number;
|
|
79
|
+
}
|
|
80
|
+
/** Mapped workflow state (camelCase view of the snake_case API response). */
|
|
81
|
+
export interface WorkflowData {
|
|
82
|
+
/** Unique workflow identifier (UUIDv7) — `workflow_id` wire key. */
|
|
83
|
+
workflowId: string;
|
|
84
|
+
name: string;
|
|
85
|
+
status: WorkflowStatus;
|
|
86
|
+
organizationId?: string;
|
|
87
|
+
projectId?: string;
|
|
88
|
+
/** Workflow-level error summary (null/absent while running). */
|
|
89
|
+
errorMessage?: string;
|
|
90
|
+
createdAt?: string;
|
|
91
|
+
updatedAt?: string;
|
|
92
|
+
/** Terminal timestamp (absent while running). */
|
|
93
|
+
endedAt?: string;
|
|
94
|
+
/** Number of materialized node jobs (list rows). */
|
|
95
|
+
nodeCount?: number;
|
|
96
|
+
/** Materialized node jobs keyed by node-job name (create response). */
|
|
97
|
+
nodes?: Record<string, WorkflowNodeRef>;
|
|
98
|
+
/**
|
|
99
|
+
* Name of the cronjob that spawned this workflow (`cronjob_name` wire key,
|
|
100
|
+
* api 0.3.2) — null for API/CLI submissions; absent on create/cancel
|
|
101
|
+
* responses (the contract surfaces the linkage on list/detail only).
|
|
102
|
+
*/
|
|
103
|
+
cronjobName?: string | null;
|
|
104
|
+
}
|
|
105
|
+
/** Mapped `get` response: the workflow fields plus live node jobs and aggregate costs. */
|
|
106
|
+
export interface WorkflowDetailData {
|
|
107
|
+
workflowId: string;
|
|
108
|
+
name: string;
|
|
109
|
+
status: WorkflowStatus;
|
|
110
|
+
organizationId?: string;
|
|
111
|
+
projectId?: string;
|
|
112
|
+
errorMessage?: string;
|
|
113
|
+
createdAt?: string;
|
|
114
|
+
updatedAt?: string;
|
|
115
|
+
endedAt?: string;
|
|
116
|
+
nodeCount?: number;
|
|
117
|
+
/** Name of the spawning cronjob (`cronjob_name`, api 0.3.2) — null for API/CLI submissions. */
|
|
118
|
+
cronjobName?: string | null;
|
|
119
|
+
/** Node jobs read live from the jobs rows (created_at, name order). */
|
|
120
|
+
nodes: WorkflowNodeData[];
|
|
121
|
+
/** Aggregate estimated cost over the nodes (absent when no node reports one). */
|
|
122
|
+
estimatedCost?: number;
|
|
123
|
+
actualCost?: number;
|
|
124
|
+
ondemandCost?: number;
|
|
125
|
+
}
|
|
126
|
+
/** Paginated `list` response envelope (`ListWorkflowsResponse` wire shape). */
|
|
127
|
+
export interface WorkflowListData {
|
|
128
|
+
workflows: WorkflowData[];
|
|
129
|
+
/** Total number of workflows matching the filter. */
|
|
130
|
+
total: number;
|
|
131
|
+
offset: number;
|
|
132
|
+
limit: number;
|
|
133
|
+
}
|
|
134
|
+
/** Maps a workflow row (`workflow_id` on create/cancel, `id` on list rows). */
|
|
135
|
+
export declare function mapWorkflow(raw: RawRecord): WorkflowData;
|
|
136
|
+
/** Maps the `get` detail response (live node jobs + aggregate cost sums). */
|
|
137
|
+
export declare function mapWorkflowDetail(raw: RawRecord): WorkflowDetailData;
|
|
138
|
+
export declare class WorkflowsResource {
|
|
139
|
+
private readonly client;
|
|
140
|
+
constructor(client: SoltiClient);
|
|
141
|
+
/**
|
|
142
|
+
* Submits a DAG workflow. Without `name`/`namePrefix` a unique Notion-like
|
|
143
|
+
* name is auto-generated (e.g. `tidal-star-1234`).
|
|
144
|
+
*/
|
|
145
|
+
create(request: CreateWorkflowRequest): Promise<WorkflowData>;
|
|
146
|
+
/** Accepts either the workflow's unique UUID or its unique name. */
|
|
147
|
+
get(idOrName: string): Promise<WorkflowDetailData>;
|
|
148
|
+
/** Lists workflows, newest first, with the paginated response envelope. */
|
|
149
|
+
list(filters?: WorkflowListFilters): Promise<WorkflowListData>;
|
|
150
|
+
/**
|
|
151
|
+
* Lists the workflows a cronjob spawned — its run history, newest first
|
|
152
|
+
* (GET /1/cronjobs/{idOrName}/workflows, api 0.3.2, change 092). Accepts
|
|
153
|
+
* either the cronjob's UUID or its unique name; the match is on the stored
|
|
154
|
+
* `cronjob_name` linkage the scheduler persists on spawn. Same envelope and
|
|
155
|
+
* filters as {@link WorkflowsResource.list}.
|
|
156
|
+
*/
|
|
157
|
+
listForCronjob(cronjobIdOrName: string, filters?: WorkflowListFilters): Promise<WorkflowListData>;
|
|
158
|
+
/**
|
|
159
|
+
* Cancels a running workflow (by UUID or name): every non-terminal node job
|
|
160
|
+
* is cancelled; returns the workflow in its post-cancel status. 409 when
|
|
161
|
+
* the workflow is already terminal.
|
|
162
|
+
*/
|
|
163
|
+
cancel(idOrName: string): Promise<WorkflowData>;
|
|
164
|
+
}
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Workflows resource — DAG orchestration over job templates (api 0.3.0,
|
|
3
|
+
* change 091 WS2). A workflow is a `templates` list, each entry a standard
|
|
4
|
+
* job definition wired with `dependencies` edges referencing other template
|
|
5
|
+
* names: root templates (no dependencies) provision immediately, dependents
|
|
6
|
+
* wait for ALL upstream nodes. Fan-out via `withItems` (static list) or
|
|
7
|
+
* `withSequence` (numeric range) materializes one node per item (≤50 nodes).
|
|
8
|
+
*
|
|
9
|
+
* Request payloads use camelCase wire keys (`namePrefix`, `withItems`,
|
|
10
|
+
* `withSequence`); responses are snake_case and are mapped to camelCase SDK
|
|
11
|
+
* types (`workflowId`, `nodeCount`, `ondemandCost`) exactly like `JobData`.
|
|
12
|
+
*
|
|
13
|
+
* Workflows spawned by a cronjob carry `cronjob_name` (api 0.3.2, change 092)
|
|
14
|
+
* and are listable per cronjob via {@link WorkflowsResource.listForCronjob}.
|
|
15
|
+
*/
|
|
16
|
+
import { rawNumber, rawString, rawUnion, } from "./shared.js";
|
|
17
|
+
/**
|
|
18
|
+
* `cronjob_name` wire value (api 0.3.2): string when cron-spawned, null for
|
|
19
|
+
* API/CLI submissions, absent (undefined) on create/cancel responses.
|
|
20
|
+
*/
|
|
21
|
+
function rawCronjobName(raw) {
|
|
22
|
+
const value = raw.cronjob_name;
|
|
23
|
+
return typeof value === "string" ? value : value === null ? null : undefined;
|
|
24
|
+
}
|
|
25
|
+
/** Maps a workflow row (`workflow_id` on create/cancel, `id` on list rows). */
|
|
26
|
+
export function mapWorkflow(raw) {
|
|
27
|
+
const nodes = raw.nodes;
|
|
28
|
+
const nodeMap = {};
|
|
29
|
+
if (typeof nodes === "object" && nodes !== null && !Array.isArray(nodes)) {
|
|
30
|
+
for (const [nodeName, value] of Object.entries(nodes)) {
|
|
31
|
+
const ref = value;
|
|
32
|
+
nodeMap[nodeName] = {
|
|
33
|
+
jobId: rawString(ref, "job_id") ?? rawString(ref, "id") ?? "",
|
|
34
|
+
name: rawString(ref, "name") ?? nodeName,
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
return {
|
|
39
|
+
workflowId: rawString(raw, "workflow_id") ?? rawString(raw, "id") ?? "",
|
|
40
|
+
name: rawString(raw, "name") ?? "",
|
|
41
|
+
status: rawUnion(raw, "status") ?? "",
|
|
42
|
+
organizationId: rawString(raw, "organization_id"),
|
|
43
|
+
projectId: rawString(raw, "project_id"),
|
|
44
|
+
errorMessage: rawString(raw, "error_message"),
|
|
45
|
+
createdAt: rawString(raw, "created_at"),
|
|
46
|
+
updatedAt: rawString(raw, "updated_at"),
|
|
47
|
+
endedAt: rawString(raw, "ended_at"),
|
|
48
|
+
nodeCount: rawNumber(raw, "node_count"),
|
|
49
|
+
nodes: Object.keys(nodeMap).length > 0 ? nodeMap : undefined,
|
|
50
|
+
cronjobName: rawCronjobName(raw),
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
function mapWorkflowNode(raw) {
|
|
54
|
+
return {
|
|
55
|
+
jobId: rawString(raw, "job_id") ?? rawString(raw, "id") ?? "",
|
|
56
|
+
name: rawString(raw, "name") ?? "",
|
|
57
|
+
status: rawUnion(raw, "status") ?? "",
|
|
58
|
+
vmStatus: rawUnion(raw, "vm_status"),
|
|
59
|
+
errorMessage: rawString(raw, "error_message"),
|
|
60
|
+
startedAt: rawString(raw, "started_at"),
|
|
61
|
+
endedAt: rawString(raw, "ended_at"),
|
|
62
|
+
estimatedCost: rawNumber(raw, "estimated_cost"),
|
|
63
|
+
actualCost: rawNumber(raw, "actual_cost"),
|
|
64
|
+
ondemandCost: rawNumber(raw, "ondemand_cost"),
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
/** Maps the shared paginated `ListWorkflowsResponse` envelope (list + listForCronjob). */
|
|
68
|
+
function mapWorkflowList(data) {
|
|
69
|
+
const items = Array.isArray(data.workflows) ? data.workflows : [];
|
|
70
|
+
return {
|
|
71
|
+
workflows: items.map(mapWorkflow),
|
|
72
|
+
total: rawNumber(data, "total") ?? items.length,
|
|
73
|
+
offset: rawNumber(data, "offset") ?? 0,
|
|
74
|
+
limit: rawNumber(data, "limit") ?? items.length,
|
|
75
|
+
};
|
|
76
|
+
}
|
|
77
|
+
/** Maps the `get` detail response (live node jobs + aggregate cost sums). */
|
|
78
|
+
export function mapWorkflowDetail(raw) {
|
|
79
|
+
const nodes = Array.isArray(raw.nodes) ? raw.nodes : [];
|
|
80
|
+
return {
|
|
81
|
+
workflowId: rawString(raw, "workflow_id") ?? rawString(raw, "id") ?? "",
|
|
82
|
+
name: rawString(raw, "name") ?? "",
|
|
83
|
+
status: rawUnion(raw, "status") ?? "",
|
|
84
|
+
organizationId: rawString(raw, "organization_id"),
|
|
85
|
+
projectId: rawString(raw, "project_id"),
|
|
86
|
+
errorMessage: rawString(raw, "error_message"),
|
|
87
|
+
createdAt: rawString(raw, "created_at"),
|
|
88
|
+
updatedAt: rawString(raw, "updated_at"),
|
|
89
|
+
endedAt: rawString(raw, "ended_at"),
|
|
90
|
+
nodeCount: rawNumber(raw, "node_count"),
|
|
91
|
+
cronjobName: rawCronjobName(raw),
|
|
92
|
+
nodes: nodes.map(mapWorkflowNode),
|
|
93
|
+
estimatedCost: rawNumber(raw, "estimated_cost"),
|
|
94
|
+
actualCost: rawNumber(raw, "actual_cost"),
|
|
95
|
+
ondemandCost: rawNumber(raw, "ondemand_cost"),
|
|
96
|
+
};
|
|
97
|
+
}
|
|
98
|
+
export class WorkflowsResource {
|
|
99
|
+
client;
|
|
100
|
+
constructor(client) {
|
|
101
|
+
this.client = client;
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* Submits a DAG workflow. Without `name`/`namePrefix` a unique Notion-like
|
|
105
|
+
* name is auto-generated (e.g. `tidal-star-1234`).
|
|
106
|
+
*/
|
|
107
|
+
async create(request) {
|
|
108
|
+
const raw = (await this.client.request("workflows", { method: "POST", body: request }));
|
|
109
|
+
return mapWorkflow(raw);
|
|
110
|
+
}
|
|
111
|
+
/** Accepts either the workflow's unique UUID or its unique name. */
|
|
112
|
+
async get(idOrName) {
|
|
113
|
+
const raw = (await this.client.request(`workflows/${encodeURIComponent(idOrName)}`));
|
|
114
|
+
return mapWorkflowDetail(raw);
|
|
115
|
+
}
|
|
116
|
+
/** Lists workflows, newest first, with the paginated response envelope. */
|
|
117
|
+
async list(filters = {}) {
|
|
118
|
+
const data = (await this.client.request("workflows", {
|
|
119
|
+
query: {
|
|
120
|
+
status: filters.status,
|
|
121
|
+
offset: filters.offset,
|
|
122
|
+
limit: filters.limit,
|
|
123
|
+
},
|
|
124
|
+
}));
|
|
125
|
+
return mapWorkflowList(data);
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* Lists the workflows a cronjob spawned — its run history, newest first
|
|
129
|
+
* (GET /1/cronjobs/{idOrName}/workflows, api 0.3.2, change 092). Accepts
|
|
130
|
+
* either the cronjob's UUID or its unique name; the match is on the stored
|
|
131
|
+
* `cronjob_name` linkage the scheduler persists on spawn. Same envelope and
|
|
132
|
+
* filters as {@link WorkflowsResource.list}.
|
|
133
|
+
*/
|
|
134
|
+
async listForCronjob(cronjobIdOrName, filters = {}) {
|
|
135
|
+
const data = (await this.client.request(`cronjobs/${encodeURIComponent(cronjobIdOrName)}/workflows`, {
|
|
136
|
+
query: {
|
|
137
|
+
status: filters.status,
|
|
138
|
+
offset: filters.offset,
|
|
139
|
+
limit: filters.limit,
|
|
140
|
+
},
|
|
141
|
+
}));
|
|
142
|
+
return mapWorkflowList(data);
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* Cancels a running workflow (by UUID or name): every non-terminal node job
|
|
146
|
+
* is cancelled; returns the workflow in its post-cancel status. 409 when
|
|
147
|
+
* the workflow is already terminal.
|
|
148
|
+
*/
|
|
149
|
+
async cancel(idOrName) {
|
|
150
|
+
const raw = (await this.client.request(`workflows/${encodeURIComponent(idOrName)}/cancel`, { method: "POST" }));
|
|
151
|
+
return mapWorkflow(raw);
|
|
152
|
+
}
|
|
153
|
+
}
|
package/package.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@solti/sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Solti Platform TypeScript SDK — submit and orchestrate workloads, manage connections and cronjobs without managing infrastructure.",
|
|
5
5
|
"type": "module",
|
|
6
|
-
"license": "
|
|
6
|
+
"license": "MIT",
|
|
7
7
|
"main": "./dist/index.js",
|
|
8
8
|
"types": "./dist/index.d.ts",
|
|
9
9
|
"exports": {
|