dataiku-sdk 2.0.0 → 3.1.0

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;
 }