dataiku-sdk 3.3.0 → 3.5.0

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

@@ -394,12 +394,39 @@ async function collectTsvRowCount(body, stopAfter, timeoutMs) {
         reader.releaseLock();
     }
 }
+/**
+ * Encoded CSV bytes accumulated before one stream push. Rows are joined into
+ * batch-sized chunks so large downloads do not pay per-row stream overhead; a
+ * single escaped row may exceed the budget (rows are never split), and the
+ * batch is always flushed at EOF so trailing rows are never dropped.
+ */
+const CSV_BATCH_BYTES = 64 * 1024;
 function tsvToCsvTransform(maxDataRows, stats, onHeader, spreadsheetSafe = true) {
     const state = createTsvStreamState();
     const decoder = new StringDecoder("utf-8");
     const maxRows = Math.max(1, maxDataRows);
     let headerSeen = false;
     let done = false;
+    // Bounded CSV output batching: emitted rows accumulate here and are joined
+    // into a single push once the batch reaches CSV_BATCH_BYTES, so memory stays
+    // bounded by the batch budget plus one escaped row (the join briefly holds a
+    // second copy of the batch) while per-row push/callback overhead disappears.
+    let batchLines = [];
+    let batchBytes = 0;
+    const flushBatch = (target) => {
+        if (batchLines.length === 0)
+            return;
+        const csv = batchLines.join("");
+        batchLines = [];
+        batchBytes = 0;
+        target.push(csv);
+    };
+    const queueLine = (target, line) => {
+        batchLines.push(line);
+        batchBytes += Buffer.byteLength(line);
+        if (batchBytes >= CSV_BATCH_BYTES)
+            flushBatch(target);
+    };
     let columnCount = 0;
     const handleRow = (row, push) => {
         if (done)
@@ -430,16 +457,19 @@ function tsvToCsvTransform(maxDataRows, stats, onHeader, spreadsheetSafe = true)
                 return;
             }
             try {
-                consumeTsvChunk(decoder.write(chunk), state, (row) => handleRow(row, (line) => this.push(line)));
+                consumeTsvChunk(decoder.write(chunk), state, (row) => handleRow(row, (line) => queueLine(this, line)));
             }
             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)
+            if (done) {
+                // Truncation reached: emit the batch queued so far before EOF.
+                flushBatch(this);
                 this.push(null);
+            }
             callback();
         },
         flush(callback) {
@@ -450,14 +480,17 @@ function tsvToCsvTransform(maxDataRows, stats, onHeader, spreadsheetSafe = true)
             try {
                 const tail = decoder.end();
                 if (tail !== "") {
-                    consumeTsvChunk(tail, state, (row) => handleRow(row, (line) => this.push(line)));
+                    consumeTsvChunk(tail, state, (row) => handleRow(row, (line) => queueLine(this, line)));
                 }
-                flushTsvStream(state, (row) => handleRow(row, (line) => this.push(line)));
+                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
+            // download (below the batch budget) would be silently dropped.
+            flushBatch(this);
             callback();
         },
     });
@@ -485,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,
@@ -604,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.d.ts

@@ -1,3 +1,4 @@
+import type { DataikuGetOptions } from "../client.js";
 import type { FlowZone, FlowZoneCreateOptions, FlowZoneObjectType, FlowZoneUpdateOptions } from "../schemas.js";
 import { BaseResource } from "./base.js";
 export type FlowZoneItemInput = {
@@ -6,8 +7,11 @@ export type FlowZoneItemInput = {
     projectKey?: string;
 };
 export declare class FlowZonesResource extends BaseResource {
-    /** List all flow zones in a project. */
-    list(projectKey?: string): Promise<FlowZone[]>;
+    /**
+     * List all flow zones in a project. Pass `timeoutMs` to bound the whole
+     * request (attempts, backoff, and body read) by a total budget.
+     */
+    list(projectKey?: string, options?: DataikuGetOptions): Promise<FlowZone[]>;
     /** Get one flow zone by id. */
     get(zoneId: string, projectKey?: string): Promise<FlowZone>;
     /** Create a flow zone. */

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";
@@ -9,9 +10,12 @@ function normalizeZoneItem(item) {
     };
 }
 export class FlowZonesResource extends BaseResource {
-    /** List all flow zones in a project. */
-    async list(projectKey) {
-        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/flow/zones`);
+    /**
+     * List all flow zones in a project. Pass `timeoutMs` to bound the whole
+     * request (attempts, backoff, and body read) by a total budget.
+     */
+    async list(projectKey, options) {
+        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/flow/zones`, options);
         return this.client.safeParse(FlowZoneArraySchema, raw, "flowZones.list");
     }
     /** Get one flow zone by id. */
@@ -45,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.d.ts

@@ -7,11 +7,13 @@ export interface FutureWaitOptions {
 export declare class FuturesResource extends BaseResource {
     get(futureId: string, opts?: {
         timeoutMs?: number;
+        noRetry?: boolean;
     }): Promise<FutureState>;
     peek(futureId: string): Promise<FutureState>;
     state(futureId: string, opts?: {
         peek?: boolean;
         timeoutMs?: number;
+        noRetry?: boolean;
     }): Promise<FutureState>;
     abort(futureId: string): Promise<void>;
     wait(futureId: string, opts?: FutureWaitOptions): Promise<FutureWaitResult>;

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));
 }
