dataiku-sdk 3.1.0 → 3.3.0

package/dist/src/cli/commands/macro.js

@@ -0,0 +1,221 @@
+import { macroResultMaxBytes, } from "../../resources/macros.js";
+import { jsonInput, num, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
+import { encodedProjectEndpoint, } from "../output.js";
+import { requireArgs, UsageError, } from "../usage.js";
+const MACRO_RUN_USAGE = "dss macro run <macro_id> [--wait] [--timeout MS (default 120000)] [--poll-interval MS] [--data JSON] [--dry-run] [--project-key KEY]";
+/**
+ * Flags accepted by run/run-and-wait; validated identically for live, dry-run,
+ * and --plan so a plan that would fail cannot be "fixed" by dropping flags.
+ * Returns undefined rather than a partial options object so callers can spread
+ * it only when the macro actually has parameters.
+ */
+function macroWaitOptionsFromFlags(flags) {
+    const timeoutMs = num(flags["timeout"], "--timeout");
+    const pollIntervalMs = num(flags["poll-interval"], "--poll-interval");
+    if (timeoutMs !== undefined && timeoutMs < 0) {
+        throw new UsageError("--timeout must be >= 0.", "invalid_flag_value", undefined, {
+            flag: "--timeout",
+        });
+    }
+    if (pollIntervalMs !== undefined && pollIntervalMs < 1) {
+        throw new UsageError("--poll-interval must be >= 1.", "invalid_flag_value", undefined, { flag: "--poll-interval", });
+    }
+    return { timeoutMs, pollIntervalMs, };
+}
+/**
+ * Macro parameter payload from --data/--data-file/--stdin. The JSON object is
+ * passed through as the POST body: `{ "params": {...}, "adminParams": {...} }`.
+ * Values may carry credentials; the plan redacts nothing beyond DSS's own
+ * response echo, so callers must not log payloads.
+ */
+function macroRunParamsFromFlags(flags) {
+    const input = jsonInput(flags);
+    if (input === undefined)
+        return {};
+    const body = {};
+    if (input["params"] !== undefined) {
+        if (input["params"] === null || typeof input["params"] !== "object") {
+            throw new UsageError("Macro run payload params must be an object keyed by macro parameter names.", "invalid_flag_value", undefined, { flag: "--data", });
+        }
+        body.params = input["params"];
+    }
+    if (input["adminParams"] !== undefined) {
+        if (input["adminParams"] === null || typeof input["adminParams"] !== "object") {
+            throw new UsageError("Macro run payload adminParams must be an object.", "invalid_flag_value", undefined, { flag: "--data", });
+        }
+        body.adminParams = input["adminParams"];
+    }
+    return body;
+}
+/** Exact POST body a run will send; empty object when no parameters. */
+function macroRunDryRunPayload(runParams) {
+    const payload = {};
+    if (runParams.params !== undefined)
+        payload["params"] = runParams.params;
+    if (runParams.adminParams !== undefined)
+        payload["adminParams"] = runParams.adminParams;
+    return payload;
+}
+/**
+ * Reject blank/whitespace positional ids as a usage error BEFORE any request:
+ * an empty macro/run id would hit the list route or an unresolvable path.
+ */
+function requireNotBlankId(value, usage) {
+    if (value.trim().length === 0) {
+        throw new UsageError(`Macro/run id must be non-empty. Usage: ${usage}`);
+    }
+}
+export const macroCommands = {
+    list: {
+        handler: (c, _a, f) => c.macros.list(f["project-key"]),
+        usage: "dss macro list [--project-key KEY]",
+        description: "List the macros (runnables) available in a project.",
+        examples: ["dss macro list",],
+    },
+    get: {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, "dss macro get <macro_id>");
+            requireNotBlankId(a[0], "dss macro get <macro_id>");
+            return c.macros.definition(a[0], {
+                projectKey: f["project-key"],
+            });
+        },
+        usage: "dss macro get <macro_id> [--project-key KEY]",
+        description: "Get a macro's definition: parameters, result type, owning plugin, labels.",
+        examples: ["dss macro get compute_orders",],
+    },
+    run: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss macro run <macro_id>");
+            const pk = f["project-key"];
+            const waitOptions = macroWaitOptionsFromFlags(f);
+            const runParams = macroRunParamsFromFlags(f);
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "run",
+                    resource: "macro",
+                    id: a[0],
+                    ...waitOptions,
+                    ...(runParams.params !== undefined ? { params: runParams.params, } : {}),
+                    ...(runParams.adminParams !== undefined
+                        ? { adminParams: runParams.adminParams, }
+                        : {}),
+                    endpoint: encodedProjectEndpoint(c, pk, `/runnables/${encodeURIComponent(a[0])}?wait=false`),
+                    method: "POST",
+                    payload: macroRunDryRunPayload(runParams),
+                    warning: "Macro runs execute arbitrary plugin code on the DSS backend; review the macro definition before running.",
+                };
+            }
+            if (f["wait"] === true) {
+                return c.macros.runAndWait(a[0], {
+                    ...waitOptions,
+                    ...runParams,
+                    projectKey: pk,
+                });
+            }
+            return c.macros.run(a[0], { ...runParams, projectKey: pk, });
+        },
+        usage: MACRO_RUN_USAGE,
+        description: "Start a macro run. Macros execute arbitrary plugin code and are classified destructive. --wait polls to completion and exits 4 on failure; without it only the runId is returned. --data JSON may carry { params: {...}, adminParams: {...} } for parameterized macros.",
+        examples: [
+            "dss macro run compute_orders",
+            "dss macro run compute_orders --wait",
+            'dss macro run compute_orders --data \'{"params":{"region":"EU"}}\'',
+            "dss macro run compute_orders --wait --timeout 300000",
+        ],
+    },
+    "run-and-wait": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss macro run-and-wait <macro_id>");
+            const pk = f["project-key"];
+            const waitOptions = macroWaitOptionsFromFlags(f);
+            const runParams = macroRunParamsFromFlags(f);
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "run-and-wait",
+                    resource: "macro",
+                    id: a[0],
+                    ...waitOptions,
+                    ...(runParams.params !== undefined ? { params: runParams.params, } : {}),
+                    ...(runParams.adminParams !== undefined
+                        ? { adminParams: runParams.adminParams, }
+                        : {}),
+                    endpoint: encodedProjectEndpoint(c, pk, `/runnables/${encodeURIComponent(a[0])}?wait=false`),
+                    method: "POST",
+                    payload: macroRunDryRunPayload(runParams),
+                    warning: "Macro runs execute arbitrary plugin code on the DSS backend; review the macro definition before running.",
+                };
+            }
+            return c.macros.runAndWait(a[0], {
+                ...waitOptions,
+                ...runParams,
+                projectKey: pk,
+            });
+        },
+        usage: "dss macro run-and-wait <macro_id> [--timeout MS (default 120000)] [--poll-interval MS] [--data JSON] [--dry-run] [--project-key KEY]",
+        description: "Run a macro and poll its state until it finishes. Exits 4 on failure; returns { success: false, timedOut: true } on timeout.",
+        examples: [
+            "dss macro run-and-wait compute_orders",
+            "dss macro run-and-wait compute_orders --timeout 60000 --poll-interval 500",
+        ],
+    },
+    abort: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 2, "dss macro abort <macro_id> <run_id>");
+            requireNotBlankId(a[0], "dss macro abort <macro_id> <run_id>");
+            requireNotBlankId(a[1], "dss macro abort <macro_id> <run_id>");
+            const pk = f["project-key"];
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "abort",
+                    resource: "macro",
+                    id: a[0],
+                    runId: a[1],
+                    endpoint: encodedProjectEndpoint(c, pk, `/runnables/${encodeURIComponent(a[0])}/abort/${encodeURIComponent(a[1])}`),
+                    method: "POST",
+                };
+            }
+            await c.macros.abort(a[0], a[1], pk);
+            return { aborted: a[1], runId: a[1], resource: "macro", };
+        },
+        usage: "dss macro abort <macro_id> <run_id> [--dry-run] [--project-key KEY]",
+        description: "Request abort of a running macro run.",
+        examples: ["dss macro abort compute_orders run_42",],
+    },
+    state: {
+        handler: (c, a, f) => {
+            requireArgs(a, 2, "dss macro state <macro_id> <run_id>");
+            requireNotBlankId(a[0], "dss macro state <macro_id> <run_id>");
+            requireNotBlankId(a[1], "dss macro state <macro_id> <run_id>");
+            return c.macros.state(a[0], a[1], {
+                projectKey: f["project-key"],
+            });
+        },
+        usage: "dss macro state <macro_id> <run_id> [--project-key KEY]",
+        description: "Get the poll state of a macro run: running flag, progress stack, failure details.",
+        examples: ["dss macro state compute_orders run_42",],
+    },
+    result: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 2, "dss macro result <macro_id> <run_id>");
+            requireNotBlankId(a[0], "dss macro result <macro_id> <run_id>");
+            requireNotBlankId(a[1], "dss macro result <macro_id> <run_id>");
+            const pk = f["project-key"];
+            const maxBytes = num(f["max-bytes"], "--max-bytes");
+            if (maxBytes !== undefined && (maxBytes < 1 || !Number.isInteger(maxBytes))) {
+                throw new UsageError("--max-bytes must be a positive integer.", "invalid_flag_value", undefined, { flag: "--max-bytes", });
+            }
+            return c.macros.result(a[0], a[1], {
+                projectKey: pk,
+                maxBytes: macroResultMaxBytes(maxBytes),
+            });
+        },
+        usage: "dss macro result <macro_id> <run_id> [--max-bytes N (default 8388608)] [--project-key KEY]",
+        description: "Download a macro run's result. Text/HTML bodies print as a JSON string (stdout stays one JSON document, embedded newlines escaped); JSON bodies print as the parsed object.",
+        examples: ["dss macro result compute_orders run_42", "dss macro result m r --max-bytes 1024",],
+    },
+};

