dataiku-sdk 4.0.0 → 4.2.0

package/dist/src/cli/contract.js

@@ -253,6 +253,7 @@ const ALLOWED_CLEANUP_ACTIONS = new Set([
     "data-collection delete",
     "plugin delete",
     "connection delete",
+    "messaging-channel delete",
     "user delete",
     "group delete",
 ]);
@@ -669,6 +670,9 @@ function inferSideEffect(resource, action) {
     }
     if (resource === "install-skill")
         return "write";
+    // `send` matches no mutating verb, yet delivers real mail through the channel.
+    if (resource === "messaging-channel" && action === "send")
+        return "write";
     if (resource === "sql" && action === "query")
         return "write";
     if (resource === "ml-task" && action === "train")
@@ -735,7 +739,7 @@ function inferSideEffect(resource, action) {
         .test(action)
         // Compound actions whose mutating verb is a suffix (e.g. permissions-set,
         // dataset-compute, saved-model external-metadata-put).
-        || /-(set|compute|restore|put)$/.test(action)) {
+        || /-(set|compute|restore|put|add|remove)$/.test(action)) {
         return "write";
     }
     return "read";
@@ -779,10 +783,16 @@ const STRING_OUTPUT_ACTIONS = new Set([
  */
 const SCOPED_OUTPUT_SHAPES = {
     "folder.contents": "array",
+    "scenario.last-runs": "array",
+    "scenario.runs-by-date": "array",
+    "scenario.trigger-list": "array",
+    "scenario.reporter-list": "array",
+    "scenario.run-report": "string",
     "plugin.usages": "object",
     "plugin.download": "object",
     "dataset.download": "object",
     "project-library.get": "string",
+    "messaging-channel.permissions-get": "array",
     "project-library.diff": "object",
 };
 function inferOutputShape(resource, action) {
@@ -919,6 +929,11 @@ const EXPLICIT_DESTRUCTIVE_KEYS = {
     // MLflow cleanup permanently erases experiment-tracking data.
     "mlflow.garbage-collect": true,
     "mlflow.clean-db": true,
+    // Removing a trigger or reporter drops its configuration; no public route restores it.
+    "scenario.trigger-remove": true,
+    "scenario.reporter-remove": true,
+    // A sent mail is delivered to external recipients and cannot be recalled.
+    "messaging-channel.send": true,
 };
 function inferDestructiveLevel(resource, sideEffect, action) {
     if (sideEffect !== "write")
@@ -945,7 +960,8 @@ function inferAsyncKind(resource, action) {
         return "job";
     if (resource === "future" && ["get", "peek", "wait", "abort",].includes(action))
         return "future";
-    if (resource === "scenario" && ["run", "run-and-wait", "status",].includes(action)) {
+    if (resource === "scenario"
+        && ["run", "run-and-wait", "status", "get-run-for-trigger",].includes(action)) {
         return "future";
     }
     if (resource === "user" && ADMIN_SECURITY_FUTURE_ACTIONS[action] === true)
@@ -1518,7 +1534,7 @@ export function buildAgentContract() {
                     "dss commands run --fields dataset",
                     "dss commands run --fields dataset.create",
                 ],
-                scopedDiscoveryHint: "Default: resource/action summary. --contains TEXT: top 5 actions by concept. --fields RESOURCE: all resource entries; RESOURCE.ACTION: one entry keyed by that path; append .FIELD for nested metadata. Comma-separate paths. --output PATH exports the full registry.",
+                scopedDiscoveryHint: "Default: resource/action summary. --contains TEXT: top 5 actions by concept. --fields RESOURCE: each action's usage, description, and side effect; RESOURCE.ACTION: one full entry keyed by that path; append .FIELD for nested metadata. Comma-separate paths. --output PATH exports full entries (the full registry without --fields).",
                 // Accepted by every command and absent from per-entry `flags`; the
                 // connection flags matter only for commands that call DSS.
                 globalFlags: [...GLOBAL_AGENT_FLAGS, ...AUTHENTICATED_AGENT_FLAGS,].map((name) => {
@@ -1545,7 +1561,7 @@ export function buildAgentContract() {
                 failure: "structured-error-object",
                 failureResultDetailLimitBytes: 65_536,
                 fieldProjection: "Missing --fields paths: null on stdout; field_projection_missing on stderr.",
-                compactResults: "*.list, job get, dataset get/info, project get: compact; --full/--fields use DSS objects; lists take --contains/--limit (list_truncated warning).",
+                compactResults: "*.list, job get, dataset get/info, project get, scenario get-run/last-runs: compact; --full/--fields use DSS objects; lists take --contains/--limit (list_truncated warning).",
                 richFailureResults: "doctor/batch/cleanup failures: own compact {ok:false,...} result on stdout and command exit code; no wrapper.",
             },
             stderr: {

package/dist/src/cli/env.d.ts

@@ -10,4 +10,10 @@ export declare function envFileProvenance(name: string): EnvFileProvenance | und
 export declare function dataikuEnvironmentEnabled(): boolean;
 /** DATAIKU_PROJECT_KEY from the environment, unless `DATAIKU_DISABLE_ENV=1`. */
 export declare function ambientProjectKey(): string | undefined;
+/**
+ * `DSS_PRETTY=1` indents stdout JSON. Agent shells that cut long lines (omp at
+ * 768 bytes) truncate a one-line result; indented output keeps each line short.
+ * Read from the process environment only, never from a `.env` file.
+ */
+export declare function prettyOutputEnabled(): boolean;
 export declare function loadEnvFile(): void;

package/dist/src/cli/env.js

@@ -23,6 +23,14 @@ export function dataikuEnvironmentEnabled() {
 export function ambientProjectKey() {
     return dataikuEnvironmentEnabled() ? process.env.DATAIKU_PROJECT_KEY : undefined;
 }
+/**
+ * `DSS_PRETTY=1` indents stdout JSON. Agent shells that cut long lines (omp at
+ * 768 bytes) truncate a one-line result; indented output keeps each line short.
+ * Read from the process environment only, never from a `.env` file.
+ */
+export function prettyOutputEnabled() {
+    return process.env.DSS_PRETTY === "1";
+}
 const allowedEnvKeys = new Set(["NODE_EXTRA_CA_CERTS", "NODE_TLS_REJECT_UNAUTHORIZED",]);
 /**
  * `.env` files are untrusted input: only the CLI's own `DATAIKU_*` variables and

package/dist/src/cli/flags.js

@@ -76,6 +76,9 @@ export const BOOLEAN_FLAGS = new Set([
     "no-auto-rebuild",
     "all-users",
     "with-scenarios",
+    "scenarios-only",
+    "only-finished",
+    "clear",
     "for-everybody",
     "payload-only",
     "allow-same-path",
@@ -102,6 +105,8 @@ export const BOOLEAN_FLAGS = new Set([
     "conda",
     "force",
     "partitioning-folder",
+    "plain-text",
+    "single-message",
 ]);
 export const SHORT_FLAGS = {
     v: "verbose",
@@ -231,6 +236,24 @@ export const VALUE_FLAGS = new Set([
     "repository",
     "request-timeout",
     "params",
+    "params-file",
+    "frequency",
+    "every",
+    "hour",
+    "minute",
+    "days",
+    "day-of-month",
+    "run-on",
+    "start-date",
+    "timezone",
+    "index",
+    "channel",
+    "recipient",
+    "subject",
+    "condition",
+    "phase",
+    "user",
+    "trigger-id",
     "password-env",
     "results-per-page",
     "record-cleanup",
@@ -324,6 +347,16 @@ export const VALUE_FLAGS = new Set([
     "time-variable",
     "timeseries-ids",
     "full-reguess",
+    "cc",
+    "bcc",
+    "subject",
+    "body",
+    "body-file",
+    "attachment",
+    "family",
+    "permissions",
+    "automation-node-id",
+    "id",
 ]);
 export const REPEATABLE_VALUE_FLAGS = new Set([
     "dataset",
@@ -337,6 +370,7 @@ export const REPEATABLE_VALUE_FLAGS = new Set([
     "replace-input",
     "replace-output",
     "replace-payload-text",
+    "attachment",
 ]);
 export const KNOWN_LONG_FLAGS = new Set([
     ...BOOLEAN_FLAGS,

package/dist/src/cli/helpers/cleanup.js

@@ -345,6 +345,17 @@ export function cleanupLedgerEntry(resource, action, args, flags, result, projec
                 cleanup: { argv: ["streaming-endpoint", "delete", id, ...withProject,], },
             };
         }
+        case "messaging-channel.create": {
+            // DSS echoes the id it allocated; an explicit --id is the fallback.
+            const id = stringField(record, ["id",]) ?? flags["id"];
+            if (!id)
+                return undefined;
+            return {
+                ...base,
+                id,
+                cleanup: { argv: ["messaging-channel", "delete", id, "--if-exists",], },
+            };
+        }
         case "meaning.create": {
             const id = args[0];
             return {

package/dist/src/cli/list-shapes.js

@@ -100,6 +100,11 @@ export const COMPACT_LIST_FIELDS = {
         label: field("label", STRING),
         type: field("type", STRING),
     },
+    "messaging-channel": {
+        id: field("id", STRING),
+        type: field("type", STRING),
+        family: field("family", STRING),
+    },
 };
 /** Discovery output schemas of the compact `RESOURCE.list` defaults. */
 export function compactListOutputSchemas() {

package/dist/src/cli/output.d.ts

@@ -11,6 +11,8 @@ export declare function pickResultFields(item: unknown, fields: string[]): unkno
  * that are absent become null so every row keeps a stable, predictable shape.
  */
 export declare function projectResultFields(result: unknown, fields: string[], availableFieldNames?: () => string[]): unknown;
+/** One JSON value plus newline for stdout; indented when `DSS_PRETTY=1`. */
+export declare function stdoutJson(value: unknown): string;
 export declare function writeCommandResult(result: unknown): void;
 export declare function addTransientTargetContext(error: unknown, target: string, elapsedMs: number): never;
 export declare function isFailedWaitResult(result: unknown): boolean;

package/dist/src/cli/output.js

@@ -1,4 +1,5 @@
 import { DataikuError, } from "../errors.js";
+import { prettyOutputEnabled, } from "./env.js";
 let outputFieldProjection;
 export function setOutputFieldProjection(fields) {
     outputFieldProjection = fields;
@@ -98,12 +99,16 @@ export function projectResultFields(result, fields, availableFieldNames) {
         return result.map((item) => pickResultFields(item, fields));
     return pickResultFields(result, fields);
 }
+/** One JSON value plus newline for stdout; indented when `DSS_PRETTY=1`. */
+export function stdoutJson(value) {
+    return `${JSON.stringify(value, null, prettyOutputEnabled() ? 2 : undefined)}\n`;
+}
 export function writeCommandResult(result) {
     const projected = outputFieldProjection
         ? projectResultFields(result, outputFieldProjection)
         : result;
     flushCliWarnings();
-    process.stdout.write(`${JSON.stringify(projected ?? { ok: true, })}\n`);
+    process.stdout.write(stdoutJson(projected ?? { ok: true, }));
 }
 export function addTransientTargetContext(error, target, elapsedMs) {
     if (error instanceof DataikuError && error.category === "transient") {
@@ -200,13 +205,28 @@ export function commandFailureMessage(result) {
             const resume = typeof record.resume === "string" ? ` Resume with: ${record.resume}` : "";
             return `Timed out waiting for job ${record.jobId} after ${record.elapsedMs}ms (last known state: ${record.state}); the job is still running in DSS and was not cancelled.${resume}`;
         }
+        if (record.timedOut === true) {
+            // ML training, scenario runs, futures, code run: the client stopped waiting. Only a
+            // result that says `cancelled: false` proves nothing was stopped; `code run` cleans up
+            // its throwaway scenario, so its `cleanup` status is what tells.
+            const known = typeof record.state === "string"
+                ? record.state
+                : typeof record.outcome === "string"
+                    ? record.outcome
+                    : undefined;
+            const elapsed = typeof record.elapsedMs === "number" ? ` after ${record.elapsedMs}ms` : "";
+            const after = record.cancelled === false
+                ? "the operation was not cancelled and may still be running in DSS."
+                : record.cleanup !== undefined
+                    ? "the client stopped waiting; see `cleanup` for what happened to the run."
+                    : "the client stopped waiting; the operation may still be running in DSS.";
+            return `Timed out waiting${elapsed}${known ? ` (last known state: ${known})` : ""}; ${after}`;
+        }
         const state = typeof record.state === "string"
             ? record.state
             : typeof record.outcome === "string"
                 ? record.outcome
-                : typeof record.timedOut === "boolean"
-                    ? "timed out"
-                    : undefined;
+                : undefined;
         return `Command completed with failed long-running result${state ? `: ${state}` : ""}.`;
     }
     if (isAssertionFailureResult(result)) {

package/dist/src/cli/plans.js

@@ -10,13 +10,16 @@ import { encodeLibraryPath, PROJECT_LIBRARY_CONCURRENCY_CONTROL, validateLibrary
 import { buildRecipeCreateRequest, } from "../resources/recipe-create.js";
 import { modelDiagnosticsBody, } from "../resources/trained-model.js";
 import { encodeGitReferencePath, validateGitReferencePath, } from "../utils/git-reference.js";
+import { sanitizeMessagingChannelSecrets, } from "../utils/messaging-channel-secrets.js";
 import { jobBuildTargetTypeFromFlags, json, jsonInput, num, parseBooleanOption, parseJsonObject, requiredJsonInput, rewritePairsFromFlags, schemaColumnsInput, sha256Hex, stableHash, stringField, textInput, unknownJsonInput, } from "./coerce.js";
 import { parseCodeRunIntegerFlag, resolveCodeInputWithSource, } from "./commands/code.js";
 import { schemaPropagationOptionsFromFlags, } from "./commands/flow.js";
+import { messagingChannelPlanShape, } from "./commands/messaging-channel.js";
 import { mlTaskFieldsFromFlags, mlTaskReguessOptionsFromFlags, } from "./commands/ml-task.js";
 import { deployRunOptionsFromFlags, experimentsDatasetOptionsFromFlags, inferenceInfoFromFlags, } from "./commands/mlflow.js";
 import { projectLibraryPutPayload, } from "./commands/project-library.js";
 import { enqueueRecipeCreateWarnings, recipeCreateOptionsFromFlags, } from "./commands/recipe.js";
+import { scenarioReporterFromFlags, scenarioRunParams, scenarioTriggerFromFlags, } from "./commands/scenario.js";
 import { resolveSqlQueryInvocation, } from "./commands/sql.js";
 import { buildRegistryEntry, splitPackageSpec, } from "./contract.js";
 import { ambientProjectKey, } from "./env.js";
@@ -1209,7 +1212,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 method: "POST",
                 endpoint: projectEndpoint(`/scenarios/${encodeURIComponent(id)}/run/`),
                 identifiers: { id, },
-                payload: {},
+                payload: scenarioRunParams(flags) ?? {},
                 wait: action === "run-and-wait" || flags["wait"] === true,
             };
         case "scenario.delete":
@@ -1230,10 +1233,84 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                     name: args[1],
                     projectKey,
                     type,
-                    params: type === "step_based" ? { steps: [], triggers: [], reporters: [], } : {},
+                    ...(type === "step_based"
+                        ? { params: { steps: [], }, triggers: [], reporters: [], }
+                        : { params: {}, }),
+                    ...jsonInput(flags),
                 },
             };
         }
+        case "scenario.trigger-add":
+        case "scenario.reporter-add": {
+            const isTrigger = action === "trigger-add";
+            const field = isTrigger ? "triggers" : "reporters";
+            const item = isTrigger
+                ? scenarioTriggerFromFlags(flags)
+                : sanitizeMessagingChannelSecrets(scenarioReporterFromFlags(flags));
+            const endpoint = projectEndpoint(`/scenarios/${encodeURIComponent(id)}/`);
+            return {
+                exact: false,
+                reason: `Apply GETs the scenario, appends this element to ${field} (the others are kept), PUTs the full scenario, then GETs it back to verify; the stored element gains DSS-assigned ids.`,
+                method: "PUT",
+                endpoint,
+                identifiers: { id, },
+                payload: item,
+                requests: [
+                    { sequence: 1, method: "GET", endpoint, },
+                    { sequence: 2, method: "PUT", endpoint, payloadEdits: { [field]: { append: item, }, }, },
+                    { sequence: 3, method: "GET", endpoint, },
+                ],
+            };
+        }
+        case "scenario.trigger-remove":
+        case "scenario.reporter-remove": {
+            const field = action === "trigger-remove" ? "triggers" : "reporters";
+            const selector = flags["index"] !== undefined
+                ? { index: num(flags["index"], "--index"), }
+                : { name: flags["name"], };
+            if ((flags["index"] === undefined) === (flags["name"] === undefined)) {
+                throw new UsageError(`Pass exactly one of --index or --name. Usage: ${entry.usage}`);
+            }
+            const endpoint = projectEndpoint(`/scenarios/${encodeURIComponent(id)}/`);
+            return {
+                exact: false,
+                reason: `Apply GETs the scenario, drops the selected element from ${field} (the others are kept), PUTs the full scenario, then GETs it back to verify.`,
+                method: "PUT",
+                endpoint,
+                identifiers: { id, },
+                payload: selector,
+                requests: [
+                    { sequence: 1, method: "GET", endpoint, },
+                    { sequence: 2, method: "PUT", endpoint, payloadEdits: { [field]: { remove: selector, }, }, },
+                    { sequence: 3, method: "GET", endpoint, },
+                ],
+            };
+        }
+        case "scenario.run-as-set": {
+            const user = flags["user"];
+            if ((typeof user === "string") === (flags["clear"] === true)) {
+                throw new UsageError(`Pass exactly one of --user LOGIN or --clear. Usage: ${entry.usage}`);
+            }
+            const endpoint = projectEndpoint(`/scenarios/${encodeURIComponent(id)}/`);
+            return {
+                exact: false,
+                reason: "Apply GETs the scenario, sets (or, with --clear, removes) runAsUser, PUTs the full scenario, then GETs it back to verify.",
+                method: "PUT",
+                endpoint,
+                identifiers: { id, },
+                payload: { runAsUser: typeof user === "string" ? user : null, },
+                requests: [
+                    { sequence: 1, method: "GET", endpoint, },
+                    {
+                        sequence: 2,
+                        method: "PUT",
+                        endpoint,
+                        payloadEdits: { runAsUser: typeof user === "string" ? user : "<removed>", },
+                    },
+                    { sequence: 3, method: "GET", endpoint, },
+                ],
+            };
+        }
         case "scenario.update":
             return {
                 method: "PUT",
@@ -1345,6 +1422,21 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 endpoint: `/public/api/project-deployer/infras/${encodeURIComponent(id)}`,
                 identifiers: { infraId: id, },
             };
+        case "project-deployer.run-test-scenarios": {
+            const nodeFlag = flags["automation-node-id"];
+            const automationNodeId = typeof nodeFlag === "string" && nodeFlag !== "" ? nodeFlag : undefined;
+            return {
+                method: "POST",
+                endpoint: `/public/api/project-deployer/deployments/${encodeURIComponent(id)}/run-test-scenarios${querySuffix({ automationNodeId, })}`,
+                identifiers: { deploymentId: id, },
+            };
+        }
+        case "messaging-channel.create":
+        case "messaging-channel.settings-set":
+        case "messaging-channel.permissions-set":
+        case "messaging-channel.delete":
+        case "messaging-channel.send":
+            return messagingChannelPlanShape(action, args, flags, projectKey);
         case "project-deployer.delete-project":
             return {
                 method: "DELETE",

package/dist/src/cli/read-shapes.js

@@ -32,7 +32,29 @@ export function compactReadOutputSchemas() {
         additionalProperties: false,
         properties: { type: STRING, message: STRING, },
     };
-    return {
+    const triggerSchema = {
+        type: "object",
+        additionalProperties: false,
+        properties: { type: STRING, name: STRING, },
+    };
+    const failureSchema = {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            stepId: STRING,
+            jobId: STRING,
+            dataset: STRING,
+            recipe: STRING,
+            inputs: { type: "array", items: { type: "string", }, },
+            message: STRING,
+        },
+    };
+    const nextSchema = {
+        type: "array",
+        description: "Next commands to run, each as an argv array.",
+        items: { type: "array", items: STRING, },
+    };
+    const schemas = {
         "job.get": {
             type: "object",
             additionalProperties: false,
@@ -110,5 +132,74 @@ export function compactReadOutputSchemas() {
                 lastModifiedBy: STRING,
             },
         },
+        "scenario.get-run": {
+            type: "object",
+            additionalProperties: false,
+            required: ["runId", "steps",],
+            properties: {
+                runId: STRING,
+                scenarioId: STRING,
+                projectKey: STRING,
+                outcome: STRING,
+                start: NUMBER,
+                end: NUMBER,
+                durationMs: NUMBER,
+                trigger: triggerSchema,
+                steps: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        additionalProperties: false,
+                        properties: {
+                            id: STRING,
+                            name: STRING,
+                            type: STRING,
+                            outcome: STRING,
+                            message: STRING,
+                            datasets: {
+                                type: "array",
+                                items: {
+                                    type: "object",
+                                    additionalProperties: false,
+                                    properties: { dataset: STRING, projectKey: STRING, partition: STRING, outcome: STRING, },
+                                },
+                            },
+                            jobs: {
+                                type: "array",
+                                items: {
+                                    type: "object",
+                                    additionalProperties: false,
+                                    properties: { jobId: STRING, outcome: STRING, message: STRING, },
+                                },
+                            },
+                        },
+                    },
+                },
+                failure: failureSchema,
+                next: nextSchema,
+                hint: {
+                    type: "string",
+                    description: "Edit-and-rerun commands when the failed recipe is known.",
+                },
+            },
+        },
+        "scenario.last-runs": {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["runId",],
+                properties: {
+                    runId: STRING,
+                    outcome: STRING,
+                    start: NUMBER,
+                    end: NUMBER,
+                    trigger: triggerSchema,
+                    failure: { type: "object", additionalProperties: false, properties: { message: STRING, }, },
+                    next: nextSchema,
+                },
+            },
+        },
     };
+    return { ...schemas, "scenario.runs-by-date": schemas["scenario.last-runs"], };
 }

package/dist/src/cli/result-shapes.d.ts

@@ -1,6 +1,24 @@
+type Item = Record<string, unknown>;
+/** The failed activity of a job: the recipe that failed and the datasets it read. */
+export interface FailedActivity {
+    recipe: string;
+    inputs: string[];
+}
+/**
+ * Failure diagnosis of a raw `scenario get-run` report: the first failure
+ * (`{ stepId, jobId, dataset, message }`) and the next command(s) to run as
+ * argv arrays. With the failed recipe known, `hint` names the edit-and-rerun
+ * loop, so the agent does not look up the write commands. Empty when the run did not fail.
+ */
+export declare function scenarioRunDiagnosis(details: unknown, activity?: FailedActivity): {
+    failure?: Item;
+    next?: string[][];
+    hint?: string;
+};
 /**
  * Compact a command result for agents: `*.list` items (filter, cap, compact
- * fields) and the four large read commands. `--full` and `--fields` bypass
+ * fields) and the large read commands. `--full` and `--fields` bypass
  * the read shapers so the DSS object (or a projection of it) is returned.
  */
 export declare function shapeCommandResult(resource: string, action: string, result: unknown, flags: Record<string, string | boolean>): unknown;
+export {};