dataiku-sdk 0.10.0 → 0.11.0

package/dist/src/cli/output.js

@@ -0,0 +1,159 @@
+import { DataikuError, } from "../errors.js";
+let outputFieldProjection;
+export function setOutputFieldProjection(fields) {
+    outputFieldProjection = fields;
+}
+/**
+ * Non-fatal diagnostics queued during a command and flushed to stderr as one
+ * JSON envelope, so agents get a loud, machine-parseable signal (e.g. truncated
+ * exports) without polluting the stdout result contract.
+ */
+let pendingCliWarnings = [];
+export function enqueueCliWarning(warning) {
+    pendingCliWarnings.push(warning);
+}
+/** Emit queued warnings as one JSONL warning event on stderr. Idempotent. */
+function flushCliWarnings() {
+    if (pendingCliWarnings.length === 0)
+        return;
+    const warnings = pendingCliWarnings;
+    pendingCliWarnings = [];
+    process.stderr.write(`${JSON.stringify({ type: "warning", warnings, })}\n`);
+}
+function resolveFieldPath(source, field) {
+    let current = source;
+    for (const segment of field.split(".")) {
+        if (current === null || typeof current !== "object" || Array.isArray(current))
+            return null;
+        current = current[segment];
+    }
+    return current ?? null;
+}
+export function pickResultFields(item, fields) {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+        return item;
+    const source = item;
+    const picked = {};
+    for (const field of fields)
+        picked[field] = resolveFieldPath(source, field);
+    return picked;
+}
+/**
+ * Project the top-level fields callers asked for via --fields. Arrays are mapped
+ * element-wise; scalars and string results pass through untouched. Requested keys
+ * that are absent become null so every row keeps a stable, predictable shape.
+ */
+export function projectResultFields(result, fields) {
+    if (Array.isArray(result))
+        return result.map((item) => pickResultFields(item, fields));
+    return pickResultFields(result, fields);
+}
+export function writeCommandResult(result) {
+    flushCliWarnings();
+    const projected = outputFieldProjection
+        ? projectResultFields(result, outputFieldProjection)
+        : result;
+    process.stdout.write(`${JSON.stringify(projected ?? { ok: true, }, null, 2)}\n`);
+}
+export function transientBodyWithTargetContext(body, target, elapsedMs) {
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const record = parsed;
+            const message = typeof record.message === "string" && record.message.length > 0
+                ? `Target: ${target}\nElapsed: ${elapsedMs}ms\n${record.message}`
+                : `Target: ${target}\nElapsed: ${elapsedMs}ms`;
+            return JSON.stringify({ ...record, message, target, elapsedMs, });
+        }
+    }
+    catch {
+        // Non-JSON DSS bodies are wrapped as text below.
+    }
+    return `Target: ${target}\nElapsed: ${elapsedMs}ms\n${body}`;
+}
+export function addTransientTargetContext(error, target, elapsedMs) {
+    if (error instanceof DataikuError && error.category === "transient") {
+        throw new DataikuError(error.status, error.statusText, transientBodyWithTargetContext(error.body, target, elapsedMs), error.retry, error.requestId);
+    }
+    throw error;
+}
+export function isFailedWaitResult(result) {
+    if (result === null || typeof result !== "object" || Array.isArray(result))
+        return false;
+    const record = result;
+    return record.success === false
+        && typeof record.elapsedMs === "number"
+        && typeof record.pollCount === "number"
+        && (typeof record.state === "string" || typeof record.outcome === "string");
+}
+export function commandFailureExitCode(result) {
+    if (isFailedWaitResult(result))
+        return 4;
+    if (result && typeof result === "object" && result.unchanged === false)
+        return 4;
+    return undefined;
+}
+export class CommandResultFailure extends Error {
+    result;
+    exitCode;
+    constructor(result, exitCode) {
+        super(commandFailureMessage(result));
+        this.name = "CommandResultFailure";
+        this.result = result;
+        this.exitCode = exitCode;
+    }
+}
+export function commandFailureMessage(result) {
+    if (isFailedWaitResult(result)) {
+        const record = result;
+        const state = typeof record.state === "string" ? record.state : record.outcome;
+        return `Command completed with failed long-running result${state ? `: ${state}` : ""}.`;
+    }
+    if (result && typeof result === "object" && result.unchanged === false) {
+        return "Command completed with failed assertion result.";
+    }
+    return "Command completed with failed result.";
+}
+export function isNotFoundError(error) {
+    if (error instanceof DataikuError)
+        return error.category === "not_found";
+    if (error instanceof Error)
+        return /not found|does not exist|unknown/i.test(error.message);
+    return false;
+}
+export async function readIfExists(reader) {
+    try {
+        return await reader();
+    }
+    catch (error) {
+        if (isNotFoundError(error))
+            return undefined;
+        throw error;
+    }
+}
+export function skipResult(resource, id, reason, extra = {}) {
+    return { skipped: id, reason, resource, ...extra, };
+}
+export function planResult(resource, action, options) {
+    return {
+        plan: true,
+        action,
+        resource,
+        ...(options.plannedAndDryRun ? { plannedAndDryRun: true, } : {}),
+        ...options.identifiers,
+        ...(options.method ? { method: options.method, } : {}),
+        ...(options.endpoint ? { endpoint: options.endpoint, } : {}),
+        ...(options.payload !== undefined ? { payload: options.payload, } : {}),
+        ...(options.localWrites !== undefined ? { localWrites: options.localWrites, } : {}),
+        ...(options.wait !== undefined ? { wait: options.wait, } : {}),
+        idempotency: options.idempotency,
+        async: options.asyncKind,
+        exitCodesOnFailure: options.exitCodesOnFailure,
+    };
+}
+export function encodedProjectEndpoint(client, projectKey, suffix) {
+    return `/public/api/projects/${encodeURIComponent(client.resolveProjectKey(projectKey))}${suffix}`;
+}
+export function encodedProjectEndpointForPlan(projectKey, suffix) {
+    return `/public/api/projects/${encodeURIComponent(projectKey)}${suffix}`;
+}

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

