dataiku-sdk 3.1.0 → 3.3.0

package/dist/src/resources/macros.js

@@ -0,0 +1,231 @@
+import { ClientValidationError, DataikuError, } from "../errors.js";
+import { MacroDefinitionSchema, MacroRunStartSchema, MacroStateSchema, MacroSummaryArraySchema, MacroWaitResultSchema, } from "../schemas.js";
+import { computeNextPollDelayMs, isRequestDeadlineError, } from "../utils/polling.js";
+import { BaseResource, requireNonEmpty, } from "./base.js";
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_TIMEOUT_MS = 120_000;
+/** Hard floor for the result download cap; keeps a caller typo from hanging the read. */
+const MIN_RESULT_MAX_BYTES = 1;
+const MAX_RESULT_MAX_BYTES = 2 * 1024 * 1024 * 1024;
+/**
+ * Normalize a byte cap coming from user input (CLI `--max-bytes`) into the
+ * inclusive range [1, 2 GiB], rejecting non-integers before any DSS request.
+ */
+export function macroResultMaxBytes(maxBytes) {
+    const raw = maxBytes ?? 8 * 1024 * 1024;
+    if (!Number.isInteger(raw) || raw < MIN_RESULT_MAX_BYTES) {
+        throw new ClientValidationError(`maxBytes must be a positive integer >= ${String(MIN_RESULT_MAX_BYTES)} (got ${String(raw)},)`);
+    }
+    return Math.min(raw, MAX_RESULT_MAX_BYTES);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Build the run POST body from params/adminParams. DSS macro runs accept
+ * `params` keyed by the macro's declared param names and `adminParams` keyed
+ * by its declared adminParams names; both are optional.
+ */
+function macroRunBody(params, adminParams) {
+    const body = {};
+    if (params !== undefined)
+        body["params"] = params;
+    if (adminParams !== undefined)
+        body["adminParams"] = adminParams;
+    return body;
+}
+function macroRunFailure(state) {
+    if (state["resultError"] !== undefined && state["resultError"] !== null) {
+        return { source: "resultError", details: state["resultError"], };
+    }
+    if (state["storedError"] !== undefined && state["storedError"] !== null) {
+        return { source: "storedError", details: state["storedError"], };
+    }
+    return undefined;
+}
+/**
+ * DSS Macros — the plugin "runnable" surface under
+ * `/public/api/projects/{pk}/runnables`.
+ *
+ * A macro run executes arbitrary plugin code on the DSS backend with
+ * side effects that DSS cannot predict; every method here that starts or
+ * stops a run is a write. Result bodies may be plain text or HTML rather
+ * than JSON, so {@link MacrosResource.result} returns the raw body.
+ */
+export class MacrosResource extends BaseResource {
+    /**
+     * List the macros (runnables) available in a project. The official client
+     * lists at `/runnables/` (trailing slash): the slashless path 404s on live
+     * DSS 15, while get/run/state/result stay slashless.
+     */
+    async list(projectKey) {
+        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/runnables/`);
+        return this.client.safeParse(MacroSummaryArraySchema, raw, "macros.list");
+    }
+    /** Get the definition of a macro: params, result type, owning plugin. */
+    async definition(runnableType, opts) {
+        requireNonEmpty(runnableType, "runnableType");
+        const raw = await this.client.get(`${this.base(runnableType, opts?.projectKey)}`);
+        return this.client.safeParse(MacroDefinitionSchema, raw, "macros.definition");
+    }
+    /**
+     * Start a macro run. Executes arbitrary plugin code: classify as
+     * destructive. With `wait: true` the server call blocks until completion
+     * and the resolved state is attached to the returned run handle.
+     */
+    async run(runnableType, opts) {
+        requireNonEmpty(runnableType, "runnableType");
+        const wait = opts?.wait === true;
+        const query = wait ? "?wait=true" : "?wait=false";
+        const raw = await this.client.post(`${this.base(runnableType, opts?.projectKey)}${query}`, macroRunBody(opts?.params, opts?.adminParams));
+        const run = this.client.safeParse(MacroRunStartSchema, raw, "macros.run");
+        if (typeof run?.runId !== "string" || run.runId.trim().length === 0) {
+            throw new DataikuError(200, "Unexpected Response", "macros.run: DSS did not return a run identifier.");
+        }
+        if (!wait)
+            return run;
+        try {
+            const state = await this.state(runnableType, run.runId, {
+                projectKey: opts?.projectKey,
+            });
+            return { ...run, state, };
+        }
+        catch {
+            // The run started; a failed post-wait state probe must not lose the runId.
+            return run;
+        }
+    }
+    /** Request abort of a running macro run (204 response). */
+    async abort(runnableType, runId, projectKey) {
+        requireNonEmpty(runnableType, "runnableType");
+        requireNonEmpty(runId, "runId");
+        await this.client.post(`${this.base(runnableType, projectKey)}/abort/${encodeURIComponent(runId)}`, {});
+    }
+    /** Get the poll state of a macro run (running flag, progress, errors). */
+    async state(runnableType, runId, opts) {
+        requireNonEmpty(runnableType, "runnableType");
+        requireNonEmpty(runId, "runId");
+        const remainingMs = opts?.timeoutMs;
+        const raw = await this.client.get(`${this.base(runnableType, opts?.projectKey)}/state/${encodeURIComponent(runId)}`, ...(remainingMs !== undefined ? [{ timeoutMs: remainingMs, },] : []));
+        return this.client.safeParse(MacroStateSchema, raw, "macros.state");
+    }
+    /**
+     * Download the result of a macro run. Macro results are documents of the
+     * macro's declared `resultType` (HTML, text, JSON, …) and are frequently
+     * NOT JSON: the raw body is returned verbatim. JSON bodies are returned
+     * as parsed values so programmatic callers can read fields directly.
+     */
+    async result(runnableType, runId, opts) {
+        requireNonEmpty(runnableType, "runnableType");
+        requireNonEmpty(runId, "runId");
+        const maxBytes = macroResultMaxBytes(opts?.maxBytes);
+        const raw = await this.client.getTextLimited(`${this.base(runnableType, opts?.projectKey)}/result/${encodeURIComponent(runId)}`, maxBytes);
+        if (raw.truncated) {
+            throw new Error(`Macro result exceeded ${String(maxBytes)} bytes; retry with a larger maxBytes.`);
+        }
+        const text = raw.text;
+        const trimmed = text.trim();
+        if (trimmed.startsWith("{") && trimmed.endsWith("}")
+            || trimmed.startsWith("[") && trimmed.endsWith("]")) {
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                // Not JSON after all — fall through and return the text.
+            }
+        }
+        return text;
+    }
+    /**
+     * Run a macro and poll its state until it finishes or times out, using a
+     * bounded client-side loop on the state endpoint. Returns
+     * `{ success: false, timedOut: true }` on timeout rather than throwing.
+     */
+    async runAndWait(runnableType, opts) {
+        requireNonEmpty(runnableType, "runnableType");
+        // Validate the wait knobs BEFORE the run POST: an invalid budget must be
+        // a caller error, not a mutation whose wait behavior is undefined.
+        if (opts?.pollIntervalMs !== undefined) {
+            if (!Number.isFinite(opts.pollIntervalMs) || opts.pollIntervalMs < 1) {
+                throw new ClientValidationError("pollIntervalMs must be a finite number >= 1.");
+            }
+        }
+        if (opts?.timeoutMs !== undefined) {
+            if (!Number.isFinite(opts.timeoutMs) || opts.timeoutMs < 0) {
+                throw new ClientValidationError("timeoutMs must be a finite number >= 0.");
+            }
+        }
+        const baseIntervalMs = Math.max(1, opts?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+        const adaptivePolling = opts?.pollIntervalMs === undefined;
+        // One state observation always happens regardless of budget (poll
+        // precedes deadline check), but never round a budget up to a full poll.
+        const timeoutMs = Math.max(0, opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        const startedAt = Date.now();
+        const run = await this.run(runnableType, {
+            wait: false,
+            projectKey: opts?.projectKey,
+            params: opts?.params,
+            adminParams: opts?.adminParams,
+        });
+        const runId = run.runId;
+        let pollCount = 0;
+        let lastState;
+        const timedOutResult = (elapsedMs, state) => this.client.safeParse(MacroWaitResultSchema, {
+            runnableType,
+            runId,
+            running: true,
+            success: false,
+            timedOut: true,
+            elapsedMs,
+            pollCount,
+            ...(state ? { state, } : {}),
+        }, "macros.runAndWait");
+        while (true) {
+            pollCount += 1;
+            try {
+                lastState = await this.state(runnableType, runId, {
+                    projectKey: opts?.projectKey,
+                    timeoutMs: Math.max(1, timeoutMs - (Date.now() - startedAt)),
+                });
+            }
+            catch (error) {
+                if (!isRequestDeadlineError(error, startedAt + timeoutMs))
+                    throw error;
+                return timedOutResult(Date.now() - startedAt, lastState);
+            }
+            const running = lastState.running === true;
+            if (running !== true) {
+                return this.client.safeParse(MacroWaitResultSchema, {
+                    runnableType,
+                    runId,
+                    running: false,
+                    success: macroRunFailure(lastState) === undefined
+                        && lastState.exists !== false,
+                    elapsedMs: Date.now() - startedAt,
+                    pollCount,
+                    ...(macroRunFailure(lastState)
+                        ? { failure: macroRunFailure(lastState), }
+                        : {}),
+                    state: lastState,
+                }, "macros.runAndWait");
+            }
+            const elapsedMs = Date.now() - startedAt;
+            if (elapsedMs >= timeoutMs) {
+                return timedOutResult(elapsedMs, lastState);
+            }
+            const nextDelayMs = computeNextPollDelayMs({
+                pollCount,
+                baseIntervalMs,
+                adaptiveEnabled: adaptivePolling,
+            });
+            const { promise, resolve, } = Promise.withResolvers();
+            setTimeout(resolve, Math.min(nextDelayMs, Math.max(1, timeoutMs - (Date.now() - startedAt))));
+            await promise;
+        }
+    }
+    base(runnableType, projectKey) {
+        return `/public/api/projects/${this.enc(projectKey)}/runnables/${encodeURIComponent(runnableType)}`;
+    }
+}
+// Re-exported for CLI/plan use: failure extraction from a poll state record.
+export { isRecord as isMacroStateRecord, macroRunFailure, };

package/dist/src/resources/ml-tasks.d.ts

@@ -39,6 +39,19 @@ export interface MlTaskTrainOptions {
     sessionDescription?: string;
     runQueue?: boolean;
     wait?: boolean;
+    /**
+     * Deadline in milliseconds for the whole `wait` phase after DSS has
+     * accepted the training request. Validated before any request is sent:
+     * an invalid deadline must not start training work on the server.
+     * `timeoutMs: 0` disables waiting (single status check). Requires `wait`.
+     */
+    timeoutMs?: number;
+    /**
+     * Fixed poll interval in milliseconds for the training status loop.
+     * When omitted the loop backs off adaptively (doubles every 3 polls, capped).
+     * Requires `wait`.
+     */
+    pollIntervalMs?: number;
     projectKey?: string;
 }
 export interface MlTaskTrainingSession extends Record<string, unknown> {
@@ -48,7 +61,17 @@ export interface MlTaskTrainCompletedResult extends Record<string, unknown> {
     sessionId: string;
     trainedModelIds: string[];
 }
-export type MlTaskTrainResult = MlTaskTrainingSession | MlTaskTrainCompletedResult;
+/** Result returned when the training wait budget was exhausted. */
+export interface MlTaskTrainTimedOutResult extends Record<string, unknown> {
+    sessionId: string;
+    trainedModelIds: string[];
+    timedOut: true;
+    success: false;
+    state: "RUNNING";
+    elapsedMs: number;
+    pollCount: number;
+}
+export type MlTaskTrainResult = MlTaskTrainingSession | MlTaskTrainCompletedResult | MlTaskTrainTimedOutResult;
 export interface MlTrainedModelDetails extends Record<string, unknown> {
     id?: string;
     algorithm?: string;
@@ -77,7 +100,19 @@ export declare class MlTasksResource extends BaseResource {
     getSettings(analysisId: string, mlTaskId: string, projectKey?: string): Promise<MlTaskSettings>;
     /** Save the full settings object of an ML task. */
     saveSettings(analysisId: string, mlTaskId: string, settings: MlTaskSettings, projectKey?: string): Promise<MlTaskActionResult | undefined>;
-    /** Start training, optionally waiting for the task to finish. */
+    /**
+     * Start training, optionally waiting for the task to finish.
+     *
+     * `timeoutMs` is validated BEFORE the training POST: an invalid deadline
+     * never reaches the server, so bad input cannot start training work. Once
+     * DSS has accepted the training request, the deadline scopes only the
+     * wait phase — each status poll is issued with the remaining budget as a
+     * total request deadline, so a hung status request cannot outlast it.
+     *
+     * When the budget is exhausted the returned result keeps the documented
+     * success shape plus `timedOut: true` and `success: false` instead of
+     * throwing, so a caller can distinguish "still training" from "finished".
+     */
     train(opts: MlTaskTrainOptions): Promise<MlTaskTrainResult>;
     /** List identifiers for every trained model currently present on the task. */
     listTrainedModels(analysisId: string, mlTaskId: string, projectKey?: string): Promise<string[]>;

package/dist/src/resources/ml-tasks.js

@@ -1,12 +1,8 @@
-import { UsageError, } from "../cli/usage.js";
-import { BaseResource, } from "./base.js";
+import { ClientValidationError, } from "../errors.js";
+import { computeNextPollDelayMs, isRequestDeadlineError, } from "../utils/polling.js";
+import { BaseResource, requireNonEmpty, } from "./base.js";
 const TRAIN_POLL_INTERVAL_MS = 5_000;
-function requireNonEmpty(value, name) {
-    if (typeof value !== "string" || value.trim().length === 0) {
-        throw new UsageError(`${name} must be a non-empty string.`, "validation_failed");
-    }
-    return value;
-}
+const TRAIN_DEFAULT_TIMEOUT_MS = 120_000;
 function delay(ms) {
     const { promise, resolve, } = Promise.withResolvers();
     setTimeout(resolve, ms);
@@ -26,11 +22,11 @@ export class MlTasksResource extends BaseResource {
     /** Create a prediction or clustering task in an existing visual analysis. */
     async create(opts) {
         if (opts.taskType !== "PREDICTION" && opts.taskType !== "CLUSTERING") {
-            throw new UsageError("taskType must be PREDICTION or CLUSTERING.", "invalid_enum");
+            throw new ClientValidationError("taskType must be PREDICTION or CLUSTERING.", "invalid_enum");
         }
         if (opts.taskType === "PREDICTION"
             && (typeof opts.targetVariable !== "string" || opts.targetVariable.trim().length === 0)) {
-            throw new UsageError("targetVariable is required for PREDICTION ML tasks.", "missing_required_arg");
+            throw new ClientValidationError("targetVariable is required for PREDICTION ML tasks.", "missing_required_arg");
         }
         const analysisId = encodeURIComponent(requireNonEmpty(opts.analysisId, "analysisId"));
         const backendType = opts.backendType ?? "PY_MEMORY";
@@ -65,17 +61,49 @@ export class MlTasksResource extends BaseResource {
     /** Save the full settings object of an ML task. */
     async saveSettings(analysisId, mlTaskId, settings, projectKey) {
         if (settings === null || typeof settings !== "object" || Array.isArray(settings)) {
-            throw new UsageError("settings must be an object.", "validation_failed");
+            throw new ClientValidationError("settings must be an object.", "validation_failed");
         }
         return this.client.post(`${this.taskPath(analysisId, mlTaskId, projectKey)}/settings`, settings);
     }
-    /** Start training, optionally waiting for the task to finish. */
+    /**
+     * Start training, optionally waiting for the task to finish.
+     *
+     * `timeoutMs` is validated BEFORE the training POST: an invalid deadline
+     * never reaches the server, so bad input cannot start training work. Once
+     * DSS has accepted the training request, the deadline scopes only the
+     * wait phase — each status poll is issued with the remaining budget as a
+     * total request deadline, so a hung status request cannot outlast it.
+     *
+     * When the budget is exhausted the returned result keeps the documented
+     * success shape plus `timedOut: true` and `success: false` instead of
+     * throwing, so a caller can distinguish "still training" from "finished".
+     */
     async train(opts) {
         if (opts.sessionName !== undefined)
             requireNonEmpty(opts.sessionName, "sessionName");
         if (opts.sessionDescription !== undefined) {
             requireNonEmpty(opts.sessionDescription, "sessionDescription");
         }
+        // Deadline validation happens before any network request: a malformed
+        // budget must not start training work on the server.
+        const explicitIntervalMs = opts.pollIntervalMs;
+        if (explicitIntervalMs !== undefined && opts.wait !== true) {
+            throw new ClientValidationError("pollIntervalMs requires wait: true.", "validation_failed");
+        }
+        if (explicitIntervalMs !== undefined
+            && (!Number.isFinite(explicitIntervalMs) || explicitIntervalMs <= 0)) {
+            throw new ClientValidationError("pollIntervalMs must be a finite positive number.", "validation_failed");
+        }
+        let timeoutMs;
+        if (opts.timeoutMs !== undefined) {
+            if (opts.wait !== true) {
+                throw new ClientValidationError("timeoutMs requires wait: true.", "validation_failed");
+            }
+            if (!Number.isFinite(opts.timeoutMs) || opts.timeoutMs < 0) {
+                throw new ClientValidationError("timeoutMs must be a finite non-negative number.", "validation_failed");
+            }
+            timeoutMs = opts.timeoutMs;
+        }
         const taskPath = this.taskPath(opts.analysisId, opts.mlTaskId, opts.projectKey);
         const session = await this.client.post(`${taskPath}/train`, {
             sessionName: opts.sessionName,
@@ -84,15 +112,67 @@ export class MlTasksResource extends BaseResource {
         });
         if (opts.wait !== true)
             return session;
-        let status = await this.status(opts.analysisId, opts.mlTaskId, opts.projectKey);
-        while (status.training !== false) {
-            await delay(TRAIN_POLL_INTERVAL_MS);
-            status = await this.status(opts.analysisId, opts.mlTaskId, opts.projectKey);
+        const deadlineMs = timeoutMs ?? TRAIN_DEFAULT_TIMEOUT_MS;
+        const baseIntervalMs = Math.max(1, explicitIntervalMs ?? TRAIN_POLL_INTERVAL_MS);
+        const adaptiveEnabled = explicitIntervalMs === undefined;
+        const startedAt = Date.now();
+        let pollCount = 0;
+        // One status observation always happens; the poll precedes the deadline
+        // check, so `timeoutMs: 0` still reports the freshly-started state once.
+        while (true) {
+            pollCount += 1;
+            // One status observation always happens, even when the budget is
+            // already spent (the poll precedes the deadline check); only the
+            // requests issued while budget remains are bounded by the remaining
+            // time, so a stalled status endpoint can never defeat the deadline.
+            const remainingMs = deadlineMs - (Date.now() - startedAt);
+            let status;
+            try {
+                status = await this.client.get(`${this.taskPath(opts.analysisId, opts.mlTaskId, opts.projectKey)}/status`, remainingMs > 0
+                    ? { timeoutMs: remainingMs, }
+                    : undefined);
+            }
+            catch (error) {
+                // The poll budget ran out: report the structured timeout instead
+                // of letting the transport deadline error escape the loop.
+                if (!isRequestDeadlineError(error, startedAt + deadlineMs))
+                    throw error;
+                return {
+                    sessionId: session.sessionId,
+                    trainedModelIds: [],
+                    timedOut: true,
+                    success: false,
+                    state: "RUNNING",
+                    elapsedMs: Date.now() - startedAt,
+                    pollCount,
+                };
+            }
+            const elapsedMs = Date.now() - startedAt;
+            if (status.training !== false) {
+                if (elapsedMs >= deadlineMs) {
+                    return {
+                        sessionId: session.sessionId,
+                        trainedModelIds: modelIdsFromStatus(status),
+                        timedOut: true,
+                        success: false,
+                        state: "RUNNING",
+                        elapsedMs,
+                        pollCount,
+                    };
+                }
+                const nextDelayMs = computeNextPollDelayMs({
+                    pollCount,
+                    baseIntervalMs,
+                    adaptiveEnabled,
+                });
+                await delay(Math.min(nextDelayMs, deadlineMs - elapsedMs));
+                continue;
+            }
+            return {
+                sessionId: session.sessionId,
+                trainedModelIds: modelIdsFromStatus(status),
+            };
         }
-        return {
-            sessionId: session.sessionId,
-            trainedModelIds: modelIdsFromStatus(status),
-        };
     }
     /** List identifiers for every trained model currently present on the task. */
     async listTrainedModels(analysisId, mlTaskId, projectKey) {

package/dist/src/resources/model-evaluation-stores.js

@@ -1,11 +1,4 @@
-import { UsageError, } from "../cli/usage.js";
-import { BaseResource, } from "./base.js";
-function requireNonEmpty(value, name) {
-    if (typeof value !== "string" || value.trim().length === 0) {
-        throw new UsageError(`${name} must be a non-empty string.`, "validation_failed");
-    }
-    return value;
-}
+import { BaseResource, requireNonEmpty, } from "./base.js";
 export class ModelEvaluationStoresResource extends BaseResource {
     /** List model evaluation stores in a project. */
     async list(projectKey) {

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

@@ -7,6 +7,15 @@ export interface NotebookSaveResult {
     /** SHA-256 (hex) of the persisted content after a confirming re-read. */
     hash: string;
 }
+/**
+ * SQL-notebook save result. `id` is the persisted notebook identifier: on a
+ * create DSS allocates it server-side (a request-supplied `id` is rejected),
+ * so every later read, update, and delete must use this id — the requested
+ * handle only becomes the notebook's display name.
+ */
+export interface SqlNotebookSaveResult extends NotebookSaveResult {
+    id: string;
+}
 export interface SaveNotebookOptions {
     /** Reject the save when the stored content hash no longer matches. */
     expectHash?: string;
@@ -84,16 +93,43 @@ export declare class NotebooksResource extends BaseResource {
     listSql(projectKey?: string): Promise<SqlNotebookSummary[]>;
     /** Get the full content of a SQL notebook. */
     getSql(id: string, projectKey?: string): Promise<SqlNotebookContent>;
-    /** Create a SQL notebook. */
-    createSql(id: string, content: SqlNotebookContent, projectKey?: string): Promise<void>;
-    /** Save (overwrite) a SQL notebook's content. */
+    /**
+     * Create a SQL notebook.
+     *
+     * DSS allocates the notebook id server-side and rejects a request-supplied
+     * `id` (`Field 'id' is specified, it must not be specified`); `name` is
+     * the display handle (the requested label) when provided. The returned id
+     * comes from the creation receipt and is the only handle later reads,
+     * updates, and deletes may use.
+     */
+    createSql(content: SqlNotebookContent, projectKey?: string, opts?: {
+        name?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    /**
+     * Save (overwrite) a SQL notebook's content.
+     *
+     * Identity is positional: the URL id and the resolved project key are
+     * injected into the body, overriding any `id`/`projectKey` the content may
+     * carry, so a stale or hand-built body can never retarget the write. PUT
+     * is a full replacement — fields absent from the content (e.g. `name`)
+     * are cleared server-side.
+     */
     saveSql(id: string, content: SqlNotebookContent, projectKey?: string): Promise<void>;
     /**
-     * Save a SQL notebook, creating it when missing. Same contract as
-     * `saveOrCreateJupyter`: `created` reflects the fresh read, and `hash` is
-     * the hash of the persisted content from a confirming re-read.
+     * Save a SQL notebook, creating it when missing.
+     *
+     * Update path: the fresh read finds the notebook and a PUT overwrites it.
+     * Create path: DSS allocates the persisted id (the requested handle becomes
+     * the display name; there is no name-based re-lookup, so a foreign
+     * notebook can never be mistaken for the target), the id is returned, and
+     * every later read/update/delete must use that returned id. `created`
+     * reflects the fresh read; `hash` is the hash of the persisted content
+     * from a confirming re-read. The armed `--expect-hash` guard also refuses
+     * an absent target.
      */
-    saveOrCreateSql(id: string, content: SqlNotebookContent, projectKey?: string, opts?: SaveNotebookOptions): Promise<NotebookSaveResult>;
+    saveOrCreateSql(id: string, content: SqlNotebookContent, projectKey?: string, opts?: SaveNotebookOptions): Promise<SqlNotebookSaveResult>;
     /** Delete a SQL notebook. */
     deleteSql(id: string, projectKey?: string): Promise<void>;
     /** Get execution history for a SQL notebook (keyed by cell ID). */

package/dist/src/resources/notebooks.js

@@ -139,31 +139,71 @@ export class NotebooksResource extends BaseResource {
         const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/${idEnc}`);
         return this.client.safeParse(SqlNotebookContentSchema, raw, "notebooks.getSql");
     }
-    /** Create a SQL notebook. */
-    async createSql(id, content, projectKey) {
-        await this.client.post(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/`, { ...content, id, projectKey: this.resolveProjectKey(projectKey), });
+    /**
+     * Create a SQL notebook.
+     *
+     * DSS allocates the notebook id server-side and rejects a request-supplied
+     * `id` (`Field 'id' is specified, it must not be specified`); `name` is
+     * the display handle (the requested label) when provided. The returned id
+     * comes from the creation receipt and is the only handle later reads,
+     * updates, and deletes may use.
+     */
+    async createSql(content, projectKey, opts) {
+        const body = {
+            ...content,
+            projectKey: this.resolveProjectKey(projectKey),
+        };
+        // Positional identity only: a content-supplied id (e.g. a stale GET
+        // spread) is stripped before the request — DSS rejects it outright.
+        delete body["id"];
+        if (opts?.name !== undefined && body["name"] === undefined)
+            body["name"] = opts.name;
+        const raw = await this.client.post(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/`, body);
+        const record = raw !== null && typeof raw === "object" && !Array.isArray(raw)
+            ? raw
+            : undefined;
+        const id = record?.["id"];
+        if (typeof id !== "string" || id.length === 0) {
+            throw new DataikuError(200, "Unexpected Response", "notebooks.createSql: DSS did not return the generated notebook id.");
+        }
+        return { id, };
     }
-    /** Save (overwrite) a SQL notebook's content. */
+    /**
+     * Save (overwrite) a SQL notebook's content.
+     *
+     * Identity is positional: the URL id and the resolved project key are
+     * injected into the body, overriding any `id`/`projectKey` the content may
+     * carry, so a stale or hand-built body can never retarget the write. PUT
+     * is a full replacement — fields absent from the content (e.g. `name`)
+     * are cleared server-side.
+     */
     async saveSql(id, content, projectKey) {
         const idEnc = encodeURIComponent(id);
-        await this.client.putVoid(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/${idEnc}`, content);
+        await this.client.putVoid(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/${idEnc}`, { ...content, id, projectKey: this.resolveProjectKey(projectKey), });
     }
     /**
-     * Save a SQL notebook, creating it when missing. Same contract as
-     * `saveOrCreateJupyter`: `created` reflects the fresh read, and `hash` is
-     * the hash of the persisted content from a confirming re-read.
+     * Save a SQL notebook, creating it when missing.
+     *
+     * Update path: the fresh read finds the notebook and a PUT overwrites it.
+     * Create path: DSS allocates the persisted id (the requested handle becomes
+     * the display name; there is no name-based re-lookup, so a foreign
+     * notebook can never be mistaken for the target), the id is returned, and
+     * every later read/update/delete must use that returned id. `created`
+     * reflects the fresh read; `hash` is the hash of the persisted content
+     * from a confirming re-read. The armed `--expect-hash` guard also refuses
+     * an absent target.
      */
     async saveOrCreateSql(id, content, projectKey, opts) {
         const pk = this.resolveProjectKey(projectKey);
         const before = await this.prepareSave(() => this.getSql(id, pk), opts?.expectHash, pk, "SQL notebook", id);
         if (before === undefined) {
-            await this.createSql(id, content, pk);
-        }
-        else {
-            await this.saveSql(id, content, pk);
+            const created = await this.createSql(content, pk, { name: id, });
+            const persisted = await this.getSql(created.id, pk);
+            return { created: true, id: created.id, hash: stableHash(persisted), };
         }
+        await this.saveSql(id, content, pk);
         const persisted = await this.getSql(id, pk);
-        return { created: before === undefined, hash: stableHash(persisted), };
+        return { created: false, id, hash: stableHash(persisted), };
     }
     /** Delete a SQL notebook. */
     async deleteSql(id, projectKey) {