dataiku-sdk 3.0.0 → 3.2.0

package/dist/src/resources/project-git.js

@@ -17,11 +17,39 @@ function sleep(ms) {
     setTimeout(resolve, ms);
     return promise;
 }
-function encodePathSegments(path) {
+function gitReferencePathError(path, message) {
+    return new ClientValidationError(message, "validation_failed", "Use a Git library reference path relative to the project library root: '/' -separated segment names, with no '.' or '..' segments.", { path, });
+}
+/**
+ * Validate and canonicalize a Git library reference path. This is the single
+ * validator used by both SDK dispatch and CLI mutation planning.
+ *
+ * Strip only the permitted outer '/' separators, then require nonempty
+ * ordinary segments: no empty segments and no '.' or '..' segments. A hostile
+ * path therefore cannot change which API resource a dispatcher's URL
+ * normalization would otherwise select.
+ */
+export function validateGitReferencePath(path) {
+    if (typeof path !== "string" || path.trim() === "") {
+        throw gitReferencePathError(path, "A Git library reference path is required.");
+    }
     const normalized = path.replace(/^\/+/, "").replace(/\/+$/, "");
-    if (!normalized)
-        throw new ClientValidationError("A Git reference path is required.");
-    return normalized
+    if (normalized === "") {
+        throw gitReferencePathError(path, "A Git library reference path is required.");
+    }
+    for (const segment of normalized.split("/")) {
+        if (segment === "") {
+            throw gitReferencePathError(path, "A Git library reference path must not contain empty segments (consecutive or repeated '/').");
+        }
+        if (segment === "." || segment === "..") {
+            throw gitReferencePathError(path, "A Git library reference path must not contain '.' or '..' segments.");
+        }
+    }
+    return normalized;
+}
+/** Validate a Git library reference path and URL-encode it per segment. */
+export function encodeGitReferencePath(path) {
+    return validateGitReferencePath(path)
         .split("/")
         .map((segment) => encodeURIComponent(segment))
         .join("/");
@@ -280,7 +308,8 @@ export class ProjectGitResource extends BaseResource {
     async setLibrary(projectKey, gitReferencePath, options) {
         const repository = validatedRepository(options.repository, "Git library repository URL");
         const secrets = [options.password,].filter((secret) => secret !== undefined && secret !== "");
-        const raw = await this.request("PUT", `${this.libraryPath(projectKey)}/${encodePathSegments(gitReferencePath)}`, {
+        const encodedPath = encodeGitReferencePath(gitReferencePath);
+        const raw = await this.request("PUT", `${this.libraryPath(projectKey)}/${encodedPath}`, {
             repository,
             login: options.login ?? null,
             password: options.password ?? null,
@@ -291,19 +320,21 @@ export class ProjectGitResource extends BaseResource {
     }
     /** Detach a library, optionally deleting its local directory. */
     async removeLibrary(projectKey, gitReferencePath, deleteDirectory = false) {
-        await this.request("DELETE", `${this.libraryPath(projectKey)}/${encodePathSegments(gitReferencePath)}${this.query({ deleteDirectory, })}`);
+        await this.request("DELETE", `${this.libraryPath(projectKey)}/${encodeGitReferencePath(gitReferencePath)}${this.query({ deleteDirectory, })}`);
     }
     /** Reset one library to its remote state. Runs as a DSS future. */
     async resetLibrary(projectKey, gitReferencePath) {
+        const gitRef = validateGitReferencePath(gitReferencePath);
         const raw = await this.request("POST", `${this.libraryPath(projectKey)}/action/reset`, {
-            gitRef: gitReferencePath,
+            gitRef,
         });
         return this.client.safeParse(ProjectGitFutureResponseSchema, raw ?? {}, "projectGit.resetLibrary");
     }
     /** Commit and push one library. Runs as a DSS future. */
     async pushLibrary(projectKey, gitReferencePath, commitMessage) {
+        const gitRef = validateGitReferencePath(gitReferencePath);
         const raw = await this.request("POST", `${this.libraryPath(projectKey)}/action/push`, {
-            gitRef: gitReferencePath,
+            gitRef,
             commitMessage,
         });
         return this.client.safeParse(ProjectGitFutureResponseSchema, raw ?? {}, "projectGit.pushLibrary");

package/dist/src/resources/project-library.d.ts

@@ -1,6 +1,16 @@
 import { BaseResource } from "./base.js";
 export interface ProjectLibraryItem {
     name: string;
+    /** Full library path of the item, as observed from DSS contents listings. */
+    path?: string;
+    /** File size in bytes, as observed from DSS contents listings. */
+    size?: number;
+    /** MIME type of the file content, as observed from DSS contents listings. */
+    mimeType?: string;
+    /** Whether the item carries data, as observed from DSS contents listings. */
+    hasData?: boolean;
+    /** Last modification timestamp (epoch milliseconds), as observed from DSS contents listings. */
+    lastModified?: number;
     children?: ProjectLibraryItem[];
 }
 export interface ProjectLibraryFileContent {
@@ -14,25 +24,130 @@ export interface ProjectLibraryMoveRequest {
     oldPath: string;
     newPath: string;
 }
+export interface ProjectLibraryWriteOptions {
+    /**
+     * 64-character SHA-256 hex digest the caller last read from this file.
+     * Non-atomic stale-read guard: the write is refused when the remote
+     * content already differs at the verification read. It cannot prevent a
+     * concurrent write landing between that read and this write.
+     */
+    expectSha256?: string;
+}
+export interface ProjectLibraryWriteResult {
+    path: string;
+    /** Number of bytes written. */
+    bytes: number;
+    /** SHA-256 hex digest of the exact bytes written. */
+    sha256: string;
+    /** SHA-256 hex digest observed before the write; present when a precondition was checked. */
+    beforeSha256?: string;
+}
+export interface ProjectLibraryDiffOptions {
+    /** Cap on reported diff lines (default 200). */
+    maxLines?: number;
+}
+export interface ProjectLibraryDiffResult {
+    path: string;
+    /** True when remote and local content are byte-identical. */
+    unchanged: boolean;
+    /** Lines added in the local content relative to the remote file. */
+    added: number;
+    /** Lines removed from the remote file relative to the local content. */
+    removed: number;
+    /** Unified diff text; capped at `maxLines`. Empty for binary or byte-identical content. */
+    diff: string;
+    /** True when the diff text was truncated at `maxLines`. */
+    diffTruncated: boolean;
+    /** True when either side is not valid UTF-8 text; diff is never emitted for binary. */
+    binary?: boolean;
+    /** True when the remote file does not exist. */
+    remoteAbsent?: boolean;
+    remoteSha256?: string;
+    remoteBytes?: number;
+    localSha256: string;
+    localBytes: number;
+    maxLines: number;
+}
+/**
+ * The only concurrency control the public project-library API permits. DSS
+ * exposes no conditional write (no ETag, no If-Match, no version token), so
+ * `expectSha256` can only detect a hash that is already stale when it is
+ * checked; it can never turn the subsequent POST into a conditional write.
+ */
+export declare const PROJECT_LIBRARY_CONCURRENCY_CONTROL = "client-side-non-atomic-stale-read-check";
+/** Lowercase or uppercase SHA-256 hex digest. */
+export declare const EXPECT_SHA256_PATTERN: RegExp;
+/**
+ * Validate and canonicalize a project library path.
+ *
+ * Rejects empty paths, control characters, backslash separators, empty
+ * segments (leading/trailing/doubled '/'), '.'/'..' segments (including
+ * mid-path traversals), whitespace-only or edge-whitespace segments, and
+ * trailing dot/space segments that differ across filesystem normalizations.
+ *
+ * Returns the canonical path with any leading '/' prefix stripped (the DSS
+ * contents endpoints take paths relative to the library root).
+ */
+export declare function validateLibraryPath(path: string): string;
+/**
+ * Validate a rename target: a single library segment (no '/'), with the same
+ * character rules as path segments. Returns the validated name unchanged.
+ */
+export declare function validateLibraryName(name: string): string;
+/**
+ * Validate a destination folder path for a library move. '/' (the library
+ * root) is valid; any other path must pass {@link validateLibraryPath}.
+ * Returns the canonical destination ('/' or '/<path>').
+ */
+export declare function validateLibraryDestinationPath(path: string): string;
+/** Validate and URL-encode each segment of a library path for endpoint use. */
+export declare function encodeLibraryPath(path: string): string;
 export declare class ProjectLibraryResource extends BaseResource {
-    /** List the full project code-library contents tree. */
+    /**
+     * List the full project code-library contents tree. Items carry the DSS
+     * observed fields (path, size, mimeType, hasData, lastModified) when the
+     * server reports them; folders carry children, files do not.
+     */
     listContents(projectKey?: string): Promise<ProjectLibraryItem[]>;
     /** Read a project code-library file as text. */
     getFile(path: string, projectKey?: string): Promise<string>;
     /** Read a project code-library file as bytes. */
     getFileBytes(path: string, projectKey?: string): Promise<Uint8Array>;
-    /** Create an empty project code-library file. */
+    /**
+     * True when a file or folder exists at the given library path. Existence is
+     * verified against the live contents tree read from DSS.
+     */
+    hasLibraryItem(path: string, projectKey?: string): Promise<boolean>;
+    /** Create an empty project code-library file; refuses to overwrite an existing item. */
     addFile(path: string, projectKey?: string): Promise<void>;
-    /** Create a project code-library folder. */
+    /** Create a project code-library folder; refuses to overwrite an existing item. */
     addFolder(path: string, projectKey?: string): Promise<void>;
-    /** Create or replace a project code-library file with raw text content. */
-    addOrUpdateFile(path: string, content: string, projectKey?: string): Promise<void>;
-    /** Delete a project code-library file. */
+    /**
+     * Create or replace a project code-library file with raw content. `content`
+     * may be a string (UTF-8 text) or raw bytes (binary-safe); the exact bytes
+     * sent are returned as a SHA-256 digest and byte count.
+     *
+     * When `options.expectSha256` is set, the current remote content is read
+     * first and the write is refused with an `assertion_failed` error when its
+     * SHA-256 differs. The check is non-atomic (see
+     * {@link PROJECT_LIBRARY_CONCURRENCY_CONTROL}).
+     */
+    addOrUpdateFile(path: string, content: string | Uint8Array, projectKey?: string, options?: ProjectLibraryWriteOptions): Promise<ProjectLibraryWriteResult>;
+    /**
+     * Diff a library file against local content. The remote side is read as
+     * bytes (so binary files are detected instead of dumped); the reported
+     * unified diff is capped at `options.maxLines` (default 200) and never
+     * contains binary payloads.
+     */
+    diffFile(path: string, local: string | Uint8Array, projectKey?: string, options?: ProjectLibraryDiffOptions): Promise<ProjectLibraryDiffResult>;
+    /** Delete a project code-library file or folder. */
     deleteFile(path: string, projectKey?: string): Promise<void>;
     /** Rename a project code-library file or folder within its current parent folder. */
     rename(path: string, newName: string, projectKey?: string): Promise<void>;
     /** Move a project code-library file or folder into another library folder. */
     move(path: string, destinationFolderPath: string, projectKey?: string): Promise<void>;
     private contentsPath;
-    private postRawText;
+    private postRawBody;
+    private alreadyExistsError;
+    private assertLibraryFileAbsent;
 }