feat: Parameter to send custom page range when splitting pdf (#101)

To match the python feature:
Unstructured-IO/unstructured-python-client#125

# New parameter
Add a client-side param called `splitPdfPageRange` which takes a list of
two integers, `[start, end]`. If `splitPdfPage` is `true` and a range is
set, slice the doc from `start` up to and including `end`. Only this
page range will be sent to the API. The subset of pages is still split
up as needed. If `[start, end]` is out of bounds, throw an error to the
user.

# Testing
Check out this branch and set up a request to your local API:

```
const client = new UnstructuredClient({
    serverURL: "http://localhost:8000",
    security: {
        apiKeyAuth: key,
    },
});

const filename = "layout-parser-paper.pdf";
const data = fs.readFileSync(filename);

client.general.partition({
    partitionParameters: {
        files: {
            content: data,
            fileName: filename,
        },
        strategy: Strategy.Fast,
        splitPdfPage: true,
        splitPdfPageRange: [4, 8],
    }
}).then((res: PartitionResponse) => {
    if (res.statusCode == 200) {
        console.log(res.elements);
    }
}).catch((e) => {
    if (e.statusCode) {
      console.log(e.statusCode);
      console.log(e.body);
    } else {
      console.log(e);
    }
});
```

Test out various page ranges and confirm that the returned elements are
within the range. Invalid ranges should throw a useful Error (pages are
out of bounds, or end_page < start_page).

Author: awalker4

docs/sdk/models/shared/partitionparameters.md

@@ -21,6 +21,18 @@ actions:
           "description": "Number of maximum concurrent requests made when splitting PDF. Ignored on backend.",
           "default": 5,
         }
+  - target: $["components"]["schemas"]["partition_parameters"]["properties"]
+    update:
+      "split_pdf_page_range":
+        {
+          "type": "array",
+          "title": "Split Pdf Page Range",
+          "description": "When `split_pdf_page is set to `True`, this parameter selects a subset of the pdf to send to the API. The parameter is a list of 2 integers within the range [1, length_of_pdf]. An Error is thrown if the given range is invalid. Ignored on backend.",
+          "items": {"type": "integer"},
+          "minItems": 2,
+          "maxItems": 2,
+          "example": [1, 10],
+        }
   - target: $["components"]["schemas"]["partition_parameters"]["properties"]
     update:
       "split_pdf_allow_failed":

overlay_client.yaml

@@ -15,6 +15,7 @@ import {
   getOptimalSplitSize, getSplitPdfAllowFailed,
   getSplitPdfConcurrencyLevel,
   getStartingPageNumber,
+  getSplitPdfPageRange,
   loadPdf,
   prepareRequestBody,
   prepareRequestHeaders,
@@ -107,18 +108,14 @@ export class SplitPdfHook
       return request;
     }
 
-    const [error, pdf, pagesCount] = await loadPdf(file);
+    const [error, pdf, totalPages] = await loadPdf(file);
     if (file === null || pdf === null || error) {
       console.info("Partitioning without split.")
       return request;
     }
 
-    if (pagesCount < MIN_PAGES_PER_THREAD) {
-      console.info(
-        `PDF has less than ${MIN_PAGES_PER_THREAD} pages. Partitioning without split.`
-      );
-      return request;
-    }
+    const [pageRangeStart, pageRangeEnd] = getSplitPdfPageRange(formData, totalPages);
+    const pagesCount = pageRangeEnd - pageRangeStart + 1;
 
     const startingPageNumber = getStartingPageNumber(formData);
     console.info("Starting page number set to %d", startingPageNumber);
@@ -132,15 +129,22 @@ export class SplitPdfHook
     const splitSize = await getOptimalSplitSize(pagesCount, concurrencyLevel);
     console.info("Determined optimal split size of %d pages.", splitSize)
 