@@ -0,0 +1,15 @@
+import { type DssCredentials } from "../config.js";
+export type TlsSettings = Pick<DssCredentials, "tlsRejectUnauthorized" | "caCertPath">;
+export declare function resolveTlsSettings(flags: Record<string, string | boolean>, saved?: TlsSettings): TlsSettings;
+export declare const currentCommandContext: {
+    resource?: string;
+    action?: string;
+    projectKey?: string;
+};
+export declare function resolveCredentials(flags: Record<string, string | boolean>): {
+    url: string;
+    apiKey: string;
+    projectKey?: string;
+    tlsRejectUnauthorized?: boolean;
+    caCertPath?: string;
+};

package/dist/src/cli/runtime.js

@@ -0,0 +1,59 @@
+import { loadCredentials, } from "../config.js";
+import { dataikuEnvironmentEnabled, } from "./env.js";
+function parseTlsRejectUnauthorizedEnv(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "0" || normalized === "false" || normalized === "no")
+        return false;
+    if (normalized === "1" || normalized === "true" || normalized === "yes")
+        return true;
+    return undefined;
+}
+export function resolveTlsSettings(flags, saved) {
+    let tlsRejectUnauthorized = flags["insecure"] === true ? false : undefined;
+    let caCertPath = flags["ca-cert"];
+    tlsRejectUnauthorized ??= parseTlsRejectUnauthorizedEnv(process.env.NODE_TLS_REJECT_UNAUTHORIZED);
+    caCertPath ??= process.env.NODE_EXTRA_CA_CERTS;
+    if (tlsRejectUnauthorized === undefined) {
+        tlsRejectUnauthorized = saved?.tlsRejectUnauthorized;
+    }
+    caCertPath ??= saved?.caCertPath;
+    return { tlsRejectUnauthorized, caCertPath, };
+}
+export const currentCommandContext = {};
+// ---------------------------------------------------------------------------
+// Credential resolution
+// ---------------------------------------------------------------------------
+export function resolveCredentials(flags) {
+    const hasUrlFlag = Object.hasOwn(flags, "url");
+    const hasApiKeyFlag = Object.hasOwn(flags, "api-key");
+    const hasProjectKeyFlag = Object.hasOwn(flags, "project-key");
+    let url = hasUrlFlag ? flags["url"] : undefined;
+    let apiKey = hasApiKeyFlag ? flags["api-key"] : undefined;
+    let projectKey = hasProjectKeyFlag ? flags["project-key"] : undefined;
+    const saved = loadCredentials();
+    const useEnv = dataikuEnvironmentEnabled();
+    if (useEnv) {
+        if (!hasUrlFlag)
+            url ??= process.env.DATAIKU_URL;
+        if (!hasApiKeyFlag)
+            apiKey ??= process.env.DATAIKU_API_KEY;
+        if (!hasProjectKeyFlag)
+            projectKey ??= process.env.DATAIKU_PROJECT_KEY;
+    }
+    if (saved) {
+        if (!hasUrlFlag)
+            url ??= saved.url;
+        if (!hasApiKeyFlag)
+            apiKey ??= saved.apiKey;
+        if (!hasProjectKeyFlag)
+            projectKey ??= saved.projectKey;
+    }
+    return {
+        url: url ?? "",
+        apiKey: apiKey ?? "",
+        projectKey,
+        ...resolveTlsSettings(flags, saved ?? undefined),
+    };
+}

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

