dataiku-sdk 4.0.0 → 4.2.0

package/dist/src/resources/messaging-channels.d.ts

@@ -0,0 +1,83 @@
+import { BaseResource } from "./base.js";
+/** One entry of a channel's permission list: a group or a user, and whether it may use the channel. */
+export interface MessagingChannelPermission extends Record<string, unknown> {
+    group?: string;
+    user?: string;
+    canUse?: boolean;
+}
+/** A channel as DSS lists or returns it. Configuration fields (credentials included) arrive unredacted. */
+export interface MessagingChannel extends Record<string, unknown> {
+    id?: string;
+    type?: string;
+    family?: string;
+}
+export interface MessagingChannelListOptions {
+    /** Channel type to filter by, e.g. `smtp`, `aws-ses-mail`, `slack`. */
+    channelType?: string;
+    /** Channel family to filter by; `mail` selects every channel that sends email-like messages. */
+    channelFamily?: string;
+}
+export interface MessagingChannelCreateRequest {
+    type: string;
+    /** Channel id; DSS allocates one when omitted. */
+    id?: string;
+    /** Type-specific configuration (host, sender, webhookUrl, ...). */
+    configuration?: Record<string, unknown>;
+    /** Usage permissions; `null`/omitted lets DSS grant every user. */
+    permissions?: MessagingChannelPermission[] | null;
+}
+export interface MailAttachment {
+    /** Local file to attach. */
+    path: string;
+    /** Name the recipient sees; defaults to the file's base name. */
+    fileName?: string;
+}
+export interface MailMessageRequest {
+    to: string[];
+    subject: string;
+    body: string;
+    cc?: string[];
+    bcc?: string[];
+    /** Sender address; defaults to the sender configured on the channel. */
+    from?: string;
+    /** Send `body` as plain text instead of HTML. */
+    plainText?: boolean;
+}
+export interface MailSendOptions {
+    /** Project issuing the email; the caller needs "Write content" on it. Defaults to the client's project. */
+    projectKey?: string;
+    /** One message to every `to` address (true) or one message per address (false, DSS default). */
+    sendAsSingleMessage?: boolean;
+    attachments?: MailAttachment[];
+}
+/** The JSON `message` part of the send request, shaped like the official Python client's payload. */
+export declare function mailMessagePayload(message: MailMessageRequest): Record<string, unknown>;
+/** Query string of the send request. */
+export declare function mailSendQuery(projectKey: string, sendAsSingleMessage: boolean | undefined): URLSearchParams;
+/** The POST body of a channel creation, as the official Python client sends it. */
+export declare function messagingChannelCreateBody(request: MessagingChannelCreateRequest): Record<string, unknown>;
+export declare class MessagingChannelsResource extends BaseResource {
+    /** List messaging channels visible to the caller, optionally filtered by type or family. */
+    list(options?: MessagingChannelListOptions): Promise<MessagingChannel[]>;
+    /** Get one channel (type, family, and for mail channels the sender). */
+    get(channelId: string): Promise<MessagingChannel>;
+    /** Create a channel (admin). DSS returns the created channel. */
+    create(request: MessagingChannelCreateRequest): Promise<MessagingChannel>;
+    /** Get a channel's settings, i.e. its configuration (admin). */
+    getSettings(channelId: string): Promise<Record<string, unknown>>;
+    /** Replace a channel's settings (admin); pass the object obtained from {@link getSettings}. */
+    saveSettings(channelId: string, settings: Record<string, unknown>): Promise<void>;
+    /** Get the users and groups allowed to use a channel. */
+    getPermissions(channelId: string): Promise<MessagingChannelPermission[]>;
+    /** Replace a channel's permission list. */
+    setPermissions(channelId: string, permissions: MessagingChannelPermission[]): Promise<void>;
+    /** Delete a channel (admin). */
+    delete(channelId: string): Promise<void>;
+    /**
+     * Send an email through a mail-family channel, as a multipart request: a JSON
+     * `message` part plus one `attachments` part per file. This sends real mail
+     * and is never retried.
+     */
+    send(channelId: string, message: MailMessageRequest, options?: MailSendOptions): Promise<void>;
+    private channelPath;
+}

