dataiku-sdk 1.0.0 → 2.0.0

package/dist/src/cli.js

@@ -32,19 +32,28 @@ import { canonicalDssUrl, } from "./utils/dss-url.js";
 // ---------------------------------------------------------------------------
 // Auth commands (run before client creation)
 // ---------------------------------------------------------------------------
-function findUnboundAppCleanup(entries) {
+function findUnboundLifecycleCleanup(entries) {
     for (const [index, entry,] of entries.entries()) {
         const parsed = parseArgs(entry.cleanup.argv);
         const [resource, action,] = parsed.positional;
-        if (resource !== "app" || action !== "delete-instance")
+        if (resource === "app" && action === "delete-instance") {
+            if (parsed.flags["unconfirmed-creation"] === true)
+                continue;
+            const expected = parsed.flags["expect-project-incarnation"];
+            if (typeof expected !== "string")
+                return { index, resource, action, reason: "missing", };
+            if (!/^[0-9a-f]{64}$/.test(expected))
+                return { index, resource, action, reason: "invalid", };
             continue;
-        if (parsed.flags["unconfirmed-creation"] === true)
+        }
+        if (resource === "project" && action === "delete") {
+            const expected = parsed.flags["expect-project-incarnation"];
+            if (typeof expected !== "string")
+                return { index, resource, action, reason: "missing", };
+            if (!/^[0-9a-f]{64}$/.test(expected))
+                return { index, resource, action, reason: "invalid", };
             continue;
-        const expected = parsed.flags["expect-project-incarnation"];
-        if (typeof expected !== "string")
-            return { index, reason: "missing", };
-        if (!/^[0-9a-f]{64}$/.test(expected))
-            return { index, reason: "invalid", };
+        }
     }
     return undefined;
 }
@@ -119,9 +128,10 @@ async function runCleanup(flags) {
         };
     }
     // Lifecycle binding is as load-bearing as server binding. Validate the whole
