dataiku-sdk 0.12.7 → 1.1.0

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

@@ -0,0 +1,427 @@
+import { ClientValidationError, DataikuError, } from "../errors.js";
+import { ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagsSchema, } from "../schemas.js";
+import { BaseResource, } from "./base.js";
+/**
+ * The per-project Git routes exist only under the dataikuapi base, not under
+ * the documented `/public/api` REST prefix used by the rest of this SDK, so
+ * this family carries its own mount point.
+ */
+const GIT_API_BASE = "/dip/publicapi";
+const DEFAULT_REMOTE = "origin";
+const DEFAULT_LOG_COUNT = 1_000;
+const DEFAULT_TAG_REFERENCE = "HEAD";
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_TIMEOUT_MS = 120_000;
+function sleep(ms) {
+    const { promise, resolve, } = Promise.withResolvers();
+    setTimeout(resolve, ms);
+    return promise;
+}
+function encodePathSegments(path) {
+    const normalized = path.replace(/^\/+/, "").replace(/\/+$/, "");
+    if (!normalized)
+        throw new ClientValidationError("A Git reference path is required.");
+    return normalized
+        .split("/")
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+/**
+ * Reject `https://user:token@host/repo` before it reaches DSS: an embedded
+ * secret would be stored in the project's Git configuration and echoed back by
+ * later reads. SSH and scp-style remotes (`git@host:org/repo.git`) are the
+ * documented way to authenticate and stay allowed.
+ */
+function validatedRepository(repository, field) {
+    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 (candidate.includes("\\")) {
+            throw new ClientValidationError(`${field} must be a valid HTTP(S) URL.`);
+        }
+        if (!/^https?:\/\//i.test(candidate)) {
+            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;
+}
+/** Replace every exact occurrence of a secret so echoed errors cannot leak it. */
+function redactSecrets(text, secrets) {
+    let result = text;
+    for (const secret of secrets) {
+        if (secret !== undefined && secret !== "") {
+            result = result.split(secret).join("[redacted]");
+        }
+    }
+    return result;
+}
+/**
+ * Strip a password that a server misconfiguration may have echoed from an
+ * error response. `DataikuError.message` was built at construction, so the
+ * raw body, the message, and the stack all need scrubbing.
+ */
+function scrubErrorSecrets(error, secrets) {
+    if (!(error instanceof DataikuError) || secrets.length === 0)
+        return;
+    error.body = redactSecrets(error.body, secrets);
+    error.message = redactSecrets(error.message, secrets);
+    if (typeof error.stack === "string") {
+        error.stack = redactSecrets(error.stack, secrets);
+    }
+}
+function describeFutureFailure(error) {
+    if (error === undefined || error === null)
+        return undefined;
+    if (typeof error === "string")
+        return error.trim() === "" ? undefined : error;
+    if (typeof error === "object") {
+        const record = error;
+        for (const key of ["detailedMessage", "message", "errorType",]) {
+            const value = record[key];
+            if (typeof value === "string" && value.trim() !== "")
+                return value;
+        }
+        return JSON.stringify(error);
+    }
+    return String(error);
+}
+/* ------------------------------------------------------------------ */
+/*  Resource                                                          */
+/* ------------------------------------------------------------------ */
+export class ProjectGitResource extends BaseResource {
+    /* ---- status & remotes ---- */
+    /** Working-copy status: current branch, remotes, tracking counts, changes. */
+    async status(projectKey) {
+        const raw = await this.request("GET", `${this.gitPath(projectKey)}/status`);
+        return this.client.safeParse(ProjectGitStatusSchema, raw ?? {}, "projectGit.status");
+    }
+    /**
+     * Read a Git remote. DSS answers `{}` when the remote is not configured.
+     * The remote name defaults to `origin` like the Python client.
+     */
+    async getRemote(projectKey, name = DEFAULT_REMOTE) {
+        const raw = await this.request("GET", `${this.gitPath(projectKey)}/remotes/${encodeURIComponent(name)}`);
+        return this.client.safeParse(ProjectGitRemoteSchema, raw ?? {}, "projectGit.getRemote");
+    }
+    /** Create or replace a Git remote. */
+    async setRemote(projectKey, options) {
+        const repository = validatedRepository(options.url, "Git remote URL");
+        const raw = await this.request("POST", `${this.gitPath(projectKey)}/remotes/${encodeURIComponent(options.name ?? DEFAULT_REMOTE)}`, { url: repository, });
+        return this.client.safeParse(ProjectGitActionResultSchema, raw ?? {}, "projectGit.setRemote");
+    }
+    /** Delete a Git remote. */
+    async removeRemote(projectKey, name = DEFAULT_REMOTE) {
+        await this.request("DELETE", `${this.gitPath(projectKey)}/remotes/${encodeURIComponent(name)}`);
+    }
+    /* ---- branches ---- */
+    /** Plain list of branch names, local by default. */
+    async listBranches(projectKey, remote = false) {
+        const raw = await this.request("GET", `${this.gitPath(projectKey)}/branches${this.query({ remote, })}`);
+        return (raw ?? []);
+    }
+    /**
+     * Create a branch and switch to it. With `duplicateProject`, DSS creates a
+     * duplicate project for the branch instead of moving this one.
+     */
+    async createBranch(projectKey, name, options = {}) {
+        // DSS consumes the full key set, so absent values travel as nulls.
+        const raw = await this.request("POST", `${this.gitPath(projectKey)}/branches/`, {
+            name,
+            commit: options.commit ?? null,
+            duplicateProject: options.duplicateProject ?? false,
+            targetProjectKey: options.targetProjectKey ?? null,
+            targetProjectFolderId: options.targetProjectFolderId ?? null,
+        });
+        return this.client.safeParse(ProjectGitActionResultSchema, raw ?? {}, "projectGit.createBranch");
+    }
+    /** Delete a branch locally and, with `deleteRemotely`, on the remote too. */
+    async deleteBranch(projectKey, name, options = {}) {
+        const raw = await this.request("POST", `${this.actionPath(projectKey)}/deleteBranch`, {
+            name,
+            remote: options.remote ?? false,
+            deleteRemotely: options.deleteRemotely ?? false,
+            forceDelete: options.forceDelete ?? false,
+        });
+        return this.client.safeParse(ProjectGitActionResultSchema, raw ?? {}, "projectGit.deleteBranch");
+    }
+    /** Current branch name, or null when DSS reports none. */
+    async currentBranch(projectKey) {
+        const raw = await this.request("GET", `${this.gitPath(projectKey)}/current-branch`);
+        const name = raw?.name;
+        return typeof name === "string" && name !== "" ? name : null;
+    }
+    /** Switch the project to another branch. */
+    async switchBranch(projectKey, branchName) {
+        const raw = await this.request("POST", `${this.actionPath(projectKey)}/switchBranch${this.query({ branchName, })}`);
+        return this.client.safeParse(ProjectGitActionResultSchema, raw ?? {}, "projectGit.switchBranch");
+    }
+    /* ---- tags ---- */
+    async listTags(projectKey) {
+        const raw = await this.request("GET", `${this.gitPath(projectKey)}/tags`);
+        return this.client.safeParse(ProjectGitTagsSchema, raw ?? [], "projectGit.listTags");
+    }
+    async createTag(projectKey, name, options = {}) {
+        const raw = await this.request("POST", `${this.gitPath(projectKey)}/tags/`, {
+            name,
+            reference: options.reference ?? DEFAULT_TAG_REFERENCE,
+            message: options.message ?? "",
+        });
+        return this.client.safeParse(ProjectGitActionResultSchema, raw ?? {}, "projectGit.createTag");
+    }
+    async deleteTag(projectKey, name) {
+        const raw = await this.request("POST", `${this.actionPath(projectKey)}/deleteTag`, {
+            name,
+        });
+        return this.client.safeParse(ProjectGitActionResultSchema, raw ?? {}, "projectGit.deleteTag");
+    }
+    /* ---- synchronous Git actions ---- */
+    /** Fetch from the remote. Failures arrive as `{success: false}` with HTTP 200. */
+    async fetch(projectKey) {
+        const raw = await this.request("POST", `${this.actionPath(projectKey)}/fetch`);
+        return this.client.safeParse(ProjectGitActionResultSchema, raw ?? {}, "projectGit.fetch");
+    }
+    /** Pull. DSS only ever exposes a rebase pull; there is no merge variant. */
+    async pull(projectKey, options = {}) {
+        const raw = await this.request("POST", `${this.actionPath(projectKey)}/pullRebase${this.query({ branchName: options.branchName, })}`);
+        return this.client.safeParse(ProjectGitActionResultSchema, raw ?? {}, "projectGit.pull");
+    }
+    async push(projectKey, options = {}) {
+        const raw = await this.request("POST", `${this.actionPath(projectKey)}/push${this.query({ branchName: options.branchName, })}`);
+        return this.client.safeParse(ProjectGitActionResultSchema, raw ?? {}, "projectGit.push");
+    }
+    /** Commit log page. Paginate by passing the previous `nextCommit` as `startCommit`. */
+    async log(projectKey, options = {}) {
+        const raw = await this.request("GET", `${this.actionPath(projectKey)}/log${this.query({
+            path: options.path,
+            startCommit: options.startCommit,
+            count: options.count ?? DEFAULT_LOG_COUNT,
+        })}`);
+        return this.client.safeParse(ProjectGitLogResultSchema, raw ?? { entries: [], }, "projectGit.log");
+    }
+    async diff(projectKey, options = {}) {
+        const raw = await this.request("GET", `${this.actionPath(projectKey)}/diff${this.query({ commitFrom: options.commitFrom, commitTo: options.commitTo, })}`);
+        return this.client.safeParse(ProjectGitDiffResultSchema, raw ?? {}, "projectGit.diff");
+    }
+    /** Commit the project. DSS stages untracked files before committing. */
+    async commit(projectKey, options) {
+        const raw = await this.request("POST", `${this.actionPath(projectKey)}/commit`, {
+            message: options.message,
+        });
+        return this.client.safeParse(ProjectGitActionResultSchema, raw ?? {}, "projectGit.commit");
+    }
+    /** Restore the project to the state of a past commit. */
+    async revertToRevision(projectKey, commit) {
+        const raw = await this.request("POST", `${this.actionPath(projectKey)}/revertToRevision${this.query({ commit, })}`);
+        return this.client.safeParse(ProjectGitActionResultSchema, raw ?? {}, "projectGit.revertToRevision");
+    }
+    /** Revert one commit, keeping later history. */
+    async revertCommit(projectKey, commit) {
+        const raw = await this.request("POST", `${this.actionPath(projectKey)}/revertCommit${this.query({ commit, })}`);
+        return this.client.safeParse(ProjectGitActionResultSchema, raw ?? {}, "projectGit.revertCommit");
+    }
+    /** Hard reset to local HEAD, dropping uncommitted changes. */
+    async resetToHead(projectKey) {
+        const raw = await this.request("POST", `${this.actionPath(projectKey)}/resetToLocalHeadState`);
+        return this.client.safeParse(ProjectGitActionResultSchema, raw ?? {}, "projectGit.resetToHead");
+    }
+    /** Hard reset to the tracked upstream branch, dropping local commits. */
+    async resetToUpstream(projectKey) {
+        const raw = await this.request("POST", `${this.actionPath(projectKey)}/resetToRemoteHeadState`);
+        return this.client.safeParse(ProjectGitActionResultSchema, raw ?? {}, "projectGit.resetToUpstream");
+    }
+    /**
+     * Wipe the project's entire Git history and rebuild a fresh repository.
+     * Irreversible, so nothing is sent unless the caller acknowledges it.
+     */
+    async dropAndRebuild(projectKey, options = {}) {
+        if (options.confirmed !== true) {
+            throw new ClientValidationError("projectGit.dropAndRebuild permanently destroys the project's Git history. "
+                + "Pass { confirmed: true } to acknowledge before calling it.");
+        }
+        const raw = await this.request("POST", `${this.actionPath(projectKey)}/dropAndRebuild${this.query({ iKnowWhatIAmDoing: true, })}`);
+        return this.client.safeParse(ProjectGitActionResultSchema, raw ?? {}, "projectGit.dropAndRebuild");
+    }
+    /* ---- external libraries (async futures) ---- */
+    async listLibraries(projectKey) {
+        const raw = await this.request("GET", `${this.libraryPath(projectKey)}/`);
+        return this.client.safeParse(ProjectGitLibrariesSchema, raw ?? [], "projectGit.listLibraries");
+    }
+    /** Attach an external Git library. Runs as a DSS future. */
+    async addLibrary(projectKey, options) {
+        const repository = validatedRepository(options.repository, "Git library repository URL");
+        const secrets = [options.password,].filter((secret) => secret !== undefined && secret !== "");
+        const raw = await this.request("POST", `${this.libraryPath(projectKey)}/`, {
+            repository,
+            login: options.login ?? null,
+            password: options.password ?? null,
+            pathInGitRepository: options.pathInGitRepository ?? "",
+            localTargetPath: options.localTargetPath,
+            checkout: options.checkout,
+            addToPythonPath: options.addToPythonPath ?? true,
+        }, secrets);
+        return this.client.safeParse(ProjectGitFutureResponseSchema, raw ?? {}, "projectGit.addLibrary");
+    }
+    /** Update an attached library's repository, sub-path, or checkout. */
+    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)}`, {
+            repository,
+            login: options.login ?? null,
+            password: options.password ?? null,
+            pathInGitRepository: options.pathInGitRepository ?? "",
+            checkout: options.checkout,
+        }, secrets);
+        return raw;
+    }
+    /** 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, })}`);
+    }
+    /** Reset one library to its remote state. Runs as a DSS future. */
+    async resetLibrary(projectKey, gitReferencePath) {
+        const raw = await this.request("POST", `${this.libraryPath(projectKey)}/action/reset`, {
+            gitRef: gitReferencePath,
+        });
+        return this.client.safeParse(ProjectGitFutureResponseSchema, raw ?? {}, "projectGit.resetLibrary");
+    }
+    /** Commit and push one library. Runs as a DSS future. */
+    async pushLibrary(projectKey, gitReferencePath, commitMessage) {
+        const raw = await this.request("POST", `${this.libraryPath(projectKey)}/action/push`, {
+            gitRef: gitReferencePath,
+            commitMessage,
+        });
+        return this.client.safeParse(ProjectGitFutureResponseSchema, raw ?? {}, "projectGit.pushLibrary");
+    }
+    /** Commit and push every attached library. Runs as a DSS future. */
+    async pushAllLibraries(projectKey, commitMessage) {
+        const raw = await this.request("POST", `${this.actionPath(projectKey)}/git-refs/push-all`, { commitMessage, });
+        return this.client.safeParse(ProjectGitFutureResponseSchema, raw ?? {}, "projectGit.pushAllLibraries");
+    }
+    /** Reset every attached library to its remote state. Runs as a DSS future. */
+    async resetAllLibraries(projectKey) {
+        const raw = await this.request("POST", `${this.actionPath(projectKey)}/git-refs/reset-all`);
+        return this.client.safeParse(ProjectGitFutureResponseSchema, raw ?? {}, "projectGit.resetAllLibraries");
+    }
+    /* ---- futures ---- */
+    /**
+     * Read a future's state. `peek` leaves the future's log unconsumed, which is
+     * what polling loops want; the default consumes it like the Python client.
+     */
+    async getFutureState(jobId, options = {}) {
+        const raw = await this.request("GET", `/futures/${encodeURIComponent(jobId)}${this.query({ peek: options.peek === true, })}`);
+        return this.client.safeParse(ProjectGitFutureStateSchema, raw ?? {}, "projectGit.getFutureState");
+    }
+    /** Abort a running future. */
+    async abortFuture(jobId) {
+        await this.request("DELETE", `/futures/${encodeURIComponent(jobId)}`);
+    }
+    /**
+     * Poll until the future carries a result and return that result. Throws on
+     * an aborted or failed future and on an exhausted budget, so a caller never
+     * mistakes an unfinished future for a successful one.
+     */
+    async waitForFuture(jobId, options = {}) {
+        const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        if (!Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0) {
+            throw new ClientValidationError("pollIntervalMs must be a finite positive number.");
+        }
+        if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+            throw new ClientValidationError("timeoutMs must be a finite non-negative number.");
+        }
+        const startedAt = Date.now();
+        while (true) {
+            // Unlike peek state, the ordinary state includes the completed result.
+            const state = await this.getFutureState(jobId, { peek: false, });
+            const failure = describeFutureFailure(state.error);
+            if (failure !== undefined) {
+                throw new Error(`Dataiku future ${jobId} failed: ${failure}`);
+            }
+            if (state.aborted === true) {
+                throw new Error(`Dataiku future ${jobId} was aborted`);
+            }
+            if (state.hasResult === true)
+                return state.result;
+            if (state.unknown === true) {
+                throw new Error(`Dataiku future ${jobId} is unknown to the server`);
+            }
+            if (state.alive === false) {
+                throw new Error(`Dataiku future ${jobId} ended without producing a result`);
+            }
+            // Only the remaining budget is slept, so a caller's deadline is never
+            // overshot by a whole poll interval.
+            const elapsedMs = Date.now() - startedAt;
+            if (elapsedMs >= timeoutMs) {
+                throw new Error(`Timed out after ${String(elapsedMs)}ms waiting for Dataiku future ${jobId}`);
+            }
+            await sleep(Math.min(pollIntervalMs, timeoutMs - elapsedMs));
+        }
+    }
+    /* ---- private ---- */
+    gitPath(projectKey) {
+        return `/projects/${this.enc(projectKey)}/git`;
+    }
+    actionPath(projectKey) {
+        return `${this.gitPath(projectKey)}/actions`;
+    }
+    libraryPath(projectKey) {
+        return `${this.gitPath(projectKey)}/lib-git-refs`;
+    }
+    query(params) {
+        const search = new URLSearchParams();
+        for (const [key, value,] of Object.entries(params)) {
+            if (value === undefined)
+                continue;
+            search.set(key, String(value));
+        }
+        const queryString = search.toString();
+        return queryString === "" ? "" : `?${queryString}`;
+    }
+    async request(method, path, body, secrets = []) {
+        const transport = this.client;
+        const init = {
+            method,
+            headers: {
+                // The Git routes are only reachable with dataikuapi-style Basic auth:
+                // API key as the username, empty password.
+                Authorization: `Basic ${Buffer.from(`${transport.apiKey}:`, "utf8").toString("base64")}`,
+                Accept: "application/json",
+                "Content-Type": "application/json",
+            },
+        };
+        if (body !== undefined)
+            init.body = JSON.stringify(body);
+        try {
+            const res = await transport.fetchWithRetry(`${transport.baseUrl}${GIT_API_BASE}${path}`, init);
+            const text = await res.text();
+            if (text.trim() === "")
+                return undefined;
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new Error(`Dataiku Git API returned a non-JSON response for ${method} ${path}`);
+            }
+        }
+        catch (error) {
+            scrubErrorSecrets(error, secrets);
+            throw error;
+        }
+    }
+}

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

