dataiku-sdk 3.2.0 → 3.3.0

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

@@ -48,10 +48,23 @@ export declare class WebappsResource extends BaseResource {
     /**
      * Start or restart a webapp backend. The documented endpoint returns a
      * reference to a future, which is surfaced as-is; settle it with
-     * {@link restartBackendAndWait} or `client.futures.wait`.
+     * {@link restartBackendAndWait} or `client.futures.wait`. DSS 15 returns
+     * an empty body (no future) when no async job was spawned — the official
+     * Python client tolerates that (`DSSFuture.from_resp` accepts a missing
+     * jobId), so an empty response surfaces as `{}` rather than crashing.
      */
     startOrRestartBackend(webappId: string, projectKey?: string): Promise<Record<string, unknown>>;
-    /** Restart a webapp backend and wait for the returned future to settle. */
+    /**
+     * Restart a webapp backend and wait for the returned future to settle.
+     * The documented endpoint returns a reference to a future; with a real
+     * jobId this polls that future to completion. An empty response carries
+     * NO future to wait on (observed on DSS 15 for a webapp whose backend is
+     * not enabled — a no-op restart, not a supported wait target), so the
+     * wait reports the missing future explicitly instead of fabricating a
+     * result for it. Enable the backend (params.backendEnabled with the
+     * params.python code, exactly as the DSS editor does) to get a real
+     * restart future.
+     */
     restartBackendAndWait(webappId: string, projectKey?: string, options?: WebappWaitOptions): Promise<FutureWaitResult>;
     /** Get a webapp backend's state. */
     getBackendState(webappId: string, projectKey?: string): Promise<Record<string, unknown>>;

package/dist/src/resources/webapps.js

@@ -59,18 +59,32 @@ export class WebappsResource extends BaseResource {
     /**
      * Start or restart a webapp backend. The documented endpoint returns a
      * reference to a future, which is surfaced as-is; settle it with
-     * {@link restartBackendAndWait} or `client.futures.wait`.
+     * {@link restartBackendAndWait} or `client.futures.wait`. DSS 15 returns
+     * an empty body (no future) when no async job was spawned — the official
+     * Python client tolerates that (`DSSFuture.from_resp` accepts a missing
+     * jobId), so an empty response surfaces as `{}` rather than crashing.
      */
     async startOrRestartBackend(webappId, projectKey) {
         const id = encodeURIComponent(webappId);
-        return this.client.put(`/public/api/projects/${this.enc(projectKey)}/webapps/${id}/backend/actions/restart`, {});
+        const future = await this.client.put(`/public/api/projects/${this.enc(projectKey)}/webapps/${id}/backend/actions/restart`, {});
+        return future ?? {};
     }
-    /** Restart a webapp backend and wait for the returned future to settle. */
+    /**
+     * Restart a webapp backend and wait for the returned future to settle.
+     * The documented endpoint returns a reference to a future; with a real
+     * jobId this polls that future to completion. An empty response carries
+     * NO future to wait on (observed on DSS 15 for a webapp whose backend is
+     * not enabled — a no-op restart, not a supported wait target), so the
+     * wait reports the missing future explicitly instead of fabricating a
+     * result for it. Enable the backend (params.backendEnabled with the
+     * params.python code, exactly as the DSS editor does) to get a real
+     * restart future.
+     */
     async restartBackendAndWait(webappId, projectKey, options = {}) {
         const future = await this.startOrRestartBackend(webappId, projectKey);
         const jobId = future.jobId;
         if (typeof jobId !== "string" || jobId.length === 0) {
-            throw new Error("Webapp backend restart did not return a future jobId.");
+            throw new ClientValidationError("Webapp backend restart returned no future jobId, so there is nothing to wait on.", "validation_failed", "The restart endpoint returns a future reference only when it starts an async job (a webapp with an enabled Python backend). Enable the backend before restarting with --wait.", { webappId, restartResponseKeys: Object.keys(future), });
         }
         return this.client.futures.wait(jobId, {
             pollIntervalMs: options.pollIntervalMs,

package/dist/src/schemas.d.ts

@@ -3,5 +3,5 @@
  * The types package (packages/types/) owns the TypeBox schema definitions.
  * SDK consumers get everything through this re-export.
  */
-export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvGetLogOptionsSchema, CodeEnvLogResultSchema, CodeEnvLogSummaryArraySchema, CodeEnvLogSummarySchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdateImagesOptionsSchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvVersionForProjectSchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZonePositionSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLibrarySchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagSchema, ProjectGitTagsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioStepRunSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookHistorySchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "../packages/types/src/index.js";
-export type { BuildMode, CodeEnvActionResult, CodeEnvCreateOptions, CodeEnvDetails, CodeEnvGetLogOptions, CodeEnvLogResult, CodeEnvLogSummary, CodeEnvPackageList, CodeEnvSetPackagesOptions, CodeEnvSummary, CodeEnvUpdateImagesOptions, CodeEnvUpdatePackagesOptions, CodeEnvUsage, CodeEnvVersionForProject, CodeEnvWaitOptions, ConnectionSummary, DashboardDetails, DashboardSummary, DataQualityComputeResult, DataQualityProjectStatus, DataQualityRule, DataQualityRuleResult, DataQualityRules, DataQualityStatus, DataQualityStatusByPartition, DataQualityTimeline, DataQualityTimelineEntry, DatasetCreateOptions, DatasetDetails, DatasetSchema, DatasetSummary, FlowMapOptions, FlowZone, FlowZoneCreateOptions, FlowZoneItem, FlowZoneObjectType, FlowZonePosition, FlowZoneUpdateOptions, FolderCreateOptions, FolderDetails, FolderItem, FolderSummary, FutureState, FutureWaitResult, InsightDetails, InsightSummary, JobSummary, JobWaitResult, JupyterCell, JupyterNotebookContent, JupyterNotebookSummary, NotebookSession, ProjectDetails, ProjectGitActionResult, ProjectGitDiffResult, ProjectGitFutureResponse, ProjectGitFutureState, ProjectGitLibraries, ProjectGitLibrary, ProjectGitLogResult, ProjectGitRemote, ProjectGitStatus, ProjectGitTag, ProjectGitTags, ProjectMetadata, ProjectSummary, ProjectVariables, RecipeCreateOptions, RecipeCreateResult, RecipeDetails, RecipeSummary, SafeParseResult, ScenarioDetails, ScenarioStatus, ScenarioStepRun, ScenarioSummary, ScenarioWaitResult, SqlNotebookCell, SqlNotebookContent, SqlNotebookHistory, SqlNotebookSummary, SqlQueryResponse, SqlQueryResult, SqlQuerySchema, WikiArticleData, WikiArticleMetadata, WikiSettings, WikiTaxonomyNode, } from "../packages/types/src/index.js";
+export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvGetLogOptionsSchema, CodeEnvLogResultSchema, CodeEnvLogSummaryArraySchema, CodeEnvLogSummarySchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdateImagesOptionsSchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvVersionForProjectSchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZonePositionSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, MacroDefinitionSchema, MacroRunStartSchema, MacroStateSchema, MacroSummaryArraySchema, MacroSummarySchema, MacroWaitResultSchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLibrarySchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagSchema, ProjectGitTagsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectTagsSchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioStepRunSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookHistorySchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "../packages/types/src/index.js";
+export type { BuildMode, CodeEnvActionResult, CodeEnvCreateOptions, CodeEnvDetails, CodeEnvGetLogOptions, CodeEnvLogResult, CodeEnvLogSummary, CodeEnvPackageList, CodeEnvSetPackagesOptions, CodeEnvSummary, CodeEnvUpdateImagesOptions, CodeEnvUpdatePackagesOptions, CodeEnvUsage, CodeEnvVersionForProject, CodeEnvWaitOptions, ConnectionSummary, DashboardDetails, DashboardSummary, DataQualityComputeResult, DataQualityProjectStatus, DataQualityRule, DataQualityRuleResult, DataQualityRules, DataQualityStatus, DataQualityStatusByPartition, DataQualityTimeline, DataQualityTimelineEntry, DatasetCreateOptions, DatasetDetails, DatasetSchema, DatasetSummary, FlowMapOptions, FlowZone, FlowZoneCreateOptions, FlowZoneItem, FlowZoneObjectType, FlowZonePosition, FlowZoneUpdateOptions, FolderCreateOptions, FolderDetails, FolderItem, FolderSummary, FutureState, FutureWaitResult, InsightDetails, InsightSummary, JobSummary, JobWaitResult, JupyterCell, JupyterNotebookContent, JupyterNotebookSummary, MacroDefinition, MacroRunStart, MacroState, MacroSummary, MacroSummaryArray, MacroWaitResult, NotebookSession, ProjectDetails, ProjectGitActionResult, ProjectGitDiffResult, ProjectGitFutureResponse, ProjectGitFutureState, ProjectGitLibraries, ProjectGitLibrary, ProjectGitLogResult, ProjectGitRemote, ProjectGitStatus, ProjectGitTag, ProjectGitTags, ProjectMetadata, ProjectSummary, ProjectTags, ProjectVariables, RecipeCreateOptions, RecipeCreateResult, RecipeDetails, RecipeSummary, SafeParseResult, ScenarioDetails, ScenarioStatus, ScenarioStepRun, ScenarioSummary, ScenarioWaitResult, SqlNotebookCell, SqlNotebookContent, SqlNotebookHistory, SqlNotebookSummary, SqlQueryResponse, SqlQueryResult, SqlQuerySchema, WikiArticleData, WikiArticleMetadata, WikiSettings, WikiTaxonomyNode, } from "../packages/types/src/index.js";

package/dist/src/schemas.js

@@ -3,4 +3,4 @@
  * The types package (packages/types/) owns the TypeBox schema definitions.
  * SDK consumers get everything through this re-export.
  */
-export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvGetLogOptionsSchema, CodeEnvLogResultSchema, CodeEnvLogSummaryArraySchema, CodeEnvLogSummarySchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdateImagesOptionsSchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvVersionForProjectSchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZonePositionSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLibrarySchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagSchema, ProjectGitTagsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioStepRunSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookHistorySchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "../packages/types/src/index.js";
+export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvGetLogOptionsSchema, CodeEnvLogResultSchema, CodeEnvLogSummaryArraySchema, CodeEnvLogSummarySchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdateImagesOptionsSchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvVersionForProjectSchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZonePositionSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, MacroDefinitionSchema, MacroRunStartSchema, MacroStateSchema, MacroSummaryArraySchema, MacroSummarySchema, MacroWaitResultSchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLibrarySchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagSchema, ProjectGitTagsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectTagsSchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioStepRunSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookHistorySchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "../packages/types/src/index.js";

package/dist/src/utils/deep-merge.d.ts

@@ -1 +1 @@
-export declare function deepMerge<T extends Record<string, unknown>>(base: T, patch: Record<string, unknown>): T;
+export declare function deepMerge<T extends object>(base: T, patch: Record<string, unknown>): T & Record<string, unknown>;

package/dist/src/utils/polling.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared polling helpers used by every long-running wait loop (jobs, futures,
+ * scenarios, macros, Visual ML training, Project Git futures).
+ */
+/** Hard ceiling for one adaptive backoff step (ms). */
+export declare const MAX_POLL_INTERVAL_MS = 10000;
+interface ComputeNextPollDelayMsOptions {
+    pollCount: number;
+    baseIntervalMs: number;
+    adaptiveEnabled: boolean;
+}
+/**
+ * Compute the next poll delay.
+ * When adaptive polling is enabled, the interval doubles every 3 polls,
+ * capped at MAX_POLL_INTERVAL_MS (or baseIntervalMs if it's larger).
+ */
+export declare function computeNextPollDelayMs({ pollCount, baseIntervalMs, adaptiveEnabled, }: ComputeNextPollDelayMsOptions): number;
+/** Distinguish an exhausted wait deadline from an earlier request timeout. */
+export declare function isRequestDeadlineError(error: unknown, deadlineAt: number): boolean;
+export {};

package/dist/src/utils/polling.js

@@ -0,0 +1,27 @@
+import { DataikuError, } from "../errors.js";
+/**
+ * Shared polling helpers used by every long-running wait loop (jobs, futures,
+ * scenarios, macros, Visual ML training, Project Git futures).
+ */
+/** Hard ceiling for one adaptive backoff step (ms). */
+export const MAX_POLL_INTERVAL_MS = 10_000;
+/**
+ * Compute the next poll delay.
+ * When adaptive polling is enabled, the interval doubles every 3 polls,
+ * capped at MAX_POLL_INTERVAL_MS (or baseIntervalMs if it's larger).
+ */
+export function computeNextPollDelayMs({ pollCount, baseIntervalMs, adaptiveEnabled, }) {
+    if (!adaptiveEnabled) {
+        return baseIntervalMs;
+    }
+    const step = Math.max(0, Math.floor((pollCount - 1) / 3));
+    const interval = baseIntervalMs * 2 ** step;
+    return Math.min(interval, Math.max(baseIntervalMs, MAX_POLL_INTERVAL_MS));
+}
+/** Distinguish an exhausted wait deadline from an earlier request timeout. */
+export function isRequestDeadlineError(error, deadlineAt) {
+    return Date.now() >= deadlineAt
+        && error instanceof DataikuError
+        && error.status === 0
+        && (error.retry?.timedOut === true || error.statusText === "Request Timeout");
+}

package/dist/src/utils/response-file.js

@@ -17,7 +17,7 @@ export async function writeResponseToFile(path, response, permissions = "private
             mode = 0o666 & ~process.umask();
         }
     }
-    const input = Readable.fromWeb(response.body);
+    const input = Readable.from(response.body, { objectMode: false, });
     const temporaryPath = join(dirname(path), `.${basename(path)}.tmp-${randomUUID()}`);
     const output = createWriteStream(temporaryPath, { flags: "wx", mode: 0o600, });
     try {

package/dist/src/utils/secret-sanitize.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared recursive secret sanitizer for CLI output and error surfaces.
+ *
+ * Walks any JSON-like value and:
+ * - replaces values under sensitive keys (per-domain key table) with `[redacted]`;
+ * - replaces exact occurrences of known secret values anywhere in strings;
+ * - optionally redacts userinfo embedded in HTTP(S) URL authorities
+ *   (`https://user:pass@host/...` -> `https://[redacted]@host/...`).
+ *
+ * The SDK resource layer forwards values verbatim to DSS over TLS; sanitization
+ * is a CLI presentation concern and must never leak secret material instead.
+ */
+/** Marker replacing every redacted value or secret occurrence. */
+export declare const SECRET_REDACTED = "[redacted]";
+/** Sensitive keys are matched after stripping `-`/`_` and lowercasing. */
+export declare function normalizeSecretKey(key: string): string;
+export interface SecretSanitizeOptions {
+    /**
+     * Per-domain table of sensitive keys (normalized form -> true). Policies
+     * deliberately differ between domains; never merge them.
+     */
+    sensitiveKeys: Record<string, true>;
+    /**
+     * Optional extra predicate over normalized keys for key families a flat
+     * table cannot express (e.g. the user `secrets` array).
+     */
+    isSensitiveKey?: (normalizedKey: string) => boolean;
+    /** Exact secret values to replace everywhere in strings. */
+    secrets?: string[];
+    /** Also redact userinfo embedded in HTTP(S) URL authorities. */
+    redactUrlUserinfo?: boolean;
+}
+/**
+ * Replace every exact occurrence of each secret so echoed errors cannot leak
+ * it. Empty secrets are skipped (an empty needle would corrupt every string).
+ */
+export declare function replaceSecrets(text: string, secrets: readonly string[]): string;
+/**
+ * Redact the userinfo of every HTTP(S) URL in a string. DSS may contain legacy
+ * remotes with credentials in the URL, and Git error text can echo them.
+ */
+export declare function redactUrlUserinfo(text: string): string;
+/**
+ * Recursively sanitize `value`: strings lose exact secret occurrences (and
+ * URL userinfo when enabled), objects redact values under sensitive keys and
+ * recurse, arrays recurse. Non-string scalars pass through unchanged.
+ */
+export declare function sanitizeSecrets<T>(value: T, options: SecretSanitizeOptions): T;
+/**
+ * Scrub secret material from an error's message, stack, and string body.
+ * `DataikuError.message` is built at construction, so all three carriers need
+ * the same string pass as output values.
+ */
+export declare function sanitizeErrorSecrets(error: unknown, options: SecretSanitizeOptions): unknown;

package/dist/src/utils/secret-sanitize.js

@@ -0,0 +1,101 @@
+/**
+ * Shared recursive secret sanitizer for CLI output and error surfaces.
+ *
+ * Walks any JSON-like value and:
+ * - replaces values under sensitive keys (per-domain key table) with `[redacted]`;
+ * - replaces exact occurrences of known secret values anywhere in strings;
+ * - optionally redacts userinfo embedded in HTTP(S) URL authorities
+ *   (`https://user:pass@host/...` -> `https://[redacted]@host/...`).
+ *
+ * The SDK resource layer forwards values verbatim to DSS over TLS; sanitization
+ * is a CLI presentation concern and must never leak secret material instead.
+ */
+/** Marker replacing every redacted value or secret occurrence. */
+export const SECRET_REDACTED = "[redacted]";
+/** Sensitive keys are matched after stripping `-`/`_` and lowercasing. */
+export function normalizeSecretKey(key) {
+    return key.replace(/[-_]/g, "").toLowerCase();
+}
+/**
+ * Replace every exact occurrence of each secret so echoed errors cannot leak
+ * it. Empty secrets are skipped (an empty needle would corrupt every string).
+ */
+export function replaceSecrets(text, secrets) {
+    let result = text;
+    for (const secret of secrets) {
+        if (secret !== "" && secret !== undefined && secret !== null) {
+            result = result.split(secret).join(SECRET_REDACTED);
+        }
+    }
+    return result;
+}
+/**
+ * Redact the userinfo of every HTTP(S) URL in a string. DSS may contain legacy
+ * remotes with credentials in the URL, and Git error text can echo them.
+ */
+export function redactUrlUserinfo(text) {
+    return text.replace(/https?:[\\/]{1,2}[^\s"'<>]+/giu, (url) => {
+        const schemeEnd = url.indexOf(":") + 1;
+        let authorityStart = schemeEnd;
+        while (url[authorityStart] === "/" || url[authorityStart] === "\\")
+            authorityStart++;
+        const slash = url.slice(authorityStart).search(/[\\/]/u);
+        const authorityEnd = slash === -1 ? url.length : authorityStart + slash;
+        const at = url.lastIndexOf("@", authorityEnd - 1);
+        if (at < authorityStart)
+            return url;
+        return `${url.slice(0, authorityStart)}${SECRET_REDACTED}@${url.slice(at + 1)}`;
+    });
+}
+/**
+ * Recursively sanitize `value`: strings lose exact secret occurrences (and
+ * URL userinfo when enabled), objects redact values under sensitive keys and
+ * recurse, arrays recurse. Non-string scalars pass through unchanged.
+ */
+export function sanitizeSecrets(value, options) {
+    const { secrets = [], } = options;
+    const stringPass = (text) => {
+        const sanitized = options.redactUrlUserinfo ? redactUrlUserinfo(text) : text;
+        return replaceSecrets(sanitized, secrets);
+    };
+    if (typeof value === "string") {
+        return stringPass(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeSecrets(item, options));
+    }
+    if (value !== null && typeof value === "object") {
+        const sanitized = {};
+        for (const [key, item,] of Object.entries(value)) {
+            const normalizedKey = normalizeSecretKey(key);
+            sanitized[key] = options.sensitiveKeys[normalizedKey] === true
+                || options.isSensitiveKey?.(normalizedKey) === true
+                ? SECRET_REDACTED
+                : sanitizeSecrets(item, options);
+        }
+        return sanitized;
+    }
+    return value;
+}
+/**
+ * Scrub secret material from an error's message, stack, and string body.
+ * `DataikuError.message` is built at construction, so all three carriers need
+ * the same string pass as output values.
+ */
+export function sanitizeErrorSecrets(error, options) {
+    if (!(error instanceof Error))
+        return error;
+    const stringPass = (text) => {
+        const sanitized = options.redactUrlUserinfo ? redactUrlUserinfo(text) : text;
+        return replaceSecrets(sanitized, options.secrets ?? []);
+    };
+    error.message = stringPass(error.message);
+    if (typeof error.stack === "string") {
+        error.stack = stringPass(error.stack);
+    }
+    const errorWithBody = error;
+    if (typeof errorWithBody.body === "string") {
+        errorWithBody.body = stringPass(errorWithBody.body);
+    }
+    return error;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dataiku-sdk",
-	"version": "3.2.0",
+	"version": "3.3.0",
 	"description": "Dataiku DSS SDK and CLI for programmatic access to DSS REST APIs",
 	"type": "module",
 	"workspaces": [
@@ -25,10 +25,10 @@
 		"build": "tsc && bun scripts/generate-build-metadata.mjs && tsc -p packages/types/tsconfig.json",
 		"prepack": "bun scripts/sync-plugin-version.mjs --check && tsc && bun scripts/generate-build-metadata.mjs && tsc -p packages/types/tsconfig.json",
 		"prepublishOnly": "bun scripts/sync-plugin-version.mjs --check && tsc && bun scripts/generate-build-metadata.mjs && tsc -p packages/types/tsconfig.json",
-		"check": "tsc --noEmit && bun run check:live && bun scripts/sync-plugin-version.mjs --check",
+		"check": "tsc --noEmit && tsc -p tools/oxlint/tsconfig.json && bun run check:live && bun scripts/sync-plugin-version.mjs --check",
 		"version": "bun scripts/sync-plugin-version.mjs && git add plugin.json",
-		"lint": "oxlint src/ scripts/live-suite.ts tests/live-*.ts",
-		"lint:fix": "oxlint --fix src/ scripts/live-suite.ts tests/live-*.ts",
+		"lint": "oxlint src/ tools/oxlint/ scripts/live-suite.ts tests/live-*.ts",
+		"lint:fix": "oxlint --fix src/ tools/oxlint/ scripts/live-suite.ts tests/live-*.ts",
 		"format": "dprint fmt",
 		"format:check": "dprint check",
 		"test": "bun test",
@@ -42,11 +42,12 @@
 		"test:integration:rigorous:mutating": "cross-env RUN_DATAIKU_INTEGRATION=1 RUN_DATAIKU_INTEGRATION_MUTATING=1 bun test tests/integration-rigorous.test.ts"
 	},
 	"devDependencies": {
+		"@oxlint/plugins": "1.81.0",
 		"@types/bun": "^1.4.0",
 		"cross-env": "^10.1.0",
 		"dprint": "^0.57.0",
 		"js-tiktoken": "1.0.21",
-		"oxlint": "^1.81.0",
+		"oxlint": "1.81.0",
 		"typescript": "^7.0.2",
 		"typescript-language-server": "6.0.0",
 		"typescript-language-service": "npm:typescript@5.9.3"

package/packages/types/dist/index.d.ts

@@ -59,6 +59,12 @@ export declare const ProjectMetadataSchema: import("@sinclair/typebox").TObject<
     }>>;
 }>;
 export type ProjectMetadata = Static<typeof ProjectMetadataSchema>;
+export declare const ProjectTagsSchema: import("@sinclair/typebox").TObject<{
+    tags: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
+        color: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>;
+}>;
+export type ProjectTags = Static<typeof ProjectTagsSchema>;
 export declare const DatasetSummarySchema: import("@sinclair/typebox").TObject<{
     name: import("@sinclair/typebox").TString;
     type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -308,6 +314,85 @@ export declare const ScenarioWaitResultSchema: import("@sinclair/typebox").TObje
     }>>>;
 }>;
 export type ScenarioWaitResult = Static<typeof ScenarioWaitResultSchema>;
+/** A macro definition as returned by GET /projects/{pk}/runnables/{runnableType}. */
+export declare const MacroDefinitionSchema: import("@sinclair/typebox").TObject<{
+    runnableType: import("@sinclair/typebox").TString;
+    ownerPluginId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    meta: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        label: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>;
+    longDescription: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    resultType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    extension: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    mimeType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    resultLabel: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    params: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        name: import("@sinclair/typebox").TString;
+        type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>>;
+    adminParams: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnknown>>;
+}>;
+export type MacroDefinition = Static<typeof MacroDefinitionSchema>;
+/** One entry of GET /projects/{pk}/runnables (array[Macro]). */
+export declare const MacroSummarySchema: import("@sinclair/typebox").TObject<{
+    runnableType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /** Owning plugin id as the server returns it (live identifiers are server-authored). */
+    ownerPluginId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    meta: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        label: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>;
+}>;
+export type MacroSummary = Static<typeof MacroSummarySchema>;
+export declare const MacroSummaryArraySchema: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+    runnableType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /** Owning plugin id as the server returns it (live identifiers are server-authored). */
+    ownerPluginId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    meta: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        label: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>;
+}>>;
+export type MacroSummaryArray = Static<typeof MacroSummaryArraySchema>;
+/**
+ * Poll-state response of GET /projects/{pk}/runnables/{runnableType}/state/{run}.
+ * While running: `running: true` and optionally a stack of `progress` entries.
+ * When finished: `running: false`; on failure `resultError`/`storedError` carry
+ * details, otherwise `type` is filled.
+ */
+export declare const MacroStateSchema: import("@sinclair/typebox").TObject<{
+    exists: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    running: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    empty: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    progress: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+    resultError: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+    storedError: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+}>;
+export type MacroState = Static<typeof MacroStateSchema>;
+/** Run trigger response of POST /projects/{pk}/runnables/{runnableType}. */
+export declare const MacroRunStartSchema: import("@sinclair/typebox").TObject<{
+    runId: import("@sinclair/typebox").TString;
+}>;
+export type MacroRunStart = Static<typeof MacroRunStartSchema>;
+/** Result of {@link MacrosResource.runAndWait}: bounded client-side polling. */
+export declare const MacroWaitResultSchema: import("@sinclair/typebox").TObject<{
+    runnableType: import("@sinclair/typebox").TString;
+    runId: import("@sinclair/typebox").TString;
+    running: import("@sinclair/typebox").TBoolean;
+    success: import("@sinclair/typebox").TBoolean;
+    elapsedMs: import("@sinclair/typebox").TNumber;
+    pollCount: import("@sinclair/typebox").TNumber;
+    timedOut: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    state: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        exists: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        running: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        empty: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        progress: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+        resultError: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+        storedError: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+    }>>;
+}>;
+export type MacroWaitResult = Static<typeof MacroWaitResultSchema>;
 export declare const FlowZoneObjectTypeSchema: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"DATASET">, import("@sinclair/typebox").TLiteral<"MANAGED_FOLDER">, import("@sinclair/typebox").TLiteral<"SAVED_MODEL">, import("@sinclair/typebox").TLiteral<"RECIPE">, import("@sinclair/typebox").TLiteral<"MODEL_EVALUATION_STORE">, import("@sinclair/typebox").TLiteral<"STREAMING_ENDPOINT">, import("@sinclair/typebox").TLiteral<"LABELING_TASK">, import("@sinclair/typebox").TLiteral<"RETRIEVABLE_KNOWLEDGE">]>;
 export type FlowZoneObjectType = Static<typeof FlowZoneObjectTypeSchema>;
 export declare const FlowZoneItemSchema: import("@sinclair/typebox").TObject<{
@@ -658,6 +743,11 @@ export declare const SqlNotebookCellSchema: import("@sinclair/typebox").TObject<
     id: import("@sinclair/typebox").TString;
     type: import("@sinclair/typebox").TString;
     name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /**
+     * Cell source. DSS enforces a JSON string here: an array fails to parse
+     * server-side (`Expected a string but was BEGIN_ARRAY ... $.cells[0].code`),
+     * so the official-client example's line-array form does not apply to SQL.
+     */
     code: import("@sinclair/typebox").TString;
 }>;
 export type SqlNotebookCell = Static<typeof SqlNotebookCellSchema>;
@@ -668,12 +758,24 @@ export declare const SqlNotebookSummarySchema: import("@sinclair/typebox").TObje
     connection: import("@sinclair/typebox").TString;
 }>;
 export type SqlNotebookSummary = Static<typeof SqlNotebookSummarySchema>;
