@ptkl/sdk 1.16.0 → 1.17.1

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

@@ -20761,17 +20761,33 @@ class Kortex extends PlatformBaseClient {
     async injectMessage(conversationUUID, data) {
         return await this.client.post(`${BASE$1}/conversations/${conversationUUID}/messages/inject`, data);
     }
+    // ── Stateless chat ──
+    // Stateless completion — no conversation is created and nothing is
+    // persisted. The caller owns the message list.
+    //
+    // Always responds with an SSE stream (message_start, thinking_delta,
+    // content_delta, message_complete, error). Tool calls are surfaced in
+    // message_complete for client-side execution; post the results back as
+    // messages with role 'tool' and the matching tool_call_id.
+    //
+    // Constraints enforced server-side: agent_uuid is required, the last
+    // message must have role 'user', 'context' or 'tool', and no message
+    // content may exceed 32000 bytes.
+    //
+    // Typed as a Node stream because that is what axios `responseType:
+    // 'stream'` yields under Node, which is where this binding is used.
+    // Browser callers should drive the endpoint with fetch directly rather
+    // than through axios.
+    async chat(data) {
+        return await this.client.post(`${BASE$1}/chat`, data, {
+            responseType: 'stream',
+            timeout: 120000,
+        });
+    }
     // ── OCR ──
     async ocr(data) {
         return await this.client.post(`${BASE$1}/ocr`, data, { timeout: 120000 });
     }
-    // ── Workflow ──
-    async workflowComplete(data) {
-        return await this.client.post(`${BASE$1}/workflow/complete`, data);
-    }
-    async workflowOcr(data) {
-        return await this.client.post(`${BASE$1}/workflow/ocr`, data, { timeout: 120000 });
-    }
     // ── User Access ──
     async createUserAccess(data) {
         return await this.client.post(`${BASE$1}/user-access`, data);
@@ -21138,6 +21154,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 +21392,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

@@ -1794,17 +1794,33 @@ class Kortex extends PlatformBaseClient {
     async injectMessage(conversationUUID, data) {
         return await this.client.post(`${BASE$1}/conversations/${conversationUUID}/messages/inject`, data);
     }
+    // ── Stateless chat ──
+    // Stateless completion — no conversation is created and nothing is
+    // persisted. The caller owns the message list.
+    //
+    // Always responds with an SSE stream (message_start, thinking_delta,
+    // content_delta, message_complete, error). Tool calls are surfaced in
+    // message_complete for client-side execution; post the results back as
+    // messages with role 'tool' and the matching tool_call_id.
+    //
+    // Constraints enforced server-side: agent_uuid is required, the last
+    // message must have role 'user', 'context' or 'tool', and no message
+    // content may exceed 32000 bytes.
+    //
+    // Typed as a Node stream because that is what axios `responseType:
+    // 'stream'` yields under Node, which is where this binding is used.
+    // Browser callers should drive the endpoint with fetch directly rather
+    // than through axios.
+    async chat(data) {
+        return await this.client.post(`${BASE$1}/chat`, data, {
+            responseType: 'stream',
+            timeout: 120000,
+        });
+    }
     // ── OCR ──
     async ocr(data) {
         return await this.client.post(`${BASE$1}/ocr`, data, { timeout: 120000 });
     }
-    // ── Workflow ──
-    async workflowComplete(data) {
-        return await this.client.post(`${BASE$1}/workflow/complete`, data);
-    }
-    async workflowOcr(data) {
-        return await this.client.post(`${BASE$1}/workflow/ocr`, data, { timeout: 120000 });
-    }
     // ── User Access ──
     async createUserAccess(data) {
         return await this.client.post(`${BASE$1}/user-access`, data);
@@ -2171,6 +2187,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 +2425,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.10/types/kortex.d.ts

@@ -288,22 +288,16 @@ type KnowledgeBaseSearchChunk = {
 type KnowledgeBaseSearchResult = {
     chunks: KnowledgeBaseSearchChunk[];
 };
-type KortexWorkflowMessage = {
-    role: string;
+type KortexChatRole = 'user' | 'assistant' | 'context' | 'tool';
+type KortexChatMessage = {
+    role: KortexChatRole;
     content: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
 };
-type KortexWorkflowPayload = {
-    agent_uuid?: string;
-    system_prompt?: string;
-    response_format?: string;
-    messages: KortexWorkflowMessage[];
-    stream?: boolean;
-    temperature?: number;
-    max_tokens?: number;
+type KortexChatPayload = {
+    agent_uuid: string;
+    messages: KortexChatMessage[];
     tools?: Record<string, any>[];
 };
-type KortexWorkflowResult = {
-    content: string;
-    usage: TokenUsage;
-};
-export { PagedResponse, PaginationParams, RAGConfig, LLMSettings, Agent, AgentCreatePayload, AgentUpdatePayload, ChunkingStrategy, KnowledgeBase, KnowledgeBaseCreatePayload, KnowledgeBaseUpdatePayload, Document, Participant, TokenUsage, ToolCall, RAGSource, Message, Conversation, ConversationCreatePayload, ConversationUpdatePayload, ParticipantAddPayload, ToolResultApproval, ToolResultPayload, PageContext, SendMessagePayload, InjectMessagePayload, OCRPayload, OCRResult, UserAccess, UserAccessCreatePayload, UserAccessUpdatePayload, TopUpPayload, UserMonthlyUsage, UserUsageBreakdown, MyAccess, AggregatedUsage, Tier, KnowledgeBaseSearchPayload, KnowledgeBaseSearchChunk, KnowledgeBaseSearchResult, KortexWorkflowMessage, KortexWorkflowPayload, KortexWorkflowResult, };
+export { PagedResponse, PaginationParams, RAGConfig, LLMSettings, Agent, AgentCreatePayload, AgentUpdatePayload, ChunkingStrategy, KnowledgeBase, KnowledgeBaseCreatePayload, KnowledgeBaseUpdatePayload, Document, Participant, TokenUsage, ToolCall, RAGSource, Message, Conversation, ConversationCreatePayload, ConversationUpdatePayload, ParticipantAddPayload, ToolResultApproval, ToolResultPayload, PageContext, SendMessagePayload, InjectMessagePayload, OCRPayload, OCRResult, UserAccess, UserAccessCreatePayload, UserAccessUpdatePayload, TopUpPayload, UserMonthlyUsage, UserUsageBreakdown, MyAccess, AggregatedUsage, Tier, KnowledgeBaseSearchPayload, KnowledgeBaseSearchChunk, KnowledgeBaseSearchResult, KortexChatRole, KortexChatMessage, KortexChatPayload, };

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>>;