@@ -64,10 +64,30 @@ export interface ProjectImportUploadResult {
     id: string;
     [key: string]: unknown;
 }
+export interface ProjectImportSettings {
+    targetProjectKey?: string;
+    remapping?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface ProjectImportProcessResult {
+    /** Present on definitive responses; a missing or non-boolean value makes the outcome indeterminate. */
+    success?: boolean;
+    /** Project key DSS actually created (after remapping). Definitive success includes it. */
+    usedProjectKey?: string;
+    [key: string]: unknown;
+}
+export interface ProjectImportResult extends ProjectImportProcessResult {
+    importId: string;
+    /** Key the import was bound to: the explicit settings target, else the archive manifest's key. Known on success. */
+    requestedProjectKey?: string;
+    /** True when usedProjectKey differs from requestedProjectKey (set only when both are known). */
+    remapped?: boolean;
+    /** SHA-256 fingerprint of the landed project's creationTag. Present on verified success. */
+    projectIncarnationHash?: string;
+}
 export declare class ProjectsResource extends BaseResource {
     private httpInternals;
     private postStream;
-    private uploadJson;
     /** Create a new project. */
     createProject(projectKey: string, name: string, ownerLogin: string, settings?: ProjectLifecycleSettings | null): Promise<Record<string, unknown>>;
     /** Delete a project using the lifecycle endpoint. */
@@ -76,8 +96,21 @@ export declare class ProjectsResource extends BaseResource {
     duplicate(projectKey: string, targetProjectKey: string, targetProjectName: string, options?: ProjectDuplicateOptions): Promise<Record<string, unknown>>;
     /** Export a project archive to a local file. */
     exportArchive(projectKey: string, filePath: string, options?: ProjectExportOptions): Promise<void>;
-    /** Upload a project archive and return the temporary import id. */
-    importProjectFromArchive(filePath: string): Promise<ProjectImportUploadResult>;
+    /** Upload a project archive and return its temporary import handle. */
+    prepareProjectImport(filePath: string): Promise<ProjectImportUploadResult>;
+    /** Process an uploaded archive into a DSS project. */
+    processProjectImport(importId: string, settings?: ProjectImportSettings): Promise<ProjectImportProcessResult>;
+    /**
+     * Upload and process a project archive.
+     *
+     * The archive is validated locally before anything is uploaded. Definitive
+     * failures surface the process response verbatim (with `importId`); every
+     * indeterminate path throws ClientValidationError(`ambiguous_outcome`).
+     * Verified success carries the actually-used project key, the requested
+     * key when known (with explicit `remapped` reporting), and the landed
+     * project's incarnation hash for identity-bound cleanup and guarded deletes.
+     */
+    importProjectFromArchive(filePath: string, settings?: ProjectImportSettings): Promise<ProjectImportResult>;
     /** Get project permissions. */
     getPermissions(projectKey?: string): Promise<ProjectPermissions>;
     /** Set project permissions. */

package/dist/src/resources/projects.js

@@ -1,7 +1,10 @@
-import { createWriteStream, openAsBlob, } from "node:fs";
+import { createWriteStream, } from "node:fs";
 import { Writable, } from "node:stream";
+import { ClientValidationError, DataikuError, } from "../errors.js";
 import { ProjectDetailsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, } from "../schemas.js";
 import { normalizeFlowGraph, } from "../utils/flow-map.js";
+import { assertImportableProjectArchive, } from "../utils/project-archive.js";
+import { projectIncarnationHash, } from "../utils/project-incarnation.js";
 import { BaseResource, } from "./base.js";
 function fetchWithTimeout(label, timeoutMs, fetcher) {
     return new Promise((resolve) => {
@@ -100,6 +103,7 @@ function truncateFlowMap(normalized, maxNodes, maxEdges) {
 const DEFAULT_MAX_NODES = 300;
 const DEFAULT_MAX_EDGES = 600;
 const DEFAULT_METADATA_TIMEOUT_MS = 1_500;
+const PROJECT_IMPORT_AMBIGUOUS_REMEDIATION = "Import processing left DSS state indeterminate. Inspect the archive with `dss project inspect-archive <file>` and the live projects with `dss project list` before retrying the import.";
 export class ProjectsResource extends BaseResource {
     httpInternals() {
         return this.client;
@@ -116,18 +120,6 @@ export class ProjectsResource extends BaseResource {
             body: JSON.stringify(body),
         });
     }
-    async uploadJson(path, filePath, fileName) {
-        const http = this.httpInternals();
-        const fileBlob = await openAsBlob(filePath);
-        const formData = new FormData();
-        formData.append("file", fileBlob, fileName);
-        const res = await http.fetchWithRetry(`${http.baseUrl}${path}`, {
-            method: "POST",
-            headers: { Authorization: `Bearer ${http.apiKey}`, },
-            body: formData,
-        });
-        return res.json();
-    }
     /** Create a new project. */
     async createProject(projectKey, name, ownerLogin, settings) {
         return this.client.post("/public/api/projects/", {
@@ -176,9 +168,128 @@ export class ProjectsResource extends BaseResource {
             throw error;
         }
     }
-    /** Upload a project archive and return the temporary import id. */
-    async importProjectFromArchive(filePath) {
-        return this.uploadJson("/public/api/projects/import/upload", filePath, "tmp-import.zip");
+    /** Upload a project archive and return its temporary import handle. */
+    async prepareProjectImport(filePath) {
+        const upload = await this.client.uploadJson("/public/api/projects/import/upload", filePath, "tmp-import.zip");
+        if (!upload || typeof upload.id !== "string" || upload.id.trim() === "") {
+            throw new ClientValidationError("DSS accepted the project archive upload but did not return a temporary import id.", "ambiguous_outcome", "The archive may remain in temporary DSS storage, but no project import was started. Inspect DSS before retrying.");
+        }
+        return upload;
+    }
+    /** Process an uploaded archive into a DSS project. */
+    async processProjectImport(importId, settings = {}) {
+        const body = Object.keys(settings).length === 0 ? { _: "_", } : settings;
+        try {
+            const response = await this.client.post(`/public/api/projects/import/${encodeURIComponent(importId)}/process`, body);
+            // An empty or null 2xx body carries no definitive outcome: DSS may
+            // have created the project, partially processed it, or done nothing.
+            if (!response) {
+                throw new ClientValidationError("DSS accepted the import process request but returned no response body: the project may or may not have been created.", "ambiguous_outcome", PROJECT_IMPORT_AMBIGUOUS_REMEDIATION, {
+                    importId,
+                    ...(typeof settings.targetProjectKey === "string"
+                        && settings.targetProjectKey.trim() !== ""
+                        ? { targetProjectKey: settings.targetProjectKey, }
+                        : {}),
+                });
+            }
+            return response;
+        }
+        catch (error) {
+            // A transport timeout or server-side 5xx leaves the import outcome
+            // unknowable: the project may or may not exist. Surface that as an
+            // ambiguous outcome — never as a definitive failure. A 2xx
+            // response that carried a non-JSON body has the same property.
+            if (error instanceof DataikuError
+                && (error.status === 0
+                    || error.status >= 500
+                    || (error.status >= 200 && error.status < 300))) {
+                throw new ClientValidationError(error.status >= 200 && error.status < 300
+                    ? "DSS returned a non-JSON process response: the import outcome is indeterminate and the project may or may not have been created."
+                    : "DSS returned no definitive import result: the project may or may not have been created.", "ambiguous_outcome", PROJECT_IMPORT_AMBIGUOUS_REMEDIATION, {
+                    importId,
+                    ...(typeof settings.targetProjectKey === "string"
+                        && settings.targetProjectKey.trim() !== ""
+                        ? { targetProjectKey: settings.targetProjectKey, }
+                        : {}),
+                });
+            }
+            throw error;
+        }
+    }
+    /**
+     * Upload and process a project archive.
+     *
+     * The archive is validated locally before anything is uploaded. Definitive
+     * failures surface the process response verbatim (with `importId`); every
+     * indeterminate path throws ClientValidationError(`ambiguous_outcome`).
+     * Verified success carries the actually-used project key, the requested
+     * key when known (with explicit `remapped` reporting), and the landed
+     * project's incarnation hash for identity-bound cleanup and guarded deletes.
+     */
+    async importProjectFromArchive(filePath, settings = {}) {
+        // Fatal archive problems abort before any DSS call or upload.
+        const inspection = await assertImportableProjectArchive(filePath);
+        const requestedProjectKey = typeof settings.targetProjectKey === "string"
+            && settings.targetProjectKey.trim() !== ""
+            ? settings.targetProjectKey
+            : inspection.sourceProjectKey;
+        const upload = await this.prepareProjectImport(filePath);
+        const result = await this.processProjectImport(upload.id, settings);
+        const importId = upload.id;
+        if (typeof result.success !== "boolean") {
+            throw new ClientValidationError("DSS returned a process response without a boolean success field: the import outcome is indeterminate.", "ambiguous_outcome", PROJECT_IMPORT_AMBIGUOUS_REMEDIATION, {
+                importId,
+                ...(requestedProjectKey !== undefined
+                    ? { targetProjectKey: requestedProjectKey, }
+                    : {}),
+            });
+        }
+        if (result.success === false) {
+            // Definitive DSS-side failure: keep the response authoritative and
+            // let the command layer report it as a plain command failure.
+            return { ...result, success: false, importId, };
+        }
+        const usedProjectKey = typeof result.usedProjectKey === "string"
+            && result.usedProjectKey.trim() !== ""
+            ? result.usedProjectKey
+            : undefined;
+        if (usedProjectKey === undefined) {
+            throw new ClientValidationError("DSS reported import success but did not name the project that was created.", "ambiguous_outcome", PROJECT_IMPORT_AMBIGUOUS_REMEDIATION, {
+                importId,
+                ...(requestedProjectKey !== undefined
+                    ? { targetProjectKey: requestedProjectKey, }
+                    : {}),
+            });
+        }
+        // Verify the claimed landing and capture identity for cleanup binding.
+        let details;
+        try {
+            details = await this.get(usedProjectKey);
+        }
+        catch (error) {
+            if (error instanceof DataikuError
+                && (error.status === 404 || error.status === 0 || error.status >= 500)) {
+                throw new ClientValidationError(`DSS reported import success for project ${usedProjectKey}, but the project could not be re-read for verification.`, "ambiguous_outcome", PROJECT_IMPORT_AMBIGUOUS_REMEDIATION, { importId, usedProjectKey, });
+            }
+            throw error;
+        }
+        const incarnation = projectIncarnationHash(usedProjectKey, details);
+        if (incarnation === undefined) {
+            throw new ClientValidationError(`DSS imported project ${usedProjectKey}, but returned no creationTag identity.`, "ambiguous_outcome", "Refusing to claim identity-bound success without a project-incarnation hash. Verify the project identity before any cleanup or guarded delete.", { importId, usedProjectKey, });
+        }
+        return {
+            ...result,
+            success: true,
+            importId,
+            usedProjectKey,
+            projectIncarnationHash: incarnation,
+            ...(requestedProjectKey === undefined
+                ? {}
+                : {
+                    requestedProjectKey,
+                    remapped: requestedProjectKey !== usedProjectKey,
+                }),
+        };
     }
     /** Get project permissions. */
     async getPermissions(projectKey) {