+/**
+ * A SQL notebook's content as returned by GET. The notebook record carries
+ * the server-allocated `id` (a request-supplied `id` is rejected on create)
+ * plus `name`/`projectKey`/`isRunning` and similar receipt fields via
+ * `additionalProperties`; requests supply `connection` + `cells` (and
+ * optionally `name` as the display handle).
+ */
 export declare const SqlNotebookContentSchema: import("@sinclair/typebox").TObject<{
     connection: import("@sinclair/typebox").TString;
     cells: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
         id: import("@sinclair/typebox").TString;
         type: import("@sinclair/typebox").TString;
         name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        /**
+         * Cell source. DSS enforces a JSON string here: an array fails to parse
+         * server-side (`Expected a string but was BEGIN_ARRAY ... $.cells[0].code`),
+         * so the official-client example's line-array form does not apply to SQL.
+         */
         code: import("@sinclair/typebox").TString;
     }>>;
 }>;

package/packages/types/dist/index.js

@@ -113,6 +113,9 @@ export const ProjectMetadataSchema = Type.Object({
         }, { additionalProperties: true, }))),
     }, { additionalProperties: true, })),
 }, { additionalProperties: true, });
+export const ProjectTagsSchema = Type.Object({
+    tags: Type.Record(Type.String(), Type.Object({ color: Type.Optional(Type.String()), }, { additionalProperties: true, }), { additionalProperties: true, }),
+}, { additionalProperties: true, });
 // ---------------------------------------------------------------------------
 // Datasets
 // ---------------------------------------------------------------------------
