dataiku-sdk 3.0.0 → 3.1.0

package/dist/src/resources/api-services.js

@@ -1,4 +1,21 @@
+import { ClientValidationError, } from "../errors.js";
+import { stableHash, } from "../utils/stable-hash.js";
 import { BaseResource, } from "./base.js";
+const EXPECT_HASH_PATTERN = /^[0-9a-fA-F]{64}$/;
+function assertExpectedSettingsHash(serviceId, expectHash, current, projectKey) {
+    if (!EXPECT_HASH_PATTERN.test(expectHash)) {
+        throw new ClientValidationError("Expected API service settings hash must be a 64-character SHA-256 hex digest.", "validation_failed", "Use the hash value returned by a previous read.", { projectKey, serviceId, });
+    }
+    const actual = stableHash(current);
+    if (actual !== expectHash.toLowerCase()) {
+        throw new ClientValidationError(`The API service ${JSON.stringify(serviceId)} changed since it was read.`, "validation_failed", "Re-read the service settings and retry with the current hash value.", {
+            projectKey,
+            serviceId,
+            expectedHash: expectHash.toLowerCase(),
+            actualHash: actual,
+        });
+    }
+}
 export class ApiServicesResource extends BaseResource {
     /** List API services in a project. */
     async list(projectKey) {
@@ -12,8 +29,17 @@ export class ApiServicesResource extends BaseResource {
     async getSettings(serviceId, projectKey) {
         return this.client.get(`${this.servicePath(serviceId, projectKey)}/settings`);
     }
-    /** Save API service settings. */
-    async saveSettings(serviceId, body, projectKey) {
+    /**
+     * Save API service settings with explicit replacement semantics: the body
+     * is the complete settings object (fetched via get-settings) and is PUT
+     * as-is. With `expectHash` armed, the settings are read first and their
+     * stable hash must match, or the write is refused before any PUT.
+     */
+    async saveSettings(serviceId, body, projectKey, options = {}) {
+        if (options.expectHash !== undefined) {
+            const current = await this.getSettings(serviceId, projectKey);
+            assertExpectedSettingsHash(serviceId, options.expectHash, current, projectKey);
+        }
         return this.client.put(`${this.servicePath(serviceId, projectKey)}/settings`, body);
     }
     /** Add a standard prediction endpoint backed by a saved model. */
@@ -35,9 +61,17 @@ export class ApiServicesResource extends BaseResource {
     async getPackageSummary(serviceId, packageId, projectKey) {
         return this.client.get(`${this.packagePath(serviceId, packageId, projectKey)}/summary`);
     }
-    /** Create a deployable package from the current service state. */
-    async createPackage(serviceId, packageId, projectKey) {
-        const message = await this.client.postText(this.packagePath(serviceId, packageId, projectKey), {});
+    /**
+     * Create a deployable package from the current service state. The
+     * documented optional `releaseNotes` parameter is forwarded as the
+     * `releaseNotes` query parameter when provided.
+     */
+    async createPackage(serviceId, packageId, projectKey, options = {}) {
+        const params = new URLSearchParams();
+        if (options.releaseNotes !== undefined)
+            params.set("releaseNotes", options.releaseNotes);
+        const query = params.size > 0 ? `?${params.toString()}` : "";
+        const message = await this.client.postText(`${this.packagePath(serviceId, packageId, projectKey)}${query}`, {});
         return { message, };
     }
     /** Delete an API service package. */
@@ -48,9 +82,21 @@ export class ApiServicesResource extends BaseResource {
     async downloadPackageArchive(serviceId, packageId, projectKey) {
         return this.client.stream(`${this.packagePath(serviceId, packageId, projectKey)}/archive`);
     }
-    /** Publish an API service package to the API Deployer. */
-    async publishPackage(serviceId, packageId, projectKey) {
-        return this.client.post(`${this.packagePath(serviceId, packageId, projectKey)}/publish`, {});
+    /**
+     * Publish an API service package to the API Deployer. The documented
+     * optional `publishedServiceId` parameter selects the published service
+     * the package is deployed to (a new published service is created when no
+     * match exists; when omitted, the server falls back to the service's own
+     * id). It is forwarded as the `publishedServiceId` query parameter when
+     * provided.
+     */
+    async publishPackage(serviceId, packageId, projectKey, options = {}) {
+        const params = new URLSearchParams();
+        if (options.publishedServiceId !== undefined) {
+            params.set("publishedServiceId", options.publishedServiceId);
+        }
+        const query = params.size > 0 ? `?${params.toString()}` : "";
+        return this.client.post(`${this.packagePath(serviceId, packageId, projectKey)}/publish${query}`, {});
     }
     servicePath(serviceId, projectKey) {
         return `/public/api/projects/${this.enc(projectKey)}/apiservices/${encodeURIComponent(serviceId)}`;

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

@@ -1,23 +1,68 @@
 import { BaseResource } from "./base.js";
+/**
+ * Optional, documented parameters of the bundle-export endpoint:
+ * - `releaseNotes`: important changes introduced in the bundle;
+ * - `evaluateProjectStandardsChecks`: whether the Project Standards Checks
+ *   applying to the project should run (defaults to true server-side, and the
+ *   official client always sends it).
+ */
+export interface BundleExportOptions {
+    releaseNotes?: string;
+    evaluateProjectStandardsChecks?: boolean;
+}
+/**
+ * Optional, documented parameter of the bundle-publish endpoint: the key of
+ * the published project on the Project Deployer where the bundle is deployed
+ * (a new published project is created when no match exists; when omitted, the
+ * server falls back to the source project's key).
+ */
+export interface BundlePublishOptions {
+    publishedProjectKey?: string;
+}
+/**
+ * Optional, documented parameter of the bundle-activation endpoint: scenario
+ * IDs mapped to whether each scenario should be enabled or disabled upon
+ * activation.
+ */
+export interface BundleActivateOptions {
+    scenariosToEnable?: Record<string, boolean>;
+}
 export declare class BundlesResource extends BaseResource {
     /** List bundles exported from a project on the Design node. */
     listExported(projectKey?: string): Promise<Record<string, unknown>[]>;
-    /** Create or overwrite an exported Design-node bundle. */
-    exportBundle(bundleId: string, projectKey?: string): Promise<void>;
+    /**
+     * Create or overwrite an exported Design-node bundle. The documented
+     * optional parameters are forwarded as query parameters:
+     * `releaseNotes` when provided, and `evaluateProjectStandardsChecks`
+     * (defaults to true, matching the official client which always sends it).
+     */
+    exportBundle(bundleId: string, projectKey?: string, options?: BundleExportOptions): Promise<void>;
     /** Delete an exported Design-node bundle. */
     deleteExported(bundleId: string, projectKey?: string): Promise<void>;
     /** Download an exported Design-node bundle archive. */
     downloadExportedArchive(bundleId: string, projectKey?: string): Promise<Response>;
-    /** Publish a Design-node bundle to the Project Deployer. */
-    publish(bundleId: string, projectKey?: string): Promise<Record<string, unknown>>;
+    /**
+     * Publish a Design-node bundle to the Project Deployer. The documented
+     * optional `publishedProjectKey` parameter selects the published project
+     * the bundle is deployed to (a new published project is created when no
+     * match exists; when omitted, the server falls back to the source
+     * project's key). It is forwarded as the `publishedProjectKey` query
+     * parameter when provided.
+     */
+    publish(bundleId: string, projectKey?: string, options?: BundlePublishOptions): Promise<Record<string, unknown>>;
     /** List bundles imported into a project on the Automation node. */
     listImported(projectKey?: string): Promise<Record<string, unknown>[]>;
     /** Import a server-side bundle archive into an Automation-node project. */
     importFromArchive(archivePath: string, projectKey?: string): Promise<Record<string, unknown>>;
     /** Import a local bundle archive stream into an Automation-node project. */
     importFromStream(filePath: string, projectKey?: string): Promise<void>;
-    /** Activate an imported Automation-node bundle. */
-    activate(bundleId: string, projectKey?: string): Promise<Record<string, unknown>>;
+    /**
+     * Activate an imported Automation-node bundle. The documented optional
+     * `scenariosToEnable` dict (scenario ID → enabled/disabled upon
+     * activation) is forwarded as the `scenariosActiveOnActivation` request
+     * body when provided.
+     */
+    activate(bundleId: string, projectKey?: string, options?: BundleActivateOptions): Promise<Record<string, unknown>>;
     /** Preload an imported Automation-node bundle. */
     preload(bundleId: string, projectKey?: string): Promise<Record<string, unknown>>;
     /** Delete an imported Automation-node bundle. */

package/dist/src/resources/bundles.js

@@ -5,9 +5,18 @@ export class BundlesResource extends BaseResource {
         const res = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/bundles/exported`);
         return res.bundles ?? [];
     }
-    /** Create or overwrite an exported Design-node bundle. */
-    async exportBundle(bundleId, projectKey) {
-        await this.client.putVoid(`/public/api/projects/${this.enc(projectKey)}/bundles/exported/${encodeURIComponent(bundleId)}`, {});
+    /**
+     * Create or overwrite an exported Design-node bundle. The documented
+     * optional parameters are forwarded as query parameters:
+     * `releaseNotes` when provided, and `evaluateProjectStandardsChecks`
+     * (defaults to true, matching the official client which always sends it).
+     */
+    async exportBundle(bundleId, projectKey, options = {}) {
+        const params = new URLSearchParams();
+        if (options.releaseNotes !== undefined)
+            params.set("releaseNotes", options.releaseNotes);
+        params.set("evaluateProjectStandardsChecks", String(options.evaluateProjectStandardsChecks ?? true));
+        await this.client.putVoid(`/public/api/projects/${this.enc(projectKey)}/bundles/exported/${encodeURIComponent(bundleId)}?${params.toString()}`, {});
     }
     /** Delete an exported Design-node bundle. */
     async deleteExported(bundleId, projectKey) {
@@ -17,9 +26,21 @@ export class BundlesResource extends BaseResource {
     async downloadExportedArchive(bundleId, projectKey) {
         return this.client.stream(`/public/api/projects/${this.enc(projectKey)}/bundles/exported/${encodeURIComponent(bundleId)}/archive`);
     }
-    /** Publish a Design-node bundle to the Project Deployer. */
-    async publish(bundleId, projectKey) {
-        return this.client.post(`/public/api/projects/${this.enc(projectKey)}/bundles/${encodeURIComponent(bundleId)}/publish`, {});
+    /**
+     * Publish a Design-node bundle to the Project Deployer. The documented
+     * optional `publishedProjectKey` parameter selects the published project
+     * the bundle is deployed to (a new published project is created when no
+     * match exists; when omitted, the server falls back to the source
+     * project's key). It is forwarded as the `publishedProjectKey` query
+     * parameter when provided.
+     */
+    async publish(bundleId, projectKey, options = {}) {
+        const params = new URLSearchParams();
+        if (options.publishedProjectKey !== undefined) {
+            params.set("publishedProjectKey", options.publishedProjectKey);
+        }
+        const query = params.size > 0 ? `?${params.toString()}` : "";
+        return this.client.post(`/public/api/projects/${this.enc(projectKey)}/bundles/${encodeURIComponent(bundleId)}/publish${query}`, {});
     }
     /** List bundles imported into a project on the Automation node. */
     async listImported(projectKey) {
@@ -34,9 +55,18 @@ export class BundlesResource extends BaseResource {
     async importFromStream(filePath, projectKey) {
         await this.client.upload(`/public/api/projects/${this.enc(projectKey)}/bundles/imported/actions/importFromStream`, filePath);
     }
-    /** Activate an imported Automation-node bundle. */
-    async activate(bundleId, projectKey) {
-        return this.client.post(`/public/api/projects/${this.enc(projectKey)}/bundles/imported/${encodeURIComponent(bundleId)}/actions/activate`, {});
+    /**
+     * Activate an imported Automation-node bundle. The documented optional
+     * `scenariosToEnable` dict (scenario ID → enabled/disabled upon
+     * activation) is forwarded as the `scenariosActiveOnActivation` request
+     * body when provided.
+     */
+    async activate(bundleId, projectKey, options = {}) {
+        const body = options.scenariosToEnable !== undefined
+            && Object.keys(options.scenariosToEnable).length > 0
+            ? { scenariosActiveOnActivation: options.scenariosToEnable, }
+            : {};
+        return this.client.post(`/public/api/projects/${this.enc(projectKey)}/bundles/imported/${encodeURIComponent(bundleId)}/actions/activate`, body);
     }
     /** Preload an imported Automation-node bundle. */
     async preload(bundleId, projectKey) {

package/dist/src/resources/code-envs.d.ts

@@ -1,4 +1,4 @@
-import type { CodeEnvActionResult, CodeEnvCreateOptions, CodeEnvDetails, CodeEnvPackageList, CodeEnvSetPackagesOptions, CodeEnvSummary, CodeEnvUpdatePackagesOptions, CodeEnvWaitOptions } from "../schemas.js";
+import type { CodeEnvActionResult, CodeEnvCreateOptions, CodeEnvDetails, CodeEnvGetLogOptions, CodeEnvLogResult, CodeEnvLogSummary, CodeEnvPackageList, CodeEnvSetPackagesOptions, CodeEnvSummary, CodeEnvUpdateImagesOptions, CodeEnvUpdatePackagesOptions, CodeEnvVersionForProject, CodeEnvWaitOptions } from "../schemas.js";
 import { BaseResource } from "./base.js";
 export declare class CodeEnvsResource extends BaseResource {
     list(opts?: {
@@ -6,9 +6,31 @@ export declare class CodeEnvsResource extends BaseResource {
     }): Promise<CodeEnvSummary[]>;
     get(envLang: string, envName: string): Promise<CodeEnvDetails>;
     getDefinition(envLang: string, envName: string): Promise<Record<string, unknown>>;
+    /** List the build log files DSS keeps for this code environment. */
+    listLogs(envLang: string, envName: string): Promise<CodeEnvLogSummary[]>;
+    /**
+     * Fetch one code-env build log, bounded by default: at most
+     * `maxBytes` bytes (default 10 MiB, 0 disables the cap) and the last
+     * `maxLines` lines (default 500, 0 disables the tail). Returns what was
+     * kept plus the truncation flags so callers can warn instead of
+     * silently losing output.
+     */
+    getLog(envLang: string, envName: string, logName: string, opts?: CodeEnvGetLogOptions): Promise<CodeEnvLogResult>;
+    /**
+     * Rebuild the Docker image(s) of the code environment to match its
+     * settings. `wait: false` returns the raw DSS future payload.
+     */
+    updateImages(envLang: string, envName: string, opts?: CodeEnvUpdateImagesOptions): Promise<CodeEnvActionResult>;
+    /**
+     * Resolve the code-env version a project uses (versioned environments on
+     * automation nodes); empty `version` for unversioned environments.
+     */
+    getVersionForProject(envLang: string, envName: string, projectKey: string): Promise<CodeEnvVersionForProject>;
     create(opts: CodeEnvCreateOptions): Promise<CodeEnvActionResult>;
-    setDefinition(envLang: string, envName: string, definition: Record<string, unknown>): Promise<CodeEnvActionResult>;
-    setPackages(envLang: string, envName: string, packages: CodeEnvPackageList, opts?: Pick<CodeEnvSetPackagesOptions, "installCorePackages">): Promise<CodeEnvActionResult>;
+    setDefinition(envLang: string, envName: string, definition: Record<string, unknown>, opts?: {
+        expectHash?: string;
+    }): Promise<CodeEnvActionResult>;
+    setPackages(envLang: string, envName: string, packages: CodeEnvPackageList, opts?: Pick<CodeEnvSetPackagesOptions, "installCorePackages" | "expectHash">): Promise<CodeEnvActionResult>;
     updatePackages(envLang: string, envName: string, opts?: CodeEnvUpdatePackagesOptions): Promise<CodeEnvActionResult>;
     setJupyterSupport(envLang: string, envName: string, active: boolean, opts?: CodeEnvWaitOptions): Promise<CodeEnvActionResult>;
     delete(envLang: string, envName: string, opts?: CodeEnvWaitOptions): Promise<CodeEnvActionResult>;

package/dist/src/resources/code-envs.js

@@ -1,5 +1,11 @@
-import { CodeEnvSummaryArraySchema, CodeEnvUsageArraySchema, } from "../schemas.js";
+import { ClientValidationError, } from "../errors.js";
+import { CodeEnvLogSummaryArraySchema, CodeEnvSummaryArraySchema, CodeEnvUsageArraySchema, CodeEnvVersionForProjectSchema, } from "../schemas.js";
+import { stableHash, } from "../utils/stable-hash.js";
 import { BaseResource, } from "./base.js";
+/** Byte cap applied to fetched code-env logs so stdout/JSON stays bounded. */
+const DEFAULT_LOG_MAX_BYTES = 10 * 1024 * 1024;
+/** Default number of tail lines returned by getLog (0 disables). */
+const DEFAULT_LOG_MAX_LINES = 500;
 export class CodeEnvsResource extends BaseResource {
     async list(opts) {
         const raw = await this.client.get("/public/api/admin/code-envs/");
@@ -21,8 +27,12 @@ export class CodeEnvsResource extends BaseResource {
             envName: raw.envName ?? envName,
             envLang: raw.envLang ?? envLang,
             pythonInterpreter: desc.pythonInterpreter,
+            deploymentMode: typeof raw.deploymentMode === "string"
+                ? raw.deploymentMode
+                : undefined,
             requestedPackages,
             installedPackages,
+            definitionHash: stableHash(raw),
         };
     }
     async getDefinition(envLang, envName) {
@@ -30,6 +40,61 @@ export class CodeEnvsResource extends BaseResource {
         const nameEnc = encodeURIComponent(envName);
         return this.client.get(`/public/api/admin/code-envs/${langEnc}/${nameEnc}`);
     }
+    /** List the build log files DSS keeps for this code environment. */
+    async listLogs(envLang, envName) {
+        const langEnc = encodeURIComponent(envLang);
+        const nameEnc = encodeURIComponent(envName);
+        const raw = await this.client.get(`/public/api/admin/code-envs/${langEnc}/${nameEnc}/logs`);
+        return this.client.safeParse(CodeEnvLogSummaryArraySchema, raw, "codeEnvs.listLogs");
+    }
+    /**
+     * Fetch one code-env build log, bounded by default: at most
+     * `maxBytes` bytes (default 10 MiB, 0 disables the cap) and the last
+     * `maxLines` lines (default 500, 0 disables the tail). Returns what was
+     * kept plus the truncation flags so callers can warn instead of
+     * silently losing output.
+     */
+    async getLog(envLang, envName, logName, opts) {
+        const langEnc = encodeURIComponent(envLang);
+        const nameEnc = encodeURIComponent(envName);
+        const logEnc = encodeURIComponent(logName);
+        const path = `/public/api/admin/code-envs/${langEnc}/${nameEnc}/logs/${logEnc}`;
+        const maxBytes = opts?.maxBytes ?? DEFAULT_LOG_MAX_BYTES;
+        const fetched = maxBytes > 0
+            ? await this.client.getTextLimited(path, maxBytes)
+            : { text: await this.client.getText(path), truncated: false, };
+        const tailed = tailLog(fetched.text, opts?.maxLines ?? DEFAULT_LOG_MAX_LINES);
+        return {
+            log: tailed.log,
+            bytes: Buffer.byteLength(fetched.text, "utf-8"),
+            truncated: fetched.truncated,
+            tailed: tailed.tailed,
+        };
+    }
+    /**
+     * Rebuild the Docker image(s) of the code environment to match its
+     * settings. `wait: false` returns the raw DSS future payload.
+     */
+    async updateImages(envLang, envName, opts) {
+        const langEnc = encodeURIComponent(envLang);
+        const nameEnc = encodeURIComponent(envName);
+        const query = new URLSearchParams();
+        if (opts?.envVersion !== undefined)
+            query.set("envVersion", opts.envVersion);
+        query.set("wait", String(opts?.wait !== false));
+        return this.client.post(`/public/api/admin/code-envs/${langEnc}/${nameEnc}/images?${query.toString()}`);
+    }
+    /**
+     * Resolve the code-env version a project uses (versioned environments on
+     * automation nodes); empty `version` for unversioned environments.
+     */
+    async getVersionForProject(envLang, envName, projectKey) {
+        const langEnc = encodeURIComponent(envLang);
+        const nameEnc = encodeURIComponent(envName);
+        const pkEnc = encodeURIComponent(projectKey);
+        const raw = await this.client.get(`/public/api/admin/code-envs/${langEnc}/${nameEnc}/${pkEnc}/version`);
+        return this.client.safeParse(CodeEnvVersionForProjectSchema, raw, "codeEnvs.getVersionForProject");
+    }
     async create(opts) {
         const langEnc = encodeURIComponent(opts.envLang);
         const nameEnc = encodeURIComponent(opts.envName);
@@ -39,13 +104,20 @@ export class CodeEnvsResource extends BaseResource {
         };
         return this.client.post(`/public/api/admin/code-envs/${langEnc}/${nameEnc}?wait=${opts.wait !== false}`, body);
     }
-    async setDefinition(envLang, envName, definition) {
+    async setDefinition(envLang, envName, definition, opts) {
+        if (opts?.expectHash !== undefined) {
+            const current = await this.getDefinition(envLang, envName);
+            assertDefinitionHash(envLang, envName, current, opts.expectHash);
+        }
         const langEnc = encodeURIComponent(envLang);
         const nameEnc = encodeURIComponent(envName);
         return this.client.put(`/public/api/admin/code-envs/${langEnc}/${nameEnc}`, definition);
     }
     async setPackages(envLang, envName, packages, opts) {
         const current = await this.getDefinition(envLang, envName);
+        if (opts?.expectHash !== undefined) {
+            assertDefinitionHash(envLang, envName, current, opts.expectHash);
+        }
         const next = {
             ...current,
             specPackageList: normalizePackageList(packages),
@@ -98,6 +170,36 @@ export class CodeEnvsResource extends BaseResource {
         return this.client.safeParse(CodeEnvUsageArraySchema, raw, "codeEnvs.listUsages");
     }
 }
+/**
+ * Keep only the last `maxLines` lines of a log (0 disables the tail).
+ * Returns whether any leading lines were dropped.
+ */
+function tailLog(log, maxLines) {
+    if (!log)
+        return { log, tailed: false, };
+    if (maxLines <= 0)
+        return { log, tailed: false, };
+    const lines = log.split(/\r\n|\n/);
+    if (lines.length <= maxLines)
+        return { log, tailed: false, };
+    return { log: lines.slice(lines.length - maxLines).join("\n"), tailed: true, };
+}
+/**
+ * Provenance guard for full-definition writes: DSS requires the PUT body to
+ * come from a prior GET, so refuse the write when the definition no longer
+ * hashes to the hash the caller captured.
+ */
+function assertDefinitionHash(envLang, envName, current, expected) {
+    const currentHash = stableHash(current);
+    if (currentHash === expected)
+        return;
+    throw new ClientValidationError(`Code env ${envLang}/${envName} changed since the expected definition hash was captured; refusing to overwrite it.`, "validation_failed", "Re-read the definition with dss code-env get-definition (definitionHash comes from code-env get), review the diff, and retry with the fresh hash.", {
+        envLang,
+        envName,
+        expectedDefinitionHash: expected,
+        currentDefinitionHash: currentHash,
+    });
+}
 function splitPackageList(raw) {
     if (!raw)
         return [];

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

@@ -80,6 +80,10 @@ export declare class DatasetsResource extends BaseResource {
      *
      * If `validateColumns` is provided, the first TSV row (header) is checked
      * against the column names. Mismatches emit a warning via onValidationWarning.
+     *
+     * The stream is byte-bounded (16 MiB per field, 64 MiB per row, 16 GiB per
+     * response): an oversized field or unterminated quoted row aborts the
+     * preview, cancels the response, and fails with a DataikuError.
      */
     preview(datasetName: string, opts?: {
         maxRows?: number;
@@ -103,6 +107,10 @@ export declare class DatasetsResource extends BaseResource {
      * fully scanned. Returns the observed count together with `exact` (false when
      * the probe cap was reached, i.e. the count is a lower bound) and whether the
      * count satisfies the assertion.
+     *
+     * Streaming is byte-bounded (16 MiB per field, 64 MiB per row, 16 GiB per
+     * response); oversized fields abort the count, cancel the response, and
+     * fail with a DataikuError.
      */
     assertRowCount(datasetName: string, expected: number, projectKey?: string): Promise<{
         expected: number;
@@ -117,6 +125,16 @@ export declare class DatasetsResource extends BaseResource {
      * (default 100k). Returns the written path, the number of data rows written,
      * whether the dataset had more rows than the cap (truncated), and the limit
      * used — so callers can detect truncation instead of silently getting a sample.
+     *
+     * Exported cells are spreadsheet-safe by default: headers/values whose
+     * first effective character is a spreadsheet formula sigil (`=`, `+`, `-`,
+     * `@`, including leading whitespace/control variants) are neutralized with
+     * a leading apostrophe so the file never executes formulas on open. Pass
+     * `rawData: true` to preserve exact bytes.
+     *
+     * Streaming is byte-bounded (16 MiB per field, 64 MiB per row, 16 GiB per
+     * response); on overflow the response is cancelled, the error is thrown,
+     * and any partially written download file is removed.
      */
     download(datasetName: string, opts?: {
         outputPath?: string;
@@ -125,6 +143,8 @@ export declare class DatasetsResource extends BaseResource {
             name: string;
         }[];
         limit?: number;
+        /** Preserve exact cell bytes (no spreadsheet-safe formula neutralization), default false. */
+        rawData?: boolean;
     }): Promise<{
         path: string;
         rows: number;