package/dist/src/resources/messaging-channels.js

@@ -0,0 +1,108 @@
+import { readFile, } from "node:fs/promises";
+import { basename, } from "node:path";
+import { ClientValidationError, } from "../errors.js";
+import { BaseResource, requireArrayResponse, requireNonEmpty, requireObject, } from "./base.js";
+/** The JSON `message` part of the send request, shaped like the official Python client's payload. */
+export function mailMessagePayload(message) {
+    return {
+        from: message.from ?? null,
+        to: message.to,
+        cc: message.cc ?? null,
+        bcc: message.bcc ?? null,
+        subject: message.subject,
+        body: message.body,
+        plainText: message.plainText ?? false,
+    };
+}
+/** Query string of the send request. */
+export function mailSendQuery(projectKey, sendAsSingleMessage) {
+    return new URLSearchParams({
+        projectKey,
+        sendAsSingleMessage: String(sendAsSingleMessage ?? false),
+    });
+}
+/** The POST body of a channel creation, as the official Python client sends it. */
+export function messagingChannelCreateBody(request) {
+    return {
+        id: request.id ? requireNonEmpty(request.id, "channelId") : "",
+        type: requireNonEmpty(request.type, "type"),
+        configuration: request.configuration === undefined
+            ? {}
+            : requireObject(request.configuration, "configuration"),
+        permissions: request.permissions ?? null,
+    };
+}
+export class MessagingChannelsResource extends BaseResource {
+    /** List messaging channels visible to the caller, optionally filtered by type or family. */
+    async list(options = {}) {
+        const query = new URLSearchParams();
+        if (options.channelType !== undefined)
+            query.set("channelType", options.channelType);
+        if (options.channelFamily !== undefined)
+            query.set("channelFamily", options.channelFamily);
+        const suffix = query.size > 0 ? `?${query.toString()}` : "";
+        const channels = await this.client.get(`/public/api/messaging-channels/${suffix}`);
+        return requireArrayResponse(channels, "messagingChannels.list");
+    }
+    /** Get one channel (type, family, and for mail channels the sender). */
+    async get(channelId) {
+        return this.client.get(this.channelPath(channelId));
+    }
+    /** Create a channel (admin). DSS returns the created channel. */
+    async create(request) {
+        return this.client.post("/public/api/messaging-channels/", messagingChannelCreateBody(request));
+    }
+    /** Get a channel's settings, i.e. its configuration (admin). */
+    async getSettings(channelId) {
+        return this.client.get(`${this.channelPath(channelId)}/settings`);
+    }
+    /** Replace a channel's settings (admin); pass the object obtained from {@link getSettings}. */
+    async saveSettings(channelId, settings) {
+        await this.client.putVoid(`${this.channelPath(channelId)}/settings`, requireObject(settings, "settings"));
+    }
+    /** Get the users and groups allowed to use a channel. */
+    async getPermissions(channelId) {
+        const permissions = await this.client.get(`${this.channelPath(channelId)}/permissions`);
+        return requireArrayResponse(permissions, "messagingChannels.getPermissions");
+    }
+    /** Replace a channel's permission list. */
+    async setPermissions(channelId, permissions) {
+        await this.client.putVoid(`${this.channelPath(channelId)}/permissions`, permissions);
+    }
+    /** Delete a channel (admin). */
+    async delete(channelId) {
+        await this.client.del(this.channelPath(channelId));
+    }
+    /**
+     * Send an email through a mail-family channel, as a multipart request: a JSON
+     * `message` part plus one `attachments` part per file. This sends real mail
+     * and is never retried.
+     */
+    async send(channelId, message, options = {}) {
+        const parts = [{
+                name: "message",
+                blob: new Blob([JSON.stringify(mailMessagePayload(message)),], {
+                    type: "application/json",
+                }),
+                fileName: "send-payload.json",
+            },];
+        for (const attachment of options.attachments ?? []) {
+            let blob;
+            try {
+                blob = new Blob([await readFile(attachment.path),]);
+            }
+            catch {
+                throw new ClientValidationError(`Attachment could not be read: ${attachment.path}`, "validation_failed", "Verify that the path names an existing, readable file.", { path: attachment.path, });
+            }
+            parts.push({
+                name: "attachments",
+                blob,
+                fileName: attachment.fileName ?? basename(attachment.path),
+            });
+        }
+        await this.client.uploadFormVoid(`${this.channelPath(channelId)}/actions/send`, parts, mailSendQuery(this.resolveProjectKey(options.projectKey), options.sendAsSingleMessage));
+    }
+    channelPath(channelId) {
+        return `/public/api/messaging-channels/${encodeURIComponent(requireNonEmpty(channelId, "channelId"))}`;
+    }
+}

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