@@ -347,6 +350,67 @@ export const ScenarioWaitResultSchema = Type.Object({
     steps: Type.Optional(Type.Array(ScenarioStepRunSchema)),
 });
 // ---------------------------------------------------------------------------
+// Macros (runnables)
+// ---------------------------------------------------------------------------
+/** A macro definition as returned by GET /projects/{pk}/runnables/{runnableType}. */
+export const MacroDefinitionSchema = Type.Object({
+    runnableType: Type.String(),
+    ownerPluginId: Type.Optional(Type.String()),
+    meta: Type.Optional(Type.Object({
+        label: Type.Optional(Type.String()),
+    }, { additionalProperties: true, })),
+    longDescription: Type.Optional(Type.String()),
+    resultType: Type.Optional(Type.String()),
+    extension: Type.Optional(Type.String()),
+    mimeType: Type.Optional(Type.String()),
+    resultLabel: Type.Optional(Type.String()),
+    params: Type.Optional(Type.Array(Type.Object({
+        name: Type.String(),
+        type: Type.Optional(Type.String()),
+    }, { additionalProperties: true, }))),
+    adminParams: Type.Optional(Type.Array(Type.Unknown())),
+}, { additionalProperties: true, });
+/** One entry of GET /projects/{pk}/runnables (array[Macro]). */
+export const MacroSummarySchema = Type.Object({
+    runnableType: Type.Optional(Type.String()),
+    /** Owning plugin id as the server returns it (live identifiers are server-authored). */
+    ownerPluginId: Type.Optional(Type.String()),
+    meta: Type.Optional(Type.Object({
+        label: Type.Optional(Type.String()),
+    }, { additionalProperties: true, })),
+}, { additionalProperties: true, });
+export const MacroSummaryArraySchema = Type.Array(MacroSummarySchema);
+/**
+ * Poll-state response of GET /projects/{pk}/runnables/{runnableType}/state/{run}.
+ * While running: `running: true` and optionally a stack of `progress` entries.
+ * When finished: `running: false`; on failure `resultError`/`storedError` carry
+ * details, otherwise `type` is filled.
+ */
+export const MacroStateSchema = Type.Object({
+    exists: Type.Optional(Type.Boolean()),
+    running: Type.Optional(Type.Boolean()),
+    empty: Type.Optional(Type.Boolean()),
+    type: Type.Optional(Type.String()),
+    progress: Type.Optional(Type.Unknown()),
+    resultError: Type.Optional(Type.Unknown()),
+    storedError: Type.Optional(Type.Unknown()),
+}, { additionalProperties: true, });
+/** Run trigger response of POST /projects/{pk}/runnables/{runnableType}. */
+export const MacroRunStartSchema = Type.Object({
+    runId: Type.String(),
+}, { additionalProperties: true, });
+/** Result of {@link MacrosResource.runAndWait}: bounded client-side polling. */
+export const MacroWaitResultSchema = Type.Object({
+    runnableType: Type.String(),
+    runId: Type.String(),
+    running: Type.Boolean(),
+    success: Type.Boolean(),
+    elapsedMs: Type.Number(),
+    pollCount: Type.Number(),
+    timedOut: Type.Optional(Type.Boolean()),
+    state: Type.Optional(MacroStateSchema),
+}, { additionalProperties: true, });
+// ---------------------------------------------------------------------------
 // Flow zones
 // ---------------------------------------------------------------------------
 export const FlowZoneObjectTypeSchema = Type.Union([
@@ -631,6 +695,11 @@ export const SqlNotebookCellSchema = Type.Object({
     id: Type.String(),
     type: Type.String(),
     name: Type.Optional(Type.String()),
+    /**
+     * Cell source. DSS enforces a JSON string here: an array fails to parse
+     * server-side (`Expected a string but was BEGIN_ARRAY ... $.cells[0].code`),
+     * so the official-client example's line-array form does not apply to SQL.
+     */
     code: Type.String(),
 }, { additionalProperties: true, });
 export const SqlNotebookSummarySchema = Type.Object({
@@ -639,6 +708,13 @@ export const SqlNotebookSummarySchema = Type.Object({
     language: Type.String(),
     connection: Type.String(),
 }, { additionalProperties: true, });
+/**
+ * A SQL notebook's content as returned by GET. The notebook record carries
+ * the server-allocated `id` (a request-supplied `id` is rejected on create)
+ * plus `name`/`projectKey`/`isRunning` and similar receipt fields via
+ * `additionalProperties`; requests supply `connection` + `cells` (and
+ * optionally `name` as the display handle).
+ */
 export const SqlNotebookContentSchema = Type.Object({
     connection: Type.String(),
     cells: Type.Array(SqlNotebookCellSchema),

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "dataiku-sdk",
-	"version": "3.2.0",
+	"version": "3.3.0",
 	"description": "Dataiku DSS SDK and agent-oriented CLI for programmatic access to DSS REST APIs.",
 	"homepage": "https://github.com/clssck/dataiku-sdk",
 	"repository": "https://github.com/clssck/dataiku-sdk",

package/skills/dataiku-dss/SKILL.md

@@ -21,13 +21,15 @@ Bootstrap once:
 ```text
 dss agent contract --fields protocol,agentContractVersion,cli,stdio,planning,compatibility
 ```
-Find actions: `dss commands run`. Before invoking, discover exact syntax:
+Known resource: `dss agent contract --fields commands.actions.dataset`; otherwise `dss commands run`.
+For reads, discover compact syntax:
 ```text
-dss commands run --fields dataset.create.usage,dataset.create.description,dataset.create.flags,dataset.create.examples
+dss commands run --fields dataset.preview.usage,dataset.preview.description,dataset.preview.flags,dataset.preview.examples
 ```
-Use `--fields RESOURCE.ACTION` for payload schemas, side effects, auth, idempotency,
-dry-run, cleanup, or output details. Combine paths in one request. Never load the full
-registry into context; export only if needed: `dss commands run --output commands.json`.
+For writes, fetch `--fields RESOURCE.ACTION` once, directly: the full entry includes
+syntax, payload schemas, side effects, auth, idempotency, dry-run, cleanup, and output.
+Combine paths in one request. Never load the full registry into context; export only
+if needed: `dss commands run --output commands.json`.
 
 ## Safety and results