dataiku-sdk 0.10.0 → 0.11.0

package/dist/src/cli/helpers/flow-zone.js

@@ -0,0 +1,420 @@
+import { readFileSync, } from "node:fs";
+import { finiteNumberField, jsonInput, optionalStringField, parseJsonObject, plainRecord, requiredStringArray, splitCsvFlag, } from "../coerce.js";
+import { UsageError, } from "../usage.js";
+export function flowZoneId(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new UsageError("Flow zone id must not be empty.");
+    return trimmed;
+}
+export function flowZoneName(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new UsageError("--name is required. Usage: dss flow-zone create --name NAME [--color #RRGGBB]");
+    }
+    return value.trim();
+}
+export function flowZoneColor(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !/^#[0-9a-fA-F]{6}$/.test(value.trim())) {
+        throw new UsageError("--color must be a hex color like #2ab1ac.");
+    }
+    return value.trim();
+}
+export function flowZoneObjectType(value) {
+    const normalized = value.trim().toUpperCase().replace(/-/g, "_");
+    if (normalized === "FOLDER")
+        return "MANAGED_FOLDER";
+    if (normalized === "MODEL_EVAL_STORE")
+        return "MODEL_EVALUATION_STORE";
+    if (normalized === "KNOWLEDGE_BANK")
+        return "RETRIEVABLE_KNOWLEDGE";
+    if (normalized === "DATASET"
+        || normalized === "MANAGED_FOLDER"
+        || normalized === "SAVED_MODEL"
+        || normalized === "RECIPE"
+        || normalized === "MODEL_EVALUATION_STORE"
+        || normalized === "STREAMING_ENDPOINT"
+        || normalized === "LABELING_TASK"
+        || normalized === "RETRIEVABLE_KNOWLEDGE") {
+        return normalized;
+    }
+    throw new UsageError(`Invalid flow zone object type: ${value}. Use DATASET, RECIPE, MANAGED_FOLDER, SAVED_MODEL, MODEL_EVALUATION_STORE, STREAMING_ENDPOINT, LABELING_TASK, or RETRIEVABLE_KNOWLEDGE.`, "invalid_enum");
+}
+export function addFlowZoneFlagItems(items, flags, flagName, objectType) {
+    for (const objectId of splitCsvFlag(flags[flagName])) {
+        items.push({ objectId, objectType, });
+    }
+}
+export function parseFlowZoneObject(value) {
+    const parts = value.split(":").map((part) => part.trim()).filter((part) => part.length > 0);
+    if (parts.length === 2) {
+        return { objectType: flowZoneObjectType(parts[0]), objectId: parts[1], };
+    }
+    if (parts.length === 3) {
+        return { projectKey: parts[0], objectType: flowZoneObjectType(parts[1]), objectId: parts[2], };
+    }
+    throw new UsageError(`Invalid --object value: ${value}. Use TYPE:ID or PROJECT_KEY:TYPE:ID.`);
+}
+export function flowZoneMoveItems(flags) {
+    const items = [];
+    addFlowZoneFlagItems(items, flags, "dataset", "DATASET");
+    addFlowZoneFlagItems(items, flags, "recipe", "RECIPE");
+    addFlowZoneFlagItems(items, flags, "folder", "MANAGED_FOLDER");
+    addFlowZoneFlagItems(items, flags, "saved-model", "SAVED_MODEL");
+    addFlowZoneFlagItems(items, flags, "model-evaluation-store", "MODEL_EVALUATION_STORE");
+    addFlowZoneFlagItems(items, flags, "streaming-endpoint", "STREAMING_ENDPOINT");
+    addFlowZoneFlagItems(items, flags, "labeling-task", "LABELING_TASK");
+    addFlowZoneFlagItems(items, flags, "knowledge-bank", "RETRIEVABLE_KNOWLEDGE");
+    for (const value of splitCsvFlag(flags["object"])) {
+        items.push(parseFlowZoneObject(value));
+    }
+    return items;
+}
+export function flowZoneItems(zone) {
+    return [...(zone.items ?? []), ...(zone.shared ?? []),];
+}
+export function flowZoneContains(zone, object) {
+    return flowZoneItems(zone).some((item) => item.objectId === object.objectId
+        && item.objectType === object.objectType
+        && (object.projectKey === undefined || item.projectKey === object.projectKey));
+}
+export function flowZoneSummary(zone, object) {
+    const items = flowZoneItems(zone);
+    return {
+        id: zone.id,
+        name: zone.name,
+        itemCount: items.length,
+        ...(object ? { containsMatchingObject: flowZoneContains(zone, object), } : {}),
+    };
+}
+export function flowZoneDetailSummary(zone) {
+    return {
+        ...flowZoneSummary(zone),
+        items: flowZoneItems(zone),
+    };
+}
+export function flowZonePlanColor(value, source) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !/^#[0-9a-fA-F]{6}$/.test(value.trim())) {
+        throw new UsageError(`${source} must be a hex color like #2ab1ac.`, "validation_failed");
+    }
+    return value.trim();
+}
+export function flowZonePlanPosition(value, source) {
+    if (value === undefined)
+        return undefined;
+    const record = plainRecord(value);
+    if (!record) {
+        throw new UsageError(`${source} must be an object with x and y.`, "validation_failed");
+    }
+    return {
+        x: finiteNumberField(record, "x", source),
+        y: finiteNumberField(record, "y", source),
+    };
+}
+export function flowZoneCurrentPosition(zone) {
+    const record = zone;
+    const position = plainRecord(record.position);
+    if (!position)
+        return undefined;
+    const x = position.x;
+    const y = position.y;
+    return typeof x === "number" && Number.isFinite(x) && typeof y === "number" && Number.isFinite(y)
+        ? { x, y, }
+        : undefined;
+}
+export function flowZoneSamePosition(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return a.x === b.x && a.y === b.y;
+}
+export function parseFlowZonePlanItem(value, source) {
+    if (typeof value === "string")
+        return parseFlowZoneObject(value);
+    const record = plainRecord(value);
+    if (!record) {
+        throw new UsageError(`${source} must be TYPE:ID or an object.`, "validation_failed");
+    }
+    const object = optionalStringField(record, ["object",]);
+    if (object)
+        return parseFlowZoneObject(object);
+    const objectType = optionalStringField(record, ["objectType", "type",]);
+    const objectId = optionalStringField(record, ["objectId", "id", "name",]);
+    if (!objectType || !objectId) {
+        throw new UsageError(`${source} must include objectType/type and objectId/id, or object as TYPE:ID.`, "validation_failed");
+    }
+    const projectKey = optionalStringField(record, ["projectKey", "project",]);
+    return {
+        objectType: flowZoneObjectType(objectType),
+        objectId,
+        ...(projectKey ? { projectKey, } : {}),
+    };
+}
+export function addFlowZonePlanTypedItems(items, record, key, objectType, source) {
+    if (record[key] === undefined)
+        return;
+    for (const objectId of requiredStringArray(record[key], `${source}.${key}`)) {
+        items.push({ objectType, objectId, });
+    }
+}
+export function flowZoneItemKey(item) {
+    return `${item.projectKey ?? ""}\0${item.objectType}\0${item.objectId}`;
+}
+export function flowZonePlanLabel(plan) {
+    return plan.id ?? plan.name ?? "<unknown>";
+}
+export function dedupeFlowZonePlanItems(items) {
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        const key = flowZoneItemKey(item);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(item);
+    }
+    return result;
+}
+export function flowZonePlanItemKeys(plan) {
+    const keys = new Set();
+    for (const zone of plan.zones) {
+        for (const item of zone.items)
+            keys.add(flowZoneItemKey(item));
+    }
+    return keys;
+}
+export function validateUniqueFlowZoneAssignments(plan) {
+    const seen = new Map();
+    for (const zone of plan.zones) {
+        const label = flowZonePlanLabel(zone);
+        for (const item of zone.items) {
+            const key = flowZoneItemKey(item);
+            const previous = seen.get(key);
+            if (previous) {
+                throw new UsageError(`Flow object ${item.objectType}:${item.objectId} is assigned to both "${previous}" and "${label}".`, "validation_failed");
+            }
+            seen.set(key, label);
+        }
+    }
+}
+export function parseFlowZoneOrganizePlan(input) {
+    const zones = input.zones;
+    if (!Array.isArray(zones) || zones.length === 0) {
+        throw new UsageError("Flow zone organize plan must include a non-empty zones array.", "validation_failed");
+    }
+    const plan = {
+        zones: zones.map((value, index) => {
+            const source = `zones[${index}]`;
+            const record = plainRecord(value);
+            if (!record)
+                throw new UsageError(`${source} must be an object.`, "validation_failed");
+            const id = optionalStringField(record, ["id", "zoneId",]);
+            const name = optionalStringField(record, ["name",]);
+            if (!id && !name) {
+                throw new UsageError(`${source} must include name or id.`, "validation_failed");
+            }
+            const items = [];
+            const rawItems = record.items ?? record.objects;
+            if (rawItems !== undefined) {
+                if (!Array.isArray(rawItems)) {
+                    throw new UsageError(`${source}.items must be an array.`, "validation_failed");
+                }
+                rawItems.forEach((item, itemIndex) => {
+                    items.push(parseFlowZonePlanItem(item, `${source}.items[${itemIndex}]`));
+                });
+            }
+            addFlowZonePlanTypedItems(items, record, "datasets", "DATASET", source);
+            addFlowZonePlanTypedItems(items, record, "recipes", "RECIPE", source);
+            addFlowZonePlanTypedItems(items, record, "folders", "MANAGED_FOLDER", source);
+            addFlowZonePlanTypedItems(items, record, "savedModels", "SAVED_MODEL", source);
+            addFlowZonePlanTypedItems(items, record, "modelEvaluationStores", "MODEL_EVALUATION_STORE", source);
+            addFlowZonePlanTypedItems(items, record, "streamingEndpoints", "STREAMING_ENDPOINT", source);
+            addFlowZonePlanTypedItems(items, record, "labelingTasks", "LABELING_TASK", source);
+            addFlowZonePlanTypedItems(items, record, "knowledgeBanks", "RETRIEVABLE_KNOWLEDGE", source);
+            return {
+                ...(id ? { id, } : {}),
+                ...(name ? { name, } : {}),
+                ...(record.color !== undefined
+                    ? { color: flowZonePlanColor(record.color, `${source}.color`), }
+                    : {}),
+                ...(record.position !== undefined
+                    ? { position: flowZonePlanPosition(record.position, `${source}.position`), }
+                    : {}),
+                items: dedupeFlowZonePlanItems(items),
+            };
+        }),
+    };
+    validateUniqueFlowZoneAssignments(plan);
+    return plan;
+}
+export function readFlowZoneOrganizePlan(flags, usage) {
+    const data = typeof flags["file"] === "string"
+        ? parseJsonObject(readFileSync(flags["file"], "utf-8"), flags["file"])
+        : jsonInput(flags);
+    if (!data) {
+        throw new UsageError(`--data, --data-file, --file, or --stdin is required. Usage: ${usage}`, "missing_required_flag");
+    }
+    return parseFlowZoneOrganizePlan(data);
+}
+export function findFlowZoneForPlan(zones, plan) {
+    if (plan.id) {
+        const byId = zones.find((zone) => zone.id === plan.id);
+        if (byId)
+            return byId;
+    }
+    if (!plan.name)
+        return undefined;
+    const byName = zones.filter((zone) => zone.name === plan.name);
+    if (byName.length > 1) {
+        throw new UsageError(`Multiple flow zones named "${plan.name}" exist; use id.`, "validation_failed");
+    }
+    return byName[0];
+}
+export function ensureFlowZonePlanTarget(plan, existing) {
+    if (existing || plan.name)
+        return;
+    throw new UsageError(`Flow zone ${plan.id ?? "<unknown>"} was not found and cannot be created without name.`, "validation_failed");
+}
+export function flowZoneExplicitItems(zone) {
+    return (zone.items ?? []).map((item) => ({
+        objectId: item.objectId,
+        objectType: item.objectType,
+        ...(item.projectKey ? { projectKey: item.projectKey, } : {}),
+    }));
+}
+export function flowZonePruneItems(existing, plannedItemKeys) {
+    if (!existing)
+        return [];
+    return flowZoneExplicitItems(existing).filter((item) => !plannedItemKeys.has(flowZoneItemKey(item)));
+}
+export function flowZoneOrganizeStep(plan, existing, sync, plannedItemKeys) {
+    ensureFlowZonePlanTarget(plan, existing);
+    const update = {};
+    if (existing && plan.name && plan.name !== existing.name)
+        update.name = plan.name;
+    if (existing && plan.color && plan.color !== existing.color)
+        update.color = plan.color;
+    if (existing && plan.position !== undefined
+        && !flowZoneSamePosition(flowZoneCurrentPosition(existing), plan.position)) {
+        update.position = plan.position;
+    }
+    const pruneItems = sync ? flowZonePruneItems(existing, plannedItemKeys) : [];
+    return {
+        target: {
+            ...(plan.id ? { id: plan.id, } : {}),
+            ...(plan.name ? { name: plan.name, } : {}),
+            ...(plan.color ? { color: plan.color, } : {}),
+            ...(plan.position ? { position: plan.position, } : {}),
+        },
+        ...(existing ? { existing: flowZoneSummary(existing), } : { create: true, }),
+        ...(Object.keys(update).length > 0 ? { update, } : {}),
+        moveItems: plan.items,
+        ...(pruneItems.length > 0 ? { pruneItems, } : {}),
+    };
+}
+export function flowZoneValidationBucket(index, objectType) {
+    switch (objectType) {
+        case "DATASET":
+            return index.datasets;
+        case "RECIPE":
+            return index.recipes;
+        case "MANAGED_FOLDER":
+            return index.folders;
+        case "SAVED_MODEL":
+        case "MODEL_EVALUATION_STORE":
+        case "STREAMING_ENDPOINT":
+        case "LABELING_TASK":
+        case "RETRIEVABLE_KNOWLEDGE":
+            return index.all;
+    }
+}
+export async function flowZoneValidationIndex(client, projectKey) {
+    const result = await client.projects.map({
+        projectKey,
+        maxNodes: 100_000,
+        maxEdges: 100_000,
+    });
+    const index = {
+        projectKey: result.map.projectKey,
+        all: new Set(),
+        datasets: new Set(),
+        recipes: new Set(),
+        folders: new Set(),
+    };
+    for (const node of result.map.nodes) {
+        index.all.add(node.id);
+        switch (node.kind) {
+            case "dataset":
+                index.datasets.add(node.id);
+                break;
+            case "recipe":
+                index.recipes.add(node.id);
+                break;
+            case "folder":
+                index.folders.add(node.id);
+                break;
+            case "other":
+                break;
+        }
+    }
+    return index;
+}
+export async function validateFlowZoneOrganizeObjects(client, plan, projectKey) {
+    const indexes = new Map();
+    const missing = [];
+    const getIndex = async (itemProjectKey) => {
+        const requestedProjectKey = itemProjectKey ?? projectKey;
+        const cacheKey = requestedProjectKey ?? "";
+        const cached = indexes.get(cacheKey);
+        if (cached)
+            return cached;
+        const index = await flowZoneValidationIndex(client, requestedProjectKey);
+        indexes.set(cacheKey, index);
+        return index;
+    };
+    for (const zone of plan.zones) {
+        for (const item of zone.items) {
+            const index = await getIndex(item.projectKey);
+            const bucket = flowZoneValidationBucket(index, item.objectType);
+            if (bucket.has(item.objectId))
+                continue;
+            missing.push({
+                zone: flowZonePlanLabel(zone),
+                objectId: item.objectId,
+                objectType: item.objectType,
+                ...(item.projectKey ? { projectKey: item.projectKey, } : {}),
+                reason: `Object not found in project ${item.projectKey ?? index.projectKey}.`,
+            });
+        }
+    }
+    return { valid: missing.length === 0, missing, };
+}
+export function throwFlowZoneValidationError(validation) {
+    if (validation.valid)
+        return;
+    const first = validation.missing[0];
+    const suffix = validation.missing.length > 1 ? ` and ${validation.missing.length - 1} more` : "";
+    throw new UsageError(`Flow zone organize validation failed: ${first?.objectType}:${first?.objectId} in zone "${first?.zone}" was not found${suffix}.`, "validation_failed");
+}
+export async function resolveFlowZoneIdFromFlags(client, flags, projectKey) {
+    const zoneId = typeof flags["zone-id"] === "string" ? flags["zone-id"].trim() : "";
+    if (zoneId)
+        return zoneId;
+    const zone = typeof flags["zone"] === "string" ? flags["zone"].trim() : "";
+    if (!zone)
+        return undefined;
+    const zones = await client.flowZones.list(projectKey);
+    const match = zones.find((candidate) => candidate.id === zone || candidate.name === zone);
+    if (!match)
+        throw new UsageError(`Flow zone not found: ${zone}`, "invalid_enum");
+    return match.id;
+}
+export async function moveCreatedItemsToZone(client, flags, items, projectKey) {
+    const zoneId = await resolveFlowZoneIdFromFlags(client, flags, projectKey);
+    if (!zoneId || items.length === 0)
+        return {};
+    await client.flowZones.moveItems(zoneId, items, projectKey);
+    return { zoneId, moved: items, };
+}

