dataiku-sdk 3.0.0 → 3.1.0

package/dist/src/client.js

@@ -3,7 +3,7 @@ import { basename, } from "node:path";
 import { getCACertificates, } from "node:tls";
 import { Value, } from "@sinclair/typebox/value";
 import { safeParseSchema, } from "./schemas.js";
-import { classifyDataikuError, ClientValidationError, DataikuError, } from "./errors.js";
+import { classifyDataikuError, ClientValidationError, DataikuError, NON_JSON_RESPONSE_MARKER, } from "./errors.js";
 import { AnalysesResource, } from "./resources/analyses.js";
 import { ApiDeployerResource, } from "./resources/api-deployer.js";
 import { ApiServicesResource, } from "./resources/api-services.js";
@@ -47,6 +47,14 @@ const MAX_RETRY_ATTEMPTS_CAP = 10;
 const BASE_DELAY_MS = 2_000;
 const MAX_BACKOFF_DELAY_MS = 30_000;
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * Default cap on bytes buffered from a single response body by the text/JSON
+ * consumers (getText, postText, parseJsonResponse). Bodies larger than this
+ * are rejected with a DataikuError after the stream is cancelled; raw
+ * streaming methods (stream, postStream) are unaffected.
+ */
+const DEFAULT_MAX_BUFFERED_BODY_BYTES = 50 * 1024 * 1024;
+const RESPONSE_TOO_LARGE_STATUS_TEXT = "Response Too Large";
 /* ------------------------------------------------------------------ */
 /*  Helpers                                                            */
 /* ------------------------------------------------------------------ */
@@ -105,6 +113,43 @@ function trimToUtf8Boundary(bytes) {
         return bytes;
     return continuation + 1 < expected ? bytes.subarray(0, i) : bytes;
 }
