dataiku-sdk 0.1.0

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

@@ -0,0 +1,72 @@
+import type { BuildMode, JobSummary, JobWaitResult } from "../schemas.js";
+import { BaseResource } from "./base.js";
+interface ComputeNextPollDelayMsOptions {
+    pollCount: number;
+    baseIntervalMs: number;
+    adaptiveEnabled: boolean;
+}
+/**
+ * Compute the next poll delay.
+ * When adaptive polling is enabled, the interval doubles every 3 polls,
+ * capped at MAX_POLL_INTERVAL_MS (or baseIntervalMs if it's larger).
+ */
+export declare function computeNextPollDelayMs({ pollCount, baseIntervalMs, adaptiveEnabled, }: ComputeNextPollDelayMsOptions): number;
+export declare class JobsResource extends BaseResource {
+    /** List jobs in a project. */
+    list(projectKey?: string): Promise<JobSummary[]>;
+    /** Get full details for a single job. */
+    get(jobId: string, projectKey?: string): Promise<Record<string, unknown>>;
+    /**
+     * Retrieve job log text.
+     * Returns the last `maxLogLines` lines (default 50) from the tail.
+     */
+    log(jobId: string, opts?: {
+        activity?: string;
+        maxLogLines?: number;
+        projectKey?: string;
+    }): Promise<string>;
+    /**
+     * Start a dataset build job.
+     * Returns the new job's ID.
+     */
+    build(datasetName: string, opts?: {
+        buildMode?: BuildMode;
+        autoUpdateSchema?: boolean;
+        projectKey?: string;
+    }): Promise<{
+        jobId: string;
+    }>;
+    /**
+     * Build a dataset and wait for the job to reach a terminal state.
+     * Combines {@link build} then {@link wait}.
+     */
+    buildAndWait(datasetName: string, opts?: {
+        buildMode?: BuildMode;
+        autoUpdateSchema?: boolean;
+        activity?: string;
+        includeLogs?: boolean;
+        maxLogLines?: number;
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+        projectKey?: string;
+    }): Promise<JobWaitResult>;
+    /**
+     * Poll a job until it reaches a terminal state or times out.
+     *
+     * Adaptive polling doubles the interval every 3 polls when
+     * `pollIntervalMs` is not explicitly set.
+     *
+     * On timeout, returns `{ success: false, ... }` rather than throwing.
+     */
+    wait(jobId: string, opts?: {
+        activity?: string;
+        includeLogs?: boolean;
+        maxLogLines?: number;
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+        projectKey?: string;
+    }): Promise<JobWaitResult>;
+    /** Request a job abort. */
+    abort(jobId: string, projectKey?: string): Promise<void>;
+}
+export {};

package/dist/src/resources/jobs.js