package/dist/src/cli/helpers/recipe.d.ts

@@ -0,0 +1,11 @@
+export declare function recipeBackupPath(recipeName: string, backupDir: string): string;
+export declare function recipeCodeEnv(recipe: Record<string, unknown>): unknown;
+export declare function recipeGraph(recipe: Record<string, unknown>): Record<string, unknown>;
+export declare function recipeBackupDocument(recipeName: string, projectKey: string | undefined, current: {
+    recipe: Record<string, unknown>;
+    payload?: string;
+}): Record<string, unknown>;
+export declare function readRecipeBackup(backupPath: string): Record<string, unknown>;
+export declare function recipeRunShouldWait(flags: Record<string, string | boolean>): boolean;
+export declare function recipeRoleInputItems(recipe: Record<string, unknown>, role: string): unknown[];
+export declare function recipeInputItemRef(item: unknown): string | undefined;

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

@@ -0,0 +1,83 @@
+import { readFileSync, } from "node:fs";
+import { join, } from "node:path";
+import { sanitizeFileName, } from "../../utils/sanitize.js";
+import { normalizeLineEndings, sha256Hex, stableHash, } from "../coerce.js";
+import { UsageError, } from "../usage.js";
+export function recipeBackupPath(recipeName, backupDir) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return join(backupDir, `${sanitizeFileName(recipeName, "recipe")}-${stamp}.recipe-backup.json`);
+}
+export function recipeCodeEnv(recipe) {
+    const params = recipe.params;
+    if (!params || typeof params !== "object" || Array.isArray(params))
+        return undefined;
+    return params.envSelection;
+}
+export function recipeGraph(recipe) {
+    return {
+        inputs: recipe.inputs,
+        outputs: recipe.outputs,
+    };
+}
+export function recipeBackupDocument(recipeName, projectKey, current) {
+    return {
+        resource: "recipe",
+        recipeName,
+        projectKey,
+        createdAt: new Date().toISOString(),
+        versionTag: current.recipe.versionTag,
+        payloadHash: sha256Hex(current.payload ?? ""),
+        graphHash: stableHash(recipeGraph(current.recipe)),
+        normalizedPayloadHash: sha256Hex(normalizeLineEndings(current.payload ?? "")),
+        codeEnvHash: stableHash(recipeCodeEnv(current.recipe)),
+        codeEnv: recipeCodeEnv(current.recipe),
+        recipe: current.recipe,
+        payload: current.payload ?? "",
+    };
+}
+export function readRecipeBackup(backupPath) {
+    const raw = readFileSync(backupPath, "utf-8");
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && parsed.resource === "recipe")
+            return parsed;
+    }
+    catch {
+        // Backward-compatible payload-only backups are handled below.
+    }
+    return {
+        resource: "recipe",
+        recipeName: "unknown",
+        payloadHash: sha256Hex(raw),
+        payload: raw,
+    };
+}
+export function recipeRunShouldWait(flags) {
+    if (flags["wait"] === true && flags["no-wait"] === true) {
+        throw new UsageError("--wait and --no-wait are mutually exclusive.", "invalid_enum");
+    }
+    const waitImplied = flags["include-logs"] === true
+        || flags["summary"] === true
+        || flags["timeout"] !== undefined
+        || flags["poll-interval"] !== undefined;
+    if (flags["no-wait"] === true && waitImplied) {
+        throw new UsageError("--include-logs, --summary, --timeout, and --poll-interval require waiting; remove --no-wait.", "invalid_enum");
+    }
+    return flags["no-wait"] !== true && (flags["wait"] === true || waitImplied);
+}
+export function recipeRoleInputItems(recipe, role) {
+    const inputs = recipe["inputs"];
+    if (!inputs || typeof inputs !== "object")
+        return [];
+    const roleEntry = inputs[role];
+    if (!roleEntry || typeof roleEntry !== "object")
+        return [];
+    const items = roleEntry["items"];
+    return Array.isArray(items) ? items : [];
+}
+export function recipeInputItemRef(item) {
+    if (!item || typeof item !== "object")
+        return undefined;
+    const ref = item["ref"];
+    return typeof ref === "string" && ref.length > 0 ? ref : undefined;
+}

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

