@ptkl/sdk 1.16.0 → 1.17.1

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.1",
   "scripts": {
     "build": "rollup -c",
     "build:monaco": "npm run build && node scripts/generate-monaco-types.cjs",