dataiku-sdk 4.1.0 → 4.2.0

package/dist/src/resources/scenarios.js

@@ -4,16 +4,20 @@ import { deepMerge, } from "../utils/deep-merge.js";
 import { computeNextPollDelayMs, isRequestDeadlineError, } from "../utils/polling.js";
 import { isRecord, } from "../utils/records.js";
 import { BaseResource, requireArrayResponse, requireNonEmpty, } from "./base.js";
+import { selectScenarioListIndex, } from "./scenario-authoring.js";
+/** DSS keeps triggers and reporters at the top level of the scenario (as dataikuapi does), not under params. */
 export const SCENARIO_CANONICAL_EDITABLE_FIELDS = [
     "params.steps",
-    "params.triggers",
-    "params.reporters",
+    "triggers",
+    "reporters",
     "params.customScript",
     "active",
     "name",
 ];
 /** Default byte cap applied when fetching a scenario run log. */
 export const DEFAULT_SCENARIO_MAX_LOG_BYTES = 1_048_576;
+/** Where each list lives on the scenario object (top level, as dataikuapi). */
+const SCENARIO_LIST_FIELDS = { trigger: "triggers", reporter: "reporters", };
 /**
  * Wraps a primary code-run failure so the original error (and its taxonomy:
  * category, exit-code semantics) stays intact while the concurrent throwaway
@@ -48,11 +52,55 @@ function triggerRunIdOf(trigger, scenarioId) {
     }
     return runId;
 }
-function triggerQueryOf(trigger) {
-    const triggerObj = trigger.trigger;
-    const triggerId = triggerObj?.id ?? "manual";
-    const triggerRunId = triggerRunIdOf(trigger);
-    return `triggerId=${encodeURIComponent(triggerId)}&triggerRunId=${encodeURIComponent(triggerRunId)}`;
+/** Trigger id (`manual` for API runs), trigger run id and cancellation flag of a POST /run response. */
+function triggerFireOf(trigger, scenarioId) {
+    const triggerId = isRecord(trigger.trigger) && typeof trigger.trigger.id === "string"
+        ? trigger.trigger.id
+        : "manual";
+    return {
+        triggerId,
+        triggerRunId: triggerRunIdOf(trigger, scenarioId),
+        cancelled: trigger.cancelled === true,
+    };
+}
+/** The `triggers`/`reporters` array of a scenario object; absent means empty, any other shape is an error. */
+function scenarioListField(scenario, kind) {
+    const items = scenario[SCENARIO_LIST_FIELDS[kind]];
+    return items === undefined ? [] : requireArrayResponse(items, `scenario ${kind}s`);
+}
+/**
+ * DSS stamps `params.lastUpdate` on every temporal trigger each time the scenario
+ * is saved, so echoing the value it last stored can never be read back (the
+ * verification after a trigger edit would report every trigger as unpersisted).
+ * Omitting it lets DSS stamp afresh, as it does for the other saved triggers.
+ */
+function withoutServerStamp(item) {
+    if (!isRecord(item) || !isRecord(item.params) || !("lastUpdate" in item.params))
+        return item;
+    const { lastUpdate: _stamp, ...params } = item.params;
+    return { ...item, params, };
+}
+/** `YYYY-MM-DD` day of a date or ISO date-time (the day DSS filters runs by); anything else is a usage error. */
+function scenarioDay(value, name) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})(?:[T ].*)?$/.exec(value);
+    if (match) {
+        const day = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])));
+        if (day.getUTCMonth() === Number(match[2]) - 1 && day.getUTCDate() === Number(match[3])) {
+            return `${match[1]}-${match[2]}-${match[3]}`;
+        }
+    }
+    throw new ClientValidationError(`${name} must be a YYYY-MM-DD date or ISO date-time, got ${JSON.stringify(value)}.`, "invalid_flag_value");
+}
+/** Who a scenario really runs as: its `runAsUser`, else the last editor (dataikuapi `effective_run_as`). */
+export function effectiveRunAs(scenario) {
+    if (typeof scenario.runAsUser === "string")
+        return scenario.runAsUser;
+    for (const tag of [scenario.versionTag, scenario.creationTag,]) {
+        if (isRecord(tag) && isRecord(tag.lastModifiedBy) && typeof tag.lastModifiedBy.login === "string") {
+            return tag.lastModifiedBy.login;
+        }
+    }
+    return undefined;
 }
 /** A finite number, or undefined for anything else (absent/malformed JSON fields). */
 function optionalNumber(value) {
@@ -320,12 +368,37 @@ export function scenarioUpdatePreview(current, data) {
 }
 function scenarioUpdateVerificationError(mismatches, normalization) {
     const mismatchPaths = mismatches.map((mismatch) => mismatch.path).join(", ");
-    return new DataikuError(400, "Scenario Update Verification Failed", JSON.stringify({
+    const body = {
         message: `Scenario update did not persist requested fields after refetch: ${mismatchPaths}`,
         mismatches,
         canonicalEditableFields: SCENARIO_CANONICAL_EDITABLE_FIELDS,
         ...(normalization.length > 0 ? { normalization, } : {}),
-    }));
+    };
+    const error = new DataikuError(400, "Scenario Update Verification Failed", JSON.stringify(body));
+    // CLI envelopes show `details`, never the body. Only paths go there: reporter and step
+    // values can hold webhook URLs, tokens, or credentials.
+    error.details = {
+        mismatches: mismatches.map((mismatch) => ({
+            path: mismatch.path,
+            differingPaths: differingLeafPaths(mismatch.expected, mismatch.actual, mismatch.path),
+        })),
+        canonicalEditableFields: SCENARIO_CANONICAL_EDITABLE_FIELDS,
+    };
+    return error;
+}
+/** Paths under `path` where the sent value is missing or different in what DSS stored (e.g. `reporters.0.messaging.channelId`). */
+function differingLeafPaths(expected, actual, path) {
+    if (Array.isArray(expected)) {
+        if (!Array.isArray(actual))
+            return [path,];
+        return expected.flatMap((item, index) => differingLeafPaths(item, actual[index], `${path}.${index}`));
+    }
+    if (isRecord(expected)) {
+        if (!isRecord(actual))
+            return [path,];
+        return Object.entries(expected).flatMap(([key, value,]) => differingLeafPaths(value, actual[key], `${path}.${key}`));
+    }
+    return jsonValueEqual(expected, actual) ? [] : [path,];
 }
 export class ScenariosResource extends BaseResource {
     /** List all scenarios in a project. */
@@ -348,16 +421,24 @@ export class ScenariosResource extends BaseResource {
             name,
             projectKey: pk,
             type: scenarioType,
-            params: scenarioType === "step_based" ? { steps: [], triggers: [], reporters: [], } : {},
+            ...(scenarioType === "step_based"
+                ? { params: { steps: [], }, triggers: [], reporters: [], }
+                : { params: {}, }),
             ...opts?.data,
         };
         await this.client.post(`/public/api/projects/${this.enc(opts?.projectKey)}/scenarios/`, body);
     }
-    /** Trigger a scenario run. */
-    async run(scenarioId, projectKey) {
+    /**
+     * Trigger a scenario run. `params` is sent as the POST body (dataikuapi
+     * `run(params)`) and reaches the run as its trigger parameters. The result
+     * identifies the TRIGGER fire, not a scenario run: resolve it with
+     * {@link getRunForTrigger}. `cancelled` is already true when DSS refused the
+     * fire because the scenario is running.
+     */
+    async run(scenarioId, opts) {
         const scEnc = encodeURIComponent(requireNonEmpty(scenarioId, "scenarioId"));
-        const result = await this.client.post(`/public/api/projects/${this.enc(projectKey)}/scenarios/${scEnc}/run/`, {});
-        return { runId: triggerRunIdOf(result, scenarioId), };
+        const result = await this.client.post(`/public/api/projects/${this.enc(opts?.projectKey)}/scenarios/${scEnc}/run/`, opts?.params ?? {});
+        return triggerFireOf(result, scenarioId);
     }
     /** Get the light/status view of a scenario. */
     async status(scenarioId, projectKey) {
@@ -367,12 +448,15 @@ export class ScenariosResource extends BaseResource {
     }
     /** Merge-update a scenario's definition, then refetch and verify requested fields persisted. */
     async update(scenarioId, data, projectKey) {
-        const scEnc = encodeURIComponent(scenarioId);
-        const pkEnc = this.enc(projectKey);
-        const current = await this.client.get(`/public/api/projects/${pkEnc}/scenarios/${scEnc}/`);
+        const current = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/scenarios/${encodeURIComponent(scenarioId)}/`);
+        return this.applyUpdate(scenarioId, current, data, projectKey);
+    }
+    /** PUT the merge of `data` into an already-read scenario, refetch, and verify it persisted. */
+    async applyUpdate(scenarioId, current, data, projectKey) {
+        const path = `/public/api/projects/${this.enc(projectKey)}/scenarios/${encodeURIComponent(scenarioId)}/`;
         const preview = scenarioUpdatePreview(current, data);
-        await this.client.put(`/public/api/projects/${pkEnc}/scenarios/${scEnc}/`, preview.next);
-        const after = await this.client.get(`/public/api/projects/${pkEnc}/scenarios/${scEnc}/`);
+        await this.client.put(path, preview.next);
+        const after = await this.client.get(path);
         const mismatches = scenarioFieldMismatches(after, preview.next, preview.normalizedData);
         if (mismatches.length > 0) {
             throw scenarioUpdateVerificationError(mismatches, preview.normalization);
@@ -406,14 +490,15 @@ export class ScenariosResource extends BaseResource {
         // POST /run/ returns a TRIGGER run id, which differs from the actual scenario
         // run id; resolve the real run via get-run-for-trigger so a completed scenario
         // is not misreported as a timeout (the trigger id never matches lastRun).
-        const trigger = await this.client.post(`${base}/run/`, {});
-        const tracked = await this.trackTriggerRun(scenarioId, base, trigger, {
+        const trigger = await this.client.post(`${base}/run/`, opts?.params ?? {});
+        const fire = triggerFireOf(trigger, scenarioId);
+        const tracked = await this.trackTriggerRun(scenarioId, opts?.projectKey, trigger, {
             startedAt,
             baseIntervalMs,
             adaptivePolling,
             timeout,
         });
-        const resolvedRunId = tracked.runId || triggerRunIdOf(trigger);
+        const resolvedRunId = tracked.runId || fire.triggerRunId;
         const steps = tracked.timedOut || !tracked.runId
             ? undefined
             : await this.runStepSummaries(base, tracked.runId);
@@ -424,9 +509,10 @@ export class ScenariosResource extends BaseResource {
             success: tracked.outcome === "SUCCESS",
             elapsedMs: Date.now() - startedAt,
             pollCount: tracked.pollCount,
-            ...(triggerRunIdOf(trigger) !== resolvedRunId
-                ? { triggerRunId: triggerRunIdOf(trigger), }
+            ...(fire.triggerRunId !== resolvedRunId || tracked.cancelled
+                ? { triggerRunId: fire.triggerRunId, }
                 : {}),
+            ...(tracked.cancelled ? { cancelled: true, } : {}),
             ...(tracked.timedOut ? { timedOut: true, } : {}),
             ...(steps ? { steps, } : {}),
         };
@@ -470,7 +556,7 @@ export class ScenariosResource extends BaseResource {
                 extension: "py",
             });
             const trigger = await this.client.post(`${base}/run/`, {});
-            const tracked = await this.trackTriggerRun(scenarioId, base, trigger, {
+            const tracked = await this.trackTriggerRun(scenarioId, opts?.projectKey, trigger, {
                 startedAt,
                 baseIntervalMs,
                 adaptivePolling,
@@ -535,16 +621,81 @@ export class ScenariosResource extends BaseResource {
         const scEnc = encodeURIComponent(scenarioId);
         await this.client.post(`/public/api/projects/${this.enc(projectKey)}/scenarios/${scEnc}/abort`);
     }
-    /** Get the raw last-runs list (GET /scenarios/{id}/get-last-runs/?limit=N). */
+    /**
+     * Get the raw last-runs list (GET /scenarios/{id}/get-last-runs/?limit=N).
+     * `onlyFinished` drops runs still in progress (DSS `onlyFinishedRuns`).
+     */
     async getLastRuns(scenarioId, opts) {
         if (opts?.limit !== undefined && (!Number.isInteger(opts.limit) || opts.limit < 1)) {
             throw new ClientValidationError(`limit must be a positive integer, got ${opts.limit}.`);
         }
         const scEnc = encodeURIComponent(scenarioId);
-        const query = opts?.limit !== undefined ? `?limit=${opts.limit}` : "";
-        const raw = await this.client.get(`/public/api/projects/${this.enc(opts?.projectKey)}/scenarios/${scEnc}/get-last-runs/${query}`);
+        const query = new URLSearchParams();
+        if (opts?.limit !== undefined)
+            query.set("limit", String(opts.limit));
+        if (opts?.onlyFinished === true)
+            query.set("onlyFinishedRuns", "true");
+        const suffix = query.size > 0 ? `?${query}` : "";
+        const raw = await this.client.get(`/public/api/projects/${this.enc(opts?.projectKey)}/scenarios/${scEnc}/get-last-runs/${suffix}`);
         return requireArrayResponse(raw, "scenarios.getLastRuns").map(scenarioRunSummaryFromRaw);
     }
+    /**
+     * Runs that started between two days (GET /scenarios/{id}/get-runs-by-date).
+     * Dates are `YYYY-MM-DD` or ISO date-times (the time part is dropped, as
+     * dataikuapi does). DSS treats `to` as exclusive (verified live: `from=to=today`
+     * is empty and today's runs need `to=tomorrow`), so it defaults to tomorrow
+     * rather than dataikuapi's today, which would leave today's runs out.
+     */
+    async getRunsByDate(scenarioId, opts) {
+        const query = new URLSearchParams({
+            fromDate: scenarioDay(opts.from, "from"),
+            toDate: scenarioDay(opts.to ?? new Date(Date.now() + 86_400_000).toLocaleDateString("en-CA"), "to"),
+        });
+        const raw = await this.client.get(`/public/api/projects/${this.enc(opts.projectKey)}/scenarios/${encodeURIComponent(requireNonEmpty(scenarioId, "scenarioId"))}/get-runs-by-date?${query}`);
+        return requireArrayResponse(raw, "scenarios.getRunsByDate").map(scenarioRunSummaryFromRaw);
+    }
+    /**
+     * JUnit XML report of a test scenario run (GET /scenarios/{id}/{runId}/scenario-run-report),
+     * or of one step with `stepId` (…/step-run-report?stepId=). DSS only builds
+     * reports for scenarios marked as test; the text is byte-bounded like the log.
+     */
+    async getRunReport(scenarioId, runId, opts) {
+        if (opts?.stepId !== undefined)
+            requireNonEmpty(opts.stepId, "stepId");
+        const maxBytes = Math.max(0, Math.floor(opts?.maxBytes ?? DEFAULT_SCENARIO_MAX_LOG_BYTES));
+        const runPath = `/public/api/projects/${this.enc(opts?.projectKey)}/scenarios/${encodeURIComponent(requireNonEmpty(scenarioId, "scenarioId"))}/${encodeURIComponent(requireNonEmpty(runId, "runId"))}`;
+        const { text, truncated, } = await this.client.getTextLimited(opts?.stepId === undefined
+            ? `${runPath}/scenario-run-report`
+            : `${runPath}/step-run-report?stepId=${encodeURIComponent(opts.stepId)}`, maxBytes);
+        return { text, truncated, maxBytes, };
+    }
+    /**
+     * Resolve a trigger run (what `run` returns) to its scenario run: the scenario
+     * run id once DSS started one, or `CANCELLED` when DSS cancelled the fire (a
+     * run already in progress suppresses it) and no run will ever exist.
+     */
+    async getRunForTrigger(scenarioId, triggerRunId, opts) {
+        const pkEnc = this.enc(opts?.projectKey);
+        const triggerId = requireNonEmpty(opts?.triggerId ?? "manual", "triggerId");
+        const fire = { triggerId, triggerRunId: requireNonEmpty(triggerRunId, "triggerRunId"), };
+        const run = await this.client.get(`/public/api/projects/${pkEnc}/scenarios/${encodeURIComponent(requireNonEmpty(scenarioId, "scenarioId"))}/get-run-for-trigger?triggerId=${encodeURIComponent(triggerId)}&triggerRunId=${encodeURIComponent(fire.triggerRunId)}`);
+        if (isRecord(run.scenarioRun)) {
+            const outcome = isRecord(run.scenarioRun.result) && typeof run.scenarioRun.result.outcome === "string"
+                ? run.scenarioRun.result.outcome
+                : undefined;
+            const start = optionalNumber(run.scenarioRun.start);
+            return {
+                ...fire,
+                cancelled: false,
+                state: outcome === undefined ? "RUNNING" : "FINISHED",
+                ...(typeof run.scenarioRun.runId === "string" ? { runId: run.scenarioRun.runId, } : {}),
+                ...(outcome === undefined ? {} : { outcome, }),
+                ...(start === undefined ? {} : { start, }),
+            };
+        }
+        const cancelled = await this.isTriggerFireCancelled(pkEnc, scenarioId, fire);
+        return { ...fire, cancelled, state: cancelled ? "CANCELLED" : "PENDING", };
+    }
     /** Get the details of a specific run (GET /scenarios/{id}/{runId}). */
     async getRunDetails(scenarioId, runId, opts) {
         return this.client.get(`/public/api/projects/${this.enc(opts?.projectKey)}/scenarios/${encodeURIComponent(scenarioId)}/${encodeURIComponent(runId)}/`);
@@ -604,34 +755,108 @@ export class ScenariosResource extends BaseResource {
             status: scenarioLightStatusFromRaw(after),
         };
     }
+    /** The scenario's triggers or reporters, in DSS order (GET /scenarios/{id}/). */
+    async listItems(kind, scenarioId, opts) {
+        return scenarioListField(await this.getSettings(scenarioId, opts?.projectKey), kind);
+    }
+    async getSettings(scenarioId, projectKey) {
+        return this.client.get(`/public/api/projects/${this.enc(projectKey)}/scenarios/${encodeURIComponent(requireNonEmpty(scenarioId, "scenarioId"))}/`);
+    }
     /**
-     * Poll get-run-for-trigger until the triggered run reports an outcome or the
-     * deadline elapses. Shared by runAndWait and runScript: POST /run/ returns a
-     * TRIGGER run id, which differs from the actual scenario run id, so the real
-     * run is resolved via get-run-for-trigger (the trigger id never matches
-     * lastRun and would misreport a completed scenario as a timeout).
+     * Append a trigger or reporter. `triggers`/`reporters` are arrays, which a merge
+     * update replaces wholesale, so this reads the current list and writes it back
+     * with the new element last (then verifies the stored result).
      */
-    async trackTriggerRun(scenarioId, base, trigger, timing) {
-        triggerRunIdOf(trigger, scenarioId);
-        const trigQuery = triggerQueryOf(trigger);
+    async addItem(kind, scenarioId, item, opts) {
+        const current = await this.getSettings(scenarioId, opts?.projectKey);
+        const items = scenarioListField(current, kind);
+        const result = await this.applyUpdate(scenarioId, current, {
+            [SCENARIO_LIST_FIELDS[kind]]: [...items.map(withoutServerStamp), item,],
+        }, opts?.projectKey);
+        const stored = scenarioListField(result.after, kind);
+        return { kind, index: items.length, item: stored[items.length], count: stored.length, };
+    }
+    /** Remove the trigger or reporter selected by `--index`/`--name`, keeping every other element. */
+    async removeItem(kind, scenarioId, selector, opts) {
+        const current = await this.getSettings(scenarioId, opts?.projectKey);
+        const items = scenarioListField(current, kind);
+        const index = selectScenarioListIndex(items, selector, kind);
+        const result = await this.applyUpdate(scenarioId, current, {
+            [SCENARIO_LIST_FIELDS[kind]]: items.flatMap((existing, position) => position === index ? [] : [withoutServerStamp(existing),]),
+        }, opts?.projectKey);
+        return {
+            kind,
+            index,
+            item: items[index],
+            count: scenarioListField(result.after, kind).length,
+        };
+    }
+    /**
+     * Set (`user`) or clear (`null`) the scenario's `runAsUser` (admin only for a
+     * non-null value). Clearing deletes the key, which a merge update cannot do.
+     */
+    async setRunAs(scenarioId, user, opts) {
+        const path = `/public/api/projects/${this.enc(opts?.projectKey)}/scenarios/${encodeURIComponent(requireNonEmpty(scenarioId, "scenarioId"))}/`;
+        const current = await this.client.get(path);
+        const { runAsUser: previous, ...withoutRunAs } = current;
+        await this.client.put(path, user === null ? withoutRunAs : { ...withoutRunAs, runAsUser: user, });
+        const after = await this.client.get(path);
+        const stored = typeof after.runAsUser === "string" ? after.runAsUser : null;
+        if (stored !== user) {
+            const error = new DataikuError(400, "Scenario Update Verification Failed", `Scenario run-as did not persist after refetch: expected ${user === null ? "no runAsUser" : "the requested user"}.`);
+            error.details = { mismatches: [{ path: "runAsUser", },], };
+            throw error;
+        }
+        return {
+            scenarioId,
+            runAsUser: stored,
+            effectiveRunAs: effectiveRunAs(after),
+            ...(typeof previous === "string" ? { previousRunAsUser: previous, } : {}),
+        };
+    }
+    /**
+     * Poll get-run-for-trigger until the triggered run reports an outcome, DSS
+     * cancels the trigger fire, or the deadline elapses. Shared by runAndWait and
+     * runScript: POST /run/ returns a TRIGGER run id, which differs from the actual
+     * scenario run id, so the real run is resolved via get-run-for-trigger (the
+     * trigger id never matches lastRun and would misreport a completed scenario as
+     * a timeout). While no scenario run exists yet, the trigger fire itself is read:
+     * DSS cancels a fire when the scenario is already running (or a newer fire
+     * replaces it), and then no run will ever appear.
+     */
+    async trackTriggerRun(scenarioId, projectKey, trigger, timing) {
+        const fire = triggerFireOf(trigger, scenarioId);
+        if (fire.cancelled) {
+            return { runId: "", outcome: "CANCELLED", timedOut: false, cancelled: true, pollCount: 0, };
+        }
+        const pkEnc = this.enc(projectKey);
+        const base = `/public/api/projects/${pkEnc}/scenarios/${encodeURIComponent(scenarioId)}`;
+        const trigQuery = `triggerId=${encodeURIComponent(fire.triggerId)}&triggerRunId=${encodeURIComponent(fire.triggerRunId)}`;
+        const remainingMs = () => Math.max(1, timing.timeout - (Date.now() - timing.startedAt));
         let runId = "";
         let pollCount = 0;
         while (true) {
             if (Date.now() - timing.startedAt >= timing.timeout) {
-                return { runId, outcome: "TIMEOUT", timedOut: true, pollCount, };
+                return { runId, outcome: "TIMEOUT", timedOut: true, cancelled: false, pollCount, };
             }
             pollCount += 1;
-            // Budget the per-poll GET by the remaining wait so a stalling
+            // Budget the per-poll GETs by the remaining wait so a stalling
             // trigger-status endpoint cannot defeat the overall run deadline.
-            const remainingMs = Math.max(1, timing.timeout - (Date.now() - timing.startedAt));
             let run;
+            let cancelled = false;
             try {
-                run = await this.client.get(`${base}/get-run-for-trigger?${trigQuery}`, { timeoutMs: remainingMs, });
+                run = await this.client.get(`${base}/get-run-for-trigger?${trigQuery}`, { timeoutMs: remainingMs(), });
+                if (!isRecord(run.scenarioRun)) {
+                    cancelled = await this.isTriggerFireCancelled(pkEnc, scenarioId, fire, remainingMs());
+                }
             }
             catch (error) {
                 if (!isRequestDeadlineError(error, timing.startedAt + timing.timeout))
                     throw error;
-                return { runId, outcome: "TIMEOUT", timedOut: true, pollCount, };
+                return { runId, outcome: "TIMEOUT", timedOut: true, cancelled: false, pollCount, };
+            }
+            if (cancelled) {
+                return { runId, outcome: "CANCELLED", timedOut: false, cancelled: true, pollCount, };
             }
             const scenarioRun = run.scenarioRun;
             if (scenarioRun) {
@@ -639,7 +864,7 @@ export class ScenariosResource extends BaseResource {
                 const result = scenarioRun.result;
                 const finished = result?.outcome;
                 if (finished) {
-                    return { runId, outcome: finished, timedOut: false, pollCount, };
+                    return { runId, outcome: finished, timedOut: false, cancelled: false, pollCount, };
                 }
             }
             const nextDelayMs = computeNextPollDelayMs({
@@ -648,10 +873,15 @@ export class ScenariosResource extends BaseResource {
                 adaptiveEnabled: timing.adaptivePolling,
             });
             const { promise, resolve, } = Promise.withResolvers();
-            setTimeout(resolve, Math.min(nextDelayMs, Math.max(1, timing.timeout - (Date.now() - timing.startedAt))));
+            setTimeout(resolve, Math.min(nextDelayMs, remainingMs()));
             await promise;
         }
     }
+    /** Whether DSS cancelled this trigger fire (GET /scenarios/trigger/{id}/{triggerId}?triggerRunId=). */
+    async isTriggerFireCancelled(pkEnc, scenarioId, fire, timeoutMs) {
+        const raw = await this.client.get(`/public/api/projects/${pkEnc}/scenarios/trigger/${encodeURIComponent(scenarioId)}/${encodeURIComponent(fire.triggerId)}?triggerRunId=${encodeURIComponent(fire.triggerRunId)}`, timeoutMs === undefined ? undefined : { timeoutMs, });
+        return raw.cancelled === true;
+    }
     /**
      * Best-effort step outcome summaries from the run report
      * (GET /scenarios/{id}/{runId}). Never fails the wait: an unavailable

package/dist/src/utils/messaging-channel-secrets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Replace every credential in a channel list item, definition, settings object,
+ * creation body, or permission payload with `[redacted]`. `secrets` adds exact
+ * values to scrub from free text (error messages echoing the request).
+ */
+export declare function sanitizeMessagingChannelSecrets<T>(value: T, secrets?: string[]): T;
+/** Exact secret values of a request body, for scrubbing a DSS error that echoes it. */
+export declare function messagingChannelSecretsFromBody(body: unknown): string[];
+/** Scrub an error that may echo a submitted channel configuration before it reaches output. */
+export declare function sanitizeMessagingChannelError(error: unknown, secrets: string[]): unknown;
+/**
+ * Optimistic-concurrency token for channel settings. It hashes the redacted
+ * view, so it can be published next to redacted output without handing out a
+ * checksum of the credentials (a checksum would let low-entropy passwords be
+ * guessed offline). Credential-only edits therefore do not change it.
+ */
+export declare function messagingChannelSettingsHash(settings: unknown): string;

package/dist/src/utils/messaging-channel-secrets.js

@@ -0,0 +1,114 @@
+import { isRecord, } from "./records.js";
+import { credentialValues, normalizeSecretKey, sanitizeErrorSecrets, sanitizeSecrets, SECRET_REDACTED, } from "./secret-sanitize.js";
+import { stableHash, } from "./stable-hash.js";
+/**
+ * Keys of a messaging-channel configuration that carry credentials or bearer
+ * material: SMTP/Graph/SES secrets, Slack/Teams/Google Chat webhooks (the URL
+ * itself is the credential), Twilio tokens. Matched after stripping `-`/`_` and
+ * lowercasing. The SDK resource layer forwards values verbatim to DSS (over
+ * TLS) and returns server responses unmodified; CLI output, plans, previews and
+ * errors replace these with `[redacted]`. Login names and sender addresses are
+ * identifiers, not secrets, and stay visible.
+ */
+const SENSITIVE_MESSAGING_CHANNEL_KEYS = {
+    accesskey: true,
+    apikey: true,
+    apitoken: true,
+    authorization: true,
+    authorizationtoken: true,
+    authtoken: true,
+    clientsecret: true,
+    credential: true,
+    credentials: true,
+    password: true,
+    privatekey: true,
+    secretkey: true,
+    token: true,
+    webhookkey: true,
+    webhooktoken: true,
+    webhookurl: true,
+};
+/**
+ * SMTP session properties are `{key, value, secret}` entries (`mail.smtp.password`, ...).
+ * The value is a secret when DSS flags the entry `secret` or the property name says so.
+ */
+const SECRET_PROPERTY_NAME = /pass|secret|token|auth|credential|key/i;
+function isSecretSessionProperty(property) {
+    return isRecord(property) && typeof property["key"] === "string"
+        && (property["secret"] === true || SECRET_PROPERTY_NAME.test(property["key"]));
+}
+/** Blank the value of secret session properties, at any depth. */
+function redactSessionProperties(value) {
+    if (Array.isArray(value))
+        return value.map(redactSessionProperties);
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([name, item,]) => {
+        if (normalizeSecretKey(name) === "sessionproperties" && Array.isArray(item)) {
+            return [
+                name,
+                item.map((property) => isSecretSessionProperty(property) ? { ...property, value: SECRET_REDACTED, } : property),
+            ];
+        }
+        return [name, redactSessionProperties(item),];
+    }));
+}
+/**
+ * Replace every credential in a channel list item, definition, settings object,
+ * creation body, or permission payload with `[redacted]`. `secrets` adds exact
+ * values to scrub from free text (error messages echoing the request).
+ */
+export function sanitizeMessagingChannelSecrets(value, secrets = []) {
+    return sanitizeSecrets(redactSessionProperties(value), {
+        sensitiveKeys: SENSITIVE_MESSAGING_CHANNEL_KEYS,
+        secrets,
+        redactUrlUserinfo: true,
+    });
+}
+/** Exact secret values of a request body, for scrubbing a DSS error that echoes it. */
+export function messagingChannelSecretsFromBody(body) {
+    const found = [];
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            value.forEach(visit);
+            return;
+        }
+        if (!isRecord(value))
+            return;
+        for (const [key, item,] of Object.entries(value)) {
+            if (SENSITIVE_MESSAGING_CHANNEL_KEYS[normalizeSecretKey(key)] === true) {
+                if (typeof item === "string")
+                    found.push(item);
+                continue;
+            }
+            if (normalizeSecretKey(key) === "sessionproperties" && Array.isArray(item)) {
+                for (const property of item) {
+                    if (isSecretSessionProperty(property) && typeof property["value"] === "string") {
+                        found.push(property["value"]);
+                    }
+                }
+                continue;
+            }
+            visit(item);
+        }
+    };
+    visit(body);
+    return [...found, ...credentialValues(body),];
+}
+/** Scrub an error that may echo a submitted channel configuration before it reaches output. */
+export function sanitizeMessagingChannelError(error, secrets) {
+    return sanitizeErrorSecrets(error, {
+        sensitiveKeys: SENSITIVE_MESSAGING_CHANNEL_KEYS,
+        secrets,
+        redactUrlUserinfo: true,
+    });
+}
+/**
+ * Optimistic-concurrency token for channel settings. It hashes the redacted
+ * view, so it can be published next to redacted output without handing out a
+ * checksum of the credentials (a checksum would let low-entropy passwords be
+ * guessed offline). Credential-only edits therefore do not change it.
+ */
+export function messagingChannelSettingsHash(settings) {
+    return stableHash(sanitizeMessagingChannelSecrets(settings));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dataiku-sdk",
-	"version": "4.1.0",
+	"version": "4.2.0",
 	"description": "Dataiku DSS SDK and CLI for programmatic access to DSS REST APIs",
 	"repository": {
 		"type": "git",

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "dataiku-sdk",
-	"version": "4.1.0",
+	"version": "4.2.0",
 	"description": "Dataiku DSS SDK and agent-oriented CLI for programmatic access to DSS REST APIs.",
 	"homepage": "https://github.com/clssck/dataiku-sdk",
 	"repository": "https://github.com/clssck/dataiku-sdk",

package/skills/dataiku-dss/SKILL.md

@@ -22,9 +22,9 @@ Reads (`list`, `get`, `preview`, `schema`, `cat`, `log`, `last-runs`): run them
 name or flag fails before any DSS call, and the error carries the usage line or a "Did you mean".
 Before the first write of an action, fetch its entry once (syntax, payload schema, side effects,
 dry-run, cleanup), several in one request: `dss commands run --fields recipe.set-payload,recipe.update`.
-Unknown names: `dss commands run` lists resources and actions; `--fields recipe` gives recipe usage
-lines. Contract version: `dss agent contract --fields agentContractVersion`. Never load the full
-registry into context; export it if needed: `dss commands run --output commands.json`.
+Unknown names: `dss commands run` lists actions; by concept: `dss commands run --contains "build dataset"`.
+Contract version: `dss agent contract --fields agentContractVersion`. Never load the full registry;
+export it if needed: `dss commands run --output commands.json`.
 
 ## Safety and results
 
@@ -58,3 +58,4 @@ Paths are relative to this skill, not CWD. Do not preload all references.
 | Flow maps and zones | [Flow](references/flow-maps.md) |
 | Recipes, libraries, notebooks, Git, code envs | [Coding](references/coding.md) |
 | Failures, build logs, downloads, SQL, schema changes | [Troubleshooting](references/troubleshooting.md) |
+| Scenario alerts, messaging channels, test reports | [Notifications](references/notifications.md) |

package/skills/dataiku-dss/references/notifications.md

@@ -0,0 +1,29 @@
+# Scenario notifications, messaging channels, test reports
+
+## Email notification for a scenario, end to end
+
+1. Find a mail channel: `dss messaging-channel list --family mail` (compact: `id`, `type`, `family`). Empty: there is none; an admin creates one (step 5).
+2. `dss messaging-channel get CHANNEL_ID` shows its sender. Credentials (password, secret keys, webhook URLs, tokens) are always `[redacted]` in output, plans, and errors.
+3. Attach it: `dss scenario reporter-add SCENARIO --channel CHANNEL_ID --recipient a@x.com,b@x.com --subject 'Scenario ${scenarioName}: ${outcome}' --message 'Finished with ${outcome}' --dry-run`, then apply without `--dry-run`. `--phase START|END` (default END), `--condition EXPR` limits when it fires. Other channel types (Slack, Teams, ...): pass the reporter JSON with `--data-file`.
+4. Check: `dss scenario reporter-list SCENARIO`. `dss messaging-channel permissions-get CHANNEL_ID` shows which users and groups may use the channel.
+5. Admin only, creating a channel: `dss messaging-channel create --type smtp --id mail-main --data-file smtp.json --dry-run` (`--type` smtp, aws-ses-mail, microsoft-graph-mail, slack, msteams, google-chat, twilio, shell; `--data` is its configuration; `--permissions '[{"group":"analysts","canUse":true}]'`, every user when omitted). Record it for cleanup with `--record-cleanup`.
+
+Changing a channel: `dss messaging-channel settings-set ID --data '{"sender":"ops@x.com"}' --dry-run` merges into the stored settings; omit credentials you do not change. A `[redacted]` placeholder pasted back is refused. For concurrent edits pass `--expect-hash` with the `settingsHash` from `settings-get` (it covers non-credential fields only).
+
+Send mail directly (external side effect, cannot be recalled; always `--dry-run` first, project needs Write content): `dss messaging-channel send CHANNEL_ID --to a@x.com,b@x.com --subject S --body-file body.html --attachment report.csv --project-key PROJ`. HTML unless `--plain-text`; one mail per `--to` address unless `--single-message`; `--attachment` takes comma-separated or repeated paths.
+
+## Test scenarios
+
+- `dss project testing-status [--bundle-id ID]`: worst outcome across the last runs of the project's test scenarios (scenarios with `markedAsTest`).
+- `dss project test-report [--bundle-id ID]`: JUnit XML of the last test runs, in `report`; `--output PATH` writes the file instead; `--format html --output PATH` writes the HTML page.
+- Project Deployer: `dss project-deployer testing-status DEPLOYMENT [--bundle-id ID] [--automation-node-id ID]`; `dss project-deployer run-test-scenarios DEPLOYMENT --dry-run` previews running the tests on the Automation node (blocks until they finish: raise `--request-timeout`). `--automation-node-id` is only for multi-node deployments.
+- `dss scenario run-report SCENARIO RUNID [--step-id ID] [--output PATH]`: JUnit XML of one run of a test scenario (non-test scenarios: 400).
+
+## Scenario setup and history
+
+- Triggers: `dss scenario trigger-add SCENARIO --frequency minutely|hourly|daily|weekly|monthly [--every N --hour H --minute M --days Monday,Friday --day-of-month D --run-on ON_THE_DAY|LAST_DAY_OF_THE_MONTH|FIRST_WEEK..LAST_WEEK --start-date YYYY-MM-DD --timezone TZ --name N]`, or any trigger type with `--data`. `trigger-list` gives the 0-based `index` for `trigger-remove --index N` (or `--name X`). Each add/remove rewrites the whole list, keeping the others, and verifies it; `--dry-run` previews. Triggers fire only while the scenario is active (`scenario active-set SCENARIO true`).
+- Reporters: `reporter-list`, `reporter-remove --index N|--name X` as above; `--full` shows DSS objects with credentials redacted.
+- Run as: `dss scenario run-as-set SCENARIO --user LOGIN` (administrators) or `--clear` (runs as the last editor); the result's `effectiveRunAs` is the user DSS will use; `scenario status` shows `runAsUser`.
+- Create with settings: `dss scenario create ID NAME --data '{"triggers":[...],"reporters":[...],"markedAsTest":true}'`.
+- Run: `scenario run ID --params '{"region":"EU"}'` (or `--params-file`). Without `--wait` it returns a trigger run id (`triggerRunId`, not a run id); `scenario get-run-for-trigger ID TRIGGERRUNID` returns `state` PENDING, RUNNING, FINISHED (`runId`, `outcome`) or CANCELLED (DSS refused the fire because a run was in progress: wait or `scenario abort`, then run again). `run-and-wait` / `run --wait` end CANCELLED, exit 4, in that case.
+- History: `scenario last-runs ID --only-finished --limit 1` is the last finished run (`outcome`); `scenario runs-by-date ID --from 2026-10-01 --to 2026-11-01` (`--to` exclusive; default tomorrow). `dss future list --scenarios-only` lists running scenario futures.