dataiku-sdk 3.6.1 → 3.8.0

package/dist/src/resources/recipes.js

@@ -1,23 +1,15 @@
 import { writeFile, } from "node:fs/promises";
 import { resolve, } from "node:path";
 import { ClientValidationError, DataikuError, nonJsonResponseBody, unexpectedResponseError, } from "../errors.js";
-import { ProjectMetadataSchema, RecipeSummaryArraySchema, } from "../schemas.js";
+import { ProjectMetadataSchema, RecipeSchemaUpdatesSchema, RecipeSummaryArraySchema, } from "../schemas.js";
 import { deepMerge, } from "../utils/deep-merge.js";
 import { asRecord, } from "../utils/records.js";
 import { sanitizeFileName, } from "../utils/sanitize.js";
 import { BaseResource, } from "./base.js";
+import { applyGroupingPayload, asString, buildRecipeCreateRequest, recipeInputItems, recipeOutputSchemaIsComputable, schemaUpdateComputableId, schemaUpdateIsPending, } from "./recipe-create.js";
 // ---------------------------------------------------------------------------
 // Helpers: type narrowing
 // ---------------------------------------------------------------------------
-function asString(value) {
-    return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-function asStringArray(value) {
-    if (!Array.isArray(value))
-        return undefined;
-    const out = value.filter((v) => typeof v === "string" && v.length > 0);
-    return out.length > 0 ? out : undefined;
-}
 function parseRecipePayload(payload) {
     if (!payload)
         return {};
@@ -30,48 +22,6 @@ function parseRecipePayload(payload) {
     }
     return asRecord(parsed) ?? {};
 }
-function parseJoinKeyPairs(values, optionName = "joinOn") {
-    const pairs = [];
-    for (const raw of values) {
-        const token = raw.trim();
-        if (!token)
-            continue;
-        const eq = token.indexOf("=");
-        if (eq === -1) {
-            pairs.push({ left: token, right: token, });
-            continue;
-        }
-        const left = token.slice(0, eq).trim();
-        const right = token.slice(eq + 1).trim();
-        if (!left || !right) {
-            throw new ClientValidationError(`${optionName} values must use COL or LEFT=RIGHT.`, "validation_failed");
-        }
-        pairs.push({ left, right, });
-    }
-    return pairs;
-}
-function normalizeFuzzyDistance(value) {
-    const normalized = typeof value === "string" && value.trim().length > 0
-        ? value.trim().toUpperCase()
-        : "DAMERAU_LEVENSHTEIN";
-    if (normalized === "DAMERAU_LEVENSHTEIN")
-        return "LEVENSHTEIN";
-    if (normalized === "HAMMING" || normalized === "JACCARD" || normalized === "COSINE"
-        || normalized === "EUCLIDEAN") {
-        return normalized;
-    }
-    throw new ClientValidationError("fuzzyDistance must be one of DAMERAU_LEVENSHTEIN, HAMMING, JACCARD, COSINE, or EUCLIDEAN.", "validation_failed");
-}
-function normalizeJoinType(value) {
-    const normalized = typeof value === "string" && value.trim().length > 0
-        ? value.trim().toUpperCase()
-        : "LEFT";
-    if (normalized === "LEFT" || normalized === "INNER" || normalized === "RIGHT"
-        || normalized === "FULL") {
-        return normalized;
-    }
-    throw new ClientValidationError("joinType must be one of LEFT, INNER, RIGHT, or FULL.", "validation_failed");
-}
 function recipeVirtualInputs(payload, inputCount) {
     const current = Array.isArray(payload.virtualInputs) ? payload.virtualInputs : [];
     const virtualInputs = [];
@@ -136,27 +86,6 @@ function recipeOutputItems(recipe) {
     }
     return result;
 }
-function recipeInputItems(recipe) {
-    const inputs = asRecord(recipe.inputs);
-    if (!inputs)
-        return [];
-    const result = [];
-    const seen = new Set();
-    for (const [role, roleValue,] of Object.entries(inputs)) {
-        const items = asRecord(roleValue)?.items;
-        if (!Array.isArray(items))
-            continue;
-        for (const itemValue of items) {
-            const item = asRecord(itemValue);
-            const ref = asString(item?.ref);
-            if (!ref || seen.has(ref))
-                continue;
-            seen.add(ref);
-            result.push({ ref, role, });
-        }
-    }
-    return result;
-}
 function rewriteRefs(value, rewrites) {
     if (Object.keys(rewrites).length === 0)
         return value;
@@ -295,95 +224,17 @@ function shouldRetryRecipeCreateWithOutputProvisioning(error) {
 // ---------------------------------------------------------------------------
 // Resource
 // ---------------------------------------------------------------------------
-/**
- * Pure request construction for POST /recipes/ (no DSS calls). Shared with
- * `recipe create --plan` so the plan equals the request the command sends.
- */
-export function buildRecipeCreateRequest(opts, pk) {
-    const { type, payload, outputConnection: rawConnection, joinType: rawJoinType, } = opts;
-    const outputFolder = asString(opts.outputFolder);
-    // Build inputs/outputs from simple form (inputDatasets + outputDataset) or
-    // advanced form (inputs + outputs); both may coexist — simple form wins when
-    // the advanced form is absent.
-    const inputDatasets = asStringArray(opts.inputDatasets);
-    const requestedOutputDataset = asString(opts.outputDataset);
-    let inputs = asRecord(opts.inputs);
-    let outputs = asRecord(opts.outputs);
-    if (!inputs) {
-        inputs = {
-            main: {
-                items: inputDatasets?.map((ref) => ({ ref, deps: [], })) ?? [],
-            },
-        };
-    }
-    // Auto-generate name if not provided
-    const outputNameForDefaultRecipe = requestedOutputDataset ?? outputFolder;
-    const name = opts.name ?? (type && outputNameForDefaultRecipe
-        ? `${type}_${outputNameForDefaultRecipe}`
-        : undefined);
-    const temporaryOutputDataset = outputFolder && !requestedOutputDataset && name
-        ? `${name}_folder_output_marker`
-        : undefined;
-    const outputDataset = requestedOutputDataset ?? temporaryOutputDataset;
-    if (!outputs && outputDataset) {
-        outputs = {
-            main: {
-                items: [{ ref: outputDataset, appendMode: false, },],
-            },
-        };
-    }
-    if (!type || !name || !outputs) {
-        throw new ClientValidationError("type and outputDataset/outputFolder or (name + outputs) are required for create.", "validation_failed");
-    }
-    const joinCols = typeof opts.joinOn === "string" ? [opts.joinOn,] : asStringArray(opts.joinOn);
-    const joinKeys = type === "join" && joinCols?.length
-        ? parseJoinKeyPairs(joinCols)
-        : undefined;
-    const fuzzyOn = opts.fuzzyOn ?? (type === "fuzzyjoin" ? opts.joinOn : undefined);
-    const fuzzyCols = typeof fuzzyOn === "string" ? [fuzzyOn,] : asStringArray(fuzzyOn);
-    const fuzzyKeys = type === "fuzzyjoin" && fuzzyCols?.length
-        ? parseJoinKeyPairs(fuzzyCols, "fuzzyOn")
-        : undefined;
-    const normalizedJoinType = joinKeys?.length || fuzzyKeys?.length
-        ? normalizeJoinType(rawJoinType)
-        : undefined;
-    const fuzzyDistance = fuzzyKeys?.length ? normalizeFuzzyDistance(opts.fuzzyDistance) : undefined;
-    const fuzzyThreshold = opts.fuzzyThreshold ?? 1;
-    if (!Number.isFinite(fuzzyThreshold)) {
-        throw new ClientValidationError("fuzzyThreshold must be a finite number.", "validation_failed");
-    }
-    const recipePrototype = {
-        type,
-        name,
-        projectKey: pk,
-        ...(type === "fuzzyjoin" ? {} : { inputs, }),
-        outputs,
-    };
-    const creationSettings = {};
-    if (payload !== undefined) {
-        creationSettings.script = payload;
-    }
-    if (type === "fuzzyjoin") {
-        creationSettings.virtualInputs = recipeInputItems({ inputs, }).map((item) => item.ref);
-    }
-    return {
-        creationSettings,
-        fuzzyDistance,
-        fuzzyKeys,
-        fuzzyThreshold,
-        inputDatasets,
-        inputs,
-        joinKeys,
-        name,
-        normalizedJoinType,
-        outputFolder,
-        outputs,
-        payload,
-        rawConnection,
-        recipePrototype,
-        temporaryOutputDataset,
-        type,
-    };
+// DSS renames some recipe types server-side (e.g. prediction_scoring becomes
+// "score_<inputDataset>") and documents the creation response as the final
+// unique name: Body {"name": "recipe1"} ("Returns the final unique name of the
+// recipe"). The response name is the contract — falling back to the requested
+// name would mask a missing/invalid receipt, so a body without it is an error.
+function requireRecipeName(created) {
+    const name = asString(created?.["name"]);
+    if (!name) {
+        throw unexpectedResponseError('DSS create-recipe response did not include the final recipe name (documented body: {"name": ...}).');
+    }
+    return name;
 }
 export class RecipesResource extends BaseResource {
     /** List all recipes in a project. */
@@ -636,13 +487,18 @@ export class RecipesResource extends BaseResource {
     async create(opts) {
         const pk = this.resolveProjectKey(opts.projectKey);
         const enc = encodeURIComponent(pk);
-        const { creationSettings, fuzzyDistance, fuzzyKeys, fuzzyThreshold, inputDatasets, inputs, joinKeys, name, normalizedJoinType, outputFolder, outputs, rawConnection, recipePrototype, temporaryOutputDataset, type, } = buildRecipeCreateRequest(opts, pk);
+        const { creationSettings, fuzzyDistance, fuzzyKeys, fuzzyThreshold, grouping, inputDatasets, inputs, joinKeys, normalizedJoinType, outputFolder, outputs, prepareSteps: prepareStepList, rawConnection, recipePrototype, temporaryOutputDataset, type, } = buildRecipeCreateRequest(opts, pk);
         const createRecipe = () => this.client.post(`/public/api/projects/${enc}/recipes/`, {
             recipePrototype,
             creationSettings,
         });
         const createdDatasets = [];
         let usedOutputProvisioningFallback = false;
+        // Missing outputs are created through POST /datasets/managed, like the DSS UI
+        // and dataikuapi's new_managed_dataset: DSS picks the dataset type, storage
+        // path, and format from the connection (an S3 connection yields an S3
+        // dataset under the connection's naming rule), so the client never guesses
+        // type-specific params.
         const provisionOutputDatasets = async () => {
             const existingDs = await this.client.get(`/public/api/projects/${enc}/datasets/`);
             let outputConnection = asString(rawConnection);
@@ -655,126 +511,91 @@ export class RecipesResource extends BaseResource {
             if (!outputConnection)
                 return;
             const existingNames = new Set([...existingDs.map((d) => d.name), ...createdDatasets,]);
-            const connectionSample = existingDs.find((d) => d.params?.connection === outputConnection && d.type);
-            const inferredOutputType = connectionSample?.type ?? "Filesystem";
             const outputRoles = outputs;
             for (const role of Object.values(outputRoles)) {
                 for (const item of role.items ?? []) {
                     if (!item.ref || existingNames.has(item.ref))
                         continue;
-                    const datasetBody = inferredOutputType === "Filesystem"
-                        ? {
-                            projectKey: pk,
-                            name: item.ref,
-                            type: inferredOutputType,
-                            params: {
-                                connection: outputConnection,
-                                path: `/dataiku/${pk}/${item.ref}`,
-                                metastoreTableName: item.ref,
-                            },
-                            formatType: "csv",
-                            formatParams: {
-                                style: "excel",
-                                charset: "utf8",
-                                separator: "\t",
-                                quoteChar: '"',
-                                escapeChar: "\\",
-                                dateSerializationFormat: "ISO",
-                                arrayMapFormat: "json",
-                                parseHeaderRow: true,
-                                compress: "gz",
-                            },
-                            managed: true,
-                        }
-                        : {
-                            projectKey: pk,
-                            name: item.ref,
-                            type: inferredOutputType,
-                            params: {
-                                connection: outputConnection,
-                                mode: "table",
-                                table: item.ref,
-                                ...(connectionSample?.params?.schema
-                                    ? { schema: connectionSample.params.schema, }
-                                    : {}),
-                                ...(connectionSample?.params?.catalog
-                                    ? { catalog: connectionSample.params.catalog, }
-                                    : {}),
-                            },
-                            managed: connectionSample?.managed ?? false,
-                        };
-                    await this.client.post(`/public/api/projects/${enc}/datasets/`, datasetBody);
+                    await this.client.datasets.createManaged({ name: item.ref, connection: outputConnection, }, pk);
                     existingNames.add(item.ref);
-                    if (!createdDatasets.includes(item.ref))
-                        createdDatasets.push(item.ref);
+                    createdDatasets.push(item.ref);
                 }
             }
         };
         let finalRecipeName;
-        // DSS renames some recipe types server-side (e.g. prediction_scoring
-        // becomes "score_<inputDataset>") and documents the creation response as
-        // the final unique name: Body {"name": "recipe1"} ("Returns the final
-        // unique name of the recipe"). The response name is the contract —
-        // falling back to the requested name would mask a missing/invalid
-        // receipt, so a body without it is an error.
-        try {
-            if (rawConnection)
-                await provisionOutputDatasets();
-            const created = await createRecipe();
-            const receivedName = asString(created?.["name"]);
-            if (!receivedName) {
-                throw unexpectedResponseError('DSS create-recipe response did not include the final recipe name (documented body: {"name": ...}).');
-            }
-            finalRecipeName = receivedName;
-        }
-        catch (error) {
-            if (!shouldRetryRecipeCreateWithOutputProvisioning(error)) {
+        // Datasets this call provisioned must not outlive a failed create: the
+        // failure is rethrown unchanged, with the rollback outcome in `details`.
+        // A failure can be ambiguous (timeout, 5xx after DSS committed, a body
+        // without the name), so a dataset some recipe already writes is kept:
+        // deleting it would break that recipe. DSS may rename the recipe, so the
+        // check reads the flow graph rather than the requested recipe name.
+        const rollbackProvisionedDatasets = async (error) => {
+            if (createdDatasets.length === 0)
                 throw error;
+            const deleted = [];
+            const failed = [];
+            const kept = [];
+            let producers;
+            try {
+                const { graph, } = await this.client.projects.flowTopology(pk);
+                producers = new Map(graph.edges.filter((edge) => edge.relation === "writes").map((edge) => [edge.to, edge.from,]));
             }
-            usedOutputProvisioningFallback = true;
-            await provisionOutputDatasets();
-            const retryCreated = await createRecipe();
-            const retryName = asString(retryCreated?.["name"]);
-            if (!retryName) {
-                throw unexpectedResponseError('DSS create-recipe response did not include the final recipe name (documented body: {"name": ...}).');
+            catch (graphError) {
+                const reason = `could not read the flow graph to check for a recipe writing it (${graphError instanceof Error ? graphError.message : String(graphError)})`;
+                for (const name of createdDatasets)
+                    kept.push({ name, reason, });
             }
-            finalRecipeName = retryName;
-        }
-        // For sync recipes (a 1:1 copy) DSS does not propagate schema on build, so a
-        // schemaless dataset output silently builds to an empty dataset. Copy the
-        // single input's schema onto any schemaless dataset output so the build
-        // materializes rows (mirrors the DSS UI, which sets the sync output schema).
-        let syncOutputSchemaPropagated;
-        if (type.toLowerCase() === "sync" && !outputFolder) {
-            const inputRefs = recipeInputItems({ inputs, }).map((item) => item.ref);
-            const outputDatasetRefs = recipeOutputItems({ outputs, })
-                .filter((item) => item.type !== "MANAGED_FOLDER")
-                .map((item) => item.ref);
-            if (inputRefs.length === 1 && outputDatasetRefs.length > 0) {
-                const inputSchema = await this.client.datasets
-                    .schema(inputRefs[0], pk)
-                    .catch(() => undefined);
-                const inputColumns = inputSchema?.columns;
-                if (inputColumns && inputColumns.length > 0) {
-                    const propagated = [];
-                    for (const ref of outputDatasetRefs) {
-                        const current = await this.client.datasets
-                            .schema(ref, pk)
-                            .catch(() => undefined);
-                        if (current && current.columns.length === 0) {
-                            await this.client.datasets.updateSchema(ref, inputColumns, pk);
-                            propagated.push(ref);
-                        }
-                    }
-                    if (propagated.length > 0)
-                        syncOutputSchemaPropagated = propagated;
+            for (const name of createdDatasets) {
+                if (!producers)
+                    break;
+                const producer = producers.get(name);
+                if (producer !== undefined) {
+                    kept.push({ name, reason: `written by recipe ${producer}`, });
+                    continue;
                 }
+                try {
+                    await this.client.del(`/public/api/projects/${enc}/datasets/${encodeURIComponent(name)}`);
+                    deleted.push(name);
+                }
+                catch (deleteError) {
+                    failed.push({
+                        name,
+                        error: deleteError instanceof Error ? deleteError.message : String(deleteError),
+                    });
+                }
+            }
+            if (error instanceof DataikuError || error instanceof ClientValidationError) {
+                error.details = {
+                    ...error.details,
+                    createdDatasetsDeleted: deleted,
+                    createdDatasetsNotDeleted: failed,
+                    ...(kept.length > 0 ? { createdDatasetsKept: kept, } : {}),
+                };
+            }
+            throw error;
+        };
+        try {
+            try {
+                if (rawConnection)
+                    await provisionOutputDatasets();
+                finalRecipeName = requireRecipeName(await createRecipe());
+            }
+            catch (error) {
+                if (!shouldRetryRecipeCreateWithOutputProvisioning(error)) {
+                    throw error;
+                }
+                usedOutputProvisioningFallback = true;
+                await provisionOutputDatasets();
+                finalRecipeName = requireRecipeName(await createRecipe());
             }
         }
+        catch (error) {
+            await rollbackProvisionedDatasets(error);
+        }
         // For join recipes: configure join conditions after creation
         let joinConfigured = false;
         if (type === "join" && joinKeys?.length) {
-            const rnEnc = encodeURIComponent(name);
+            const rnEnc = encodeURIComponent(finalRecipeName);
             const full = await this.client.get(`/public/api/projects/${enc}/recipes/${rnEnc}`);
             const joinPayload = parseRecipePayload(full.payload);
             const inputCount = recipeInputItems({ inputs, }).length || inputDatasets?.length || 2;
@@ -807,7 +628,7 @@ export class RecipesResource extends BaseResource {
             joinConfigured = true;
         }
         if (type === "fuzzyjoin" && fuzzyKeys?.length) {
-            const rnEnc = encodeURIComponent(name);
+            const rnEnc = encodeURIComponent(finalRecipeName);
             const full = await this.client.get(`/public/api/projects/${enc}/recipes/${rnEnc}`);
             const fuzzyPayload = parseRecipePayload(full.payload);
             const inputCount = recipeInputItems({ inputs, }).length || inputDatasets?.length || 2;
@@ -851,9 +672,27 @@ export class RecipesResource extends BaseResource {
             });
             joinConfigured = true;
         }
+        // Grouping keys/aggregates and prepare steps edit the payload DSS created.
+        let payloadConfigured = false;
+        if (grouping || prepareStepList.length > 0) {
+            const rnEnc = encodeURIComponent(finalRecipeName);
+            const full = await this.client.get(`/public/api/projects/${enc}/recipes/${rnEnc}`);
+            const created = parseRecipePayload(full.payload);
+            const configured = grouping
+                ? applyGroupingPayload(created, grouping)
+                : {
+                    ...created,
+                    steps: [...(Array.isArray(created.steps) ? created.steps : []), ...prepareStepList,],
+                };
+            await this.client.put(`/public/api/projects/${enc}/recipes/${rnEnc}`, {
+                ...full,
+                payload: JSON.stringify(configured),
+            });
+            payloadConfigured = true;
+        }
         let temporaryOutputDatasetDeleted;
         if (outputFolder) {
-            await this.update(name, {
+            await this.update(finalRecipeName, {
                 recipe: {
                     outputs: {
                         main: {
@@ -875,18 +714,113 @@ export class RecipesResource extends BaseResource {
                 }
             }
         }
+        // DSS computes visual-recipe output schemas only when asked (the UI asks on
+        // save; dataikuapi exposes compute_schema_updates). Without this, a join or
+        // grouping output keeps an empty schema and its build "succeeds" with no
+        // columns. Only outputs this call created, or whose schema is still empty,
+        // are written: an existing schema is never replaced implicitly.
+        let outputSchemaUpdated;
+        let outputSchemaUpdateError;
+        if (!outputFolder && recipeOutputSchemaIsComputable(type)) {
+            try {
+                const created = new Set(createdDatasets);
+                const { updated, } = await this.applySchemaUpdates(finalRecipeName, await this.computeSchemaUpdates(finalRecipeName, pk), pk, (computable) => computable.previousSchemaWasEmpty === true
+                    || created.has(schemaUpdateComputableId(computable)));
+                if (updated.length > 0)
+                    outputSchemaUpdated = updated;
+            }
+            catch (error) {
+                if (!(error instanceof DataikuError))
+                    throw error;
+                outputSchemaUpdateError = error.message.split("\n")[0];
+            }
+        }
         return {
+            ...(opts.name && opts.name !== finalRecipeName ? { requestedName: opts.name, } : {}),
             recipeName: finalRecipeName,
             type,
             createdDatasets,
             joinConfigured,
+            ...(payloadConfigured ? { payloadConfigured, } : {}),
             outputProvisioningFallbackUsed: usedOutputProvisioningFallback,
-            ...(syncOutputSchemaPropagated ? { syncOutputSchemaPropagated, } : {}),
+            ...(outputSchemaUpdated ? { outputSchemaUpdated, } : {}),
+            ...(outputSchemaUpdateError ? { outputSchemaUpdateError, } : {}),
             ...(outputFolder ? { outputFolder, } : {}),
             ...(temporaryOutputDataset ? { temporaryOutputDataset, } : {}),
             ...(temporaryOutputDatasetDeleted !== undefined ? { temporaryOutputDatasetDeleted, } : {}),
         };
     }
+    /**
+     * Compute the output schemas DSS derives from the recipe's current settings
+     * (GET /recipes/{name}/schema-update, dataikuapi `compute_schema_updates`).
+     * DSS rejects code recipes, whose code sets the schema at run time.
+     */
+    async computeSchemaUpdates(recipeName, projectKey) {
+        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/recipes/${encodeURIComponent(recipeName)}/schema-update`);
+        return this.client.safeParse(RecipeSchemaUpdatesSchema, raw, "recipes.computeSchemaUpdates");
+    }
+    /**
+     * Write each pending computed schema accepted by `select` through
+     * actions/updateOutputSchema. Pending outputs `select` rejects are reported,
+     * not written.
+     */
+    async applySchemaUpdates(recipeName, updates, projectKey, select) {
+        const endpoint = `/public/api/projects/${this.enc(projectKey)}/recipes/${encodeURIComponent(recipeName)}/actions/updateOutputSchema`;
+        const updated = [];
+        const pending = [];
+        const unchanged = [];
+        const datasetsNeedingAction = [];
+        for (const computable of updates.computables) {
+            const computableId = schemaUpdateComputableId(computable);
+            if (!schemaUpdateIsPending(computable)) {
+                unchanged.push(computableId);
+                continue;
+            }
+            if (!select(computable)) {
+                pending.push(computableId);
+                continue;
+            }
+            const applied = await this.client.post(endpoint, { computableType: computable.type, computableId, newSchema: computable.newSchema, });
+            updated.push(computableId);
+            if (applied?.datasetsNeedingAction?.length) {
+                datasetsNeedingAction.push(...applied.datasetsNeedingAction);
+            }
+        }
+        return { updated, pending, unchanged, datasetsNeedingAction, };
+    }
+    /**
+     * Replace each output schema that differs from the DSS-computed one
+     * (dataikuapi `compute_schema_updates().apply()`, the UI's "Update schema").
+     * With `derivedOutputs`, only outputs whose schema is empty or listed there
+     * are written: callers pass the outputs whose schema matched the computed
+     * one before an edit, so DSS-derived schemas follow the edit while
+     * hand-edited ones are left alone. `dryRun` writes nothing. Skipped
+     * differing outputs are listed under `pending`. Code recipes are rejected
+     * before the schema computation: DSS cannot compute their output schema.
+     */
+    async updateSchema(recipeName, opts) {
+        const { recipe, } = await this.get(recipeName, { projectKey: opts?.projectKey, });
+        const recipeType = typeof recipe.type === "string" ? recipe.type : "";
+        if (!recipeOutputSchemaIsComputable(recipeType)) {
+            throw new ClientValidationError(`DSS cannot compute output schemas for ${recipeType} recipes: the code sets the schema when it runs. Build the recipe, or set columns with dss dataset refresh-schema.`, "validation_failed");
+        }
+        const updates = await this.computeSchemaUpdates(recipeName, opts?.projectKey);
+        const derived = opts?.derivedOutputs ? new Set(opts.derivedOutputs) : undefined;
+        const applied = await this.applySchemaUpdates(recipeName, updates, opts?.projectKey, (computable) => opts?.dryRun !== true
+            && (derived === undefined || computable.previousSchemaWasEmpty === true
+                || derived.has(schemaUpdateComputableId(computable))));
+        return {
+            recipeName,
+            updated: applied.updated,
+            pending: applied.pending,
+            unchanged: applied.unchanged,
+            totalIncompatibilities: updates.totalIncompatibilities ?? 0,
+            computables: updates.computables,
+            ...(applied.datasetsNeedingAction.length > 0
+                ? { datasetsNeedingAction: applied.datasetsNeedingAction, }
+                : {}),
+        };
+    }
     /**
      * Update a recipe by merging the patch into the current definition.
      * The `recipe` sub-object is deep-merged to preserve nested fields.

package/dist/src/resources/saved-models.d.ts

@@ -1,4 +1,5 @@
 import { BaseResource } from "./base.js";
+import { type ScoringJarOptions, TrainedModel } from "./trained-model.js";
 export interface SavedModelListItem extends Record<string, unknown> {
     id?: string;
     name?: string;
@@ -64,11 +65,6 @@ export interface ExternalModelVersionEvaluateOptions extends Record<string, unkn
     useOptimalThreshold?: boolean;
     skipExpensiveReports?: boolean;
 }
-/** Query options for the scoring JAR export (GET .../scoring-jar). */
-export interface SavedModelScoringJarOptions extends Record<string, unknown> {
-    fullClassName?: string;
-    includeLibs?: boolean;
-}
 export declare class SavedModelsResource extends BaseResource {
     /** List saved models in a project. */
     list(projectKey?: string): Promise<SavedModelListItem[]>;
@@ -159,7 +155,7 @@ export declare class SavedModelsResource extends BaseResource {
      * responsible for consuming the response body (e.g. writeResponseToFile);
      * the stream is read under the client body deadline.
      */
-    downloadScoringJar(options: SavedModelScoringJarOptions | undefined, savedModelId: string, versionId: string, projectKey?: string): Promise<Response>;
+    downloadScoringJar(options: ScoringJarOptions | undefined, savedModelId: string, versionId: string, projectKey?: string): Promise<Response>;
     /** GET the scoring PMML of a version as a binary/XML stream. */
     downloadScoringPmml(savedModelId: string, versionId: string, projectKey?: string): Promise<Response>;
     /**
@@ -167,6 +163,14 @@ export declare class SavedModelsResource extends BaseResource {
      * "userMeta" field of a previously-retrieved version-details object.
      */
     setUserMeta(savedModelId: string, versionId: string, userMeta: Record<string, unknown>, projectKey?: string): Promise<void>;
+    /**
+     * One saved-model version as a {@link TrainedModel}: diagnostics
+     * (subpopulation analyses, partial dependencies, timeseries residuals and
+     * per-series results), documentation, scoring exports, user metadata.
+     */
+    version(savedModelId: string, versionId: string, projectKey?: string): TrainedModel;
+    /** GET a generated saved-model version documentation (docx) by the `exportId` of its finished future. */
+    downloadDocumentation(exportId: string, projectKey?: string): Promise<Response>;
     /** Delete a saved model and all of its versions. */
     delete(savedModelId: string, projectKey?: string): Promise<void>;
     private mlflowImportQuery;