dataiku-sdk 3.1.0 → 3.3.0

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

@@ -0,0 +1,265 @@
+import { BaseResource } from "./base.js";
+import { validateGitReferencePath } from "./project-git.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;
+export { validateGitReferencePath, };