@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 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
@@ -1,3 +1,98 @@
1
- # Temporary Holding Version
1
+ # @solti/sdk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Solti Platform TypeScript SDK — submit and orchestrate workloads, manage
4
+ connections and cronjobs from Node.js backends, serverless endpoints, and
5
+ orchestrators, without managing infrastructure.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm i @solti/sdk
11
+ # or
12
+ pnpm add @solti/sdk
13
+ ```
14
+
15
+ Requires Node.js >= 20 (native `fetch`).
16
+
17
+ ## Quick start
18
+
19
+ ```typescript
20
+ import { SoltiClient } from "@solti/sdk";
21
+
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
+ // always targets the global API host.
25
+ const client = new SoltiClient({
26
+ apiKey: process.env.SOLTI_API_KEY,
27
+ projectId: "<project-id>",
28
+ });
29
+
30
+ const job = await client.jobs.create({
31
+ namePrefix: "postgres-cleanup-",
32
+ image: "postgres:18-alpine",
33
+ command: ["psql"],
34
+ args: ["-c", "VACUUM ANALYZE;"],
35
+ resources: { cpu: 2, memory: "4Gi" },
36
+ labels: { environment: "production" },
37
+ tags: ["maintenance"],
38
+ });
39
+
40
+ console.log(`Job submitted: ${job.id} (${job.status})`);
41
+
42
+ const finalJob = await job.waitUntilComplete({
43
+ timeoutMs: 600_000,
44
+ onProgress: (status) => console.log(`Status: ${status}`),
45
+ });
46
+ ```
47
+
48
+ ## Error handling
49
+
50
+ ```typescript
51
+ import {
52
+ WorkloadFailedError,
53
+ TimeoutError,
54
+ RateLimitError,
55
+ AuthenticationError,
56
+ PermissionDeniedError,
57
+ ValidationError,
58
+ } from "@solti/sdk";
59
+
60
+ try {
61
+ await job.waitUntilComplete({ timeoutMs: 600_000 });
62
+ } catch (e) {
63
+ if (e instanceof WorkloadFailedError) {
64
+ console.error(`Workload failed: exit ${e.exitCode}\n${e.errorSummary}`);
65
+ } else if (e instanceof TimeoutError) {
66
+ await client.jobs.cancel(job.id);
67
+ }
68
+ }
69
+ ```
70
+
71
+ Error mapping per the client tools spec:
72
+
73
+ | Error | Condition |
74
+ | --- | --- |
75
+ | `AuthenticationError` | HTTP 401 — invalid or expired API key |
76
+ | `PermissionDeniedError` | HTTP 403 — key role too weak (e.g. `viewer` on a write) |
77
+ | `ValidationError` | HTTP 422 — invalid payload configuration |
78
+ | `RateLimitError` | HTTP 429 — exposes `retryAfter` and the `X-RateLimit-*` headers |
79
+ | `WorkloadFailedError` | Terminal `failed` state during `waitUntilComplete` (`exitCode`, `errorSummary`, OOM flag) |
80
+ | `TimeoutError` | Client-side wait timeout exceeded |
81
+
82
+ Idempotent reads (GET) are auto-retried on 429 honoring `Retry-After`
83
+ (capped at 30s, at most 2 retries); mutations surface `RateLimitError`.
84
+
85
+ ## Resources
86
+
87
+ - `client.jobs` — `create`, `get`, `list`, `cancel`, `waitUntilComplete`
88
+ - `client.connections` — `create`, `get`, `list`, `delete`
89
+ - `client.cronjobs` — `create`, `get`, `list`, `patch`/`update`, `delete` (by UUID `id` or unique `name`)
90
+ - `client.keys` — `create`, `list`, `delete` (admin only)
91
+
92
+ ## Configuration
93
+
94
+ | Option | Default | Description |
95
+ | --- | --- | --- |
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
+ | `projectId` | — | Sent as `X-Solti-Project-Id` |
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Solti SDK client — host strategy, auth, and error mapping.
3
+ *
4
+ * Host strategy (Change 015 WS2): per-project wildcard hosts
5
+ * (`<project-id>.api.solti.run`) are NOT deployed. The SDK always targets the
6
+ * global host and selects the project via the `X-Solti-Project-Id` header —
7
+ * exactly the deployed mechanism of ../solti-cli/src/api/client.ts.
8
+ *
9
+ * Auth: `X-Solti-API-Key` header, from the explicit `apiKey` option or the
10
+ * `SOLTI_API_KEY` environment variable.
11
+ */
12
+ import { ConnectionsResource } from "./resources/connections.js";
13
+ import { CronjobsResource } from "./resources/cronjobs.js";
14
+ import { JobsResource } from "./resources/jobs.js";
15
+ import { KeysResource } from "./resources/keys.js";
16
+ import { WorkflowsResource } from "./resources/workflows.js";
17
+ /** Global API host — same default as the CLI (`SOLTI_API_URL_GLOBAL` override supported). */
18
+ export declare const GLOBAL_API_URL: string;
19
+ export interface SoltiClientOptions {
20
+ /** Zitadel-managed PAT. Falls back to the `SOLTI_API_KEY` environment variable. */
21
+ apiKey?: string;
22
+ /** API base URL including the `/1` version segment. Defaults to the global host. */
23
+ apiUrl?: string;
24
+ /** Project selection — sent as the `X-Solti-Project-Id` header (no per-project hostnames). */
25
+ projectId?: string;
26
+ }
27
+ export declare class SoltiClient {
28
+ readonly apiKey: string;
29
+ readonly apiUrl: string;
30
+ readonly projectId?: string;
31
+ /** Jobs lifecycle: create / get / list / cancel / waitUntilComplete. */
32
+ readonly jobs: JobsResource;
33
+ /** Connections CRUD. */
34
+ readonly connections: ConnectionsResource;
35
+ /** Cronjobs management (addressable by UUID `id` or unique `name`). */
36
+ readonly cronjobs: CronjobsResource;
37
+ /** API keys (admin-only endpoints). */
38
+ readonly keys: KeysResource;
39
+ /** Workflow DAG orchestration (api 0.3.0): create / get / list / cancel. */
40
+ readonly workflows: WorkflowsResource;
41
+ constructor(options?: SoltiClientOptions);
42
+ /** Performs an API request. `path` is relative to the `/1` base (e.g. `jobs`). */
43
+ request(path: string, options?: {
44
+ method?: string;
45
+ body?: unknown;
46
+ query?: Record<string, string | number | undefined>;
47
+ }): Promise<unknown>;
48
+ }
package/dist/client.js ADDED
@@ -0,0 +1,109 @@
1
+ /**
2
+ * Solti SDK client — host strategy, auth, and error mapping.
3
+ *
4
+ * Host strategy (Change 015 WS2): per-project wildcard hosts
5
+ * (`<project-id>.api.solti.run`) are NOT deployed. The SDK always targets the
6
+ * global host and selects the project via the `X-Solti-Project-Id` header —
7
+ * exactly the deployed mechanism of ../solti-cli/src/api/client.ts.
8
+ *
9
+ * Auth: `X-Solti-API-Key` header, from the explicit `apiKey` option or the
10
+ * `SOLTI_API_KEY` environment variable.
11
+ */
12
+ import { AuthenticationError, PermissionDeniedError, RateLimitError, SoltiApiError, ValidationError } from "./errors.js";
13
+ import { ConnectionsResource } from "./resources/connections.js";
14
+ import { CronjobsResource } from "./resources/cronjobs.js";
15
+ import { JobsResource } from "./resources/jobs.js";
16
+ import { KeysResource } from "./resources/keys.js";
17
+ import { WorkflowsResource } from "./resources/workflows.js";
18
+ /** Global API host — same default as the CLI (`SOLTI_API_URL_GLOBAL` override supported). */
19
+ export const GLOBAL_API_URL = process.env.SOLTI_API_URL_GLOBAL ?? "https://api.solti.run/1";
20
+ export class SoltiClient {
21
+ apiKey;
22
+ apiUrl;
23
+ projectId;
24
+ /** Jobs lifecycle: create / get / list / cancel / waitUntilComplete. */
25
+ jobs;
26
+ /** Connections CRUD. */
27
+ connections;
28
+ /** Cronjobs management (addressable by UUID `id` or unique `name`). */
29
+ cronjobs;
30
+ /** API keys (admin-only endpoints). */
31
+ keys;
32
+ /** Workflow DAG orchestration (api 0.3.0): create / get / list / cancel. */
33
+ workflows;
34
+ constructor(options = {}) {
35
+ const apiKey = options.apiKey ?? process.env.SOLTI_API_KEY;
36
+ if (apiKey === undefined || apiKey === "") {
37
+ throw new Error("No API key provided. Pass `apiKey` or set the SOLTI_API_KEY environment variable.");
38
+ }
39
+ this.apiKey = apiKey;
40
+ this.apiUrl = (options.apiUrl ?? GLOBAL_API_URL).replace(/\/+$/, "");
41
+ this.projectId = options.projectId === "" ? undefined : options.projectId;
42
+ this.jobs = new JobsResource(this);
43
+ this.connections = new ConnectionsResource(this);
44
+ this.cronjobs = new CronjobsResource(this);
45
+ this.keys = new KeysResource(this);
46
+ this.workflows = new WorkflowsResource(this);
47
+ }
48
+ /** Performs an API request. `path` is relative to the `/1` base (e.g. `jobs`). */
49
+ async request(path, options = {}) {
50
+ const method = options.method ?? "GET";
51
+ const headers = { "X-Solti-API-Key": this.apiKey };
52
+ if (options.body !== undefined)
53
+ headers["Content-Type"] = "application/json";
54
+ if (this.projectId !== undefined)
55
+ headers["X-Solti-Project-Id"] = this.projectId;
56
+ let url = `${this.apiUrl}/${path.replace(/^\//, "")}`;
57
+ const query = options.query ?? {};
58
+ const params = new URLSearchParams();
59
+ for (const [key, value] of Object.entries(query)) {
60
+ if (value !== undefined && value !== "")
61
+ params.set(key, String(value));
62
+ }
63
+ const queryString = params.toString();
64
+ if (queryString !== "")
65
+ url += `?${queryString}`;
66
+ const isIdempotentRead = method === "GET";
67
+ let attempts = 0;
68
+ let retryAfterMs = 0;
69
+ // Rate-limit friendly behavior (api spec §5): auto-retry idempotent reads
70
+ // honoring `Retry-After` (capped at 30s), generalized from
71
+ // ../solti-cli/src/api/client.ts. Mutations surface `RateLimitError`.
72
+ for (;;) {
73
+ if (retryAfterMs > 0) {
74
+ await new Promise((resolve) => setTimeout(resolve, retryAfterMs));
75
+ }
76
+ attempts += 1;
77
+ const response = await fetch(url, {
78
+ method,
79
+ headers,
80
+ body: options.body === undefined ? undefined : JSON.stringify(options.body),
81
+ });
82
+ if (response.status === 429 && isIdempotentRead && attempts <= 2) {
83
+ const retryAfter = Number(response.headers.get("Retry-After") ?? "5");
84
+ retryAfterMs = Math.min(Number.isFinite(retryAfter) ? retryAfter * 1000 : 5000, 30_000);
85
+ continue;
86
+ }
87
+ const text = await response.text();
88
+ let payload = null;
89
+ try {
90
+ payload = text === "" ? null : JSON.parse(text);
91
+ }
92
+ catch {
93
+ payload = text;
94
+ }
95
+ if (!response.ok) {
96
+ if (response.status === 401)
97
+ throw new AuthenticationError(response.status, payload);
98
+ if (response.status === 403)
99
+ throw new PermissionDeniedError(response.status, payload);
100
+ if (response.status === 422)
101
+ throw new ValidationError(response.status, payload);
102
+ if (response.status === 429)
103
+ throw new RateLimitError(response.status, payload, response.headers);
104
+ throw new SoltiApiError(response.status, payload);
105
+ }
106
+ return payload;
107
+ }
108
+ }
109
+ }
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Error mapping per constitution/tools/sdk.md §5.
3
+ *
4
+ * Every HTTP error surfaces as a `SoltiApiError` subclass (or `SoltiApiError`
5
+ * itself for statuses without a dedicated type). `RateLimitError` carries the
6
+ * server-provided `retry_after` (seconds) and the `X-RateLimit-*` headers.
7
+ */
8
+ export declare class SoltiApiError extends Error {
9
+ /** HTTP status code of the failed response. */
10
+ readonly status: number;
11
+ /** Parsed response body (JSON object when parseable, raw text otherwise). */
12
+ readonly payload: unknown;
13
+ constructor(status: number, payload: unknown, message?: string);
14
+ }
15
+ /** 401 — the API key (Zitadel PAT) is invalid or has expired. */
16
+ export declare class AuthenticationError extends SoltiApiError {
17
+ constructor(status: number, payload: unknown);
18
+ }
19
+ /** 403 — the key's role is not allowed to perform this operation (e.g. `viewer` on a write). */
20
+ export declare class PermissionDeniedError extends SoltiApiError {
21
+ constructor(status: number, payload: unknown);
22
+ }
23
+ /** 422 — the payload contains invalid configuration (e.g. invalid cron expression, malformed volume). */
24
+ export declare class ValidationError extends SoltiApiError {
25
+ constructor(status: number, payload: unknown);
26
+ }
27
+ /** 429 — rate limit exceeded. Idempotent reads are auto-retried by the client; mutations surface this error. */
28
+ export declare class RateLimitError extends SoltiApiError {
29
+ /** Server-provided `Retry-After` in seconds (defaults to 5 when absent). */
30
+ readonly retryAfter: number;
31
+ /** `X-RateLimit-Limit` header value, when present. */
32
+ readonly limit?: number;
33
+ /** `X-RateLimit-Remaining` header value, when present. */
34
+ readonly remaining?: number;
35
+ /** `X-RateLimit-Reset` header value (unix epoch seconds), when present. */
36
+ readonly reset?: number;
37
+ constructor(status: number, payload: unknown, headers: Headers);
38
+ }
39
+ /**
40
+ * Raised by `waitUntilComplete` when the job reaches a terminal `failed`
41
+ * state (non-zero container exit, execution error, or OOM).
42
+ */
43
+ export declare class WorkloadFailedError extends Error {
44
+ readonly status: number;
45
+ readonly payload: unknown;
46
+ /** Container exit code, when the Task Manager reported one. */
47
+ readonly exitCode?: number;
48
+ /** Logged error summary, when present. */
49
+ readonly errorSummary?: string;
50
+ /** True when the container was killed by the OOM killer. */
51
+ readonly oom?: boolean;
52
+ /** Final job state at failure time. */
53
+ readonly job?: JobSnapshot;
54
+ constructor(options: {
55
+ exitCode?: number;
56
+ errorSummary?: string;
57
+ oom?: boolean;
58
+ job?: JobSnapshot;
59
+ status?: number;
60
+ payload?: unknown;
61
+ });
62
+ }
63
+ /** Minimal snapshot of the failed job attached to {@link WorkloadFailedError}. */
64
+ export interface JobSnapshot {
65
+ id: string;
66
+ name: string;
67
+ status: string;
68
+ [key: string]: unknown;
69
+ }
70
+ /** Raised by `waitUntilComplete` when the client-side wait timeout is exceeded. */
71
+ export declare class TimeoutError extends Error {
72
+ constructor(message?: string);
73
+ }
package/dist/errors.js ADDED
@@ -0,0 +1,101 @@
1
+ /**
2
+ * Error mapping per constitution/tools/sdk.md §5.
3
+ *
4
+ * Every HTTP error surfaces as a `SoltiApiError` subclass (or `SoltiApiError`
5
+ * itself for statuses without a dedicated type). `RateLimitError` carries the
6
+ * server-provided `retry_after` (seconds) and the `X-RateLimit-*` headers.
7
+ */
8
+ export class SoltiApiError extends Error {
9
+ /** HTTP status code of the failed response. */
10
+ status;
11
+ /** Parsed response body (JSON object when parseable, raw text otherwise). */
12
+ payload;
13
+ constructor(status, payload, message) {
14
+ super(message ?? `Solti API error (HTTP ${status})`);
15
+ this.name = "SoltiApiError";
16
+ this.status = status;
17
+ this.payload = payload;
18
+ }
19
+ }
20
+ /** 401 — the API key (Zitadel PAT) is invalid or has expired. */
21
+ export class AuthenticationError extends SoltiApiError {
22
+ constructor(status, payload) {
23
+ super(status, payload, "Authentication failed: the API key is invalid or has expired.");
24
+ this.name = "AuthenticationError";
25
+ }
26
+ }
27
+ /** 403 — the key's role is not allowed to perform this operation (e.g. `viewer` on a write). */
28
+ export class PermissionDeniedError extends SoltiApiError {
29
+ constructor(status, payload) {
30
+ super(status, payload, "Permission denied: this API key's role does not permit this operation.");
31
+ this.name = "PermissionDeniedError";
32
+ }
33
+ }
34
+ /** 422 — the payload contains invalid configuration (e.g. invalid cron expression, malformed volume). */
35
+ export class ValidationError extends SoltiApiError {
36
+ constructor(status, payload) {
37
+ super(status, payload, "Validation failed: the request payload contains invalid configuration.");
38
+ this.name = "ValidationError";
39
+ }
40
+ }
41
+ /** 429 — rate limit exceeded. Idempotent reads are auto-retried by the client; mutations surface this error. */
42
+ export class RateLimitError extends SoltiApiError {
43
+ /** Server-provided `Retry-After` in seconds (defaults to 5 when absent). */
44
+ retryAfter;
45
+ /** `X-RateLimit-Limit` header value, when present. */
46
+ limit;
47
+ /** `X-RateLimit-Remaining` header value, when present. */
48
+ remaining;
49
+ /** `X-RateLimit-Reset` header value (unix epoch seconds), when present. */
50
+ reset;
51
+ constructor(status, payload, headers) {
52
+ super(status, payload, "Rate limit exceeded.");
53
+ this.name = "RateLimitError";
54
+ const retryAfter = Number(headers.get("Retry-After") ?? "5");
55
+ this.retryAfter = Number.isFinite(retryAfter) ? retryAfter : 5;
56
+ const limit = Number(headers.get("X-RateLimit-Limit"));
57
+ if (Number.isFinite(limit))
58
+ this.limit = limit;
59
+ const remaining = Number(headers.get("X-RateLimit-Remaining"));
60
+ if (Number.isFinite(remaining))
61
+ this.remaining = remaining;
62
+ const reset = Number(headers.get("X-RateLimit-Reset"));
63
+ if (Number.isFinite(reset))
64
+ this.reset = reset;
65
+ }
66
+ }
67
+ /**
68
+ * Raised by `waitUntilComplete` when the job reaches a terminal `failed`
69
+ * state (non-zero container exit, execution error, or OOM).
70
+ */
71
+ export class WorkloadFailedError extends Error {
72
+ status;
73
+ payload;
74
+ /** Container exit code, when the Task Manager reported one. */
75
+ exitCode;
76
+ /** Logged error summary, when present. */
77
+ errorSummary;
78
+ /** True when the container was killed by the OOM killer. */
79
+ oom;
80
+ /** Final job state at failure time. */
81
+ job;
82
+ constructor(options) {
83
+ const code = options.exitCode !== undefined ? ` (exit code ${options.exitCode})` : "";
84
+ const oomSuffix = options.oom === true ? " — container was OOM-killed" : "";
85
+ super(`Workload failed${code}${oomSuffix}${options.errorSummary !== undefined ? `: ${options.errorSummary}` : ""}`);
86
+ this.name = "WorkloadFailedError";
87
+ this.exitCode = options.exitCode;
88
+ this.errorSummary = options.errorSummary;
89
+ this.oom = options.oom;
90
+ this.job = options.job;
91
+ this.status = options.status ?? 0;
92
+ this.payload = options.payload ?? null;
93
+ }
94
+ }
95
+ /** Raised by `waitUntilComplete` when the client-side wait timeout is exceeded. */
96
+ export class TimeoutError extends Error {
97
+ constructor(message = "Workload did not complete before the client-side timeout.") {
98
+ super(message);
99
+ this.name = "TimeoutError";
100
+ }
101
+ }
@@ -0,0 +1,27 @@
1
+ /**
2
+ * @solti/sdk — Solti Platform TypeScript SDK.
3
+ *
4
+ * Usage:
5
+ * ```ts
6
+ * import { SoltiClient } from "@solti/sdk";
7
+ *
8
+ * const client = new SoltiClient({ apiKey: process.env.SOLTI_API_KEY, projectId: "<project-id>" });
9
+ * const job = await client.jobs.create({ image: "alpine:latest", command: ["echo", "hi"] });
10
+ * const finalJob = await job.waitUntilComplete({ timeoutMs: 600_000 });
11
+ * ```
12
+ */
13
+ export { SoltiClient, GLOBAL_API_URL, type SoltiClientOptions } from "./client.js";
14
+ export { SoltiApiError, AuthenticationError, PermissionDeniedError, ValidationError, RateLimitError, WorkloadFailedError, TimeoutError, type JobSnapshot, } from "./errors.js";
15
+ export type { VolumeMount, JobResources, GpuRequest, JobDefinition, CreateJobRequest, JobListFilters, JobData, WaitUntilCompleteOptions, } from "./resources/jobs.js";
16
+ export { Job, JobsResource, DEFAULT_POLL_INTERVAL_MS } from "./resources/jobs.js";
17
+ export type { Connection, ConnectionCreateRequest, ConnectionCredentials, AwsCredentials, GcpCredentials, AzureCredentials, R2Credentials, GithubCredentials, } from "./resources/connections.js";
18
+ export { ConnectionsResource } from "./resources/connections.js";
19
+ export type { Cronjob, CreateCronjobRequest, PatchCronjobRequest } from "./resources/cronjobs.js";
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";
23
+ export type { Key, CreateKeyRequest, CreateKeyResponse } from "./resources/keys.js";
24
+ export { KeysResource } from "./resources/keys.js";
25
+ export { TERMINAL_STATUSES } from "./resources/shared.js";
26
+ export type { WorkflowStatus } from "./resources/shared.js";
27
+ export type { WorkloadStatus, TerminalStatus, VmStatus, CloudProvider, ConnectionType, KeyRole, MacroRegion, } from "./resources/shared.js";
package/dist/index.js ADDED
@@ -0,0 +1,20 @@
1
+ /**
2
+ * @solti/sdk — Solti Platform TypeScript SDK.
3
+ *
4
+ * Usage:
5
+ * ```ts
6
+ * import { SoltiClient } from "@solti/sdk";
7
+ *
8
+ * const client = new SoltiClient({ apiKey: process.env.SOLTI_API_KEY, projectId: "<project-id>" });
9
+ * const job = await client.jobs.create({ image: "alpine:latest", command: ["echo", "hi"] });
10
+ * const finalJob = await job.waitUntilComplete({ timeoutMs: 600_000 });
11
+ * ```
12
+ */
13
+ export { SoltiClient, GLOBAL_API_URL } from "./client.js";
14
+ export { SoltiApiError, AuthenticationError, PermissionDeniedError, ValidationError, RateLimitError, WorkloadFailedError, TimeoutError, } from "./errors.js";
15
+ export { Job, JobsResource, DEFAULT_POLL_INTERVAL_MS } from "./resources/jobs.js";
16
+ export { ConnectionsResource } from "./resources/connections.js";
17
+ export { CronjobsResource } from "./resources/cronjobs.js";
18
+ export { WorkflowsResource, mapWorkflow, mapWorkflowDetail } from "./resources/workflows.js";
19
+ export { KeysResource } from "./resources/keys.js";
20
+ export { TERMINAL_STATUSES } from "./resources/shared.js";
@@ -0,0 +1,66 @@
1
+ /**
2
+ * Connections resource — CRUD for cloud/storage credential integrations
3
+ * (api spec §3.1). Credentials are write-only: the API stores them encrypted
4
+ * and redacts them on read.
5
+ *
6
+ * Wire payload follows ../solti-cli/src/commands/connection.ts: credential
7
+ * fields are sent flat at the top level (`access_key_id`, `access_token`, …).
8
+ * The SDK accepts them nested under `credentials` and flattens for the wire.
9
+ */
10
+ import type { SoltiClient } from "../client.js";
11
+ import { type ConnectionType } from "./shared.js";
12
+ /** `type: "aws"` credential fields (cli wire format). */
13
+ export interface AwsCredentials {
14
+ access_key_id: string;
15
+ secret_access_key: string;
16
+ region?: string;
17
+ }
18
+ /** `type: "gcp"` credential fields (cli wire format). */
19
+ export interface GcpCredentials {
20
+ gcp_project_id: string;
21
+ /** Service-account key JSON (stringified) or omitted for ADC-style creds. */
22
+ keyfile_json?: string;
23
+ }
24
+ /** `type: "azure"` credential fields (cli wire format). */
25
+ export interface AzureCredentials {
26
+ client_id: string;
27
+ client_secret: string;
28
+ subscription_id: string;
29
+ tenant_id: string;
30
+ }
31
+ /** `type: "r2"` (Cloudflare R2) credential fields (cli wire format). */
32
+ export interface R2Credentials {
33
+ account_id: string;
34
+ access_key_id: string;
35
+ secret_access_key: string;
36
+ }
37
+ /** `type: "github"` credential fields (cli wire format). */
38
+ export interface GithubCredentials {
39
+ access_token: string;
40
+ }
41
+ /** Provider-specific credentials, flattened into the wire payload (cli convention). */
42
+ export type ConnectionCredentials = AwsCredentials | GcpCredentials | AzureCredentials | R2Credentials | GithubCredentials;
43
+ /** A stored connection (credentials are redacted by the API on read). */
44
+ export interface Connection {
45
+ name: string;
46
+ type: ConnectionType;
47
+ createdAt?: string;
48
+ /** Remaining provider-specific fields (credentials are redacted by the API). */
49
+ [key: string]: unknown;
50
+ }
51
+ export interface ConnectionCreateRequest {
52
+ name: string;
53
+ type: ConnectionType;
54
+ /** Provider credential fields, flattened into the wire payload (CLI convention). */
55
+ credentials?: ConnectionCredentials;
56
+ /** Flat credential fields are also accepted directly (CLI convention). */
57
+ [key: string]: unknown;
58
+ }
59
+ export declare class ConnectionsResource {
60
+ private readonly client;
61
+ constructor(client: SoltiClient);
62
+ create(request: ConnectionCreateRequest): Promise<Connection>;
63
+ get(name: string): Promise<Connection>;
64
+ list(): Promise<Connection[]>;
65
+ delete(name: string): Promise<void>;
66
+ }
@@ -0,0 +1,43 @@
1
+ /**
2
+ * Connections resource — CRUD for cloud/storage credential integrations
3
+ * (api spec §3.1). Credentials are write-only: the API stores them encrypted
4
+ * and redacts them on read.
5
+ *
6
+ * Wire payload follows ../solti-cli/src/commands/connection.ts: credential
7
+ * fields are sent flat at the top level (`access_key_id`, `access_token`, …).
8
+ * The SDK accepts them nested under `credentials` and flattens for the wire.
9
+ */
10
+ import { rawUnion, rawString } from "./shared.js";
11
+ function mapConnection(raw) {
12
+ const { created_at: createdAt, ...rest } = raw;
13
+ return {
14
+ ...rest,
15
+ name: rawString(raw, "name") ?? "",
16
+ type: rawUnion(raw, "type") ?? "",
17
+ createdAt: createdAt,
18
+ };
19
+ }
20
+ export class ConnectionsResource {
21
+ client;
22
+ constructor(client) {
23
+ this.client = client;
24
+ }
25
+ async create(request) {
26
+ const { credentials, ...flat } = request;
27
+ const body = { ...flat, ...credentials };
28
+ const raw = (await this.client.request("connections", { method: "POST", body }));
29
+ return mapConnection(raw);
30
+ }
31
+ async get(name) {
32
+ const raw = (await this.client.request(`connections/${encodeURIComponent(name)}`));
33
+ return mapConnection(raw);
34
+ }
35
+ async list() {
36
+ const data = (await this.client.request("connections"));
37
+ const items = Array.isArray(data) ? data : (data.connections ?? []);
38
+ return items.map(mapConnection);
39
+ }
40
+ async delete(name) {
41
+ await this.client.request(`connections/${encodeURIComponent(name)}`, { method: "DELETE" });
42
+ }
43
+ }
@@ -0,0 +1,50 @@
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 type { SoltiClient } from "../client.js";
10
+ import type { JobDefinition } from "./jobs.js";
11
+ export interface Cronjob {
12
+ id: string;
13
+ name: string;
14
+ /** UTC crontab expression. */
15
+ cronSpec: string;
16
+ isActive: boolean;
17
+ lastTriggeredAt?: string;
18
+ /** Job template spawned on each trigger (a job definition without `name`). */
19
+ jobDefinition?: JobDefinition;
20
+ createdAt?: string;
21
+ [key: string]: unknown;
22
+ }
23
+ export interface CreateCronjobRequest {
24
+ name: string;
25
+ /** UTC crontab expression (e.g. `"0 2 * * *"`). */
26
+ cronSpec: string;
27
+ /** Default true. */
28
+ isActive?: boolean;
29
+ /** Strict job template (a {@link JobDefinition}) — must not contain `name`. */
30
+ jobDefinition: JobDefinition;
31
+ }
32
+ export interface PatchCronjobRequest {
33
+ cronSpec?: string;
34
+ isActive?: boolean;
35
+ jobDefinition?: JobDefinition;
36
+ }
37
+ export declare class CronjobsResource {
38
+ private readonly client;
39
+ constructor(client: SoltiClient);
40
+ create(request: CreateCronjobRequest): Promise<Cronjob>;
41
+ /** Accepts either the cronjob's unique UUID or its unique name. */
42
+ get(idOrName: string): Promise<Cronjob>;
43
+ list(): Promise<Cronjob[]>;
44
+ /** Updates schedule / active flag / job template without recreating the resource. */
45
+ patch(idOrName: string, request: PatchCronjobRequest): Promise<Cronjob>;
46
+ /** Alias for {@link CronjobsResource.patch} (sdk.md §2 `.update`). */
47
+ update(idOrName: string, request: PatchCronjobRequest): Promise<Cronjob>;
48
+ /** Accepts either the cronjob's unique UUID or its unique name. */
49
+ delete(idOrName: string): Promise<void>;
50
+ }