dataiku-sdk 3.6.1 → 3.8.0

package/dist/src/resources/datasets.js

@@ -1,15 +1,14 @@
 import * as fs from "node:fs";
 import * as nodePath from "node:path";
-import { Readable, Transform, } from "node:stream";
-import { pipeline, } from "node:stream/promises";
 import { StringDecoder, } from "node:string_decoder";
-import { createGzip, } from "node:zlib";
 import { ClientValidationError, DataikuError, } from "../errors.js";
 import { DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, } from "../schemas.js";
 import { deepMerge, } from "../utils/deep-merge.js";
+import { isRecord, } from "../utils/records.js";
 import { sanitizeFileName, } from "../utils/sanitize.js";
 import { BaseResource, } from "./base.js";
 import { resolveAdminManagedStorageConnection, } from "./connections.js";
+import { buildDatasetCreateBody, } from "./dataset-create.js";
 // ---------------------------------------------------------------------------
 // Helpers: TSV → CSV streaming conversion
 // ---------------------------------------------------------------------------
@@ -404,13 +403,14 @@ const CSV_BATCH_BYTES = 64 * 1024;
 function tsvToCsvTransform(maxDataRows, stats, onHeader, spreadsheetSafe = true) {
     const state = createTsvStreamState();
     const decoder = new StringDecoder("utf-8");
+    const encoder = new TextEncoder();
     const maxRows = Math.max(1, maxDataRows);
     let headerSeen = false;
     let done = false;
     // Bounded CSV output batching: emitted rows accumulate here and are joined
-    // into a single push once the batch reaches CSV_BATCH_BYTES, so memory stays
-    // bounded by the batch budget plus one escaped row (the join briefly holds a
-    // second copy of the batch) while per-row push/callback overhead disappears.
+    // into a single enqueue once the batch reaches CSV_BATCH_BYTES, so memory
+    // stays bounded by the batch budget plus one escaped row (the join briefly
+    // holds a second copy of the batch) while per-row chunk overhead disappears.
     let batchLines = [];
     let batchBytes = 0;
     const flushBatch = (target) => {
@@ -419,7 +419,7 @@ function tsvToCsvTransform(maxDataRows, stats, onHeader, spreadsheetSafe = true)
         const csv = batchLines.join("");
         batchLines = [];
         batchBytes = 0;
-        target.push(csv);
+        target.enqueue(encoder.encode(csv));
     };
     const queueLine = (target, line) => {
         batchLines.push(line);
@@ -450,48 +450,27 @@ function tsvToCsvTransform(maxDataRows, stats, onHeader, spreadsheetSafe = true)
         push(`${rowToCsv(row, spreadsheetSafe)}\n`);
         stats.rows += 1;
     };
-    return new Transform({
-        transform(chunk, _encoding, callback) {
+    // A byte-limit overflow throws out of transform/flush: the stream errors,
+    // which cancels the response and makes download() remove the partial file.
+    return new TransformStream({
+        transform(chunk, controller) {
+            consumeTsvChunk(decoder.write(chunk), state, (row) => handleRow(row, (line) => queueLine(controller, line)));
             if (done) {
-                callback();
-                return;
-            }
-            try {
-                consumeTsvChunk(decoder.write(chunk), state, (row) => handleRow(row, (line) => queueLine(this, line)));
-            }
-            catch (error) {
-                // Byte-limit overflow: destroy the transform so the pipeline
-                // cancels the response and the partial file is removed.
-                callback(error instanceof Error ? error : new ClientValidationError(String(error), "internal_error"));
-                return;
+                // Truncation reached: emit the batch queued so far, end the output,
+                // and cancel the rest of the response.
+                flushBatch(controller);
+                controller.terminate();
             }
-            if (done) {
-                // Truncation reached: emit the batch queued so far before EOF.
-                flushBatch(this);
-                this.push(null);
-            }
-            callback();
         },
-        flush(callback) {
-            if (done) {
-                callback();
-                return;
-            }
-            try {
-                const tail = decoder.end();
-                if (tail !== "") {
-                    consumeTsvChunk(tail, state, (row) => handleRow(row, (line) => queueLine(this, line)));
-                }
-                flushTsvStream(state, (row) => handleRow(row, (line) => queueLine(this, line)));
-            }
-            catch (error) {
-                callback(error instanceof Error ? error : new ClientValidationError(String(error), "internal_error"));
-                return;
+        flush(controller) {
+            const tail = decoder.end();
+            if (tail !== "") {
+                consumeTsvChunk(tail, state, (row) => handleRow(row, (line) => queueLine(controller, line)));
             }
+            flushTsvStream(state, (row) => handleRow(row, (line) => queueLine(controller, line)));
             // Emit the trailing partial batch; without this the last rows of a
             // download (below the batch budget) would be silently dropped.
-            flushBatch(this);
-            callback();
+            flushBatch(controller);
         },
     });
 }
@@ -518,60 +497,6 @@ function isMissingUploadedFilesTargetConnection(error) {
     return (detail.includes("without a target connection")
         || detail.includes("target connection is required"));
 }
-/** Wire body for POST /datasets/; shared with `dataset create --plan` so the plan matches the request. */
-export function buildDatasetCreateBody(opts) {
-    if (opts.dsType.toLowerCase() === "uploadedfiles") {
-        return {
-            projectKey: opts.projectKey,
-            name: opts.datasetName,
-            type: opts.dsType,
-            params: opts.connection ? { uploadConnection: opts.connection, } : {},
-        };
-    }
-    if (!opts.connection) {
-        throw new ClientValidationError("connection is required unless dsType is UploadedFiles.");
-    }
-    if (opts.table) {
-        const params = {
-            connection: opts.connection,
-            mode: "table",
-            table: opts.table,
-        };
-        if (opts.dbSchema)
-            params.schema = opts.dbSchema;
-        if (opts.catalog)
-            params.catalog = opts.catalog;
-        return {
-            projectKey: opts.projectKey,
-            name: opts.datasetName,
-            type: opts.dsType,
-            params,
-            managed: opts.managed ?? false,
-        };
-    }
-    return {
-        projectKey: opts.projectKey,
-        name: opts.datasetName,
-        type: opts.dsType,
-        params: {
-            connection: opts.connection,
-            path: `/dataiku/${opts.projectKey}/${opts.datasetName}`,
-        },
-        formatType: opts.formatType ?? "csv",
-        formatParams: opts.formatParams ?? {
-            style: "excel",
-            charset: "utf8",
-            separator: "\t",
-            quoteChar: '"',
-            escapeChar: "\\",
-            dateSerializationFormat: "ISO",
-            arrayMapFormat: "json",
-            parseHeaderRow: true,
-            compress: "gz",
-        },
-        managed: opts.managed ?? true,
-    };
-}
 const DATASET_CLONE_PARAM_KEYS = [
     "connection",
     "uploadConnection",
@@ -595,6 +520,28 @@ function cloneDatasetParams(params) {
     }
     return cloned;
 }
+/** Explain an empty detection result from the first error DSS put in the response body. */
+function describeSqlDetectionFailure(raw) {
+    if (!isRecord(raw))
+        return "DSS returned no schema detection result.";
+    for (const [key, value,] of Object.entries(raw)) {
+        if (!key.endsWith("Error"))
+            continue;
+        if (typeof value === "string" && value !== "")
+            return value;
+        if (isRecord(value)) {
+            const message = value["detailedMessage"] ?? value["message"];
+            if (typeof message === "string" && message !== "")
+                return message;
+        }
+    }
+    const failedChecks = Object.entries(raw)
+        .filter(([key, value,]) => key.endsWith("OK") && value === false)
+        .map(([key,]) => key);
+    return failedChecks.length > 0
+        ? `DSS detected no columns (failed checks: ${failedChecks.join(", ")}).`
+        : "DSS detected no columns.";
+}
 function parseUploadedFiles(raw, datasetName) {
     if (!Array.isArray(raw)) {
         throw new ClientValidationError(`DSS returned an invalid uploaded-files list for dataset ${datasetName}.`, "validation_failed", "Expected an array from the UploadedFiles dataset file endpoint.");
@@ -668,6 +615,40 @@ export class DatasetsResource extends BaseResource {
         const dsEnc = encodeURIComponent(datasetName);
         await this.client.put(`/public/api/projects/${this.enc(projectKey)}/datasets/${dsEnc}/schema`, { columns, });
     }
+    /**
+     * Detect the schema of a SQL dataset (table or query mode) with DSS and
+     * store it: `POST /actions/testAndDetectSettings/externalSQL` (what
+     * dataikuapi's `autodetect_settings` calls), then `PUT /schema` with the
+     * suggested schema. DSS reports connection, table, and query problems in the
+     * response body (HTTP 200), so a failed detection is returned with
+     * `detected: false` and the reason instead of thrown.
+     */
+    async detectSqlSchema(datasetName, projectKey) {
+        const base = `/public/api/projects/${this.enc(projectKey)}/datasets/${encodeURIComponent(datasetName)}`;
+        try {
+            const raw = await this.client.post(`${base}/actions/testAndDetectSettings/externalSQL`);
+            const detection = isRecord(raw) ? raw["schemaDetection"] : undefined;
+            const newSchema = isRecord(detection) ? detection["newSchema"] : undefined;
+            const rawColumns = isRecord(newSchema) && Array.isArray(newSchema["columns"])
+                ? newSchema["columns"]
+                : [];
+            const columns = rawColumns.flatMap((column) => isRecord(column) && typeof column["name"] === "string"
+                && typeof column["type"] === "string"
+                ? [{ name: column["name"], type: column["type"], },]
+                : []);
+            if (!isRecord(newSchema) || columns.length === 0) {
+                return { detected: false, columns: [], error: describeSqlDetectionFailure(raw), };
+            }
+            await this.client.put(`${base}/schema`, newSchema);
+            return { detected: true, columns, };
+        }
+        catch (error) {
+            if (error instanceof DataikuError) {
+                return { detected: false, columns: [], error: error.message.split("\n")[0] ?? "", };
+            }
+            throw error;
+        }
+    }
     /**
      * Get the raw dataset schema object exactly as the DSS schema endpoint
      * returns it, without schema validation — used for deterministic comparison.
@@ -676,6 +657,23 @@ export class DatasetsResource extends BaseResource {
         const dsEnc = encodeURIComponent(datasetName);
         return this.client.get(`/public/api/projects/${this.enc(projectKey)}/datasets/${dsEnc}/schema`);
     }
+    /**
+     * TSV data stream of at most `limit` rows. A column or partition selection
+     * uses the documented POST variant of the data endpoint (body `columns`,
+     * `partitions`, `format`, `sampling`); otherwise the GET endpoint.
+     */
+    async dataStream(datasetName, limit, projectKey, selection) {
+        const path = `/public/api/projects/${this.enc(projectKey)}/datasets/${encodeURIComponent(datasetName)}/data/`;
+        if (!selection?.columns?.length && !selection?.partitions) {
+            return this.client.stream(`${path}?format=tsv-excel-header&limit=${limit}`);
+        }
+        return this.client.postStream(path, {
+            format: "tsv-excel-header",
+            ...(selection.columns?.length ? { columns: selection.columns, } : {}),
+            ...(selection.partitions ? { partitions: selection.partitions, } : {}),
+            sampling: { samplingMethod: "HEAD_SEQUENTIAL", maxRecords: limit, },
+        });
+    }
     /**
      * Preview dataset rows as structured data: column names plus row arrays,
      * mirroring the sql query shape ({ columns, rows, rowCount }). Streams TSV
@@ -691,10 +689,9 @@ export class DatasetsResource extends BaseResource {
     async preview(datasetName, opts) {
         const maxRows = Math.max(1, Math.min(opts?.maxRows ?? 50, 500));
         const timeoutMs = Math.max(1, opts?.timeoutMs ?? this.client.getRequestTimeoutMs());
-        const dsEnc = encodeURIComponent(datasetName);
         // Probe one row past the cap so callers learn whether the dataset holds
         // more rows than requested without materializing the full dataset.
-        const res = await this.client.stream(`/public/api/projects/${this.enc(opts?.projectKey)}/datasets/${dsEnc}/data/?format=tsv-excel-header&limit=${maxRows + 1}`);
+        const res = await this.dataStream(datasetName, maxRows + 1, opts?.projectKey, opts);
         const onHeader = opts?.validateColumns
             ? (headerRow) => {
                 const warnings = validateStreamColumns(headerRow, opts.validateColumns);
@@ -761,6 +758,20 @@ export class DatasetsResource extends BaseResource {
         const dsEnc = encodeURIComponent(datasetName);
         return this.client.put(`/public/api/projects/${this.enc(projectKey)}/datasets/${dsEnc}/metadata`, metadata);
     }
+    /**
+     * Create or update the Hive table of an HDFS dataset so it matches the
+     * dataset schema (POST /actions/synchronizeHiveMetastore).
+     */
+    async synchronizeHiveMetastore(datasetName, projectKey) {
+        await this.client.post(`/public/api/projects/${this.enc(projectKey)}/datasets/${encodeURIComponent(datasetName)}/actions/synchronizeHiveMetastore`);
+    }
+    /**
+     * Update an HDFS dataset (path, schema, partitioning, format) from its
+     * Hive table (POST /actions/updateFromHive).
+     */
+    async updateFromHive(datasetName, projectKey) {
+        await this.client.post(`/public/api/projects/${this.enc(projectKey)}/datasets/${encodeURIComponent(datasetName)}/actions/updateFromHive`);
+    }
     /**
      * Create a managed dataset through the dedicated
      * `POST /projects/{projectKey}/datasets/managed` endpoint. DSS handles the
@@ -862,8 +873,7 @@ export class DatasetsResource extends BaseResource {
      */
     async download(datasetName, opts) {
         const limit = Math.max(1, opts?.limit ?? 100_000);
-        const dsEnc = encodeURIComponent(datasetName);
-        const res = await this.client.stream(`/public/api/projects/${this.enc(opts?.projectKey)}/datasets/${dsEnc}/data/?format=tsv-excel-header&limit=${limit + 1}`);
+        const res = await this.dataStream(datasetName, limit + 1, opts?.projectKey, opts);
         const safeDatasetName = sanitizeFileName(datasetName, "dataset");
         const filePath = opts?.outputPath?.endsWith(".gz") || opts?.outputPath?.endsWith(".csv")
             ? nodePath.resolve(opts.outputPath)
@@ -878,18 +888,13 @@ export class DatasetsResource extends BaseResource {
             : undefined;
         const shouldGzip = filePath.endsWith(".gz");
         const stats = { rows: 0, truncated: false, };
-        const nodeStream = Readable.from(res.body, { objectMode: false, });
-        const csvTransform = tsvToCsvTransform(limit, stats, onHeader, opts?.rawData !== true);
+        let csv = res.body.pipeThrough(tsvToCsvTransform(limit, stats, onHeader, opts?.rawData !== true));
+        if (shouldGzip)
+            csv = csv.pipeThrough(new CompressionStream("gzip"));
         fs.mkdirSync(nodePath.dirname(filePath), { recursive: true, });
-        const fileOut = fs.createWriteStream(filePath);
         try {
-            if (shouldGzip) {
-                const gzip = createGzip();
-                await pipeline(nodeStream, csvTransform, gzip, fileOut);
-            }
-            else {
-                await pipeline(nodeStream, csvTransform, fileOut);
-            }
+            // Native streaming write with backpressure; no Node stream layer.
+            await Bun.write(filePath, new Response(csv));
         }
         catch (error) {
             // A failed export (byte-limit overflow, network error) must never
@@ -911,7 +916,7 @@ export class DatasetsResource extends BaseResource {
         const enc = encodeURIComponent(pk);
         const explicitType = opts.dsType;
         let dsType = explicitType
-            ?? (opts.table ? DEFAULT_DATABASE_DATASET_TYPE : DEFAULT_FILESYSTEM_DATASET_TYPE);
+            ?? (opts.table || opts.query ? DEFAULT_DATABASE_DATASET_TYPE : DEFAULT_FILESYSTEM_DATASET_TYPE);
         let body = buildDatasetCreateBody({
             projectKey: pk,
             datasetName: opts.datasetName,
@@ -920,6 +925,7 @@ export class DatasetsResource extends BaseResource {
             table: opts.table,
             dbSchema: opts.dbSchema,
             catalog: opts.catalog,
+            query: opts.query,
             formatType: opts.formatType,
             formatParams: opts.formatParams,
             managed: opts.managed,
@@ -951,6 +957,7 @@ export class DatasetsResource extends BaseResource {
                     table: opts.table,
                     dbSchema: opts.dbSchema,
                     catalog: opts.catalog,
+                    query: opts.query,
                     formatType: opts.formatType,
                     formatParams: opts.formatParams,
                     managed: opts.managed,
@@ -975,6 +982,7 @@ export class DatasetsResource extends BaseResource {
                 table: opts.table,
                 dbSchema: opts.dbSchema,
                 catalog: opts.catalog,
+                query: opts.query,
                 formatType: opts.formatType,
                 formatParams: opts.formatParams,
                 managed: opts.managed,

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

@@ -21,6 +21,11 @@ export declare class DiscussionsResource extends BaseResource {
     create(objectType: string, objectId: string, topic: string, reply: string, projectKey?: string): Promise<Discussion>;
     /** Add a reply to an existing discussion. */
     reply(objectType: string, objectId: string, discussionId: string, text: string, projectKey?: string): Promise<Discussion>;
+    /**
+     * Update a discussion (topic, or the object it is attached to within the
+     * project): PUT the full discussion object obtained from `get`, edited.
+     */
+    update(objectType: string, objectId: string, discussionId: string, discussion: Record<string, unknown>, projectKey?: string): Promise<Discussion>;
     private objectDiscussionsPath;
     private discussionPath;
 }

package/dist/src/resources/discussions.js

@@ -16,6 +16,13 @@ export class DiscussionsResource extends BaseResource {
     async reply(objectType, objectId, discussionId, text, projectKey) {
         return this.client.post(`${this.discussionPath(objectType, objectId, discussionId, projectKey)}/replies/`, { reply: text, });
     }
+    /**
+     * Update a discussion (topic, or the object it is attached to within the
+     * project): PUT the full discussion object obtained from `get`, edited.
+     */
+    async update(objectType, objectId, discussionId, discussion, projectKey) {
+        return this.client.put(this.discussionPath(objectType, objectId, discussionId, projectKey), discussion);
+    }
     objectDiscussionsPath(objectType, objectId, projectKey) {
         const pk = this.enc(projectKey);
         const encodedType = encodeURIComponent(objectType);

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

@@ -0,0 +1,25 @@
+import type { DataikuClient } from "../client.js";
+import { type DssTask } from "./futures.js";
+/** Documentation template: the DSS default, an uploaded docx, or a docx in a managed folder. */
+export type DocumentationTemplate = {
+    kind: "default";
+} | {
+    kind: "file";
+    filePath: string;
+} | {
+    kind: "folder";
+    folderId: string;
+    path: string;
+};
+/** The three generation endpoints of one documented object (flow, lab model, saved-model version). */
+export interface DocumentationRoutes {
+    default: string;
+    file: string;
+    folder: string;
+}
+/**
+ * Start a DSS documentation export (docx): POST the default route, upload the
+ * template as multipart `file`, or POST the folder route with `folderId` and
+ * `path`. The finished task's result carries the `exportId` to download.
+ */
+export declare function startDocumentation(client: DataikuClient, routes: DocumentationRoutes, template: DocumentationTemplate, operation: string): Promise<DssTask>;

package/dist/src/resources/documentation.js

@@ -0,0 +1,16 @@
+import { dssTask, } from "./futures.js";
+/**
+ * Start a DSS documentation export (docx): POST the default route, upload the
+ * template as multipart `file`, or POST the folder route with `folderId` and
+ * `path`. The finished task's result carries the `exportId` to download.
+ */
+export async function startDocumentation(client, routes, template, operation) {
+    if (template.kind === "file") {
+        return dssTask(await client.uploadJson(routes.file, template.filePath), operation);
+    }
+    if (template.kind === "folder") {
+        const query = new URLSearchParams({ folderId: template.folderId, path: template.path, });
+        return dssTask(await client.post(`${routes.folder}?${query}`), operation);
+    }
+    return dssTask(await client.post(routes.default), operation);
+}

package/dist/src/resources/flow-zones.d.ts

@@ -1,11 +1,21 @@
 import type { DataikuGetOptions } from "../client.js";
-import type { FlowZone, FlowZoneCreateOptions, FlowZoneObjectType, FlowZoneUpdateOptions } from "../schemas.js";
+import type { FlowZone, FlowZoneCreateOptions, FlowZoneObjectType, FlowZonePosition, FlowZoneUpdateOptions } from "../schemas.js";
 import { BaseResource } from "./base.js";
 export type FlowZoneItemInput = {
     objectId: string;
     objectType: FlowZoneObjectType;
     projectKey?: string;
 };
+export type FlowZoneRecreateOptions = {
+    position: FlowZonePosition;
+    name?: string;
+    color?: string;
+    projectKey?: string;
+};
+export type FlowZoneRecreateResult = {
+    zone: FlowZone;
+    replacedZoneId: string;
+};
 export declare class FlowZonesResource extends BaseResource {
     /**
      * List all flow zones in a project. Pass `timeoutMs` to bound the whole
@@ -14,10 +24,26 @@ export declare class FlowZonesResource extends BaseResource {
     list(projectKey?: string, options?: DataikuGetOptions): Promise<FlowZone[]>;
     /** Get one flow zone by id. */
     get(zoneId: string, projectKey?: string): Promise<FlowZone>;
-    /** Create a flow zone. */
+    /**
+     * Create a flow zone. DSS stores `position` only while the project's manual
+     * zone positioning is off; with it on, DSS auto-places the zone.
+     */
     create(opts: FlowZoneCreateOptions): Promise<FlowZone>;
-    /** Update flow zone settings such as name, color, and manual position. */
+    /**
+     * Update flow zone name and color. DSS's public API ignores `position` on
+     * this endpoint; use {@link recreate} to move an existing zone.
+     */
     update(zoneId: string, opts: FlowZoneUpdateOptions): Promise<FlowZone>;
+    /**
+     * Replace a zone with a new one at `position`: DSS honors a zone position
+     * only on creation, and only while the project's manual zone positioning is
+     * off (otherwise it auto-places the new zone). The replacement receives the
+     * old zone's name, color, metadata (tags, custom fields, checklists, ...),
+     * items, and shared items; the old zone is deleted once it is empty. The zone
+     * id changes, so anything referencing the old id (for example scenario zone
+     * builds) must be updated.
+     */
+    recreate(zoneId: string, opts: FlowZoneRecreateOptions): Promise<FlowZoneRecreateResult>;
     /** Delete a flow zone. DSS moves its items back to the default zone. */
     delete(zoneId: string, projectKey?: string): Promise<void>;
     /** Move items into a flow zone. */

package/dist/src/resources/flow-zones.js

@@ -23,7 +23,10 @@ export class FlowZonesResource extends BaseResource {
         const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/flow/zones/${encodeURIComponent(zoneId)}`);
         return this.client.safeParse(FlowZoneSchema, raw, "flowZones.get");
     }
-    /** Create a flow zone. */
+    /**
+     * Create a flow zone. DSS stores `position` only while the project's manual
+     * zone positioning is off; with it on, DSS auto-places the zone.
+     */
     async create(opts) {
         const raw = await this.client.post(`/public/api/projects/${this.enc(opts.projectKey)}/flow/zones`, {
             name: opts.name,
@@ -32,17 +35,64 @@ export class FlowZonesResource extends BaseResource {
         });
         return this.client.safeParse(FlowZoneSchema, raw, "flowZones.create");
     }
-    /** Update flow zone settings such as name, color, and manual position. */
+    /**
+     * Update flow zone name and color. DSS's public API ignores `position` on
+     * this endpoint; use {@link recreate} to move an existing zone.
+     */
     async update(zoneId, opts) {
         const current = await this.get(zoneId, opts.projectKey);
         const merged = deepMerge(current, {
             ...(opts.name !== undefined ? { name: opts.name, } : {}),
             ...(opts.color !== undefined ? { color: opts.color, } : {}),
-            ...(opts.position !== undefined ? { position: opts.position, } : {}),
         });
         await this.client.putVoid(`/public/api/projects/${this.enc(opts.projectKey)}/flow/zones/${encodeURIComponent(zoneId)}`, merged);
         return this.get(zoneId, opts.projectKey);
     }
+    /**
+     * Replace a zone with a new one at `position`: DSS honors a zone position
+     * only on creation, and only while the project's manual zone positioning is
+     * off (otherwise it auto-places the new zone). The replacement receives the
+     * old zone's name, color, metadata (tags, custom fields, checklists, ...),
+     * items, and shared items; the old zone is deleted once it is empty. The zone
+     * id changes, so anything referencing the old id (for example scenario zone
+     * builds) must be updated.
+     */
+    async recreate(zoneId, opts) {
+        const base = `/public/api/projects/${this.enc(opts.projectKey)}/flow/zones`;
+        const old = await this.get(zoneId, opts.projectKey);
+        const created = await this.create({
+            name: opts.name ?? old.name,
+            color: opts.color ?? old.color,
+            position: opts.position,
+            projectKey: opts.projectKey,
+        });
+        const completed = ["create",];
+        try {
+            const { id: _id, items, shared, position: _position, ...metadata } = old;
+            await this.client.putVoid(`${base}/${encodeURIComponent(created.id)}`, {
+                ...created,
+                ...metadata,
+                id: created.id,
+                name: created.name,
+                color: created.color,
+                position: created.position,
+            });
+            completed.push("metadata");
+            if (items && items.length > 0) {
+                await this.moveItems(created.id, items, opts.projectKey);
+            }
+            completed.push("items");
+            for (const item of shared ?? []) {
+                await this.client.post(`${base}/${encodeURIComponent(created.id)}/shared`, normalizeZoneItem(item));
+            }
+            completed.push("shared");
+            await this.delete(old.id, opts.projectKey);
+        }
+        catch (error) {
+            throw new ClientValidationError(`Recreating flow zone ${old.id} at a new position stopped after ${completed.at(-1)}; both zones may now exist.`, "ambiguous_outcome", "Inspect both zones with dss flow-zone list, then move remaining items and delete the zone you no longer need.", { replacedZoneId: old.id, zoneId: created.id, completed, }, { cause: error, });
+        }
+        return { zone: await this.get(created.id, opts.projectKey), replacedZoneId: old.id, };
+    }
     /** Delete a flow zone. DSS moves its items back to the default zone. */
     async delete(zoneId, projectKey) {
         await this.client.del(`/public/api/projects/${this.enc(projectKey)}/flow/zones/${encodeURIComponent(zoneId)}`);

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

@@ -0,0 +1,48 @@
+import type { FutureWaitResult } from "../schemas.js";
+import { BaseResource } from "./base.js";
+import { type DocumentationTemplate } from "./documentation.js";
+import { type DssTask, type FutureWaitOptions } from "./futures.js";
+/** Schema propagation options (dataikuapi `DSSSchemaPropagationRunBuilder` settings). */
+export interface SchemaPropagationOptions {
+    projectKey?: string;
+    /** Rebuild datasets when propagation needs their data (DSS default: true). */
+    autoRebuild?: boolean;
+    /** Recipes where propagation stops (dataikuapi `stop_at`). */
+    excludedRecipes?: string[];
+    /** Recipes always considered OK (dataikuapi `mark_recipe_as_ok`). */
+    markAsOkRecipes?: string[];
+    /** Partitioned flows: default partition value per dimension when rebuilding. */
+    defaultPartitionValuesByDimension?: Record<string, string>;
+    /** Partitioned flows: partition per computable, keyed `PROJECTKEY.id`. */
+    partitionsByComputable?: Record<string, string>;
+    /** Per-recipe-type and per-recipe update options, as dataikuapi sends them. */
+    recipeUpdateOptions?: {
+        byType?: Record<string, unknown>;
+        byName?: Record<string, unknown>;
+    };
+}
+/**
+ * Flow-wide tools: schema propagation from a dataset through every downstream
+ * recipe, and flow documentation export. Zones and the flow graph live on
+ * `flowZones`; per-recipe schema updates on `recipes.updateSchema`.
+ */
+export declare class FlowResource extends BaseResource {
+    private flowPath;
+    /**
+     * Start propagating `datasetName`'s schema through the flow
+     * (POST /flow/tools/propagate-schema/, dataikuapi
+     * `new_schema_propagation(...).start()`). Returns the DSS future.
+     */
+    propagateSchema(datasetName: string, opts?: SchemaPropagationOptions): Promise<DssTask>;
+    propagateSchemaAndWait(datasetName: string, opts?: SchemaPropagationOptions & FutureWaitOptions): Promise<FutureWaitResult | DssTask>;
+    /**
+     * Start generating the flow documentation (docx) from the DSS default
+     * template, an uploaded docx template, or a docx in a managed folder.
+     * The finished future's result carries the `exportId` to download.
+     */
+    generateDocumentation(template?: DocumentationTemplate, projectKey?: string): Promise<DssTask>;
+    /** GET a generated flow documentation (docx) as a binary stream. */
+    downloadDocumentation(exportId: string, projectKey?: string): Promise<Response>;
+}
+/** Request body of POST /flow/tools/propagate-schema/ (pure; shared with `--plan`). */
+export declare function schemaPropagationBody(projectKey: string, datasetName: string, opts: SchemaPropagationOptions): Record<string, unknown>;