dataiku-sdk 0.12.4 → 0.12.6

package/dist/src/client.js

@@ -2,7 +2,7 @@ import { readFileSync, } from "node:fs";
 import { getCACertificates, } from "node:tls";
 import { Value, } from "@sinclair/typebox/value";
 import { safeParseSchema, } from "./schemas.js";
-import { classifyDataikuError, DataikuError, } from "./errors.js";
+import { classifyDataikuError, ClientValidationError, DataikuError, } from "./errors.js";
 import { AnalysesResource, } from "./resources/analyses.js";
 import { ApiDeployerResource, } from "./resources/api-deployer.js";
 import { ApiServicesResource, } from "./resources/api-services.js";
@@ -135,6 +135,22 @@ function buildFetchTlsOptions(config) {
     }
     return tls;
 }
+/**
+ * True when the URL embeds userinfo (`https://user:password@host`). Embedded
+ * credentials are rejected up front so they can never reach the canonical base
+ * URL that gets persisted in recorded artifacts (cleanup ledgers, permission
+ * snapshots) or echoed in diagnostics. Malformed URLs fall through to the
+ * existing request-time failure.
+ */
+function hasEmbeddedUserinfo(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.username !== "" || parsed.password !== "";
+    }
+    catch {
+        return false;
+    }
+}
 /* ------------------------------------------------------------------ */
 /*  Client                                                             */
 /* ------------------------------------------------------------------ */
@@ -297,6 +313,9 @@ export class DataikuClient {
         if (!url || !apiKey) {
             throw new Error("Dataiku URL and API key are required: pass {url, apiKey} or set DATAIKU_URL/DATAIKU_API_KEY");
         }
+        if (hasEmbeddedUserinfo(url)) {
+            throw new ClientValidationError("Dataiku URL must not contain embedded credentials (userinfo). Authenticate with an API key instead.", "validation_failed", "Pass the DSS base URL without a username or password.", { urlHasEmbeddedUserinfo: true, });
+        }
         this.baseUrl = url.replace(/\/+$/, "");
         this.apiKey = apiKey;
         this.defaultProjectKey = config?.projectKey?.trim() || undefined;
@@ -308,6 +327,14 @@ export class DataikuClient {
         this.onTrace = config?.onTrace ?? defaultTrace;
         this.onValidationWarning = config?.onValidationWarning ?? defaultValidationWarning;
     }
+    /**
+     * Canonical request base URL: the exact prefix every HTTP verb concatenates
+     * paths onto (trimmed, trailing slashes stripped). Callers that must bind a
+     * recorded artifact to its originating DSS server compare against this.
+     */
+    getBaseUrl() {
+        return this.baseUrl;
+    }
     getRequestTimeoutMs() {
         return this.requestTimeoutMs;
     }
@@ -379,12 +406,21 @@ export class DataikuClient {
         const usable = truncated ? trimToUtf8Boundary(collected) : collected;
         return { text: new TextDecoder().decode(usable), truncated, };
     }
-    async post(path, body) {
+    /**
+     * POST with optional transient retry. Only opt in when repeating the request
+     * is safe: the server may have accepted an attempt whose response was lost.
+     */
+    async post(path, body, options) {
+        const retryMaxAttempts = options?.retryMaxAttempts;
+        if (retryMaxAttempts !== undefined
+            && (!Number.isInteger(retryMaxAttempts) || retryMaxAttempts < 1)) {
+            throw new ClientValidationError("retryMaxAttempts must be a positive integer.");
+        }
         const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "POST",
             headers: this.getHeaders(),
             body: body !== undefined ? JSON.stringify(body) : undefined,
-        });
+        }, retryMaxAttempts);
         return this.parseJsonResponse(res);
     }
     async postText(path, body) {
@@ -511,10 +547,14 @@ export class DataikuClient {
         }
     }
     /* ---- private: retry loop ---- */