+/**
+ * Drop leading UTF-8 continuation bytes. A UTF-8 character never *starts*
+ * with a continuation byte, so any leading continuation bytes are the remains
+ * of a character split by a byte cut at the start of the retained range.
+ * Dropping them keeps the decoded text free of replacement characters.
+ */
+function trimFromUtf8BoundaryStart(bytes) {
+    let i = 0;
+    while (i < bytes.length && (bytes[i] & 0xC0) === 0x80) {
+        i++;
+    }
+    return i > 0 ? bytes.subarray(i) : bytes;
+}
+function buildBodyReadTimeoutError(timeoutMs) {
+    return new DataikuError(0, "Request Timeout", `Request timed out after ${timeoutMs}ms while reading the response body.`);
+}
+/**
+ * Read the next chunk of a response body under a hard deadline.
+ * When `remainingMs` elapses, the stream is cancelled and the caller's
+ * promise rejects with a DataikuError, so a stalled body cannot hang the
+ * buffered consumers after headers already arrived.
+ */
+async function readChunkWithDeadline(reader, remainingMs, timeoutMs) {
+    const { promise, resolve, reject, } = Promise.withResolvers();
+    const timer = setTimeout(() => {
+        void reader.cancel(buildBodyReadTimeoutError(timeoutMs)).catch(() => { });
+        reject(buildBodyReadTimeoutError(timeoutMs));
+    }, remainingMs);
+    reader.read().then((result) => {
+        clearTimeout(timer);
+        resolve(result);
+    }, (error) => {
+        clearTimeout(timer);
+        reject(error);
+    });
+    return promise;
+}
 function buildRetryMetadata(method, enabled, maxAttempts, attempts, delaysMs, timedOut) {
     return {
         method,
@@ -161,6 +206,7 @@ export class DataikuClient {
     apiKey;
     defaultProjectKey;
     requestTimeoutMs;
+    maxResponseBodyBytes;
     retryMaxAttempts;
     verbose;
     tlsOptions;
@@ -326,6 +372,7 @@ export class DataikuClient {
         this.apiKey = apiKey;
         this.defaultProjectKey = config?.projectKey?.trim() || undefined;
         this.requestTimeoutMs = config?.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this.maxResponseBodyBytes = config?.maxResponseBodyBytes ?? DEFAULT_MAX_BUFFERED_BODY_BYTES;
         const rawMax = config?.retryMaxAttempts ?? DEFAULT_RETRY_MAX_ATTEMPTS;
         this.retryMaxAttempts = Math.min(Math.max(1, rawMax), MAX_RETRY_ATTEMPTS_CAP);
         this.verbose = config?.verbose === true;
@@ -344,6 +391,13 @@ export class DataikuClient {
     getRequestTimeoutMs() {
         return this.requestTimeoutMs;
     }
+    /**
+     * The configured maximum number of bytes buffered from a single response
+     * body by the text/JSON consumer methods (default 50 MiB).
+     */
+    getMaxResponseBodyBytes() {
+        return this.maxResponseBodyBytes;
+    }
     /* ---- public: project key resolution ---- */
     resolveProjectKey(paramValue) {
         const pk = paramValue?.trim();
@@ -374,56 +428,50 @@ export class DataikuClient {
         const data = await this.parseJsonResponse(res);
         return { data, meta: this.responseMeta(res.headers), };
     }
+    /**
+     * GET returning the entire text body. The body is buffered with a hard
+     * byte cap (`maxResponseBodyBytes`, default 50 MiB) and read under the
+     * request deadline: a response exceeding the cap throws a DataikuError
+     * instead of being silently truncated, and a stalled body times out.
+     */
     async getText(path) {
         const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "GET",
             headers: this.getAnyHeaders(),
         });
-        return res.text();
+        const { text, truncated, } = await this.readBoundedBodyText(res, this.maxResponseBodyBytes);
+        if (truncated)
+            throw this.buildResponseTooLargeError(res, this.maxResponseBodyBytes);
+        return text;
     }
+    /**
+     * GET returning at most the first `maxBytes` bytes of a text body.
+     * When the response exceeds the cap the stream is cancelled, only the
+     * collected prefix is returned and `truncated` is true. The read runs
+     * under the request deadline: a stalled body throws a DataikuError.
+     */
     async getTextLimited(path, maxBytes) {
         const limit = Math.max(0, Math.floor(maxBytes));
         const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "GET",
             headers: this.getAnyHeaders(),
         });
-        if (!res.body)
-            return { text: "", truncated: false, };
-        const reader = res.body.getReader();
-        const chunks = [];
-        let bytesRead = 0;
-        let truncated = false;
-        try {
-            while (bytesRead < limit) {
-                const { done, value, } = await reader.read();
-                if (done)
-                    break;
-                const room = limit - bytesRead;
-                if (value.byteLength > room) {
-                    chunks.push(value.slice(0, room));
-                    bytesRead += room;
-                    truncated = true;
-                    break;
-                }
-                chunks.push(value);
-                bytesRead += value.byteLength;
-            }
-            if (!truncated && bytesRead >= limit) {
-                // Buffer filled exactly on a chunk boundary; peek whether more data remains.
-                const { done, } = await reader.read();
-                if (!done)
-                    truncated = true;
-            }
-        }
-        finally {
-            await reader.cancel();
-        }
-        const collected = concatBytes(chunks, bytesRead);
-        // On truncation, drop any trailing partial UTF-8 character so the decoded
-        // text never re-encodes beyond the byte cap (a stream-flush would otherwise
-        // emit a 3-byte replacement char for a split multibyte sequence).
-        const usable = truncated ? trimToUtf8Boundary(collected) : collected;
-        return { text: new TextDecoder().decode(usable), truncated, };
+        return this.readBoundedBodyText(res, limit);
+    }
+    /**
+     * GET returning at most the last `maxBytes` bytes of a text body.
+     * When the response exceeds the cap, earlier bytes are discarded, only
+     * the tail is kept and `truncated` is true — so callers that need the end
+     * of a large document (e.g. job logs) stay bounded without losing the most
+     * recent content. The read runs under the request deadline.
+     */
+    async getTextTailLimited(path, maxBytes) {
+        const limit = Math.max(0, Math.floor(maxBytes));
+        const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
+            method: "GET",
+            headers: this.getAnyHeaders(),
+        });
+        return this.readBodyTextTail(res, limit);
     }
     /**
      * POST with optional transient retry. Only opt in when repeating the request
@@ -442,13 +490,20 @@ export class DataikuClient {
         }, retryMaxAttempts);
         return this.parseJsonResponse(res);
     }
+    /**
+     * POST returning the text body, under the same bounded buffering rules as
+     * {@link getText} (byte cap `maxResponseBodyBytes`, request deadline).
+     */
     async postText(path, body) {
         const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "POST",
             headers: this.getHeaders(),
             body: body !== undefined ? JSON.stringify(body) : undefined,
         });
