dataiku-sdk 3.2.0 → 3.3.0

package/dist/src/resources/plugins.js

@@ -0,0 +1,458 @@
+import { ClientValidationError, DataikuError, } from "../errors.js";
+import { BaseResource, requireNonEmpty, } from "./base.js";
+import { validateGitReferencePath, } from "./project-git.js";
+/* ------------------------------------------------------------------ */
+/*  Path helpers                                                       */
+/* ------------------------------------------------------------------ */
+const PLUGIN_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+/**
+ * Validate a plugin identifier. Plugin ids select the API route segment, so a
+ * hostile id must not be able to change which resource the URL addresses.
+ */
+export function validatePluginId(pluginId) {
+    requireNonEmpty(pluginId, "pluginId");
+    if (!PLUGIN_ID_PATTERN.test(pluginId)) {
+        throw new ClientValidationError(`Invalid plugin id: ids use letters, digits, '-', '_', and '.', and start with a letter or digit.`, "validation_failed", undefined, { pluginId, });
+    }
+    return pluginId;
+}
+function pluginPathError(path, message) {
+    return new ClientValidationError(message, "validation_failed", "Use a plugin path relative to the plugin root: folders separated by '/', each segment a simple file or folder name.", { path, });
+}
+const CONTROL_CHARACTER_RE = /[\u0000-\u001f\u007f]/;
+const BACKSLASH_RE = /\\/;
+const TRAILING_AMBIGUOUS_RE = /[\s.]$/;
+const WHITESPACE_ONLY_RE = /^\s+$/;
+/**
+ * Validate and canonicalize a path inside a plugin. Mirrors the project
+ * library validator: rejects empty paths, control characters, backslashes,
+ * empty segments, '.'/'..' traversals, whitespace-only or edge-whitespace
+ * segments, and trailing dot/space segments.
+ *
+ * Returns the canonical path with any leading '/' stripped (the contents
+ * endpoints take paths relative to the plugin root).
+ */
+export function validatePluginPath(path) {
+    if (typeof path !== "string" || path.trim() === "") {
+        throw pluginPathError(path, "A plugin path is required.");
+    }
+    if (CONTROL_CHARACTER_RE.test(path)) {
+        throw pluginPathError(path, "Plugin path must not contain control characters.");
+    }
+    const normalized = path.replace(/^\/+/, "");
+    if (normalized === "") {
+        throw pluginPathError(path, "Plugin path must name a file or folder below the plugin root.");
+    }
+    for (const segment of normalized.split("/")) {
+        if (segment === "") {
+            throw pluginPathError(path, "Plugin path must not contain empty segments (leading, trailing, or doubled '/').");
+        }
+        if (segment === "." || segment === "..") {
+            throw pluginPathError(path, "Plugin path must not contain '.' or '..' segments.");
+        }
+        if (BACKSLASH_RE.test(segment)) {
+            throw pluginPathError(path, "Plugin path must not contain backslashes.");
+        }
+        if (segment !== segment.trim() || WHITESPACE_ONLY_RE.test(segment)) {
+            throw pluginPathError(path, "Plugin path segments must not be whitespace-only, or start or end with whitespace.");
+        }
+        if (TRAILING_AMBIGUOUS_RE.test(segment)) {
+            throw pluginPathError(path, "Plugin path must not contain segments with a trailing space or dot (ambiguous across filesystem normalizations).");
+        }
+    }
+    return normalized;
+}
+/**
+ * Validate a destination folder for a plugin contents move. '/' (the plugin
+ * root) is valid; any other path must pass {@link validatePluginPath}.
+ * Returns the canonical destination ('/' or '/<path>').
+ */
+export function validatePluginDestinationPath(path) {
+    if (path === "/")
+        return "/";
+    return `/${validatePluginPath(path)}`;
+}
+/** Validate a rename target: a single plugin path segment, no '/'. */
+export function validatePluginName(name) {
+    if (typeof name !== "string" || name.trim() === "") {
+        throw new ClientValidationError("Plugin rename target must be a non-empty string.", "validation_failed", undefined, { newName: name, });
+    }
+    if (name.includes("/")) {
+        throw new ClientValidationError("Plugin rename target must be a single segment without '/'.", "validation_failed", "Rename within the current parent folder; use the move operation to change folders.", { newName: name, });
+    }
+    if (name === "." || name === "..") {
+        throw new ClientValidationError("Plugin rename target must not be '.' or '..'.", "validation_failed", undefined, { newName: name, });
+    }
+    if (BACKSLASH_RE.test(name)) {
+        throw new ClientValidationError("Plugin rename target must not contain backslashes.", "validation_failed", undefined, { newName: name, });
+    }
+    if (name !== name.trim() || WHITESPACE_ONLY_RE.test(name) || TRAILING_AMBIGUOUS_RE.test(name)) {
+        throw new ClientValidationError("Plugin rename target must not start or end with whitespace or a trailing dot.", "validation_failed", undefined, { newName: name, });
+    }
+    return name;
+}
+/** Validate and URL-encode each segment of a plugin path for endpoint use. */
+export function encodePluginPath(path) {
+    const normalized = validatePluginPath(path);
+    return normalized
+        .split("/")
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+/** URL-encode a plugin id after validation. */
+function enc(pluginId) {
+    return encodeURIComponent(validatePluginId(pluginId));
+}
+/* ------------------------------------------------------------------ */
+/*  Resource                                                           */
+/* ------------------------------------------------------------------ */
+/**
+ * The documented Plugins REST section (DSS 15): instance-level plugin
+ * administration under `/public/api/plugins/...`. All endpoints require admin
+ * or plugin-developer privileges server-side.
+ */
+export class PluginsResource extends BaseResource {
+    /* ---- listing & lifecycle ---- */
+    /** List installed plugins (including dev plugins). */
+    async list() {
+        return this.client.get("/public/api/plugins/");
+    }
+    /**
+     * Install a plugin from a local zip file. Fails if already installed.
+     * Resolves only after the installation completed: when DSS answers with a
+     * future receipt the future is settled before returning.
+     */
+    async installFromZip(filePath) {
+        const receipt = await this.client.uploadJson("/public/api/plugins/actions/installFromZip", filePath);
+        await this.settleActionFuture(receipt, "installFromZip");
+    }
+    /** Install a plugin from the Dataiku store. Fails if already installed. */
+    async installFromStore(pluginId) {
+        const receipt = await this.client.post("/public/api/plugins/actions/installFromStore", { pluginId: validatePluginId(pluginId), });
+        await this.settleActionFuture(receipt, "installFromStore");
+    }
+    /** Install a plugin by checking out a Git repository. Fails if already installed. */
+    async installFromGit(options) {
+        const receipt = await this.client.post("/public/api/plugins/actions/installFromGit", {
+            gitRepositoryUrl: validatedPluginGitUrl(options.gitRepositoryUrl),
+            gitCheckout: options.gitCheckout ?? null,
+            gitSubpath: options.gitSubpath ?? null,
+        });
+        await this.settleActionFuture(receipt, "installFromGit");
+    }
+    /** Download a development plugin as a zip archive. */
+    async download(pluginId) {
+        return this.client.stream(`/public/api/plugins/${enc(pluginId)}/download`);
+    }
+    /**
+     * Update a plugin from a local zip file. Fails if not already installed.
+     * Resolves only after the update completed (future receipt settled).
+     */
+    async updateFromZip(pluginId, filePath) {
+        const receipt = await this.client.uploadJson(`/public/api/plugins/${enc(pluginId)}/actions/updateFromZip`, filePath);
+        await this.settleActionFuture(receipt, "updateFromZip");
+    }
+    /** Update a plugin from the Dataiku Store. */
+    async updateFromStore(pluginId) {
+        const receipt = await this.client.post(`/public/api/plugins/${enc(pluginId)}/actions/updateFromStore`, {});
+        await this.settleActionFuture(receipt, "updateFromStore");
+    }
+    /**
+     * Update an installed plugin from Git. Fails if the plugin is not already
+     * installed. Resolves only after the update completed (future settled).
+     */
+    async updateFromGit(pluginId, options) {
+        const receipt = await this.client.post(`/public/api/plugins/${enc(pluginId)}/actions/updateFromGit`, {
+            gitRepositoryUrl: validatedPluginGitUrl(options.gitRepositoryUrl),
+            gitCheckout: options.gitCheckout ?? null,
+            gitSubpath: options.gitSubpath ?? null,
+        });
+        await this.settleActionFuture(receipt, "updateFromGit");
+    }
+    /**
+     * Move an installed plugin to the development environment. Resolves only
+     * after the move completed (future receipt settled).
+     */
+    async moveToDev(pluginId) {
+        const receipt = await this.client.post(`/public/api/plugins/${enc(pluginId)}/actions/moveToDev`, {});
+        await this.settleActionFuture(receipt, "moveToDev");
+    }
+    /**
+     * Delete a plugin; refuses when usages exist unless `force` is set.
+     * Resolves only after the deletion completed: DSS answers this route with
+     * a future, so reporting success before the future settles would leave
+     * the plugin briefly present after the call returned.
+     */
+    async delete(pluginId, options = {}) {
+        const receipt = await this.client.post(`/public/api/plugins/${enc(pluginId)}/actions/delete`, { force: options.force === true, });
+        await this.settleActionFuture(receipt, "delete");
+    }
+    /* ---- settings ---- */
+    /** Get plugin settings (optionally scoped to a project). */
+    async getSettings(pluginId, options = {}) {
+        const query = scopeQuery(options.projectKey);
+        return this.client.get(`/public/api/plugins/${enc(pluginId)}/settings${query}`);
+    }
+    /**
+     * Replace plugin settings. DSS expects a settings object previously
+     * obtained through {@link getSettings}; `config` and `codeEnvName` are
+     * the documented fields and any extra keys the caller read are forwarded.
+     */
+    async setSettings(pluginId, settings, options = {}) {
+        if (settings === null || typeof settings !== "object" || Array.isArray(settings)) {
+            throw new ClientValidationError("Plugin settings must be an object (use the object returned by plugins.getSettings).");
+        }
+        await this.client.post(`/public/api/plugins/${enc(pluginId)}/settings${scopeQuery(options.projectKey)}`, settings);
+    }
+    /* ---- usages ---- */
+    /** List usages of the plugin's elements, optionally scoped to a project. */
+    async listUsages(pluginId, options = {}) {
+        const raw = await this.client.get(`/public/api/plugins/${enc(pluginId)}/actions/listUsages${scopeQuery(options.projectKey)}`);
+        return raw ?? {};
+    }
+    /* ---- code env ---- */
+    /**
+     * Create the code env of a plugin. Returns the DSS future handle
+     * (`{jobId}`). The request carries the plugin-managed deployment mode and
+     * an explicit interpreter (null = the plugin's default), exactly as the
+     * official Python client sends it.
+     */
+    async createCodeEnv(pluginId, options = {}) {
+        const raw = await this.client.post(`/public/api/plugins/${enc(pluginId)}/code-env/actions/create`, {
+            deploymentMode: "PLUGIN_MANAGED",
+            conda: options.conda === true,
+            pythonInterpreter: options.pythonInterpreter ?? null,
+        });
+        return requireJobId(raw, "plugins.createCodeEnv");
+    }
+    /** Update the code env of a plugin. Returns the DSS future handle. */
+    async updateCodeEnv(pluginId) {
+        const raw = await this.client.post(`/public/api/plugins/${enc(pluginId)}/code-env/actions/update`, {});
+        return requireJobId(raw, "plugins.updateCodeEnv");
+    }
+    /* ---- development plugins ---- */
+    /** Create a new development plugin (empty, cloned, or exported from Git). */
+    async createDev(options) {
+        if (options.creationMode !== "EMPTY" && options.creationMode !== "GIT_CLONE"
+            && options.creationMode !== "GIT_EXPORT") {
+            throw new ClientValidationError("creationMode must be one of EMPTY, GIT_CLONE, GIT_EXPORT.");
+        }
+        const needsGit = options.creationMode !== "EMPTY";
+        if (needsGit && !options.gitRepository?.trim()) {
+            throw new ClientValidationError(`gitRepository is required when creationMode is ${options.creationMode}.`);
+        }
+        await this.client.post("/public/api/plugins/actions/createDev", {
+            pluginId: validatePluginId(options.pluginId),
+            creationMode: options.creationMode,
+            gitRepository: needsGit ? validatedPluginGitUrl(options.gitRepository) : null,
+            gitCheckout: needsGit ? options.gitCheckout ?? null : null,
+            gitSubpath: options.creationMode === "GIT_EXPORT" ? options.gitSubpath ?? null : null,
+        });
+    }
+    /* ---- dev plugin Git remote ---- */
+    /** Get the Git remote declared for a dev plugin (null when unset). */
+    async getGitRemote(pluginId) {
+        const raw = await this.client.get(`/public/api/plugins/${enc(pluginId)}/gitRemote`);
+        if (raw === undefined || raw === null)
+            return { repositoryUrl: null, };
+        if (typeof raw !== "object" || Array.isArray(raw)) {
+            return { repositoryUrl: null, ...wrapUnknown(raw), };
+        }
+        const record = raw;
+        return {
+            repositoryUrl: typeof record.repositoryUrl === "string" ? record.repositoryUrl : null,
+            ...record,
+        };
+    }
+    /** Set (create or replace) the Git remote of a dev plugin. */
+    async setGitRemote(pluginId, repositoryUrl) {
+        const validated = validatedPluginGitUrl(repositoryUrl);
+        const raw = await this.client.post(`/public/api/plugins/${enc(pluginId)}/gitRemote`, { repositoryUrl: validated, });
+        return raw ?? { repositoryUrl: validated, };
+    }
+    /** Delete the Git remote declared for a dev plugin. */
+    async deleteGitRemote(pluginId) {
+        await this.client.del(`/public/api/plugins/${enc(pluginId)}/gitRemote`);
+    }
+    /**
+     * List the Git branches of a dev plugin. Observed DSS 15 contract: GET
+     * `/plugins/{pluginId}/gitBranches` answers `200 ["master"]`. The upstream
+     * DSS 15 REST reference documents POST for this path, but the live API
+     * answers that POST with 405 Method Not Allowed (upstream method wrong);
+     * this SDK uses the observed GET, with no POST fallback.
+     */
+    async listGitBranches(pluginId) {
+        const raw = await this.client.get(`/public/api/plugins/${enc(pluginId)}/gitBranches`);
+        return Array.isArray(raw) ? raw : [];
+    }
+    /** Push the dev plugin's content to its previously-declared Git remote. */
+    async push(pluginId) {
+        return this.devGitAction(pluginId, "push");
+    }
+    /** Pull (and rebase) the dev plugin's content from its Git remote. */
+    async pull(pluginId) {
+        return this.devGitAction(pluginId, "pullRebase");
+    }
+    /** Fetch the dev plugin's content from its Git remote. */
+    async fetch(pluginId) {
+        return this.devGitAction(pluginId, "fetch");
+    }
+    /** Reset the dev plugin to its local HEAD state (discards local edits). */
+    async resetToLocalHeadState(pluginId) {
+        return this.devGitAction(pluginId, "resetToLocalHeadState");
+    }
+    /** Reset the dev plugin to the remote HEAD state (discards local work). */
+    async resetToRemoteHeadState(pluginId) {
+        return this.devGitAction(pluginId, "resetToRemoteHeadState");
+    }
+    async devGitAction(pluginId, action) {
+        const raw = await this.client.post(`/public/api/plugins/${enc(pluginId)}/actions/${action}`, {});
+        const receipt = raw ?? {};
+        await this.settleActionFuture(receipt, action);
+        return receipt;
+    }
+    /**
+     * Settle a plugin action's future receipt. Plugin action endpoints answer
+     * with `{jobId}` when DSS processes the action asynchronously, and with an
+     * empty or already-settled body for synchronous ones — the official
+     * Python client's `DSSFuture.from_resp` accepts a missing jobId and its
+     * `wait_for_result` treats a jobless state as already complete. A jobless
+     * receipt is returned as-is (no fake wait); a jobId is polled through the
+     * shared futures waiter so callers only observe completion.
+     */
+    async settleActionFuture(receipt, action) {
+        const jobId = receipt?.["jobId"];
+        if (typeof jobId !== "string" || jobId.length === 0)
+            return;
+        const waited = await this.client.futures.wait(jobId, {});
+        if (waited.state !== "DONE") {
+            throw new DataikuError(200, "Unexpected Response", `plugin ${action} future ${jobId} ended in state ${waited.state}${waited.timedOut === true ? " (wait timed out)" : ""}`);
+        }
+    }
+    /* ---- dev plugin contents ---- */
+    /** List the contents tree of a dev plugin. */
+    async listContents(pluginId) {
+        return this.client.get(`/public/api/plugins/${enc(pluginId)}/contents/`);
+    }
+    /**
+     * Read a dev plugin file as text. DSS answers this route with the raw file
+     * body (no JSON envelope, `dataEncoding` is not honored), so the response
+     * is read as text directly.
+     */
+    async getFile(pluginId, path) {
+        const valid = validatePluginPath(path);
+        return await this.client.getText(this.contentsPath(pluginId, valid));
+    }
+    /** Read a dev plugin file as raw bytes (same raw-body route as getFile). */
+    async getFileBytes(pluginId, path) {
+        const valid = validatePluginPath(path);
+        const res = await this.client.stream(this.contentsPath(pluginId, valid));
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    /** Download a dev plugin file as a raw stream (binary-safe). */
+    async downloadFile(pluginId, path) {
+        return this.client.stream(this.contentsPath(pluginId, validatePluginPath(path)));
+    }
+    /** Get a single plugin file's detail record (size, mime, timestamps). */
+    async getFileDetails(pluginId, path) {
+        const valid = validatePluginPath(path);
+        const raw = await this.client.get(`/public/api/plugins/${enc(pluginId)}/details/${encodePluginPath(valid)}`);
+        return raw ?? {};
+    }
+    /** Upload (create or replace) a dev plugin file with text or binary content. */
+    async putFile(pluginId, path, content) {
+        const valid = validatePluginPath(path);
+        if (typeof content !== "string" && !(content instanceof Uint8Array)) {
+            throw new ClientValidationError("Plugin file content must be a string or raw bytes.", "validation_failed");
+        }
+        const payload = typeof content === "string" ? Buffer.from(content, "utf8") : content;
+        await this.client.postRawBody(this.contentsPath(pluginId, valid), payload);
+    }
+    /** Delete a file (or folder) from a dev plugin. */
+    async deleteFile(pluginId, path) {
+        await this.client.del(this.contentsPath(pluginId, validatePluginPath(path)));
+    }
+    /** Add a folder to a dev plugin. */
+    async addFolder(pluginId, path) {
+        const valid = validatePluginPath(path);
+        await this.client.post(`/public/api/plugins/${enc(pluginId)}/folders/${encodePluginPath(valid)}`, {});
+    }
+    /** Rename a file or folder inside a dev plugin (same parent folder). */
+    async rename(pluginId, path, newName) {
+        const validPath = validatePluginPath(path);
+        const validName = validatePluginName(newName);
+        await this.client.post(`/public/api/plugins/${enc(pluginId)}/contents-actions/rename`, { oldPath: `/${validPath}`, newName: validName, });
+    }
+    /** Move a file or folder inside a dev plugin. The destination folder must exist. */
+    async move(pluginId, path, destinationFolderPath) {
+        const validPath = validatePluginPath(path);
+        const destination = validatePluginDestinationPath(destinationFolderPath);
+        await this.client.post(`/public/api/plugins/${enc(pluginId)}/contents-actions/move`, { oldPath: `/${validPath}`, newPath: destination, });
+    }
+    /* ---- private ---- */
+    contentsPath(pluginId, path) {
+        return `/public/api/plugins/${enc(pluginId)}/contents/${encodePluginPath(path)}`;
+    }
+}
+/* ------------------------------------------------------------------ */
+/*  Shared helpers                                                     */
+/* ------------------------------------------------------------------ */
+function wrapUnknown(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : { value, };
+}
+function scopeQuery(projectKey) {
+    if (projectKey === undefined)
+        return "";
+    const trimmed = projectKey.trim();
+    if (trimmed === "")
+        return "";
+    return `?projectKey=${encodeURIComponent(trimmed)}`;
+}
+function requireJobId(raw, method) {
+    if (raw === undefined || raw === null || typeof raw.jobId !== "string" || raw.jobId === "") {
+        throw new DataikuError(200, "Unexpected Response", `${method}: DSS did not return a future jobId.`);
+    }
+    return raw;
+}
+/**
+ * Reject `https://user:token@host/repo` before it reaches DSS for plugin Git
+ * install/update/dev-create and the dev-plugin Git remote. Same policy as the
+ * project Git remotes: HTTP(S) URLs must not embed credentials; SSH and
+ * scp-style remotes stay allowed.
+ */
+export function validatedPluginGitUrl(repository, field = "Git repository URL") {
+    const candidate = repository.trim();
+    if (candidate === "")
+        throw new ClientValidationError(`${field} is required.`);
+    if (/[\u0000-\u001f\u007f]/u.test(candidate)) {
+        throw new ClientValidationError(`${field} must not contain control characters.`);
+    }
+    if (/^https?:/i.test(candidate)) {
+        if (!/^https?:\/\//i.test(candidate) || candidate.includes("\\")) {
+            throw new ClientValidationError(`${field} must be a valid HTTP(S) URL.`);
+        }
+        let parsed;
+        try {
+            parsed = new URL(candidate);
+        }
+        catch {
+            throw new ClientValidationError(`${field} must be a valid HTTP(S) URL.`);
+        }
+        if (parsed.username !== "" || parsed.password !== "") {
+            throw new ClientValidationError(`${field} must not embed credentials (user:password@host). `
+                + "Use an SSH remote or configure the Git credentials in DSS instead.");
+        }
+    }
+    return candidate;
+}
+/**
+ * True when a value is a usable plugin id shape without throwing — used by the
+ * CLI to decide which actions need a plugin id positional.
+ */
+export function isPluginIdCandidate(value) {
+    return typeof value === "string" && PLUGIN_ID_PATTERN.test(value);
+}
+// Re-exported for CLI consumers so a single import site covers path rules.
+export { validateGitReferencePath, };

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

@@ -0,0 +1,71 @@
+import { BaseResource } from "./base.js";
+/**
+ * Project folders form the instance-wide hierarchy in which projects live.
+ * These are NOT managed folders (see {@link FoldersResource} for project data
+ * storage); the project-folder API is an instance-level tree of containers.
+ *
+ * @see https://doc.dataiku.com/dss/api/15/rest/ (Project Folders section)
+ */
+export interface ProjectFolder extends Record<string, unknown> {
+    /** ID of the project folder. */
+    id?: string;
+    /** Name of the project folder (null for the root project folder). */
+    name?: string | null;
+    /** ID of the parent project folder (null for the root project folder). */
+    parentId?: string | null;
+    /** IDs of this project folder's children. */
+    childrenIds?: string[];
+    /** Project keys inside this project folder. */
+    projectKeys?: string[];
+}
+export interface ProjectFolderSettings extends Record<string, unknown> {
+    /** Name of the project folder. */
+    name?: string;
+    /** Login of the owner of the project folder. */
+    owner?: string;
+    /** Permissions of the project folder. */
+    permissions?: ProjectFolderPermission[] | null;
+}
+export interface ProjectFolderPermission extends Record<string, unknown> {
+    group?: string;
+    read?: boolean;
+    writeContents?: boolean;
+    admin?: boolean;
+}
+export declare class ProjectFoldersResource extends BaseResource {
+    /**
+     * Get the definition of the root project folder. Only items on which the
+     * API key has READ privilege for project folders (children) and READ_CONF
+     * for projects are listed.
+     */
+    root(): Promise<ProjectFolder>;
+    /** Get the definition of a project folder. Requires READ on the folder. */
+    get(folderId: string): Promise<ProjectFolder>;
+    /** Get the settings of a project folder. Requires ADMIN on the folder. */
+    getSettings(folderId: string): Promise<ProjectFolderSettings>;
+    /** Replace the settings of a project folder. Requires ADMIN on the folder. */
+    updateSettings(folderId: string, settings: ProjectFolderSettings): Promise<void>;
+    /**
+     * Move a project folder into another project folder (change its parent)
+     * along with its content. A folder cannot be moved into one of its own
+     * sub-folders. Requires ADMIN on the folder and WRITE_CONTENTS on the
+     * destination.
+     */
+    move(folderId: string, destinationId: string): Promise<void>;
+    /**
+     * Permanently delete a project folder. It must be empty: no sub-folders
+     * and no projects inside. Requires ADMIN on the folder.
+     */
+    delete(folderId: string): Promise<void>;
+    /**
+     * Create a sub-project folder within the given project folder. Requires
+     * WRITE_CONTENTS on the parent.
+     */
+    createChild(folderId: string, name: string): Promise<ProjectFolder>;
+    /**
+     * Move a project from the project folder it lives in to another project
+     * folder. Requires WRITE_CONTENTS on the destination folder and admin on
+     * the project.
+     */
+    moveProject(folderId: string, projectKey: string, destinationId: string): Promise<void>;
+}

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

@@ -0,0 +1,57 @@
+import { BaseResource, } from "./base.js";
+function folderPath(folderId) {
+    return `/public/api/project-folders/${encodeURIComponent(folderId)}`;
+}
+export class ProjectFoldersResource extends BaseResource {
+    /**
+     * Get the definition of the root project folder. Only items on which the
+     * API key has READ privilege for project folders (children) and READ_CONF
+     * for projects are listed.
+     */
+    async root() {
+        return this.client.get("/public/api/project-folders/");
+    }
+    /** Get the definition of a project folder. Requires READ on the folder. */
+    async get(folderId) {
+        return this.client.get(folderPath(folderId));
+    }
+    /** Get the settings of a project folder. Requires ADMIN on the folder. */
+    async getSettings(folderId) {
+        return this.client.get(`${folderPath(folderId)}/settings`);
+    }
+    /** Replace the settings of a project folder. Requires ADMIN on the folder. */
+    async updateSettings(folderId, settings) {
+        await this.client.putVoid(`${folderPath(folderId)}/settings`, settings);
+    }
+    /**
+     * Move a project folder into another project folder (change its parent)
+     * along with its content. A folder cannot be moved into one of its own
+     * sub-folders. Requires ADMIN on the folder and WRITE_CONTENTS on the
+     * destination.
+     */
+    async move(folderId, destinationId) {
+        await this.client.post(`${folderPath(folderId)}/move?destination=${encodeURIComponent(destinationId)}`);
+    }
+    /**
+     * Permanently delete a project folder. It must be empty: no sub-folders
+     * and no projects inside. Requires ADMIN on the folder.
+     */
+    async delete(folderId) {
+        await this.client.del(folderPath(folderId));
+    }
+    /**
+     * Create a sub-project folder within the given project folder. Requires
+     * WRITE_CONTENTS on the parent.
+     */
+    async createChild(folderId, name) {
+        return this.client.post(`${folderPath(folderId)}/children?name=${encodeURIComponent(name)}`);
+    }
+    /**
+     * Move a project from the project folder it lives in to another project
+     * folder. Requires WRITE_CONTENTS on the destination folder and admin on
+     * the project.
+     */
+    async moveProject(folderId, projectKey, destinationId) {
+        await this.client.post(`${folderPath(folderId)}/projects/${encodeURIComponent(projectKey)}/move?destination=${encodeURIComponent(destinationId)}`);
+    }
+}

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

@@ -62,6 +62,12 @@ export interface ProjectGitSetLibraryOptions {
 }
 export interface ProjectGitFutureStateOptions {
     peek?: boolean;
+    /**
+     * Total duration budget in milliseconds for this single state request,
+     * covering headers, retries, backoff, and body read. Intended for polling
+     * loops that must not hang on a stalled endpoint.
+     */
+    timeoutMs?: number;
 }
 export interface ProjectGitFutureWaitOptions {
     pollIntervalMs?: number;