dataiku-sdk 0.1.0 → 0.1.2

package/bin/dss.js

@@ -1,2 +1,4 @@
 #!/usr/bin/env bun
-import "../dist/src/cli.js";
+import * as cli from "../dist/src/cli.js";
+
+void cli;

package/dist/packages/types/src/index.d.ts

@@ -298,8 +298,8 @@ export declare const JupyterNotebookSummarySchema: import("@sinclair/typebox").T
     language: import("@sinclair/typebox").TString;
     kernelSpec: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         name: import("@sinclair/typebox").TString;
-        display_name: import("@sinclair/typebox").TString;
-        language: import("@sinclair/typebox").TString;
+        display_name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        language: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;
 }>;
 export type JupyterNotebookSummary = Static<typeof JupyterNotebookSummarySchema>;
@@ -438,8 +438,8 @@ export declare const JupyterNotebookSummaryArraySchema: import("@sinclair/typebo
     language: import("@sinclair/typebox").TString;
     kernelSpec: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         name: import("@sinclair/typebox").TString;
-        display_name: import("@sinclair/typebox").TString;
-        language: import("@sinclair/typebox").TString;
+        display_name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        language: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;
 }>>;
 export declare const SqlNotebookSummaryArraySchema: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{

package/dist/packages/types/src/index.js

@@ -306,8 +306,8 @@ export const JupyterNotebookSummarySchema = Type.Object({
     language: Type.String(),
     kernelSpec: Type.Optional(Type.Object({
         name: Type.String(),
-        display_name: Type.String(),
-        language: Type.String(),
+        display_name: Type.Optional(Type.String()),
+        language: Type.Optional(Type.String()),
     }, { additionalProperties: true, })),
 }, { additionalProperties: true, });
 export const JupyterNotebookContentSchema = Type.Object({

package/dist/src/cli.js

@@ -18,6 +18,87 @@ function json(v) {
         return undefined;
     return JSON.parse(v);
 }
+function jsonInput(flags) {
+    if (flags["stdin"] === true) {
+        return JSON.parse(readFileSync(0, "utf-8"));
+    }
+    if (typeof flags["data-file"] === "string") {
+        return JSON.parse(readFileSync(flags["data-file"], "utf-8"));
+    }
+    if (typeof flags["data"] === "string") {
+        return JSON.parse(flags["data"]);
+    }
+    return undefined;
+}
+async function resolveFolderId(client, nameOrId, flags) {
+    return client.folders.resolveId(nameOrId, flags["project-key"]);
+}
+function formatLineDiff(remoteName, localPath, remoteContent, localContent) {
+    if (localContent === remoteContent) {
+        return "No differences.";
+    }
+    const localLines = localContent.split("\n");
+    const remoteLines = remoteContent.split("\n");
+    const lines = [`--- remote:${remoteName}`, `+++ local:${localPath}`, "",];
+    const maxLen = Math.max(localLines.length, remoteLines.length);
+    for (let i = 0; i < maxLen; i++) {
+        const remoteLine = remoteLines[i];
+        const localLine = localLines[i];
+        if (remoteLine === localLine)
+            continue;
+        if (remoteLine !== undefined && localLine !== undefined) {
+            lines.push(`@@ line ${String(i + 1)} @@`);
+            lines.push(`- ${remoteLine}`);
+            lines.push(`+ ${localLine}`);
+            continue;
+        }
+        if (remoteLine !== undefined) {
+            lines.push(`- ${remoteLine}`);
+            continue;
+        }
+        lines.push(`+ ${localLine}`);
+    }
+    return lines.join("\n");
+}
+function parseOutputFormat(v) {
+    if (v === undefined)
+        return "json";
+    if (v === "json" || v === "quiet" || v === "tsv")
+        return v;
+    throw new UsageError(`Invalid --format value: ${String(v)}. Use json, tsv, or quiet.`);
+}
+function writeCommandResult(result, format) {
+    if (result === undefined || result === null) {
+        if (format !== "quiet") {
+            process.stdout.write(`${JSON.stringify({ ok: true, }, null, 2)}\n`);
+        }
+        return;
+    }
+    if (typeof result === "string") {
+        if (format !== "quiet") {
+            process.stdout.write(result);
+            if (!result.endsWith("\n"))
+                process.stdout.write("\n");
+        }
+        return;
+    }
+    if (format === "quiet")
+        return;
+    if (format === "tsv"
+        && Array.isArray(result)
+        && result.every((item) => item !== null && typeof item === "object" && !Array.isArray(item))) {
+        const items = result;
+        if (items.length === 0)
+            return;
+        const keys = Object.keys(items[0]);
+        process.stdout.write(`${keys.join("\t")}\n`);
+        for (const item of items) {
+            process.stdout.write(`${keys.map((key) => String(item[key] ?? "")).join("\t")}\n`);
+        }
+        return;
+    }
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
 function parseArgs(argv) {
     const positional = [];
     const flags = {};
@@ -142,14 +223,14 @@ const commands = {
         },
         update: {
             handler: (c, a, f) => {
-                requireArgs(a, 1, "dss dataset update <name> --data '{...}'");
-                const data = json(f["data"]);
+                requireArgs(a, 1, "dss dataset update <name> [--data '{...}' | --data-file PATH | --stdin]");
+                const data = jsonInput(f);
                 if (!data) {
-                    throw new UsageError("--data is required. Usage: dss dataset update <name> --data '{...}'");
+                    throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss dataset update <name> [--data '{...}' | --data-file PATH | --stdin]");
                 }
                 return c.datasets.update(a[0], data, f["project-key"]);
             },
-            usage: "dss dataset update <name> --data '{...}' [--project-key KEY]",
+            usage: "dss dataset update <name> [--data '{...}' | --data-file PATH | --stdin] [--project-key KEY]",
         },
     },
     recipe: {
@@ -178,37 +259,71 @@ const commands = {
                 requireArgs(a, 1, "dss recipe download <name>");
                 return c.recipes.download(a[0], {
                     outputPath: f["output"],
+                    projectKey: f["project-key"],
+                });
+            },
+            usage: "dss recipe download <name> [--output PATH] [--project-key KEY]",
+        },
+        "download-code": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss recipe download-code <name>");
+                return c.recipes.downloadCode(a[0], {
+                    outputPath: f["output"],
+                    projectKey: f["project-key"],
                 });
             },
-            usage: "dss recipe download <name> [--output PATH]",
+            usage: "dss recipe download-code <name> [--output PATH] [--project-key KEY]",
         },
         create: {
             handler: (c, _a, f) => {
                 const type = f["type"];
                 if (!type) {
-                    throw new UsageError("--type is required. Usage: dss recipe create --type TYPE --input DS");
+                    throw new UsageError("--type is required. Usage: dss recipe create --type TYPE --input DS --output DS");
+                }
+                const outputDataset = f["output"];
+                if (!outputDataset) {
+                    throw new UsageError("--output is required. Usage: dss recipe create --type TYPE --input DS --output DS");
                 }
                 return c.recipes.create({
                     type,
                     name: f["name"],
                     inputDatasets: f["input"] ? [f["input"],] : undefined,
-                    outputDataset: f["output"],
+                    outputDataset,
                     outputConnection: f["output-connection"],
                     projectKey: f["project-key"],
                 });
             },
-            usage: "dss recipe create --type TYPE --input DS [--output DS] [--output-connection CONN] [--project-key KEY]",
+            usage: "dss recipe create --type TYPE --input DS --output DS [--output-connection CONN] [--project-key KEY]",
+        },
+        diff: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss recipe diff <name> --file PATH");
+                const filePath = f["file"];
+                if (!filePath) {
+                    throw new UsageError("--file is required. Usage: dss recipe diff <name> --file PATH");
+                }
+                const result = await c.recipes.get(a[0], {
+                    includePayload: true,
+                    projectKey: f["project-key"],
+                });
+                if (!result.payload) {
+                    throw new Error(`Recipe "${a[0]}" has no code payload to diff.`);
+                }
+                const localContent = readFileSync(filePath, "utf-8");
+                return formatLineDiff(a[0], filePath, result.payload, localContent);
+            },
+            usage: "dss recipe diff <name> --file PATH [--project-key KEY]",
         },
         update: {
             handler: (c, a, f) => {
-                requireArgs(a, 1, "dss recipe update <name> --data '{...}'");
-                const data = json(f["data"]);
+                requireArgs(a, 1, "dss recipe update <name> [--data '{...}' | --data-file PATH | --stdin]");
+                const data = jsonInput(f);
                 if (!data) {
-                    throw new UsageError("--data is required. Usage: dss recipe update <name> --data '{...}'");
+                    throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss recipe update <name> [--data '{...}' | --data-file PATH | --stdin]");
                 }
                 return c.recipes.update(a[0], data, f["project-key"]);
             },
-            usage: "dss recipe update <name> --data '{...}' [--project-key KEY]",
+            usage: "dss recipe update <name> [--data '{...}' | --data-file PATH | --stdin] [--project-key KEY]",
         },
     },
     job: {
@@ -316,14 +431,14 @@ const commands = {
         },
         update: {
             handler: (c, a, f) => {
-                requireArgs(a, 1, "dss scenario update <id> --data '{...}'");
-                const data = json(f["data"]);
+                requireArgs(a, 1, "dss scenario update <id> [--data '{...}' | --data-file PATH | --stdin]");
+                const data = jsonInput(f);
                 if (!data) {
-                    throw new UsageError("--data is required. Usage: dss scenario update <id> --data '{...}'");
+                    throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss scenario update <id> [--data '{...}' | --data-file PATH | --stdin]");
                 }
                 return c.scenarios.update(a[0], data, f["project-key"]);
             },
-            usage: "dss scenario update <id> --data '{...}' [--project-key KEY]",
+            usage: "dss scenario update <id> [--data '{...}' | --data-file PATH | --stdin] [--project-key KEY]",
         },
     },
     folder: {
@@ -332,41 +447,44 @@ const commands = {
             usage: "dss folder list [--project-key KEY]",
         },
         get: {
-            handler: (c, a, f) => {
-                requireArgs(a, 1, "dss folder get <id>");
-                return c.folders.get(a[0], f["project-key"]);
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss folder get <name-or-id>");
+                return c.folders.get(await resolveFolderId(c, a[0], f), f["project-key"]);
             },
-            usage: "dss folder get <id> [--project-key KEY]",
+            usage: "dss folder get <name-or-id> [--project-key KEY]",
         },
         contents: {
-            handler: (c, a, _f) => {
-                requireArgs(a, 1, "dss folder contents <id>");
-                return c.folders.contents(a[0]);
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss folder contents <name-or-id>");
+                return c.folders.contents(await resolveFolderId(c, a[0], f), {
+                    projectKey: f["project-key"],
+                });
             },
-            usage: "dss folder contents <id>",
+            usage: "dss folder contents <name-or-id> [--project-key KEY]",
         },
         download: {
-            handler: (c, a, f) => {
-                requireArgs(a, 2, "dss folder download <id> <path>");
-                return c.folders.download(a[0], a[1], {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss folder download <name-or-id> <path>");
+                return c.folders.download(await resolveFolderId(c, a[0], f), a[1], {
                     localPath: f["output"],
+                    projectKey: f["project-key"],
                 });
             },
-            usage: "dss folder download <id> <path> [--output PATH]",
+            usage: "dss folder download <name-or-id> <path> [--output PATH] [--project-key KEY]",
         },
         upload: {
-            handler: (c, a, f) => {
-                requireArgs(a, 3, "dss folder upload <id> <path> <localPath>");
-                return c.folders.upload(a[0], a[1], a[2], f["project-key"]);
+            handler: async (c, a, f) => {
+                requireArgs(a, 3, "dss folder upload <name-or-id> <path> <localPath>");
+                return c.folders.upload(await resolveFolderId(c, a[0], f), a[1], a[2], f["project-key"]);
             },
-            usage: "dss folder upload <id> <path> <localPath> [--project-key KEY]",
+            usage: "dss folder upload <name-or-id> <path> <localPath> [--project-key KEY]",
         },
         "delete-file": {
-            handler: (c, a, f) => {
-                requireArgs(a, 2, "dss folder delete-file <id> <path>");
-                return c.folders.deleteFile(a[0], a[1], f["project-key"]);
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss folder delete-file <name-or-id> <path>");
+                return c.folders.deleteFile(await resolveFolderId(c, a[0], f), a[1], f["project-key"]);
             },
-            usage: "dss folder delete-file <id> <path> [--project-key KEY]",
+            usage: "dss folder delete-file <name-or-id> <path> [--project-key KEY]",
         },
     },
     variable: {
@@ -378,8 +496,10 @@ const commands = {
             handler: (c, _a, f) => c.variables.set({
                 standard: json(f["standard"]),
                 local: json(f["local"]),
+                replace: f["replace"] === true,
+                projectKey: f["project-key"],
             }),
-            usage: 'dss variable set --standard \'{"k":"v"}\' --local \'{"k":"v"}\'',
+            usage: 'dss variable set --standard \'{"k":"v"}\' --local \'{"k":"v"}\' [--replace] [--project-key KEY]',
         },
     },
     connection: {
@@ -492,23 +612,25 @@ const commands = {
         },
         "save-jupyter": {
             handler: (c, a, f) => {
-                requireArgs(a, 1, "dss notebook save-jupyter <name> --data '{...}'");
-                const data = json(f["data"]);
-                if (!data)
-                    throw new UsageError("--data is required (notebook JSON content)");
+                requireArgs(a, 1, "dss notebook save-jupyter <name> [--data '{...}' | --data-file PATH | --stdin]");
+                const data = jsonInput(f);
+                if (!data) {
+                    throw new UsageError("--data, --data-file, or --stdin is required (notebook JSON content).");
+                }
                 return c.notebooks.saveJupyter(a[0], data, f["project-key"]);
             },
-            usage: "dss notebook save-jupyter <name> --data '{...}' [--project-key KEY]",
+            usage: "dss notebook save-jupyter <name> [--data '{...}' | --data-file PATH | --stdin] [--project-key KEY]",
         },
         "save-sql": {
             handler: (c, a, f) => {
-                requireArgs(a, 1, "dss notebook save-sql <id> --data '{...}'");
-                const data = json(f["data"]);
-                if (!data)
-                    throw new UsageError("--data is required (SQL notebook content JSON)");
+                requireArgs(a, 1, "dss notebook save-sql <id> [--data '{...}' | --data-file PATH | --stdin]");
+                const data = jsonInput(f);
+                if (!data) {
+                    throw new UsageError("--data, --data-file, or --stdin is required (SQL notebook content JSON).");
+                }
                 return c.notebooks.saveSql(a[0], data, f["project-key"]);
             },
-            usage: "dss notebook save-sql <id> --data '{...}' [--project-key KEY]",
+            usage: "dss notebook save-sql <id> [--data '{...}' | --data-file PATH | --stdin] [--project-key KEY]",
         },
         "clear-sql-history": {
             handler: (c, a, f) => {
@@ -535,6 +657,8 @@ function printTopLevelHelp() {
         "  --url URL            Dataiku DSS base URL (env: DATAIKU_URL)",
         "  --api-key KEY        API key              (env: DATAIKU_API_KEY)",
         "  --project-key KEY    Default project key   (env: DATAIKU_PROJECT_KEY)",
+        "  --format FORMAT      Output format: json|tsv|quiet",
+        "  --verbose            Log HTTP requests to stderr",
         "  --help               Show help",
         "",
         "Resources:",
@@ -662,10 +786,12 @@ async function main() {
         url,
         apiKey,
         projectKey: flags["project-key"] ?? process.env.DATAIKU_PROJECT_KEY,
+        verbose: flags["verbose"] === true,
     });
     const args = positional.slice(2);
+    const format = parseOutputFormat(flags["format"]);
     const result = await actionMeta.handler(client, args, flags);
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    writeCommandResult(result, format);
 }
 main().catch((err) => {
     if (err instanceof UsageError) {
@@ -681,7 +807,7 @@ main().catch((err) => {
         if (err.retryHint)
             payload.retryHint = err.retryHint;
         process.stderr.write(`${JSON.stringify(payload, null, 2)}\n`);
-        process.exit(1);
+        process.exit(err.category === "transient" ? 3 : 2);
     }
     const message = err instanceof Error ? err.message : String(err);
     process.stderr.write(`${JSON.stringify({ error: message, }, null, 2)}\n`);

package/dist/src/client.d.ts

@@ -21,9 +21,11 @@ export interface DataikuClientConfig {
     requestTimeoutMs?: number;
     /** Max retry attempts for idempotent requests (default 4, capped at 10) */
     retryMaxAttempts?: number;
+    /** Emit HTTP request/response logs to stderr for CLI debugging. */
+    verbose?: boolean;
     /**
      * Called when an API response fails schema validation but data is still usable.
-     * Default: logs to console.warn. Set to a throwing function for strict mode.
+     * Default: writes to stderr. Set to a throwing function for strict mode.
      * @param method - resource method that triggered the warning (e.g. "datasets.list")
      * @param errors - human-readable validation error strings
      */
@@ -35,6 +37,7 @@ export declare class DataikuClient {
     private readonly defaultProjectKey;
     private readonly requestTimeoutMs;
     private readonly retryMaxAttempts;
+    private readonly verbose;
     private readonly onValidationWarning;
     private _projects?;
     private _datasets?;
@@ -70,6 +73,7 @@ export declare class DataikuClient {
     stream(path: string): Promise<Response>;
     private getHeaders;
     private getAnyHeaders;
+    private logVerbose;
     /**
      * Validate raw data against a TypeBox schema, throwing on structural mismatch.
      * Resources call this instead of bare `as T` casts for validated responses.

package/dist/src/client.js

@@ -24,7 +24,7 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 /*  Helpers                                                            */
 /* ------------------------------------------------------------------ */
 function defaultValidationWarning(method, errors) {
-    console.warn(`[dataiku-sdk] Schema validation warning in ${method}:\n  ${errors.join("\n  ")}`);
+    process.stderr.write(`[dataiku-sdk] Schema validation warning in ${method}:\n  ${errors.join("\n  ")}\n`);
 }
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
@@ -59,6 +59,7 @@ export class DataikuClient {
     defaultProjectKey;
     requestTimeoutMs;
     retryMaxAttempts;
+    verbose;
     onValidationWarning;
     /* Resource namespaces — lazily initialized to break circular imports */
     _projects;
@@ -118,6 +119,7 @@ export class DataikuClient {
         this.requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
         const rawMax = config.retryMaxAttempts ?? DEFAULT_RETRY_MAX_ATTEMPTS;
         this.retryMaxAttempts = Math.min(Math.max(1, rawMax), MAX_RETRY_ATTEMPTS_CAP);
+        this.verbose = config.verbose === true;
         this.onValidationWarning = config.onValidationWarning ?? defaultValidationWarning;
     }
     /* ---- public: project key resolution ---- */
@@ -206,6 +208,10 @@ export class DataikuClient {
             Accept: "*/*",
         };
     }
+    logVerbose(message) {
+        if (this.verbose)
+            process.stderr.write(`[dss] ${message}\n`);
+    }
     /* ---- public: schema-validated parsing ---- */
     /**
      * Validate raw data against a TypeBox schema, throwing on structural mismatch.
@@ -235,6 +241,9 @@ export class DataikuClient {
     /* ---- private: JSON parsing ---- */
     async parseJsonResponse(res) {
         const text = await res.text();
+        // SAFETY: Empty 2xx responses from DSS are surfaced to callers as undefined
+        // cast to T. This keeps existing call sites stable, but callers that rely on
+        // an object shape must guard explicitly before dereferencing the result.
         if (!text)
             return undefined;
         try {
@@ -253,13 +262,16 @@ export class DataikuClient {
         const delaysMs = [];
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
             let timedOut = false;
+            const startedAt = Date.now();
             const controller = new AbortController();
             const timeout = setTimeout(() => {
                 timedOut = true;
                 controller.abort();
             }, this.requestTimeoutMs);
+            this.logVerbose(`${method} ${url}`);
             try {
                 const res = await fetch(url, { ...init, method, signal: controller.signal, });
+                this.logVerbose(`${method} ${url} → ${res.status} (${Date.now() - startedAt}ms)`);
                 if (!res.ok) {
                     const text = await res.text();
                     const canRetry = retryEnabled && attempt < maxAttempts && isTransientError(res.status, text);
@@ -288,6 +300,7 @@ export class DataikuClient {
                     : error instanceof Error
                         ? error.message
                         : "Unknown transport error";
+                this.logVerbose(`${method} ${url} → ERROR (${Date.now() - startedAt}ms) ${detail}`);
                 const statusText = timedOut ? "Request Timeout" : "Network Error";
                 throw new DataikuError(0, statusText, detail, buildRetryMetadata(method, retryEnabled, maxAttempts, attempt, delaysMs, timedOut));
             }

package/dist/src/errors.js

@@ -39,6 +39,18 @@ export function classifyDataikuError(status, body) {
             retryHint: "Request appears invalid for this endpoint. Fix parameters/payload before retrying.",
         };
     }
+    const isServerPermissionLike = status >= 500
+        && (lowerBody.includes("not allowed to access")
+            || lowerBody.includes("access denied")
+            || (lowerBody.includes("permission")
+                && (lowerBody.includes("cannot use") || lowerBody.includes("not allowed"))));
+    if (isServerPermissionLike) {
+        return {
+            category: "forbidden",
+            retryable: false,
+            retryHint: "Check API key validity and project permissions for the requested action.",
+        };
+    }
     if (status === 404) {
         const isHtmlGatewayResponse = lowerBody.includes("<!doctype html>");
         return {

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

@@ -9,7 +9,7 @@ export declare class ConnectionsResource extends BaseResource {
      * Infers available connections.
      *
      * - fast (default): fetches the connection name list and maps to ConnectionSummary.
-     *   Falls back to rich mode on any failure.
+     *   Falls back to rich mode on any failure or empty result set.
      * - rich: inspects project datasets to derive connection metadata
      *   (types, managed flag, db schemas).
      */

package/dist/src/resources/connections.js

@@ -55,7 +55,7 @@ export class ConnectionsResource extends BaseResource {
      * Infers available connections.
      *
      * - fast (default): fetches the connection name list and maps to ConnectionSummary.
-     *   Falls back to rich mode on any failure.
+     *   Falls back to rich mode on any failure or empty result set.
      * - rich: inspects project datasets to derive connection metadata
      *   (types, managed flag, db schemas).
      */
@@ -65,13 +65,16 @@ export class ConnectionsResource extends BaseResource {
         if (mode === "rich") {
             return inferRichConnectionsFromDatasets(this.client, projectEnc);
         }
-        // fast — attempt name list, fall back to rich on any error
+        // fast — attempt name list, fall back to rich on any error or empty result
         try {
             const names = await this.list();
-            return names.map((name) => ({ name, }));
+            if (names.length > 0) {
+                return names.map((name) => ({ name, }));
+            }
         }
         catch {
-            return inferRichConnectionsFromDatasets(this.client, projectEnc);
+            // Fall through to rich inference.
         }
+        return inferRichConnectionsFromDatasets(this.client, projectEnc);
     }
 }

package/dist/src/resources/datasets.js

@@ -346,11 +346,17 @@ export class DatasetsResource extends BaseResource {
                 }
             }
             : undefined;
+        const shouldGzip = filePath.endsWith(".gz");
         const nodeStream = Readable.fromWeb(res.body);
         const csvTransform = tsvToCsvTransform(downloadLimit, onHeader);
-        const gzip = createGzip();
         const fileOut = createWriteStream(filePath);
-        await pipeline(nodeStream, csvTransform, gzip, fileOut);
+        if (shouldGzip) {
+            const gzip = createGzip();
+            await pipeline(nodeStream, csvTransform, gzip, fileOut);
+        }
+        else {
+            await pipeline(nodeStream, csvTransform, fileOut);
+        }
         return filePath;
     }
     /**

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

@@ -2,6 +2,7 @@ import type { FolderDetails, FolderItem, FolderSummary } from "../schemas.js";
 import { BaseResource } from "./base.js";
 export declare class FoldersResource extends BaseResource {
     list(projectKey?: string): Promise<FolderSummary[]>;
+    resolveId(nameOrId: string, projectKey?: string): Promise<string>;
     get(folderId: string, projectKey?: string): Promise<FolderDetails>;
     contents(folderId: string, opts?: {
         projectKey?: string;

package/dist/src/resources/folders.js

@@ -21,6 +21,14 @@ export class FoldersResource extends BaseResource {
         const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/managedfolders/`);
         return this.client.safeParse(FolderSummaryArraySchema, raw, "folders.list");
     }
+    async resolveId(nameOrId, projectKey) {
+        const folders = await this.list(projectKey);
+        if (folders.some((folder) => folder.id === nameOrId)) {
+            return nameOrId;
+        }
+        const match = folders.find((folder) => folder.name === nameOrId);
+        return match?.id ?? nameOrId;
+    }
     async get(folderId, projectKey) {
         const fEnc = encodeURIComponent(folderId);
         const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/managedfolders/${fEnc}`);

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

@@ -18,7 +18,8 @@ export declare class JobsResource extends BaseResource {
     get(jobId: string, projectKey?: string): Promise<Record<string, unknown>>;
     /**
      * Retrieve job log text.
-     * Returns the last `maxLogLines` lines (default 50) from the tail.
+     * Returns the last `maxLogLines` lines (default 500) from the tail.
+     * Use `0` or `-1` to return the full log without truncation.
      */
     log(jobId: string, opts?: {
         activity?: string;

package/dist/src/resources/jobs.js

@@ -3,7 +3,7 @@ import { BaseResource, } from "./base.js";
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const MAX_POLL_INTERVAL_MS = 10_000;
 const DEFAULT_TIMEOUT_MS = 120_000;
-const DEFAULT_MAX_LOG_LINES = 50;
+const DEFAULT_MAX_LOG_LINES = 500;
 const TERMINAL_STATES = new Set([
     "DONE",
     "FAILED",
@@ -49,7 +49,8 @@ export class JobsResource extends BaseResource {
     }
     /**
      * Retrieve job log text.
-     * Returns the last `maxLogLines` lines (default 50) from the tail.
+     * Returns the last `maxLogLines` lines (default 500) from the tail.
+     * Use `0` or `-1` to return the full log without truncation.
      */
     async log(jobId, opts) {
         const jobEnc = encodeURIComponent(jobId);
@@ -57,8 +58,11 @@ export class JobsResource extends BaseResource {
         const log = await this.client.getText(`/public/api/projects/${this.enc(opts?.projectKey)}/jobs/${jobEnc}/log/${query}`);
         if (!log)
             return "";
-        const lines = log.split("\n");
         const limit = opts?.maxLogLines ?? DEFAULT_MAX_LOG_LINES;
+        if (limit === 0 || limit === -1) {
+            return log;
+        }
+        const lines = log.split("\n");
         if (lines.length > limit) {
             return lines.slice(-limit).join("\n");
         }

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

@@ -7,13 +7,28 @@ export declare class NotebooksResource extends BaseResource {
     getJupyter(name: string, projectKey?: string): Promise<JupyterNotebookContent>;
     /** Save (overwrite) a Jupyter notebook's content. */
     saveJupyter(name: string, content: JupyterNotebookContent, projectKey?: string): Promise<void>;
-    /** Delete a Jupyter notebook. */
+    /**
+     * Delete a Jupyter notebook.
+     *
+     * DSS public APIs can delete notebooks but do not expose notebook creation, so
+     * this can only target notebooks created outside this SDK (for example in the UI).
+     */
     deleteJupyter(name: string, projectKey?: string): Promise<void>;
-    /** Clear all cell outputs from a Jupyter notebook. */
+    /**
+     * Clear all cell outputs from a Jupyter notebook.
+     *
+     * DSS public APIs do not expose a dedicated clear-outputs endpoint, so this
+     * method fetches the notebook, strips outputs locally, and saves it back.
+     */
     clearJupyterOutputs(name: string, projectKey?: string): Promise<void>;
     /** List running kernel sessions for a Jupyter notebook. */
     listJupyterSessions(name: string, projectKey?: string): Promise<NotebookSession[]>;
-    /** Unload (stop) a running Jupyter notebook session. */
+    /**
+     * Unload (stop) a running Jupyter notebook session.
+     *
+     * DSS public APIs do not expose notebook or session creation, so this only
+     * works for sessions started outside this SDK.
+     */
     unloadJupyter(name: string, sessionId: string, projectKey?: string): Promise<void>;
     /** List all SQL notebooks in a project. */
     listSql(projectKey?: string): Promise<SqlNotebookSummary[]>;

package/dist/src/resources/notebooks.js

@@ -18,15 +18,30 @@ export class NotebooksResource extends BaseResource {
         const nameEnc = encodeURIComponent(name);
         await this.client.putVoid(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/${nameEnc}`, content);
     }
-    /** Delete a Jupyter notebook. */
+    /**
+     * Delete a Jupyter notebook.
+     *
+     * DSS public APIs can delete notebooks but do not expose notebook creation, so
+     * this can only target notebooks created outside this SDK (for example in the UI).
+     */
     async deleteJupyter(name, projectKey) {
         const nameEnc = encodeURIComponent(name);
         await this.client.del(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/${nameEnc}`);
     }
-    /** Clear all cell outputs from a Jupyter notebook. */
+    /**
+     * Clear all cell outputs from a Jupyter notebook.
+     *
+     * DSS public APIs do not expose a dedicated clear-outputs endpoint, so this
+     * method fetches the notebook, strips outputs locally, and saves it back.
+     */
     async clearJupyterOutputs(name, projectKey) {
-        const nameEnc = encodeURIComponent(name);
-        await this.client.del(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/${nameEnc}/outputs`);
+        const notebook = await this.getJupyter(name, projectKey);
+        const clearedCells = notebook.cells.map((cell) => ({
+            ...cell,
+            outputs: [],
+            execution_count: null,
+        }));
+        await this.saveJupyter(name, { ...notebook, cells: clearedCells, }, projectKey);
     }
     /** List running kernel sessions for a Jupyter notebook. */
     async listJupyterSessions(name, projectKey) {
@@ -34,7 +49,12 @@ export class NotebooksResource extends BaseResource {
         const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/${nameEnc}/sessions`);
         return this.client.safeParse(NotebookSessionArraySchema, raw, "notebooks.sessionsJupyter");
     }
-    /** Unload (stop) a running Jupyter notebook session. */
+    /**
+     * Unload (stop) a running Jupyter notebook session.
+     *
+     * DSS public APIs do not expose notebook or session creation, so this only
+     * works for sessions started outside this SDK.
+     */
     async unloadJupyter(name, sessionId, projectKey) {
         const nameEnc = encodeURIComponent(name);
         const sidEnc = encodeURIComponent(sessionId);

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

@@ -19,9 +19,18 @@ export declare class RecipesResource extends BaseResource {
     create(opts: RecipeCreateOptions): Promise<RecipeCreateResult>;
     /**
      * Update a recipe by merging the patch into the current definition.
-     * The `recipe` sub-object is spread-merged to preserve nested fields.
+     * The `recipe` sub-object is deep-merged to preserve nested fields.
      */
     update(recipeName: string, data: Record<string, unknown>, projectKey?: string): Promise<void>;
+    /**
+     * Download a recipe code payload to a local file.
+
+     * Returns the path to the written file.
+     */
+    downloadCode(recipeName: string, opts?: {
+        outputPath?: string;
+        projectKey?: string;
+    }): Promise<string>;
     /** Delete a recipe. */
     delete(recipeName: string, projectKey?: string): Promise<void>;
     /**

package/dist/src/resources/recipes.js

@@ -2,6 +2,7 @@ import { writeFile, } from "node:fs/promises";
 import { resolve, } from "node:path";
 import { DataikuError, } from "../errors.js";
 import { RecipeSummaryArraySchema, } from "../schemas.js";
+import { deepMerge, } from "../utils/deep-merge.js";
 import { sanitizeFileName, } from "../utils/sanitize.js";
 import { BaseResource, } from "./base.js";
 // ---------------------------------------------------------------------------
@@ -21,6 +22,22 @@ function asRecord(value) {
         return undefined;
     return value;
 }
+function inferRecipeCodeExtension(recipeType) {
+    const normalized = typeof recipeType === "string" ? recipeType.trim().toLowerCase() : "";
+    if (!normalized)
+        return ".txt";
+    if (normalized.includes("python") || normalized.includes("pyspark"))
+        return ".py";
+    if (normalized.includes("sql"))
+        return ".sql";
+    if (normalized === "r" || normalized.startsWith("r_"))
+        return ".R";
+    if (normalized.includes("scala"))
+        return ".scala";
+    if (normalized.includes("shell"))
+        return ".sh";
+    return ".txt";
+}
 // ---------------------------------------------------------------------------
 // Helpers: retry predicate
 // ---------------------------------------------------------------------------
@@ -53,7 +70,7 @@ export class RecipesResource extends BaseResource {
      * Get a recipe definition (and optionally its payload).
      * Returns the raw API response shape: `{ recipe, payload }`.
      */
-    get(recipeName, opts) {
+    async get(recipeName, opts) {
         const enc = this.enc(opts?.projectKey);
         const rnEnc = encodeURIComponent(recipeName);
         const params = new URLSearchParams();
@@ -64,7 +81,12 @@ export class RecipesResource extends BaseResource {
             params.set("payloadMaxLines", String(opts.payloadMaxLines));
         const qs = params.toString();
         const url = `/public/api/projects/${enc}/recipes/${rnEnc}${qs ? `?${qs}` : ""}`;
-        return this.client.get(url);
+        const result = await this.client.get(url);
+        const recipe = asRecord(result?.recipe);
+        if (!result || !recipe) {
+            throw new DataikuError(404, "Not Found", `Recipe "${recipeName}" not found in project "${this.resolveProjectKey(opts?.projectKey)}" (DSS returned empty response).`);
+        }
+        return { ...result, recipe, };
     }
     /** Create a recipe, with optional output dataset provisioning and join configuration. */
     async create(opts) {
@@ -242,7 +264,7 @@ export class RecipesResource extends BaseResource {
     }
     /**
      * Update a recipe by merging the patch into the current definition.
-     * The `recipe` sub-object is spread-merged to preserve nested fields.
+     * The `recipe` sub-object is deep-merged to preserve nested fields.
      */
     async update(recipeName, data, projectKey) {
         const enc = this.enc(projectKey);
@@ -252,13 +274,28 @@ export class RecipesResource extends BaseResource {
         if (!currentRecipe) {
             throw new Error(`Recipe "${recipeName}" was not found or returned an empty definition.`);
         }
-        const mergedRecipe = {
-            ...currentRecipe,
-            ...data.recipe,
-        };
+        const mergedRecipe = deepMerge(currentRecipe, asRecord(data.recipe) ?? {});
         const merged = { ...current, ...data, recipe: mergedRecipe, };
         await this.client.put(`/public/api/projects/${enc}/recipes/${rnEnc}`, merged);
     }
+    /**
+     * Download a recipe code payload to a local file.
+
+     * Returns the path to the written file.
+     */
+    async downloadCode(recipeName, opts) {
+        const result = await this.get(recipeName, {
+            includePayload: true,
+            projectKey: opts?.projectKey,
+        });
+        if (!result.payload) {
+            throw new Error(`Recipe "${recipeName}" has no code payload.`);
+        }
+        const safeRecipeName = sanitizeFileName(recipeName, "recipe");
+        const filePath = opts?.outputPath ?? resolve(process.cwd(), `${safeRecipeName}${inferRecipeCodeExtension(result.recipe.type)}`);
+        await writeFile(filePath, result.payload, "utf-8");
+        return filePath;
+    }
     /** Delete a recipe. */
     async delete(recipeName, projectKey) {
         const enc = this.enc(projectKey);

package/dist/src/resources/sql.js

@@ -1,4 +1,18 @@
+import { DataikuError, } from "../errors.js";
 import { BaseResource, } from "./base.js";
+const UNSUPPORTED_SQL_DATASET_CONNECTION_DETAIL = "neither of sql nor hdfs type";
+function isUnsupportedSqlDatasetConnectionError(error) {
+    if (!(error instanceof DataikuError))
+        return false;
+    const detail = `${error.statusText}\n${error.body}\n${error.message}`.toLowerCase();
+    return detail.includes(UNSUPPORTED_SQL_DATASET_CONNECTION_DETAIL);
+}
+function buildUnsupportedSqlDatasetConnectionMessage(datasetFullName) {
+    const subject = datasetFullName
+        ? `Dataset "${datasetFullName}" uses a connection that DSS does not support for direct SQL queries.`
+        : "This query uses a connection that DSS does not support for direct SQL queries.";
+    return `${subject} Use --connection with a SQL-compatible connection instead.`;
+}
 export class SqlResource extends BaseResource {
     /**
      * Start a SQL query and return the queryId + schema.
@@ -6,7 +20,10 @@ export class SqlResource extends BaseResource {
      * or `datasetFullName` (run against a dataset's connection).
      */
     async startQuery(opts) {
-        return this.client.post(`/public/api/sql/queries`, opts);
+        return this.client.post("/public/api/sql/queries/", {
+            ...opts,
+            type: opts.type ?? "sql",
+        });
     }
     /**
      * Stream results of a started query as parsed JSON (array of arrays).
@@ -32,9 +49,19 @@ export class SqlResource extends BaseResource {
      * This is the primary method most callers want.
      */
     async query(opts) {
-        const { queryId, schema, } = await this.startQuery(opts);
-        const rows = await this.streamResults(queryId);
-        await this.finishStreaming(queryId);
-        return { queryId, schema, rows, };
+        const queryOpts = { ...opts, type: opts.type ?? "sql", };
+        try {
+            const { queryId, schema, } = await this.startQuery(queryOpts);
+            const rows = await this.streamResults(queryId);
+            await this.finishStreaming(queryId);
+            return { queryId, schema, rows, };
+        }
+        catch (error) {
+            if (!isUnsupportedSqlDatasetConnectionError(error))
+                throw error;
+            throw new Error(buildUnsupportedSqlDatasetConnectionMessage(queryOpts.datasetFullName), {
+                cause: error,
+            });
+        }
     }
 }

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

@@ -5,6 +5,7 @@ export declare class VariablesResource extends BaseResource {
     set(opts: {
         standard?: Record<string, unknown>;
         local?: Record<string, unknown>;
+        replace?: boolean;
         projectKey?: string;
     }): Promise<ProjectVariables>;
 }

package/dist/src/resources/variables.js

@@ -7,6 +7,15 @@ export class VariablesResource extends BaseResource {
         return this.client.safeParse(ProjectVariablesSchema, raw, "variables.get");
     }
     async set(opts) {
+        const enc = this.enc(opts.projectKey);
+        if (opts.replace === true) {
+            const replaced = {
+                standard: opts.standard ?? {},
+                local: opts.local ?? {},
+            };
+            await this.client.putVoid(`/public/api/projects/${enc}/variables/`, replaced);
+            return replaced;
+        }
         if (opts.standard === undefined && opts.local === undefined) {
             throw new Error("At least one of standard or local must be provided");
         }
@@ -15,7 +24,6 @@ export class VariablesResource extends BaseResource {
             standard: { ...existing.standard, ...opts.standard, },
             local: { ...existing.local, ...opts.local, },
         };
-        const enc = this.enc(opts.projectKey);
         await this.client.putVoid(`/public/api/projects/${enc}/variables/`, merged);
         return merged;
     }

package/package.json

@@ -1,9 +1,11 @@
 {
 	"name": "dataiku-sdk",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"description": "Dataiku DSS SDK and CLI for programmatic access to DSS REST APIs",
 	"type": "module",
-	"workspaces": ["packages/*"],
+	"workspaces": [
+		"packages/*"
+	],
 	"main": "dist/src/index.js",
 	"types": "dist/src/index.d.ts",
 	"bin": {

package/packages/types/dist/index.d.ts

@@ -298,8 +298,8 @@ export declare const JupyterNotebookSummarySchema: import("@sinclair/typebox").T
     language: import("@sinclair/typebox").TString;
     kernelSpec: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         name: import("@sinclair/typebox").TString;
-        display_name: import("@sinclair/typebox").TString;
-        language: import("@sinclair/typebox").TString;
+        display_name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        language: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;
 }>;
 export type JupyterNotebookSummary = Static<typeof JupyterNotebookSummarySchema>;
@@ -438,8 +438,8 @@ export declare const JupyterNotebookSummaryArraySchema: import("@sinclair/typebo
     language: import("@sinclair/typebox").TString;
     kernelSpec: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         name: import("@sinclair/typebox").TString;
-        display_name: import("@sinclair/typebox").TString;
-        language: import("@sinclair/typebox").TString;
+        display_name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        language: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;
 }>>;
 export declare const SqlNotebookSummaryArraySchema: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{

package/packages/types/dist/index.js

@@ -306,8 +306,8 @@ export const JupyterNotebookSummarySchema = Type.Object({
     language: Type.String(),
     kernelSpec: Type.Optional(Type.Object({
         name: Type.String(),
-        display_name: Type.String(),
-        language: Type.String(),
+        display_name: Type.Optional(Type.String()),
+        language: Type.Optional(Type.String()),
     }, { additionalProperties: true, })),
 }, { additionalProperties: true, });
 export const JupyterNotebookContentSchema = Type.Object({