@@ -0,0 +1,184 @@
+import { JobSummaryArraySchema, } from "../schemas.js";
+import { BaseResource, } from "./base.js";
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const MAX_POLL_INTERVAL_MS = 10_000;
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_MAX_LOG_LINES = 50;
+const TERMINAL_STATES = new Set([
+    "DONE",
+    "FAILED",
+    "ABORTED",
+    "KILLED",
+    "CANCELED",
+    "CANCELLED",
+    "ERROR",
+]);
+function isTerminalState(state) {
+    return TERMINAL_STATES.has((state ?? "").toUpperCase());
+}
+function isSuccessfulTerminalState(state) {
+    return (state ?? "").toUpperCase() === "DONE";
+}
+/**
+ * Compute the next poll delay.
+ * When adaptive polling is enabled, the interval doubles every 3 polls,
+ * capped at MAX_POLL_INTERVAL_MS (or baseIntervalMs if it's larger).
+ */
+export function computeNextPollDelayMs({ pollCount, baseIntervalMs, adaptiveEnabled, }) {
+    if (!adaptiveEnabled) {
+        return baseIntervalMs;
+    }
+    const step = Math.max(0, Math.floor((pollCount - 1) / 3));
+    const interval = baseIntervalMs * 2 ** step;
+    return Math.min(interval, Math.max(baseIntervalMs, MAX_POLL_INTERVAL_MS));
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class JobsResource extends BaseResource {
+    /** List jobs in a project. */
+    async list(projectKey) {
+        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/jobs/`);
+        return this.client.safeParse(JobSummaryArraySchema, raw, "jobs.list");
+    }
+    /** Get full details for a single job. */
+    async get(jobId, projectKey) {
+        const jobEnc = encodeURIComponent(jobId);
+        // Trailing slash required — DSS Cloud proxy misroutes URLs ending in .NNN (job ID timestamps)
+        return this.client.get(`/public/api/projects/${this.enc(projectKey)}/jobs/${jobEnc}/`);
+    }
+    /**
+     * Retrieve job log text.
+     * Returns the last `maxLogLines` lines (default 50) from the tail.
+     */
+    async log(jobId, opts) {
+        const jobEnc = encodeURIComponent(jobId);
+        const query = opts?.activity ? `?activity=${encodeURIComponent(opts.activity)}` : "";
+        const log = await this.client.getText(`/public/api/projects/${this.enc(opts?.projectKey)}/jobs/${jobEnc}/log/${query}`);
+        if (!log)
+            return "";
+        const lines = log.split("\n");
+        const limit = opts?.maxLogLines ?? DEFAULT_MAX_LOG_LINES;
+        if (lines.length > limit) {
+            return lines.slice(-limit).join("\n");
+        }
+        return log;
+    }
+    /**
+     * Start a dataset build job.
+     * Returns the new job's ID.
+     */
+    async build(datasetName, opts) {
+        const pk = this.resolveProjectKey(opts?.projectKey);
+        const enc = encodeURIComponent(pk);
+        const jobDef = {
+            outputs: [{ projectKey: pk, id: datasetName, type: "DATASET", },],
+            type: opts?.buildMode ?? "NON_RECURSIVE_FORCED_BUILD",
+        };
+        if (opts?.autoUpdateSchema) {
+            jobDef.autoUpdateSchemaBeforeEachRecipeRun = true;
+        }
+        const job = await this.client.post(`/public/api/projects/${enc}/jobs/`, jobDef);
+        return { jobId: job.id, };
+    }
+    /**
+     * Build a dataset and wait for the job to reach a terminal state.
+     * Combines {@link build} then {@link wait}.
+     */
+    async buildAndWait(datasetName, opts) {
+        const { jobId, } = await this.build(datasetName, {
+            buildMode: opts?.buildMode,
+            autoUpdateSchema: opts?.autoUpdateSchema,
+            projectKey: opts?.projectKey,
+        });
+        return this.wait(jobId, {
+            activity: opts?.activity,
+            includeLogs: opts?.includeLogs,
+            maxLogLines: opts?.maxLogLines,
+            pollIntervalMs: opts?.pollIntervalMs,
+            timeoutMs: opts?.timeoutMs,
+            projectKey: opts?.projectKey,
+        });
+    }
+    /**
+     * Poll a job until it reaches a terminal state or times out.
+     *
+     * Adaptive polling doubles the interval every 3 polls when
+     * `pollIntervalMs` is not explicitly set.
+     *
+     * On timeout, returns `{ success: false, ... }` rather than throwing.
+     */
+    async wait(jobId, opts) {
+        const projectEnc = this.enc(opts?.projectKey);
+        const jobEnc = encodeURIComponent(jobId);
+        const baseIntervalMs = Math.max(1, opts?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+        const adaptivePolling = opts?.pollIntervalMs === undefined;
+        const timeout = Math.max(baseIntervalMs, opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        const startedAt = Date.now();
+        let pollCount = 0;
+        while (true) {
+            pollCount += 1;
+            const j = await this.client.get(`/public/api/projects/${projectEnc}/jobs/${jobEnc}/`);
+            const bs = j.baseStatus ?? {};
+            const def = bs.def ?? {};
+            const gs = j.globalState ?? {};
+            const state = bs.state ?? "unknown";
+            const elapsedMs = Date.now() - startedAt;
+            if (isTerminalState(state)) {
+                const success = isSuccessfulTerminalState(state);
+                let log;
+                if (opts?.includeLogs) {
+                    log = await this.log(jobId, {
+                        activity: opts.activity,
+                        maxLogLines: opts.maxLogLines,
+                        projectKey: opts.projectKey,
+                    });
+                }
+                return {
+                    success,
+                    jobId: def.id ?? jobId,
+                    state,
+                    type: def.type ?? "unknown",
+                    elapsedMs,
+                    pollCount,
+                    progress: {
+                        done: gs.done ?? 0,
+                        failed: gs.failed ?? 0,
+                        running: gs.running ?? 0,
+                        total: gs.total ?? null,
+                    },
+                    ...(log !== undefined ? { log, } : {}),
+                };
+            }
+            // Timeout — return failure result, don't throw
+            if (elapsedMs >= timeout) {
+                return {
+                    success: false,
+                    jobId,
+                    state,
+                    type: def.type ?? "unknown",
+                    elapsedMs,
+                    pollCount,
+                    timedOut: true,
+                    progress: {
+                        done: gs.done ?? 0,
+                        failed: gs.failed ?? 0,
+                        running: gs.running ?? 0,
+                        total: gs.total ?? null,
+                    },
+                };
+            }
+            const nextDelayMs = computeNextPollDelayMs({
+                pollCount,
+                baseIntervalMs,
+                adaptiveEnabled: adaptivePolling,
+            });
+            await sleep(Math.min(nextDelayMs, timeout - elapsedMs));
+        }
+    }
+    /** Request a job abort. */
+    async abort(jobId, projectKey) {
+        const jobEnc = encodeURIComponent(jobId);
+        await this.client.post(`/public/api/projects/${this.enc(projectKey)}/jobs/${jobEnc}/abort/`);
+    }
+}

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

@@ -0,0 +1,34 @@
+import type { JupyterNotebookContent, JupyterNotebookSummary, NotebookSession, SqlNotebookContent, SqlNotebookSummary } from "../schemas.js";
+import { BaseResource } from "./base.js";
+export declare class NotebooksResource extends BaseResource {
+    /** List all Jupyter notebooks in a project. */
+    listJupyter(projectKey?: string): Promise<JupyterNotebookSummary[]>;
+    /** Get the full content of a Jupyter notebook. */
+    getJupyter(name: string, projectKey?: string): Promise<JupyterNotebookContent>;
+    /** Save (overwrite) a Jupyter notebook's content. */
+    saveJupyter(name: string, content: JupyterNotebookContent, projectKey?: string): Promise<void>;
+    /** Delete a Jupyter notebook. */
+    deleteJupyter(name: string, projectKey?: string): Promise<void>;
+    /** Clear all cell outputs from a Jupyter notebook. */
+    clearJupyterOutputs(name: string, projectKey?: string): Promise<void>;
+    /** List running kernel sessions for a Jupyter notebook. */
+    listJupyterSessions(name: string, projectKey?: string): Promise<NotebookSession[]>;
+    /** Unload (stop) a running Jupyter notebook session. */
+    unloadJupyter(name: string, sessionId: string, projectKey?: string): Promise<void>;
+    /** List all SQL notebooks in a project. */
+    listSql(projectKey?: string): Promise<SqlNotebookSummary[]>;
+    /** Get the full content of a SQL notebook. */
+    getSql(id: string, projectKey?: string): Promise<SqlNotebookContent>;
+    /** Save (overwrite) a SQL notebook's content. */
+    saveSql(id: string, content: SqlNotebookContent, projectKey?: string): Promise<void>;
+    /** Delete a SQL notebook. */
+    deleteSql(id: string, projectKey?: string): Promise<void>;
+    /** Get execution history for a SQL notebook (keyed by cell ID). */
+    getSqlHistory(id: string, projectKey?: string): Promise<Record<string, unknown[]>>;
+    /** Clear execution history for a SQL notebook. */
+    clearSqlHistory(id: string, opts?: {
+        cellId?: string;
+        numRunsToRetain?: number;
+        projectKey?: string;
+    }): Promise<void>;
+}

package/dist/src/resources/notebooks.js

@@ -0,0 +1,75 @@
+import { JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, NotebookSessionArraySchema, SqlNotebookContentSchema, SqlNotebookSummaryArraySchema, } from "../schemas.js";
+import { BaseResource, } from "./base.js";
+export class NotebooksResource extends BaseResource {
+    // ── Jupyter Notebooks ──────────────────────────────────────────────
+    /** List all Jupyter notebooks in a project. */
+    async listJupyter(projectKey) {
+        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/`);
+        return this.client.safeParse(JupyterNotebookSummaryArraySchema, raw, "notebooks.listJupyter");
+    }
+    /** Get the full content of a Jupyter notebook. */
+    async getJupyter(name, projectKey) {
+        const nameEnc = encodeURIComponent(name);
+        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/${nameEnc}`);
+        return this.client.safeParse(JupyterNotebookContentSchema, raw, "notebooks.getJupyter");
+    }
+    /** Save (overwrite) a Jupyter notebook's content. */
+    async saveJupyter(name, content, projectKey) {
+        const nameEnc = encodeURIComponent(name);
+        await this.client.putVoid(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/${nameEnc}`, content);
+    }
+    /** Delete a Jupyter notebook. */
+    async deleteJupyter(name, projectKey) {
+        const nameEnc = encodeURIComponent(name);
+        await this.client.del(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/${nameEnc}`);
+    }
+    /** Clear all cell outputs from a Jupyter notebook. */
+    async clearJupyterOutputs(name, projectKey) {
+        const nameEnc = encodeURIComponent(name);
+        await this.client.del(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/${nameEnc}/outputs`);
+    }
+    /** List running kernel sessions for a Jupyter notebook. */
+    async listJupyterSessions(name, projectKey) {
+        const nameEnc = encodeURIComponent(name);
+        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/${nameEnc}/sessions`);
+        return this.client.safeParse(NotebookSessionArraySchema, raw, "notebooks.sessionsJupyter");
+    }
+    /** Unload (stop) a running Jupyter notebook session. */
+    async unloadJupyter(name, sessionId, projectKey) {
+        const nameEnc = encodeURIComponent(name);
+        const sidEnc = encodeURIComponent(sessionId);
+        await this.client.del(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/${nameEnc}/sessions/${sidEnc}`);
+    }
+    // ── SQL Notebooks ──────────────────────────────────────────────────
+    /** List all SQL notebooks in a project. */
+    async listSql(projectKey) {
+        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/`);
+        return this.client.safeParse(SqlNotebookSummaryArraySchema, raw, "notebooks.listSql");
+    }
+    /** Get the full content of a SQL notebook. */
+    async getSql(id, projectKey) {
+        const idEnc = encodeURIComponent(id);
+        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/${idEnc}`);
+        return this.client.safeParse(SqlNotebookContentSchema, raw, "notebooks.getSql");
+    }
+    /** Save (overwrite) a SQL notebook's content. */
+    async saveSql(id, content, projectKey) {
+        const idEnc = encodeURIComponent(id);
+        await this.client.putVoid(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/${idEnc}`, content);
+    }
+    /** Delete a SQL notebook. */
+    async deleteSql(id, projectKey) {
+        const idEnc = encodeURIComponent(id);
+        await this.client.del(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/${idEnc}`);
+    }
+    /** Get execution history for a SQL notebook (keyed by cell ID). */
+    async getSqlHistory(id, projectKey) {
+        const idEnc = encodeURIComponent(id);
+        return this.client.get(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/${idEnc}/history`);
+    }
+    /** Clear execution history for a SQL notebook. */
+    async clearSqlHistory(id, opts) {
+        const idEnc = encodeURIComponent(id);
+        await this.client.post(`/public/api/projects/${this.enc(opts?.projectKey)}/sql-notebooks/${idEnc}/history/clear`, { cellId: opts?.cellId, numRunsToRetain: opts?.numRunsToRetain, });
+    }
+}

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

@@ -0,0 +1,38 @@
+import type { FlowMapOptions, ProjectDetails, ProjectMetadata, ProjectSummary } from "../schemas.js";
+import type { NormalizedFlowMap } from "../utils/flow-map.js";
+import { BaseResource } from "./base.js";
+interface FlowMapTruncationSummary {
+    truncated: boolean;
+    maxNodes: number | null;
+    maxEdges: number | null;
+    nodeCountBefore: number;
+    nodeCountAfter: number;
+    edgeCountBefore: number;
+    edgeCountAfter: number;
+}
+export interface FlowMapResult {
+    map: NormalizedFlowMap;
+    truncation: FlowMapTruncationSummary;
+    raw?: unknown;
+}
+export declare class ProjectsResource extends BaseResource {
+    /** List all projects visible to the API key. */
+    list(): Promise<ProjectSummary[]>;
+    /** Get details for a single project. */
+    get(projectKey?: string): Promise<ProjectDetails>;
+    /** Get metadata (tags, custom fields, checklists) for a project. */
+    metadata(projectKey?: string): Promise<ProjectMetadata>;
+    /** Get the raw flow graph for a project. */
+    flow(projectKey?: string): Promise<unknown>;
+    /**
+     * Build a normalized, optionally truncated flow map for a project.
+     *
+     * Fetches the flow graph and supplementary metadata (datasets, recipes,
+     * managed folders) in parallel. Folder name resolution uses a timeout
+     * to avoid blocking when the folders endpoint is slow.
+     */
+    map(opts?: FlowMapOptions & {
+        projectKey?: string;
+    }): Promise<FlowMapResult>;
+}
+export {};

package/dist/src/resources/projects.js

@@ -0,0 +1,185 @@
+import { ProjectDetailsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, } from "../schemas.js";
+import { normalizeFlowGraph, } from "../utils/flow-map.js";
+import { BaseResource, } from "./base.js";
+function fetchWithTimeout(label, timeoutMs, fetcher) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            resolve({
+                warning: `${label} metadata timed out after ${timeoutMs}ms; continuing without it.`,
+            });
+        }, timeoutMs);
+        fetcher().then((value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ value, });
+        }, (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const detail = error instanceof Error ? error.message : String(error);
+            resolve({
+                warning: `${label} metadata unavailable: ${detail}`,
+            });
+        });
+    });
+}
+function computeRootsAndLeaves(nodes, edges) {
+    const inDegree = new Map();
+    const outDegree = new Map();
+    for (const node of nodes) {
+        inDegree.set(node.id, 0);
+        outDegree.set(node.id, 0);
+    }
+    for (const edge of edges) {
+        inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);
+        outDegree.set(edge.from, (outDegree.get(edge.from) ?? 0) + 1);
+    }
+    const roots = nodes
+        .filter((node) => (inDegree.get(node.id) ?? 0) === 0)
+        .map((node) => node.id)
+        .sort((a, b) => a.localeCompare(b));
+    const leaves = nodes
+        .filter((node) => (outDegree.get(node.id) ?? 0) === 0)
+        .map((node) => node.id)
+        .sort((a, b) => a.localeCompare(b));
+    return { roots, leaves, };
+}
+function truncateFlowMap(normalized, maxNodes, maxEdges) {
+    const nodes = maxNodes === undefined ? normalized.nodes : normalized.nodes.slice(0, maxNodes);
+    const nodeIds = new Set(nodes.map((node) => node.id));
+    const edgesWithinNodes = normalized.edges.filter((edge) => nodeIds.has(edge.from) && nodeIds.has(edge.to));
+    const edges = maxEdges === undefined ? edgesWithinNodes : edgesWithinNodes.slice(0, maxEdges);
+    const { roots, leaves, } = computeRootsAndLeaves(nodes, edges);
+    const truncation = {
+        truncated: nodes.length < normalized.nodes.length || edges.length < normalized.edges.length,
+        maxNodes: maxNodes ?? null,
+        maxEdges: maxEdges ?? null,
+        nodeCountBefore: normalized.nodes.length,
+        nodeCountAfter: nodes.length,
+        edgeCountBefore: normalized.edges.length,
+        edgeCountAfter: edges.length,
+    };
+    const warnings = truncation.truncated
+        ? [
+            ...normalized.warnings,
+            `Flow map truncated (nodes ${truncation.nodeCountAfter}/${truncation.nodeCountBefore}, edges ${truncation.edgeCountAfter}/${truncation.edgeCountBefore}).`,
+        ]
+        : normalized.warnings;
+    return {
+        map: {
+            ...normalized,
+            nodes,
+            edges,
+            roots,
+            leaves,
+            warnings,
+            stats: {
+                nodeCount: nodes.length,
+                edgeCount: edges.length,
+                datasets: nodes.filter((node) => node.kind === "dataset").length,
+                recipes: nodes.filter((node) => node.kind === "recipe").length,
+                roots: roots.length,
+                leaves: leaves.length,
+            },
+        },
+        truncation,
+    };
+}
+// ---------------------------------------------------------------------------
+// Resource
+// ---------------------------------------------------------------------------
+const DEFAULT_MAX_NODES = 300;
+const DEFAULT_MAX_EDGES = 600;
+const DEFAULT_METADATA_TIMEOUT_MS = 1_500;
+export class ProjectsResource extends BaseResource {
+    /** List all projects visible to the API key. */
+    async list() {
+        const raw = await this.client.get("/public/api/projects/");
+        return this.client.safeParse(ProjectSummaryArraySchema, raw, "projects.list");
+    }
+    /** Get details for a single project. */
+    async get(projectKey) {
+        const enc = this.enc(projectKey);
+        const raw = await this.client.get(`/public/api/projects/${enc}/`);
+        return this.client.safeParse(ProjectDetailsSchema, raw, "projects.get");
+    }
+    /** Get metadata (tags, custom fields, checklists) for a project. */
+    async metadata(projectKey) {
+        const enc = this.enc(projectKey);
+        const raw = await this.client.get(`/public/api/projects/${enc}/metadata`);
+        return this.client.safeParse(ProjectMetadataSchema, raw, "projects.metadata");
+    }
+    /** Get the raw flow graph for a project. */
+    async flow(projectKey) {
+        const enc = this.enc(projectKey);
+        return this.client.get(`/public/api/projects/${enc}/flow/graph/`);
+    }
+    /**
+     * Build a normalized, optionally truncated flow map for a project.
+     *
+     * Fetches the flow graph and supplementary metadata (datasets, recipes,
+     * managed folders) in parallel. Folder name resolution uses a timeout
+     * to avoid blocking when the folders endpoint is slow.
+     */
+    async map(opts) {
+        const enc = this.enc(opts?.projectKey);
+        const pk = this.resolveProjectKey(opts?.projectKey);
+        const timeoutMs = DEFAULT_METADATA_TIMEOUT_MS;
+        const [rawGraph, foldersMeta, datasetsMeta, recipesMeta,] = await Promise.all([
+            this.client.get(`/public/api/projects/${enc}/flow/graph/`),
+            fetchWithTimeout("Managed folders", timeoutMs, () => this.client.get(`/public/api/projects/${enc}/managedfolders/`)),
+            fetchWithTimeout("Datasets", timeoutMs, () => this.client.get(`/public/api/projects/${enc}/datasets/`)),
+            fetchWithTimeout("Recipes", timeoutMs, () => this.client.get(`/public/api/projects/${enc}/recipes/`)),
+        ]);
+        // Build folder name lookup
+        const folderNamesById = {};
+        const allFolderIds = [];
+        for (const f of foldersMeta.value ?? []) {
+            if (!f.id || f.id.length === 0)
+                continue;
+            allFolderIds.push(f.id);
+            folderNamesById[f.id] = f.name ?? f.id;
+        }
+        const allDatasetNames = (datasetsMeta.value ?? [])
+            .map((d) => d.name)
+            .filter((n) => typeof n === "string" && n.length > 0);
+        const allRecipeNames = (recipesMeta.value ?? [])
+            .map((r) => r.name)
+            .filter((n) => typeof n === "string" && n.length > 0);
+        // Normalize the flow graph
+        const normalizedBase = normalizeFlowGraph(rawGraph, pk, {
+            folderNamesById,
+            allDatasetNames,
+            allRecipeNames,
+            allFolderIds,
+        });
+        // Append any metadata fetch warnings
+        const metadataWarnings = [
+            foldersMeta.warning,
+            datasetsMeta.warning,
+            recipesMeta.warning,
+        ].filter((w) => typeof w === "string" && w.length > 0);
+        const normalized = metadataWarnings.length > 0
+            ? {
+                ...normalizedBase,
+                warnings: [...normalizedBase.warnings, ...metadataWarnings,],
+            }
+            : normalizedBase;
+        // Truncate
+        const effectiveMaxNodes = opts?.maxNodes ?? DEFAULT_MAX_NODES;
+        const effectiveMaxEdges = opts?.maxEdges ?? DEFAULT_MAX_EDGES;
+        const { map, truncation, } = truncateFlowMap(normalized, effectiveMaxNodes, effectiveMaxEdges);
+        const result = { map, truncation, };
+        if (opts?.includeRaw) {
+            result.raw = rawGraph;
+        }
+        return result;
+    }
+}

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

@@ -0,0 +1,35 @@
+import type { RecipeCreateOptions, RecipeCreateResult, RecipeSummary } from "../schemas.js";
+import { BaseResource } from "./base.js";
+export declare class RecipesResource extends BaseResource {
+    /** List all recipes in a project. */
+    list(projectKey?: string): Promise<RecipeSummary[]>;
+    /**
+     * Get a recipe definition (and optionally its payload).
+     * Returns the raw API response shape: `{ recipe, payload }`.
+     */
+    get(recipeName: string, opts?: {
+        includePayload?: boolean;
+        payloadMaxLines?: number;
+        projectKey?: string;
+    }): Promise<{
+        recipe: Record<string, unknown>;
+        payload?: string;
+    }>;
+    /** Create a recipe, with optional output dataset provisioning and join configuration. */
+    create(opts: RecipeCreateOptions): Promise<RecipeCreateResult>;
+    /**
+     * Update a recipe by merging the patch into the current definition.
+     * The `recipe` sub-object is spread-merged to preserve nested fields.
+     */
+    update(recipeName: string, data: Record<string, unknown>, projectKey?: string): Promise<void>;
+    /** Delete a recipe. */
+    delete(recipeName: string, projectKey?: string): Promise<void>;
+    /**
+     * Download a recipe definition as a JSON file.
+     * Returns the path to the written file.
+     */
+    download(recipeName: string, opts?: {
+        outputPath?: string;
+        projectKey?: string;
+    }): Promise<string>;
+}