dataiku-sdk 3.4.0 → 3.5.0

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);
     }

package/dist/src/resources/jobs.js

@@ -1,9 +1,7 @@
-import { DataikuError, } from "../errors.js";
+import { ClientValidationError, DataikuError, } from "../errors.js";
 import { JobSummaryArraySchema, } 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;
 const DEFAULT_MAX_LOG_LINES = 500;
 /**
  * Default bytes retained from a job log body (default 10 MiB). Logs larger
@@ -51,7 +49,7 @@ function jobBuildOutput(target, defaultProjectKey, defaultPartition, defaultTarg
 }
 function jobBuildDefinition(targets, defaultProjectKey, opts) {
     if (targets.length === 0) {
-        throw new Error("At least one build target is required.");
+        throw new ClientValidationError("At least one build target is required.", "validation_failed");
     }
     const payload = {
         outputs: targets.map((target) => jobBuildOutput(target, defaultProjectKey, opts?.partition, opts?.targetType)),
@@ -203,7 +201,7 @@ export class JobsResource extends BaseResource {
         const jobId = parsed.searchParams.get("jobId") ?? undefined;
         const activity = parsed.searchParams.get("activityId") ?? undefined;
         if (!projectKey || !jobId || !activity) {
-            throw new Error("Log URL must include projectKey, jobId, and activityId query parameters.");
+            throw new ClientValidationError("Log URL must include projectKey, jobId, and activityId query parameters.", "validation_failed");
         }
         return this.log(jobId, {
             activity,

package/dist/src/resources/macros.js

@@ -1,9 +1,7 @@
 import { ClientValidationError, DataikuError, } from "../errors.js";
 import { MacroDefinitionSchema, MacroRunStartSchema, MacroStateSchema, MacroSummaryArraySchema, MacroWaitResultSchema, } 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, requireNonEmpty, } from "./base.js";
-const DEFAULT_POLL_INTERVAL_MS = 2_000;
-const DEFAULT_TIMEOUT_MS = 120_000;
 /** Hard floor for the result download cap; keeps a caller typo from hanging the read. */
 const MIN_RESULT_MAX_BYTES = 1;
 const MAX_RESULT_MAX_BYTES = 2 * 1024 * 1024 * 1024;