-    if (splitSize >= pagesCount) {
-      console.info(
+    // If user wants a specific page range, we need to call splitPdf,
+    // even if this page count is too small to be split normally
+    const isPageRangeRequested = pagesCount < totalPages;
+
+    // Otherwise, if there are not enough pages, return the original request without splitting
+    if (!isPageRangeRequested) {
+      if (splitSize >= pagesCount || pagesCount < MIN_PAGES_PER_THREAD) {
+        console.info(
           "Document has too few pages (%d) to be split efficiently. Partitioning without split.",
           pagesCount,
-      )
-      return request;
+        )
+        return request;
+      }
     }
 
-    const splits = await splitPdf(pdf, splitSize);
+    const splits = await splitPdf(pdf, splitSize, pageRangeStart, pageRangeEnd);
     const numberOfSplits = splits.length
     console.info(
         "Document split into %d, %d-paged sets.",

src/hooks/custom/SplitPdfHook.ts

@@ -12,6 +12,7 @@ export const PARTITION_FORM_FILES_KEY = "files";
 export const PARTITION_FORM_SPLIT_PDF_PAGE_KEY = "split_pdf_page";
 export const PARTITION_FORM_SPLIT_PDF_ALLOW_FAILED_KEY = "split_pdf_allow_failed";
 export const PARTITION_FORM_STARTING_PAGE_NUMBER_KEY = "starting_page_number";
+export const PARTITION_FORM_SPLIT_PDF_PAGE_RANGE_KEY = "split_pdf_page_range";
 export const PARTITION_FORM_SPLIT_PDF_CONCURRENCY_LEVEL =
   "split_pdf_concurrency_level";
 

src/hooks/custom/common.ts

@@ -3,6 +3,7 @@ import {
   DEFAULT_STARTING_PAGE_NUMBER,
   MAX_NUMBER_OF_PARALLEL_REQUESTS, PARTITION_FORM_SPLIT_PDF_ALLOW_FAILED_KEY,
   PARTITION_FORM_SPLIT_PDF_CONCURRENCY_LEVEL,
+  PARTITION_FORM_SPLIT_PDF_PAGE_RANGE_KEY,
   PARTITION_FORM_STARTING_PAGE_NUMBER_KEY,
 } from "../common.js";
 
@@ -78,6 +79,31 @@ function getBooleanParameter(
   return booleanParameter;
 }
 
+/**
+ * Retrieves and validates a page range from FormData, ensuring that the start and end values are defined and within bounds.
+ *
+ * @param formData - The FormData object containing the page range parameter.
+ * @param maxPages - The maximum number of pages in the document.
+ * @returns {[number, number]} - A tuple containing the validated start and end page numbers.
+ *
+ * @throws Will throw an error if the page range is invalid or out of bounds.
+ */
+export function getSplitPdfPageRange(formData: FormData, maxPages: number): [number, number] {
+  const formDataParameter = formData.get(PARTITION_FORM_SPLIT_PDF_PAGE_RANGE_KEY);
+  const pageRange = String(formDataParameter).split(",").map(Number)
+
+  let start = pageRange[0] || 1;
+  let end = pageRange[1] || maxPages;
+
+  if (!(start > 0 && start <= maxPages) || !(end > 0 && end <= maxPages) || !(start <= end)) {
+    const msg = `Page range (${start} to ${end}) is out of bounds. Values should be between 1 and ${maxPages}.`;
+    console.error(msg);
+    throw new Error(msg);
+  }
+
+  return [start, end];
+}
+
 /**
  * Gets the number of maximum requests that can be made when splitting PDF.
  * - The number of maximum requests is determined by the value of the request parameter

src/hooks/custom/utils/form.ts

@@ -66,24 +66,32 @@ export async function getOptimalSplitSize(
  *
  * @param pdf - The PDF file to extract pages from.
  * @param splitSize - The number of pages per split.
+ * @param [pageRangeStart=1] - The starting page of the range to be split (1-based index). Defaults to the first page of the document.
+ * @param [pageRangeEnd=pdf.getPageCount()] - The ending page of the range to be split (1-based index). Defaults to the last page of the document.
  * @returns A promise that resolves to an array of objects containing Blob files and
  * start and end page numbers from the original document.
  */
 export async function splitPdf(
   pdf: PDFDocument,
-  splitSize: number
+  splitSize: number,
+  pageRangeStart?: number,
+  pageRangeEnd?: number
 ): Promise<PdfSplit[]> {
   const pdfSplits: PdfSplit[] = [];
-  const pagesCount = pdf.getPages().length;
+
+  const startPage = pageRangeStart || 1;
+  const endPage = pageRangeEnd || pdf.getPageCount();
+  const pagesCount = endPage - startPage + 1
+
   const numberOfSplits = Math.ceil(pagesCount / splitSize);
 
   for (let i = 0; i < numberOfSplits; ++i) {
     const offset = i * splitSize;
-    const startPage = offset + 1;
-    // If it's the last split, take the rest of the pages
-    const endPage = Math.min(pagesCount, offset + splitSize);
-    const pdfSplit = await pdfPagesToBlob(pdf, startPage, endPage);
-    pdfSplits.push({ content: pdfSplit, startPage, endPage });
+    const splitStartPage = offset + startPage;
+    const splitEndPage = Math.min(endPage, splitStartPage + splitSize - 1);
+
+    const pdfSplit = await pdfPagesToBlob(pdf, splitStartPage, splitEndPage);
+    pdfSplits.push({ content: pdfSplit, startPage: splitStartPage, endPage: splitEndPage });
   }
 
   return pdfSplits;

src/hooks/custom/utils/pdf.ts

@@ -161,6 +161,12 @@ export class General extends ClientSDK {
         if (payload$.partition_parameters.split_pdf_page !== undefined) {
             body$.append("split_pdf_page", String(payload$.partition_parameters.split_pdf_page));
         }
+        if (payload$.partition_parameters.split_pdf_page_range !== undefined) {
+            body$.append(
+                "split_pdf_page_range",
+                String(payload$.partition_parameters.split_pdf_page_range)
+            );
+        }
         if (payload$.partition_parameters.starting_page_number !== undefined) {
             body$.append(
                 "starting_page_number",

src/sdk/general.ts

@@ -148,6 +148,10 @@ export type PartitionParameters = {
      * Should the pdf file be split at client. Ignored on backend.
      */
     splitPdfPage?: boolean | undefined;
+    /**
+     * When `split_pdf_page is set to `True`, this parameter selects a subset of the pdf to send to the API. The parameter is a list of 2 integers within the range [1, length_of_pdf]. An Error is thrown if the given range is invalid. Ignored on backend.
+     */
+    splitPdfPageRange?: Array<number> | undefined;
     /**
      * When PDF is split into pages before sending it into the API, providing this information will allow the page number to be assigned correctly. Introduced in 1.0.27.
      */
@@ -298,6 +302,7 @@ export const PartitionParameters$inboundSchema: z.ZodType<
         split_pdf_allow_failed: z.boolean().default(false),
         split_pdf_concurrency_level: z.number().int().default(5),
         split_pdf_page: z.boolean().default(true),
+        split_pdf_page_range: z.array(z.number().int()).optional(),
         starting_page_number: z.nullable(z.number().int()).optional(),
         strategy: Strategy$inboundSchema.default(Strategy.Auto),
         unique_element_ids: z.boolean().default(false),
@@ -325,6 +330,7 @@ export const PartitionParameters$inboundSchema: z.ZodType<
             split_pdf_allow_failed: "splitPdfAllowFailed",
             split_pdf_concurrency_level: "splitPdfConcurrencyLevel",
             split_pdf_page: "splitPdfPage",
+            split_pdf_page_range: "splitPdfPageRange",
             starting_page_number: "startingPageNumber",
             unique_element_ids: "uniqueElementIds",
             xml_keep_tags: "xmlKeepTags",
@@ -358,6 +364,7 @@ export type PartitionParameters$Outbound = {
     split_pdf_allow_failed: boolean;
     split_pdf_concurrency_level: number;
     split_pdf_page: boolean;
+    split_pdf_page_range?: Array<number> | undefined;
     starting_page_number?: number | null | undefined;
     strategy: string;
     unique_element_ids: boolean;
@@ -396,6 +403,7 @@ export const PartitionParameters$outboundSchema: z.ZodType<
         splitPdfAllowFailed: z.boolean().default(false),
         splitPdfConcurrencyLevel: z.number().int().default(5),
         splitPdfPage: z.boolean().default(true),
+        splitPdfPageRange: z.array(z.number().int()).optional(),
         startingPageNumber: z.nullable(z.number().int()).optional(),
         strategy: Strategy$outboundSchema.default(Strategy.Auto),
         uniqueElementIds: z.boolean().default(false),
@@ -423,6 +431,7 @@ export const PartitionParameters$outboundSchema: z.ZodType<
             splitPdfAllowFailed: "split_pdf_allow_failed",
             splitPdfConcurrencyLevel: "split_pdf_concurrency_level",
             splitPdfPage: "split_pdf_page",
+            splitPdfPageRange: "split_pdf_page_range",
             startingPageNumber: "starting_page_number",
             uniqueElementIds: "unique_element_ids",
             xmlKeepTags: "xml_keep_tags",

src/sdk/models/shared/partitionparameters.ts

@@ -4,12 +4,14 @@ import { UnstructuredClient } from "../../src";
 import { PartitionResponse } from "../../src/sdk/models/operations";
 import { PartitionParameters, Strategy } from "../../src/sdk/models/shared";
 
+const localServer = "http://localhost:8000"
+
 describe("HttpsCheckHook integration tests", () => {
     const FAKE_API_KEY = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
 
     it.each([
-        "http://localhost:8000",
-        "http://localhost:8000/general/v0/general",
+        localServer,
+      `${localServer}/general/v0/general`,
     ])("should throw error when given filename is empty", async (serverURL) => {
         const client = new UnstructuredClient({
             serverURL: serverURL,