@@ -25,7 +23,11 @@ function waitState(state) {
 }
 export class FuturesResource extends BaseResource {
     async get(futureId, opts = {}) {
-        return this.state(futureId, { peek: false, timeoutMs: opts.timeoutMs, });
+        return this.state(futureId, {
+            peek: false,
+            timeoutMs: opts.timeoutMs,
+            noRetry: opts.noRetry,
+        });
     }
     async peek(futureId) {
         return this.state(futureId, { peek: true, });
@@ -33,7 +35,7 @@ export class FuturesResource extends BaseResource {
     async state(futureId, opts = {}) {
         const params = new URLSearchParams();
         params.set("peek", String(opts.peek === true));
-        const raw = await this.client.get(`/public/api/futures/${encodeURIComponent(futureId)}?${params.toString()}`, { timeoutMs: opts.timeoutMs, });
+        const raw = await this.client.get(`/public/api/futures/${encodeURIComponent(futureId)}?${params.toString()}`, { timeoutMs: opts.timeoutMs, noRetry: opts.noRetry, });
         return this.client.safeParse(FutureStateSchema, raw, "futures.state");
     }
     async abort(futureId) {
@@ -51,16 +53,37 @@ export class FuturesResource extends BaseResource {
         const timeoutMs = Math.max(0, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
         const startedAt = Date.now();
         let pollCount = 0;
+        let lastState;
         while (true) {
+            const elapsedBeforeMs = Date.now() - startedAt;
+            // The first observation always happens, even when the budget is
+            // already spent. A later poll is never started after the deadline:
+            // the loop reports the structured timeout from the last observed
+            // state instead of issuing a request the budget cannot cover.
+            if (lastState !== undefined && elapsedBeforeMs >= timeoutMs) {
+                return this.client.safeParse(FutureWaitResultSchema, {
+                    futureId,
+                    jobId: lastState.jobId,
+                    state: waitState(lastState),
+                    elapsedMs: elapsedBeforeMs,
+                    pollCount,
+                    success: false,
+                    timedOut: true,
+                    hasResult: lastState.hasResult === true,
+                    alive: lastState.alive,
+                    aborted: lastState.aborted,
+                    unknown: lastState.unknown,
+                }, "futures.wait");
+            }
             pollCount += 1;
-            // One state observation always happens, even when the budget is
-            // already spent (the poll precedes the deadline check); only the
-            // requests issued while budget remains are bounded by the remaining
-            // time, so a stalled status endpoint can never defeat the deadline.
-            const remainingMs = timeoutMs - (Date.now() - startedAt);
+            // Requests issued while budget remains are bounded by the remaining
+            // time; a spent budget still issues exactly one transport attempt
+            // (no retries, client requestTimeoutMs cap) so the first observation
+            // reaches the server instead of failing before any attempt.
+            const remainingMs = timeoutMs - elapsedBeforeMs;
             let state;
             try {
-                state = await this.get(futureId, remainingMs > 0 ? { timeoutMs: remainingMs, } : undefined);
+                state = await this.get(futureId, remainingMs > 0 ? { timeoutMs: remainingMs, } : { noRetry: true, });
             }
             catch (error) {
                 // The poll budget ran out mid-request: report the structured
@@ -76,6 +99,7 @@ export class FuturesResource extends BaseResource {
                     timedOut: true,
                 }, "futures.wait");
             }
+            lastState = state;
             const elapsedMs = Date.now() - startedAt;
             const status = waitState(state);
             if (isFinished(state)) {
@@ -94,22 +118,10 @@ export class FuturesResource extends BaseResource {
                 };
                 return this.client.safeParse(FutureWaitResultSchema, result, "futures.wait");
             }
-            if (elapsedMs >= timeoutMs) {
-                const result = {
-                    futureId,
-                    jobId: state.jobId,
-                    state: status,
-                    elapsedMs,
-                    pollCount,
-                    success: false,
-                    timedOut: true,
-                    hasResult: state.hasResult === true,
-                    alive: state.alive,
-                    aborted: state.aborted,
-                    unknown: state.unknown,
-                };
-                return this.client.safeParse(FutureWaitResultSchema, result, "futures.wait");
-            }
+            // Deadline reached: the guard at the top of the loop reports the
+            // timeout from this observation without issuing another request.
+            if (elapsedMs >= timeoutMs)
+                continue;
             // Only the remaining budget is slept: a longer sleep would report an
             // elapsed time the caller never authorized.
             const nextDelayMs = computeNextPollDelayMs({

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,
@@ -289,19 +287,44 @@ export class JobsResource extends BaseResource {
         const timeout = Math.max(baseIntervalMs, opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS);
         const startedAt = Date.now();
         let pollCount = 0;
+        let lastJ;
         while (true) {
+            const elapsedBeforeMs = Date.now() - startedAt;
+            // The first observation always happens, even when the budget is
+            // already spent. A later poll is never started after the deadline:
+            // the loop reports the structured timeout from the last observed
+            // state instead of issuing a request the budget cannot cover.
+            if (lastJ !== undefined && elapsedBeforeMs >= timeout) {
+                const bs = lastJ.baseStatus ?? {};
+                const def = bs.def ?? {};
+                const gs = lastJ.globalState ?? {};
+                return {
+                    success: false,
+                    jobId,
+                    state: bs.state ?? "unknown",
+                    type: def.type ?? "unknown",
+                    elapsedMs: elapsedBeforeMs,
+                    pollCount,
+                    timedOut: true,
+                    progress: {
+                        done: gs.done ?? 0,
+                        failed: gs.failed ?? 0,
+                        running: gs.running ?? 0,
+                        total: gs.total ?? null,
+                    },
+                };
+            }
             pollCount += 1;
-            // One status observation always happens, even when the budget is
-            // already spent (the poll precedes the deadline check); only the
-            // requests issued while budget remains are bounded by the remaining
-            // time, so a stalled status endpoint can never defeat the deadline.
-            const elapsedBefore = Date.now() - startedAt;
-            const remainingMs = timeout - elapsedBefore;
+            // Requests issued while budget remains are bounded by the remaining
+            // time; a spent budget still issues exactly one transport attempt
+            // (no retries, client requestTimeoutMs cap) so the first observation
+            // reaches the server instead of failing before any attempt.
+            const remainingMs = timeout - elapsedBeforeMs;
             let j;
             try {
                 j = await this.client.get(`/public/api/projects/${projectEnc}/jobs/${jobEnc}/`, remainingMs > 0
                     ? { timeoutMs: remainingMs, }
-                    : undefined);
+                    : { noRetry: true, });
             }
             catch (error) {
                 // The poll budget ran out mid-request: report the documented
@@ -325,6 +348,7 @@ export class JobsResource extends BaseResource {
                     },
                 };
             }
+            lastJ = j;
             const bs = j.baseStatus ?? {};
             const def = bs.def ?? {};
             const gs = j.globalState ?? {};
@@ -387,24 +411,10 @@ export class JobsResource extends BaseResource {
                     ...(removed !== undefined ? { removed, } : {}),
                 };
             }
-            // Timeout — return failure result, don't throw
-            if (elapsedMs >= timeout) {
-                return {
-                    success: false,
-                    jobId,
-                    state,
-                    type: def.type ?? "unknown",
-                    elapsedMs,
-                    pollCount,
-                    timedOut: true,
-                    progress: {
-                        done: gs.done ?? 0,
-                        failed: gs.failed ?? 0,
-                        running: gs.running ?? 0,
-                        total: gs.total ?? null,
-                    },
-                };
-            }
+            // Timeout — the guard at the top of the loop returns the failure
+            // result from this observation without issuing another request.
+            if (elapsedMs >= timeout)
+                continue;
             const nextDelayMs = computeNextPollDelayMs({
                 pollCount,
                 baseIntervalMs,

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