@@ -121,7 +119,7 @@ export class MacrosResource extends BaseResource {
         const maxBytes = macroResultMaxBytes(opts?.maxBytes);
         const raw = await this.client.getTextLimited(`${this.base(runnableType, opts?.projectKey)}/result/${encodeURIComponent(runId)}`, maxBytes);
         if (raw.truncated) {
-            throw new Error(`Macro result exceeded ${String(maxBytes)} bytes; retry with a larger maxBytes.`);
+            throw new ClientValidationError(`Macro result exceeded ${String(maxBytes)} bytes; retry with a larger maxBytes.`, "validation_failed");
         }
         const text = raw.text;
         const trimmed = text.trim();

package/dist/src/resources/notebooks.js

@@ -1,8 +1,7 @@
 import { ClientValidationError, DataikuError, } from "../errors.js";
 import { JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, NotebookSessionArraySchema, SqlNotebookContentSchema, SqlNotebookHistorySchema, SqlNotebookSummaryArraySchema, } from "../schemas.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}$/;
 export class NotebooksResource extends BaseResource {
     // ── Jupyter Notebooks ──────────────────────────────────────────────
     /**
@@ -260,7 +259,7 @@ export class NotebooksResource extends BaseResource {
     }
     /** Validate the armed `--expect-hash` value into a comparable hex digest. */
     validatedExpectHash(expectHash, pk, resourceLabel, id) {
-        if (!EXPECT_HASH_PATTERN.test(expectHash)) {
+        if (!SHA256_HEX_PATTERN.test(expectHash)) {
             throw new ClientValidationError(`Expected ${resourceLabel} hash must be a 64-character SHA-256 hex digest.`, "validation_failed", "Use the hash value returned by a previous save or read.", { projectKey: pk, id, });
         }
         return expectHash.toLowerCase();

package/dist/src/resources/project-git.js

@@ -1,7 +1,7 @@
-import { ClientValidationError, } from "../errors.js";
+import { ClientValidationError, DataikuError, nonJsonResponseBody, } from "../errors.js";
 import { ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagsSchema, } from "../schemas.js";
 import { encodeGitReferencePath, validateGitReferencePath, } from "../utils/git-reference.js";
-import { computeNextPollDelayMs, isRequestDeadlineError, } from "../utils/polling.js";
+import { computeNextPollDelayMs, DEFAULT_POLL_INTERVAL_MS, DEFAULT_TIMEOUT_MS, isRequestDeadlineError, } from "../utils/polling.js";
 import { sanitizeErrorSecrets, } from "../utils/secret-sanitize.js";
 import { BaseResource, } from "./base.js";
 /**
@@ -13,8 +13,6 @@ const GIT_API_BASE = "/dip/publicapi";
 const DEFAULT_REMOTE = "origin";
 const DEFAULT_LOG_COUNT = 1_000;
 const DEFAULT_TAG_REFERENCE = "HEAD";
-const DEFAULT_POLL_INTERVAL_MS = 2_000;
-const DEFAULT_TIMEOUT_MS = 120_000;
 function sleep(ms) {
     const { promise, resolve, } = Promise.withResolvers();
     setTimeout(resolve, ms);
@@ -362,7 +360,7 @@ export class ProjectGitResource extends BaseResource {
             // the loop reports the documented timeout from the last observed
             // state instead of issuing a request the budget cannot cover.
             if (lastState !== undefined && elapsedBeforeMs >= timeoutMs) {
-                throw new Error(`Timed out after ${String(elapsedBeforeMs)}ms waiting for Dataiku future ${jobId}`);
+                throw new ClientValidationError(`Timed out after ${String(elapsedBeforeMs)}ms waiting for Dataiku future ${jobId}`, "long_running_failure");
             }
             // Unlike peek state, the ordinary state includes the completed result.
             // Requests issued while budget remains are bounded by the remaining
@@ -386,23 +384,23 @@ export class ProjectGitResource extends BaseResource {
                 // error escape.
                 if (!isRequestDeadlineError(error, startedAt + timeoutMs))
                     throw error;
-                throw new Error(`Timed out after ${String(Date.now() - startedAt)}ms waiting for Dataiku future ${jobId}`, { cause: error, });
+                throw new ClientValidationError(`Timed out after ${String(Date.now() - startedAt)}ms waiting for Dataiku future ${jobId}`, "long_running_failure", undefined, undefined, { cause: error, });
             }
             lastState = state;
             const failure = describeFutureFailure(state.error);
             if (failure !== undefined) {
-                throw new Error(`Dataiku future ${jobId} failed: ${failure}`);
+                throw new ClientValidationError(`Dataiku future ${jobId} failed: ${failure}`, "long_running_failure");
             }
             if (state.aborted === true) {
-                throw new Error(`Dataiku future ${jobId} was aborted`);
+                throw new ClientValidationError(`Dataiku future ${jobId} was aborted`, "long_running_failure");
             }
             if (state.hasResult === true)
                 return state.result;
             if (state.unknown === true) {
-                throw new Error(`Dataiku future ${jobId} is unknown to the server`);
+                throw new ClientValidationError(`Dataiku future ${jobId} is unknown to the server`, "long_running_failure");
             }
             if (state.alive === false) {
-                throw new Error(`Dataiku future ${jobId} ended without producing a result`);
+                throw new ClientValidationError(`Dataiku future ${jobId} ended without producing a result`, "long_running_failure");
             }
             const elapsedMs = Date.now() - startedAt;
             // Deadline reached: the guard at the top of the loop reports the
@@ -449,7 +447,7 @@ export class ProjectGitResource extends BaseResource {
                 return JSON.parse(text);
             }
             catch {
-                throw new Error(`Dataiku Git API returned a non-JSON response for ${method} ${path}`);
+                throw new DataikuError(res.status, "Invalid JSON response", nonJsonResponseBody(text));
             }
         }
         catch (error) {

package/dist/src/resources/project-library.d.ts

@@ -75,8 +75,6 @@ export interface ProjectLibraryDiffResult {
  * checked; it can never turn the subsequent POST into a conditional write.
  */
 export declare const PROJECT_LIBRARY_CONCURRENCY_CONTROL = "client-side-non-atomic-stale-read-check";
-/** Lowercase or uppercase SHA-256 hex digest. */
-export declare const EXPECT_SHA256_PATTERN: RegExp;
 /**
  * Validate and canonicalize a project library path.
  *

package/dist/src/resources/project-library.js

@@ -1,5 +1,5 @@
-import { createHash, } from "node:crypto";
 import { ClientValidationError, DataikuError, } from "../errors.js";
+import { SHA256_HEX_PATTERN, sha256Hex, } from "../utils/stable-hash.js";
 import { BaseResource, } from "./base.js";
 /**
  * The only concurrency control the public project-library API permits. DSS
@@ -8,11 +8,6 @@ import { BaseResource, } from "./base.js";
  * checked; it can never turn the subsequent POST into a conditional write.
  */
 export const PROJECT_LIBRARY_CONCURRENCY_CONTROL = "client-side-non-atomic-stale-read-check";
-/** Lowercase or uppercase SHA-256 hex digest. */
-export const EXPECT_SHA256_PATTERN = /^[0-9a-fA-F]{64}$/;
-function sha256Hex(value) {
-    return createHash("sha256").update(value).digest("hex");
-}
 const CONTROL_CHARACTER_RE = /[\u0000-\u001f\u007f]/;
 const BACKSLASH_RE = /\\/;
 const TRAILING_AMBIGUOUS_RE = /[\s.]$/;
@@ -376,7 +371,7 @@ export class ProjectLibraryResource extends BaseResource {
         }
         const expectSha256 = options?.expectSha256;
         if (expectSha256 !== undefined
-            && (typeof expectSha256 !== "string" || !EXPECT_SHA256_PATTERN.test(expectSha256))) {
+            && (typeof expectSha256 !== "string" || !SHA256_HEX_PATTERN.test(expectSha256))) {
             throw new ClientValidationError("expectSha256 must be a 64-character SHA-256 hex digest.", "validation_failed", "Use the sha256 value returned by a project library read or diff.", { path: valid, });
         }
         let beforeSha256;

package/dist/src/resources/projects.js

@@ -1,4 +1,4 @@
-import { ClientValidationError, DataikuError, } from "../errors.js";
+import { ClientValidationError, DataikuError, unexpectedResponseError, } from "../errors.js";
 import { isRequestDeadlineError, } from "../utils/polling.js";
 import { writeResponseToFile, } from "../utils/response-file.js";
 import { ProjectDetailsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectTagsSchema, } from "../schemas.js";
@@ -140,8 +140,9 @@ export class ProjectsResource extends BaseResource {
     /** Export a project archive to a local file. */
     async exportArchive(projectKey, filePath, options) {
         const res = await this.client.postStream(`/public/api/projects/${encodeURIComponent(projectKey)}/export`, options ?? {});
-        if (!res.body)
-            throw new Error("projects.exportArchive response did not include a body");
+        if (!res.body) {
+            throw unexpectedResponseError("projects.exportArchive response did not include a body");
+        }
         await writeResponseToFile(filePath, res);
     }
     /** Upload a project archive and return its temporary import handle. */

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

@@ -1,6 +1,11 @@
 import type { BuildMode, JobWaitResult, ProjectMetadata, RecipeCreateOptions, RecipeCreateResult, RecipeSummary } from "../schemas.js";
 import { BaseResource } from "./base.js";
 import type { JobBuildTarget, JobBuildTargetType, JobLogFilter, JobLogSummary } from "./jobs.js";
+type JoinType = "LEFT" | "INNER" | "RIGHT" | "FULL";
+type JoinKeyPair = {
+    left: string;
+    right: string;
+};
 export interface RecipeRunOutput extends JobBuildTarget {
     ref: string;
     role: string;
@@ -65,6 +70,28 @@ export interface RecipeCloneResult {
     payloadTextRewrites: Record<string, string>;
     copiedOutputDatasets: string[];
 }
+/**
+ * Pure request construction for POST /recipes/ (no DSS calls). Shared with
+ * `recipe create --plan` so the plan equals the request the command sends.
+ */
+export declare function buildRecipeCreateRequest(opts: RecipeCreateOptions, pk: string): {
+    creationSettings: Record<string, unknown>;
+    fuzzyDistance: string | undefined;
+    fuzzyKeys: JoinKeyPair[] | undefined;
+    fuzzyThreshold: number;
+    inputDatasets: string[] | undefined;
+    inputs: Record<string, unknown>;
+    joinKeys: JoinKeyPair[] | undefined;
+    name: string;
+    normalizedJoinType: JoinType | undefined;
+    outputFolder: string | undefined;
+    outputs: Record<string, unknown>;
+    payload: string | undefined;
+    rawConnection: string | undefined;
+    recipePrototype: Record<string, unknown>;
+    temporaryOutputDataset: string | undefined;
+    type: string;
+};
 export declare class RecipesResource extends BaseResource {
     /** List all recipes in a project. */
     list(projectKey?: string): Promise<RecipeSummary[]>;
@@ -144,3 +171,4 @@ export declare class RecipesResource extends BaseResource {
         projectKey?: string;
     }): Promise<string>;
 }
+export {};

package/dist/src/resources/recipes.js

@@ -1,6 +1,6 @@
 import { writeFile, } from "node:fs/promises";
 import { resolve, } from "node:path";
-import { DataikuError, } from "../errors.js";
+import { ClientValidationError, DataikuError, nonJsonResponseBody, unexpectedResponseError, } from "../errors.js";
 import { ProjectMetadataSchema, RecipeSummaryArraySchema, } from "../schemas.js";
 import { deepMerge, } from "../utils/deep-merge.js";
 import { sanitizeFileName, } from "../utils/sanitize.js";
@@ -25,7 +25,13 @@ function asRecord(value) {
 function parseRecipePayload(payload) {
     if (!payload)
         return {};
-    const parsed = JSON.parse(payload);
+    let parsed;
+    try {
+        parsed = JSON.parse(payload);
+    }
+    catch {
+        throw new DataikuError(200, "Invalid JSON response", nonJsonResponseBody(payload));
+    }
     return asRecord(parsed) ?? {};
 }
 function parseJoinKeyPairs(values, optionName = "joinOn") {
@@ -41,8 +47,9 @@ function parseJoinKeyPairs(values, optionName = "joinOn") {
         }
         const left = token.slice(0, eq).trim();
         const right = token.slice(eq + 1).trim();
-        if (!left || !right)
-            throw new Error(`${optionName} values must use COL or LEFT=RIGHT.`);
+        if (!left || !right) {
+            throw new ClientValidationError(`${optionName} values must use COL or LEFT=RIGHT.`, "validation_failed");
+        }
         pairs.push({ left, right, });
     }
     return pairs;
@@ -57,7 +64,7 @@ function normalizeFuzzyDistance(value) {
         || normalized === "EUCLIDEAN") {
         return normalized;
     }
-    throw new Error("fuzzyDistance must be one of DAMERAU_LEVENSHTEIN, HAMMING, JACCARD, COSINE, or EUCLIDEAN.");
+    throw new ClientValidationError("fuzzyDistance must be one of DAMERAU_LEVENSHTEIN, HAMMING, JACCARD, COSINE, or EUCLIDEAN.", "validation_failed");
 }
 function normalizeJoinType(value) {
     const normalized = typeof value === "string" && value.trim().length > 0
@@ -67,7 +74,7 @@ function normalizeJoinType(value) {
         || normalized === "FULL") {
         return normalized;
     }
-    throw new Error("joinType must be one of LEFT, INNER, RIGHT, or FULL.");
+    throw new ClientValidationError("joinType must be one of LEFT, INNER, RIGHT, or FULL.", "validation_failed");
 }
 function recipeVirtualInputs(payload, inputCount) {
     const current = Array.isArray(payload.virtualInputs) ? payload.virtualInputs : [];
@@ -208,7 +215,7 @@ function rewriteSqlTableReferences(payload, rewrites) {
                 return `${keyword}${space}[${escapedTo}]`;
             }
             if (!bareIdentifierPattern.test(to)) {
-                throw new Error(`Unsafe SQL rewrite target for ${from}: ${to}`);
+                throw new ClientValidationError(`Unsafe SQL rewrite target for ${from}: ${to}`, "validation_failed");
             }
             return `${keyword}${space}${to}`;
         });
@@ -292,6 +299,96 @@ function shouldRetryRecipeCreateWithOutputProvisioning(error) {
 // ---------------------------------------------------------------------------
 // Resource
 // ---------------------------------------------------------------------------
+/**
+ * Pure request construction for POST /recipes/ (no DSS calls). Shared with
+ * `recipe create --plan` so the plan equals the request the command sends.
+ */
+export function buildRecipeCreateRequest(opts, pk) {
+    const { type, payload, outputConnection: rawConnection, joinType: rawJoinType, } = opts;
+    const outputFolder = asString(opts.outputFolder);
+    // Build inputs/outputs from simple form (inputDatasets + outputDataset) or
+    // advanced form (inputs + outputs); both may coexist — simple form wins when
+    // the advanced form is absent.
+    const inputDatasets = asStringArray(opts.inputDatasets);
+    const requestedOutputDataset = asString(opts.outputDataset);
+    let inputs = asRecord(opts.inputs);
+    let outputs = asRecord(opts.outputs);
+    if (!inputs) {
+        inputs = {
+            main: {
+                items: inputDatasets?.map((ref) => ({ ref, deps: [], })) ?? [],
+            },
+        };
+    }
+    // Auto-generate name if not provided
+    const outputNameForDefaultRecipe = requestedOutputDataset ?? outputFolder;
+    const name = opts.name ?? (type && outputNameForDefaultRecipe
+        ? `${type}_${outputNameForDefaultRecipe}`
+        : undefined);
+    const temporaryOutputDataset = outputFolder && !requestedOutputDataset && name
+        ? `${name}_folder_output_marker`
+        : undefined;
+    const outputDataset = requestedOutputDataset ?? temporaryOutputDataset;
+    if (!outputs && outputDataset) {
+        outputs = {
+            main: {
+                items: [{ ref: outputDataset, appendMode: false, },],
+            },
+        };
+    }
+    if (!type || !name || !outputs) {
+        throw new ClientValidationError("type and outputDataset/outputFolder or (name + outputs) are required for create.", "validation_failed");
+    }
+    const joinCols = typeof opts.joinOn === "string" ? [opts.joinOn,] : asStringArray(opts.joinOn);
+    const joinKeys = type === "join" && joinCols?.length
+        ? parseJoinKeyPairs(joinCols)
+        : undefined;
+    const fuzzyOn = opts.fuzzyOn ?? (type === "fuzzyjoin" ? opts.joinOn : undefined);
+    const fuzzyCols = typeof fuzzyOn === "string" ? [fuzzyOn,] : asStringArray(fuzzyOn);
+    const fuzzyKeys = type === "fuzzyjoin" && fuzzyCols?.length
+        ? parseJoinKeyPairs(fuzzyCols, "fuzzyOn")
+        : undefined;
+    const normalizedJoinType = joinKeys?.length || fuzzyKeys?.length
+        ? normalizeJoinType(rawJoinType)
+        : undefined;
+    const fuzzyDistance = fuzzyKeys?.length ? normalizeFuzzyDistance(opts.fuzzyDistance) : undefined;
+    const fuzzyThreshold = opts.fuzzyThreshold ?? 1;
+    if (!Number.isFinite(fuzzyThreshold)) {
+        throw new ClientValidationError("fuzzyThreshold must be a finite number.", "validation_failed");
+    }
+    const recipePrototype = {
+        type,
+        name,
+        projectKey: pk,
+        ...(type === "fuzzyjoin" ? {} : { inputs, }),
+        outputs,
+    };
+    const creationSettings = {};
+    if (payload !== undefined) {
+        creationSettings.script = payload;
+    }
+    if (type === "fuzzyjoin") {
+        creationSettings.virtualInputs = recipeInputItems({ inputs, }).map((item) => item.ref);
+    }
+    return {
+        creationSettings,
+        fuzzyDistance,
+        fuzzyKeys,
+        fuzzyThreshold,
+        inputDatasets,
+        inputs,
+        joinKeys,
+        name,
+        normalizedJoinType,
+        outputFolder,
+        outputs,
+        payload,
+        rawConnection,
+        recipePrototype,
+        temporaryOutputDataset,
+        type,
+    };
+}
 export class RecipesResource extends BaseResource {
     /** List all recipes in a project. */
     async list(projectKey) {
@@ -433,7 +530,7 @@ export class RecipesResource extends BaseResource {
         const { recipe, } = await this.get(recipeName, { projectKey: pk, });
         const outputItems = recipeOutputItems(recipe);
         if (outputItems.length === 0) {
-            throw new Error(`Recipe "${recipeName}" has no output items to build.`);
+            throw new ClientValidationError(`Recipe "${recipeName}" has no output items to build.`, "validation_failed");
         }
         const [datasets, folders,] = await Promise.all([
             this.client.datasets.list(pk),
@@ -483,7 +580,7 @@ export class RecipesResource extends BaseResource {
             }
             const isDataset = datasetNames.has(item.ref);
             if (isDataset && folderId) {
-                throw new Error(`Recipe "${recipeName}" output "${item.ref}" matches both a dataset and a managed folder. Add an explicit output type to the recipe definition or build the target directly with --target-type.`);
+                throw new ClientValidationError(`Recipe "${recipeName}" output "${item.ref}" matches both a dataset and a managed folder. Add an explicit output type to the recipe definition or build the target directly with --target-type.`, "validation_failed");
             }
             if (folderId) {
                 return {
@@ -505,7 +602,7 @@ export class RecipesResource extends BaseResource {
                     partition: opts?.partition,
                 };
             }
-            throw new Error(`Recipe "${recipeName}" output "${item.ref}" was not found as a dataset or managed folder in project "${pk}".`);
+            throw new ClientValidationError(`Recipe "${recipeName}" output "${item.ref}" was not found as a dataset or managed folder in project "${pk}".`, "validation_failed");
         });
     }
     /** Run a recipe by building its resolved outputs. */
@@ -543,72 +640,7 @@ export class RecipesResource extends BaseResource {
     async create(opts) {
         const pk = this.resolveProjectKey(opts.projectKey);
         const enc = encodeURIComponent(pk);
-        const { type, payload, outputConnection: rawConnection, joinType: rawJoinType, } = opts;
-        const outputFolder = asString(opts.outputFolder);
-        // Build inputs/outputs from simple form (inputDatasets + outputDataset) or
-        // advanced form (inputs + outputs); both may coexist — simple form wins when
-        // the advanced form is absent.
-        const inputDatasets = asStringArray(opts.inputDatasets);
-        const requestedOutputDataset = asString(opts.outputDataset);
-        let inputs = asRecord(opts.inputs);
-        let outputs = asRecord(opts.outputs);
-        if (!inputs) {
-            inputs = {
-                main: {
-                    items: inputDatasets?.map((ref) => ({ ref, deps: [], })) ?? [],
-                },
-            };
-        }
-        // Auto-generate name if not provided
-        const outputNameForDefaultRecipe = requestedOutputDataset ?? outputFolder;
-        const name = opts.name ?? (type && outputNameForDefaultRecipe
-            ? `${type}_${outputNameForDefaultRecipe}`
-            : undefined);
-        const temporaryOutputDataset = outputFolder && !requestedOutputDataset && name
-            ? `${name}_folder_output_marker`
-            : undefined;
-        const outputDataset = requestedOutputDataset ?? temporaryOutputDataset;
-        if (!outputs && outputDataset) {
-            outputs = {
-                main: {
-                    items: [{ ref: outputDataset, appendMode: false, },],
-                },
-            };
-        }
-        if (!type || !name || !outputs) {
-            throw new Error("type and outputDataset/outputFolder or (name + outputs) are required for create.");
-        }
-        const joinCols = typeof opts.joinOn === "string" ? [opts.joinOn,] : asStringArray(opts.joinOn);
-        const joinKeys = type === "join" && joinCols?.length
-            ? parseJoinKeyPairs(joinCols)
-            : undefined;
-        const fuzzyOn = opts.fuzzyOn ?? (type === "fuzzyjoin" ? opts.joinOn : undefined);
-        const fuzzyCols = typeof fuzzyOn === "string" ? [fuzzyOn,] : asStringArray(fuzzyOn);
-        const fuzzyKeys = type === "fuzzyjoin" && fuzzyCols?.length
-            ? parseJoinKeyPairs(fuzzyCols, "fuzzyOn")
-            : undefined;
-        const normalizedJoinType = joinKeys?.length || fuzzyKeys?.length
-            ? normalizeJoinType(rawJoinType)
-            : undefined;
-        const fuzzyDistance = fuzzyKeys?.length ? normalizeFuzzyDistance(opts.fuzzyDistance) : undefined;
-        const fuzzyThreshold = opts.fuzzyThreshold ?? 1;
-        if (!Number.isFinite(fuzzyThreshold)) {
-            throw new Error("fuzzyThreshold must be a finite number.");
-        }
-        const recipePrototype = {
-            type,
-            name,
-            projectKey: pk,
-            ...(type === "fuzzyjoin" ? {} : { inputs, }),
-            outputs,
-        };
-        const creationSettings = {};
-        if (payload !== undefined) {
-            creationSettings.script = payload;
-        }
-        if (type === "fuzzyjoin") {
-            creationSettings.virtualInputs = recipeInputItems({ inputs, }).map((item) => item.ref);
-        }
+        const { creationSettings, fuzzyDistance, fuzzyKeys, fuzzyThreshold, inputDatasets, inputs, joinKeys, name, normalizedJoinType, outputFolder, outputs, rawConnection, recipePrototype, temporaryOutputDataset, type, } = buildRecipeCreateRequest(opts, pk);
         const createRecipe = () => this.client.post(`/public/api/projects/${enc}/recipes/`, {
             recipePrototype,
             creationSettings,
@@ -695,7 +727,7 @@ export class RecipesResource extends BaseResource {
             const created = await createRecipe();
             const receivedName = asString(created?.["name"]);
             if (!receivedName) {
-                throw new Error('DSS create-recipe response did not include the final recipe name (documented body: {"name": ...}).');
+                throw unexpectedResponseError('DSS create-recipe response did not include the final recipe name (documented body: {"name": ...}).');
             }
             finalRecipeName = receivedName;
         }
@@ -708,7 +740,7 @@ export class RecipesResource extends BaseResource {
             const retryCreated = await createRecipe();
             const retryName = asString(retryCreated?.["name"]);
             if (!retryName) {
-                throw new Error('DSS create-recipe response did not include the final recipe name (documented body: {"name": ...}).', { cause: error, });
+                throw unexpectedResponseError('DSS create-recipe response did not include the final recipe name (documented body: {"name": ...}).');
             }
             finalRecipeName = retryName;
         }
@@ -869,11 +901,11 @@ export class RecipesResource extends BaseResource {
         const current = await this.client.get(`/public/api/projects/${enc}/recipes/${rnEnc}`);
         const currentRecipe = asRecord(current.recipe);
         if (!currentRecipe) {
-            throw new Error(`Recipe "${recipeName}" was not found or returned an empty definition.`);
+            throw new ClientValidationError(`Recipe "${recipeName}" was not found or returned an empty definition.`, "validation_failed");
         }
         const misplacedRecipeFields = rootRecipeDefinitionFields(data);
         if (misplacedRecipeFields.length > 0) {
-            throw new Error(`Recipe fields ${misplacedRecipeFields.join(", ")} must be nested under "recipe". Example: {"recipe":{"outputs":{...},"params":{...}}}`);
+            throw new ClientValidationError(`Recipe fields ${misplacedRecipeFields.join(", ")} must be nested under "recipe". Example: {"recipe":{"outputs":{...},"params":{...}}}`, "validation_failed");
         }
         const mergedRecipe = deepMerge(currentRecipe, asRecord(data.recipe) ?? {});
         const merged = { ...current, ...data, recipe: mergedRecipe, };
@@ -895,7 +927,7 @@ export class RecipesResource extends BaseResource {
         if (opts.outputDataset !== undefined) {
             const outputs = recipeOutputItems(source.recipe).filter((item) => item.type !== "MANAGED_FOLDER");
             if (outputs.length !== 1 && Object.keys(outputRewrites).length === 0) {
-                throw new Error(`Recipe "${sourceName}" has ${outputs.length} dataset outputs; pass explicit outputRewrites instead of outputDataset.`);
+                throw new ClientValidationError(`Recipe "${sourceName}" has ${outputs.length} dataset outputs; pass explicit outputRewrites instead of outputDataset.`, "validation_failed");
             }
             if (outputs[0])
                 outputRewrites[outputs[0].ref] = opts.outputDataset;
@@ -910,7 +942,7 @@ export class RecipesResource extends BaseResource {
         if (opts.copyOutputSettings === true
             && Object.keys(outputRewrites).length > 1
             && (opts.outputPath !== undefined || opts.metastoreTableName !== undefined)) {
-            throw new Error("Cannot reuse --path or --metastore-table for multiple cloned output datasets; pass per-output settings in a separate step.");
+            throw new ClientValidationError("Cannot reuse --path or --metastore-table for multiple cloned output datasets; pass per-output settings in a separate step.", "validation_failed");
         }
         const payloadTextRewrites = {};
         if (opts.payloadTextRewrites)
@@ -956,7 +988,7 @@ export class RecipesResource extends BaseResource {
             projectKey: opts?.projectKey,
         });
         if (!result.payload) {
-            throw new Error(`Recipe "${recipeName}" has no code payload.`);
+            throw new ClientValidationError(`Recipe "${recipeName}" has no code payload.`, "validation_failed");
         }
         const safeRecipeName = sanitizeFileName(recipeName, "recipe");
         const filePath = opts?.outputPath ?? resolve(process.cwd(), `${safeRecipeName}${inferRecipeCodeExtension(result.recipe.type)}`);
@@ -970,7 +1002,7 @@ export class RecipesResource extends BaseResource {
             projectKey: opts?.projectKey,
         });
         if (!result.payload) {
-            throw new Error(`Recipe "${recipeName}" has no code payload.`);
+            throw new ClientValidationError(`Recipe "${recipeName}" has no code payload.`, "validation_failed");
         }
         return result.payload;
     }

package/dist/src/resources/sql.js

@@ -1,4 +1,4 @@
-import { ClientValidationError, DataikuError, } from "../errors.js";
+import { ClientValidationError, DataikuError, nonJsonResponseBody, SQL_QUERY_FAILED_MARKER, } from "../errors.js";
 import { BaseResource, } from "./base.js";
 const UNSUPPORTED_SQL_DATASET_CONNECTION_DETAIL = "neither of sql nor hdfs type";
 /**
@@ -159,7 +159,12 @@ export class SqlResource extends BaseResource {
         if (truncated) {
             throw new DataikuError(0, "Response Too Large", `SQL stream results exceeded the ${maxBytes}-byte response limit and were not parsed.`);
         }
-        return JSON.parse(text);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new DataikuError(200, "Invalid JSON response", nonJsonResponseBody(text));
+        }
     }
     /**
      * Verify that a query finished successfully server-side.
@@ -173,7 +178,7 @@ export class SqlResource extends BaseResource {
             throw new DataikuError(0, "Response Too Large", `SQL finish-streaming response exceeded the ${maxBytes}-byte response limit.`);
         }
         if (text.length > 0) {
-            throw new Error(`SQL query ${queryId} failed: ${text}`);
+            throw new DataikuError(200, "SQL Query Failed", `${SQL_QUERY_FAILED_MARKER} (${queryId}): ${text}`);
         }
     }
     async executeQuery(opts) {

package/dist/src/resources/statistics.js

@@ -1,4 +1,5 @@
 import { UsageError, } from "../cli/usage.js";
+import { ClientValidationError, } from "../errors.js";
 import { BaseResource, } from "./base.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -36,7 +37,7 @@ export class StatisticsResource extends BaseResource {
     async runWorksheet(datasetName, worksheetId, projectKey) {
         const worksheet = await this.getWorksheet(datasetName, worksheetId, projectKey);
         if (!isRecord(worksheet.rootCard)) {
-            throw new Error("statistics.runWorksheet requires worksheet.rootCard");
+            throw new ClientValidationError("statistics.runWorksheet requires worksheet.rootCard", "validation_failed");
         }
         return this.runCard(datasetName, worksheetId, worksheet.rootCard, projectKey);
     }

package/dist/src/resources/variables.js

@@ -1,3 +1,4 @@
+import { ClientValidationError, } from "../errors.js";
 import { ProjectVariablesSchema, } from "../schemas.js";
 import { BaseResource, } from "./base.js";
 export class VariablesResource extends BaseResource {
@@ -17,7 +18,7 @@ export class VariablesResource extends BaseResource {
             return replaced;
         }
         if (opts.standard === undefined && opts.local === undefined) {
-            throw new Error("At least one of standard or local must be provided");
+            throw new ClientValidationError("At least one of standard or local must be provided", "validation_failed");
         }
         const existing = await this.get(opts.projectKey);
         const merged = {