dataiku-sdk 3.7.0 → 3.9.0

package/dist/src/cli.js

@@ -5,10 +5,10 @@ import { resolve, } from "node:path";
 import { num, seenJsonInputCredentials, unknownJsonInput, } from "./cli/coerce.js";
 import { commands, } from "./cli/commands/index.js";
 import { ambientProjectKey, loadEnvFile, } from "./cli/env.js";
-import { executionMode, FLAG_ALIASES, isNegativeNumberToken, parseArgs, rawPositionals, } from "./cli/flags.js";
+import { executionMode, FLAG_ALIASES, isFlagValueToken, parseArgs, rawPositionals, } from "./cli/flags.js";
 import { cleanupLedgerEntry, } from "./cli/helpers/cleanup.js";
-import { shapeListResult, } from "./cli/list-output.js";
 import { commandFailureExitCode, CommandResultFailure, enqueueCliWarning, flushCliWarnings, isFailedWaitResult, planResult, projectResultFields, setOutputFieldProjection, writeCommandResult, } from "./cli/output.js";
+import { shapeCommandResult, } from "./cli/result-shapes.js";
 import { currentCommandContext, resolveCredentials, resolveLoginCredentials, } from "./cli/runtime.js";
 import { commandSyntaxTree, commandUsage, } from "./cli/syntax.js";
 import { COMMANDS_RUN_HINT, inferRequiresProject, missingActionError, noCommandError, requireArgs, RESOURCE_NAMES, unknownActionError, unknownFlagError, unknownResourceError, UsageError, } from "./cli/usage.js";
