dataiku-sdk 0.12.3 → 0.12.5

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

@@ -1,3 +1,4 @@
+import { type DataikuErrorCategory } from "../errors.js";
 import { BaseResource } from "./base.js";
 export interface AppListItem extends Record<string, unknown> {
     appId?: string;
@@ -20,6 +21,141 @@ export interface BusinessAppInstanceUserPermissions extends Record<string, unkno
     readProjectContent?: boolean;
     writeProjectContent?: boolean;
 }
+export interface DeleteAppInstanceOptions {
+    /** Refuse deletion unless the current creationTag hashes to this value. */
+    expectedProjectIncarnationHash?: string;
+}
+export type AppManifestReferenceKind = "scenario" | "folder" | "variable";
+/**
+ * Source-verifiable app-manifest reference locations. Validation is scoped to
+ * homepage tiles so identically named keys in arbitrary custom-form `config`
+ * objects are never treated as references.
+ */
+export declare const APP_MANIFEST_REFERENCE_KEYS: Record<AppManifestReferenceKind, string[]>;
+export interface AppManifestReference {
+    kind: AppManifestReferenceKind;
+    path: string;
+    value: string;
+    exists: boolean;
+}
+export interface AppManifestCheck {
+    kind: AppManifestReferenceKind;
+    status: "ok" | "failed" | "skipped";
+    checked: number;
+    malformed: number;
+    missing: number;
+}
+export interface AppManifestIssue {
+    code: "INVALID_MANIFEST_ROOT" | "INVALID_REFERENCE_VALUE" | "MISSING_SCENARIO" | "MISSING_FOLDER" | "MISSING_VARIABLE";
+    path: string;
+    message: string;
+}
+export interface AppManifestValidationResult {
+    valid: boolean;
+    projectKey: string;
+    manifestHash: string;
+    references: AppManifestReference[];
+    checks: AppManifestCheck[];
+    errors: AppManifestIssue[];
+}
+export interface AppManifestPathDifference {
+    path: string;
+    kind: "added" | "removed" | "changed";
+    template?: unknown;
+    instance?: unknown;
+}
+export interface AppManifestComparisonResult {
+    appId: string;
+    projectKey: string;
+    templateHash: string;
+    instanceHash: string;
+    identical: boolean;
+    omittedFields: string[];
+    differences: AppManifestPathDifference[];
+}
+/**
+ * Raw app-manifest version markers. DSS renders the Application header version
+ * from the manifest's own `version` string, so that field (with its optional
+ * `versionNotes`) is the authoritative state; no separate publish/release
+ * transaction exists on the public API.
+ */
+export interface AppManifestVersionState {
+    projectKey: string;
+    projectAppType: string | null;
+    version: string | null;
+    versionNotes: string | null;
+    manifestHash: string;
+}
+export interface AppManifestVersionUpdate {
+    /** New manifest `version` string. Must be non-empty when supplied. */
+    version?: string;
+    /** New manifest `versionNotes` string. May be empty to clear existing notes. */
+    versionNotes?: string;
+    /**
+     * 64-hex manifest hash the caller last read, used as a non-atomic stale-read
+     * guard: the write is refused when the manifest already differs at the
+     * verification read. It cannot prevent a concurrent write that lands between
+     * that read and this write.
+     */
+    expectHash?: string;
+    /** Compute and report the change without issuing a write. */
+    dryRun?: boolean;
+}
+/**
+ * The only concurrency control the public app-manifest endpoint permits. DSS
+ * exposes no conditional write (no ETag, no If-Match, no version token), so
+ * `expectHash` can only detect a hash that is already stale when it is checked;
+ * it can never turn the subsequent PUT into a conditional write. Every
+ * manifest-version write
+ * result reports this literal so callers can machine-check the guarantee they
+ * actually get instead of inferring one from prose.
+ */
+export declare const APP_MANIFEST_CONCURRENCY_CONTROL = "client-side-non-atomic-stale-read-check";
+export type AppManifestConcurrencyControl = typeof APP_MANIFEST_CONCURRENCY_CONTROL;
+export type AppManifestVersionWriteOutcome = "persisted" | "dry-run" | "unchanged" | "indeterminate";
+export interface AppManifestVersionWriteFailure {
+    /** Sanitized summary; never echoes response bodies or secrets. */
+    error: string;
+    errorStatus: number | null;
+    errorCategory: DataikuErrorCategory | null;
+    remediation: string;
+}
+export interface AppManifestVersionWriteResult {
+    projectKey: string;
+    projectAppType: string | null;
+    /** Fields the caller asked to set; null means "left untouched". */
+    requested: {
+        version: string | null;
+        versionNotes: string | null;
+    };
+    /** True when the desired manifest differs from the manifest that was read. */
+    changed: boolean;
+    dryRun: boolean;
+    /**
+     * True only after a write was accepted and re-read as exactly `desired`.
+     * False for unchanged/dry-run results. Null when the write outcome could
+     * not be observed (transport loss, transient/server failure, or failed
+     * verification read) — the write may still have landed.
+     */
+    persisted: boolean | null;
+    outcome: AppManifestVersionWriteOutcome;
+    before: AppManifestVersionState;
+    desired: AppManifestVersionState;
+    /**
+     * Last state observed on the server; equals `before` when nothing was
+     * written. Null when the write outcome could not be observed.
+     */
+    after: AppManifestVersionState | null;
+    /**
+     * Always `"client-side-non-atomic-stale-read-check"`. The GET→PUT window is
+     * unguarded: this client can overwrite a competing write that lands after its
+     * GET, and that lost update is not detectable when this client's PUT wins.
+     * The final read only verifies the state observed after this client's PUT.
+     */
+    concurrencyControl: AppManifestConcurrencyControl;
+    /** Present only when outcome is "indeterminate". */
+    error?: AppManifestVersionWriteFailure;
+}
 export declare class ApplicationsResource extends BaseResource {
     /** List all Dataiku Apps. */
     listApps(): Promise<AppListItem[]>;
@@ -31,10 +167,64 @@ export declare class ApplicationsResource extends BaseResource {
     createInstance(appId: string, body: Record<string, unknown>): Promise<AppInstanceRef>;
     /** Get the manifest for an app instance project. */
     getInstanceManifest(projectKey?: string): Promise<Record<string, unknown>>;
+    private getProjectDetails;
+    private getProjectAppType;
+    /**
+     * Shared app-manifest write guard: DSS only accepts manifest saves for app
+     * template projects, so every mutation path rejects instances and ordinary
+     * projects before issuing a PUT.
+     */
+    private requireAppTemplateForManifestSave;
     /** Save the manifest for a Dataiku App template project (rejects classic app-instance projects). */
     saveInstanceManifest(manifest: Record<string, unknown>, projectKey?: string): Promise<void>;
+    /**
+     * Read the manifest plus its derived version state. The project type comes
+     * from the manifest when DSS includes it and from project details otherwise,
+     * so ordinary reads cost a single request.
+     */
+    private readManifestVersion;
+    /**
+     * Read the authoritative app-manifest version markers. Allowed for app
+     * templates and app instances alike: instance verification compares an
+     * instance's inherited `version` against its template.
+     */
+    getManifestVersion(projectKey?: string): Promise<AppManifestVersionState>;
+    /**
+     * Set the manifest `version`/`versionNotes` strings on an app template.
+     *
+     * This is a manifest save, not a publish transaction: DSS exposes no release
+     * endpoint, and new instances simply inherit whatever version string the
+     * template carries at creation time.
+     *
+     * The write is not atomic, and `expectHash` cannot change that: the
+     * endpoint takes every PUT unconditionally, so `expectHash` only rejects a
+     * caller whose hash is already stale at the verification read. This client
+     * can overwrite a writer that commits after that read but before this PUT,
+     * and a final state equal to this client's desired manifest cannot reveal
+     * that lost update. The final read still prevents a different state observed
+     * after the PUT from being reported as persisted.
+     */
+    setManifestVersion(update: AppManifestVersionUpdate, projectKey?: string): Promise<AppManifestVersionWriteResult>;
+    /**
+     * Validate source-verifiable references in app homepage tiles:
+     * SCENARIO_RUN scenario IDs, DOWNLOAD_FILE managed-folder IDs, and runtime
+     * form parameter names (which DSS maps to project variables). Arbitrary
+     * custom-form `config` objects remain opaque. The manifest is never mutated.
+     * Missing/malformed references are returned deterministically; a reference
+     * kind with no applicable tiles does not trigger its project API.
+     */
+    validateAppManifest(manifest: unknown, projectKey?: string): Promise<AppManifestValidationResult>;
+    /**
+     * Compare a Dataiku App template manifest with the app-instance manifest of
+     * the target project. Root-level project identity fields in
+     * APP_MANIFEST_COMPARE_OMITTED_FIELDS are omitted from both sides; every
+     * other field — including ones the SDK does not model — is compared.
+     * Hashes cover the omitted-field-normalized states; differences are emitted
+     * as deterministic, path-ordered entries.
+     */
+    compareAppManifest(appId: string, projectKey?: string): Promise<AppManifestComparisonResult>;
     /** Delete an app instance project. */
-    deleteInstance(projectKey?: string): Promise<void>;
+    deleteInstance(projectKey?: string, options?: DeleteAppInstanceOptions): Promise<void>;
     /** List all Business Apps. */
     listBusinessApps(): Promise<BusinessAppListItem[]>;
     /** Get Business App details. */