@@ -0,0 +1,38 @@
+import type { DataikuClient } from "../client.js";
+export declare function setOutputFieldProjection(fields: string[] | undefined): void;
+export declare function enqueueCliWarning(warning: Record<string, unknown>): void;
+export declare function pickResultFields(item: unknown, fields: string[]): unknown;
+/**
+ * Project the top-level fields callers asked for via --fields. Arrays are mapped
+ * element-wise; scalars and string results pass through untouched. Requested keys
+ * that are absent become null so every row keeps a stable, predictable shape.
+ */
+export declare function projectResultFields(result: unknown, fields: string[]): unknown;
+export declare function writeCommandResult(result: unknown): void;
+export declare function transientBodyWithTargetContext(body: string, target: string, elapsedMs: number): string;
+export declare function addTransientTargetContext(error: unknown, target: string, elapsedMs: number): never;
+export declare function isFailedWaitResult(result: unknown): boolean;
+export declare function commandFailureExitCode(result: unknown): number | undefined;
+export declare class CommandResultFailure extends Error {
+    readonly result: unknown;
+    readonly exitCode: number;
+    constructor(result: unknown, exitCode: number);
+}
+export declare function commandFailureMessage(result: unknown): string;
+export declare function isNotFoundError(error: unknown): boolean;
+export declare function readIfExists<T>(reader: () => Promise<T>): Promise<T | undefined>;
+export declare function skipResult(resource: string, id: string, reason: "exists" | "missing", extra?: Record<string, unknown>): Record<string, unknown>;
+export declare function planResult(resource: string, action: string, options: {
+    asyncKind: string;
+    endpoint?: string;
+    exitCodesOnFailure: Record<string, number>;
+    identifiers?: Record<string, unknown>;
+    idempotency: string;
+    method?: string;
+    payload?: unknown;
+    localWrites?: unknown;
+    plannedAndDryRun?: boolean;
+    wait?: unknown;
+}): Record<string, unknown>;
+export declare function encodedProjectEndpoint(client: DataikuClient, projectKey: string | undefined, suffix: string): string;
+export declare function encodedProjectEndpointForPlan(projectKey: string, suffix: string): string;