@@ -533,8 +533,7 @@ function redactArgv(argv) {
                 else {
                     redacted.push(arg);
                     const next = argv[index + 1];
-                    if (next !== undefined
-                        && (next === "-" || !next.startsWith("-") || isNegativeNumberToken(next))) {
+                    if (next !== undefined && isFlagValueToken(next)) {
                         redacted.push("***");
                         index++;
                     }
@@ -1023,8 +1022,7 @@ async function runBatch(flags) {
                     await preflightCleanupLedgerForFlags(client, stepFlags);
                     const stepArgs = positional.slice(2);
                     result = await meta.handler(client, stepArgs, stepFlags);
-                    if (action === "list")
-                        result = shapeListResult(resource, result, stepFlags);
+                    result = shapeCommandResult(resource, action, result, stepFlags);
                     await recordCleanupLedgerEntry(client, resource, action, stepArgs, stepFlags, result, projectKey);
                 }
                 const failureExitCode = commandFailureExitCode(result);
@@ -1247,6 +1245,10 @@ function dssDiagnosticDetails(err) {
 function isAmbiguousMutationFailure(err, context) {
     if (!(err instanceof DataikuError))
         return false;
+    // DSS definitively refused the operation (e.g. the database rejected the SQL):
+    // nothing took effect, so there is no outcome to verify.
+    if (err.definiteFailure)
+        return false;
     const method = err.retry?.method.toUpperCase();
     if (!method || method === "GET" || method === "HEAD")
         return false;
@@ -1298,13 +1300,14 @@ function errorExitCode(err) {
 }
 function buildErrorReport(err, contextOverride) {
     const context = contextOverride ?? rawCommandContext();
+    // The envelope echoes only the resolved project; resource/action are known to the caller.
+    const scope = context.projectKey ? { projectKey: context.projectKey, } : {};
     const exitCode = errorExitCode(err);
     if (err instanceof ClientValidationError
         && (err.code === "ambiguous_outcome" || err.code === "assertion_failed"
             || err.code === "long_running_failure")) {
         return {
             type: "error",
-            ok: false,
             error: err.message,
             code: err.code,
             category: "dss",
@@ -1312,13 +1315,12 @@ function buildErrorReport(err, contextOverride) {
             retryable: false,
             ...(err.hint ? { hint: err.hint, } : {}),
             ...(err.details ? { details: err.details, } : {}),
-            ...context,
+            ...scope,
         };
     }
     if (err instanceof UsageError || err instanceof ClientValidationError) {
         return {
             type: "error",
-            ok: false,
             error: err.message,
             code: err.code,
             category: err.code === "target_absence_unverifiable"
@@ -1330,26 +1332,24 @@ function buildErrorReport(err, contextOverride) {
             ...(err.code === "target_absence_unverifiable" ? { retryable: false, } : {}),
             ...(err.hint ? { hint: err.hint, } : {}),
             ...(err.details ? { details: err.details, } : {}),
-            ...context,
+            ...scope,
         };
     }
     if (err instanceof CommandResultFailure) {
         return {
             type: "error",
-            ok: false,
             error: err.message,
             code: err.code,
             category: "dss",
             exitCode: err.exitCode,
             details: boundedFailureResult(err.result),
-            ...context,
+            ...scope,
         };
     }
     if (isAmbiguousMutationFailure(err, context)) {
         const method = err.retry?.method.toUpperCase() ?? "mutation";
         return {
             type: "error",
-            ok: false,
             error: `The ${method} request failed after dispatch; the mutation outcome is unknown.`,
             code: "ambiguous_outcome",
             category: "dss",
@@ -1363,14 +1363,19 @@ function buildErrorReport(err, contextOverride) {
                 idempotency: "none",
                 ...dssErrorDetails(err),
                 ...dssDiagnosticDetails(err),
+                ...err.details,
                 ...(err.retry ? { retry: err.retry, } : {}),
             },
-            ...context,
+            ...scope,
         };
     }
     if (err instanceof DataikuError) {
         const { dssMessage, dssErrorType, } = dssDiagnosticDetails(err);
-        const details = { ...dssErrorDetails(err), ...(dssErrorType ? { dssErrorType, } : {}), };
+        const details = {
+            ...dssErrorDetails(err),
+            ...(dssErrorType ? { dssErrorType, } : {}),
+            ...err.details,
+        };
         // Generic hints name what the command targeted. DSS answers 403 (not
         // 404) for a project that does not exist: "Failed to read project
         // permissions". A 403 about something else keeps the generic hint.
@@ -1383,7 +1388,6 @@ function buildErrorReport(err, contextOverride) {
                 : err.retryHint;
         return {
             type: "error",
-            ok: false,
             error: dssMessage ? `${err.safeMessage}: ${dssMessage}` : err.safeMessage,
             code: dataikuErrorCode(err.category),
             category: "dss",
@@ -1393,18 +1397,17 @@ function buildErrorReport(err, contextOverride) {
             retryable: err.retryable,
             requestId: err.requestId ?? requestIdFromBody(err.body),
             ...(Object.keys(details).length > 0 ? { details, } : {}),
-            ...context,
+            ...scope,
         };
     }
     const message = err instanceof Error ? err.message : String(err);
     return {
         type: "error",
-        ok: false,
         error: message,
         code: "internal_error",
         category: "internal",
         exitCode,
-        ...context,
+        ...scope,
     };
 }
 function writeErrorReport(err) {
@@ -1516,7 +1519,7 @@ async function main() {
     assertCleanupLedgerSupported(resource, action, flags);
     await preflightCleanupLedgerForFlags(client, flags);
     const handled = await actionMeta.handler(client, args, flags);
-    const result = action === "list" ? shapeListResult(resource, handled, flags) : handled;
+    const result = shapeCommandResult(resource, action, handled, flags);
     await recordCleanupLedgerEntry(client, resource, action, args, flags, result, projectKey);
     const failureExitCode = commandFailureExitCode(result);
     if (failureExitCode !== undefined)

package/dist/src/errors.d.ts

@@ -20,12 +20,18 @@ export interface DataikuErrorTrustedMetadata {
     elapsedMs?: number;
     /** Set by the transport when the retained response body is only a bounded prefix. */
     bodyTruncated?: boolean;
+    /**
+     * Set by a resource that recognized DSS's answer as a definite failure of the
+     * whole operation: nothing took effect, so a non-idempotent mutation is not
+     * ambiguous.
+     */
+    definiteFailure?: boolean;
 }
 export declare function canonicalStatusText(status: number): string;
 export declare class ClientValidationError extends Error {
     readonly code: StableErrorCode;
     readonly hint?: string;
-    readonly details?: Record<string, unknown>;
+    details?: Record<string, unknown>;
     constructor(message: string, code?: StableErrorCode, hint?: string, details?: Record<string, unknown>, options?: ErrorOptions);
 }
 /**
@@ -62,6 +68,10 @@ export declare class DataikuError extends Error {
     readonly trustedTarget?: string;
     readonly trustedElapsedMs?: number;
     readonly bodyTruncated?: boolean;
+    /** DSS definitively failed the whole operation; see `DataikuErrorTrustedMetadata.definiteFailure`. */
+    readonly definiteFailure?: boolean;
+    /** Client-side outcome context (e.g. rollback of partial mutations), surfaced in CLI `details`. */
+    details?: Record<string, unknown>;
     constructor(status: number, statusText: string, body: string, retry?: DataikuRetryMetadata, requestId?: string, trustedMetadata?: DataikuErrorTrustedMetadata);
     /** Status line only: never echoes response body text. */
     get safeMessage(): string;

package/dist/src/errors.js

@@ -74,6 +74,8 @@ export const UNEXPECTED_RESPONSE_MARKER = "Unexpected DSS response";
 export function unexpectedResponseError(detail, status = 200) {
     return new DataikuError(status, "Unexpected Response", `${UNEXPECTED_RESPONSE_MARKER}: ${detail}`);
 }
+/** Hint for a DSS answer that definitively failed the request (e.g. the database rejected the SQL). */
+const DEFINITE_FAILURE_HINT = "DSS reported that the request failed (for SQL: syntax error, missing object, or missing privileges of the connection's role). Fix the request or grants; do not retry unchanged.";
 /** Prefix for a SQL query failure reported by DSS on a 2xx finish-streaming response. */
 export const SQL_QUERY_FAILED_MARKER = "SQL query failed in DSS";
 const TLS_CERTIFICATE_HINT = "TLS certificate verification failed. Trust the DSS/corporate CA with --ca-cert PATH or NODE_EXTRA_CA_CERTS, or save it for every process and directory with `dss auth login --ca-cert PATH` (a project .env applies only when dss runs in that directory); use --insecure only for temporary troubleshooting.";
@@ -140,6 +142,8 @@ function isCertificateTrustFailure(lowerBody) {
         || lowerBody.includes("unable to get local issuer certificate")
         || lowerBody.includes("unable to verify leaf signature")
         || lowerBody.includes("self-signed certificate")
+        || lowerBody.includes("self signed certificate")
+        || lowerBody.includes("depth_zero_self_signed_cert")
         || lowerBody.includes("certificate has expired")
         || lowerBody.includes("cert_has_expired")
         || lowerBody.includes("self_signed_cert_in_chain")
@@ -372,6 +376,10 @@ export class DataikuError extends Error {
     trustedTarget;
     trustedElapsedMs;
     bodyTruncated;
+    /** DSS definitively failed the whole operation; see `DataikuErrorTrustedMetadata.definiteFailure`. */
+    definiteFailure;
+    /** Client-side outcome context (e.g. rollback of partial mutations), surfaced in CLI `details`. */
+    details;
     constructor(status, statusText, body, retry, requestId, trustedMetadata) {
         const details = DataikuError.buildDetails(status, body);
         super(details.message);
@@ -379,14 +387,21 @@ export class DataikuError extends Error {
         this.statusText = statusText;
         this.body = body;
         this.name = "DataikuError";
-        this.category = details.category;
-        this.retryable = details.retryable;
-        this.retryHint = details.retryHint;
+        const definite = trustedMetadata?.definiteFailure === true;
+        // A definite DSS refusal is not a transport/server fault: replaying it
+        // unchanged cannot succeed. Keep a more specific forbidden/not_found class.
+        const reclassify = definite
+            && (details.category === "transient" || details.category === "unknown"
+                || details.category === "unexpected_response");
+        this.category = reclassify ? "validation" : details.category;
+        this.retryable = reclassify ? false : details.retryable;
+        this.retryHint = reclassify ? DEFINITE_FAILURE_HINT : details.retryHint;
         this.retry = retry;
         this.requestId = requestId;
         this.trustedTarget = trustedMetadata?.target;
         this.trustedElapsedMs = trustedMetadata?.elapsedMs;
         this.bodyTruncated = trustedMetadata?.bodyTruncated === true ? true : undefined;
+        this.definiteFailure = definite ? true : undefined;
     }
     /** Status line only: never echoes response body text. */
     get safeMessage() {

package/dist/src/generated/action-output-schemas.json

@@ -363,6 +363,107 @@
                 }
             }
         },
+        "dataset.info": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string"
+                },
+                "type": {
+                    "type": "string"
+                },
+                "managed": {
+                    "type": "boolean"
+                },
+                "connection": {
+                    "type": "string"
+                },
+                "formatType": {
+                    "type": "string"
+                },
+                "partitioned": {
+                    "type": "boolean"
+                },
+                "schema": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "required": [
+                            "name",
+                            "type"
+                        ],
+                        "properties": {
+                            "name": {
+                                "type": "string"
+                            },
+                            "type": {
+                                "type": "string"
+                            },
+                            "meaning": {
+                                "type": "string"
+                            },
+                            "comment": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                },
+                "recipes": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "buildable": {
+                    "type": "boolean"
+                },
+                "upstreamBuildable": {
+                    "type": "boolean"
+                },
+                "downstreamBuildable": {
+                    "type": "boolean"
+                },
+                "tags": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "dataQuality": {
+                    "type": "object",
+                    "additionalProperties": true
+                },
+                "lastBuild": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "jobId": {
+                            "type": "string"
+                        },
+                        "success": {
+                            "type": "boolean"
+                        },
+                        "startTime": {
+                            "type": "number"
+                        },
+                        "endTime": {
+                            "type": "number"
+                        }
+                    }
+                },
+                "lastModifiedOn": {
+                    "type": "number"
+                },
+                "lastModifiedBy": {
+                    "type": "string"
+                }
+            }
+        },
         "dataset.list": {
             "type": "array",
             "items": {
@@ -825,6 +926,121 @@
                 }
             }
         },
+        "job.get": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "id",
+                "state"
+            ],
+            "properties": {
+                "id": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string"
+                },
+                "type": {
+                    "type": "string"
+                },
+                "state": {
+                    "type": "string"
+                },
+                "initiator": {
+                    "type": "string"
+                },
+                "triggeredFrom": {
+                    "type": "string"
+                },
+                "startTime": {
+                    "type": "number"
+                },
+                "endTime": {
+                    "type": "number"
+                },
+                "outputs": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "properties": {
+                            "type": {
+                                "type": "string"
+                            },
+                            "id": {
+                                "type": "string"
+                            },
+                            "projectKey": {
+                                "type": "string"
+                            },
+                            "partition": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                },
+                "progress": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "number"
+                    }
+                },
+                "error": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "type": {
+                            "type": "string"
+                        },
+                        "message": {
+                            "type": "string"
+                        }
+                    }
+                },
+                "activities": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "properties": {
+                            "id": {
+                                "type": "string"
+                            },
+                            "recipe": {
+                                "type": "string"
+                            },
+                            "recipeType": {
+                                "type": "string"
+                            },
+                            "state": {
+                                "type": "string"
+                            },
+                            "totalTime": {
+                                "type": "number"
+                            },
+                            "warnings": {
+                                "type": "number"
+                            },
+                            "error": {
+                                "type": "object",
+                                "additionalProperties": false,
+                                "properties": {
+                                    "type": {
+                                        "type": "string"
+                                    },
+                                    "message": {
+                                        "type": "string"
+                                    }
+                                }
+                            },
+                            "message": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            }
+        },
         "job.list": {
             "type": "array",
             "items": {
@@ -1519,7 +1735,8 @@
             "type": "object",
             "required": [
                 "projectKey",
-                "name"
+                "name",
+                "deniedPermissions"
             ],
             "properties": {
                 "projectKey": {
@@ -1537,25 +1754,6 @@
                 "projectAppType": {
                     "type": "string"
                 },
-                "creationTag": {
-                    "additionalProperties": true,
-                    "type": "object",
-                    "properties": {
-                        "versionNumber": {
-                            "type": "number"
-                        },
-                        "lastModifiedOn": {
-                            "anyOf": [
-                                {
-                                    "type": "number"
-                                },
-                                {
-                                    "type": "string"
-                                }
-                            ]
-                        }
-                    }
-                },
                 "ownerLogin": {
                     "type": "string"
                 },
@@ -1565,21 +1763,12 @@
                         "type": "string"
                     }
                 },
-                "versionTag": {
-                    "additionalProperties": true,
-                    "type": "object",
-                    "required": [
-                        "versionNumber",
-                        "lastModifiedOn"
-                    ],
-                    "properties": {
-                        "versionNumber": {
-                            "type": "number"
-                        },
-                        "lastModifiedOn": {
-                            "type": "number"
-                        }
-                    }
+                "deniedPermissions": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Permission flags DSS reports as false; absent flags are granted."
                 }
             }
         },

