dataiku-sdk 3.6.1 → 3.8.0

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

@@ -68,11 +68,24 @@ export interface DoctorResult {
         tlsVerify: "strict" | "disabled";
         caCert: "default" | "custom";
     };
+    identity?: DoctorIdentity;
     permissions?: DoctorPermissions;
     permissionDetails?: Partial<Record<DoctorPermissionKey, Record<string, unknown>>>;
     fixtures?: DoctorFixtures;
     environment?: DoctorEnvironment;
 }
+/**
+ * The identity a DSS API key acts as, from `GET /public/api/auth/info`
+ * (no admin privilege required). Explains unexplained 403s: a personal key
+ * acts as its owner, a global key shows up as an `api:<id>` identity.
+ * Carries no secret material.
+ */
+export interface DoctorIdentity {
+    authSource?: string;
+    authIdentifier?: string;
+    groups?: string[];
+    userProfile?: string;
+}
 export declare function errorDetails(error: unknown): Record<string, unknown>;
 export declare function firstStringField(items: unknown[] | undefined, fields: string[]): string | null;
 export declare function integrationFlag(name: string): boolean;

package/dist/src/cli/doctor.js

@@ -11,6 +11,8 @@ export function errorDetails(error) {
             retryable: error.retryable,
             status: error.status,
             statusText: error.statusText,
+            message: error.message,
+            retryHint: error.retryHint,
         };
     }
     return { message: error instanceof Error ? error.message : String(error), };
@@ -49,6 +51,34 @@ export function doctorEnvironment(projectKey, versionInfo) {
         },
     };
 }
+/**
+ * Identity fields this doctor version reports, read from the documented
+ * `GET /public/api/auth/info` payload. Everything is optional: the field set
+ * varies across DSS versions and absent fields stay absent.
+ */
+function doctorIdentityFromAuthInfo(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    const groups = Array.isArray(record["groups"])
+        ? record["groups"].filter((g) => typeof g === "string")
+        : undefined;
+    const authSource = typeof record["authSource"] === "string" ? record["authSource"] : undefined;
+    const authIdentifier = typeof record["authIdentifier"] === "string"
+        ? record["authIdentifier"]
+        : undefined;
+    const userProfile = typeof record["userProfile"] === "string" ? record["userProfile"] : undefined;
+    if (authSource === undefined && authIdentifier === undefined && userProfile === undefined
+        && (groups === undefined || groups.length === 0)) {
+        return undefined;
+    }
+    return {
+        ...(authSource !== undefined ? { authSource, } : {}),
+        ...(authIdentifier !== undefined ? { authIdentifier, } : {}),
+        ...(groups !== undefined && groups.length > 0 ? { groups, } : {}),
+        ...(userProfile !== undefined ? { userProfile, } : {}),
+    };
+}
 export function permissionStatusForError(error) {
     if (error instanceof DataikuError) {
         if (error.status === 401 || error.status === 403 || error.status === 404)
@@ -261,6 +291,7 @@ export async function runDoctor(flags) {
     });
     let accessibleProjects;
     let environmentVersion;
+    let identity;
     if (credentialsOk) {
         const requestTimeoutMs = num(flags["request-timeout"], "--request-timeout");
         const retryMaxAttempts = num(flags["retries"], "--retries");
@@ -318,6 +349,12 @@ export async function runDoctor(flags) {
                 details: errorDetails(error),
             });
         }
+        // Which principal the key acts as (personal vs global key, groups) explains
+        // 403s on objects the user's UI profile can use. Diagnostic only: an
+        // unanswered /auth/info (older DSS) never fails doctor.
+        if (accessibleProjects) {
+            identity = await client.get("/public/api/auth/info").then(doctorIdentityFromAuthInfo, () => undefined);
+        }
         if (projectKey) {
             try {
                 const project = await client.projects.get(projectKey);
@@ -341,7 +378,12 @@ export async function runDoctor(flags) {
             }
         }
     }
