dataiku-sdk 4.0.0 → 4.2.0

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

@@ -1,6 +1,8 @@
 import type { ScenarioDetails, ScenarioStatus, ScenarioSummary, ScenarioWaitResult } from "../schemas.js";
 import { BaseResource } from "./base.js";
-export declare const SCENARIO_CANONICAL_EDITABLE_FIELDS: readonly ["params.steps", "params.triggers", "params.reporters", "params.customScript", "active", "name"];
+import { type ScenarioListSelector } from "./scenario-authoring.js";
+/** DSS keeps triggers and reporters at the top level of the scenario (as dataikuapi does), not under params. */
+export declare const SCENARIO_CANONICAL_EDITABLE_FIELDS: readonly ["params.steps", "triggers", "reporters", "params.customScript", "active", "name"];
 /** Default byte cap applied when fetching a scenario run log. */
 export declare const DEFAULT_SCENARIO_MAX_LOG_BYTES = 1048576;
 /** One entry of GET /scenarios/{id}/get-last-runs — a finished (or running) scenario run summary. */
@@ -44,6 +46,45 @@ export interface ScenarioRunDetails {
     };
     stepRuns?: ScenarioRunStepReport[];
 }
+/** One firing of a scenario trigger: what `POST /scenarios/{id}/run` returns (not a scenario run). */
+export interface ScenarioTriggerFire {
+    triggerId: string;
+    triggerRunId: string;
+    cancelled: boolean;
+}
+/** A trigger fire resolved against the scenario run it started (if any). */
+export interface ScenarioTriggerRunState extends ScenarioTriggerFire {
+    state: "PENDING" | "RUNNING" | "FINISHED" | "CANCELLED";
+    /** The scenario run id (what get-run and log take), once DSS started the run. */
+    runId?: string;
+    outcome?: string;
+    start?: number;
+}
+/** Test-scenario report text (JUnit XML), byte-bounded. */
+export interface ScenarioRunReport {
+    text: string;
+    truncated: boolean;
+    maxBytes: number;
+}
+export type ScenarioListKind = "trigger" | "reporter";
+/** Outcome of adding or removing one trigger/reporter. */
+export interface ScenarioListEdit {
+    kind: ScenarioListKind;
+    /** Position of the added element (as stored) or of the removed one. */
+    index: number;
+    /** The element as DSS stored it (added) or as it was (removed). */
+    item: unknown;
+    /** Elements left in the list. */
+    count: number;
+}
+export interface ScenarioRunAsResult {
+    scenarioId: string;
+    /** The explicit run-as login, or null when the scenario runs as its last editor. */
+    runAsUser: string | null;
+    /** Who the scenario actually runs as (dataikuapi `effective_run_as`). */
+    effectiveRunAs?: string;
+    previousRunAsUser?: string;
+}
 /** Bounded log retrieval result: text plus whether the byte cap cut it. */
 export interface ScenarioRunLog {
     text: string;
@@ -120,6 +161,8 @@ export interface ScenarioScriptRunResult {
     /** Observable throwaway-scenario cleanup outcome; never silently swallowed here. */
     cleanup: ScenarioScriptRunCleanup;
 }
+/** Who a scenario really runs as: its `runAsUser`, else the last editor (dataikuapi `effective_run_as`). */
+export declare function effectiveRunAs(scenario: Record<string, unknown>): string | undefined;
 export declare function normalizeScenarioUpdateData(data: Record<string, unknown>): {
     normalizedData: Record<string, unknown>;
     normalization: ScenarioUpdateNormalization[];
@@ -138,14 +181,23 @@ export declare class ScenariosResource extends BaseResource {
         data?: Record<string, unknown>;
         projectKey?: string;
     }): Promise<void>;
-    /** Trigger a scenario run. */
-    run(scenarioId: string, projectKey?: string): Promise<{
-        runId: string;
-    }>;
+    /**
+     * 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.
+     */
+    run(scenarioId: string, opts?: {
+        params?: Record<string, unknown>;
+        projectKey?: string;
+    }): Promise<ScenarioTriggerFire>;
     /** Get the light/status view of a scenario. */
     status(scenarioId: string, projectKey?: string): Promise<ScenarioStatus>;
     /** Merge-update a scenario's definition, then refetch and verify requested fields persisted. */
     update(scenarioId: string, data: Record<string, unknown>, projectKey?: string): Promise<ScenarioUpdateResult>;
+    /** PUT the merge of `data` into an already-read scenario, refetch, and verify it persisted. */
+    private applyUpdate;
     /** Delete a scenario. */
     delete(scenarioId: string, projectKey?: string): Promise<void>;
     /**
@@ -153,6 +205,7 @@ export declare class ScenariosResource extends BaseResource {
      * Returns `{ success: false, timedOut: true }` on timeout rather than throwing.
      */
     runAndWait(scenarioId: string, opts?: {
+        params?: Record<string, unknown>;
         pollIntervalMs?: number;
         timeoutMs?: number;
         projectKey?: string;
@@ -177,11 +230,46 @@ export declare class ScenariosResource extends BaseResource {
      * actually stop, so this does not wait for termination.
      */
     abort(scenarioId: string, projectKey?: string): Promise<void>;
-    /** 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`).
+     */
     getLastRuns(scenarioId: string, opts?: {
         limit?: number;
+        onlyFinished?: boolean;
         projectKey?: string;
     }): Promise<ScenarioRunSummary[]>;
+    /**
+     * 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.
+     */
+    getRunsByDate(scenarioId: string, opts: {
+        from: string;
+        to?: string;
+        projectKey?: string;
+    }): Promise<ScenarioRunSummary[]>;
+    /**
+     * 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.
+     */
+    getRunReport(scenarioId: string, runId: string, opts?: {
+        stepId?: string;
+        maxBytes?: number;
+        projectKey?: string;
+    }): Promise<ScenarioRunReport>;
+    /**
+     * 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.
+     */
+    getRunForTrigger(scenarioId: string, triggerRunId: string, opts?: {
+        triggerId?: string;
+        projectKey?: string;
+    }): Promise<ScenarioTriggerRunState>;
     /** Get the details of a specific run (GET /scenarios/{id}/{runId}). */
     getRunDetails(scenarioId: string, runId: string, opts?: {
         projectKey?: string;
@@ -216,14 +304,43 @@ export declare class ScenariosResource extends BaseResource {
     setActive(scenarioId: string, active: boolean, opts?: {
         projectKey?: string;
     }): Promise<ScenarioActiveUpdateResult>;
+    /** The scenario's triggers or reporters, in DSS order (GET /scenarios/{id}/). */
+    listItems(kind: ScenarioListKind, scenarioId: string, opts?: {
+        projectKey?: string;
+    }): Promise<unknown[]>;
+    private getSettings;
+    /**
+     * 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).
+     */
+    addItem(kind: ScenarioListKind, scenarioId: string, item: Record<string, unknown>, opts?: {
+        projectKey?: string;
+    }): Promise<ScenarioListEdit>;
+    /** Remove the trigger or reporter selected by `--index`/`--name`, keeping every other element. */
+    removeItem(kind: ScenarioListKind, scenarioId: string, selector: ScenarioListSelector, opts?: {
+        projectKey?: string;
+    }): Promise<ScenarioListEdit>;
+    /**
+     * 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.
+     */
+    setRunAs(scenarioId: string, user: string | null, opts?: {
+        projectKey?: string;
+    }): Promise<ScenarioRunAsResult>;
     /**
-     * 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).
+     * 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.
      */
     private trackTriggerRun;
+    /** Whether DSS cancelled this trigger fire (GET /scenarios/trigger/{id}/{triggerId}?triggerRunId=). */
+    private isTriggerFireCancelled;
     /**
      * Best-effort step outcome summaries from the run report
      * (GET /scenarios/{id}/{runId}). Never fails the wait: an unavailable

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