@@ -0,0 +1,25 @@
+import type { DataikuClient } from "../client.js";
+export type CommandHandler = (client: DataikuClient, args: string[], flags: Record<string, string | boolean>) => Promise<unknown>;
+export interface CommandPayloadSchema {
+    stdin?: boolean;
+    dataFlag?: boolean;
+    dataFileFlag?: boolean;
+    jsonShape?: "object" | "array";
+}
+export interface CommandFlagChoice {
+    oneOf: string[][];
+}
+export interface CommandRegistryOverride {
+    requiredFlags?: string[];
+    requiredOneOf?: CommandFlagChoice[];
+    optionalFlags?: string[];
+    payloadSchema?: CommandPayloadSchema;
+    examplePayload?: unknown;
+    cleanupCommand?: string;
+}
+export interface CommandMeta extends CommandRegistryOverride {
+    handler: CommandHandler;
+    usage: string;
+    description?: string;
+    examples?: string[];
+}

package/dist/src/cli/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,16 @@
+import type { StableErrorCode } from "../errors.js";
+export declare const RESOURCE_NAMES: string[];
+export declare class UsageError extends Error {
+    readonly code: StableErrorCode;
+    readonly hint?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code?: StableErrorCode, hint?: string, details?: Record<string, unknown>);
+}
+export declare const COMMANDS_RUN_HINT = "Use `dss commands run` for machine-readable command discovery.";
+export declare function unsupportedHelpFlag(): UsageError;
+export declare function noCommandError(): UsageError;
+export declare function missingActionError(resource: string, validActions: string[], usage?: string): UsageError;
+export declare function unknownResourceError(resource: string): UsageError;
+export declare function unknownActionError(resource: string, action: string | undefined, validActions: string[], hint?: string): UsageError;
+export declare function requireArgs(args: string[], count: number, usage: string): void;
+export declare function requireNoArgs(args: string[], usage: string): void;

package/dist/src/cli/usage.js