-    // reversed plan before step one so a later legacy app entry cannot leave an
-    // earlier cleanup applied and then fail on project-key reuse protection.
-    const lifecycleViolation = findUnboundAppCleanup(ordered);
+    // reversed plan before step one so a later legacy app or project entry
+    // cannot leave an earlier cleanup applied and then fail on project-key
+    // reuse protection.
+    const lifecycleViolation = findUnboundLifecycleCleanup(ordered);
     if (lifecycleViolation) {
         return {
             result: {
@@ -129,8 +139,8 @@ async function runCleanup(flags) {
                 steps,
                 lifecycleError: {
                     entryIndex: lifecycleViolation.index,
-                    resource: "app",
-                    action: "delete-instance",
+                    resource: lifecycleViolation.resource,
+                    action: lifecycleViolation.action,
                     reason: lifecycleViolation.reason,
                 },
             },
@@ -147,6 +157,11 @@ async function runCleanup(flags) {
                 || !commands[resource]?.[action]) {
                 throw new UsageError(`Invalid cleanup argv: ${entry.cleanup.argv.join(" ")}`);
             }
+            if (resource === "project"
+                && action === "delete"
+                && typeof parsed.flags["expect-project-incarnation"] !== "string") {
+                throw new UsageError("Project cleanup entry is not bound to a project incarnation. Refusing deletion after possible project-key reuse.", "validation_failed", "Capture a new cleanup entry from the current CLI. Legacy entries cannot safely delete projects.");
+            }
             if (resource === "app"
                 && action === "delete-instance"
                 && parsed.flags["unconfirmed-creation"] !== true
@@ -1194,6 +1209,8 @@ const MISSING_PROJECT_KEY_ERROR_PREFIX = "projectKey is required";
 function errorExitCode(err) {
     if (err instanceof CommandResultFailure)
         return err.exitCode;
+    if (err instanceof ClientValidationError && err.code === "ambiguous_outcome")
+        return 2;
     if (err instanceof UsageError || err instanceof ClientValidationError)
         return 1;
     if (err instanceof DataikuError)
@@ -1205,14 +1222,30 @@ function errorExitCode(err) {
 function buildErrorReport(err) {
     const context = rawCommandContext();
     const exitCode = errorExitCode(err);
+    if (err instanceof ClientValidationError && err.code === "ambiguous_outcome") {
+        return {
+            type: "error",
+            ok: false,
+            error: err.message,
+            code: err.code,
+            category: "dss",
+            exitCode,
+            ...(err.hint ? { hint: err.hint, } : {}),
+            ...(err.details ? { details: err.details, } : {}),
+            ...context,
+        };
+    }
     if (err instanceof UsageError || err instanceof ClientValidationError) {
         return {
             type: "error",
             ok: false,
             error: err.message,
             code: err.code,
-            category: "usage",
+            category: err.code === "target_absence_unverifiable"
+                ? "permission_or_environment"
+                : "usage",
             exitCode,
+            ...(err.code === "target_absence_unverifiable" ? { retryable: false, } : {}),
             ...(err.hint ? { hint: err.hint, } : {}),
             ...(err.details ? { details: err.details, } : {}),
             ...context,
@@ -1346,6 +1379,14 @@ async function main() {
         writeCommandResult(plan);
         return;
     }
+    if (actionMeta.localHandler) {
+        const result = await actionMeta.localHandler(args, flags);
+        const failureExitCode = commandFailureExitCode(result);
+        if (failureExitCode !== undefined)
+            throw new CommandResultFailure(result, failureExitCode);
+        writeCommandResult(result);
+        return;
+    }
     const { url, apiKey, projectKey, tlsRejectUnauthorized, caCertPath, } = resolveCredentials(flags);
     currentCommandContext.projectKey = projectKey;
     if (!url) {

package/dist/src/client.d.ts

@@ -45,6 +45,21 @@ export interface DataikuClientTraceEvent {
     elapsedMs?: number;
     detail?: string;
 }
+/**
+ * Selected response metadata captured alongside a public API response body.
+ * A fixed whitelist of non-sensitive headers: authorization data is never
+ * returned. Null means the header was absent.
+ */
+export interface DataikuClientResponseMeta {
+    /** `DSS-Version` — version of the DSS backend answering the request. */
+    dssVersion: string | null;
+    /** `DSS-API-Version` — version of the API server handling the request. */
+    dssApiVersion: string | null;
+    /** `Date` — origin server timestamp, when present. */
+    date: string | null;
+    /** Server-provided request id, when present. */
+    requestId: string | null;
+}
 export interface DataikuClientConfig {
     /** DSS base URL (e.g. https://dss.example.com) */
     url: string;
@@ -163,6 +178,15 @@ export declare class DataikuClient {
     getRequestTimeoutMs(): number;
     resolveProjectKey(paramValue?: string): string;
     get<T = unknown>(path: string): Promise<T>;
+    /**
+     * GET returning the parsed JSON body plus selected response metadata
+     * (documented DSS version headers, server date, request id). Authorization
+     * headers are never included.
+     */
+    getWithMetadata<T = unknown>(path: string): Promise<{
+        data: T;
+        meta: DataikuClientResponseMeta;
+    }>;
     getText(path: string): Promise<string>;
     getTextLimited(path: string, maxBytes: number): Promise<{
         text: string;
@@ -180,10 +204,13 @@ export declare class DataikuClient {
     put<T = unknown>(path: string, body: unknown): Promise<T>;
     del(path: string): Promise<void>;
     putVoid(path: string, body: unknown): Promise<void>;
-    upload(path: string, filePath: string): Promise<void>;
+    private uploadResponse;
+    upload(path: string, filePath: string, fileName?: string): Promise<void>;
+    uploadJson<T>(path: string, filePath: string, fileName?: string): Promise<T>;
     stream(path: string): Promise<Response>;
     private getHeaders;
     private getAnyHeaders;
+    private responseMeta;
     private logTrace;
     /**
      * Validate raw data against a TypeBox schema, throwing on structural mismatch.

package/dist/src/client.js

@@ -1,4 +1,5 @@
 import { readFileSync, } from "node:fs";
+import { basename, } from "node:path";
 import { getCACertificates, } from "node:tls";
 import { Value, } from "@sinclair/typebox/value";
 import { safeParseSchema, } from "./schemas.js";
@@ -360,6 +361,19 @@ export class DataikuClient {
         });
         return this.parseJsonResponse(res);
     }
+    /**
+     * GET returning the parsed JSON body plus selected response metadata
+     * (documented DSS version headers, server date, request id). Authorization
+     * headers are never included.
+     */
+    async getWithMetadata(path) {
+        const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
+            method: "GET",
+            headers: this.getHeaders(),
+        });
+        const data = await this.parseJsonResponse(res);
+        return { data, meta: this.responseMeta(res.headers), };
+    }
     async getText(path) {
         const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "GET",
@@ -464,19 +478,23 @@ export class DataikuClient {
             body: JSON.stringify(body),
         });
     }
-    async upload(path, filePath) {
-        const { openAsBlob, } = await import("node:fs");
-        const { basename, } = await import("node:path");
-        const fileBlob = await openAsBlob(filePath);
-        const fileName = basename(filePath);
+    async uploadResponse(path, filePath, fileName) {
+        const fileBlob = Bun.file(filePath);
         const formData = new FormData();
-        formData.append("file", fileBlob, fileName);
-        await this.fetchWithRetry(`${this.baseUrl}${path}`, {
+        formData.append("file", fileBlob, fileName ?? basename(filePath));
+        return this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "POST",
             headers: { Authorization: `Bearer ${this.apiKey}`, },
             body: formData,
         });
     }
+    async upload(path, filePath, fileName) {
+        await this.uploadResponse(path, filePath, fileName);
+    }
+    async uploadJson(path, filePath, fileName) {
+        const response = await this.uploadResponse(path, filePath, fileName);
+        return this.parseJsonResponse(response);
+    }
     async stream(path) {
         return this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "GET",
@@ -497,6 +515,15 @@ export class DataikuClient {
             Accept: "*/*",
         };
     }
+    responseMeta(headers) {
+        // Fixed non-sensitive whitelist. `Headers.get` is case-insensitive.
+        return {
+            dssVersion: headers.get("dss-version"),
+            dssApiVersion: headers.get("dss-api-version"),
+            date: headers.get("date"),
+            requestId: this.requestIdFromHeaders(headers) ?? null,
+        };
+    }
     logTrace(event) {
         if (this.verbose)
             this.onTrace({ type: "trace", ...event, });

package/dist/src/errors.d.ts

@@ -1,5 +1,5 @@
 export type DataikuErrorCategory = "not_found" | "forbidden" | "validation" | "transient" | "unknown";
-export type StableErrorCode = "usage_error" | "unknown_flag" | "missing_required_arg" | "missing_required_flag" | "invalid_flag_value" | "conflicting_input_sources" | "invalid_enum" | "not_found" | "permission_denied" | "validation_failed" | "transient" | "long_running_failure" | "command_result_failure" | "assertion_failed" | "ambiguous_outcome" | "internal_error";
+export type StableErrorCode = "usage_error" | "unknown_flag" | "missing_required_arg" | "missing_required_flag" | "invalid_flag_value" | "conflicting_input_sources" | "invalid_enum" | "not_found" | "permission_denied" | "target_absence_unverifiable" | "validation_failed" | "transient" | "long_running_failure" | "command_result_failure" | "assertion_failed" | "ambiguous_outcome" | "internal_error";
 export declare function dataikuErrorCode(category: DataikuErrorCategory): StableErrorCode;
 export interface DataikuErrorTaxonomy {
     category: DataikuErrorCategory;

package/dist/src/index.d.ts

@@ -12,7 +12,7 @@ export { type ConnectionSchemaListOptions, ConnectionsResource, type ConnectionT
 export { ContinuousActivitiesResource, } from "./resources/continuous-activities.js";
 export { DashboardsResource, } from "./resources/dashboards.js";
 export { DataQualityResource, } from "./resources/data-quality.js";
-export { type DatasetBuildValidationResult, type DatasetCloneOptions, type DatasetCloneResult, type DatasetSchemaColumnInput, DatasetsResource, } from "./resources/datasets.js";
+export { type DatasetBuildValidationResult, type DatasetCloneOptions, type DatasetCloneResult, type DatasetSchemaColumnInput, DatasetsResource, type UploadDatasetFileOptions, type UploadDatasetFileResult, type UploadedFileMetadata, } from "./resources/datasets.js";
 export { DiscussionsResource, } from "./resources/discussions.js";
 export { type FlowZoneItemInput, FlowZonesResource, } from "./resources/flow-zones.js";
 export { FoldersResource, } from "./resources/folders.js";
@@ -26,7 +26,7 @@ export * from "./resources/model-evaluation-stores.js";
 export { NotebooksResource, } from "./resources/notebooks.js";
 export * from "./resources/project-git.js";
 export { ProjectLibraryResource, } from "./resources/project-library.js";
-export { type FlowMapResult, ProjectsResource, } from "./resources/projects.js";
+export { type FlowMapResult, type ProjectImportProcessResult, type ProjectImportResult, type ProjectImportSettings, type ProjectImportUploadResult, ProjectsResource, } from "./resources/projects.js";
 export { type RecipeCloneOptions, type RecipeCloneResult, type RecipeGraphReference, type RecipeGraphValidationResult, type RecipeRunOptions, type RecipeRunOutput, type RecipeRunResult, RecipesResource, } from "./resources/recipes.js";
 export * from "./resources/saved-models.js";
 export { normalizeScenarioUpdateData, SCENARIO_CANONICAL_EDITABLE_FIELDS, type ScenarioFieldChange, type ScenarioFieldMismatch, type ScenarioScriptRunResult, ScenariosResource, type ScenarioUpdateNormalization, type ScenarioUpdatePreview, scenarioUpdatePreview, type ScenarioUpdateResult, } from "./resources/scenarios.js";
@@ -42,5 +42,6 @@ export type { SafeParseResult, } from "./schemas.js";
 export type { BuildMode, CodeEnvActionResult, CodeEnvCreateOptions, CodeEnvDetails, CodeEnvPackageList, CodeEnvSetPackagesOptions, CodeEnvSummary, CodeEnvUpdatePackagesOptions, CodeEnvUsage, CodeEnvWaitOptions, ConnectionSummary, DashboardDetails, DashboardSummary, DataQualityComputeResult, DataQualityProjectStatus, DataQualityRule, DataQualityRuleResult, DataQualityRules, DataQualityStatus, DataQualityStatusByPartition, DataQualityTimeline, DataQualityTimelineEntry, DatasetCreateOptions, DatasetDetails, DatasetSchema, DatasetSummary, FlowMapOptions, FlowZone, FlowZoneCreateOptions, FlowZoneItem, FlowZoneObjectType, FlowZonePosition, FlowZoneUpdateOptions, FolderCreateOptions, FolderDetails, FolderItem, FolderSummary, FutureState, FutureWaitResult, InsightDetails, InsightSummary, JobSummary, JobWaitResult, JupyterCell, JupyterNotebookContent, JupyterNotebookSummary, NotebookSession, ProjectDetails, ProjectGitActionResult, ProjectGitDiffResult, ProjectGitFutureResponse, ProjectGitFutureState, ProjectGitLibraries, ProjectGitLibrary, ProjectGitLogResult, ProjectGitRemote, ProjectGitStatus, ProjectGitTag, ProjectGitTags, ProjectMetadata, ProjectSummary, ProjectVariables, RecipeCreateOptions, RecipeCreateResult, RecipeDetails, RecipeSummary, ScenarioDetails, ScenarioStatus, ScenarioStepRun, ScenarioSummary, ScenarioWaitResult, SqlNotebookCell, SqlNotebookContent, SqlNotebookSummary, SqlQueryResponse, SqlQueryResult, SqlQuerySchema, WikiArticleData, WikiArticleMetadata, WikiSettings, WikiTaxonomyNode, } from "./schemas.js";
 export { deepMerge, } from "./utils/deep-merge.js";
 export { type NormalizedFlowEdge, type NormalizedFlowMap, type NormalizedFlowNode, normalizeFlowGraph, } from "./utils/flow-map.js";
+export * from "./utils/project-archive.js";
 export { sanitizeFileName, } from "./utils/sanitize.js";
 export { validateStreamColumns, } from "./resources/datasets.js";

package/dist/src/index.js

@@ -46,6 +46,7 @@ export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema,
 // Utilities
 export { deepMerge, } from "./utils/deep-merge.js";
 export { normalizeFlowGraph, } from "./utils/flow-map.js";
+export * from "./utils/project-archive.js";
 export { sanitizeFileName, } from "./utils/sanitize.js";
 // Stream validation
 export { validateStreamColumns, } from "./resources/datasets.js";

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

@@ -32,6 +32,25 @@ export interface DatasetCloneResult {
     created: Record<string, unknown>;
     settings: Record<string, unknown>;
 }
+export interface UploadedFileMetadata {
+    filename: string;
+    path?: string;
+    length?: number;
+    mime?: string;
+    weird?: boolean;
+    [key: string]: unknown;
+}
+export interface UploadDatasetFileOptions {
+    projectKey?: string;
+    fileName: string;
+}
+export interface UploadDatasetFileResult {
+    datasetName: string;
+    projectKey: string;
+    fileName: string;
+    bytes: number;
+    after: UploadedFileMetadata;
+}
 /**
  * Compare streamed TSV header columns against a known dataset schema.
  * Returns an array of warning strings (empty if all columns match).
@@ -49,6 +68,11 @@ export declare class DatasetsResource extends BaseResource {
     schema(datasetName: string, projectKey?: string): Promise<DatasetSchema>;
     /** Replace dataset schema columns directly through the schema endpoint. */
     updateSchema(datasetName: string, columns: DatasetSchemaColumnInput[], projectKey?: string): Promise<void>;
+    /**
+     * Get the raw dataset schema object exactly as the DSS schema endpoint
+     * returns it, without schema validation — used for deterministic comparison.
+     */
+    getSchemaObject(datasetName: string, projectKey?: string): Promise<unknown>;
     /**
      * Preview dataset rows as structured data: column names plus row arrays,
      * mirroring the sql query shape ({ columns, rows, rowCount }). Streams TSV
@@ -70,6 +94,21 @@ export declare class DatasetsResource extends BaseResource {
         }>;
         rows: string[][];
         rowCount: number;
+        truncated: boolean;
+        limit: number;
+    }>;
+    /**
+     * Count dataset rows by streaming the TSV data endpoint and stopping as soon
+     * as `expected + 1` rows have been seen, so a mismatched dataset is never
+     * fully scanned. Returns the observed count together with `exact` (false when
+     * the probe cap was reached, i.e. the count is a lower bound) and whether the
+     * count satisfies the assertion.
+     */
+    assertRowCount(datasetName: string, expected: number, projectKey?: string): Promise<{
+        expected: number;
+        count: number;
+        exact: boolean;
+        satisfied: boolean;
     }>;
     /** Get dataset metadata (tags, custom fields, checklists). */
     metadata(datasetName: string, projectKey?: string): Promise<Record<string, unknown>>;
@@ -102,6 +141,10 @@ export declare class DatasetsResource extends BaseResource {
     create(opts: DatasetCreateOptions): Promise<Record<string, unknown>>;
     /** Validate common build blockers before running a dataset build. */
     validateBuildSettings(datasetName: string, projectKey?: string): Promise<DatasetBuildValidationResult>;
+    /** List files stored by an UploadedFiles dataset. */
+    listUploadedFiles(datasetName: string, projectKey?: string): Promise<UploadedFileMetadata[]>;
+    /** Add a new file to an UploadedFiles dataset and verify its byte length. */
+    uploadDatasetFile(datasetName: string, localPath: string, opts: UploadDatasetFileOptions): Promise<UploadDatasetFileResult>;
     /** Clone dataset settings, preserving connection/storage, format, and schema fields. */
     clone(sourceName: string, targetName: string, opts?: DatasetCloneOptions): Promise<DatasetCloneResult>;
     /** Update a dataset by deep-merging a patch into the current definition. */