-    const result = { ok: checks.every((check) => check.ok), checks, context, };
+    const result = {
+        ok: checks.every((check) => check.ok),
+        checks,
+        context,
+        ...(identity ? { identity, } : {}),
+    };
     if (flags["capabilities"] === true && credentialsOk) {
         const requestTimeoutMs = num(flags["request-timeout"], "--request-timeout");
         const retryMaxAttempts = num(flags["retries"], "--retries") ?? 1;

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

@@ -1,3 +1,9 @@
+/**
+ * Positional arguments scanned with the same flag grammar as `parseArgs`, so
+ * error reporting can recover the invoked resource/action without depending
+ * on the command registry being loaded.
+ */
+export declare function rawPositionals(argv: string[]): string[];
 /** Planning wins dispatch; dryRun remains set for combined plan metadata. */
 export declare function executionMode(flags: Record<string, string | boolean>): {
     readonly plan: boolean;
@@ -10,8 +16,15 @@ export declare const FLAG_ALIASES: Record<string, string>;
 export declare const VALUE_FLAGS: Set<string>;
 export declare const REPEATABLE_VALUE_FLAGS: Set<string>;
 export declare const KNOWN_LONG_FLAGS: Set<string>;
-export declare function normalizeLongFlag(rawFlagName: string): string;
+export declare function normalizeLongFlag(rawFlagName: string, argv: string[]): string;
 export declare function isNegativeNumberToken(value: string): boolean;
+/**
+ * Whether the token after a value flag is that flag's value rather than the
+ * next flag. `-` (stdin), negative numbers, and anything not flag-shaped
+ * qualify, so a SQL value beginning with a `-- comment` is a value; `--` alone
+ * and `--flag`/`--flag=x` are not.
+ */
+export declare function isFlagValueToken(token: string): boolean;
 export declare function requireFlagValue(flagLabel: string, next: string | undefined): string;
 export declare function setParsedFlagValue(flags: Record<string, string | boolean>, flagName: string, value: string): void;
 export interface ParsedArgs {

package/dist/src/cli/flags.js

@@ -1,5 +1,40 @@
 import { parseBooleanOption, } from "./coerce.js";
-import { unsupportedHelpFlag, UsageError, } from "./usage.js";
+import { unknownFlagError, unsupportedHelpFlag, UsageError, } from "./usage.js";
+/**
+ * Positional arguments scanned with the same flag grammar as `parseArgs`, so
+ * error reporting can recover the invoked resource/action without depending
+ * on the command registry being loaded.
+ */
+export function rawPositionals(argv) {
+    const positionals = [];
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === "--") {
+            positionals.push(...argv.slice(index + 1));
+            break;
+        }
+        if (arg.startsWith("--")) {
+            const name = arg.slice(2).split("=")[0] ?? "";
+            const canonical = FLAG_ALIASES[name] ?? name;
+            if (!arg.includes("=") && VALUE_FLAGS.has(canonical))
+                index++;
+            continue;
+        }
+        if (arg.length === 2 && arg[0] === "-" && arg[1] !== "-") {
+            const long = SHORT_FLAGS[arg[1]];
+            if (long && VALUE_FLAGS.has(long))
+                index++;
+            continue;
+        }
+        positionals.push(arg);
+    }
+    return positionals;
+}
+/** Unknown flags name the invoked command, so the error carries its usage line. */
+function commandUnknownFlagError(flagLabel, argv) {
+    const [resource, action,] = rawPositionals(argv);
+    return unknownFlagError(flagLabel, resource, action);
+}
 /** Planning wins dispatch; dryRun remains set for combined plan metadata. */
 export function executionMode(flags) {
     return {
@@ -31,15 +66,22 @@ export const BOOLEAN_FLAGS = new Set([
     "if-exists",
     "no-wait",
     "force-rebuild",
+    "auto-update-schema",
     "latest",
+    "full",
     "copy-output-settings",
     "copy-permissions",
     "continue-on-error",
     "no-backup",
+    "no-auto-rebuild",
+    "all-users",
+    "with-scenarios",
+    "for-everybody",
     "payload-only",
     "allow-same-path",
     "sync",
     "validate-objects",
+    "recreate-on-move",
     "errors-only",
     "keep",
     "full-log",
@@ -182,6 +224,8 @@ export const VALUE_FLAGS = new Set([
     "render",
     "prediction-type",
     "project-key",
+    "query",
+    "query-file",
     "recipe",
     "reference",
     "repository",
@@ -249,6 +293,37 @@ export const VALUE_FLAGS = new Set([
     "full-class-name",
     "include-libs",
     "archive",
+    "stop-at",
+    "mark-ok",
+    "template-file",
+    "group-by",
+    "aggregate",
+    "order-by",
+    "rename",
+    "fill-empty",
+    "formula",
+    "filter",
+    "drop-columns",
+    "keep-columns",
+    "columns",
+    "format-option",
+    "bundle-id",
+    "archive-path",
+    "project-folder",
+    "classes",
+    "version-id",
+    "evaluation-dataset",
+    "experiments",
+    "view-type",
+    "format",
+    "kind",
+    "features",
+    "sample-size",
+    "random-state",
+    "n-jobs",
+    "time-variable",
+    "timeseries-ids",
+    "full-reguess",
 ]);
 export const REPEATABLE_VALUE_FLAGS = new Set([
     "dataset",
@@ -269,21 +344,44 @@ export const KNOWN_LONG_FLAGS = new Set([
     ...Object.keys(FLAG_ALIASES),
     ...Object.values(FLAG_ALIASES),
 ]);
-export function normalizeLongFlag(rawFlagName) {
+export function normalizeLongFlag(rawFlagName, argv) {
     if (rawFlagName === "help")
         throw unsupportedHelpFlag();
     const flagName = FLAG_ALIASES[rawFlagName] ?? rawFlagName;
     if (!KNOWN_LONG_FLAGS.has(rawFlagName) && !KNOWN_LONG_FLAGS.has(flagName)) {
-        throw new UsageError(`Unknown flag: --${rawFlagName}`, "unknown_flag");
+        throw commandUnknownFlagError(`--${rawFlagName}`, argv);
     }
     return flagName;
 }
 export function isNegativeNumberToken(value) {
     return value.startsWith("-") && Number.isFinite(Number(value));
 }
+/** `--name` or `--name=value`: a token that parses as a long flag. */
+const LONG_FLAG_SHAPE = /^--[A-Za-z][A-Za-z0-9-]*(?:=|$)/;
+/**
+ * Whether the token after a value flag is that flag's value rather than the
+ * next flag. `-` (stdin), negative numbers, and anything not flag-shaped
+ * qualify, so a SQL value beginning with a `-- comment` is a value; `--` alone
+ * and `--flag`/`--flag=x` are not.
+ */
+export function isFlagValueToken(token) {
+    if (token === "-" || isNegativeNumberToken(token))
+        return true;
+    if (!token.startsWith("-"))
+        return true;
+    return token.startsWith("--") && token !== "--" && !LONG_FLAG_SHAPE.test(token);
+}
 export function requireFlagValue(flagLabel, next) {
-    if (next === undefined || (next !== "-" && next.startsWith("-") && !isNegativeNumberToken(next))) {
-        throw new UsageError(`Flag ${flagLabel} requires a value.`, "missing_required_flag");
+    if (next === undefined || !isFlagValueToken(next)) {
+        const inlineForm = flagLabel.startsWith("--") ? `${flagLabel}=VALUE` : undefined;
+        const hint = next === undefined || !next.startsWith("-")
+            ? undefined
+            : flagLabel === "--sql"
+                ? 'A SQL value that starts with `--` (a comment) can be passed as --sql="-- ...", from a file with --sql-file PATH, or on stdin with --stdin.'
+                : inlineForm
+                    ? `If the value itself starts with \`-\`, pass it as ${inlineForm}.`
+                    : undefined;
+        throw new UsageError(`Flag ${flagLabel} requires a value.`, "missing_required_flag", hint);
     }
     return next;
 }
@@ -309,7 +407,7 @@ export function parseArgs(argv) {
             const eqIdx = arg.indexOf("=");
             if (eqIdx !== -1) {
                 const raw = arg.slice(2, eqIdx);
-                const flagName = normalizeLongFlag(raw);
+                const flagName = normalizeLongFlag(raw, argv);
                 const value = arg.slice(eqIdx + 1);
                 if (BOOLEAN_FLAGS.has(flagName)) {
                     flags[flagName] = parseBooleanOption(value, `--${flagName}`);
@@ -320,7 +418,7 @@ export function parseArgs(argv) {
             }
             else {
                 const rawFlagName = arg.slice(2);
-                const flagName = normalizeLongFlag(rawFlagName);
+                const flagName = normalizeLongFlag(rawFlagName, argv);
                 if (BOOLEAN_FLAGS.has(flagName)) {
                     flags[flagName] = true;
                 }
@@ -346,7 +444,7 @@ export function parseArgs(argv) {
             else {
                 if (arg[1] === "h")
                     throw unsupportedHelpFlag();
-                throw new UsageError(`Unknown flag: -${arg[1]}`, "unknown_flag");
+                throw commandUnknownFlagError(`-${arg[1]}`, argv);
             }
         }
         else {

package/dist/src/cli/helpers/app-successor.js

@@ -1,4 +1,3 @@
-import { randomUUID, } from "node:crypto";
 import { DataikuError, } from "../../errors.js";
 import { projectIncarnationHash, } from "../../utils/project-incarnation.js";
 import { stableHash, stringField, } from "../coerce.js";
@@ -26,7 +25,7 @@ export const VISUAL_UI_GATE = {
  * probed for absence and is never retried under an alternate key.
  */
 export function generatedInstanceKey() {
-    return `APP_${randomUUID().replace(/-/g, "").toUpperCase()}`;
+    return `APP_${crypto.randomUUID().replace(/-/g, "").toUpperCase()}`;
 }
 /**
  * DSS answers the app-manifest probe with 400 ("neither an app template nor an

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

@@ -1,2 +1,14 @@
 import type { DatasetDetails } from "../../schemas.js";
+export interface DatasetSqlSourceFlags {
+    table?: string;
+    dbSchema?: string;
+    catalog?: string;
+    query?: string;
+}
+/**
+ * The SQL source of `dataset create` (`--table [--schema S] [--catalog C]` or
+ * `--query SQL`/`--query-file PATH`), validated against the dataset type.
+ * Empty when no SQL flag is given.
+ */
+export declare function datasetSqlSourceFromFlags(flags: Record<string, string | boolean>, dsType: string): DatasetSqlSourceFlags;
 export declare function datasetSourceSummary(details: DatasetDetails): Record<string, unknown>;

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

@@ -1,3 +1,39 @@
+import { assertSqlDatasetSource, } from "../../resources/dataset-create.js";
+import { readInputText, stripUtf8Bom, } from "../coerce.js";
+import { UsageError, } from "../usage.js";
+/**
+ * The SQL source of `dataset create` (`--table [--schema S] [--catalog C]` or
+ * `--query SQL`/`--query-file PATH`), validated against the dataset type.
+ * Empty when no SQL flag is given.
+ */
+export function datasetSqlSourceFromFlags(flags, dsType) {
+    const text = (flag) => {
+        const value = flags[flag];
+        if (value === undefined)
+            return undefined;
+        if (typeof value !== "string") {
+            throw new UsageError(`--${flag} requires a value.`, "missing_required_flag");
+        }
+        return value;
+    };
+    if (flags["query"] !== undefined && flags["query-file"] !== undefined) {
+        throw new UsageError("Conflicting input sources: --query, --query-file. Provide exactly one.", "conflicting_input_sources", undefined, { sources: ["query", "query-file",], });
+    }
+    const queryFile = text("query-file");
+    const inline = text("query");
+    const source = {
+        ...(text("table") !== undefined ? { table: text("table"), } : {}),
+        ...(text("schema") !== undefined ? { dbSchema: text("schema"), } : {}),
+        ...(text("catalog") !== undefined ? { catalog: text("catalog"), } : {}),
+        ...(queryFile !== undefined
+            ? { query: stripUtf8Bom(readInputText(queryFile, "--query-file")), }
+            : inline !== undefined
+                ? { query: inline, }
+                : {}),
+    };
+    assertSqlDatasetSource(dsType, source);
+    return source;
+}
 export function datasetSourceSummary(details) {
     const params = details.params ?? {};
     return {

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

@@ -0,0 +1,21 @@
+import type { DataikuClient } from "../../client.js";
+import type { DocumentationTemplate } from "../../resources/documentation.js";
+import type { DssTask, FutureWaitOptions } from "../../resources/futures.js";
+import type { FutureWaitResult } from "../../schemas.js";
+type Flags = Record<string, string | boolean>;
+/** Documentation template from flags: --template-file, or --folder with --path, or the DSS default. */
+export declare function documentationTemplateFromFlags(flags: Flags): DocumentationTemplate;
+/** `--poll-interval` / `--timeout` for commands that wait on a DSS task. */
+export declare function taskWaitOptions(flags: Flags): FutureWaitOptions;
+/**
+ * Shared `generate-documentation` flow: return the started task; with
+ * --wait, its final state; with --output PATH, wait and download the docx
+ * named by the result's `exportId`. A failed or timed-out generation carries
+ * no exportId, so its state is returned instead.
+ */
+export declare function runDocumentationCommand(client: DataikuClient, flags: Flags, task: DssTask, download: (exportId: string) => Promise<Response>): Promise<DssTask | FutureWaitResult | {
+    path: string;
+    bytes: number;
+    exportId: string;
+}>;
+export {};

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

@@ -0,0 +1,53 @@
+import { writeResponseToFile, } from "../../utils/response-file.js";
+import { num, } from "../coerce.js";
+import { UsageError, } from "../usage.js";
+/** Documentation template from flags: --template-file, or --folder with --path, or the DSS default. */
+export function documentationTemplateFromFlags(flags) {
+    const file = flags["template-file"];
+    const folder = flags["folder"];
+    const path = flags["path"];
+    if (typeof file === "string" && (folder !== undefined || path !== undefined)) {
+        throw new UsageError("Use either --template-file or --folder with --path, not both.", "conflicting_input_sources");
+    }
+    if (typeof file === "string")
+        return { kind: "file", filePath: file, };
+    if (typeof folder === "string" || typeof path === "string") {
+        if (typeof folder !== "string" || typeof path !== "string") {
+            throw new UsageError("A template in a managed folder needs both --folder FOLDER_ID and --path PATH.", "missing_required_flag");
+        }
+        return { kind: "folder", folderId: folder, path, };
+    }
+    return { kind: "default", };
+}
+/** `--poll-interval` / `--timeout` for commands that wait on a DSS task. */
+export function taskWaitOptions(flags) {
+    return {
+        pollIntervalMs: num(flags["poll-interval"], "--poll-interval"),
+        timeoutMs: num(flags["timeout"], "--timeout"),
+    };
+}
+/**
+ * Shared `generate-documentation` flow: return the started task; with
+ * --wait, its final state; with --output PATH, wait and download the docx
+ * named by the result's `exportId`. A failed or timed-out generation carries
+ * no exportId, so its state is returned instead.
+ */
+export async function runDocumentationCommand(client, flags, task, download) {
+    const output = flags["output"];
+    if (flags["wait"] !== true && typeof output !== "string")
+        return task;
+    const waited = await client.futures.waitTask(task, taskWaitOptions(flags));
+    if (typeof output !== "string")
+        return waited;
+    const result = waited.result;
+    const exportId = result && typeof result === "object" && "exportId" in result
+        ? result.exportId
+        : undefined;
+    if (typeof exportId !== "string")
+        return waited;
+    return {
+        path: output,
+        bytes: await writeResponseToFile(output, await download(exportId)),
+        exportId,
+    };
+}

package/dist/src/cli/helpers/flow-zone.d.ts

@@ -1,6 +1,7 @@
 import type { DataikuClient } from "../../client.js";
 import type { FlowZoneItemInput } from "../../resources/flow-zones.js";
 import type { FlowZone, FlowZoneObjectType, FlowZonePosition } from "../../schemas.js";
+import type { NormalizedFlowMap } from "../../utils/flow-map.js";
 export declare function flowZoneId(value: string): string;
 export declare function flowZoneName(value: string | boolean | undefined): string;
 export declare function flowZoneColor(value: string | boolean | undefined): string | undefined;
@@ -18,6 +19,8 @@ export interface FlowZoneOrganizeZonePlan {
     color?: string;
     position?: FlowZonePosition;
     items: FlowZoneItemInput[];
+    /** Recipe/output unit members added by {@link applyFlowZoneUnits}; also present in `items`. */
+    impliedItems?: FlowZoneItemInput[];
 }
 export interface FlowZoneOrganizePlan {
     topologyFingerprint?: string;
@@ -60,7 +63,25 @@ export declare function flowZoneExplicitItems(zone: FlowZone): FlowZoneItemInput
 export declare function flowZonePlanFromZones(zones: FlowZone[], topologyFingerprint: string): FlowZoneOrganizePlan;
 export declare function flowZoneMoveDelta(existing: FlowZone | undefined, plannedItems: FlowZoneItemInput[]): FlowZoneItemInput[];
 export declare function flowZonePruneItems(existing: FlowZone | undefined, plannedItemKeys: Set<string>): FlowZoneItemInput[];
+/**
+ * The position an existing zone must move to, if the plan changes it. DSS
+ * honors a zone position only on creation, so a move means recreating the zone.
+ */
+export declare function flowZoneRepositionTarget(plan: FlowZoneOrganizeZonePlan, existing: FlowZone): FlowZonePosition | undefined;
 export declare function flowZoneOrganizeStep(plan: FlowZoneOrganizeZonePlan, existing: FlowZone | undefined, sync: boolean, plannedItemKeys: Set<string>): Record<string, unknown>;
+/**
+ * Enforce the DSS recipe/output zone invariant on a plan. Rejects plans that
+ * place members of one unit in different zones (they would never converge),
+ * and adds the unlisted members of each planned unit to that zone as
+ * `impliedItems`, so moves, `--sync` pruning, and reruns all agree with what
+ * DSS actually does.
+ */
+export declare function applyFlowZoneUnits(plan: FlowZoneOrganizePlan, graph: NormalizedFlowMap, zones: FlowZone[], projectKey: string | undefined): FlowZoneOrganizePlan;
+/**
+ * Default-zone objects an organization plan has to place: recipes (their
+ * outputs follow) and objects no recipe produces, such as uploaded sources.
+ */
+export declare function flowZoneUnassignedItems(graph: NormalizedFlowMap, zones: FlowZone[]): FlowZoneItemInput[];
 export declare function flowZoneValidationBucket(index: FlowZoneOrganizeValidationIndex, objectType: FlowZoneObjectType): Set<string>;
 export declare function flowZoneValidationIndex(client: DataikuClient, projectKey: string | undefined): Promise<FlowZoneOrganizeValidationIndex>;
 export declare function validateFlowZoneOrganizeObjects(client: DataikuClient, plan: FlowZoneOrganizePlan, projectKey: string | undefined): Promise<FlowZoneOrganizeValidationResult>;