dataiku-sdk 3.4.0 → 3.6.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, NON_JSON_RESPONSE_MARKER, } from "./errors.js";
+import { classifyDataikuError, ClientValidationError, DataikuError, nonJsonResponseBody, } from "./errors.js";
 import { AnalysesResource, } from "./resources/analyses.js";
 import { ApiDeployerResource, } from "./resources/api-deployer.js";
 import { ApiServicesResource, } from "./resources/api-services.js";
@@ -187,7 +187,7 @@ function buildFetchTlsOptions(config) {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            throw new Error(`Unable to read CA certificate bundle at ${caCertPath}: ${message}`, {
+            throw new ClientValidationError(`Unable to read CA certificate bundle at ${caCertPath}: ${message}`, "invalid_flag_value", undefined, undefined, {
                 cause: error,
             });
         }
@@ -416,12 +416,14 @@ export class DataikuClient {
         return (this.groupsResource ??= new GroupsResource(this));
     }
     constructor(config) {
+        /* oxlint-disable dss/no-direct-process-env -- SDK constructor defaults (DATAIKU_URL/DATAIKU_API_KEY) for library callers */
         const envUrl = process.env["DATAIKU_URL"]?.trim();
         const envApiKey = process.env["DATAIKU_API_KEY"]?.trim();
+        /* oxlint-enable dss/no-direct-process-env */
         const url = config?.url?.trim() || envUrl;
         const apiKey = config?.apiKey?.trim() || envApiKey;
         if (!url || !apiKey) {
-            throw new Error("Dataiku URL and API key are required: pass {url, apiKey} or set DATAIKU_URL/DATAIKU_API_KEY");
+            throw new ClientValidationError("Dataiku URL and API key are required: pass {url, apiKey} or set DATAIKU_URL/DATAIKU_API_KEY", "missing_required_flag");
         }
         if (hasEmbeddedUserinfo(url)) {
             throw new ClientValidationError("Dataiku URL must not contain embedded credentials (userinfo). Authenticate with an API key instead.", "validation_failed", "Pass the DSS base URL without a username or password.", { urlHasEmbeddedUserinfo: true, });
@@ -463,12 +465,12 @@ export class DataikuClient {
             return pk;
         if (this.defaultProjectKey)
             return this.defaultProjectKey;
-        throw new Error("projectKey is required — pass it as a parameter or set projectKey in DataikuClientConfig");
+        throw new ClientValidationError("projectKey is required — pass it as a parameter or set projectKey in DataikuClientConfig", "missing_required_flag", "Pass --project-key or set DATAIKU_PROJECT_KEY.");
     }
     /* ---- public: HTTP verbs ---- */
     async get(path, options) {
         const deadlineAt = resolveGetDeadlineAt(options);
-        const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, { method: "GET", headers: this.getHeaders(), }, options?.noRetry === true ? 1 : undefined, deadlineAt);
+        const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, { method: "GET", headers: this.getHeaders(false), }, options?.noRetry === true ? 1 : undefined, deadlineAt);
         return this.parseJsonResponse(res, deadlineAt);
     }
     /**
@@ -479,7 +481,7 @@ export class DataikuClient {
     async getWithMetadata(path) {
         const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "GET",
-            headers: this.getHeaders(),
+            headers: this.getHeaders(false),
         });
         const data = await this.parseJsonResponse(res);
         return { data, meta: this.responseMeta(res.headers), };
@@ -541,7 +543,7 @@ export class DataikuClient {
         }
         const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "POST",
-            headers: this.getHeaders(),
+            headers: this.getHeaders(body !== undefined),
             body: body !== undefined ? JSON.stringify(body) : undefined,
         }, retryMaxAttempts);
         return this.parseJsonResponse(res);
@@ -553,7 +555,7 @@ export class DataikuClient {
     async postText(path, body) {
         const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "POST",
-            headers: this.getHeaders(),
+            headers: this.getHeaders(body !== undefined),
             body: body !== undefined ? JSON.stringify(body) : undefined,
         });
         const { text, truncated, } = await this.readBoundedBodyText(res, this.maxResponseBodyBytes);
@@ -598,7 +600,7 @@ export class DataikuClient {
     async put(path, body) {
         const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "PUT",
-            headers: this.getHeaders(),
+            headers: this.getHeaders(true),
             body: JSON.stringify(body),
         });
         return this.parseJsonResponse(res);
@@ -606,13 +608,13 @@ export class DataikuClient {
     async del(path) {
         await this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "DELETE",
-            headers: this.getHeaders(),
+            headers: this.getHeaders(false),
         });
     }
     async putVoid(path, body) {
         await this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "PUT",
-            headers: this.getHeaders(),
+            headers: this.getHeaders(true),
             body: JSON.stringify(body),
         });
     }
@@ -624,7 +626,7 @@ export class DataikuClient {
     async putVoidNoBody(path) {
         await this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "PUT",
-            headers: this.getHeaders(),
+            headers: this.getHeaders(false),
         });
     }
     /**
@@ -729,11 +731,12 @@ export class DataikuClient {
         return response;
     }
     /* ---- private: headers ---- */
-    getHeaders() {
+    /** JSON request headers; Content-Type only when a body is sent. */
+    getHeaders(withBody) {
         return {
             Authorization: `Bearer ${this.apiKey}`,
             Accept: "application/json",
-            "Content-Type": "application/json",
+            ...(withBody ? { "Content-Type": "application/json", } : {}),
         };
     }
     getAnyHeaders() {
@@ -810,8 +813,7 @@ export class DataikuClient {
             return JSON.parse(text);
         }
         catch {
-            const summary = text.length > 300 ? `${text.slice(0, 300)}…` : text;
-            throw new DataikuError(res.status, res.statusText || "Invalid JSON response", `${NON_JSON_RESPONSE_MARKER}: ${summary}`, undefined, this.requestIdFromHeaders(res.headers));
+            throw new DataikuError(res.status, res.statusText || "Invalid JSON response", nonJsonResponseBody(text), undefined, this.requestIdFromHeaders(res.headers));
         }
     }
     /* ---- private: bounded response body reading ---- */
@@ -1029,7 +1031,20 @@ export class DataikuClient {
                     elapsedMs: Date.now() - startedAt,
                 });
                 if (!res.ok) {
-                    const { text, truncated, } = await this.readBoundedBodyText(res, this.maxResponseBodyBytes, startedAt + attemptTimeoutMs);
+                    // The status is already known; a body that misses the deadline must not
+                    // turn a real 5xx/4xx into a bare transport timeout.
+                    let text = "";
+                    let truncated = false;
+                    try {
+                        ({ text, truncated, } = await this.readBoundedBodyText(res, this.maxResponseBodyBytes, startedAt + attemptTimeoutMs));
+                    }
+                    catch (bodyError) {
+                        // Oversized bodies keep their own classified error; any other read
+                        // failure (deadline abort, dropped connection) keeps the known status.
+                        if (bodyError instanceof DataikuError && bodyError.status !== 0)
+                            throw bodyError;
+                        text = `(response body not received within ${attemptTimeoutMs}ms)`;
+                    }
                     const canRetry = retryEnabled && attempt < maxAttempts && isTransientError(res.status, text);
                     const serverDelayMs = canRetry ? retryAfterDelayMs(res.headers.get("retry-after")) : 0;
                     // A longer server wait declines automatic retry; never clamp it into an early request.

package/dist/src/errors.d.ts

@@ -26,7 +26,7 @@ export declare class ClientValidationError extends Error {
     readonly code: StableErrorCode;
     readonly hint?: string;
     readonly details?: Record<string, unknown>;
-    constructor(message: string, code?: StableErrorCode, hint?: string, details?: Record<string, unknown>);
+    constructor(message: string, code?: StableErrorCode, hint?: string, details?: Record<string, unknown>, options?: ErrorOptions);
 }
 /**
  * Message prefix the client stamps on a 2xx body that is not JSON. The
@@ -34,6 +34,17 @@ export declare class ClientValidationError extends Error {
  * taxonomy stay in sync as one contract.
  */
 export declare const NON_JSON_RESPONSE_MARKER = "Expected JSON response body but got non-JSON content";
+/** Body text for a 2xx response that should have been JSON; truncated to keep envelopes bounded. */
+export declare function nonJsonResponseBody(text: string): string;
+/** Prefix for a 2xx DSS response that lacks something the API documents (a body, an id, a job id). */
+export declare const UNEXPECTED_RESPONSE_MARKER = "Unexpected DSS response";
+/**
+ * The one representation of a malformed 2xx DSS response: a DataikuError whose
+ * body carries {@link UNEXPECTED_RESPONSE_MARKER}, classified `unexpected_response`.
+ */
+export declare function unexpectedResponseError(detail: string, status?: number): DataikuError;
+/** Prefix for a SQL query failure reported by DSS on a 2xx finish-streaming response. */
+export declare const SQL_QUERY_FAILED_MARKER = "SQL query failed in DSS";
 export declare function classifyDataikuError(status: number, body: string): DataikuErrorTaxonomy;
 export declare class DataikuError extends Error {
     status: number;

package/dist/src/errors.js

@@ -47,8 +47,8 @@ export class ClientValidationError extends Error {
     code;
     hint;
     details;
-    constructor(message, code = "validation_failed", hint, details) {
-        super(message);
+    constructor(message, code = "validation_failed", hint, details, options) {
+        super(message, options);
         this.name = "ClientValidationError";
         this.code = code;
         this.hint = hint;
@@ -61,6 +61,21 @@ export class ClientValidationError extends Error {
  * taxonomy stay in sync as one contract.
  */
 export const NON_JSON_RESPONSE_MARKER = "Expected JSON response body but got non-JSON content";
+/** Body text for a 2xx response that should have been JSON; truncated to keep envelopes bounded. */
+export function nonJsonResponseBody(text) {
+    return `${NON_JSON_RESPONSE_MARKER}: ${text.length > 300 ? `${text.slice(0, 300)}…` : text}`;
+}
+/** Prefix for a 2xx DSS response that lacks something the API documents (a body, an id, a job id). */
+export const UNEXPECTED_RESPONSE_MARKER = "Unexpected DSS response";
+/**
+ * The one representation of a malformed 2xx DSS response: a DataikuError whose
+ * body carries {@link UNEXPECTED_RESPONSE_MARKER}, classified `unexpected_response`.
+ */
+export function unexpectedResponseError(detail, status = 200) {
+    return new DataikuError(status, "Unexpected Response", `${UNEXPECTED_RESPONSE_MARKER}: ${detail}`);
+}
+/** Prefix for a SQL query failure reported by DSS on a 2xx finish-streaming response. */
+export const SQL_QUERY_FAILED_MARKER = "SQL query failed in DSS";
 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;
@@ -166,13 +181,23 @@ export function classifyDataikuError(status, body) {
     // 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())) {
+        && (lowerBody.startsWith(NON_JSON_RESPONSE_MARKER.toLowerCase())
+            || lowerBody.startsWith(UNEXPECTED_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.",
         };
     }
+    // finish-streaming answers 2xx with the server-side failure text when the
+    // query itself failed (bad SQL, missing column, permissions on the source).
+    if (status >= 200 && status < 300 && lowerBody.startsWith(SQL_QUERY_FAILED_MARKER.toLowerCase())) {
+        return {
+            category: "validation",
+            retryable: false,
+            retryHint: "The SQL query failed in DSS. Fix the query or its inputs; do not retry unchanged.",
+        };
+    }
     const isSqlInputConnectionMismatch = (status === 400 || status >= 500)
         && lowerBody.includes("s3 dataset")
         && lowerBody.includes("athena connection");

package/dist/src/index.d.ts

@@ -46,9 +46,7 @@ export { WebappsResource, } from "./resources/webapps.js";
 export { WikiResource, } from "./resources/wiki.js";
 export { WorkspacesResource, } from "./resources/workspaces.js";
 export { computeNextPollDelayMs, } from "./utils/polling.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, MacroDefinitionSchema, MacroRunStartSchema, MacroStateSchema, MacroSummaryArraySchema, MacroSummarySchema, MacroWaitResultSchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLibrarySchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagSchema, ProjectGitTagsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectTagsSchema, 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, 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, MacroDefinition, MacroRunStart, MacroState, MacroSummary, MacroSummaryArray, MacroWaitResult, NotebookSession, ProjectDetails, ProjectGitActionResult, ProjectGitDiffResult, ProjectGitFutureResponse, ProjectGitFutureState, ProjectGitLibraries, ProjectGitLibrary, ProjectGitLogResult, ProjectGitRemote, ProjectGitStatus, ProjectGitTag, ProjectGitTags, ProjectMetadata, ProjectSummary, ProjectTags, ProjectVariables, RecipeCreateOptions, RecipeCreateResult, RecipeDetails, RecipeSummary, ScenarioDetails, ScenarioStatus, ScenarioStepRun, ScenarioSummary, ScenarioWaitResult, SqlNotebookCell, SqlNotebookContent, SqlNotebookSummary, SqlQueryResponse, SqlQueryResult, SqlQuerySchema, WikiArticleData, WikiArticleMetadata, WikiSettings, WikiTaxonomyNode, } from "./schemas.js";
+export * 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";

package/dist/src/index.js

@@ -50,8 +50,8 @@ export { WebappsResource, } from "./resources/webapps.js";
 export { WikiResource, } from "./resources/wiki.js";
 export { WorkspacesResource, } from "./resources/workspaces.js";
 export { computeNextPollDelayMs, } from "./utils/polling.js";
-// Schemas (TypeBox schema objects for runtime validation)
-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, MacroDefinitionSchema, MacroRunStartSchema, MacroStateSchema, MacroSummaryArraySchema, MacroSummarySchema, MacroWaitResultSchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLibrarySchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagSchema, ProjectGitTagsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectTagsSchema, 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";
+// Schemas, derived types, and parse helpers
+export * from "./schemas.js";
 // Utilities
 export { deepMerge, } from "./utils/deep-merge.js";
 export { analyzeFlowMap, flowTopologyFingerprint, renderFlowMap, } from "./utils/flow-analysis.js";

package/dist/src/resources/api-services.js

@@ -1,9 +1,8 @@
 import { ClientValidationError, } from "../errors.js";
-import { stableHash, } from "../utils/stable-hash.js";
+import { SHA256_HEX_PATTERN, stableHash, } from "../utils/stable-hash.js";
 import { BaseResource, } from "./base.js";
-const EXPECT_HASH_PATTERN = /^[0-9a-fA-F]{64}$/;
 function assertExpectedSettingsHash(serviceId, expectHash, current, projectKey) {
-    if (!EXPECT_HASH_PATTERN.test(expectHash)) {
+    if (!SHA256_HEX_PATTERN.test(expectHash)) {
         throw new ClientValidationError("Expected API service settings hash must be a 64-character SHA-256 hex digest.", "validation_failed", "Use the hash value returned by a previous read.", { projectKey, serviceId, });
     }
     const actual = stableHash(current);

package/dist/src/resources/applications.js

@@ -1,6 +1,6 @@
 import { ClientValidationError, DataikuError, } from "../errors.js";
 import { projectIncarnationHash, } from "../utils/project-incarnation.js";
-import { compareStrings, stableHash, stableJson, } from "../utils/stable-hash.js";
+import { compareStrings, SHA256_HEX_PATTERN, stableHash, stableJson, } from "../utils/stable-hash.js";
 import { BaseResource, } from "./base.js";
 /**
  * Source-verifiable app-manifest reference locations. Validation is scoped to
@@ -93,8 +93,6 @@ function omitRootFields(value, omitted) {
     }
     return result;
 }
-/** Lowercase or uppercase SHA-256 hex digest, as emitted by `stableHash`. */
-const EXPECT_HASH_PATTERN = /^[0-9a-fA-F]{64}$/;
 /**
  * Project a manifest onto its version state. Only string values count: a
  * non-string `version` is reported as null rather than coerced, so callers can
@@ -295,7 +293,7 @@ export class ApplicationsResource extends BaseResource {
         }
         const expectHash = update.expectHash;
         if (expectHash !== undefined
-            && (typeof expectHash !== "string" || !EXPECT_HASH_PATTERN.test(expectHash))) {
+            && (typeof expectHash !== "string" || !SHA256_HEX_PATTERN.test(expectHash))) {
             throw new ClientValidationError("Expected manifest hash must be a 64-character SHA-256 hex digest.", "validation_failed", "Use the manifestHash value returned by the manifest-version read.", { projectKey: pk, });
         }
         if (update.dryRun !== undefined && typeof update.dryRun !== "boolean") {

package/dist/src/resources/base.d.ts

@@ -3,6 +3,8 @@ import type { DataikuClient } from "../client.js";
 export declare function requireArrayResponse<T>(value: unknown, operation: string): T[];
 /** Validate identifiers without changing significant whitespace or encoding. */
 export declare function requireNonEmpty(value: unknown, name: string): string;
+export declare function requireObject(value: unknown, name: string): Record<string, unknown>;
+export declare function requireNonEmptyArray(value: string[], name: string): string[];
 export declare abstract class BaseResource {
     protected readonly client: DataikuClient;
     constructor(client: DataikuClient);

package/dist/src/resources/base.js

@@ -1,8 +1,8 @@
-import { ClientValidationError, DataikuError, } from "../errors.js";
+import { ClientValidationError, unexpectedResponseError, } from "../errors.js";
 /** Never disguise an unexpected successful HTTP payload as an empty listing. */
 export function requireArrayResponse(value, operation) {
     if (!Array.isArray(value)) {
-        throw new DataikuError(200, "Unexpected Response", `${operation}: DSS did not return an array.`);
+        throw unexpectedResponseError(`${operation}: DSS did not return an array.`);
     }
     return value;
 }
@@ -13,6 +13,18 @@ export function requireNonEmpty(value, name) {
     }
     return value;
 }
+export function requireObject(value, name) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new ClientValidationError(`${name} must be a JSON object.`, "validation_failed");
+    }
+    return value;
+}
+export function requireNonEmptyArray(value, name) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new ClientValidationError(`${name} must be a non-empty array.`, "validation_failed");
+    }
+    return value;
+}
 export class BaseResource {
     client;
     constructor(client) {

package/dist/src/resources/code-envs.js

@@ -1,5 +1,6 @@
 import { ClientValidationError, } from "../errors.js";
 import { CodeEnvLogSummaryArraySchema, CodeEnvSummaryArraySchema, CodeEnvUsageArraySchema, CodeEnvVersionForProjectSchema, } from "../schemas.js";
+import { isRecord, } from "../utils/records.js";
 import { stableHash, } from "../utils/stable-hash.js";
 import { BaseResource, } from "./base.js";
 /** Byte cap applied to fetched code-env logs so stdout/JSON stays bounded. */
@@ -158,7 +159,7 @@ export class CodeEnvsResource extends BaseResource {
         let raw;
         if (envLang !== undefined || envName !== undefined) {
             if (!envLang || !envName) {
-                throw new Error("codeEnvs.listUsages requires both envLang and envName when either is provided");
+                throw new ClientValidationError("codeEnvs.listUsages requires both envLang and envName when either is provided", "validation_failed");
             }
             const langEnc = encodeURIComponent(envLang);
             const nameEnc = encodeURIComponent(envName);
@@ -191,7 +192,7 @@ function tailLog(log, maxLines) {
  */
 function assertDefinitionHash(envLang, envName, current, expected) {
     const currentHash = stableHash(current);
-    if (currentHash === expected)
+    if (currentHash === expected.toLowerCase())
         return;
     throw new ClientValidationError(`Code env ${envLang}/${envName} changed since the expected definition hash was captured; refusing to overwrite it.`, "validation_failed", "Re-read the definition with dss code-env get-definition (definitionHash comes from code-env get), review the diff, and retry with the fresh hash.", {
         envLang,
@@ -212,6 +213,3 @@ function normalizePackageList(packages) {
     const lines = Array.isArray(packages) ? packages : packages.split(/\r?\n/);
     return lines.map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}

package/dist/src/resources/data-quality.js

@@ -1,8 +1,8 @@
-import { DataikuError, } from "../errors.js";
+import { DataikuError, unexpectedResponseError, } from "../errors.js";
 import { DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineSchema, } from "../schemas.js";
 import { deepMerge, } from "../utils/deep-merge.js";
 import { BaseResource, } from "./base.js";
-function datasetPath(projectKey, datasetName) {
+function dataQualityPath(projectKey, datasetName) {
     return `/public/api/projects/${encodeURIComponent(projectKey)}/datasets/${encodeURIComponent(datasetName)}/data-quality`;
 }
 function addQuery(params, name, value) {
@@ -22,7 +22,7 @@ function projectPath(projectKey) {
 export class DataQualityResource extends BaseResource {
     async rules(datasetName, projectKey) {
         const pk = this.resolveProjectKey(projectKey);
-        const raw = await this.client.get(`${datasetPath(pk, datasetName)}/rules`);
+        const raw = await this.client.get(`${dataQualityPath(pk, datasetName)}/rules`);
         return this.client.safeParse(DataQualityRulesSchema, raw, "dataQuality.rules");
     }
     async listRules(datasetName, projectKey) {
@@ -31,21 +31,21 @@ export class DataQualityResource extends BaseResource {
     }
     async createRule(datasetName, opts) {
         const pk = this.resolveProjectKey(opts.projectKey);
-        const raw = await this.client.post(`${datasetPath(pk, datasetName)}/rules`, opts.config);
+        const raw = await this.client.post(`${dataQualityPath(pk, datasetName)}/rules`, opts.config);
         return this.client.safeParse(DataQualityRuleSchema, raw, "dataQuality.createRule");
     }
     async updateRule(datasetName, ruleId, opts) {
         const current = await this.getRule(datasetName, ruleId, opts.projectKey);
         const next = deepMerge(current, opts.data);
         const pk = this.resolveProjectKey(opts.projectKey);
-        await this.client.putVoid(`${datasetPath(pk, datasetName)}/rules/${encodeURIComponent(ruleId)}`, next);
+        await this.client.putVoid(`${dataQualityPath(pk, datasetName)}/rules/${encodeURIComponent(ruleId)}`, next);
         return this.client.safeParse(DataQualityRuleSchema, next, "dataQuality.updateRule");
     }
     async deleteRule(datasetName, ruleId, projectKey) {
         const pk = this.resolveProjectKey(projectKey);
         const params = new URLSearchParams();
         params.set("ruleId", ruleId);
-        await this.client.del(`${datasetPath(pk, datasetName)}/rules/${encodeURIComponent(ruleId)}${queryString(params)}`);
+        await this.client.del(`${dataQualityPath(pk, datasetName)}/rules/${encodeURIComponent(ruleId)}${queryString(params)}`);
     }
     async getRule(datasetName, ruleId, projectKey) {
         const rules = await this.listRules(datasetName, projectKey);
@@ -57,14 +57,14 @@ export class DataQualityResource extends BaseResource {
     }
     async status(datasetName, projectKey) {
         const pk = this.resolveProjectKey(projectKey);
-        const raw = await this.client.get(`${datasetPath(pk, datasetName)}/status-by-partition`);
+        const raw = await this.client.get(`${dataQualityPath(pk, datasetName)}/status-by-partition`);
         return this.client.safeParse(DataQualityStatusSchema, raw, "dataQuality.status");
     }
     async statusByPartition(datasetName, opts = {}) {
         const pk = this.resolveProjectKey(opts.projectKey);
         const params = new URLSearchParams();
         addQuery(params, "includeAllPartitions", opts.includeAllPartitions);
-        const raw = await this.client.get(`${datasetPath(pk, datasetName)}/status-by-partition${queryString(params)}`);
+        const raw = await this.client.get(`${dataQualityPath(pk, datasetName)}/status-by-partition${queryString(params)}`);
         return this.client.safeParse(DataQualityStatusByPartitionSchema, raw, "dataQuality.statusByPartition");
     }
     async lastResults(datasetName, opts = {}) {
@@ -72,7 +72,7 @@ export class DataQualityResource extends BaseResource {
         const params = new URLSearchParams();
         addQuery(params, "partition", partitionValue(opts.partition));
         addQuery(params, "ruleId", opts.ruleId);
-        const raw = await this.client.get(`${datasetPath(pk, datasetName)}/last-rules-result${queryString(params)}`);
+        const raw = await this.client.get(`${dataQualityPath(pk, datasetName)}/last-rules-result${queryString(params)}`);
         return this.client.safeParse(DataQualityRuleResultArraySchema, raw, "dataQuality.lastResults");
     }
     async history(datasetName, opts = {}) {
@@ -83,7 +83,7 @@ export class DataQualityResource extends BaseResource {
         addQuery(params, "resultsPerPage", opts.resultsPerPage);
         addQuery(params, "page", opts.page);
         addQuery(params, "ruleId", opts.ruleId);
-        const raw = await this.client.get(`${datasetPath(pk, datasetName)}/rules-history${queryString(params)}`);
+        const raw = await this.client.get(`${dataQualityPath(pk, datasetName)}/rules-history${queryString(params)}`);
         return this.client.safeParse(DataQualityRuleResultArraySchema, raw, "dataQuality.history");
     }
     async computeRules(datasetName, opts = {}) {
@@ -91,13 +91,14 @@ export class DataQualityResource extends BaseResource {
         const params = new URLSearchParams();
         addQuery(params, "partition", partitionValue(opts.partition));
         addQuery(params, "ruleId", opts.ruleId);
-        const raw = await this.client.post(`${datasetPath(pk, datasetName)}/actions/compute-rules${queryString(params)}`);
+        const raw = await this.client.post(`${dataQualityPath(pk, datasetName)}/actions/compute-rules${queryString(params)}`);
         return this.client.safeParse(DataQualityComputeResultSchema, raw, "dataQuality.computeRules");
     }
     async computeRulesAndWait(datasetName, opts = {}) {
         const future = await this.computeRules(datasetName, opts);
-        if (!future.jobId)
-            throw new Error("Data quality compute did not return a future jobId.");
+        if (!future.jobId) {
+            throw unexpectedResponseError("Data quality compute did not return a future jobId.");
+        }
         return this.client.futures.wait(future.jobId, {
             pollIntervalMs: opts.pollIntervalMs,
             timeoutMs: opts.timeoutMs,

package/dist/src/resources/datasets.d.ts

@@ -89,6 +89,19 @@ export interface UploadDatasetFileResult {
 export declare function validateStreamColumns(headerRow: string[], expectedColumns: {
     name: string;
 }[]): string[];
+/** Wire body for POST /datasets/; shared with `dataset create --plan` so the plan matches the request. */
+export declare function buildDatasetCreateBody(opts: {
+    projectKey: string;
+    datasetName: string;
+    connection?: string;
+    dsType: string;
+    table?: string;
+    dbSchema?: string;
+    catalog?: string;
+    formatType?: string;
+    formatParams?: Record<string, unknown>;
+    managed?: boolean;
+}): Record<string, unknown>;
 export declare function buildDatasetCloneSettings(source: DatasetDetails, targetName: string, projectKey: string, opts: DatasetCloneOptions): Record<string, unknown>;
 export declare class DatasetsResource extends BaseResource {
     /** List all datasets in a project. */

package/dist/src/resources/datasets.js

@@ -462,7 +462,7 @@ function tsvToCsvTransform(maxDataRows, stats, onHeader, spreadsheetSafe = true)
             catch (error) {
                 // Byte-limit overflow: destroy the transform so the pipeline
                 // cancels the response and the partial file is removed.
-                callback(error instanceof Error ? error : new Error(String(error)));
+                callback(error instanceof Error ? error : new ClientValidationError(String(error), "internal_error"));
                 return;
             }
             if (done) {
@@ -485,7 +485,7 @@ function tsvToCsvTransform(maxDataRows, stats, onHeader, spreadsheetSafe = true)
                 flushTsvStream(state, (row) => handleRow(row, (line) => queueLine(this, line)));
             }
             catch (error) {
-                callback(error instanceof Error ? error : new Error(String(error)));
+                callback(error instanceof Error ? error : new ClientValidationError(String(error), "internal_error"));
                 return;
             }
             // Emit the trailing partial batch; without this the last rows of a
@@ -518,7 +518,8 @@ function isMissingUploadedFilesTargetConnection(error) {
     return (detail.includes("without a target connection")
         || detail.includes("target connection is required"));
 }
-function buildDatasetCreateBody(opts) {
+/** Wire body for POST /datasets/; shared with `dataset create --plan` so the plan matches the request. */
+export function buildDatasetCreateBody(opts) {
     if (opts.dsType.toLowerCase() === "uploadedfiles") {
         return {
             projectKey: opts.projectKey,
@@ -637,7 +638,7 @@ export function buildDatasetCloneSettings(source, targetName, projectKey, opts)
         && source.managed === true
         && sourcePath !== undefined
         && settingsParams.path === sourcePath) {
-        throw new Error(`Refusing to clone managed dataset "${source.name}" with the same storage path. Pass a new path or allowSamePath: true.`);
+        throw new ClientValidationError(`Refusing to clone managed dataset "${source.name}" with the same storage path. Pass a new path or allowSamePath: true.`, "validation_failed");
     }
     return settings;
 }

package/dist/src/resources/flow-zones.js

@@ -1,3 +1,4 @@
+import { ClientValidationError, } from "../errors.js";
 import { FlowZoneArraySchema, FlowZoneSchema, } from "../schemas.js";
 import { deepMerge, } from "../utils/deep-merge.js";
 import { BaseResource, } from "./base.js";
@@ -48,8 +49,9 @@ export class FlowZonesResource extends BaseResource {
     }
     /** Move items into a flow zone. */
     async moveItems(zoneId, items, projectKey) {
-        if (items.length === 0)
-            throw new Error("flowZones.moveItems requires at least one item");
+        if (items.length === 0) {
+            throw new ClientValidationError("flowZones.moveItems requires at least one item", "validation_failed");
+        }
         const raw = await this.client.post(`/public/api/projects/${this.enc(projectKey)}/flow/zones/${encodeURIComponent(zoneId)}/add-items`, items.map(normalizeZoneItem));
         return this.client.safeParse(FlowZoneSchema, raw, "flowZones.moveItems");
     }

package/dist/src/resources/folders.js

@@ -1,4 +1,5 @@
 import * as nodePath from "node:path";
+import { unexpectedResponseError, } from "../errors.js";
 import { FolderDetailsSchema, FolderItemArraySchema, FolderSummaryArraySchema, } from "../schemas.js";
 import { deepMerge, } from "../utils/deep-merge.js";
 import { writeResponseToFile, } from "../utils/response-file.js";
@@ -70,8 +71,9 @@ export class FoldersResource extends BaseResource {
         const normalizedPath = normalizeRemotePath(path);
         const pEnc = encodeURIComponent(normalizedPath);
         const res = await this.client.stream(`/public/api/projects/${this.enc(opts?.projectKey)}/managedfolders/${fEnc}/contents/${pEnc}`);
-        if (!res.body)
-            throw new Error("folders.download response did not include a body");
+        if (!res.body) {
+            throw unexpectedResponseError("folders.download response did not include a body");
+        }
         const dest = opts?.localPath
             ?? nodePath.resolve(process.cwd(), inferDownloadFileName(normalizedPath));
         await writeResponseToFile(dest, res);

package/dist/src/resources/futures.js

@@ -1,8 +1,6 @@
 import { FutureStateSchema, FutureWaitResultSchema, } from "../schemas.js";
-import { computeNextPollDelayMs, isRequestDeadlineError, } from "../utils/polling.js";
+import { computeNextPollDelayMs, DEFAULT_POLL_INTERVAL_MS, DEFAULT_TIMEOUT_MS, isRequestDeadlineError, } from "../utils/polling.js";
 import { BaseResource, } from "./base.js";
-const DEFAULT_POLL_INTERVAL_MS = 2_000;
-const DEFAULT_TIMEOUT_MS = 120_000;
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/dist/src/resources/insights.js

@@ -1,3 +1,4 @@
+import { ClientValidationError, unexpectedResponseError, } from "../errors.js";
 import { InsightDetailsSchema, InsightSummaryArraySchema, } from "../schemas.js";
 import { deepMerge, } from "../utils/deep-merge.js";
 import { BaseResource, } from "./base.js";
@@ -33,7 +34,7 @@ export class InsightsResource extends BaseResource {
         const pk = this.resolveProjectKey(opts.projectKey);
         const prototype = applyInsightFields(opts.data ?? {}, opts);
         if (!hasCreateShape(prototype)) {
-            throw new Error("Insight create requires name and type, either as options or in data.");
+            throw new ClientValidationError("Insight create requires name and type, either as options or in data.", "validation_failed");
         }
         if (prototype.projectKey === undefined)
             prototype.projectKey = pk;
@@ -43,7 +44,7 @@ export class InsightsResource extends BaseResource {
             ...(opts.payload !== undefined ? { payload: opts.payload, } : {}),
         });
         if (typeof created.id !== "string" || created.id.length === 0) {
-            throw new Error("Insight create response did not include an id.");
+            throw unexpectedResponseError("Insight create response did not include an id.");
         }
         return this.get(created.id, pk);
     }