dataiku-sdk 3.4.0 → 3.5.0

package/dist/src/cli.js

@@ -4,7 +4,7 @@ import { homedir, } from "node:os";
 import { resolve, } from "node:path";
 import { num, unknownJsonInput, } from "./cli/coerce.js";
 import { commands, } from "./cli/commands/index.js";
-import { dataikuEnvironmentEnabled, loadEnvFile, } from "./cli/env.js";
+import { ambientProjectKey, loadEnvFile, } from "./cli/env.js";
 import { executionMode, FLAG_ALIASES, isNegativeNumberToken, parseArgs, SHORT_FLAGS, VALUE_FLAGS, } from "./cli/flags.js";
 import { cleanupLedgerEntry, } from "./cli/helpers/cleanup.js";
 import { commandFailureExitCode, CommandResultFailure, flushCliWarnings, isFailedWaitResult, planResult, projectResultFields, setOutputFieldProjection, writeCommandResult, } from "./cli/output.js";
@@ -334,32 +334,11 @@ function validateSupportedCommandFlags(resource, action, flags) {
             ? "Remove --dry-run; use --plan to preview the mutation instead."
             : `Remove --dry-run; ${resource} ${action} has no dry-run mode.`);
     }
-}
-function stripOptionalUsageGroupsForValidation(usage) {
-    let stripped = "";
-    let optionalDepth = 0;
-    for (const char of usage) {
-        if (char === "[") {
-            optionalDepth++;
-            if (optionalDepth === 1)
-                stripped += " ";
-            continue;
-        }
-        if (char === "]" && optionalDepth > 0) {
-            optionalDepth--;
-            if (optionalDepth === 0)
-                stripped += " ";
-            continue;
-        }
-        if (optionalDepth === 0)
-            stripped += char;
+    // Registry commands reject --plan in buildMutationPlan; meta commands never reach it.
+    if (META_COMMAND_RESOURCES[resource] === true && executionMode(flags).plan
+        && !entry.flags.some((flag) => flag.name === "plan")) {
+        throw new UsageError(`--plan is only supported for mutating commands; ${resource} ${action} has no plan mode.`, "usage_error", `Remove --plan; ${resource} ${action} has no plan mode.`);
     }
-    return stripped;
-}
-function requiredPositionalCount(usage) {
-    const requiredUsage = stripOptionalUsageGroupsForValidation(usage);
-    const positionalTokens = [...requiredUsage.matchAll(/<[^>]+>/g),];
-    return positionalTokens.length;
 }
 function flagIsProvided(flags, name, allowEmpty = false) {
     const value = flags[name];
@@ -370,7 +349,7 @@ function flagIsProvided(flags, name, allowEmpty = false) {
     return allowEmpty || value.length > 0;
 }
 function validateRequiredCommandInputs(resource, action, args, flags, entry) {
-    const argCount = requiredPositionalCount(entry.usage);
+    const argCount = entry.positionalArguments.filter((positional) => positional.required).length;
     const allowEmptyFlags = {};
     for (const flag of entry.flags) {
         if (flag.allowEmptyValue === true)
@@ -776,6 +755,7 @@ async function runMetaCommand(resource, action, flags) {
             throw unknownActionError("doctor", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
+        validateSupportedCommandFlags("doctor", "run", flags);
         const { runDoctor, } = await import("./cli/doctor.js");
         const { result, exitCode, } = await runDoctor(flags);
         return { action: "run", result, exitCode, };
@@ -791,6 +771,7 @@ async function runMetaCommand(resource, action, flags) {
         if (!authMeta) {
             throw unknownActionError("auth", action, validActions, "auth only supports 'login'. To check credentials/connectivity, run 'dss doctor'.");
         }
+        validateSupportedCommandFlags("auth", action, flags);
         if (executionMode(flags).plan) {
             return { action, result: authLoginPlan(flags), exitCode: 0, };
         }
@@ -802,6 +783,7 @@ async function runMetaCommand(resource, action, flags) {
             throw unknownActionError("install-skill", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
+        validateSupportedCommandFlags("install-skill", "run", flags);
         return { action: "run", result: await runInstallSkill(flags), exitCode: 0, };
     }
     if (resource === "agent") {
@@ -811,6 +793,7 @@ async function runMetaCommand(resource, action, flags) {
         currentCommandContext.action = action;
         if (action !== "contract")
             throw unknownActionError("agent", action, ["contract",]);
+        validateSupportedCommandFlags("agent", "contract", flags);
         return { action, result: contract.buildAgentContract(), exitCode: 0, };
     }
     if (resource === "commands") {
@@ -856,10 +839,12 @@ async function runMetaCommand(resource, action, flags) {
         };
     }
     if (resource === "version") {
+        await loadCommandRuntime();
         if (action !== undefined && action !== "run") {
             throw unknownActionError("version", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
+        validateSupportedCommandFlags("version", "run", flags);
         return { action: "run", result: cliVersionResult(), exitCode: 0, };
     }
     if (resource === "cleanup") {
@@ -868,6 +853,10 @@ async function runMetaCommand(resource, action, flags) {
             throw unknownActionError("cleanup", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
+        validateSupportedCommandFlags("cleanup", "run", flags);
+        if (flags["apply"] === true && executionMode(flags).dryRun) {
+            throw new UsageError("--dry-run and --apply are mutually exclusive.", "usage_error");
+        }
         if (executionMode(flags).plan) {
             return { action: "run", result: cleanupPlan(flags), exitCode: 0, };
         }
@@ -880,6 +869,7 @@ async function runMetaCommand(resource, action, flags) {
             throw unknownActionError("fixtures", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
+        validateSupportedCommandFlags("fixtures", "run", flags);
         const { runFixtures, } = await import("./cli/doctor.js");
         return { action: "run", result: await runFixtures(flags), exitCode: 0, };
     }
@@ -889,6 +879,7 @@ async function runMetaCommand(resource, action, flags) {
             throw unknownActionError("batch", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
+        validateSupportedCommandFlags("batch", "run", flags);
         if (executionMode(flags).plan) {
             return { action: "run", result: batchPlan(flags), exitCode: 0, };
         }
@@ -993,9 +984,7 @@ async function runBatch(flags) {
     if (executionMode(flags).dryRun) {
         const batchProjectKey = typeof flags["project-key"] === "string"
             ? flags["project-key"]
-            : dataikuEnvironmentEnabled()
-                ? process.env.DATAIKU_PROJECT_KEY
-                : undefined;
+            : ambientProjectKey();
         const planned = await Promise.all(steps.map(async (argv, index) => {
             const context = batchStepCommandContext(argv);
             Object.assign(currentCommandContext, { ...context, projectKey: batchProjectKey, });
@@ -1018,7 +1007,8 @@ async function runBatch(flags) {
                 };
             }
             catch (error) {
-                const envelope = buildErrorReport(error);
+                // Steps validate concurrently; the shared context may belong to a sibling.
+                const envelope = buildErrorReport(error, { ...context, projectKey: batchProjectKey, });
                 return {
                     index,
                     args: redactArgv(argv),
@@ -1037,9 +1027,7 @@ async function runBatch(flags) {
     validateBatchStepModes(steps);
     let projectKey = typeof flags["project-key"] === "string"
         ? flags["project-key"]
-        : dataikuEnvironmentEnabled()
-            ? process.env.DATAIKU_PROJECT_KEY
-            : undefined;
+        : ambientProjectKey();
     let client;
     const needsClient = steps.some((argv) => batchStepNeedsClient(argv));
     if (needsClient) {
@@ -1247,8 +1235,7 @@ function rawFlagValue(argv, flagName) {
 function commandIsProjectScoped(resource, action) {
     if (!resource)
         return false;
-    const usage = commands[resource]?.[action ?? ""]?.usage ?? "";
-    return inferRequiresProject(resource, action ?? "", usage);
+    return inferRequiresProject(resource, action ?? "");
 }
 function rawCommandContext() {
     const argv = process.argv.slice(2);
@@ -1256,15 +1243,13 @@ function rawCommandContext() {
     const resource = currentCommandContext.resource ?? positionals[0];
     const action = currentCommandContext.action ?? positionals[1];
     const explicitProjectKey = rawFlagValue(argv, "project-key") ?? rawFlagValue(argv, "project");
-    const ambientProjectKey = dataikuEnvironmentEnabled()
-        ? process.env.DATAIKU_PROJECT_KEY
-        : undefined;
+    const environmentProjectKey = ambientProjectKey();
     return {
         resource,
         action,
         projectKey: explicitProjectKey
             ?? (commandIsProjectScoped(resource, action)
-                ? currentCommandContext.projectKey ?? ambientProjectKey
+                ? currentCommandContext.projectKey ?? environmentProjectKey
                 : undefined),
     };
 }
@@ -1364,7 +1349,6 @@ function dssDiagnosticDetails(err) {
         return {};
     }
 }
-const MISSING_PROJECT_KEY_ERROR_PREFIX = "projectKey is required";
 function isAmbiguousMutationFailure(err, context) {
     if (!(err instanceof DataikuError))
         return false;
@@ -1399,9 +1383,11 @@ function boundedFailureResult(result) {
 function errorExitCode(err) {
     if (err instanceof CommandResultFailure)
         return err.exitCode;
-    if (err instanceof ClientValidationError && err.code === "assertion_failed")
+    if (err instanceof ClientValidationError
+        && (err.code === "assertion_failed" || err.code === "long_running_failure"))
         return 4;
-    if (err instanceof ClientValidationError && err.code === "ambiguous_outcome")
+    if (err instanceof ClientValidationError
+        && (err.code === "ambiguous_outcome" || err.code === "internal_error"))
         return 2;
     if (err instanceof UsageError || err instanceof ClientValidationError)
         return 1;
@@ -1409,15 +1395,14 @@ function errorExitCode(err) {
         return 2;
     if (err instanceof DataikuError)
         return err.category === "transient" ? 3 : 2;
-    if (err instanceof Error && err.message.startsWith(MISSING_PROJECT_KEY_ERROR_PREFIX))
-        return 1;
     return 2;
 }
-function buildErrorReport(err) {
-    const context = rawCommandContext();
+function buildErrorReport(err, contextOverride) {
+    const context = contextOverride ?? rawCommandContext();
     const exitCode = errorExitCode(err);
     if (err instanceof ClientValidationError
-        && (err.code === "ambiguous_outcome" || err.code === "assertion_failed")) {
+        && (err.code === "ambiguous_outcome" || err.code === "assertion_failed"
+            || err.code === "long_running_failure")) {
         return {
             type: "error",
             ok: false,
@@ -1439,7 +1424,9 @@ function buildErrorReport(err) {
             code: err.code,
             category: err.code === "target_absence_unverifiable"
                 ? "permission_or_environment"
-                : "usage",
+                : err.code === "internal_error"
+                    ? "internal"
+                    : "usage",
             exitCode,
             ...(err.code === "target_absence_unverifiable" ? { retryable: false, } : {}),
             ...(err.hint ? { hint: err.hint, } : {}),
@@ -1517,18 +1504,6 @@ function buildErrorReport(err) {
             ...context,
         };
     }
-    if (err instanceof Error && err.message.startsWith(MISSING_PROJECT_KEY_ERROR_PREFIX)) {
-        return {
-            type: "error",
-            ok: false,
-            error: err.message,
-            code: "missing_required_flag",
-            category: "usage",
-            exitCode,
-            hint: "Pass --project-key or set DATAIKU_PROJECT_KEY.",
-            ...context,
-        };
-    }
     const message = err instanceof Error ? err.message : String(err);
     return {
         type: "error",
@@ -1579,9 +1554,7 @@ async function main() {
         action: positional[1],
         projectKey: typeof flags["project-key"] === "string"
             ? flags["project-key"]
-            : dataikuEnvironmentEnabled()
-                ? process.env.DATAIKU_PROJECT_KEY
-                : undefined,
+            : ambientProjectKey(),
     });
     const metaCommand = await runMetaCommand(resource, positional[1], flags);
     if (metaCommand) {

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,7 +465,7 @@ 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) {
@@ -810,8 +812,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 ---- */

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/code-envs.js

@@ -158,7 +158,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 +191,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,

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

@@ -1,4 +1,4 @@
-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";
@@ -96,8 +96,9 @@ export class DataQualityResource extends BaseResource {
     }
     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));
 }