dataiku-sdk 3.6.1 → 3.8.0

package/dist/src/resources/saved-models.js

@@ -1,6 +1,7 @@
 import { basename, } from "node:path";
 import { ClientValidationError, } from "../errors.js";
 import { BaseResource, requireNonEmpty, requireNonEmptyArray, requireObject, } from "./base.js";
+import { TrainedModel, } from "./trained-model.js";
 function boolQuery(value) {
     return value === undefined ? "true" : String(value);
 }
@@ -187,30 +188,31 @@ export class SavedModelsResource extends BaseResource {
      * the stream is read under the client body deadline.
      */
     async downloadScoringJar(options, savedModelId, versionId, projectKey) {
-        const version = encodeURIComponent(requireNonEmpty(versionId, "versionId"));
-        const query = new URLSearchParams();
-        if (options?.fullClassName !== undefined) {
-            query.set("fullClassName", options.fullClassName);
-        }
-        if (options?.includeLibs !== undefined) {
-            query.set("includeLibs", String(options.includeLibs));
-        }
-        const suffix = [...query.keys(),].length > 0 ? `?${query.toString()}` : "";
-        return this.client.stream(`${this.savedModelPath(savedModelId, projectKey)}/versions/${version}/scoring-jar${suffix}`);
+        return this.version(savedModelId, versionId, projectKey).downloadScoringJar(options);
     }
     /** GET the scoring PMML of a version as a binary/XML stream. */
     async downloadScoringPmml(savedModelId, versionId, projectKey) {
-        const version = encodeURIComponent(requireNonEmpty(versionId, "versionId"));
-        return this.client.stream(`${this.savedModelPath(savedModelId, projectKey)}/versions/${version}/scoring-pmml`);
+        return this.version(savedModelId, versionId, projectKey).downloadScoringPmml();
     }
     /**
      * Update the user metadata of a model version. The body must only be the
      * "userMeta" field of a previously-retrieved version-details object.
      */
     async setUserMeta(savedModelId, versionId, userMeta, projectKey) {
+        await this.version(savedModelId, versionId, projectKey).setUserMeta(userMeta);
+    }
+    /**
+     * One saved-model version as a {@link TrainedModel}: diagnostics
+     * (subpopulation analyses, partial dependencies, timeseries residuals and
+     * per-series results), documentation, scoring exports, user metadata.
+     */
+    version(savedModelId, versionId, projectKey) {
         const version = encodeURIComponent(requireNonEmpty(versionId, "versionId"));
-        requireObject(userMeta, "userMeta");
-        await this.client.putVoid(`${this.savedModelPath(savedModelId, projectKey)}/versions/${version}/user-meta`, userMeta);
+        return new TrainedModel(this.client, `${this.savedModelPath(savedModelId, projectKey)}/versions/${version}`);
+    }
+    /** GET a generated saved-model version documentation (docx) by the `exportId` of its finished future. */
+    async downloadDocumentation(exportId, projectKey) {
+        return this.client.stream(`/public/api/projects/${this.enc(projectKey)}/savedmodels/documentations/${encodeURIComponent(requireNonEmpty(exportId, "exportId"))}`);
     }
     /** Delete a saved model and all of its versions. */
     async delete(savedModelId, projectKey) {

package/dist/src/resources/scenarios.js

@@ -1,4 +1,3 @@
-import { randomUUID, } from "node:crypto";
 import { ClientValidationError, DataikuError, } from "../errors.js";
 import { ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioSummaryArraySchema, } from "../schemas.js";
 import { deepMerge, } from "../utils/deep-merge.js";
@@ -56,20 +55,15 @@ function scenarioRunSummaryFromRaw(entry) {
     if (!isRecord(entry))
         return { runId: "unknown", };
     const runId = typeof entry.runId === "string" ? entry.runId : "unknown";
-    const optionalRecord = (value) => isRecord(value) ? value : undefined;
+    const start = optionalNumber(entry.start);
+    const end = optionalNumber(entry.end);
     return {
         runId,
-        ...(optionalNumber(entry.start) !== undefined ? { start: optionalNumber(entry.start), } : {}),
-        ...(optionalNumber(entry.end) !== undefined ? { end: optionalNumber(entry.end), } : {}),
-        ...(optionalRecord(entry.scenario) !== undefined
-            ? { scenario: optionalRecord(entry.scenario), }
-            : {}),
-        ...(optionalRecord(entry.variables) !== undefined
-            ? { variables: optionalRecord(entry.variables), }
-            : {}),
-        ...(optionalRecord(entry.result) !== undefined
-            ? { result: optionalRecord(entry.result), }
-            : {}),
+        ...(start !== undefined ? { start, } : {}),
+        ...(end !== undefined ? { end, } : {}),
+        ...(isRecord(entry.scenario) ? { scenario: entry.scenario, } : {}),
+        ...(isRecord(entry.variables) ? { variables: entry.variables, } : {}),
+        ...(isRecord(entry.result) ? { result: entry.result, } : {}),
     };
 }
 /** Map a light-endpoint response to the documented ScenarioWithStatus shape. */
@@ -422,7 +416,7 @@ export class ScenariosResource extends BaseResource {
     async runScript(script, opts) {
         const pk = this.resolveProjectKey(opts?.projectKey);
         const pkEnc = this.enc(opts?.projectKey);
-        const scenarioId = `dss_cli_code_run_${Date.now()}_${randomUUID().replace(/-/g, "")}`;
+        const scenarioId = `dss_cli_code_run_${Date.now()}_${crypto.randomUUID().replace(/-/g, "")}`;
         const base = `/public/api/projects/${pkEnc}/scenarios/${encodeURIComponent(scenarioId)}`;
         const envSelection = opts?.envName
             ? { envMode: "EXPLICIT_ENV", envName: opts.envName, }

package/dist/src/resources/sql.js

@@ -76,31 +76,70 @@ function sqlErrorDetailFromBody(body) {
     const match = trimmed.match(/\b[A-Z_]+(?:_ERROR|_NOT_FOUND|_MISMATCH|_DENIED|_EXCEEDED)\b[:\s-]+[^\n\r]+/);
     return match?.[0] ?? (isLikelySqlErrorDetail(trimmed) ? trimmed.slice(0, 500) : undefined);
 }
+/**
+ * JDBC/driver failures that mean the connection to the database broke or timed
+ * out mid-statement: a DML statement may already have committed, so these stay
+ * an unknown outcome even though they are SQL/JDBC-flavored.
+ */
+const SQL_CONNECTION_LOSS_TYPE = /transient|recoverable|timeout/i;
+const SQL_CONNECTION_LOSS_TEXT = /i\/o error|communication (?:link|error|failure)|connection (?:reset|closed|refused|lost|abort)|broken pipe|socket|timed out|network/i;
+/**
+ * Whether DSS answered with a definite refusal of the statement, as opposed to
+ * an unknown outcome (transport reset, timeout, bare gateway error). DSS runs the
+ * statement before answering the start POST, so a SQL-flavored error body (JDBC
+ * error, or an error type from a SQL/JDBC class) or a body DSS itself classifies
+ * as permission/not-found means the database rejected the statement — unless
+ * the error reports a lost or timed-out database connection.
+ */
+function isDefiniteSqlRejection(error, sqlDetail) {
+    if (error.status < 400)
+        return false;
+    let errorType;
+    try {
+        errorType = asRecord(JSON.parse(error.body))?.errorType;
+    }
+    catch {
+        errorType = undefined;
+    }
+    if (typeof errorType === "string" && SQL_CONNECTION_LOSS_TYPE.test(errorType))
+        return false;
+    if (SQL_CONNECTION_LOSS_TEXT.test(error.body))
+        return false;
+    if (sqlDetail)
+        return true;
+    if (error.category === "forbidden" || error.category === "not_found")
+        return true;
+    return typeof errorType === "string" && /sql|jdbc/i.test(errorType);
+}
 function withSqlErrorContext(error) {
     if (error instanceof DataikuError) {
         const detail = sqlErrorDetailFromBody(error.body);
-        if (detail) {
+        const definiteFailure = isDefiniteSqlRejection(error, detail);
+        if (detail || definiteFailure) {
             let body = error.body;
-            try {
-                const parsed = JSON.parse(error.body);
-                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                    body = JSON.stringify({
-                        ...parsed,
-                        message: `SQL query failed: ${detail}`,
-                        sqlError: detail,
-                    });
+            if (detail) {
+                try {
+                    const parsed = JSON.parse(error.body);
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        body = JSON.stringify({
+                            ...parsed,
+                            message: `SQL query failed: ${detail}`,
+                            sqlError: detail,
+                        });
+                    }
+                    else {
+                        body = `SQL query failed: ${detail}\n${error.body}`;
+                    }
                 }
-                else {
+                catch {
                     body = `SQL query failed: ${detail}\n${error.body}`;
                 }
             }
-            catch {
-                body = `SQL query failed: ${detail}\n${error.body}`;
-            }
             throw new DataikuError(error.status, error.statusText, body, error.retry, error.requestId, {
                 target: error.trustedTarget,
                 elapsedMs: error.trustedElapsedMs,
                 bodyTruncated: error.bodyTruncated,
+                definiteFailure,
             });
         }
     }

package/dist/src/resources/streaming-endpoints.d.ts

@@ -38,6 +38,18 @@ export declare class StreamingEndpointsResource extends BaseResource {
     getSettings(id: string, projectKey?: string): Promise<StreamingEndpointSettings>;
     /** Create a streaming endpoint with type-specific params. */
     create(id: string, type: string, body: StreamingEndpointCreateParams, projectKey?: string): Promise<StreamingEndpointSettings>;
+    /**
+     * Create a managed streaming endpoint (POST /streamingendpoints/managed):
+     * DSS picks type and params from the connection and format option.
+     */
+    createManaged(id: string, creationSettings: {
+        connectionId: string;
+        formatOptionId?: string;
+    }, projectKey?: string): Promise<void>;
+    /** Get a streaming endpoint's schema (`{columns: [{name, type}]}`). */
+    getSchema(id: string, projectKey?: string): Promise<Record<string, unknown>>;
+    /** Replace a streaming endpoint's schema with an object obtained from `getSchema`, edited. */
+    setSchema(id: string, schema: Record<string, unknown>, projectKey?: string): Promise<void>;
     /** Update one streaming endpoint's raw settings. */
     updateSettings(id: string, body: Record<string, unknown>, projectKey?: string): Promise<void>;
     /** Delete a streaming endpoint from the flow without deleting underlying streaming data. */

package/dist/src/resources/streaming-endpoints.js

@@ -23,6 +23,21 @@ export class StreamingEndpointsResource extends BaseResource {
             params: body,
         });
     }
+    /**
+     * Create a managed streaming endpoint (POST /streamingendpoints/managed):
+     * DSS picks type and params from the connection and format option.
+     */
+    async createManaged(id, creationSettings, projectKey) {
+        await this.client.post(`/public/api/projects/${this.enc(projectKey)}/streamingendpoints/managed`, { id, creationSettings, });
+    }
+    /** Get a streaming endpoint's schema (`{columns: [{name, type}]}`). */
+    async getSchema(id, projectKey) {
+        return this.client.get(`/public/api/projects/${this.enc(projectKey)}/streamingendpoints/${encodeURIComponent(id)}/schema`);
+    }
+    /** Replace a streaming endpoint's schema with an object obtained from `getSchema`, edited. */
+    async setSchema(id, schema, projectKey) {
+        await this.client.putVoid(`/public/api/projects/${this.enc(projectKey)}/streamingendpoints/${encodeURIComponent(id)}/schema`, schema);
+    }
     /** Update one streaming endpoint's raw settings. */
     async updateSettings(id, body, projectKey) {
         const endpointId = encodeURIComponent(id);

package/dist/src/resources/trained-model.d.ts

@@ -0,0 +1,60 @@
+import type { DataikuClient } from "../client.js";
+import { type DocumentationTemplate } from "./documentation.js";
+import { type DssTask } from "./futures.js";
+/** Sampling and execution settings of a diagnostics computation (dataikuapi `computationParams`). */
+export interface ModelDiagnosticsComputation {
+    /** Records sampled from the test set (DSS default 10000). */
+    sampleSize?: number;
+    randomState?: number;
+    nJobs?: number;
+    debugMode?: boolean;
+}
+/** Diagnostics a trained model computes on demand, then serves as results. */
+export type ComputedModelDiagnostic = "subpopulation-analyses" | "partial-dependencies" | "timeseries-residuals";
+/** Every diagnostics result a trained model serves. */
+export type ModelDiagnostic = ComputedModelDiagnostic | "per-timeseries-metrics" | "per-timeseries-evaluation-forecasts";
+/** Diagnostics that are started with POST and return a DSS future. */
+export declare const COMPUTED_MODEL_DIAGNOSTICS: Record<string, true>;
+/** Diagnostics results served by GET (computed ones plus per-series results of forecasting models). */
+export declare const MODEL_DIAGNOSTICS: Record<string, true>;
+/**
+ * Request body that starts a diagnostics computation. Subpopulation analyses
+ * and partial dependencies take the features to analyse; timeseries
+ * residuals take no body.
+ */
+export declare function modelDiagnosticsBody(kind: ComputedModelDiagnostic, features: string[], computation?: ModelDiagnosticsComputation): Record<string, unknown> | undefined;
+/** Query options for the scoring JAR export (GET .../scoring-jar). */
+export interface ScoringJarOptions {
+    fullClassName?: string;
+    includeLibs?: boolean;
+}
+/**
+ * One trained model: a visual-ML lab model (`mlTasks.model(...)`) or a
+ * saved-model version (`savedModels.version(...)`). Both expose the same
+ * routes (user meta, scoring exports, diagnostics, documentation) under
+ * different bases. Generated documents are downloaded from the owning
+ * resource (`mlTasks.downloadModelDocumentation`, `savedModels.downloadDocumentation`).
+ */
+export declare class TrainedModel {
+    private readonly client;
+    /** Route of the trained model, e.g. `.../models/lab/{a}/{t}/models/{id}`. */
+    private readonly modelPath;
+    constructor(client: DataikuClient, 
+    /** Route of the trained model, e.g. `.../models/lab/{a}/{t}/models/{id}`. */
+    modelPath: string);
+    /** Replace the user metadata: only the `userMeta` field of the model details, edited. */
+    setUserMeta(userMeta: Record<string, unknown>): Promise<void>;
+    /** GET the Java scoring JAR (license-gated, optimized-scoring models only) as a binary stream. */
+    downloadScoringJar(options?: ScoringJarOptions): Promise<Response>;
+    /** GET the PMML export (license-gated, PMML-compatible models only) as a stream. */
+    downloadScoringPmml(): Promise<Response>;
+    /**
+     * Start computing subpopulation analyses or partial dependencies over
+     * `features`, or timeseries residuals. Returns the DSS future.
+     */
+    compute(kind: ComputedModelDiagnostic, features?: string[], computation?: ModelDiagnosticsComputation): Promise<DssTask>;
+    /** Results computed so far (subpopulation analyses, partial dependencies, residuals, per-series metrics or forecasts). */
+    get(kind: ModelDiagnostic): Promise<unknown>;
+    /** Start generating the model documentation (docx); the finished result carries `exportId`. */
+    generateDocumentation(template?: DocumentationTemplate): Promise<DssTask>;
+}

package/dist/src/resources/trained-model.js

@@ -0,0 +1,98 @@
+import { ClientValidationError, } from "../errors.js";
+import { requireObject, } from "./base.js";
+import { startDocumentation, } from "./documentation.js";
+import { dssTask, } from "./futures.js";
+/** Diagnostics that are started with POST and return a DSS future. */
+export const COMPUTED_MODEL_DIAGNOSTICS = {
+    "subpopulation-analyses": true,
+    "partial-dependencies": true,
+    "timeseries-residuals": true,
+};
+/** Diagnostics results served by GET (computed ones plus per-series results of forecasting models). */
+export const MODEL_DIAGNOSTICS = {
+    ...COMPUTED_MODEL_DIAGNOSTICS,
+    "per-timeseries-metrics": true,
+    "per-timeseries-evaluation-forecasts": true,
+};
+/**
+ * Request body that starts a diagnostics computation. Subpopulation analyses
+ * and partial dependencies take the features to analyse; timeseries
+ * residuals take no body.
+ */
+export function modelDiagnosticsBody(kind, features, computation = {}) {
+    if (kind === "timeseries-residuals")
+        return undefined;
+    if (features.length === 0) {
+        throw new ClientValidationError(`${kind} needs at least one feature.`, "missing_required_arg");
+    }
+    return {
+        features,
+        computationParams: {
+            ...(computation.sampleSize !== undefined ? { sample_size: computation.sampleSize, } : {}),
+            ...(computation.randomState !== undefined ? { random_state: computation.randomState, } : {}),
+            ...(computation.nJobs !== undefined ? { n_jobs: computation.nJobs, } : {}),
+            ...(computation.debugMode !== undefined ? { debug_mode: computation.debugMode, } : {}),
+        },
+    };
+}
+/**
+ * One trained model: a visual-ML lab model (`mlTasks.model(...)`) or a
+ * saved-model version (`savedModels.version(...)`). Both expose the same
+ * routes (user meta, scoring exports, diagnostics, documentation) under
+ * different bases. Generated documents are downloaded from the owning
+ * resource (`mlTasks.downloadModelDocumentation`, `savedModels.downloadDocumentation`).
+ */
+export class TrainedModel {
+    client;
+    modelPath;
+    constructor(client, 
+    /** Route of the trained model, e.g. `.../models/lab/{a}/{t}/models/{id}`. */
+    modelPath) {
+        this.client = client;
+        this.modelPath = modelPath;
+    }
+    /** Replace the user metadata: only the `userMeta` field of the model details, edited. */
+    async setUserMeta(userMeta) {
+        await this.client.putVoid(`${this.modelPath}/user-meta`, requireObject(userMeta, "userMeta"));
+    }
+    /** GET the Java scoring JAR (license-gated, optimized-scoring models only) as a binary stream. */
+    async downloadScoringJar(options = {}) {
+        const query = new URLSearchParams();
+        if (options.fullClassName !== undefined)
+            query.set("fullClassName", options.fullClassName);
+        if (options.includeLibs !== undefined)
+            query.set("includeLibs", String(options.includeLibs));
+        return this.client.stream(`${this.modelPath}/scoring-jar${query.size > 0 ? `?${query}` : ""}`);
+    }
+    /** GET the PMML export (license-gated, PMML-compatible models only) as a stream. */
+    async downloadScoringPmml() {
+        return this.client.stream(`${this.modelPath}/scoring-pmml`);
+    }
+    /**
+     * Start computing subpopulation analyses or partial dependencies over
+     * `features`, or timeseries residuals. Returns the DSS future.
+     */
+    async compute(kind, features = [], computation = {}) {
+        if (COMPUTED_MODEL_DIAGNOSTICS[kind] !== true) {
+            throw new ClientValidationError(`Computed diagnostic must be one of ${Object.keys(COMPUTED_MODEL_DIAGNOSTICS).join(", ")}.`, "invalid_enum");
+        }
+        const raw = await this.client.post(`${this.modelPath}/${kind}`, modelDiagnosticsBody(kind, features, computation));
+        return dssTask(raw, `Computing ${kind}`);
+    }
+    /** Results computed so far (subpopulation analyses, partial dependencies, residuals, per-series metrics or forecasts). */
+    async get(kind) {
+        if (MODEL_DIAGNOSTICS[kind] !== true) {
+            throw new ClientValidationError(`Diagnostic must be one of ${Object.keys(MODEL_DIAGNOSTICS).join(", ")}.`, "invalid_enum");
+        }
+        return this.client.get(`${this.modelPath}/${kind}`);
+    }
+    /** Start generating the model documentation (docx); the finished result carries `exportId`. */
+    async generateDocumentation(template = { kind: "default", }) {
+        const base = `${this.modelPath}/generate-documentation-from`;
+        return startDocumentation(this.client, {
+            default: `${base}-default-template`,
+            file: `${base}-custom-template`,
+            folder: `${base}-template-in-folder`,
+        }, template, "Model documentation generation");
+    }
+}

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

@@ -68,4 +68,12 @@ export declare class WebappsResource extends BaseResource {
     restartBackendAndWait(webappId: string, projectKey?: string, options?: WebappWaitOptions): Promise<FutureWaitResult>;
     /** Get a webapp backend's state. */
     getBackendState(webappId: string, projectKey?: string): Promise<Record<string, unknown>>;
+    /**
+     * Trust a webapp's code (POST /actions/trust): for the caller, or for every
+     * user with `trustForEverybody` (admin). Returns `{canAccess, trustedCodeStatus}`.
+     */
+    trust(webappId: string, opts?: {
+        projectKey?: string;
+        trustForEverybody?: boolean;
+    }): Promise<Record<string, unknown>>;
 }

package/dist/src/resources/webapps.js

@@ -95,4 +95,14 @@ export class WebappsResource extends BaseResource {
         const id = encodeURIComponent(webappId);
         return this.client.get(`/public/api/projects/${this.enc(projectKey)}/webapps/${id}/backend/state`);
     }
+    /**
+     * Trust a webapp's code (POST /actions/trust): for the caller, or for every
+     * user with `trustForEverybody` (admin). Returns `{canAccess, trustedCodeStatus}`.
+     */
+    async trust(webappId, opts = {}) {
+        const query = opts.trustForEverybody === undefined
+            ? ""
+            : `?trustForEverybody=${opts.trustForEverybody}`;
+        return this.client.post(`/public/api/projects/${this.enc(opts.projectKey)}/webapps/${encodeURIComponent(webappId)}/actions/trust${query}`);
+    }
 }

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

@@ -1,4 +1,5 @@
-import type { WikiArticleData, WikiSettings } from "../schemas.js";
+import { ClientValidationError } from "../errors.js";
+import type { WikiArticleAttachment, WikiArticleData, WikiSettings } from "../schemas.js";
 import { BaseResource } from "./base.js";
 export interface WikiArticleCreateOptions {
     name: string;
@@ -12,11 +13,61 @@ export interface WikiArticleUpdateOptions {
     data?: Record<string, unknown>;
     projectKey?: string;
 }
+export interface WikiAttachResult {
+    articleId: string;
+    projectKey: string;
+    fileName: string;
+    bytes: number;
+    /** The attachment DSS created, as re-read from the article. */
+    attachment: WikiArticleAttachment;
+    /** All attachments of the article after the upload. */
+    attachments: WikiArticleAttachment[];
+}
+export interface WikiDetachResult {
+    articleId: string;
+    projectKey: string;
+    /** The attachment that was removed. */
+    detached: WikiArticleAttachment;
+    /** Attachments left on the article. */
+    attachments: WikiArticleAttachment[];
+}
+export interface LocalWikiAttachmentFile {
+    path: string;
+    fileName: string;
+    bytes: number;
+}
+/** Attachments of an article; DSS omits the field when there are none. */
+export declare function wikiAttachments(data: WikiArticleData): WikiArticleAttachment[];
+/** The attachment with exactly this smart id, or undefined. */
+export declare function findWikiAttachment(data: WikiArticleData, smartId: string): WikiArticleAttachment | undefined;
+/** Coded not_found error for a smart id that is not attached to the article. */
+export declare function wikiAttachmentNotFound(data: WikiArticleData, smartId: string): ClientValidationError;
+/** Check that a local path is a readable regular file before any DSS call. */
+export declare function statWikiAttachmentFile(localPath: string): Promise<LocalWikiAttachmentFile>;
 export declare class WikiResource extends BaseResource {
     settings(projectKey?: string): Promise<WikiSettings>;
+    /**
+     * Replace the wiki properties (home article and taxonomy, PUT /wiki/) with
+     * an object obtained from `settings`, edited.
+     */
+    updateSettings(settings: Record<string, unknown>, projectKey?: string): Promise<void>;
     list(projectKey?: string): Promise<WikiArticleData[]>;
     get(articleIdOrName: string, projectKey?: string): Promise<WikiArticleData>;
     create(opts: WikiArticleCreateOptions): Promise<WikiArticleData>;
     update(articleIdOrName: string, opts: WikiArticleUpdateOptions): Promise<WikiArticleData>;
     delete(articleIdOrName: string, projectKey?: string): Promise<void>;
+    /**
+     * Upload a local file and attach it to an article (multipart POST to
+     * /wiki/{id}/upload). DSS names the attachment after the file's basename and
+     * types it from the extension. The article is re-read to identify the new
+     * attachment.
+     */
+    attach(articleIdOrName: string, localPath: string, projectKey?: string): Promise<WikiAttachResult>;
+    /**
+     * Remove exactly one attachment (by smart id) from an article: the article is
+     * read, the entry filtered out of `article.attachments`, and the whole
+     * article PUT back. Throws a coded `not_found` error when the smart id is not
+     * attached.
+     */
+    detach(articleIdOrName: string, smartId: string, projectKey?: string): Promise<WikiDetachResult>;
 }

package/dist/src/resources/wiki.js

@@ -1,6 +1,36 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ClientValidationError, } from "../errors.js";
 import { WikiArticleDataArraySchema, WikiArticleDataSchema, WikiSettingsSchema, } from "../schemas.js";
 import { deepMerge, } from "../utils/deep-merge.js";
 import { BaseResource, } from "./base.js";
+/** Attachments of an article; DSS omits the field when there are none. */
+export function wikiAttachments(data) {
+    return data.article.attachments ?? [];
+}
+/** The attachment with exactly this smart id, or undefined. */
+export function findWikiAttachment(data, smartId) {
+    return wikiAttachments(data).find((attachment) => attachment.smartId === smartId);
+}
+/** Coded not_found error for a smart id that is not attached to the article. */
+export function wikiAttachmentNotFound(data, smartId) {
+    const available = wikiAttachments(data).flatMap((attachment) => attachment.smartId === undefined ? [] : [attachment.smartId,]);
+    return new ClientValidationError(`Attachment ${smartId} not found on wiki article ${data.article.id}.`, "not_found", "List attachments with `dss wiki get ARTICLE_ID` (article.attachments[].smartId), or pass --if-exists to treat absence as success.", { articleId: data.article.id, smartId, availableSmartIds: available, });
+}
+/** Check that a local path is a readable regular file before any DSS call. */
+export async function statWikiAttachmentFile(localPath) {
+    let stat;
+    try {
+        stat = await fs.promises.stat(localPath);
+    }
+    catch (error) {
+        throw new ClientValidationError(`Could not read attachment file ${localPath}: ${error instanceof Error ? error.message : String(error)}.`, "not_found", "Verify the file path and that it is readable.");
+    }
+    if (!stat.isFile()) {
+        throw new ClientValidationError(`${localPath} is not a regular file.`);
+    }
+    return { path: localPath, fileName: path.basename(localPath), bytes: stat.size, };
+}
 const WIKI_LIST_CONCURRENCY = 4;
 function taxonomyIds(nodes) {
     const ids = [];
@@ -33,6 +63,13 @@ export class WikiResource extends BaseResource {
         const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/wiki/`);
         return this.client.safeParse(WikiSettingsSchema, raw, "wiki.settings");
     }
+    /**
+     * Replace the wiki properties (home article and taxonomy, PUT /wiki/) with
+     * an object obtained from `settings`, edited.
+     */
+    async updateSettings(settings, projectKey) {
+        await this.client.putVoid(`/public/api/projects/${this.enc(projectKey)}/wiki/`, settings);
+    }
     async list(projectKey) {
         const settings = await this.settings(projectKey);
         const ids = taxonomyIds(settings.taxonomy);
@@ -70,4 +107,63 @@ export class WikiResource extends BaseResource {
         const current = await this.get(articleIdOrName, projectKey);
         await this.client.del(`/public/api/projects/${this.enc(projectKey)}/wiki/${encodeURIComponent(current.article.id)}`);
     }
+    /**
+     * Upload a local file and attach it to an article (multipart POST to
+     * /wiki/{id}/upload). DSS names the attachment after the file's basename and
+     * types it from the extension. The article is re-read to identify the new
+     * attachment.
+     */
+    async attach(articleIdOrName, localPath, projectKey) {
+        const file = await statWikiAttachmentFile(localPath);
+        const pk = this.resolveProjectKey(projectKey);
+        const before = await this.get(articleIdOrName, pk);
+        const articleId = before.article.id;
+        await this.client.uploadJson(`/public/api/projects/${encodeURIComponent(pk)}/wiki/${encodeURIComponent(articleId)}/upload`, localPath, file.fileName);
+        const after = await this.get(articleId, pk);
+        const knownIds = new Set(wikiAttachments(before).map((attachment) => attachment.smartId));
+        let created = wikiAttachments(after).filter((attachment) => !knownIds.has(attachment.smartId));
+        if (created.length > 1) {
+            created = created.filter((attachment) => attachment.details?.["objectDisplayName"] === file.fileName
+                && attachment.details?.["size"] === file.bytes);
+        }
+        const attachment = created[0];
+        if (created.length !== 1 || attachment === undefined || attachment.smartId === undefined) {
+            throw new ClientValidationError(`DSS did not verify upload of ${file.fileName} to wiki article ${articleId}.`, "ambiguous_outcome", "The upload returned successfully, but the article did not show exactly one new attachment. Inspect the article (dss wiki get) before retrying.", { articleId, expectedBytes: file.bytes, newAttachments: created, });
+        }
+        return {
+            articleId,
+            projectKey: pk,
+            fileName: file.fileName,
+            bytes: file.bytes,
+            attachment,
+            attachments: wikiAttachments(after),
+        };
+    }
+    /**
+     * Remove exactly one attachment (by smart id) from an article: the article is
+     * read, the entry filtered out of `article.attachments`, and the whole
+     * article PUT back. Throws a coded `not_found` error when the smart id is not
+     * attached.
+     */
+    async detach(articleIdOrName, smartId, projectKey) {
+        const pk = this.resolveProjectKey(projectKey);
+        const current = await this.get(articleIdOrName, pk);
+        const detached = findWikiAttachment(current, smartId);
+        if (detached === undefined)
+            throw wikiAttachmentNotFound(current, smartId);
+        const remaining = wikiAttachments(current).filter((attachment) => attachment.smartId !== smartId);
+        const raw = await this.client.put(`/public/api/projects/${encodeURIComponent(pk)}/wiki/${encodeURIComponent(current.article.id)}`, { ...current, article: { ...current.article, attachments: remaining, }, });
+        const saved = this.client.safeParse(WikiArticleDataSchema, raw, "wiki.detach");
+        const after = wikiAttachments(saved);
+        if (findWikiAttachment(saved, smartId) !== undefined
+            || after.length !== remaining.length) {
+            throw new ClientValidationError(`DSS did not verify removal of attachment ${smartId} from wiki article ${current.article.id}.`, "ambiguous_outcome", "The save returned successfully, but the article's attachments are not the expected remainder. Inspect the article (dss wiki get) before retrying.", {
+                articleId: current.article.id,
+                smartId,
+                expectedRemaining: remaining.length,
+                actualRemaining: after.length,
+            });
+        }
+        return { articleId: current.article.id, projectKey: pk, detached, attachments: after, };
+    }
 }

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

@@ -56,4 +56,6 @@ export declare class WorkspacesResource extends BaseResource {
     listObjects(workspaceKey: string): Promise<WorkspaceObject[]>;
     /** Add an object to a workspace. */
     addObject(workspaceKey: string, object: WorkspaceObjectInput): Promise<WorkspaceObject>;
+    /** Remove an object from a workspace by its workspace object id (from `listObjects`). */
+    removeObject(workspaceKey: string, workspaceObjectId: string): Promise<void>;
 }

package/dist/src/resources/workspaces.js

@@ -28,4 +28,8 @@ export class WorkspacesResource extends BaseResource {
     async addObject(workspaceKey, object) {
         return this.client.post(`/public/api/workspaces/${encodeURIComponent(workspaceKey)}/objects`, object);
     }
+    /** Remove an object from a workspace by its workspace object id (from `listObjects`). */
+    async removeObject(workspaceKey, workspaceObjectId) {
+        await this.client.del(`/public/api/workspaces/${encodeURIComponent(workspaceKey)}/objects/${encodeURIComponent(workspaceObjectId)}`);
+    }
 }

package/dist/src/utils/flow-analysis.js

@@ -345,6 +345,10 @@ function renderMermaid(map) {
             lines.push(`    ${idByNode.get(nodeId)}["${mermaidLabel(readableNode(node))}"]`);
         }
         lines.push("  end");
+        // Zone colors come from DSS; only plain #RRGGBB values reach the style line.
+        if (zone.color && /^#[0-9a-fA-F]{6}$/.test(zone.color)) {
+            lines.push(`  style z${zoneIndex} fill:${zone.color}22,stroke:${zone.color}`);
+        }
     }
     for (const edge of map.edges) {
         const from = idByNode.get(edge.from);