-    async fetchWithRetry(url, init) {
+    async fetchWithRetry(url, init, retryMaxAttempts) {
         const method = (init.method ?? "GET").toUpperCase();
-        const retryEnabled = shouldRetryMethod(method);
-        const maxAttempts = retryEnabled ? this.retryMaxAttempts : 1;
+        const retryEnabled = shouldRetryMethod(method) || retryMaxAttempts !== undefined;
+        const maxAttempts = retryMaxAttempts === undefined
+            ? retryEnabled
+                ? this.retryMaxAttempts
+                : 1
+            : Math.min(retryMaxAttempts, MAX_RETRY_ATTEMPTS_CAP);
         const delaysMs = [];
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
             let timedOut = false;

package/dist/src/errors.d.ts

@@ -1,5 +1,5 @@
 export type DataikuErrorCategory = "not_found" | "forbidden" | "validation" | "transient" | "unknown";
-export type StableErrorCode = "usage_error" | "unknown_flag" | "missing_required_arg" | "missing_required_flag" | "invalid_enum" | "not_found" | "permission_denied" | "validation_failed" | "transient" | "long_running_failure" | "internal_error";
+export type StableErrorCode = "usage_error" | "unknown_flag" | "missing_required_arg" | "missing_required_flag" | "invalid_enum" | "not_found" | "permission_denied" | "validation_failed" | "transient" | "long_running_failure" | "command_result_failure" | "assertion_failed" | "ambiguous_outcome" | "internal_error";
 export declare function dataikuErrorCode(category: DataikuErrorCategory): StableErrorCode;
 export interface DataikuErrorTaxonomy {
     category: DataikuErrorCategory;

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

@@ -1,3 +1,4 @@
+import { type DataikuErrorCategory } from "../errors.js";
 import { BaseResource } from "./base.js";
 export interface AppListItem extends Record<string, unknown> {
     appId?: string;
@@ -20,6 +21,141 @@ export interface BusinessAppInstanceUserPermissions extends Record<string, unkno
     readProjectContent?: boolean;
     writeProjectContent?: boolean;
 }
+export interface DeleteAppInstanceOptions {
+    /** Refuse deletion unless the current creationTag hashes to this value. */
+    expectedProjectIncarnationHash?: string;
+}
+export type AppManifestReferenceKind = "scenario" | "folder" | "variable";
+/**
+ * Source-verifiable app-manifest reference locations. Validation is scoped to
+ * homepage tiles so identically named keys in arbitrary custom-form `config`
+ * objects are never treated as references.
+ */
+export declare const APP_MANIFEST_REFERENCE_KEYS: Record<AppManifestReferenceKind, string[]>;
+export interface AppManifestReference {
+    kind: AppManifestReferenceKind;
+    path: string;
+    value: string;
+    exists: boolean;
+}
+export interface AppManifestCheck {
+    kind: AppManifestReferenceKind;
+    status: "ok" | "failed" | "skipped";
+    checked: number;
+    malformed: number;
+    missing: number;
+}
+export interface AppManifestIssue {
+    code: "INVALID_MANIFEST_ROOT" | "INVALID_REFERENCE_VALUE" | "MISSING_SCENARIO" | "MISSING_FOLDER" | "MISSING_VARIABLE";
+    path: string;
+    message: string;
+}
+export interface AppManifestValidationResult {
+    valid: boolean;
+    projectKey: string;
+    manifestHash: string;
+    references: AppManifestReference[];
+    checks: AppManifestCheck[];
+    errors: AppManifestIssue[];
+}
+export interface AppManifestPathDifference {
+    path: string;
+    kind: "added" | "removed" | "changed";
+    template?: unknown;
+    instance?: unknown;
+}
+export interface AppManifestComparisonResult {
+    appId: string;
+    projectKey: string;
+    templateHash: string;
+    instanceHash: string;
+    identical: boolean;
+    omittedFields: string[];
+    differences: AppManifestPathDifference[];
+}
+/**
+ * Raw app-manifest version markers. DSS renders the Application header version
+ * from the manifest's own `version` string, so that field (with its optional
+ * `versionNotes`) is the authoritative state; no separate publish/release
+ * transaction exists on the public API.
+ */
+export interface AppManifestVersionState {
+    projectKey: string;
+    projectAppType: string | null;
+    version: string | null;
+    versionNotes: string | null;
+    manifestHash: string;
+}
+export interface AppManifestVersionUpdate {
+    /** New manifest `version` string. Must be non-empty when supplied. */
+    version?: string;
+    /** New manifest `versionNotes` string. May be empty to clear existing notes. */
+    versionNotes?: string;
+    /**
+     * 64-hex manifest hash the caller last read, used as a non-atomic stale-read
+     * guard: the write is refused when the manifest already differs at the
+     * verification read. It cannot prevent a concurrent write that lands between
+     * that read and this write.
+     */
+    expectHash?: string;
+    /** Compute and report the change without issuing a write. */
+    dryRun?: boolean;
+}
+/**
+ * The only concurrency control the public app-manifest endpoint permits. DSS
+ * exposes no conditional write (no ETag, no If-Match, no version token), so
+ * `expectHash` can only detect a hash that is already stale when it is checked;
+ * it can never turn the subsequent PUT into a conditional write. Every
+ * manifest-version write
+ * result reports this literal so callers can machine-check the guarantee they
+ * actually get instead of inferring one from prose.
+ */
+export declare const APP_MANIFEST_CONCURRENCY_CONTROL = "client-side-non-atomic-stale-read-check";
+export type AppManifestConcurrencyControl = typeof APP_MANIFEST_CONCURRENCY_CONTROL;
+export type AppManifestVersionWriteOutcome = "persisted" | "dry-run" | "unchanged" | "indeterminate";
+export interface AppManifestVersionWriteFailure {
+    /** Sanitized summary; never echoes response bodies or secrets. */
+    error: string;
+    errorStatus: number | null;
+    errorCategory: DataikuErrorCategory | null;
+    remediation: string;
+}
+export interface AppManifestVersionWriteResult {
+    projectKey: string;
+    projectAppType: string | null;
+    /** Fields the caller asked to set; null means "left untouched". */
+    requested: {
+        version: string | null;
+        versionNotes: string | null;
+    };
+    /** True when the desired manifest differs from the manifest that was read. */
+    changed: boolean;
+    dryRun: boolean;
+    /**
+     * True only after a write was accepted and re-read as exactly `desired`.
+     * False for unchanged/dry-run results. Null when the write outcome could
+     * not be observed (transport loss, transient/server failure, or failed
+     * verification read) — the write may still have landed.
+     */
+    persisted: boolean | null;
+    outcome: AppManifestVersionWriteOutcome;
+    before: AppManifestVersionState;
+    desired: AppManifestVersionState;
+    /**
+     * Last state observed on the server; equals `before` when nothing was
+     * written. Null when the write outcome could not be observed.
+     */
+    after: AppManifestVersionState | null;
+    /**
+     * Always `"client-side-non-atomic-stale-read-check"`. The GET→PUT window is
+     * unguarded: this client can overwrite a competing write that lands after its
+     * GET, and that lost update is not detectable when this client's PUT wins.
+     * The final read only verifies the state observed after this client's PUT.
+     */
+    concurrencyControl: AppManifestConcurrencyControl;
+    /** Present only when outcome is "indeterminate". */
+    error?: AppManifestVersionWriteFailure;
+}
 export declare class ApplicationsResource extends BaseResource {
     /** List all Dataiku Apps. */
     listApps(): Promise<AppListItem[]>;
@@ -31,10 +167,64 @@ export declare class ApplicationsResource extends BaseResource {
     createInstance(appId: string, body: Record<string, unknown>): Promise<AppInstanceRef>;
     /** Get the manifest for an app instance project. */
     getInstanceManifest(projectKey?: string): Promise<Record<string, unknown>>;
+    private getProjectDetails;
+    private getProjectAppType;
+    /**
+     * Shared app-manifest write guard: DSS only accepts manifest saves for app
+     * template projects, so every mutation path rejects instances and ordinary
+     * projects before issuing a PUT.
+     */
+    private requireAppTemplateForManifestSave;
     /** Save the manifest for a Dataiku App template project (rejects classic app-instance projects). */
     saveInstanceManifest(manifest: Record<string, unknown>, projectKey?: string): Promise<void>;
+    /**
+     * Read the manifest plus its derived version state. The project type comes
+     * from the manifest when DSS includes it and from project details otherwise,
+     * so ordinary reads cost a single request.
+     */
+    private readManifestVersion;
+    /**
+     * Read the authoritative app-manifest version markers. Allowed for app
+     * templates and app instances alike: instance verification compares an
+     * instance's inherited `version` against its template.
+     */
+    getManifestVersion(projectKey?: string): Promise<AppManifestVersionState>;
+    /**
+     * Set the manifest `version`/`versionNotes` strings on an app template.
+     *
+     * This is a manifest save, not a publish transaction: DSS exposes no release
+     * endpoint, and new instances simply inherit whatever version string the
+     * template carries at creation time.
+     *
+     * The write is not atomic, and `expectHash` cannot change that: the
+     * endpoint takes every PUT unconditionally, so `expectHash` only rejects a
+     * caller whose hash is already stale at the verification read. This client
+     * can overwrite a writer that commits after that read but before this PUT,
+     * and a final state equal to this client's desired manifest cannot reveal
+     * that lost update. The final read still prevents a different state observed
+     * after the PUT from being reported as persisted.
+     */
+    setManifestVersion(update: AppManifestVersionUpdate, projectKey?: string): Promise<AppManifestVersionWriteResult>;
+    /**
+     * Validate source-verifiable references in app homepage tiles:
+     * SCENARIO_RUN scenario IDs, DOWNLOAD_FILE managed-folder IDs, and runtime
+     * form parameter names (which DSS maps to project variables). Arbitrary
+     * custom-form `config` objects remain opaque. The manifest is never mutated.
+     * Missing/malformed references are returned deterministically; a reference
+     * kind with no applicable tiles does not trigger its project API.
+     */
+    validateAppManifest(manifest: unknown, projectKey?: string): Promise<AppManifestValidationResult>;
+    /**
+     * Compare a Dataiku App template manifest with the app-instance manifest of
+     * the target project. Root-level project identity fields in
+     * APP_MANIFEST_COMPARE_OMITTED_FIELDS are omitted from both sides; every
+     * other field — including ones the SDK does not model — is compared.
+     * Hashes cover the omitted-field-normalized states; differences are emitted
+     * as deterministic, path-ordered entries.
+     */
+    compareAppManifest(appId: string, projectKey?: string): Promise<AppManifestComparisonResult>;
     /** Delete an app instance project. */
-    deleteInstance(projectKey?: string): Promise<void>;
+    deleteInstance(projectKey?: string, options?: DeleteAppInstanceOptions): Promise<void>;
     /** List all Business Apps. */
     listBusinessApps(): Promise<BusinessAppListItem[]>;
     /** Get Business App details. */