-        return res.text();
+        const { text, truncated, } = await this.readBoundedBodyText(res, this.maxResponseBodyBytes);
+        if (truncated)
+            throw this.buildResponseTooLargeError(res, this.maxResponseBodyBytes);
+        return text;
     }
     async postStream(path, body) {
         return this.fetchWithRetry(`${this.baseUrl}${path}`, {
@@ -571,7 +626,9 @@ export class DataikuClient {
         return undefined;
     }
     async parseJsonResponse(res) {
-        const text = await res.text();
+        const { text, truncated, } = await this.readBoundedBodyText(res, this.maxResponseBodyBytes);
+        if (truncated)
+            throw this.buildResponseTooLargeError(res, this.maxResponseBodyBytes);
         // SAFETY: Empty 2xx responses from DSS are surfaced to callers as undefined
         // cast to T. This keeps existing call sites stable, but callers that rely on
         // an object shape must guard explicitly before dereferencing the result.
@@ -582,9 +639,147 @@ export class DataikuClient {
         }
         catch {
             const summary = text.length > 300 ? `${text.slice(0, 300)}…` : text;
-            throw new DataikuError(res.status, res.statusText || "Invalid JSON response", `Expected JSON response body but got non-JSON content: ${summary}`, undefined, this.requestIdFromHeaders(res.headers));
+            throw new DataikuError(res.status, res.statusText || "Invalid JSON response", `${NON_JSON_RESPONSE_MARKER}: ${summary}`, undefined, this.requestIdFromHeaders(res.headers));
         }
     }
+    /* ---- private: bounded response body reading ---- */
+    /**
+     * Read at most `maxBytes` of a 2xx response body as UTF-8 text.
+     *
+     * The body is consumed with the request deadline still active (measured
+     * from the first read): a stalled body throws a DataikuError instead of
+     * hanging. When the stream yields more than the cap, the reader cancels the
+     * body and returns the collected prefix with `truncated: true`; truncated
+     * text is trimmed to a UTF-8 character boundary so it never decodes beyond
+     * the byte cap.
+     */
+    async readBoundedBodyText(res, maxBytes) {
+        const limit = Math.max(0, Math.floor(maxBytes));
+        if (!res.body)
+            return { text: "", truncated: false, };
+        const reader = res.body.getReader();
+        const chunks = [];
+        let bytesRead = 0;
+        let truncated = false;
+        const startedAt = Date.now();
+        try {
+            while (bytesRead < limit) {
+                const remainingMs = this.requestTimeoutMs - (Date.now() - startedAt);
+                if (remainingMs <= 0)
+                    throw buildBodyReadTimeoutError(this.requestTimeoutMs);
+                const { done, value, } = await readChunkWithDeadline(reader, remainingMs, this.requestTimeoutMs);
+                if (done)
+                    break;
+                const room = limit - bytesRead;
+                if (value.byteLength > room) {
+                    chunks.push(value.slice(0, room));
+                    bytesRead += room;
+                    truncated = true;
+                    break;
+                }
+                chunks.push(value);
+                bytesRead += value.byteLength;
+            }
+            if (!truncated && bytesRead >= limit) {
+                // Buffer filled exactly on a chunk boundary; peek whether more data remains.
+                const remainingMs = this.requestTimeoutMs - (Date.now() - startedAt);
+                if (remainingMs <= 0)
+                    throw buildBodyReadTimeoutError(this.requestTimeoutMs);
+                const { done, } = await readChunkWithDeadline(reader, remainingMs, this.requestTimeoutMs);
+                if (!done)
+                    truncated = true;
+            }
+        }
+        finally {
+            void reader.cancel().catch(() => { });
+        }
+        const collected = concatBytes(chunks, bytesRead);
+        // On truncation, drop any trailing partial UTF-8 character so the decoded
+        // text never re-encodes beyond the byte cap (a stream-flush would otherwise
+        // emit a 3-byte replacement char for a split multibyte sequence).
+        const usable = truncated ? trimToUtf8Boundary(collected) : collected;
+        return { text: new TextDecoder().decode(usable), truncated, };
+    }
+    /**
+     * Read a 2xx response body keeping only the last `maxBytes` bytes.
+     * Earlier bytes are discarded as the stream advances, so memory stays
+     * bounded by the cap plus one chunk even for arbitrarily large bodies.
+     * Returns `truncated: true` when bytes had to be dropped. Bytes that fall
+     * in the middle of a UTF-8 character are dropped from both ends so the
+     * decoded text never contains a replacement character.
+     */
+    async readBodyTextTail(res, maxBytes) {
+        const limit = Math.max(0, Math.floor(maxBytes));
+        if (!res.body)
+            return { text: "", truncated: false, };
+        const reader = res.body.getReader();
+        const ring = new Uint8Array(limit);
+        let writeOffset = 0;
+        let retainedBytes = 0;
+        let truncated = false;
+        const startedAt = Date.now();
+        try {
+            while (true) {
+                const remainingMs = this.requestTimeoutMs - (Date.now() - startedAt);
+                if (remainingMs <= 0)
+                    throw buildBodyReadTimeoutError(this.requestTimeoutMs);
+                const { done, value, } = await readChunkWithDeadline(reader, remainingMs, this.requestTimeoutMs);
+                if (done)
+                    break;
+                if (limit === 0) {
+                    truncated = value.byteLength > 0;
+                    if (truncated)
+                        break;
+                    continue;
+                }
+                if (value.byteLength >= limit) {
+                    ring.set(value.subarray(value.byteLength - limit));
+                    truncated = truncated || retainedBytes > 0 || value.byteLength > limit;
+                    retainedBytes = limit;
+                    writeOffset = 0;
+                    continue;
+                }
+                const firstLength = Math.min(value.byteLength, limit - writeOffset);
+                ring.set(value.subarray(0, firstLength), writeOffset);
+                const remainingLength = value.byteLength - firstLength;
+                if (remainingLength > 0) {
+                    ring.set(value.subarray(firstLength));
+                }
+                writeOffset = (writeOffset + value.byteLength) % limit;
+                truncated = truncated || retainedBytes + value.byteLength > limit;
+                retainedBytes = Math.min(limit, retainedBytes + value.byteLength);
+            }
+        }
+        finally {
+            void reader.cancel().catch(() => { });
+        }
+        let collected;
+        if (retainedBytes === 0) {
+            collected = new Uint8Array(0);
+        }
+        else if (retainedBytes < limit) {
+            collected = ring.slice(0, retainedBytes);
+        }
+        else if (writeOffset === 0) {
+            collected = ring;
+        }
+        else {
+            collected = new Uint8Array(retainedBytes);
+            const suffixLength = limit - writeOffset;
+            collected.set(ring.subarray(writeOffset));
+            collected.set(ring.subarray(0, writeOffset), suffixLength);
+        }
+        // A byte cut inside a multi-byte sequence can leave continuation bytes at
+        // the start (and possibly the end) of the tail; drop both so the decoded
+        // text never starts or ends with a U+FFFD replacement character.
+        const usable = truncated
+            ? trimToUtf8Boundary(trimFromUtf8BoundaryStart(collected))
+            : collected;
+        return { text: new TextDecoder().decode(usable), truncated, };
+    }
+    buildResponseTooLargeError(res, limit) {
+        return new DataikuError(res.status, RESPONSE_TOO_LARGE_STATUS_TEXT, `Response body exceeded the ${limit}-byte limit; the body was cancelled after ${limit} bytes.`, undefined, this.requestIdFromHeaders(res.headers));
+    }
     /* ---- private: retry loop ---- */
     async fetchWithRetry(url, init, retryMaxAttempts) {
         const method = (init.method ?? "GET").toUpperCase();

package/dist/src/errors.d.ts

@@ -1,5 +1,5 @@
-export type DataikuErrorCategory = "not_found" | "forbidden" | "validation" | "transient" | "unknown";
-export type StableErrorCode = "usage_error" | "unknown_flag" | "missing_required_arg" | "missing_required_flag" | "invalid_flag_value" | "conflicting_input_sources" | "invalid_enum" | "not_found" | "permission_denied" | "target_absence_unverifiable" | "validation_failed" | "transient" | "long_running_failure" | "command_result_failure" | "assertion_failed" | "ambiguous_outcome" | "internal_error";
+export type DataikuErrorCategory = "not_found" | "forbidden" | "validation" | "transient" | "unexpected_response" | "unknown";
+export type StableErrorCode = "usage_error" | "unknown_flag" | "missing_required_arg" | "missing_required_flag" | "invalid_flag_value" | "conflicting_input_sources" | "invalid_enum" | "not_found" | "permission_denied" | "target_absence_unverifiable" | "validation_failed" | "transient" | "long_running_failure" | "command_result_failure" | "assertion_failed" | "ambiguous_outcome" | "unexpected_response" | "internal_error";
 export declare function dataikuErrorCode(category: DataikuErrorCategory): StableErrorCode;
 export interface DataikuErrorTaxonomy {
     category: DataikuErrorCategory;
@@ -26,6 +26,12 @@ export declare class ClientValidationError extends Error {
     readonly details?: Record<string, unknown>;
     constructor(message: string, code?: StableErrorCode, hint?: string, details?: Record<string, unknown>);
 }
+/**
+ * Message prefix the client stamps on a 2xx body that is not JSON. The
+ * classifier recognizes exactly this prefix, so the parse-failure path and the
+ * taxonomy stay in sync as one contract.
+ */
+export declare const NON_JSON_RESPONSE_MARKER = "Expected JSON response body but got non-JSON content";
 export declare function classifyDataikuError(status: number, body: string): DataikuErrorTaxonomy;
 export declare class DataikuError extends Error {
     status: number;

package/dist/src/errors.js

@@ -8,6 +8,8 @@ export function dataikuErrorCode(category) {
             return "validation_failed";
         case "transient":
             return "transient";
+        case "unexpected_response":
+            return "unexpected_response";
         case "unknown":
             return "internal_error";
     }
@@ -17,11 +19,21 @@ const CANONICAL_STATUS_TEXT = {
     401: "Unauthorized",
     403: "Forbidden",
     404: "Not Found",
+    405: "Method Not Allowed",
+    406: "Not Acceptable",
     408: "Request Timeout",
     409: "Conflict",
+    410: "Gone",
+    412: "Precondition Failed",
+    413: "Payload Too Large",
+    415: "Unsupported Media Type",
+    416: "Range Not Satisfiable",
+    418: "I'm a Teapot",
     422: "Unprocessable Entity",
     425: "Too Early",
+    426: "Upgrade Required",
     429: "Too Many Requests",
+    451: "Unavailable For Legal Reasons",
     500: "Internal Server Error",
     501: "Not Implemented",
     502: "Bad Gateway",
@@ -43,6 +55,12 @@ export class ClientValidationError extends Error {
         this.details = details;
     }
 }
+/**
+ * Message prefix the client stamps on a 2xx body that is not JSON. The
+ * classifier recognizes exactly this prefix, so the parse-failure path and the
+ * taxonomy stay in sync as one contract.
+ */
+export const NON_JSON_RESPONSE_MARKER = "Expected JSON response body but got non-JSON content";
 const TLS_CERTIFICATE_HINT = "TLS certificate verification failed. Trust the DSS/corporate CA with --ca-cert PATH or NODE_EXTRA_CA_CERTS; use --insecure only for temporary troubleshooting.";
 const BUSINESS_APPS_API_UNAVAILABLE_HINT = "Business Apps API is not available on this DSS instance. Use classic app commands or check DSS version/feature availability.";
 const MAX_ERROR_SUMMARY_LENGTH = 200;
@@ -141,6 +159,18 @@ export function classifyDataikuError(status, body) {
             retryHint: "Network/transport failure. Retry with backoff and verify DSS URL reachability.",
         };
     }
+    // A 2xx response carrying a non-JSON body is a response-contract violation,
+    // not a transport fault: HTTP succeeded, but an intermediary (proxy, SSO or
+    // login page, HTML gateway) answered in place of the DSS API. Only the client's
+    // own parse-failure marker produces this prefix.
+    if (status >= 200 && status < 300
+        && lowerBody.startsWith(NON_JSON_RESPONSE_MARKER.toLowerCase())) {
+        return {
+            category: "unexpected_response",
+            retryable: false,
+            retryHint: "DSS returned a non-JSON response to a JSON API request (typically a proxy, gateway, or login page). Verify the DSS URL and that no intermediary serves HTML; do not retry unchanged.",
+        };
+    }
     const isSqlInputConnectionMismatch = (status === 400 || status >= 500)
         && lowerBody.includes("s3 dataset")
         && lowerBody.includes("athena connection");
@@ -280,6 +310,16 @@ export function classifyDataikuError(status, body) {
             retryHint: "Retry with exponential backoff. If it persists, check DSS availability and upstream proxies.",
         };
     }
+    // Any remaining HTTP error status is an API-contract mismatch: the endpoint,
+    // resource, or DSS feature/version does not support this request. It is
+    // non-retryable — retrying unchanged cannot succeed.
+    if (status >= 400) {
+        return {
+            category: "unexpected_response",
+            retryable: false,
+            retryHint: "The DSS API rejected the request with an unrecognized HTTP status. Verify the endpoint, resource, and DSS feature/version availability; do not retry unchanged.",
+        };
+    }
     return {
         category: "unknown",
         retryable: false,

package/dist/src/index.d.ts

@@ -18,7 +18,7 @@ export { type FlowZoneItemInput, FlowZonesResource, } from "./resources/flow-zon
 export { FoldersResource, } from "./resources/folders.js";
 export { FuturesResource, } from "./resources/futures.js";
 export { InsightsResource, } from "./resources/insights.js";
-export { computeNextPollDelayMs, type JobBuildAndWaitOptions, type JobBuildOptions, type JobBuildTarget, type JobBuildTargetType, type JobLogFilter, type JobLogProgress, type JobLogSummary, JobsResource, parseJobLogProgress, } from "./resources/jobs.js";
+export { computeNextPollDelayMs, type JobBuildAndWaitOptions, type JobBuildOptions, type JobBuildTarget, type JobBuildTargetType, type JobLogFilter, type JobLogProgress, type JobLogSummary, type JobLogUnavailableReason, JobsResource, type JobWaitOutcome, parseJobLogProgress, } from "./resources/jobs.js";
 export { MeaningsResource, } from "./resources/meanings.js";
 export { MetricsResource, } from "./resources/metrics.js";
 export * from "./resources/ml-tasks.js";
@@ -37,10 +37,11 @@ export { VariablesResource, } from "./resources/variables.js";
 export { WebappsResource, } from "./resources/webapps.js";
 export { WikiResource, } from "./resources/wiki.js";
 export { WorkspacesResource, } from "./resources/workspaces.js";
-export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZonePositionSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLibrarySchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagSchema, ProjectGitTagsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioStepRunSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "./schemas.js";
+export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvGetLogOptionsSchema, CodeEnvLogResultSchema, CodeEnvLogSummaryArraySchema, CodeEnvLogSummarySchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdateImagesOptionsSchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvVersionForProjectSchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZonePositionSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLibrarySchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagSchema, ProjectGitTagsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioStepRunSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookHistorySchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "./schemas.js";
 export type { SafeParseResult, } from "./schemas.js";
-export type { BuildMode, CodeEnvActionResult, CodeEnvCreateOptions, CodeEnvDetails, CodeEnvPackageList, CodeEnvSetPackagesOptions, CodeEnvSummary, CodeEnvUpdatePackagesOptions, CodeEnvUsage, CodeEnvWaitOptions, ConnectionSummary, DashboardDetails, DashboardSummary, DataQualityComputeResult, DataQualityProjectStatus, DataQualityRule, DataQualityRuleResult, DataQualityRules, DataQualityStatus, DataQualityStatusByPartition, DataQualityTimeline, DataQualityTimelineEntry, DatasetCreateOptions, DatasetDetails, DatasetSchema, DatasetSummary, FlowMapOptions, FlowZone, FlowZoneCreateOptions, FlowZoneItem, FlowZoneObjectType, FlowZonePosition, FlowZoneUpdateOptions, FolderCreateOptions, FolderDetails, FolderItem, FolderSummary, FutureState, FutureWaitResult, InsightDetails, InsightSummary, JobSummary, JobWaitResult, JupyterCell, JupyterNotebookContent, JupyterNotebookSummary, NotebookSession, ProjectDetails, ProjectGitActionResult, ProjectGitDiffResult, ProjectGitFutureResponse, ProjectGitFutureState, ProjectGitLibraries, ProjectGitLibrary, ProjectGitLogResult, ProjectGitRemote, ProjectGitStatus, ProjectGitTag, ProjectGitTags, ProjectMetadata, ProjectSummary, ProjectVariables, RecipeCreateOptions, RecipeCreateResult, RecipeDetails, RecipeSummary, ScenarioDetails, ScenarioStatus, ScenarioStepRun, ScenarioSummary, ScenarioWaitResult, SqlNotebookCell, SqlNotebookContent, SqlNotebookSummary, SqlQueryResponse, SqlQueryResult, SqlQuerySchema, WikiArticleData, WikiArticleMetadata, WikiSettings, WikiTaxonomyNode, } from "./schemas.js";
+export type { BuildMode, CodeEnvActionResult, CodeEnvCreateOptions, CodeEnvDetails, CodeEnvGetLogOptions, CodeEnvLogResult, CodeEnvLogSummary, CodeEnvPackageList, CodeEnvSetPackagesOptions, CodeEnvSummary, CodeEnvUpdateImagesOptions, CodeEnvUpdatePackagesOptions, CodeEnvUsage, CodeEnvVersionForProject, CodeEnvWaitOptions, ConnectionSummary, DashboardDetails, DashboardSummary, DataQualityComputeResult, DataQualityProjectStatus, DataQualityRule, DataQualityRuleResult, DataQualityRules, DataQualityStatus, DataQualityStatusByPartition, DataQualityTimeline, DataQualityTimelineEntry, DatasetCreateOptions, DatasetDetails, DatasetSchema, DatasetSummary, FlowMapOptions, FlowZone, FlowZoneCreateOptions, FlowZoneItem, FlowZoneObjectType, FlowZonePosition, FlowZoneUpdateOptions, FolderCreateOptions, FolderDetails, FolderItem, FolderSummary, FutureState, FutureWaitResult, InsightDetails, InsightSummary, JobSummary, JobWaitResult, JupyterCell, JupyterNotebookContent, JupyterNotebookSummary, NotebookSession, ProjectDetails, ProjectGitActionResult, ProjectGitDiffResult, ProjectGitFutureResponse, ProjectGitFutureState, ProjectGitLibraries, ProjectGitLibrary, ProjectGitLogResult, ProjectGitRemote, ProjectGitStatus, ProjectGitTag, ProjectGitTags, ProjectMetadata, ProjectSummary, ProjectVariables, RecipeCreateOptions, RecipeCreateResult, RecipeDetails, RecipeSummary, ScenarioDetails, ScenarioStatus, ScenarioStepRun, ScenarioSummary, ScenarioWaitResult, SqlNotebookCell, SqlNotebookContent, SqlNotebookSummary, SqlQueryResponse, SqlQueryResult, SqlQuerySchema, WikiArticleData, WikiArticleMetadata, WikiSettings, WikiTaxonomyNode, } from "./schemas.js";
 export { deepMerge, } from "./utils/deep-merge.js";
+export { type AnalyzedFlowMap, type AnalyzedFlowNode, analyzeFlowMap, type FlowMapComponent, type FlowMapDiagnostic, type FlowMapRendering, type FlowMapZone, type FlowRenderFormat, flowTopologyFingerprint, renderFlowMap, } from "./utils/flow-analysis.js";
 export { type NormalizedFlowEdge, type NormalizedFlowMap, type NormalizedFlowNode, normalizeFlowGraph, } from "./utils/flow-map.js";
 export * from "./utils/project-archive.js";
 export { sanitizeFileName, } from "./utils/sanitize.js";

package/dist/src/index.js

@@ -42,9 +42,10 @@ export { WebappsResource, } from "./resources/webapps.js";
 export { WikiResource, } from "./resources/wiki.js";
 export { WorkspacesResource, } from "./resources/workspaces.js";
 // Schemas (TypeBox schema objects for runtime validation)
-export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZonePositionSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLibrarySchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagSchema, ProjectGitTagsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioStepRunSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "./schemas.js";
+export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvGetLogOptionsSchema, CodeEnvLogResultSchema, CodeEnvLogSummaryArraySchema, CodeEnvLogSummarySchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdateImagesOptionsSchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvVersionForProjectSchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZonePositionSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLibrarySchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagSchema, ProjectGitTagsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioStepRunSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookHistorySchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "./schemas.js";
 // Utilities
 export { deepMerge, } from "./utils/deep-merge.js";
+export { analyzeFlowMap, flowTopologyFingerprint, renderFlowMap, } from "./utils/flow-analysis.js";
 export { normalizeFlowGraph, } from "./utils/flow-map.js";
 export * from "./utils/project-archive.js";
 export { sanitizeFileName, } from "./utils/sanitize.js";

package/dist/src/resources/api-services.d.ts

@@ -9,6 +9,32 @@ export interface ApiServicePackageListItem extends Record<string, unknown> {
     packageId?: string;
     serviceId?: string;
 }
+/**
+ * 64-hex SHA-256 hash of the service settings as last fetched, used as a
+ * non-atomic stale-read guard: the write is refused when the settings already
+ * differ at the verification read. DSS exposes no conditional write, so a
+ * writer committing between that read and the PUT is still not detected.
+ */
+export interface ApiServiceSaveOptions {
+    expectHash?: string;
+}
+/** Optional, documented parameters of the package-generation endpoint. */
+export interface ApiServiceCreatePackageOptions {
+    releaseNotes?: string;
+}
+/**
+ * Optional, documented parameter of the package-publish endpoint: the id of
+ * the published service on the API Deployer where the package is deployed
+ * (defaults to the service's own id server-side).
+ */
+export interface ApiServicePublishOptions {
+    publishedServiceId?: string;
+}
+export interface ApiServicePackageListItem extends Record<string, unknown> {
+    id?: string;
+    packageId?: string;
+    serviceId?: string;
+}
 export type ApiServiceActionResult = Record<string, unknown> | undefined;
 export declare class ApiServicesResource extends BaseResource {
     /** List API services in a project. */
@@ -17,24 +43,40 @@ export declare class ApiServicesResource extends BaseResource {
     create(serviceId: string, projectKey?: string): Promise<ApiServiceActionResult>;
     /** Get API service settings, including endpoint definitions. */
     getSettings(serviceId: string, projectKey?: string): Promise<Record<string, unknown>>;
-    /** Save API service settings. */
-    saveSettings(serviceId: string, body: Record<string, unknown>, projectKey?: string): Promise<ApiServiceActionResult>;
+    /**
+     * Save API service settings with explicit replacement semantics: the body
+     * is the complete settings object (fetched via get-settings) and is PUT
+     * as-is. With `expectHash` armed, the settings are read first and their
+     * stable hash must match, or the write is refused before any PUT.
+     */
+    saveSettings(serviceId: string, body: Record<string, unknown>, projectKey?: string, options?: ApiServiceSaveOptions): Promise<ApiServiceActionResult>;
     /** Add a standard prediction endpoint backed by a saved model. */
     addPredictionEndpoint(serviceId: string, endpointId: string, savedModelId: string, projectKey?: string): Promise<ApiServiceActionResult>;
     /** List deployable packages for an API service. */
     listPackages(serviceId: string, projectKey?: string): Promise<ApiServicePackageListItem[]>;
     /** Get an API service package summary. */
     getPackageSummary(serviceId: string, packageId: string, projectKey?: string): Promise<Record<string, unknown>>;
-    /** Create a deployable package from the current service state. */
-    createPackage(serviceId: string, packageId: string, projectKey?: string): Promise<{
+    /**
+     * Create a deployable package from the current service state. The
+     * documented optional `releaseNotes` parameter is forwarded as the
+     * `releaseNotes` query parameter when provided.
+     */
+    createPackage(serviceId: string, packageId: string, projectKey?: string, options?: ApiServiceCreatePackageOptions): Promise<{
         message: string;
     }>;
     /** Delete an API service package. */
     deletePackage(serviceId: string, packageId: string, projectKey?: string): Promise<void>;
     /** Download an API service package archive. */
     downloadPackageArchive(serviceId: string, packageId: string, projectKey?: string): Promise<Response>;
-    /** Publish an API service package to the API Deployer. */
-    publishPackage(serviceId: string, packageId: string, projectKey?: string): Promise<ApiServiceActionResult>;
+    /**
+     * Publish an API service package to the API Deployer. The documented
+     * optional `publishedServiceId` parameter selects the published service
+     * the package is deployed to (a new published service is created when no
+     * match exists; when omitted, the server falls back to the service's own
+     * id). It is forwarded as the `publishedServiceId` query parameter when
+     * provided.
+     */
+    publishPackage(serviceId: string, packageId: string, projectKey?: string, options?: ApiServicePublishOptions): Promise<ApiServiceActionResult>;
     private servicePath;
     private packagePath;
 }