dataiku-sdk 3.2.0 → 3.4.0

package/dist/src/resources/notebooks.js

@@ -139,31 +139,71 @@ export class NotebooksResource extends BaseResource {
         const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/${idEnc}`);
         return this.client.safeParse(SqlNotebookContentSchema, raw, "notebooks.getSql");
     }
-    /** Create a SQL notebook. */
-    async createSql(id, content, projectKey) {
-        await this.client.post(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/`, { ...content, id, projectKey: this.resolveProjectKey(projectKey), });
+    /**
+     * Create a SQL notebook.
+     *
+     * DSS allocates the notebook id server-side and rejects a request-supplied
+     * `id` (`Field 'id' is specified, it must not be specified`); `name` is
+     * the display handle (the requested label) when provided. The returned id
+     * comes from the creation receipt and is the only handle later reads,
+     * updates, and deletes may use.
+     */
+    async createSql(content, projectKey, opts) {
+        const body = {
+            ...content,
+            projectKey: this.resolveProjectKey(projectKey),
+        };
+        // Positional identity only: a content-supplied id (e.g. a stale GET
+        // spread) is stripped before the request — DSS rejects it outright.
+        delete body["id"];
+        if (opts?.name !== undefined && body["name"] === undefined)
+            body["name"] = opts.name;
+        const raw = await this.client.post(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/`, body);
+        const record = raw !== null && typeof raw === "object" && !Array.isArray(raw)
+            ? raw
+            : undefined;
+        const id = record?.["id"];
+        if (typeof id !== "string" || id.length === 0) {
+            throw new DataikuError(200, "Unexpected Response", "notebooks.createSql: DSS did not return the generated notebook id.");
+        }
+        return { id, };
     }
-    /** Save (overwrite) a SQL notebook's content. */
+    /**
+     * Save (overwrite) a SQL notebook's content.
+     *
+     * Identity is positional: the URL id and the resolved project key are
+     * injected into the body, overriding any `id`/`projectKey` the content may
+     * carry, so a stale or hand-built body can never retarget the write. PUT
+     * is a full replacement — fields absent from the content (e.g. `name`)
+     * are cleared server-side.
+     */
     async saveSql(id, content, projectKey) {
         const idEnc = encodeURIComponent(id);
-        await this.client.putVoid(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/${idEnc}`, content);
+        await this.client.putVoid(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/${idEnc}`, { ...content, id, projectKey: this.resolveProjectKey(projectKey), });
     }
     /**
-     * Save a SQL notebook, creating it when missing. Same contract as
-     * `saveOrCreateJupyter`: `created` reflects the fresh read, and `hash` is
-     * the hash of the persisted content from a confirming re-read.
+     * Save a SQL notebook, creating it when missing.
+     *
+     * Update path: the fresh read finds the notebook and a PUT overwrites it.
+     * Create path: DSS allocates the persisted id (the requested handle becomes
+     * the display name; there is no name-based re-lookup, so a foreign
+     * notebook can never be mistaken for the target), the id is returned, and
+     * every later read/update/delete must use that returned id. `created`
+     * reflects the fresh read; `hash` is the hash of the persisted content
+     * from a confirming re-read. The armed `--expect-hash` guard also refuses
+     * an absent target.
      */
     async saveOrCreateSql(id, content, projectKey, opts) {
         const pk = this.resolveProjectKey(projectKey);
         const before = await this.prepareSave(() => this.getSql(id, pk), opts?.expectHash, pk, "SQL notebook", id);
         if (before === undefined) {
-            await this.createSql(id, content, pk);
-        }
-        else {
-            await this.saveSql(id, content, pk);
+            const created = await this.createSql(content, pk, { name: id, });
+            const persisted = await this.getSql(created.id, pk);
+            return { created: true, id: created.id, hash: stableHash(persisted), };
         }
+        await this.saveSql(id, content, pk);
         const persisted = await this.getSql(id, pk);
-        return { created: before === undefined, hash: stableHash(persisted), };
+        return { created: false, id, hash: stableHash(persisted), };
     }
     /** Delete a SQL notebook. */
     async deleteSql(id, projectKey) {

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

@@ -0,0 +1,263 @@
+import { BaseResource } from "./base.js";
+/** Summary entry of `/plugins/` as documented (id/version/isDev/meta). */
+export interface PluginSummary {
+    id: string;
+    version?: string;
+    isDev?: boolean;
+    meta?: {
+        label?: string;
+        description?: string;
+        /** Opaque server-authored metadata (icon, author, tags, ...). */
+        [key: string]: unknown;
+    };
+    /** Opaque server fields are preserved. */
+    [key: string]: unknown;
+}
+/** Settings of a plugin (config dict + optional code env name). */
+export interface PluginSettings {
+    config?: Record<string, unknown>;
+    codeEnvName?: string;
+    [key: string]: unknown;
+}
+/** One usage entry of a plugin element, as returned by listUsages. */
+export interface PluginUsage {
+    elementKind?: string;
+    elementType?: string;
+    objectId?: string;
+    objectType?: string;
+    projectKey?: string;
+    [key: string]: unknown;
+}
+/** One missing-type entry of a plugin usage analysis. */
+export interface PluginMissingType {
+    missingType?: string;
+    objectId?: string;
+    objectType?: string;
+    projectKey?: string;
+    [key: string]: unknown;
+}
+export interface PluginUsageReport {
+    usages?: PluginUsage[];
+    missingTypes?: PluginMissingType[];
+    [key: string]: unknown;
+}
+/** Contents-tree item of a dev plugin (mirrors the library listing shape). */
+export interface PluginContentItem {
+    name: string;
+    /** Full plugin-relative path as observed from DSS contents listings. */
+    path?: string;
+    mimeType?: string;
+    size?: number;
+    hasData?: boolean;
+    lastModified?: number;
+    children?: PluginContentItem[];
+    [key: string]: unknown;
+}
+/** Detail record of a single plugin file (`/plugins/{id}/details/{path}`). */
+export interface PluginFileDetails {
+    name?: string;
+    path?: string;
+    mimeType?: string;
+    size?: number;
+    hasData?: boolean;
+    readOnly?: boolean;
+    lastModified?: number;
+    [key: string]: unknown;
+}
+/** Git remote info of a dev plugin (`repositoryUrl` is null when unset). */
+export interface PluginGitRemote {
+    repositoryUrl: string | null;
+    [key: string]: unknown;
+}
+/** Options for creating a development plugin. */
+export interface PluginCreateDevOptions {
+    pluginId: string;
+    creationMode: "EMPTY" | "GIT_CLONE" | "GIT_EXPORT";
+    gitRepository?: string;
+    gitCheckout?: string;
+    gitSubpath?: string;
+}
+/** Options for installing/updating a plugin from Git. */
+export interface PluginGitInstallOptions {
+    gitRepositoryUrl: string;
+    gitCheckout?: string;
+    gitSubpath?: string;
+}
+/** Options for creating the code env of a plugin. */
+export interface PluginCodeEnvCreateOptions {
+    conda?: boolean;
+    pythonInterpreter?: string;
+}
+/** Scope selectors for plugin settings and usage analysis. */
+export interface PluginProjectScopeOptions {
+    projectKey?: string;
+}
+/**
+ * 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 declare function validatePluginId(pluginId: string): string;
+/**
+ * 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 declare function validatePluginPath(path: string): string;
+/**
+ * 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 declare function validatePluginDestinationPath(path: string): string;
+/** Validate a rename target: a single plugin path segment, no '/'. */
+export declare function validatePluginName(name: string): string;
+/** Validate and URL-encode each segment of a plugin path for endpoint use. */
+export declare function encodePluginPath(path: string): string;
+/**
+ * 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 declare class PluginsResource extends BaseResource {
+    /** List installed plugins (including dev plugins). */
+    list(): Promise<PluginSummary[]>;
+    /**
+     * 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.
+     */
+    installFromZip(filePath: string): Promise<void>;
+    /** Install a plugin from the Dataiku store. Fails if already installed. */
+    installFromStore(pluginId: string): Promise<void>;
+    /** Install a plugin by checking out a Git repository. Fails if already installed. */
+    installFromGit(options: PluginGitInstallOptions): Promise<void>;
+    /** Download a development plugin as a zip archive. */
+    download(pluginId: string): Promise<Response>;
+    /**
+     * Update a plugin from a local zip file. Fails if not already installed.
+     * Resolves only after the update completed (future receipt settled).
+     */
+    updateFromZip(pluginId: string, filePath: string): Promise<void>;
+    /** Update a plugin from the Dataiku Store. */
+    updateFromStore(pluginId: string): Promise<void>;
+    /**
+     * Update an installed plugin from Git. Fails if the plugin is not already
+     * installed. Resolves only after the update completed (future settled).
+     */
+    updateFromGit(pluginId: string, options: PluginGitInstallOptions): Promise<void>;
+    /**
+     * Move an installed plugin to the development environment. Resolves only
+     * after the move completed (future receipt settled).
+     */
+    moveToDev(pluginId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    delete(pluginId: string, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    /** Get plugin settings (optionally scoped to a project). */
+    getSettings(pluginId: string, options?: PluginProjectScopeOptions): Promise<PluginSettings>;
+    /**
+     * 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.
+     */
+    setSettings(pluginId: string, settings: PluginSettings, options?: PluginProjectScopeOptions): Promise<void>;
+    /** List usages of the plugin's elements, optionally scoped to a project. */
+    listUsages(pluginId: string, options?: PluginProjectScopeOptions): Promise<PluginUsageReport>;
+    /**
+     * 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.
+     */
+    createCodeEnv(pluginId: string, options?: PluginCodeEnvCreateOptions): Promise<{
+        jobId: string;
+    } & Record<string, unknown>>;
+    /** Update the code env of a plugin. Returns the DSS future handle. */
+    updateCodeEnv(pluginId: string): Promise<{
+        jobId: string;
+    } & Record<string, unknown>>;
+    /** Create a new development plugin (empty, cloned, or exported from Git). */
+    createDev(options: PluginCreateDevOptions): Promise<void>;
+    /** Get the Git remote declared for a dev plugin (null when unset). */
+    getGitRemote(pluginId: string): Promise<PluginGitRemote>;
+    /** Set (create or replace) the Git remote of a dev plugin. */
+    setGitRemote(pluginId: string, repositoryUrl: string): Promise<PluginGitRemote>;
+    /** Delete the Git remote declared for a dev plugin. */
+    deleteGitRemote(pluginId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    listGitBranches(pluginId: string): Promise<string[]>;
+    /** Push the dev plugin's content to its previously-declared Git remote. */
+    push(pluginId: string): Promise<Record<string, unknown>>;
+    /** Pull (and rebase) the dev plugin's content from its Git remote. */
+    pull(pluginId: string): Promise<Record<string, unknown>>;
+    /** Fetch the dev plugin's content from its Git remote. */
+    fetch(pluginId: string): Promise<Record<string, unknown>>;
+    /** Reset the dev plugin to its local HEAD state (discards local edits). */
+    resetToLocalHeadState(pluginId: string): Promise<Record<string, unknown>>;
+    /** Reset the dev plugin to the remote HEAD state (discards local work). */
+    resetToRemoteHeadState(pluginId: string): Promise<Record<string, unknown>>;
+    private devGitAction;
+    /**
+     * 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.
+     */
+    private settleActionFuture;
+    /** List the contents tree of a dev plugin. */
+    listContents(pluginId: string): Promise<PluginContentItem[]>;
+    /**
+     * 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.
+     */
+    getFile(pluginId: string, path: string): Promise<string>;
+    /** Read a dev plugin file as raw bytes (same raw-body route as getFile). */
+    getFileBytes(pluginId: string, path: string): Promise<Uint8Array>;
+    /** Download a dev plugin file as a raw stream (binary-safe). */
+    downloadFile(pluginId: string, path: string): Promise<Response>;
+    /** Get a single plugin file's detail record (size, mime, timestamps). */
+    getFileDetails(pluginId: string, path: string): Promise<PluginFileDetails>;
+    /** Upload (create or replace) a dev plugin file with text or binary content. */
+    putFile(pluginId: string, path: string, content: string | Uint8Array): Promise<void>;
+    /** Delete a file (or folder) from a dev plugin. */
+    deleteFile(pluginId: string, path: string): Promise<void>;
+    /** Add a folder to a dev plugin. */
+    addFolder(pluginId: string, path: string): Promise<void>;
+    /** Rename a file or folder inside a dev plugin (same parent folder). */
+    rename(pluginId: string, path: string, newName: string): Promise<void>;
+    /** Move a file or folder inside a dev plugin. The destination folder must exist. */
+    move(pluginId: string, path: string, destinationFolderPath: string): Promise<void>;
+    private contentsPath;
+}
+/**
+ * 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 declare function validatedPluginGitUrl(repository: string, field?: string): string;
+/**
+ * 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 declare function isPluginIdCandidate(value: unknown): boolean;