@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.
@@ -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,6 +1,32 @@
1
1
  {
2
2
  "name": "@solti/sdk",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "Solti Platform TypeScript SDK — submit and orchestrate workloads, manage connections and cronjobs without managing infrastructure.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "main": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./dist/index.d.ts",
12
+ "import": "./dist/index.js"
13
+ }
14
+ },
15
+ "files": [
16
+ "dist",
17
+ "README.md"
18
+ ],
19
+ "engines": {
20
+ "node": ">=20"
21
+ },
22
+ "scripts": {
23
+ "build": "tsc",
24
+ "dev": "tsc --watch",
25
+ "test": "vitest run"
26
+ },
27
+ "devDependencies": {
28
+ "@types/node": "^24.10.1",
29
+ "typescript": "^5.9.3",
30
+ "vitest": "^3.2.4"
31
+ }
32
+ }