package/dist/src/resources/dataset-create.d.ts

@@ -4,6 +4,24 @@
  * public endpoint writes; without it every downstream build fails.
  */
 export declare function assertDatasetTypeCreatable(dsType: string): void;
+/**
+ * Dataset types that read from a SQL connection. These are the types DSS
+ * detects schemas for through `testAndDetectSettings/externalSQL` (the list
+ * dataikuapi's `DSSDataset.autodetect_settings` uses).
+ */
+export declare const SQL_DATASET_TYPES: readonly ["JDBC", "PostgreSQL", "MySQL", "Vertica", "Snowflake", "Redshift", "Greenplum", "Teradata", "Oracle", "SQLServer", "SAPHANA", "Netezza", "BigQuery", "Athena", "hiveserver2", "Synapse", "FabricWarehouse", "Databricks", "DatabricksLakebase"];
+export declare function isSqlDatasetType(dsType: string): boolean;
+/**
+ * Validate the SQL source options (`table`/`dbSchema`/`catalog`/`query`) of a
+ * dataset creation against its type. Shared by `dataset create`, its plan, and
+ * the SDK so every entry point rejects the same combinations.
+ */
+export declare function assertSqlDatasetSource(dsType: string, source: {
+    table?: string;
+    dbSchema?: string;
+    catalog?: string;
+    query?: string;
+}): void;
 /** Wire body for POST /datasets/; shared with `dataset create --plan` so the plan matches the request. */
 export declare function buildDatasetCreateBody(opts: {
     projectKey: string;
@@ -13,6 +31,7 @@ export declare function buildDatasetCreateBody(opts: {
     table?: string;
     dbSchema?: string;
     catalog?: string;
+    query?: string;
     formatType?: string;
     formatParams?: Record<string, unknown>;
     managed?: boolean;

package/dist/src/resources/dataset-create.js

@@ -9,6 +9,60 @@ export function assertDatasetTypeCreatable(dsType) {
         return;
     throw new ClientValidationError("Inline (editable) datasets cannot be created here: the DSS public API cannot write their rows, and an Inline dataset without rows fails every downstream build (SourceDatasetNotReadyException). For a small static table, create an UploadedFiles dataset and upload a CSV with dss dataset upload-file, or write the rows from a python recipe into a managed dataset.", "validation_failed");
 }
+/**
+ * Dataset types that read from a SQL connection. These are the types DSS
+ * detects schemas for through `testAndDetectSettings/externalSQL` (the list
+ * dataikuapi's `DSSDataset.autodetect_settings` uses).
+ */
+export const SQL_DATASET_TYPES = [
+    "JDBC",
+    "PostgreSQL",
+    "MySQL",
+    "Vertica",
+    "Snowflake",
+    "Redshift",
+    "Greenplum",
+    "Teradata",
+    "Oracle",
+    "SQLServer",
+    "SAPHANA",
+    "Netezza",
+    "BigQuery",
+    "Athena",
+    "hiveserver2",
+    "Synapse",
+    "FabricWarehouse",
+    "Databricks",
+    "DatabricksLakebase",
+];
+export function isSqlDatasetType(dsType) {
+    const lower = dsType.toLowerCase();
+    return SQL_DATASET_TYPES.some((type) => type.toLowerCase() === lower);
+}
+/**
+ * Validate the SQL source options (`table`/`dbSchema`/`catalog`/`query`) of a
+ * dataset creation against its type. Shared by `dataset create`, its plan, and
+ * the SDK so every entry point rejects the same combinations.
+ */
+export function assertSqlDatasetSource(dsType, source) {
+    const hasTable = source.table !== undefined;
+    const hasQuery = source.query !== undefined;
+    if (hasTable && hasQuery) {
+        throw new ClientValidationError("Pass either a table or a query for a SQL dataset, not both.", "conflicting_input_sources");
+    }
+    if (!hasTable && (source.dbSchema !== undefined || source.catalog !== undefined)) {
+        throw new ClientValidationError("A schema or catalog only applies together with a table.", "validation_failed", "Add --table, or drop --schema/--catalog (a query names its own tables).");
+    }
+    if (hasTable && source.table.trim() === "") {
+        throw new ClientValidationError("table must be a non-empty table name.", "invalid_flag_value");
+    }
+    if (hasQuery && source.query.trim() === "") {
+        throw new ClientValidationError("query must be a non-empty SQL query.", "invalid_flag_value");
+    }
+    if ((hasTable || hasQuery) && !isSqlDatasetType(dsType)) {
+        throw new ClientValidationError(`A table or query only applies to SQL dataset types, not "${dsType}".`, "validation_failed", `SQL types: ${SQL_DATASET_TYPES.join(", ")}.`);
+    }
+}
 /** Wire body for POST /datasets/; shared with `dataset create --plan` so the plan matches the request. */
 export function buildDatasetCreateBody(opts) {
     assertDatasetTypeCreatable(opts.dsType);
@@ -23,6 +77,21 @@ export function buildDatasetCreateBody(opts) {
     if (!opts.connection) {
         throw new ClientValidationError("connection is required unless dsType is UploadedFiles.");
     }
+    if (opts.query !== undefined) {
+        if (opts.table !== undefined) {
+            throw new ClientValidationError("Pass either a table or a query for a SQL dataset, not both.", "conflicting_input_sources");
+        }
+        if (opts.query.trim() === "") {
+            throw new ClientValidationError("query must be a non-empty SQL query.", "invalid_flag_value");
+        }
+        return {
+            projectKey: opts.projectKey,
+            name: opts.datasetName,
+            type: opts.dsType,
+            params: { connection: opts.connection, mode: "query", query: opts.query, },
+            managed: opts.managed ?? false,
+        };
+    }
     if (opts.table) {
         const params = {
             connection: opts.connection,