@@ -87,6 +87,12 @@ export interface ProjectImportResult extends ProjectImportProcessResult {
     /** SHA-256 fingerprint of the landed project's creationTag. Present on verified success. */
     projectIncarnationHash?: string;
 }
+export interface TestScenarioRunsReportOptions {
+    /** Automation-node bundle whose test runs are reported; the active bundle when omitted. */
+    bundleId?: string;
+    /** `junit` (default) is JUnit XML; `html` is a rendered page. */
+    format?: "junit" | "html";
+}
 export declare class ProjectsResource extends BaseResource {
     /** Create a new project. */
     createProject(projectKey: string, name: string, ownerLogin: string, settings?: ProjectLifecycleSettings | null): Promise<Record<string, unknown>>;
@@ -139,6 +145,24 @@ export declare class ProjectsResource extends BaseResource {
      * covers branches, commits, pulls, and remotes.
      */
     pushToGitRemote(remote: string, projectKey?: string): Promise<void>;
+    /**
+     * Get the testing status of a project: the worst outcome across the last
+     * runs of its test scenarios. On an Automation node, `bundleId` restricts
+     * the runs to those made while that bundle was active.
+     */
+    getTestingStatus(projectKey?: string, bundleId?: string): Promise<Record<string, unknown>>;
+    /**
+     * Fetch the report of the latest test-scenario runs as text: JUnit XML by
+     * default, an HTML page for `format: "html"`. On an Automation node,
+     * `bundleId` selects the bundle; otherwise the active bundle is reported.
+     */
+    getTestScenarioRunsReport(projectKey?: string, options?: TestScenarioRunsReportOptions): Promise<string>;
+    /**
+     * Download the latest test-scenario runs report to a local file and return
+     * the byte count written. The file is only published once complete.
+     */
+    downloadTestScenarioRunsReport(filePath: string, projectKey?: string, options?: TestScenarioRunsReportOptions): Promise<number>;
+    private testScenarioRoute;
     /** Get project-level tags (tag name → {color?}). */
     tags(projectKey?: string): Promise<ProjectTags>;
     /**

package/dist/src/resources/projects.js

@@ -102,6 +102,11 @@ const DEFAULT_MAX_NODES = 300;
 const DEFAULT_MAX_EDGES = 600;
 const DEFAULT_METADATA_TIMEOUT_MS = 1_500;
 const PROJECT_IMPORT_AMBIGUOUS_REMEDIATION = "Import processing left DSS state indeterminate. Inspect the archive with `dss project inspect-archive <file>` and the live projects with `dss project list` before retrying the import.";
+function testReportRoute(options) {
+    return options.format === "html"
+        ? "last-test-scenario-runs-html-report"
+        : "last-test-scenario-runs-report";
+}
 export class ProjectsResource extends BaseResource {
     /** Create a new project. */
     async createProject(projectKey, name, ownerLogin, settings) {
@@ -319,6 +324,37 @@ export class ProjectsResource extends BaseResource {
     async pushToGitRemote(remote, projectKey) {
         await this.client.post(`/public/api/projects/${this.enc(projectKey)}/actions/push-to-git-remote?remote=${encodeURIComponent(remote)}`);
     }
+    /**
+     * Get the testing status of a project: the worst outcome across the last
+     * runs of its test scenarios. On an Automation node, `bundleId` restricts
+     * the runs to those made while that bundle was active.
+     */
+    async getTestingStatus(projectKey, bundleId) {
+        return this.client.get(this.testScenarioRoute(projectKey, "testing-status", bundleId));
+    }
+    /**
+     * Fetch the report of the latest test-scenario runs as text: JUnit XML by
+     * default, an HTML page for `format: "html"`. On an Automation node,
+     * `bundleId` selects the bundle; otherwise the active bundle is reported.
+     */
+    async getTestScenarioRunsReport(projectKey, options = {}) {
+        return this.client.getText(this.testScenarioRoute(projectKey, testReportRoute(options), options.bundleId));
+    }
+    /**
+     * Download the latest test-scenario runs report to a local file and return
+     * the byte count written. The file is only published once complete.
+     */
+    async downloadTestScenarioRunsReport(filePath, projectKey, options = {}) {
+        const res = await this.client.stream(this.testScenarioRoute(projectKey, testReportRoute(options), options.bundleId));
+        if (!res.body) {
+            throw unexpectedResponseError("projects.downloadTestScenarioRunsReport response did not include a body");
+        }
+        return writeResponseToFile(filePath, res);
+    }
+    testScenarioRoute(projectKey, route, bundleId) {
+        const query = bundleId === undefined ? "" : `?bundleId=${encodeURIComponent(bundleId)}`;
+        return `/public/api/projects/${this.enc(projectKey)}/scenarios/${route}${query}`;
+    }
     /** Get project-level tags (tag name → {color?}). */
     async tags(projectKey) {
         const enc = this.enc(projectKey);

package/dist/src/resources/recipe-create.d.ts

@@ -30,7 +30,10 @@ export declare function groupingPayloadConfig(opts: RecipeCreateOptions): Groupi
 /**
  * Apply grouping keys and aggregates to the payload DSS created: `keys` lists
  * the group columns; each aggregated column's `values[]` entry gets its
- * aggregate flags (and `orderColumn` for first/last).
+ * aggregate flags (and `orderColumn` for first/last). With aggregates given,
+ * DSS's per-group row count (`globalCount`, a `count` column) is turned off so
+ * the output holds exactly the keys and the requested aggregates; `COL:count`
+ * asks for a count. Keys alone keep the count as the only aggregate.
  */
 export declare function applyGroupingPayload(payload: Record<string, unknown>, config: GroupingPayloadConfig): Record<string, unknown>;
 /** Prepare option groups, in the default step order. */

package/dist/src/resources/recipe-create.js

@@ -164,7 +164,10 @@ export function groupingPayloadConfig(opts) {
 /**
  * Apply grouping keys and aggregates to the payload DSS created: `keys` lists
  * the group columns; each aggregated column's `values[]` entry gets its
- * aggregate flags (and `orderColumn` for first/last).
+ * aggregate flags (and `orderColumn` for first/last). With aggregates given,
+ * DSS's per-group row count (`globalCount`, a `count` column) is turned off so
+ * the output holds exactly the keys and the requested aggregates; `COL:count`
+ * asks for a count. Keys alone keep the count as the only aggregate.
  */
 export function applyGroupingPayload(payload, config) {
     const values = Array.isArray(payload.values)
@@ -182,7 +185,13 @@ export function applyGroupingPayload(payload, config) {
             entry.orderColumn = config.orderBy;
         }
     }
-    return { ...payload, keys: config.keys.map((column) => ({ column, })), values, };
+    const hasAggregates = Object.keys(config.aggregates).length > 0;
+    return {
+        ...payload,
+        keys: config.keys.map((column) => ({ column, })),
+        values,
+        ...(hasAggregates ? { globalCount: false, } : {}),
+    };
 }
 function processorStep(type, params) {
     return {

package/dist/src/resources/scenario-authoring.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Pure builders for the JSON DSS stores under `triggers` and `reporters` of a
+ * scenario. Trigger shapes mirror dataikuapi's `add_periodic_trigger`,
+ * `add_hourly_trigger`, `add_daily_trigger` (which becomes a Weekly trigger when
+ * given days) and `add_monthly_trigger`; the mail reporter shape is the one DSS
+ * 15 stores for a `mail-scenario` reporter.
+ */
+export declare const SCENARIO_TRIGGER_FREQUENCIES: readonly ["minutely", "hourly", "daily", "weekly", "monthly"];
+export type ScenarioTriggerFrequency = typeof SCENARIO_TRIGGER_FREQUENCIES[number];
+export declare const SCENARIO_WEEKDAYS: readonly ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
+export declare const SCENARIO_MONTHLY_RUN_ON: readonly ["ON_THE_DAY", "LAST_DAY_OF_THE_MONTH", "FIRST_WEEK", "SECOND_WEEK", "THIRD_WEEK", "FOURTH_WEEK", "LAST_WEEK"];
+export declare const SCENARIO_REPORTER_PHASES: readonly ["START", "END"];
+export interface TemporalTriggerSpec {
+    frequency: ScenarioTriggerFrequency;
+    /** Repeat interval: minutes (minutely), hours, days, weeks or months. */
+    every?: number;
+    /** Hour of the day (daily, weekly, monthly) or hour the schedule starts from (hourly). */
+    hour?: number;
+    minute?: number;
+    /** Weekday names; required by `weekly`, rejected elsewhere. */
+    days?: readonly string[];
+    /** Day of the month of the start date (monthly, default 1). */
+    dayOfMonth?: number;
+    runOn?: string;
+    /** `YYYY-MM-DD` day before which the trigger does not run; default today (monthly: January 1st of this year). */
+    startDate?: string;
+    timezone?: string;
+    name?: string;
+    active?: boolean;
+}
+/** The scenario trigger object dataikuapi would append for this schedule. */
+export declare function temporalTrigger(spec: TemporalTriggerSpec, now?: Date): Record<string, unknown>;
+export interface MailReporterSpec {
+    channel: string;
+    recipient: string;
+    subject: string;
+    message: string;
+    /** DSS expression gating the report, e.g. `outcome == 'FAILED'`. */
+    condition?: string;
+    phase?: string;
+    name?: string;
+    active?: boolean;
+}
+/** A `mail-scenario` reporter as DSS 15 stores it (inline message, Freemarker, no attachments). */
+export declare function mailReporter(spec: MailReporterSpec): Record<string, unknown>;
+/** Which element of a trigger/reporter list to remove. */
+export interface ScenarioListSelector {
+    index?: number;
+    name?: string;
+}
+/** Position of the selected element; ambiguous or missing selections throw. */
+export declare function selectScenarioListIndex(items: readonly unknown[], selector: ScenarioListSelector, kind: "trigger" | "reporter"): number;

package/dist/src/resources/scenario-authoring.js

@@ -0,0 +1,216 @@
+import { ClientValidationError, } from "../errors.js";
+import { isRecord, } from "../utils/records.js";
+/**
+ * Pure builders for the JSON DSS stores under `triggers` and `reporters` of a
+ * scenario. Trigger shapes mirror dataikuapi's `add_periodic_trigger`,
+ * `add_hourly_trigger`, `add_daily_trigger` (which becomes a Weekly trigger when
+ * given days) and `add_monthly_trigger`; the mail reporter shape is the one DSS
+ * 15 stores for a `mail-scenario` reporter.
+ */
+export const SCENARIO_TRIGGER_FREQUENCIES = [
+    "minutely",
+    "hourly",
+    "daily",
+    "weekly",
+    "monthly",
+];
+export const SCENARIO_WEEKDAYS = [
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday",
+    "Sunday",
+];
+export const SCENARIO_MONTHLY_RUN_ON = [
+    "ON_THE_DAY",
+    "LAST_DAY_OF_THE_MONTH",
+    "FIRST_WEEK",
+    "SECOND_WEEK",
+    "THIRD_WEEK",
+    "FOURTH_WEEK",
+    "LAST_WEEK",
+];
+export const SCENARIO_REPORTER_PHASES = ["START", "END",];
+function invalid(message) {
+    return new ClientValidationError(message, "invalid_flag_value");
+}
+/** Membership test that narrows a free-form string to one of the allowed literals. */
+function isOneOf(allowed, value) {
+    return allowed.includes(value);
+}
+function boundedInteger(value, name, min, max) {
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw invalid(`${name} must be an integer from ${min} to ${max}, got ${value}.`);
+    }
+    return value;
+}
+const pad = (value, width = 2) => String(value).padStart(width, "0");
+/**
+ * dataikuapi's `startingFrom`: local midnight of the date, with milliseconds and
+ * a `+HHMM` offset (taken from the machine's time zone, as dataikuapi does).
+ */
+function startingFrom(year, month, day) {
+    const local = new Date(year, month - 1, day, 0, 0, 0, 0);
+    if (local.getFullYear() !== year || local.getMonth() !== month - 1 || local.getDate() !== day) {
+        throw invalid(`${year}-${pad(month)}-${pad(day)} is not a calendar date.`);
+    }
+    const offsetMinutes = -local.getTimezoneOffset();
+    const sign = offsetMinutes < 0 ? "-" : "+";
+    const absolute = Math.abs(offsetMinutes);
+    return `${year}-${pad(month)}-${pad(day)}T00:00:00.000${sign}${pad(Math.floor(absolute / 60))}${pad(absolute % 60)}`;
+}
+function startingFromDate(startDate, fallback) {
+    if (startDate === undefined)
+        return fallback();
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(startDate);
+    if (!match)
+        throw invalid(`--start-date must be YYYY-MM-DD, got ${JSON.stringify(startDate)}.`);
+    return startingFrom(Number(match[1]), Number(match[2]), Number(match[3]));
+}
+/** The scenario trigger object dataikuapi would append for this schedule. */
+export function temporalTrigger(spec, now = new Date()) {
+    const every = spec.every === undefined
+        ? undefined
+        : boundedInteger(spec.every, "--every", 1, 100_000);
+    const timezone = spec.timezone ?? "SERVER";
+    if (spec.frequency !== "weekly" && spec.days !== undefined) {
+        throw invalid(`--days applies to weekly triggers only (got --frequency ${spec.frequency}).`);
+    }
+    if (spec.frequency !== "monthly" && (spec.runOn !== undefined || spec.dayOfMonth !== undefined)) {
+        throw invalid(`--run-on and --day-of-month apply to monthly triggers only (got --frequency ${spec.frequency}).`);
+    }
+    if (spec.frequency === "minutely") {
+        for (const [flag, value,] of [["--hour", spec.hour,], ["--minute", spec.minute,], [
+                "--start-date",
+                spec.startDate,
+            ], ["--timezone", spec.timezone,],]) {
+            if (value !== undefined)
+                throw invalid(`${flag} does not apply to minutely triggers.`);
+        }
+    }
+    const today = () => startingFrom(now.getFullYear(), now.getMonth() + 1, now.getDate());
+    const trigger = (params) => ({
+        ...(spec.name === undefined ? {} : { name: spec.name, }),
+        active: spec.active ?? true,
+        type: "temporal",
+        params,
+    });
+    if (spec.frequency === "minutely") {
+        return trigger({ frequency: "Minutely", repeatFrequency: every ?? 5, });
+    }
+    const minute = boundedInteger(spec.minute ?? 0, "--minute", 0, 59);
+    if (spec.frequency === "hourly") {
+        return trigger({
+            frequency: "Hourly",
+            hour: boundedInteger(spec.hour ?? 0, "--hour", 0, 23),
+            minute,
+            startingFrom: startingFromDate(spec.startDate, today),
+            repeatFrequency: every ?? 1,
+            timezone,
+        });
+    }
+    const hour = boundedInteger(spec.hour ?? 2, "--hour", 0, 23);
+    if (spec.frequency === "daily") {
+        return trigger({
+            frequency: "Daily",
+            hour,
+            minute,
+            startingFrom: startingFromDate(spec.startDate, today),
+            repeatFrequency: every ?? 1,
+            timezone,
+        });
+    }
+    if (spec.frequency === "weekly") {
+        if (spec.days === undefined || spec.days.length === 0) {
+            throw invalid(`--days is required for weekly triggers (${SCENARIO_WEEKDAYS.join(", ")}, comma-separated).`);
+        }
+        const unknown = spec.days.filter((day) => !isOneOf(SCENARIO_WEEKDAYS, day));
+        if (unknown.length > 0) {
+            throw invalid(`Unknown weekday ${unknown.map((day) => JSON.stringify(day)).join(", ")}; use ${SCENARIO_WEEKDAYS.join(", ")}.`);
+        }
+        return trigger({
+            frequency: "Weekly",
+            hour,
+            minute,
+            startingFrom: startingFromDate(spec.startDate, today),
+            daysOfWeek: [...spec.days,],
+            repeatFrequency: every ?? 1,
+            timezone,
+        });
+    }
+    const runOn = spec.runOn ?? "ON_THE_DAY";
+    if (!isOneOf(SCENARIO_MONTHLY_RUN_ON, runOn)) {
+        throw invalid(`--run-on must be one of ${SCENARIO_MONTHLY_RUN_ON.join(", ")}, got ${runOn}.`);
+    }
+    if (spec.startDate !== undefined && spec.dayOfMonth !== undefined) {
+        throw invalid("--start-date and --day-of-month are mutually exclusive for monthly triggers.");
+    }
+    const dayOfMonth = boundedInteger(spec.dayOfMonth ?? 1, "--day-of-month", 1, 31);
+    return trigger({
+        frequency: "Monthly",
+        startingFrom: startingFromDate(spec.startDate, 
+        // dataikuapi starts monthly schedules on January 1st (not today) so that day 31 never lands on a short month.
+        () => startingFrom(now.getFullYear(), 1, dayOfMonth)),
+        hour,
+        minute,
+        monthlyRunOn: runOn,
+        repeatFrequency: every ?? 1,
+        timezone,
+    });
+}
+function requiredText(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw invalid(`${name} must be a non-empty string.`);
+    }
+    return value;
+}
+/** A `mail-scenario` reporter as DSS 15 stores it (inline message, Freemarker, no attachments). */
+export function mailReporter(spec) {
+    const phase = spec.phase ?? "END";
+    if (!isOneOf(SCENARIO_REPORTER_PHASES, phase)) {
+        throw invalid(`--phase must be ${SCENARIO_REPORTER_PHASES.join(" or ")}, got ${phase}.`);
+    }
+    if (spec.condition !== undefined)
+        requiredText(spec.condition, "--condition");
+    return {
+        ...(spec.name === undefined ? {} : { name: spec.name, }),
+        active: spec.active ?? true,
+        phase,
+        runConditionEnabled: spec.condition !== undefined,
+        runCondition: spec.condition ?? "true",
+        messaging: {
+            type: "mail-scenario",
+            configuration: {
+                channelId: requiredText(spec.channel, "--channel"),
+                recipient: requiredText(spec.recipient, "--recipient"),
+                subject: spec.subject,
+                message: spec.message,
+                messageSource: "INLINE",
+                templateFormat: "FREEMARKER",
+                sendAsHTML: false,
+                attachments: [],
+            },
+        },
+    };
+}
+/** Position of the selected element; ambiguous or missing selections throw. */
+export function selectScenarioListIndex(items, selector, kind) {
+    if ((selector.index === undefined) === (selector.name === undefined)) {
+        throw invalid(`Pass exactly one of --index or --name to select the ${kind}.`);
+    }
+    if (selector.index !== undefined) {
+        if (!Number.isInteger(selector.index) || selector.index < 0 || selector.index >= items.length) {
+            throw invalid(`--index ${selector.index} is outside the ${items.length} ${kind}(s) of this scenario (0-based).`);
+        }
+        return selector.index;
+    }
+    const matches = items.flatMap((item, index) => isRecord(item) && item["name"] === selector.name ? [index,] : []);
+    if (matches.length !== 1) {
+        throw invalid(matches.length === 0
+            ? `No ${kind} is named ${JSON.stringify(selector.name)}.`
+            : `${matches.length} ${kind}s are named ${JSON.stringify(selector.name)} (indexes ${matches.join(", ")}); use --index.`);
+    }
+    return matches[0];
+}