package/dist/src/cli/commands/meaning.js

@@ -1,4 +1,5 @@
 import { jsonInput, requiredJsonInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { isNotFoundError, planResult, skipResult, } from "../output.js";
 import { requireArgs, } from "../usage.js";
 const MEANING_PLAN_FAILURE_CODES = { usage: 1, error: 2, transient: 3, };
@@ -40,7 +41,7 @@ export const meaningCommands = {
             requireArgs(a, 3, "dss meaning create <id> <label> <type> [--data JSON|--data-file PATH|--stdin] [--dry-run]");
             const body = jsonInput(f) ?? {};
             const payload = meaningCreatePayload(a[0], a[1], a[2], body);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return planResult("meaning", "create", {
                     asyncKind: "none",
                     method: "POST",
@@ -62,7 +63,7 @@ export const meaningCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss meaning update <meaningId> (--data JSON|--data-file PATH|--stdin) [--dry-run]");
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (meaning definition).");
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return planResult("meaning", "update", {
                     asyncKind: "none",
                     method: "PUT",
@@ -83,7 +84,7 @@ export const meaningCommands = {
     delete: {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss meaning delete <meaningId>");
-            if (f["dry-run"] === true || f["if-exists"] === true) {
+            if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await c.meanings.get(a[0]).catch((error) => {
                     if (isNotFoundError(error)
                         || (error instanceof Error && /unknown meaning/i.test(error.message))) {
@@ -93,7 +94,7 @@ export const meaningCommands = {
                 });
                 if (!current)
                     return skipResult("meaning", a[0], "missing");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return planResult("meaning", "delete", {
                         asyncKind: "none",
                         method: "DELETE",

package/dist/src/cli/commands/ml-task.js

@@ -1,4 +1,5 @@
-import { requiredJsonInput, requiredStringFlag, } from "../coerce.js";
+import { num, requiredJsonInput, requiredStringFlag, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { requireArgs, UsageError, } from "../usage.js";
 function optionalStringFlag(flags, name) {
     const value = flags[name];
@@ -77,21 +78,33 @@ export const mlTaskCommands = {
         ],
     },
     train: {
-        handler: (c, a, f) => {
-            requireArgs(a, 2, "dss ml-task train <analysisId> <mlTaskId> [--session-name NAME] [--wait] [--project-key KEY]");
+        handler: async (c, a, f) => {
+            const usage = "dss ml-task train <analysisId> <mlTaskId> [--session-name NAME] [--wait] [--timeout MS] [--poll-interval MS] [--dry-run] [--project-key KEY]";
+            requireArgs(a, 2, usage);
             const options = {
                 analysisId: a[0],
                 mlTaskId: a[1],
                 sessionName: optionalStringFlag(f, "session-name"),
                 wait: f["wait"] === true,
+                timeoutMs: num(f["timeout"], "--timeout"),
+                pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
                 projectKey: f["project-key"],
             };
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "train",
+                    resource: "ml-task",
+                    ...options,
+                };
+            }
             return c.mlTasks.train(options);
         },
-        usage: "dss ml-task train <analysisId> <mlTaskId> [--session-name NAME] [--wait] [--project-key KEY]",
-        description: "Start ML task training, optionally waiting for trained model IDs.",
+        usage: "dss ml-task train <analysisId> <mlTaskId> [--session-name NAME] [--wait] [--timeout MS] [--poll-interval MS] [--dry-run] [--project-key KEY]",
+        description: "Start ML task training, optionally waiting for trained model IDs. --timeout bounds only the wait phase after DSS accepts training; an invalid timeout fails before any request.",
         examples: [
-            "dss ml-task train ANALYSIS_ID TASK_ID --session-name baseline --wait --project-key PROJECT",
+            "dss ml-task train ANALYSIS_ID TASK_ID --session-name baseline --wait --timeout 60000 --project-key PROJECT",
+            "dss ml-task train ANALYSIS_ID TASK_ID --wait --timeout 0 --poll-interval 1000 --project-key PROJECT",
         ],
     },
     "list-models": {
@@ -127,7 +140,7 @@ export const mlTaskCommands = {
                 testDatasetRef: optionalStringFlag(f, "test-dataset"),
                 projectKey: f["project-key"],
             };
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "deploy",
@@ -148,7 +161,7 @@ export const mlTaskCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 2, "dss ml-task delete <analysisId> <mlTaskId> [--dry-run] [--project-key KEY]");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "delete",

package/dist/src/cli/commands/model-evaluation-store.js

@@ -1,4 +1,5 @@
 import { requiredStringFlag, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { readIfExists, skipResult, } from "../output.js";
 import { requireArgs, } from "../usage.js";
 export const modelEvaluationStoreCommands = {
@@ -23,7 +24,7 @@ export const modelEvaluationStoreCommands = {
             const name = requiredStringFlag(f, "name", usage);
             const projectKey = f["project-key"];
             const options = { name, projectKey, };
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "create",
@@ -56,11 +57,11 @@ export const modelEvaluationStoreCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss model-evaluation-store delete <storeId> [--if-exists] [--dry-run] [--project-key KEY]");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true || f["if-exists"] === true) {
+            if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.modelEvaluationStores.get(a[0], projectKey));
                 if (!current)
                     return skipResult("model-evaluation-store", a[0], "missing");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return {
                         dryRun: true,
                         action: "delete",

package/dist/src/cli/commands/notebook.js

@@ -1,4 +1,5 @@
 import { jsonInput, num, parseBooleanOption, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { encodedProjectEndpoint, readIfExists, skipResult, } from "../output.js";
 import { requireArgs, requireNoArgs, UsageError, } from "../usage.js";
 export const notebookCommands = {
@@ -26,11 +27,11 @@ export const notebookCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss notebook delete-jupyter <name>");
             const pk = f["project-key"];
-            if (f["dry-run"] === true || f["if-exists"] === true) {
+            if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.notebooks.getJupyter(a[0], pk));
                 if (!current)
                     return skipResult("jupyter-notebook", a[0], "missing");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return { dryRun: true, action: "delete", resource: "jupyter-notebook", name: a[0], current, };
                 }
             }
@@ -45,7 +46,7 @@ export const notebookCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss notebook clear-jupyter-outputs <name>");
             const pk = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 // The real mutation is a single server-side DELETE of the
                 // outputs endpoint, so the dry run can only report the current
                 // content (read-only) and the exact request that would run; the
@@ -82,7 +83,7 @@ export const notebookCommands = {
             const pk = f["project-key"];
             if (f["all"] === true) {
                 requireNoArgs(a, "dss notebook unload-jupyter --all [--dry-run] [--project-key KEY]");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     const planned = [];
                     for (const notebook of await c.notebooks.listJupyter(pk, { active: true, })) {
                         for (const session of await c.notebooks.listJupyterSessions(notebook.name, pk)) {
@@ -106,7 +107,7 @@ export const notebookCommands = {
                 return { unloaded, resource: "jupyter-notebook", all: true, };
             }
             requireArgs(a, 2, "dss notebook unload-jupyter <name> <sessionId>");
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const sessions = await c.notebooks.listJupyterSessions(a[0], pk);
                 const current = sessions.find((session) => session.sessionId === a[1]);
                 return {
@@ -149,11 +150,11 @@ export const notebookCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss notebook delete-sql <id>");
             const pk = f["project-key"];
-            if (f["dry-run"] === true || f["if-exists"] === true) {
+            if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.notebooks.getSql(a[0], pk));
                 if (!current)
                     return skipResult("sql-notebook", a[0], "missing");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return { dryRun: true, action: "delete", resource: "sql-notebook", id: a[0], current, };
                 }
             }
@@ -181,7 +182,7 @@ export const notebookCommands = {
                 throw new UsageError("--data, --data-file, or --stdin is required (notebook JSON content).");
             }
             const pk = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await readIfExists(() => c.notebooks.getJupyter(a[0], pk));
                 return {
                     dryRun: true,
@@ -217,7 +218,7 @@ export const notebookCommands = {
                 throw new UsageError("--data, --data-file, or --stdin is required (SQL notebook content JSON).");
             }
             const pk = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await readIfExists(() => c.notebooks.getSql(a[0], pk));
                 return {
                     dryRun: true,
@@ -232,14 +233,18 @@ export const notebookCommands = {
                 expectHash: f["expect-hash"],
             });
             return {
-                saved: a[0],
+                // `saved` is the persisted notebook id: on create DSS allocates it
+                // server-side, so every later command must use this id. `requested`
+                // echoes the handle, which becomes the notebook's display name.
+                saved: result.id,
+                requested: a[0],
                 resource: "sql-notebook",
                 created: result.created,
                 hash: result.hash,
             };
         },
         usage: "dss notebook save-sql <id> (--data '{...}' | --data-file PATH | --stdin) [--expect-hash SHA256] [--dry-run] [--project-key KEY]",
-        description: "Save content to a SQL notebook, creating it if missing. Reports created versus updated and the persisted content hash; --expect-hash rejects a stale read before writing.",
+        description: "Save content to a SQL notebook, creating it if missing. On create DSS allocates the notebook id: `saved` is the persisted id to use for every later read/update/delete, and `requested` echoes the handle, which becomes the display name. Reports created versus updated and the persisted content hash; --expect-hash rejects a stale read before writing and refuses a missing notebook.",
         examples: ["dss notebook save-sql my_sql_notebook --data-file content.json --dry-run",],
     },
     "clear-sql-history": {
@@ -251,7 +256,7 @@ export const notebookCommands = {
                 numRunsToRetain: num(f["retain"], "--retain"),
                 projectKey: pk,
             };
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await c.notebooks.getSqlHistory(a[0], pk);
                 return {
                     dryRun: true,

package/dist/src/cli/commands/plugin.d.ts

@@ -0,0 +1,2 @@
+import type { CommandMeta } from "../types.js";
+export declare const pluginCommands: Record<string, CommandMeta>;