@@ -0,0 +1,80 @@
+export const RESOURCE_NAMES = [
+    "project",
+    "app",
+    "business-app",
+    "webapp",
+    "api-service",
+    "api-deployer",
+    "bundle",
+    "project-deployer",
+    "project-library",
+    "streaming-endpoint",
+    "continuous-activity",
+    "statistics",
+    "discussion",
+    "meaning",
+    "workspace",
+    "metrics",
+    "doctor",
+    "wiki",
+    "dashboard",
+    "insight",
+    "data-quality",
+    "future",
+    "flow-zone",
+    "dataset",
+    "recipe",
+    "job",
+    "scenario",
+    "folder",
+    "variable",
+    "connection",
+    "code-env",
+    "sql",
+    "code",
+    "notebook",
+    "auth",
+    "cleanup",
+    "commands",
+    "fixtures",
+    "install-skill",
+]
+    .sort();
+export class UsageError extends Error {
+    code;
+    hint;
+    details;
+    constructor(message, code = "usage_error", hint, details) {
+        super(message);
+        this.name = "UsageError";
+        this.code = code;
+        this.hint = hint;
+        this.details = details;
+    }
+}
+export const COMMANDS_RUN_HINT = "Use `dss commands run` for machine-readable command discovery.";
+export function unsupportedHelpFlag() {
+    return new UsageError("Help screens are not supported.", "usage_error", COMMANDS_RUN_HINT, { command: "dss commands run", });
+}
+export function noCommandError() {
+    return new UsageError("No command provided.", "usage_error", COMMANDS_RUN_HINT, { command: "dss commands run", resources: RESOURCE_NAMES, });
+}
+export function missingActionError(resource, validActions, usage) {
+    return new UsageError(`Missing action for ${resource}.`, "usage_error", usage ?? COMMANDS_RUN_HINT, { resource, validActions, });
+}
+export function unknownResourceError(resource) {
+    return new UsageError(`Unknown resource: ${resource}.`, "usage_error", COMMANDS_RUN_HINT, { resource, validResources: RESOURCE_NAMES, });
+}
+export function unknownActionError(resource, action, validActions, hint) {
+    return new UsageError(`Unknown action: ${resource} ${action ?? ""}`.trim(), "usage_error", hint ?? COMMANDS_RUN_HINT, { resource, action, validActions, });
+}
+export function requireArgs(args, count, usage) {
+    if (args.length < count) {
+        throw new UsageError(`Expected ${count} argument(s), got ${args.length}.\nUsage: ${usage}`, "missing_required_arg");
+    }
+}
+export function requireNoArgs(args, usage) {
+    if (args.length > 0) {
+        throw new UsageError(`Unexpected argument(s): ${args.join(" ")}.\nUsage: ${usage}`, "usage_error");
+    }
+}

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

@@ -0,0 +1,14 @@
+export declare function findPackageRoot(): string | undefined;
+export declare function packageVersion(packageRoot: string | undefined): string;
+export declare function gitDirectory(packageRoot: string): string;
+export declare function gitRevision(packageRoot: string | undefined): string | undefined;
+export declare const PACKAGE_ROOT: string | undefined;
+export declare const CLI_VERSION: string;
+export declare const CLI_GIT_REVISION: string | undefined;
+export declare const AGENT_CONTRACT_VERSION = 1;
+export declare const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
+export declare const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v1.json";
+export declare function cliVersionResult(): {
+    version: string;
+    gitRevision: string | null;
+};

package/dist/src/cli/version.js

@@ -0,0 +1,63 @@
+import { readFileSync, } from "node:fs";
+import { dirname, resolve, } from "node:path";
+import { fileURLToPath, } from "node:url";
+export function findPackageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 5; i++) {
+        try {
+            readFileSync(resolve(dir, "package.json"), "utf-8");
+            return dir;
+        }
+        catch {
+            dir = dirname(dir);
+        }
+    }
+    return undefined;
+}
+export function packageVersion(packageRoot) {
+    if (!packageRoot)
+        return "unknown";
+    try {
+        return JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf-8")).version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+export function gitDirectory(packageRoot) {
+    try {
+        const gitFile = readFileSync(resolve(packageRoot, ".git"), "utf-8").trim();
+        if (gitFile.startsWith("gitdir:")) {
+            return resolve(packageRoot, gitFile.slice("gitdir:".length).trim());
+        }
+    }
+    catch {
+        // Normal checkouts have a .git directory, not a .git file.
+    }
+    return resolve(packageRoot, ".git");
+}
+export function gitRevision(packageRoot) {
+    if (!packageRoot)
+        return undefined;
+    try {
+        const gitDir = gitDirectory(packageRoot);
+        const head = readFileSync(resolve(gitDir, "HEAD"), "utf-8").trim();
+        if (!head.startsWith("ref:"))
+            return head.slice(0, 7);
+        const ref = head.slice("ref:".length).trim();
+        const full = readFileSync(resolve(gitDir, ref), "utf-8").trim();
+        return full.slice(0, 7);
+    }
+    catch {
+        return undefined;
+    }
+}
+export const PACKAGE_ROOT = findPackageRoot();
+export const CLI_VERSION = packageVersion(PACKAGE_ROOT);
+export const CLI_GIT_REVISION = gitRevision(PACKAGE_ROOT);
+export const AGENT_CONTRACT_VERSION = 1;
+export const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
+export const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v1.json";
+export function cliVersionResult() {
+    return { version: CLI_VERSION, gitRevision: CLI_GIT_REVISION ?? null, };
+}