@ptkl/sdk 1.16.0 → 1.17.0

package/dist/index.0.10.js

@@ -2172,6 +2172,70 @@ var ProtokolSDK010 = (function (exports, axios) {
         }
     }
 
+    /**
+     * Build an RFC 7233 Range header value from the SDK's range options.
+     *
+     * Validation happens here rather than at the server so a typo (a float offset, a
+     * negative length) fails immediately and locally instead of arriving as an opaque
+     * 400 after a round trip.
+     */
+    function buildRangeHeader(range) {
+        const { offset, length, suffix } = range;
+        if (suffix !== undefined) {
+            if (offset !== undefined || length !== undefined) {
+                throw new Error('readRange: `suffix` cannot be combined with `offset` or `length`');
+            }
+            if (!Number.isInteger(suffix) || suffix <= 0) {
+                throw new Error('readRange: `suffix` must be a positive integer');
+            }
+            return `bytes=-${suffix}`;
+        }
+        const start = offset !== null && offset !== void 0 ? offset : 0;
+        if (!Number.isInteger(start) || start < 0) {
+            throw new Error('readRange: `offset` must be a non-negative integer');
+        }
+        if (length === undefined) {
+            return `bytes=${start}-`;
+        }
+        if (!Number.isInteger(length) || length <= 0) {
+            throw new Error('readRange: `length` must be a positive integer');
+        }
+        // Range end offsets are inclusive, so a length of N ends at start + N - 1.
+        return `bytes=${start}-${start + length - 1}`;
+    }
+    /**
+     * Turn a 206 response into a ByteRangeResult.
+     *
+     * The Content-Range check is the important part. Requests reach media-api through
+     * two proxies, and if any hop ever dropped the Range header the response would be
+     * a perfectly valid 200 carrying the *entire* file — a caller asking for 64 KiB
+     * of a 2 GB object would quietly receive all 2 GB. Failing loudly here turns that
+     * from a silent memory blow-up into an actionable error.
+     */
+    function toByteRangeResult(resp) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const contentRange = (_b = (_a = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _a === void 0 ? void 0 : _a['content-range']) !== null && _b !== void 0 ? _b : (_c = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _c === void 0 ? void 0 : _c['Content-Range'];
+        const parsed = /^bytes\s+(\d+)-(\d+)\/(\d+)$/.exec(String(contentRange !== null && contentRange !== void 0 ? contentRange : '').trim());
+        if (!parsed) {
+            throw new Error('readRange: response did not include a Content-Range header, so the returned body ' +
+                'may be the entire object rather than the requested range. ' +
+                'Check that the media host supports ranged reads and that no proxy is stripping the Range header.');
+        }
+        const start = Number(parsed[1]);
+        const end = Number(parsed[2]);
+        const totalSize = Number(parsed[3]);
+        const etag = (_e = (_d = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _d === void 0 ? void 0 : _d.etag) !== null && _e !== void 0 ? _e : (_f = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _f === void 0 ? void 0 : _f.ETag;
+        return {
+            data: resp.data,
+            start,
+            end,
+            length: end - start + 1,
+            totalSize,
+            eof: end >= totalSize - 1,
+            etag: typeof etag === 'string' ? etag.replace(/^"|"$/g, '') : undefined,
+            contentType: (_g = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _g === void 0 ? void 0 : _g['content-type'],
+        };
+    }
     /**
      * Document Management System (DMS) API client
      *
@@ -2346,6 +2410,93 @@ var ProtokolSDK010 = (function (exports, axios) {
                 responseType: (!encoding) ? 'blob' : null
             });
         }
+        /**
+         * Read a slice of a stored file without transferring the whole object.
+         *
+         * Uses an HTTP Range request, so only the requested bytes cross the wire.
+         * Slicing is positional and format-agnostic — it works on any file.
+         *
+         * ```ts
+         * // First 64 KiB
+         * const head = await dms.readRange('reports/big.csv', { length: 65536 })
+         *
+         * // Continue from where that stopped
+         * const next = await dms.readRange('reports/big.csv', { offset: head.end + 1, length: 65536 })
+         *
+         * // Final 1 KiB
+         * const tail = await dms.readRange('reports/big.csv', { suffix: 1024 })
+         * ```
+         *
+         * The server caps how much a single call may return, so `length` is an upper
+         * bound rather than a guarantee: always advance using the returned `end`
+         * rather than assuming the window you asked for. `eof` tells you when to stop.
+         *
+         * Byte ranges are not meaningful for .xlsx, .zip or .gz — their contents are
+         * compressed as a unit, so no byte window corresponds to a range of rows.
+         *
+         * @param key Path of the file within the library
+         * @param range Which bytes to read
+         * @throws If the object is smaller than `offset` (nothing left to read), or if
+         *         the response came back without range metadata — see `readRange`'s
+         *         Content-Range check, which prevents silently receiving a whole file.
+         */
+        async readRange(key, range = {}) {
+            const { responseType = 'arraybuffer' } = range;
+            const resp = await this.request('GET', `media/get/${key}`, {
+                headers: { Range: buildRangeHeader(range) },
+                responseType,
+            });
+            return toByteRangeResult(resp);
+        }
+        /**
+         * Read a file as a sequence of byte windows, newest request issued only when
+         * the previous window has been consumed.
+         *
+         * This is the memory-bounded way to process a large file: the whole object is
+         * never held at once, and a caller can stop early simply by breaking out.
+         *
+         * ```ts
+         * for await (const chunk of dms.streamRanges('logs/huge.ndjson', { chunkSize: 1 << 20 })) {
+         *     process(chunk.data)          // one window at a time
+         *     if (foundWhatIWanted) break  // no further requests are made
+         * }
+         * ```
+         *
+         * Windows are contiguous and non-overlapping, so concatenating every `data`
+         * reproduces the file byte for byte. A record spanning a window boundary is
+         * the caller's to reassemble — this yields bytes, not records.
+         *
+         * An empty object yields nothing rather than throwing.
+         *
+         * @param key Path of the file within the library
+         * @param options Where to start and how large each window should be
+         */
+        async *streamRanges(key, options = {}) {
+            var _a, _b;
+            const { chunkSize = 1024 * 1024, responseType = 'arraybuffer' } = options;
+            let offset = (_a = options.offset) !== null && _a !== void 0 ? _a : 0;
+            for (;;) {
+                let chunk;
+                try {
+                    chunk = await this.readRange(key, { offset, length: chunkSize, responseType });
+                }
+                catch (err) {
+                    // 416 means the offset is at or past the end. For the first request
+                    // that is an empty object; afterwards it is a benign race with a
+                    // truncating writer. Either way the stream is simply over.
+                    if (((_b = err === null || err === void 0 ? void 0 : err.response) === null || _b === void 0 ? void 0 : _b.status) === 416)
+                        return;
+                    throw err;
+                }
+                yield chunk;
+                if (chunk.eof)
+                    return;
+                // Advance from what the server actually returned, never from chunkSize:
+                // the per-request cap can make a window shorter than requested, and
+                // assuming otherwise would skip bytes.
+                offset = chunk.end + 1;
+            }
+        }
         async download(key) {
             return this.request('POST', `media/download`, {
                 data: {

package/dist/index.0.9.js

@@ -1355,6 +1355,70 @@ var ProtokolSDK09 = (function (exports, axios) {
         }
     }
 
+    /**
+     * Build an RFC 7233 Range header value from the SDK's range options.
+     *
+     * Validation happens here rather than at the server so a typo (a float offset, a
+     * negative length) fails immediately and locally instead of arriving as an opaque
+     * 400 after a round trip.
+     */
+    function buildRangeHeader(range) {
+        const { offset, length, suffix } = range;
+        if (suffix !== undefined) {
+            if (offset !== undefined || length !== undefined) {
+                throw new Error('readRange: `suffix` cannot be combined with `offset` or `length`');
+            }
+            if (!Number.isInteger(suffix) || suffix <= 0) {
+                throw new Error('readRange: `suffix` must be a positive integer');
+            }
+            return `bytes=-${suffix}`;
+        }
+        const start = offset !== null && offset !== void 0 ? offset : 0;
+        if (!Number.isInteger(start) || start < 0) {
+            throw new Error('readRange: `offset` must be a non-negative integer');
+        }
+        if (length === undefined) {
+            return `bytes=${start}-`;
+        }
+        if (!Number.isInteger(length) || length <= 0) {
+            throw new Error('readRange: `length` must be a positive integer');
+        }
+        // Range end offsets are inclusive, so a length of N ends at start + N - 1.
+        return `bytes=${start}-${start + length - 1}`;
+    }
+    /**
+     * Turn a 206 response into a ByteRangeResult.
+     *
+     * The Content-Range check is the important part. Requests reach media-api through
+     * two proxies, and if any hop ever dropped the Range header the response would be
+     * a perfectly valid 200 carrying the *entire* file — a caller asking for 64 KiB
+     * of a 2 GB object would quietly receive all 2 GB. Failing loudly here turns that
+     * from a silent memory blow-up into an actionable error.
+     */
+    function toByteRangeResult(resp) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const contentRange = (_b = (_a = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _a === void 0 ? void 0 : _a['content-range']) !== null && _b !== void 0 ? _b : (_c = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _c === void 0 ? void 0 : _c['Content-Range'];
+        const parsed = /^bytes\s+(\d+)-(\d+)\/(\d+)$/.exec(String(contentRange !== null && contentRange !== void 0 ? contentRange : '').trim());
+        if (!parsed) {
+            throw new Error('readRange: response did not include a Content-Range header, so the returned body ' +
+                'may be the entire object rather than the requested range. ' +
+                'Check that the media host supports ranged reads and that no proxy is stripping the Range header.');
+        }
+        const start = Number(parsed[1]);
+        const end = Number(parsed[2]);
+        const totalSize = Number(parsed[3]);
+        const etag = (_e = (_d = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _d === void 0 ? void 0 : _d.etag) !== null && _e !== void 0 ? _e : (_f = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _f === void 0 ? void 0 : _f.ETag;
+        return {
+            data: resp.data,
+            start,
+            end,
+            length: end - start + 1,
+            totalSize,
+            eof: end >= totalSize - 1,
+            etag: typeof etag === 'string' ? etag.replace(/^"|"$/g, '') : undefined,
+            contentType: (_g = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _g === void 0 ? void 0 : _g['content-type'],
+        };
+    }
     /**
      * Document Management System (DMS) API client
      *
@@ -1488,6 +1552,95 @@ var ProtokolSDK09 = (function (exports, axios) {
                 responseType: (!encoding) ? 'blob' : null
             });
         }
+        /**
+         * Read a slice of a stored file without transferring the whole object.
+         *
+         * Uses an HTTP Range request, so only the requested bytes cross the wire.
+         * Slicing is positional and format-agnostic — it works on any file.
+         *
+         * ```ts
+         * // First 64 KiB
+         * const head = await dms.readRange(libraryUuid, 'reports/big.csv', { length: 65536 })
+         *
+         * // Continue from where that stopped
+         * const next = await dms.readRange(libraryUuid, 'reports/big.csv', { offset: head.end + 1, length: 65536 })
+         *
+         * // Final 1 KiB
+         * const tail = await dms.readRange(libraryUuid, 'reports/big.csv', { suffix: 1024 })
+         * ```
+         *
+         * The server caps how much a single call may return, so `length` is an upper
+         * bound rather than a guarantee: always advance using the returned `end`
+         * rather than assuming the window you asked for. `eof` tells you when to stop.
+         *
+         * Byte ranges are not meaningful for .xlsx, .zip or .gz — their contents are
+         * compressed as a unit, so no byte window corresponds to a range of rows.
+         *
+         * @param lib Library UUID
+         * @param key Path of the file within the library
+         * @param range Which bytes to read
+         * @throws If the object is smaller than `offset` (nothing left to read), or if
+         *         the response came back without range metadata — see `readRange`'s
+         *         Content-Range check, which prevents silently receiving a whole file.
+         */
+        async readRange(lib, key, range = {}) {
+            const { responseType = 'arraybuffer' } = range;
+            const resp = await this.request('GET', `media/library/${lib}/get/${key}`, {
+                headers: { Range: buildRangeHeader(range) },
+                responseType,
+            });
+            return toByteRangeResult(resp);
+        }
+        /**
+         * Read a file as a sequence of byte windows, newest request issued only when
+         * the previous window has been consumed.
+         *
+         * This is the memory-bounded way to process a large file: the whole object is
+         * never held at once, and a caller can stop early simply by breaking out.
+         *
+         * ```ts
+         * for await (const chunk of dms.streamRanges(libraryUuid, 'logs/huge.ndjson', { chunkSize: 1 << 20 })) {
+         *     process(chunk.data)          // one window at a time
+         *     if (foundWhatIWanted) break  // no further requests are made
+         * }
+         * ```
+         *
+         * Windows are contiguous and non-overlapping, so concatenating every `data`
+         * reproduces the file byte for byte. A record spanning a window boundary is
+         * the caller's to reassemble — this yields bytes, not records.
+         *
+         * An empty object yields nothing rather than throwing.
+         *
+         * @param lib Library UUID
+         * @param key Path of the file within the library
+         * @param options Where to start and how large each window should be
+         */
+        async *streamRanges(lib, key, options = {}) {
+            var _a, _b;
+            const { chunkSize = 1024 * 1024, responseType = 'arraybuffer' } = options;
+            let offset = (_a = options.offset) !== null && _a !== void 0 ? _a : 0;
+            for (;;) {
+                let chunk;
+                try {
+                    chunk = await this.readRange(lib, key, { offset, length: chunkSize, responseType });
+                }
+                catch (err) {
+                    // 416 means the offset is at or past the end. For the first request
+                    // that is an empty object; afterwards it is a benign race with a
+                    // truncating writer. Either way the stream is simply over.
+                    if (((_b = err === null || err === void 0 ? void 0 : err.response) === null || _b === void 0 ? void 0 : _b.status) === 416)
+                        return;
+                    throw err;
+                }
+                yield chunk;
+                if (chunk.eof)
+                    return;
+                // Advance from what the server actually returned, never from chunkSize:
+                // the per-request cap can make a window shorter than requested, and
+                // assuming otherwise would skip bytes.
+                offset = chunk.end + 1;
+            }
+        }
         async download(lib, key) {
             return this.request('POST', `media/library/${lib}/download`, {
                 data: {

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ptkl/sdk",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "scripts": {
     "build": "rollup -c",
     "build:monaco": "npm run build && node scripts/generate-monaco-types.cjs",

package/dist/v0.10/api/integrations/dms.d.ts

@@ -1,6 +1,6 @@
 import IntegrationsBaseClient from "../integrationsBaseClient";
 import { AxiosResponse } from "axios";
-import { PDFFillOptions, DataConversionParams, DataValidationParams, DataInfoParams, DataInfo, DataValidationResult, ConversionOptions, HTML2PDFOptions, PDF2HTMLOptions, MediaUploadPayload, MediaUploadBase64Payload, DocumentListParams, DocumentListResponse, DocumentCreatePayload, DocumentUpdatePayload, DocumentRestorePayload, DocumentCommentPayload, DocumentResponse, DocumentGeneratePayload, DocumentGenerateResponse, DocumentRevisionListResponse, ExtractTextPayload, ExtractTextResult, OCRExtractPayload, OCRExtractResult, LibraryExportCreatePayload, LibraryExportListResponse, MediaExportCreateResult, LibraryExportGetResult, LibraryPolicy, LibraryPolicyPayload, DirPolicy, DirPolicyPayload, NotificationRuleCreatePayload, NotificationRule, NotificationRuleListResponse, FileNotificationCreatePayload, FileNotification, FileNotificationListResponse } from "../../types/integrations";
+import { PDFFillOptions, DataConversionParams, DataValidationParams, DataInfoParams, DataInfo, DataValidationResult, ConversionOptions, HTML2PDFOptions, PDF2HTMLOptions, MediaUploadPayload, MediaUploadBase64Payload, DocumentListParams, DocumentListResponse, DocumentCreatePayload, DocumentUpdatePayload, DocumentRestorePayload, DocumentCommentPayload, DocumentResponse, DocumentGeneratePayload, DocumentGenerateResponse, DocumentRevisionListResponse, ExtractTextPayload, ExtractTextResult, OCRExtractPayload, OCRExtractResult, LibraryExportCreatePayload, LibraryExportListResponse, MediaExportCreateResult, LibraryExportGetResult, LibraryPolicy, LibraryPolicyPayload, DirPolicy, DirPolicyPayload, NotificationRuleCreatePayload, NotificationRule, NotificationRuleListResponse, FileNotificationCreatePayload, FileNotification, FileNotificationListResponse, ByteRangeRequest, ByteRangeResult, ByteStreamOptions } from "../../types/integrations";
 /**
  * Document Management System (DMS) API client
  *
@@ -126,6 +126,61 @@ export default class DMS extends IntegrationsBaseClient {
      */
     uploadBase64(data: MediaUploadBase64Payload): Promise<AxiosResponse<any, any>>;
     getMedia(key: string, encoding: string): Promise<AxiosResponse<any, any>>;
+    /**
+     * Read a slice of a stored file without transferring the whole object.
+     *
+     * Uses an HTTP Range request, so only the requested bytes cross the wire.
+     * Slicing is positional and format-agnostic — it works on any file.
+     *
+     * ```ts
+     * // First 64 KiB
+     * const head = await dms.readRange('reports/big.csv', { length: 65536 })
+     *
+     * // Continue from where that stopped
+     * const next = await dms.readRange('reports/big.csv', { offset: head.end + 1, length: 65536 })
+     *
+     * // Final 1 KiB
+     * const tail = await dms.readRange('reports/big.csv', { suffix: 1024 })
+     * ```
+     *
+     * The server caps how much a single call may return, so `length` is an upper
+     * bound rather than a guarantee: always advance using the returned `end`
+     * rather than assuming the window you asked for. `eof` tells you when to stop.
+     *
+     * Byte ranges are not meaningful for .xlsx, .zip or .gz — their contents are
+     * compressed as a unit, so no byte window corresponds to a range of rows.
+     *
+     * @param key Path of the file within the library
+     * @param range Which bytes to read
+     * @throws If the object is smaller than `offset` (nothing left to read), or if
+     *         the response came back without range metadata — see `readRange`'s
+     *         Content-Range check, which prevents silently receiving a whole file.
+     */
+    readRange(key: string, range?: ByteRangeRequest): Promise<ByteRangeResult>;
+    /**
+     * Read a file as a sequence of byte windows, newest request issued only when
+     * the previous window has been consumed.
+     *
+     * This is the memory-bounded way to process a large file: the whole object is
+     * never held at once, and a caller can stop early simply by breaking out.
+     *
+     * ```ts
+     * for await (const chunk of dms.streamRanges('logs/huge.ndjson', { chunkSize: 1 << 20 })) {
+     *     process(chunk.data)          // one window at a time
+     *     if (foundWhatIWanted) break  // no further requests are made
+     * }
+     * ```
+     *
+     * Windows are contiguous and non-overlapping, so concatenating every `data`
+     * reproduces the file byte for byte. A record spanning a window boundary is
+     * the caller's to reassemble — this yields bytes, not records.
+     *
+     * An empty object yields nothing rather than throwing.
+     *
+     * @param key Path of the file within the library
+     * @param options Where to start and how large each window should be
+     */
+    streamRanges(key: string, options?: ByteStreamOptions): AsyncGenerator<ByteRangeResult>;
     download(key: string): Promise<AxiosResponse<any, any>>;
     getExifData(key: string): Promise<AxiosResponse<any, any>>;
     html2pdf(data: HTML2PDFOptions): Promise<AxiosResponse<any, any>>;

package/dist/v0.10/index.cjs.js

@@ -21138,6 +21138,70 @@ class IntegrationsBaseClient extends BaseClient {
     }
 }
 
+/**
+ * Build an RFC 7233 Range header value from the SDK's range options.
+ *
+ * Validation happens here rather than at the server so a typo (a float offset, a
+ * negative length) fails immediately and locally instead of arriving as an opaque
+ * 400 after a round trip.
+ */
+function buildRangeHeader(range) {
+    const { offset, length, suffix } = range;
+    if (suffix !== undefined) {
+        if (offset !== undefined || length !== undefined) {
+            throw new Error('readRange: `suffix` cannot be combined with `offset` or `length`');
+        }
+        if (!Number.isInteger(suffix) || suffix <= 0) {
+            throw new Error('readRange: `suffix` must be a positive integer');
+        }
+        return `bytes=-${suffix}`;
+    }
+    const start = offset !== null && offset !== void 0 ? offset : 0;
+    if (!Number.isInteger(start) || start < 0) {
+        throw new Error('readRange: `offset` must be a non-negative integer');
+    }
+    if (length === undefined) {
+        return `bytes=${start}-`;
+    }
+    if (!Number.isInteger(length) || length <= 0) {
+        throw new Error('readRange: `length` must be a positive integer');
+    }
+    // Range end offsets are inclusive, so a length of N ends at start + N - 1.
+    return `bytes=${start}-${start + length - 1}`;
+}
+/**
+ * Turn a 206 response into a ByteRangeResult.
+ *
+ * The Content-Range check is the important part. Requests reach media-api through
+ * two proxies, and if any hop ever dropped the Range header the response would be
+ * a perfectly valid 200 carrying the *entire* file — a caller asking for 64 KiB
+ * of a 2 GB object would quietly receive all 2 GB. Failing loudly here turns that
+ * from a silent memory blow-up into an actionable error.
+ */
+function toByteRangeResult(resp) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const contentRange = (_b = (_a = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _a === void 0 ? void 0 : _a['content-range']) !== null && _b !== void 0 ? _b : (_c = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _c === void 0 ? void 0 : _c['Content-Range'];
+    const parsed = /^bytes\s+(\d+)-(\d+)\/(\d+)$/.exec(String(contentRange !== null && contentRange !== void 0 ? contentRange : '').trim());
+    if (!parsed) {
+        throw new Error('readRange: response did not include a Content-Range header, so the returned body ' +
+            'may be the entire object rather than the requested range. ' +
+            'Check that the media host supports ranged reads and that no proxy is stripping the Range header.');
+    }
+    const start = Number(parsed[1]);
+    const end = Number(parsed[2]);
+    const totalSize = Number(parsed[3]);
+    const etag = (_e = (_d = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _d === void 0 ? void 0 : _d.etag) !== null && _e !== void 0 ? _e : (_f = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _f === void 0 ? void 0 : _f.ETag;
+    return {
+        data: resp.data,
+        start,
+        end,
+        length: end - start + 1,
+        totalSize,
+        eof: end >= totalSize - 1,
+        etag: typeof etag === 'string' ? etag.replace(/^"|"$/g, '') : undefined,
+        contentType: (_g = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _g === void 0 ? void 0 : _g['content-type'],
+    };
+}
 /**
  * Document Management System (DMS) API client
  *
@@ -21312,6 +21376,93 @@ class DMS extends IntegrationsBaseClient {
             responseType: (!encoding) ? 'blob' : null
         });
     }
+    /**
+     * Read a slice of a stored file without transferring the whole object.
+     *
+     * Uses an HTTP Range request, so only the requested bytes cross the wire.
+     * Slicing is positional and format-agnostic — it works on any file.
+     *
+     * ```ts
+     * // First 64 KiB
+     * const head = await dms.readRange('reports/big.csv', { length: 65536 })
+     *
+     * // Continue from where that stopped
+     * const next = await dms.readRange('reports/big.csv', { offset: head.end + 1, length: 65536 })
+     *
+     * // Final 1 KiB
+     * const tail = await dms.readRange('reports/big.csv', { suffix: 1024 })
+     * ```
+     *
+     * The server caps how much a single call may return, so `length` is an upper
+     * bound rather than a guarantee: always advance using the returned `end`
+     * rather than assuming the window you asked for. `eof` tells you when to stop.
+     *
+     * Byte ranges are not meaningful for .xlsx, .zip or .gz — their contents are
+     * compressed as a unit, so no byte window corresponds to a range of rows.
+     *
+     * @param key Path of the file within the library
+     * @param range Which bytes to read
+     * @throws If the object is smaller than `offset` (nothing left to read), or if
+     *         the response came back without range metadata — see `readRange`'s
+     *         Content-Range check, which prevents silently receiving a whole file.
+     */
+    async readRange(key, range = {}) {
+        const { responseType = 'arraybuffer' } = range;
+        const resp = await this.request('GET', `media/get/${key}`, {
+            headers: { Range: buildRangeHeader(range) },
+            responseType,
+        });
+        return toByteRangeResult(resp);
+    }
+    /**
+     * Read a file as a sequence of byte windows, newest request issued only when
+     * the previous window has been consumed.
+     *
+     * This is the memory-bounded way to process a large file: the whole object is
+     * never held at once, and a caller can stop early simply by breaking out.
+     *
+     * ```ts
+     * for await (const chunk of dms.streamRanges('logs/huge.ndjson', { chunkSize: 1 << 20 })) {
+     *     process(chunk.data)          // one window at a time
+     *     if (foundWhatIWanted) break  // no further requests are made
+     * }
+     * ```
+     *
+     * Windows are contiguous and non-overlapping, so concatenating every `data`
+     * reproduces the file byte for byte. A record spanning a window boundary is
+     * the caller's to reassemble — this yields bytes, not records.
+     *
+     * An empty object yields nothing rather than throwing.
+     *
+     * @param key Path of the file within the library
+     * @param options Where to start and how large each window should be
+     */
+    async *streamRanges(key, options = {}) {
+        var _a, _b;
+        const { chunkSize = 1024 * 1024, responseType = 'arraybuffer' } = options;
+        let offset = (_a = options.offset) !== null && _a !== void 0 ? _a : 0;
+        for (;;) {
+            let chunk;
+            try {
+                chunk = await this.readRange(key, { offset, length: chunkSize, responseType });
+            }
+            catch (err) {
+                // 416 means the offset is at or past the end. For the first request
+                // that is an empty object; afterwards it is a benign race with a
+                // truncating writer. Either way the stream is simply over.
+                if (((_b = err === null || err === void 0 ? void 0 : err.response) === null || _b === void 0 ? void 0 : _b.status) === 416)
+                    return;
+                throw err;
+            }
+            yield chunk;
+            if (chunk.eof)
+                return;
+            // Advance from what the server actually returned, never from chunkSize:
+            // the per-request cap can make a window shorter than requested, and
+            // assuming otherwise would skip bytes.
+            offset = chunk.end + 1;
+        }
+    }
     async download(key) {
         return this.request('POST', `media/download`, {
             data: {

package/dist/v0.10/index.esm.js

@@ -2171,6 +2171,70 @@ class IntegrationsBaseClient extends BaseClient {
     }
 }
 
+/**
+ * Build an RFC 7233 Range header value from the SDK's range options.
+ *
+ * Validation happens here rather than at the server so a typo (a float offset, a
+ * negative length) fails immediately and locally instead of arriving as an opaque
+ * 400 after a round trip.
+ */
+function buildRangeHeader(range) {
+    const { offset, length, suffix } = range;
+    if (suffix !== undefined) {
+        if (offset !== undefined || length !== undefined) {
+            throw new Error('readRange: `suffix` cannot be combined with `offset` or `length`');
+        }
+        if (!Number.isInteger(suffix) || suffix <= 0) {
+            throw new Error('readRange: `suffix` must be a positive integer');
+        }
+        return `bytes=-${suffix}`;
+    }
+    const start = offset !== null && offset !== void 0 ? offset : 0;
+    if (!Number.isInteger(start) || start < 0) {
+        throw new Error('readRange: `offset` must be a non-negative integer');
+    }
+    if (length === undefined) {
+        return `bytes=${start}-`;
+    }
+    if (!Number.isInteger(length) || length <= 0) {
+        throw new Error('readRange: `length` must be a positive integer');
+    }
+    // Range end offsets are inclusive, so a length of N ends at start + N - 1.
+    return `bytes=${start}-${start + length - 1}`;
+}
+/**
+ * Turn a 206 response into a ByteRangeResult.
+ *
+ * The Content-Range check is the important part. Requests reach media-api through
+ * two proxies, and if any hop ever dropped the Range header the response would be
+ * a perfectly valid 200 carrying the *entire* file — a caller asking for 64 KiB
+ * of a 2 GB object would quietly receive all 2 GB. Failing loudly here turns that
+ * from a silent memory blow-up into an actionable error.
+ */
+function toByteRangeResult(resp) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const contentRange = (_b = (_a = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _a === void 0 ? void 0 : _a['content-range']) !== null && _b !== void 0 ? _b : (_c = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _c === void 0 ? void 0 : _c['Content-Range'];
+    const parsed = /^bytes\s+(\d+)-(\d+)\/(\d+)$/.exec(String(contentRange !== null && contentRange !== void 0 ? contentRange : '').trim());
+    if (!parsed) {
+        throw new Error('readRange: response did not include a Content-Range header, so the returned body ' +
+            'may be the entire object rather than the requested range. ' +
+            'Check that the media host supports ranged reads and that no proxy is stripping the Range header.');
+    }
+    const start = Number(parsed[1]);
+    const end = Number(parsed[2]);
+    const totalSize = Number(parsed[3]);
+    const etag = (_e = (_d = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _d === void 0 ? void 0 : _d.etag) !== null && _e !== void 0 ? _e : (_f = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _f === void 0 ? void 0 : _f.ETag;
+    return {
+        data: resp.data,
+        start,
+        end,
+        length: end - start + 1,
+        totalSize,
+        eof: end >= totalSize - 1,
+        etag: typeof etag === 'string' ? etag.replace(/^"|"$/g, '') : undefined,
+        contentType: (_g = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _g === void 0 ? void 0 : _g['content-type'],
+    };
+}
 /**
  * Document Management System (DMS) API client
  *
@@ -2345,6 +2409,93 @@ class DMS extends IntegrationsBaseClient {
             responseType: (!encoding) ? 'blob' : null
         });
     }
+    /**
+     * Read a slice of a stored file without transferring the whole object.
+     *
+     * Uses an HTTP Range request, so only the requested bytes cross the wire.
+     * Slicing is positional and format-agnostic — it works on any file.
+     *
+     * ```ts
+     * // First 64 KiB
+     * const head = await dms.readRange('reports/big.csv', { length: 65536 })
+     *
+     * // Continue from where that stopped
+     * const next = await dms.readRange('reports/big.csv', { offset: head.end + 1, length: 65536 })
+     *
+     * // Final 1 KiB
+     * const tail = await dms.readRange('reports/big.csv', { suffix: 1024 })
+     * ```
+     *
+     * The server caps how much a single call may return, so `length` is an upper
+     * bound rather than a guarantee: always advance using the returned `end`
+     * rather than assuming the window you asked for. `eof` tells you when to stop.
+     *
+     * Byte ranges are not meaningful for .xlsx, .zip or .gz — their contents are
+     * compressed as a unit, so no byte window corresponds to a range of rows.
+     *
+     * @param key Path of the file within the library
+     * @param range Which bytes to read
+     * @throws If the object is smaller than `offset` (nothing left to read), or if
+     *         the response came back without range metadata — see `readRange`'s
+     *         Content-Range check, which prevents silently receiving a whole file.
+     */
+    async readRange(key, range = {}) {
+        const { responseType = 'arraybuffer' } = range;
+        const resp = await this.request('GET', `media/get/${key}`, {
+            headers: { Range: buildRangeHeader(range) },
+            responseType,
+        });
+        return toByteRangeResult(resp);
+    }
+    /**
+     * Read a file as a sequence of byte windows, newest request issued only when
+     * the previous window has been consumed.
+     *
+     * This is the memory-bounded way to process a large file: the whole object is
+     * never held at once, and a caller can stop early simply by breaking out.
+     *
+     * ```ts
+     * for await (const chunk of dms.streamRanges('logs/huge.ndjson', { chunkSize: 1 << 20 })) {
+     *     process(chunk.data)          // one window at a time
+     *     if (foundWhatIWanted) break  // no further requests are made
+     * }
+     * ```
+     *
+     * Windows are contiguous and non-overlapping, so concatenating every `data`
+     * reproduces the file byte for byte. A record spanning a window boundary is
+     * the caller's to reassemble — this yields bytes, not records.
+     *
+     * An empty object yields nothing rather than throwing.
+     *
+     * @param key Path of the file within the library
+     * @param options Where to start and how large each window should be
+     */
+    async *streamRanges(key, options = {}) {
+        var _a, _b;
+        const { chunkSize = 1024 * 1024, responseType = 'arraybuffer' } = options;
+        let offset = (_a = options.offset) !== null && _a !== void 0 ? _a : 0;
+        for (;;) {
+            let chunk;
+            try {
+                chunk = await this.readRange(key, { offset, length: chunkSize, responseType });
+            }
+            catch (err) {
+                // 416 means the offset is at or past the end. For the first request
+                // that is an empty object; afterwards it is a benign race with a
+                // truncating writer. Either way the stream is simply over.
+                if (((_b = err === null || err === void 0 ? void 0 : err.response) === null || _b === void 0 ? void 0 : _b.status) === 416)
+                    return;
+                throw err;
+            }
+            yield chunk;
+            if (chunk.eof)
+                return;
+            // Advance from what the server actually returned, never from chunkSize:
+            // the per-request cap can make a window shorter than requested, and
+            // assuming otherwise would skip bytes.
+            offset = chunk.end + 1;
+        }
+    }
     async download(key) {
         return this.request('POST', `media/download`, {
             data: {

package/dist/v0.10/types/integrations.d.ts

@@ -584,3 +584,47 @@ export type FileNotification = {
     recipient_email?: string;
 };
 export type FileNotificationListResponse = FileNotification[];
+/**
+ * Which bytes to read. Supply either `offset`/`length` or `suffix`, not both.
+ */
+export type ByteRangeRequest = {
+    /** First byte to read, 0-based. Defaults to 0. */
+    offset?: number;
+    /** How many bytes to read. Omit to read to the end of the object, subject to the server's per-request cap. */
+    length?: number;
+    /** Read the final N bytes instead. Mutually exclusive with `offset`/`length`. */
+    suffix?: number;
+    /** Axios response type for the body. Defaults to `arraybuffer`. */
+    responseType?: 'arraybuffer' | 'blob' | 'text';
+};
+/**
+ * A single window of bytes plus the position metadata needed to request the next one.
+ */
+export type ByteRangeResult<T = any> = {
+    /** The bytes, in the shape requested via `responseType`. */
+    data: T;
+    /** Offset of the first byte returned. */
+    start: number;
+    /** Offset of the last byte returned, inclusive. */
+    end: number;
+    /** Number of bytes returned. May be less than requested — see `ByteRangeRequest.length`. */
+    length: number;
+    /** Total size of the whole object. */
+    totalSize: number;
+    /** True when this window ends at the last byte of the object. */
+    eof: boolean;
+    /** Object validator. Changes if the object is replaced, so a multi-window scan can detect it. */
+    etag?: string;
+    contentType?: string;
+};
+/**
+ * Options for walking an object window by window.
+ */
+export type ByteStreamOptions = {
+    /** Byte offset to start from. Defaults to 0. */
+    offset?: number;
+    /** Bytes per window. Defaults to 1 MiB. The server may return less. */
+    chunkSize?: number;
+    /** Axios response type for each window. Defaults to `arraybuffer`. */
+    responseType?: 'arraybuffer' | 'blob' | 'text';
+};

package/dist/v0.9/api/integrations/dms.d.ts

@@ -1,6 +1,6 @@
 import IntegrationsBaseClient from "../integrationsBaseClient";
 import { AxiosResponse } from "axios";
-import { PDFFillOptions, DataConversionParams, DataValidationParams, DataInfoParams, DataInfo, DataValidationResult, ConversionOptions, HTML2PDFOptions } from "../../types/integrations";
+import { PDFFillOptions, DataConversionParams, DataValidationParams, DataInfoParams, DataInfo, DataValidationResult, ConversionOptions, HTML2PDFOptions, ByteRangeRequest, ByteRangeResult, ByteStreamOptions } from "../../types/integrations";
 /**
  * Document Management System (DMS) API client
  *
@@ -87,6 +87,63 @@ export default class DMS extends IntegrationsBaseClient {
     delete(data: any): Promise<AxiosResponse<any, any>>;
     uploadBase64(data: any): Promise<AxiosResponse<any, any>>;
     getMedia(lib: string, key: string, encoding: string): Promise<AxiosResponse<any, any>>;
+    /**
+     * Read a slice of a stored file without transferring the whole object.
+     *
+     * Uses an HTTP Range request, so only the requested bytes cross the wire.
+     * Slicing is positional and format-agnostic — it works on any file.
+     *
+     * ```ts
+     * // First 64 KiB
+     * const head = await dms.readRange(libraryUuid, 'reports/big.csv', { length: 65536 })
+     *
+     * // Continue from where that stopped
+     * const next = await dms.readRange(libraryUuid, 'reports/big.csv', { offset: head.end + 1, length: 65536 })
+     *
+     * // Final 1 KiB
+     * const tail = await dms.readRange(libraryUuid, 'reports/big.csv', { suffix: 1024 })
+     * ```
+     *
+     * The server caps how much a single call may return, so `length` is an upper
+     * bound rather than a guarantee: always advance using the returned `end`
+     * rather than assuming the window you asked for. `eof` tells you when to stop.
+     *
+     * Byte ranges are not meaningful for .xlsx, .zip or .gz — their contents are
+     * compressed as a unit, so no byte window corresponds to a range of rows.
+     *
+     * @param lib Library UUID
+     * @param key Path of the file within the library
+     * @param range Which bytes to read
+     * @throws If the object is smaller than `offset` (nothing left to read), or if
+     *         the response came back without range metadata — see `readRange`'s
+     *         Content-Range check, which prevents silently receiving a whole file.
+     */
+    readRange(lib: string, key: string, range?: ByteRangeRequest): Promise<ByteRangeResult>;
+    /**
+     * Read a file as a sequence of byte windows, newest request issued only when
+     * the previous window has been consumed.
+     *
+     * This is the memory-bounded way to process a large file: the whole object is
+     * never held at once, and a caller can stop early simply by breaking out.
+     *
+     * ```ts
+     * for await (const chunk of dms.streamRanges(libraryUuid, 'logs/huge.ndjson', { chunkSize: 1 << 20 })) {
+     *     process(chunk.data)          // one window at a time
+     *     if (foundWhatIWanted) break  // no further requests are made
+     * }
+     * ```
+     *
+     * Windows are contiguous and non-overlapping, so concatenating every `data`
+     * reproduces the file byte for byte. A record spanning a window boundary is
+     * the caller's to reassemble — this yields bytes, not records.
+     *
+     * An empty object yields nothing rather than throwing.
+     *
+     * @param lib Library UUID
+     * @param key Path of the file within the library
+     * @param options Where to start and how large each window should be
+     */
+    streamRanges(lib: string, key: string, options?: ByteStreamOptions): AsyncGenerator<ByteRangeResult>;
     download(lib: string, key: string): Promise<AxiosResponse<any, any>>;
     getExifData(lib: string, key: string): Promise<AxiosResponse<any, any>>;
     html2pdf(lib: string, data: HTML2PDFOptions): Promise<AxiosResponse<any, any>>;

package/dist/v0.9/index.cjs.js

@@ -20323,6 +20323,70 @@ class IntegrationsBaseClient extends BaseClient {
     }
 }
 
+/**
+ * Build an RFC 7233 Range header value from the SDK's range options.
+ *
+ * Validation happens here rather than at the server so a typo (a float offset, a
+ * negative length) fails immediately and locally instead of arriving as an opaque
+ * 400 after a round trip.
+ */
+function buildRangeHeader(range) {
+    const { offset, length, suffix } = range;
+    if (suffix !== undefined) {
+        if (offset !== undefined || length !== undefined) {
+            throw new Error('readRange: `suffix` cannot be combined with `offset` or `length`');
+        }
+        if (!Number.isInteger(suffix) || suffix <= 0) {
+            throw new Error('readRange: `suffix` must be a positive integer');
+        }
+        return `bytes=-${suffix}`;
+    }
+    const start = offset !== null && offset !== void 0 ? offset : 0;
+    if (!Number.isInteger(start) || start < 0) {
+        throw new Error('readRange: `offset` must be a non-negative integer');
+    }
+    if (length === undefined) {
+        return `bytes=${start}-`;
+    }
+    if (!Number.isInteger(length) || length <= 0) {
+        throw new Error('readRange: `length` must be a positive integer');
+    }
+    // Range end offsets are inclusive, so a length of N ends at start + N - 1.
+    return `bytes=${start}-${start + length - 1}`;
+}
+/**
+ * Turn a 206 response into a ByteRangeResult.
+ *
+ * The Content-Range check is the important part. Requests reach media-api through
+ * two proxies, and if any hop ever dropped the Range header the response would be
+ * a perfectly valid 200 carrying the *entire* file — a caller asking for 64 KiB
+ * of a 2 GB object would quietly receive all 2 GB. Failing loudly here turns that
+ * from a silent memory blow-up into an actionable error.
+ */
+function toByteRangeResult(resp) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const contentRange = (_b = (_a = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _a === void 0 ? void 0 : _a['content-range']) !== null && _b !== void 0 ? _b : (_c = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _c === void 0 ? void 0 : _c['Content-Range'];
+    const parsed = /^bytes\s+(\d+)-(\d+)\/(\d+)$/.exec(String(contentRange !== null && contentRange !== void 0 ? contentRange : '').trim());
+    if (!parsed) {
+        throw new Error('readRange: response did not include a Content-Range header, so the returned body ' +
+            'may be the entire object rather than the requested range. ' +
+            'Check that the media host supports ranged reads and that no proxy is stripping the Range header.');
+    }
+    const start = Number(parsed[1]);
+    const end = Number(parsed[2]);
+    const totalSize = Number(parsed[3]);
+    const etag = (_e = (_d = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _d === void 0 ? void 0 : _d.etag) !== null && _e !== void 0 ? _e : (_f = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _f === void 0 ? void 0 : _f.ETag;
+    return {
+        data: resp.data,
+        start,
+        end,
+        length: end - start + 1,
+        totalSize,
+        eof: end >= totalSize - 1,
+        etag: typeof etag === 'string' ? etag.replace(/^"|"$/g, '') : undefined,
+        contentType: (_g = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _g === void 0 ? void 0 : _g['content-type'],
+    };
+}
 /**
  * Document Management System (DMS) API client
  *
@@ -20456,6 +20520,95 @@ class DMS extends IntegrationsBaseClient {
             responseType: (!encoding) ? 'blob' : null
         });
     }
+    /**
+     * Read a slice of a stored file without transferring the whole object.
+     *
+     * Uses an HTTP Range request, so only the requested bytes cross the wire.
+     * Slicing is positional and format-agnostic — it works on any file.
+     *
+     * ```ts
+     * // First 64 KiB
+     * const head = await dms.readRange(libraryUuid, 'reports/big.csv', { length: 65536 })
+     *
+     * // Continue from where that stopped
+     * const next = await dms.readRange(libraryUuid, 'reports/big.csv', { offset: head.end + 1, length: 65536 })
+     *
+     * // Final 1 KiB
+     * const tail = await dms.readRange(libraryUuid, 'reports/big.csv', { suffix: 1024 })
+     * ```
+     *
+     * The server caps how much a single call may return, so `length` is an upper
+     * bound rather than a guarantee: always advance using the returned `end`
+     * rather than assuming the window you asked for. `eof` tells you when to stop.
+     *
+     * Byte ranges are not meaningful for .xlsx, .zip or .gz — their contents are
+     * compressed as a unit, so no byte window corresponds to a range of rows.
+     *
+     * @param lib Library UUID
+     * @param key Path of the file within the library
+     * @param range Which bytes to read
+     * @throws If the object is smaller than `offset` (nothing left to read), or if
+     *         the response came back without range metadata — see `readRange`'s
+     *         Content-Range check, which prevents silently receiving a whole file.
+     */
+    async readRange(lib, key, range = {}) {
+        const { responseType = 'arraybuffer' } = range;
+        const resp = await this.request('GET', `media/library/${lib}/get/${key}`, {
+            headers: { Range: buildRangeHeader(range) },
+            responseType,
+        });
+        return toByteRangeResult(resp);
+    }
+    /**
+     * Read a file as a sequence of byte windows, newest request issued only when
+     * the previous window has been consumed.
+     *
+     * This is the memory-bounded way to process a large file: the whole object is
+     * never held at once, and a caller can stop early simply by breaking out.
+     *
+     * ```ts
+     * for await (const chunk of dms.streamRanges(libraryUuid, 'logs/huge.ndjson', { chunkSize: 1 << 20 })) {
+     *     process(chunk.data)          // one window at a time
+     *     if (foundWhatIWanted) break  // no further requests are made
+     * }
+     * ```
+     *
+     * Windows are contiguous and non-overlapping, so concatenating every `data`
+     * reproduces the file byte for byte. A record spanning a window boundary is
+     * the caller's to reassemble — this yields bytes, not records.
+     *
+     * An empty object yields nothing rather than throwing.
+     *
+     * @param lib Library UUID
+     * @param key Path of the file within the library
+     * @param options Where to start and how large each window should be
+     */
+    async *streamRanges(lib, key, options = {}) {
+        var _a, _b;
+        const { chunkSize = 1024 * 1024, responseType = 'arraybuffer' } = options;
+        let offset = (_a = options.offset) !== null && _a !== void 0 ? _a : 0;
+        for (;;) {
+            let chunk;
+            try {
+                chunk = await this.readRange(lib, key, { offset, length: chunkSize, responseType });
+            }
+            catch (err) {
+                // 416 means the offset is at or past the end. For the first request
+                // that is an empty object; afterwards it is a benign race with a
+                // truncating writer. Either way the stream is simply over.
+                if (((_b = err === null || err === void 0 ? void 0 : err.response) === null || _b === void 0 ? void 0 : _b.status) === 416)
+                    return;
+                throw err;
+            }
+            yield chunk;
+            if (chunk.eof)
+                return;
+            // Advance from what the server actually returned, never from chunkSize:
+            // the per-request cap can make a window shorter than requested, and
+            // assuming otherwise would skip bytes.
+            offset = chunk.end + 1;
+        }
+    }
     async download(lib, key) {
         return this.request('POST', `media/library/${lib}/download`, {
             data: {

package/dist/v0.9/index.esm.js

@@ -1354,6 +1354,70 @@ class IntegrationsBaseClient extends BaseClient {
     }
 }
 
+/**
+ * Build an RFC 7233 Range header value from the SDK's range options.
+ *
+ * Validation happens here rather than at the server so a typo (a float offset, a
+ * negative length) fails immediately and locally instead of arriving as an opaque
+ * 400 after a round trip.
+ */
+function buildRangeHeader(range) {
+    const { offset, length, suffix } = range;
+    if (suffix !== undefined) {
+        if (offset !== undefined || length !== undefined) {
+            throw new Error('readRange: `suffix` cannot be combined with `offset` or `length`');
+        }
+        if (!Number.isInteger(suffix) || suffix <= 0) {
+            throw new Error('readRange: `suffix` must be a positive integer');
+        }
+        return `bytes=-${suffix}`;
+    }
+    const start = offset !== null && offset !== void 0 ? offset : 0;
+    if (!Number.isInteger(start) || start < 0) {
+        throw new Error('readRange: `offset` must be a non-negative integer');
+    }
+    if (length === undefined) {
+        return `bytes=${start}-`;
+    }
+    if (!Number.isInteger(length) || length <= 0) {
+        throw new Error('readRange: `length` must be a positive integer');
+    }
+    // Range end offsets are inclusive, so a length of N ends at start + N - 1.
+    return `bytes=${start}-${start + length - 1}`;
+}
+/**
+ * Turn a 206 response into a ByteRangeResult.
+ *
+ * The Content-Range check is the important part. Requests reach media-api through
+ * two proxies, and if any hop ever dropped the Range header the response would be
+ * a perfectly valid 200 carrying the *entire* file — a caller asking for 64 KiB
+ * of a 2 GB object would quietly receive all 2 GB. Failing loudly here turns that
+ * from a silent memory blow-up into an actionable error.
+ */
+function toByteRangeResult(resp) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const contentRange = (_b = (_a = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _a === void 0 ? void 0 : _a['content-range']) !== null && _b !== void 0 ? _b : (_c = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _c === void 0 ? void 0 : _c['Content-Range'];
+    const parsed = /^bytes\s+(\d+)-(\d+)\/(\d+)$/.exec(String(contentRange !== null && contentRange !== void 0 ? contentRange : '').trim());
+    if (!parsed) {
+        throw new Error('readRange: response did not include a Content-Range header, so the returned body ' +
+            'may be the entire object rather than the requested range. ' +
+            'Check that the media host supports ranged reads and that no proxy is stripping the Range header.');
+    }
+    const start = Number(parsed[1]);
+    const end = Number(parsed[2]);
+    const totalSize = Number(parsed[3]);
+    const etag = (_e = (_d = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _d === void 0 ? void 0 : _d.etag) !== null && _e !== void 0 ? _e : (_f = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _f === void 0 ? void 0 : _f.ETag;
+    return {
+        data: resp.data,
+        start,
+        end,
+        length: end - start + 1,
+        totalSize,
+        eof: end >= totalSize - 1,
+        etag: typeof etag === 'string' ? etag.replace(/^"|"$/g, '') : undefined,
+        contentType: (_g = resp === null || resp === void 0 ? void 0 : resp.headers) === null || _g === void 0 ? void 0 : _g['content-type'],
+    };
+}
 /**
  * Document Management System (DMS) API client
  *
@@ -1487,6 +1551,95 @@ class DMS extends IntegrationsBaseClient {
             responseType: (!encoding) ? 'blob' : null
         });
     }
+    /**
+     * Read a slice of a stored file without transferring the whole object.
+     *
+     * Uses an HTTP Range request, so only the requested bytes cross the wire.
+     * Slicing is positional and format-agnostic — it works on any file.
+     *
+     * ```ts
+     * // First 64 KiB
+     * const head = await dms.readRange(libraryUuid, 'reports/big.csv', { length: 65536 })
+     *
+     * // Continue from where that stopped
+     * const next = await dms.readRange(libraryUuid, 'reports/big.csv', { offset: head.end + 1, length: 65536 })
+     *
+     * // Final 1 KiB
+     * const tail = await dms.readRange(libraryUuid, 'reports/big.csv', { suffix: 1024 })
+     * ```
+     *
+     * The server caps how much a single call may return, so `length` is an upper
+     * bound rather than a guarantee: always advance using the returned `end`
+     * rather than assuming the window you asked for. `eof` tells you when to stop.
+     *
+     * Byte ranges are not meaningful for .xlsx, .zip or .gz — their contents are
+     * compressed as a unit, so no byte window corresponds to a range of rows.
+     *
+     * @param lib Library UUID
+     * @param key Path of the file within the library
+     * @param range Which bytes to read
+     * @throws If the object is smaller than `offset` (nothing left to read), or if
+     *         the response came back without range metadata — see `readRange`'s
+     *         Content-Range check, which prevents silently receiving a whole file.
+     */
+    async readRange(lib, key, range = {}) {
+        const { responseType = 'arraybuffer' } = range;
+        const resp = await this.request('GET', `media/library/${lib}/get/${key}`, {
+            headers: { Range: buildRangeHeader(range) },
+            responseType,
+        });
+        return toByteRangeResult(resp);
+    }
+    /**
+     * Read a file as a sequence of byte windows, newest request issued only when
+     * the previous window has been consumed.
+     *
+     * This is the memory-bounded way to process a large file: the whole object is
+     * never held at once, and a caller can stop early simply by breaking out.
+     *
+     * ```ts
+     * for await (const chunk of dms.streamRanges(libraryUuid, 'logs/huge.ndjson', { chunkSize: 1 << 20 })) {
+     *     process(chunk.data)          // one window at a time
+     *     if (foundWhatIWanted) break  // no further requests are made
+     * }
+     * ```
+     *
+     * Windows are contiguous and non-overlapping, so concatenating every `data`
+     * reproduces the file byte for byte. A record spanning a window boundary is
+     * the caller's to reassemble — this yields bytes, not records.
+     *
+     * An empty object yields nothing rather than throwing.
+     *
+     * @param lib Library UUID
+     * @param key Path of the file within the library
+     * @param options Where to start and how large each window should be
+     */
+    async *streamRanges(lib, key, options = {}) {
+        var _a, _b;
+        const { chunkSize = 1024 * 1024, responseType = 'arraybuffer' } = options;
+        let offset = (_a = options.offset) !== null && _a !== void 0 ? _a : 0;
+        for (;;) {
+            let chunk;
+            try {
+                chunk = await this.readRange(lib, key, { offset, length: chunkSize, responseType });
+            }
+            catch (err) {
+                // 416 means the offset is at or past the end. For the first request
+                // that is an empty object; afterwards it is a benign race with a
+                // truncating writer. Either way the stream is simply over.
+                if (((_b = err === null || err === void 0 ? void 0 : err.response) === null || _b === void 0 ? void 0 : _b.status) === 416)
+                    return;
+                throw err;
+            }
+            yield chunk;
+            if (chunk.eof)
+                return;
+            // Advance from what the server actually returned, never from chunkSize:
+            // the per-request cap can make a window shorter than requested, and
+            // assuming otherwise would skip bytes.
+            offset = chunk.end + 1;
+        }
+    }
     async download(lib, key) {
         return this.request('POST', `media/library/${lib}/download`, {
             data: {

package/dist/v0.9/types/integrations.d.ts

@@ -307,3 +307,47 @@ export type DocumentCommentPayload = {
     /** Comment end position */
     to?: number;
 };
+/**
+ * Which bytes to read. Supply either `offset`/`length` or `suffix`, not both.
+ */
+export type ByteRangeRequest = {
+    /** First byte to read, 0-based. Defaults to 0. */
+    offset?: number;
+    /** How many bytes to read. Omit to read to the end of the object, subject to the server's per-request cap. */
+    length?: number;
+    /** Read the final N bytes instead. Mutually exclusive with `offset`/`length`. */
+    suffix?: number;
+    /** Axios response type for the body. Defaults to `arraybuffer`. */
+    responseType?: 'arraybuffer' | 'blob' | 'text';
+};
+/**
+ * A single window of bytes plus the position metadata needed to request the next one.
+ */
+export type ByteRangeResult<T = any> = {
+    /** The bytes, in the shape requested via `responseType`. */
+    data: T;
+    /** Offset of the first byte returned. */
+    start: number;
+    /** Offset of the last byte returned, inclusive. */
+    end: number;
+    /** Number of bytes returned. May be less than requested — see `ByteRangeRequest.length`. */
+    length: number;
+    /** Total size of the whole object. */
+    totalSize: number;
+    /** True when this window ends at the last byte of the object. */
+    eof: boolean;
+    /** Object validator. Changes if the object is replaced, so a multi-window scan can detect it. */
+    etag?: string;
+    contentType?: string;
+};
+/**
+ * Options for walking an object window by window.
+ */
+export type ByteStreamOptions = {
+    /** Byte offset to start from. Defaults to 0. */
+    offset?: number;
+    /** Bytes per window. Defaults to 1 MiB. The server may return less. */
+    chunkSize?: number;
+    /** Axios response type for each window. Defaults to `arraybuffer`. */
+    responseType?: 'arraybuffer' | 'blob' | 'text';
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ptkl/sdk",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "scripts": {
     "build": "rollup -c",
     "build:monaco": "npm run build && node scripts/generate-monaco-types.cjs",