pdfdancer-client-typescript 1.0.21 → 2.0.0

package/dist/pdfdancer_v1.js

@@ -13,6 +13,7 @@ const exceptions_1 = require("./exceptions");
 const models_1 = require("./models");
 const paragraph_builder_1 = require("./paragraph-builder");
 const page_builder_1 = require("./page-builder");
+const env_loader_1 = require("./env-loader");
 const types_1 = require("./types");
 const image_builder_1 = require("./image-builder");
 const path_builder_1 = require("./path-builder");
@@ -165,35 +166,35 @@ function generateTimestamp() {
     return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}.${microseconds}Z`;
 }
 class PageClient {
-    constructor(client, pageIndex, pageRef) {
+    constructor(client, pageNumber, pageRef) {
         this.type = models_1.ObjectType.PAGE;
         this._client = client;
-        this._pageIndex = pageIndex;
-        this.internalId = pageRef?.internalId ?? `PAGE-${this._pageIndex}`;
-        this.position = pageRef?.position ?? models_1.Position.atPage(this._pageIndex);
+        this._pageNumber = pageNumber;
+        this.internalId = pageRef?.internalId ?? `PAGE-${this._pageNumber}`;
+        this.position = pageRef?.position ?? models_1.Position.atPage(this._pageNumber);
         this.pageSize = pageRef?.pageSize;
         this.orientation = pageRef?.orientation;
         // Cast to the internal interface to get access
         this._internals = this._client;
     }
     async selectPathsAt(x, y, tolerance = 0) {
-        return this._internals.toPathObjects(await this._internals.findPaths(models_1.Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
+        return this._internals.toPathObjects(await this._internals.findPaths(models_1.Position.atPageCoordinates(this._pageNumber, x, y, tolerance)));
     }
     async selectPaths() {
-        return this._internals.toPathObjects(await this._internals.findPaths(models_1.Position.atPage(this._pageIndex)));
+        return this._internals.toPathObjects(await this._internals.findPaths(models_1.Position.atPage(this._pageNumber)));
     }
     async selectImages() {
-        return this._internals.toImageObjects(await this._internals._findImages(models_1.Position.atPage(this._pageIndex)));
+        return this._internals.toImageObjects(await this._internals._findImages(models_1.Position.atPage(this._pageNumber)));
     }
     async selectImagesAt(x, y, tolerance = 0) {
-        return this._internals.toImageObjects(await this._internals._findImages(models_1.Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
+        return this._internals.toImageObjects(await this._internals._findImages(models_1.Position.atPageCoordinates(this._pageNumber, x, y, tolerance)));
     }
     async delete() {
-        return this._client.deletePage(this._pageIndex);
+        return this._client.deletePage(this._pageNumber);
     }
-    async moveTo(targetPageIndex) {
-        const pageRef = await this._client.movePage(this._pageIndex, targetPageIndex);
-        this._pageIndex = pageRef.position.pageIndex ?? targetPageIndex;
+    async moveTo(targetPageNumber) {
+        const pageRef = await this._client.movePage(this._pageNumber, targetPageNumber);
+        this._pageNumber = pageRef.position.pageNumber !== undefined ? pageRef.position.pageNumber + 1 : targetPageNumber;
         this.position = pageRef.position;
         this.internalId = pageRef.internalId;
         this.pageSize = pageRef.pageSize;
@@ -202,82 +203,82 @@ class PageClient {
     }
     // noinspection JSUnusedGlobalSymbols
     async selectForms() {
-        return this._internals.toFormXObjects(await this._internals.findFormXObjects(models_1.Position.atPage(this._pageIndex)));
+        return this._internals.toFormXObjects(await this._internals.findFormXObjects(models_1.Position.atPage(this._pageNumber)));
     }
     async selectFormsAt(x, y, tolerance = 0) {
-        return this._internals.toFormXObjects(await this._internals.findFormXObjects(models_1.Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
+        return this._internals.toFormXObjects(await this._internals.findFormXObjects(models_1.Position.atPageCoordinates(this._pageNumber, x, y, tolerance)));
     }
     async selectFormFields() {
-        return this._internals.toFormFields(await this._internals.findFormFields(models_1.Position.atPage(this._pageIndex)));
+        return this._internals.toFormFields(await this._internals.findFormFields(models_1.Position.atPage(this._pageNumber)));
     }
     async selectFormFieldsAt(x, y, tolerance = 0) {
-        return this._internals.toFormFields(await this._internals.findFormFields(models_1.Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
+        return this._internals.toFormFields(await this._internals.findFormFields(models_1.Position.atPageCoordinates(this._pageNumber, x, y, tolerance)));
     }
     // noinspection JSUnusedGlobalSymbols
     async selectFormFieldsByName(fieldName) {
-        let pos = models_1.Position.atPage(this._pageIndex);
+        let pos = models_1.Position.atPage(this._pageNumber);
         pos.name = fieldName;
         return this._internals.toFormFields(await this._internals.findFormFields(pos));
     }
     async selectParagraphs() {
-        return this._internals.toParagraphObjects(await this._internals.findParagraphs(models_1.Position.atPage(this._pageIndex)));
+        return this._internals.toParagraphObjects(await this._internals.findParagraphs(models_1.Position.atPage(this._pageNumber)));
     }
     async selectElements(types) {
-        const snapshot = await this._client.getPageSnapshot(this._pageIndex, types);
+        const snapshot = await this._client.getPageSnapshot(this._pageNumber, types);
         return snapshot.elements;
     }
     async selectParagraphsStartingWith(text) {
-        let pos = models_1.Position.atPage(this._pageIndex);
+        let pos = models_1.Position.atPage(this._pageNumber);
         pos.textStartsWith = text;
         return this._internals.toParagraphObjects(await this._internals.findParagraphs(pos));
     }
     async selectParagraphsMatching(pattern) {
-        let pos = models_1.Position.atPage(this._pageIndex);
+        let pos = models_1.Position.atPage(this._pageNumber);
         pos.textPattern = pattern;
         return this._internals.toParagraphObjects(await this._internals.findParagraphs(pos));
     }
     async selectParagraphsAt(x, y, tolerance = DEFAULT_TOLERANCE) {
-        return this._internals.toParagraphObjects(await this._internals.findParagraphs(models_1.Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
+        return this._internals.toParagraphObjects(await this._internals.findParagraphs(models_1.Position.atPageCoordinates(this._pageNumber, x, y, tolerance)));
     }
     async selectTextLinesStartingWith(text) {
-        let pos = models_1.Position.atPage(this._pageIndex);
+        let pos = models_1.Position.atPage(this._pageNumber);
         pos.textStartsWith = text;
         return this._internals.toTextLineObjects(await this._internals.findTextLines(pos));
     }
     /**
      * Creates a new ParagraphBuilder for fluent paragraph construction.
      */
-    newParagraph(pageIndex) {
-        const targetIndex = pageIndex ?? this.position.pageIndex;
+    newParagraph(pageNumber) {
+        const targetIndex = pageNumber ?? this.position.pageNumber;
         return new paragraph_builder_1.ParagraphBuilder(this._client, targetIndex);
     }
-    newImage(pageIndex) {
-        const targetIndex = pageIndex ?? this.position.pageIndex;
+    newImage(pageNumber) {
+        const targetIndex = pageNumber ?? this.position.pageNumber;
         return new image_builder_1.ImageBuilder(this._client, targetIndex);
     }
-    newPath(pageIndex) {
-        const targetIndex = pageIndex ?? this.position.pageIndex;
+    newPath(pageNumber) {
+        const targetIndex = pageNumber ?? this.position.pageNumber;
         return new path_builder_1.PathBuilder(this._client, targetIndex);
     }
     async selectTextLines() {
-        return this._internals.toTextLineObjects(await this._internals.findTextLines(models_1.Position.atPage(this._pageIndex)));
+        return this._internals.toTextLineObjects(await this._internals.findTextLines(models_1.Position.atPage(this._pageNumber)));
     }
     // noinspection JSUnusedGlobalSymbols
     async selectTextLinesMatching(pattern) {
-        let pos = models_1.Position.atPage(this._pageIndex);
+        let pos = models_1.Position.atPage(this._pageNumber);
         pos.textPattern = pattern;
         return this._internals.toTextLineObjects(await this._internals.findTextLines(pos));
     }
     // noinspection JSUnusedGlobalSymbols
     async selectTextLinesAt(x, y, tolerance = DEFAULT_TOLERANCE) {
-        return this._internals.toTextLineObjects(await this._internals.findTextLines(models_1.Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
+        return this._internals.toTextLineObjects(await this._internals.findTextLines(models_1.Position.atPageCoordinates(this._pageNumber, x, y, tolerance)));
     }
     /**
      * Gets a snapshot of this page, including all elements.
      * Optionally filter by object types.
      */
     async getSnapshot(types) {
-        return this._client.getPageSnapshot(this._pageIndex, types);
+        return this._client.getPageSnapshot(this._pageNumber, types);
     }
     // Singular convenience methods - return the first element or null
     async selectPath() {
@@ -405,7 +406,18 @@ class PDFDancer {
         this._sessionId = await this._createSession();
         return this;
     }
+    /**
+     * Opens a PDF document for manipulation.
+     *
+     * @param pdfData PDF data as Uint8Array (raw bytes) or string (filepath)
+     * @param token Authentication token (optional, can use PDFDANCER_TOKEN env var)
+     * @param baseUrl Base URL for the PDFDancer API (optional)
+     * @param timeout Request timeout in milliseconds (default: 60000)
+     * @param retryConfig Retry configuration (optional, uses defaults if not specified)
+     * @returns A PDFDancer client instance
+     */
     static async open(pdfData, token, baseUrl, timeout, retryConfig) {
+        (0, env_loader_1.loadEnv)();
         const resolvedBaseUrl = baseUrl ??
             process.env.PDFDANCER_BASE_URL ??
             "https://api.pdfdancer.com";
@@ -430,6 +442,7 @@ class PDFDancer {
      * @param retryConfig Retry configuration (optional, uses defaults if not specified)
      */
     static async new(options, token, baseUrl, timeout, retryConfig) {
+        (0, env_loader_1.loadEnv)();
         const resolvedBaseUrl = baseUrl ??
             process.env.PDFDANCER_BASE_URL ??
             "https://api.pdfdancer.com";
@@ -539,7 +552,7 @@ class PDFDancer {
             throw new exceptions_1.ValidationException("PDF data cannot be null");
         }
         try {
-            if (pdfData && pdfData.constructor === Uint8Array) {
+            if (pdfData && (pdfData.constructor === Uint8Array || Buffer.isBuffer(pdfData))) {
                 if (pdfData.length === 0) {
                     throw new exceptions_1.ValidationException("PDF data cannot be empty");
                 }
@@ -557,6 +570,7 @@ class PDFDancer {
                 return new Uint8Array(); // Placeholder, will be replaced in _createSession
             }
             else if (typeof pdfData === 'string') {
+                // TODO why is this different to `instanceof File`?
                 // Handle string as filepath
                 if (!fs_1.default.existsSync(pdfData)) {
                     throw new exceptions_1.ValidationException(`PDF file not found: ${pdfData}`);
@@ -711,7 +725,8 @@ class PDFDancer {
             'X-Session-Id': this._sessionId,
             'Content-Type': 'application/json',
             'X-Generated-At': generateTimestamp(),
-            'X-Fingerprint': fingerprint
+            'X-Fingerprint': fingerprint,
+            'X-API-VERSION': '1'
         };
         try {
             const response = await this._fetchWithRetry(url.toString(), {
@@ -771,9 +786,9 @@ class PDFDancer {
         }
         // Use snapshot-based search
         let elements;
-        if (position?.pageIndex !== undefined) {
+        if (position?.pageNumber !== undefined) {
             // Page-specific query - use page snapshot
-            const pageSnapshot = await this._getOrFetchPageSnapshot(position.pageIndex);
+            const pageSnapshot = await this._getOrFetchPageSnapshot(position.pageNumber);
             elements = pageSnapshot.elements;
         }
         else {
@@ -842,9 +857,9 @@ class PDFDancer {
     async findFormFields(position) {
         // Use snapshot-based search
         let elements;
-        if (position?.pageIndex !== undefined) {
+        if (position?.pageNumber !== undefined) {
             // Page-specific query - use page snapshot
-            const pageSnapshot = await this._getOrFetchPageSnapshot(position.pageIndex);
+            const pageSnapshot = await this._getOrFetchPageSnapshot(position.pageNumber);
             elements = pageSnapshot.elements;
         }
         else {
@@ -887,68 +902,76 @@ class PDFDancer {
      * Retrieves a reference to a specific page by its page index.
      * Now uses snapshot caching to avoid HTTP requests.
      */
-    async _getPage(pageIndex) {
-        if (pageIndex < 0) {
-            throw new exceptions_1.ValidationException(`Page index must be >= 0, got ${pageIndex}`);
+    async _getPage(pageNumber) {
+        if (pageNumber < 0) {
+            throw new exceptions_1.ValidationException(`Page index must be >= 0, got ${pageNumber}`);
         }
         // Try page snapshot cache first
-        if (this._pageSnapshotCache.has(pageIndex)) {
-            return this._pageSnapshotCache.get(pageIndex).pageRef;
+        if (this._pageSnapshotCache.has(pageNumber)) {
+            return this._pageSnapshotCache.get(pageNumber).pageRef;
         }
         // Try document snapshot cache
         if (this._documentSnapshotCache) {
-            const pageSnapshot = this._documentSnapshotCache.getPageSnapshot(pageIndex);
+            const pageSnapshot = this._documentSnapshotCache.getPageSnapshot(pageNumber);
             if (pageSnapshot) {
                 return pageSnapshot.pageRef;
             }
         }
         // Fetch document snapshot to get page (this will cache it)
         const docSnapshot = await this._getOrFetchDocumentSnapshot();
-        const pageSnapshot = docSnapshot.getPageSnapshot(pageIndex);
+        const pageSnapshot = docSnapshot.getPageSnapshot(pageNumber);
         return pageSnapshot?.pageRef ?? null;
     }
     /**
-     * Moves an existing page to a new index.
+     * Moves an existing page to a new position.
+     *
+     * @param fromPage - The source page number (1-based, page 1 is first page)
+     * @param toPage - The target page number (1-based)
+     * @returns The page reference at the new position
+     * @throws ValidationException if fromPage or toPage is less than 1
      */
-    async movePage(pageIndex, targetPageIndex) {
-        this._validatePageIndex(pageIndex, 'pageIndex');
-        this._validatePageIndex(targetPageIndex, 'targetPageIndex');
+    async movePage(fromPage, toPage) {
+        this._validatePageNumber(fromPage, 'fromPage');
+        this._validatePageNumber(toPage, 'toPage');
         // Ensure the source page exists before attempting the move
-        await this._requirePageRef(pageIndex);
-        const request = new models_1.MovePageRequest(pageIndex, targetPageIndex).toDict();
+        await this._requirePageRef(fromPage);
+        const request = new models_1.MovePageRequest(fromPage, toPage).toDict();
         const response = await this._makeRequest('PUT', '/pdf/page/move', request);
         const success = await response.json();
         if (!success) {
-            throw new exceptions_1.HttpClientException(`Failed to move page from ${pageIndex} to ${targetPageIndex}`, response);
+            throw new exceptions_1.HttpClientException(`Failed to move page from ${fromPage} to ${toPage}`, response);
         }
         // Invalidate cache after mutation
         this._invalidateCache();
         // Fetch the page again at its new position for up-to-date metadata
-        return await this._requirePageRef(targetPageIndex);
+        return await this._requirePageRef(toPage);
     }
     /**
-     * Deletes the page at the specified index.
+     * Deletes the page at the specified page number.
+     *
+     * @param pageNumber - The page number to delete (1-based, page 1 is first page)
+     * @throws ValidationException if pageNumber is less than 1
      */
-    async deletePage(pageIndex) {
-        this._validatePageIndex(pageIndex, 'pageIndex');
-        const pageRef = await this._requirePageRef(pageIndex);
+    async deletePage(pageNumber) {
+        this._validatePageNumber(pageNumber, 'pageNumber');
+        const pageRef = await this._requirePageRef(pageNumber);
         const result = await this._deletePage(pageRef);
         // Invalidate cache after mutation
         this._invalidateCache();
         return result;
     }
-    _validatePageIndex(pageIndex, fieldName) {
-        if (!Number.isInteger(pageIndex)) {
-            throw new exceptions_1.ValidationException(`${fieldName} must be an integer, got ${pageIndex}`);
+    _validatePageNumber(pageNumber, fieldName) {
+        if (!Number.isInteger(pageNumber)) {
+            throw new exceptions_1.ValidationException(`${fieldName} must be an integer, got ${pageNumber}`);
         }
-        if (pageIndex < 0) {
-            throw new exceptions_1.ValidationException(`${fieldName} must be >= 0, got ${pageIndex}`);
+        if (pageNumber < 1) {
+            throw new exceptions_1.ValidationException(`${fieldName} must be >= 1 (1-based indexing), got ${pageNumber}`);
         }
     }
-    async _requirePageRef(pageIndex) {
-        const pageRef = await this._getPage(pageIndex);
+    async _requirePageRef(pageNumber) {
+        const pageRef = await this._getPage(pageNumber);
         if (!pageRef) {
-            throw new exceptions_1.ValidationException(`Page not found at index ${pageIndex}`);
+            throw new exceptions_1.ValidationException(`Page not found at page number ${pageNumber}`);
         }
         return pageRef;
     }
@@ -984,17 +1007,18 @@ class PDFDancer {
      * Gets a snapshot of a specific page.
      * Returns the page reference and all elements on that page.
      *
-     * @param pageIndex Zero-based page index
-     * @param types Optional array of ObjectType to filter elements by type
+     * @param pageNumber - The page number to retrieve (1-based, page 1 is first page)
+     * @param types - Optional array of ObjectType to filter elements by type
      * @returns PageSnapshot containing page information and elements
+     * @throws ValidationException if pageNumber is less than 1
      */
-    async getPageSnapshot(pageIndex, types) {
-        this._validatePageIndex(pageIndex, 'pageIndex');
+    async getPageSnapshot(pageNumber, types) {
+        this._validatePageNumber(pageNumber, 'pageNumber');
         const params = {};
         if (types && types.length > 0) {
             params.types = types.join(',');
         }
-        const response = await this._makeRequest('GET', `/pdf/page/${pageIndex}/snapshot`, undefined, params);
+        const response = await this._makeRequest('GET', `/pdf/page/${pageNumber}/snapshot`, undefined, params);
         const data = await response.json();
         return this._parsePageSnapshot(data);
     }
@@ -1002,24 +1026,27 @@ class PDFDancer {
     /**
      * Gets a page snapshot from cache or fetches it.
      * First checks page cache, then document cache, then fetches from server.
+     *
+     * @param pageNumber - 1-based page number
      */
-    async _getOrFetchPageSnapshot(pageIndex) {
+    async _getOrFetchPageSnapshot(pageNumber) {
         // Check page cache first
-        if (this._pageSnapshotCache.has(pageIndex)) {
-            return this._pageSnapshotCache.get(pageIndex);
+        if (this._pageSnapshotCache.has(pageNumber)) {
+            return this._pageSnapshotCache.get(pageNumber);
         }
         // Check if we have document snapshot and can extract the page
+        // Convert 1-based page number to 0-based index for array access
         if (this._documentSnapshotCache) {
-            const pageSnapshot = this._documentSnapshotCache.getPageSnapshot(pageIndex);
+            const pageSnapshot = this._documentSnapshotCache.getPageSnapshot(pageNumber);
             if (pageSnapshot) {
                 // Cache it for future use
-                this._pageSnapshotCache.set(pageIndex, pageSnapshot);
+                this._pageSnapshotCache.set(pageNumber, pageSnapshot);
                 return pageSnapshot;
             }
         }
         // Fetch page snapshot from server
-        const pageSnapshot = await this.getPageSnapshot(pageIndex);
-        this._pageSnapshotCache.set(pageIndex, pageSnapshot);
+        const pageSnapshot = await this.getPageSnapshot(pageNumber);
+        this._pageSnapshotCache.set(pageNumber, pageSnapshot);
         return pageSnapshot;
     }
     /**
@@ -1050,8 +1077,8 @@ class PDFDancer {
         }
         let filtered = elements;
         // Filter by page index
-        if (position.pageIndex !== undefined) {
-            filtered = filtered.filter(el => el.position.pageIndex === position.pageIndex);
+        if (position.pageNumber !== undefined) {
+            filtered = filtered.filter(el => el.position.pageNumber === position.pageNumber);
         }
         // Filter by coordinates (point containment with tolerance)
         if (position.boundingRect && position.shape === models_1.ShapeType.POINT) {
@@ -1193,11 +1220,11 @@ class PDFDancer {
         if (!paragraph.getPosition()) {
             throw new exceptions_1.ValidationException("Paragraph position is null, you need to specify a position for the new paragraph, using .at(x,y)");
         }
-        if (paragraph.getPosition().pageIndex === undefined) {
-            throw new exceptions_1.ValidationException("Paragraph position page index is null");
+        if (paragraph.getPosition().pageNumber === undefined) {
+            throw new exceptions_1.ValidationException("Paragraph position page number is null");
         }
-        if (paragraph.getPosition().pageIndex < 0) {
-            throw new exceptions_1.ValidationException("Paragraph position page index is less than 0");
+        if (paragraph.getPosition().pageNumber < 1) {
+            throw new exceptions_1.ValidationException("Paragraph position page number is less than 1");
         }
         return this._addObject(paragraph);
     }
@@ -1211,11 +1238,11 @@ class PDFDancer {
         if (!path.getPosition()) {
             throw new exceptions_1.ValidationException("Path position is null, you need to specify a position for the new path, using .at(x,y)");
         }
-        if (path.getPosition().pageIndex === undefined) {
-            throw new exceptions_1.ValidationException("Path position page index is null");
+        if (path.getPosition().pageNumber === undefined) {
+            throw new exceptions_1.ValidationException("Path position page number is null");
         }
-        if (path.getPosition().pageIndex < 0) {
-            throw new exceptions_1.ValidationException("Path position page index is less than 0");
+        if (path.getPosition().pageNumber < 1) {
+            throw new exceptions_1.ValidationException("Path position page number is less than 1");
         }
         return await this._addObject(path);
     }
@@ -1530,7 +1557,7 @@ class PDFDancer {
      */
     _parsePosition(posData) {
         const position = new models_1.Position();
-        position.pageIndex = posData.pageIndex;
+        position.pageNumber = posData.pageNumber;
         position.textStartsWith = posData.textStartsWith;
         if (posData.shape) {
             position.shape = models_1.ShapeType[posData.shape];
@@ -1584,9 +1611,9 @@ class PDFDancer {
         if (Array.isArray(data.elements)) {
             for (const elementData of data.elements) {
                 const element = this._parseObjectRef(elementData);
-                // If the element's position doesn't have a pageIndex, inherit it from the page
-                if (element.position && element.position.pageIndex === undefined) {
-                    element.position.pageIndex = pageRef.position.pageIndex;
+                // If the element's position doesn't have a pageNumber, inherit it from the page
+                if (element.position && element.position.pageNumber === undefined) {
+                    element.position.pageNumber = pageRef.position.pageNumber;
                 }
                 elements.push(element);
             }
@@ -1603,27 +1630,35 @@ class PDFDancer {
     toImageObjects(objectRefs) {
         return objectRefs.map(ref => types_1.ImageObject.fromRef(this, ref));
     }
-    newImage(pageIndex) {
-        return new image_builder_1.ImageBuilder(this, pageIndex);
+    newImage(pageNumber) {
+        return new image_builder_1.ImageBuilder(this, pageNumber);
     }
-    newParagraph(pageIndex) {
-        return new paragraph_builder_1.ParagraphBuilder(this, pageIndex);
+    newParagraph(pageNumber) {
+        return new paragraph_builder_1.ParagraphBuilder(this, pageNumber);
     }
-    newPath(pageIndex) {
-        return new path_builder_1.PathBuilder(this, pageIndex);
+    newPath(pageNumber) {
+        return new path_builder_1.PathBuilder(this, pageNumber);
     }
     newPage() {
         return new page_builder_1.PageBuilder(this);
     }
-    page(pageIndex) {
-        if (pageIndex < 0) {
-            throw new exceptions_1.ValidationException(`Page index must be >= 0, got ${pageIndex}`);
+    /**
+     * Creates a client for working with a specific page.
+     *
+     * @param pageNumber - The page number (1-based, page 1 is first page)
+     * @returns A PageClient for the specified page
+     * @throws ValidationException if pageNumber is less than 1
+     */
+    page(pageNumber) {
+        if (pageNumber < 1) {
+            throw new exceptions_1.ValidationException(`Page number must be >= 1 (1-based indexing), got ${pageNumber}`);
         }
-        return new PageClient(this, pageIndex);
+        return new PageClient(this, pageNumber);
     }
     async pages() {
         const pageRefs = await this.getPages();
-        return pageRefs.map((pageRef, pageIndex) => new PageClient(this, pageIndex, pageRef));
+        // Page numbers are 1-based
+        return pageRefs.map((pageRef, index) => new PageClient(this, index + 1, pageRef));
     }
     toFormFields(objectRefs) {
         return objectRefs.map(ref => types_1.FormFieldObject.fromRef(this, ref));