pdfdancer-client-typescript 1.0.14 → 1.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdfdancer-client-typescript",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "description": "A TypeScript client library for the PDFDancer PDF manipulation API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,7 +10,7 @@
     "test:unit": "jest --selectProjects unit",
     "test:e2e": "jest --selectProjects e2e",
     "test:watch": "jest --watch",
-    "lint": "eslint src/**/*.ts",
+    "lint": "eslint src/",
     "prepublishOnly": "npm run build",
     "release": "node scripts/release.js",
     "release:skip-tests": "node scripts/release.js --skip-tests",

package/src/__tests__/e2e/acroform.test.ts

@@ -105,4 +105,62 @@ describe('AcroForm Fields E2E Tests (v2 API)', () => {
         const assertions = await PDFAssertions.create(pdf);
         await assertions.assertNumberOfFormFields(10);
     });
+
+    // Tests for singular select methods
+    test('selectFormField returns first field or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('mixed-form-types.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        // Test with results
+        const field = await pdf.page(0).selectFormField();
+        expect(field).not.toBeNull();
+        expect(field!.internalId).toBe('FORM_FIELD_000001');
+
+        // Test with PDFDancer class
+        const fieldFromPdf = await pdf.selectFormField();
+        expect(fieldFromPdf).not.toBeNull();
+        expect(fieldFromPdf!.internalId).toBe('FORM_FIELD_000001');
+    });
+
+    test('selectFormFieldByName returns first field by name or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('mixed-form-types.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        const field = await pdf.page(0).selectFormFieldByName('firstName');
+        expect(field).not.toBeNull();
+        expect(field!.name).toBe('firstName');
+        expect(field!.internalId).toBe('FORM_FIELD_000001');
+
+        // Test with no match
+        const noMatch = await pdf.page(0).selectFormFieldByName('nonExistent');
+        expect(noMatch).toBeNull();
+    });
+
+    test('selectFieldByName returns first field by name or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('mixed-form-types.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        const field = await pdf.selectFieldByName('firstName');
+        expect(field).not.toBeNull();
+        expect(field!.name).toBe('firstName');
+        expect(field!.internalId).toBe('FORM_FIELD_000001');
+
+        // Test with no match
+        const noMatch = await pdf.selectFieldByName('nonExistent');
+        expect(noMatch).toBeNull();
+    });
+
+    test('selectFormFieldAt returns first field at position or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('mixed-form-types.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        const field = await pdf.page(0).selectFormFieldAt(280, 455, 1);
+        expect(field).not.toBeNull();
+        expect(field!.type).toBe('RADIO_BUTTON');
+        expect(field!.internalId).toBe('FORM_FIELD_000008');
+
+        // Test with no match
+        const noMatch = await pdf.page(0).selectFormFieldAt(1000, 1000, 1);
+        expect(noMatch).toBeNull();
+    });
 });

package/src/__tests__/e2e/form_x_object.test.ts

@@ -55,4 +55,33 @@ describe('Form E2E Tests (v2 API)', () => {
         const assertions = await PDFAssertions.create(pdf);
         await assertions.assertNumberOfFormXObjects(0);
     });
+
+    // Tests for singular select methods
+    test('selectForm returns first form or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('form-xobject-example.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        // Test with results
+        const form = await pdf.page(0).selectForm();
+        expect(form).not.toBeNull();
+        expect(form!.internalId).toBe('FORM_000001');
+
+        // Test with PDFDancer class
+        const formFromPdf = await pdf.selectForm();
+        expect(formFromPdf).not.toBeNull();
+        expect(formFromPdf!.internalId).toBe('FORM_000001');
+    });
+
+    test('selectFormAt returns first form at position or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('form-xobject-example.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        const form = await pdf.page(0).selectFormAt(321, 601, 1);
+        expect(form).not.toBeNull();
+        expect(form!.internalId).toBe('FORM_000005');
+
+        // Test with no match
+        const noMatch = await pdf.page(0).selectFormAt(0, 0);
+        expect(noMatch).toBeNull();
+    });
 });

package/src/__tests__/e2e/image.test.ts

@@ -110,4 +110,38 @@ describe('Image E2E Tests (v2 API)', () => {
         await assertions.assertImageAt(50.1, 98.0, 6);
         await assertions.assertNumberOfImages(1, 6);
     });
+
+    // Tests for singular select methods
+    test('selectImage returns first image or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        // Test with results - page 11 has images
+        const image = await pdf.page(11).selectImage();
+        expect(image).not.toBeNull();
+        expect(image!.internalId).toBe('IMAGE_000003');
+
+        // Test with PDFDancer class
+        const imageFromPdf = await pdf.selectImage();
+        expect(imageFromPdf).not.toBeNull();
+        expect(imageFromPdf!.internalId).toBe('IMAGE_000001');
+
+        // Test page 0 also has images (2 images)
+        const imageOnPage0 = await pdf.page(0).selectImage();
+        expect(imageOnPage0).not.toBeNull();
+        expect(imageOnPage0!.internalId).toBe('IMAGE_000001');
+    });
+
+    test('selectImageAt returns first image at position or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        const image = await pdf.page(11).selectImageAt(54, 300, 1);
+        expect(image).not.toBeNull();
+        expect(image!.internalId).toBe('IMAGE_000003');
+
+        // Test with no match
+        const noMatch = await pdf.page(11).selectImageAt(0, 0);
+        expect(noMatch).toBeNull();
+    });
 });

package/src/__tests__/e2e/line-showcase.test.ts

@@ -15,7 +15,6 @@ describe('Text Line E2E Tests (Showcase)', () => {
                 const status = line.objectRef().status;
                 expect(status).toBeDefined();
                 expect(status?.isModified()).toBe(false);
-                expect(status?.isEncodable()).toBe(true);
             }
         }
     });
@@ -33,14 +32,12 @@ describe('Text Line E2E Tests (Showcase)', () => {
         expect(Math.abs(first.position.getX()! - 180)).toBeLessThanOrEqual(1);
         expect(Math.abs(first.position.getY()! - 750)).toBeLessThanOrEqual(1);
         expect(first.objectRef().status?.isModified()).toBe(false);
-        expect(first.objectRef().status?.isEncodable()).toBe(true);
 
         const last = lines[lines.length - 1];
         expect(last.internalId).toBe('TEXTLINE_000036');
         expect(Math.abs(last.position.getX()! - 69.3)).toBeLessThanOrEqual(2);
         expect(Math.abs(last.position.getY()! - 45)).toBeLessThanOrEqual(2);
         expect(last.objectRef().status?.isModified()).toBe(false);
-        expect(last.objectRef().status?.isEncodable()).toBe(true);
     });
 
     test('find lines by text', async () => {
@@ -84,7 +81,6 @@ describe('Text Line E2E Tests (Showcase)', () => {
         const moved = (await pdf.page(0).selectTextLinesAt(newX, newY, 1))[0];
         const status = moved.objectRef().status;
         expect(status).toBeDefined();
-        expect(status?.isEncodable()).toBe(true);
         expect(status?.getFontType()).toBe(FontType.EMBEDDED);
         expect(status?.isModified()).toBe(false);
 
@@ -106,7 +102,6 @@ describe('Text Line E2E Tests (Showcase)', () => {
         expect(lines.length).toBeGreaterThan(0);
         const status = lines[0].objectRef().status;
         expect(status).toBeDefined();
-        expect(status?.isEncodable()).toBe(true);
         expect(status?.getFontType()).toBe(FontType.EMBEDDED);
         expect(status?.isModified()).toBe(true);
 

package/src/__tests__/e2e/line.test.ts

@@ -24,7 +24,6 @@ describe('Text Line E2E Tests (v2 API)', () => {
         expectWithin(first.position.boundingRect?.y, 706, 1);
         expect(first.objectRef().status).toBeDefined();
         expect(first.objectRef().status?.isModified()).toBe(false);
-        expect(first.objectRef().status?.isEncodable()).toBe(true);
 
         const last = lines[lines.length - 1];
         expect(last.internalId).toBe('TEXTLINE_000340');
@@ -33,7 +32,6 @@ describe('Text Line E2E Tests (v2 API)', () => {
         expectWithin(last.position.boundingRect?.y, 35, 1);
         expect(last.objectRef().status).toBeDefined();
         expect(last.objectRef().status?.isModified()).toBe(false);
-        expect(last.objectRef().status?.isEncodable()).toBe(true);
     });
 
     test('find lines on page', async () => {
@@ -107,17 +105,15 @@ describe('Text Line E2E Tests (v2 API)', () => {
         const [line] = await pdf.page(0).selectTextLinesStartingWith('The Complete');
         const result = await line.edit().text(' replaced ').apply();
 
-        // This should issue a warning about an embedded font modification
-        expect(result.warning).toBeDefined();
-        expect(result.warning).toContain('You are using an embedded font and modified the text.');
+        expect(result.warning).toBeDefined();        // This should issue a warning about an embedded font modification
+        expect(result.warning).toContain('Text is not encodable with your current font, we are using \'Poppins-Bold\' as a fallback font instead.');
 
         const stillOld = await pdf.page(0).selectParagraphsStartingWith('The Complete');
         expect(stillOld).toHaveLength(0);
 
-        const lines = await pdf.page(0).selectTextLinesStartingWith(' replaced ');
+        const lines = await pdf.page(0).selectTextLinesMatching('.*replaced.*');
         expect(lines.length).toBeGreaterThan(0);
         expect(lines[0].objectRef().status).toBeDefined();
-        expect(lines[0].objectRef().status?.isEncodable()).toBe(true);
         expect(lines[0].objectRef().status?.getFontType()).toBe(FontType.EMBEDDED);
         expect(lines[0].objectRef().status?.isModified()).toBe(true);
 
@@ -130,4 +126,64 @@ describe('Text Line E2E Tests (v2 API)', () => {
         const assertions = await PDFAssertions.create(pdf);
         await assertions.assertTextlineExists(' replaced ');
     });
+
+    // Tests for singular select methods
+    test('selectTextLine returns first line or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        // Test with results
+        const line = await pdf.page(1).selectTextLine();
+        expect(line).not.toBeNull();
+        expect(line!.internalId).toBe('TEXTLINE_000005');
+
+        // Test with PDFDancer class
+        const lineFromPdf = await pdf.selectTextLine();
+        expect(lineFromPdf).not.toBeNull();
+        expect(lineFromPdf!.internalId).toBe('TEXTLINE_000001');
+
+        // Test alias selectLine
+        const lineAlias = await pdf.selectLine();
+        expect(lineAlias).not.toBeNull();
+        expect(lineAlias!.internalId).toBe('TEXTLINE_000001');
+    });
+
+    test('selectTextLineStartingWith returns first match or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        const line = await pdf.page(0).selectTextLineStartingWith('the complete');
+        expect(line).not.toBeNull();
+        expect(line!.internalId).toBe('TEXTLINE_000002');
+
+        // Test with no match
+        const noMatch = await pdf.page(0).selectTextLineStartingWith('NoMatch');
+        expect(noMatch).toBeNull();
+    });
+
+    test('selectTextLineMatching returns first match or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        const line = await pdf.page(0).selectTextLineMatching('.*Complete.*');
+        expect(line).not.toBeNull();
+        expect(line!.internalId).toBe('TEXTLINE_000002');
+
+        // Test with no match
+        const noMatch = await pdf.page(0).selectTextLineMatching('.*NOT FOUND.*');
+        expect(noMatch).toBeNull();
+    });
+
+    test('selectTextLineAt returns first line at position or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        const line = await pdf.page(0).selectTextLineAt(54, 606, 10);
+        expect(line).not.toBeNull();
+        expect(line!.internalId).toBe('TEXTLINE_000002');
+
+        // Test with no match
+        const noMatch = await pdf.page(0).selectTextLineAt(1000, 1000, 1);
+        expect(noMatch).toBeNull();
+    });
 });

package/src/__tests__/e2e/paragraph-showcase.test.ts

@@ -28,7 +28,6 @@ describe('Paragraph E2E Tests (Showcase)', () => {
 
         const status = last.objectRef().status;
         expect(status).toBeDefined();
-        expect(status?.isEncodable()).toBe(true);
         expect(status?.getFontType()).toBe(FontType.EMBEDDED);
         expect(status?.isModified()).toBe(false);
     });
@@ -137,7 +136,6 @@ describe('Paragraph E2E Tests (Showcase)', () => {
         const [moved] = await pdf.page(0).selectParagraphsStartingWith(SAMPLE_PARAGRAPH);
         const status = moved.objectRef().status;
         expect(status).toBeDefined();
-        expect(status?.isEncodable()).toBe(true);
         expect(status?.getFontType()).toBe(FontType.EMBEDDED);
         expect(status?.isModified()).toBe(false);
 
@@ -181,7 +179,6 @@ describe('Paragraph E2E Tests (Showcase)', () => {
         const moved = (await pdf.page(0).selectParagraphsAt(300.1, 500))[0];
         const status = moved.objectRef().status;
         expect(status).toBeDefined();
-        expect(status?.isEncodable()).toBe(true);
         expect(status?.getFontType()).toBe(FontType.STANDARD);
         expect(status?.isModified()).toBe(true);
 
@@ -242,7 +239,6 @@ describe('Paragraph E2E Tests (Showcase)', () => {
         const [updated] = await pdf.page(0).selectParagraphsStartingWith(SAMPLE_PARAGRAPH);
         const status = updated.objectRef().status;
         expect(status).toBeDefined();
-        expect(status?.isEncodable()).toBe(true);
         expect(status?.getFontType()).toBe(FontType.EMBEDDED);
         expect(status?.isModified()).toBe(false);
 
@@ -261,7 +257,6 @@ describe('Paragraph E2E Tests (Showcase)', () => {
         const [updated] = await pdf.page(0).selectParagraphsStartingWith('lorem');
         const status = updated.objectRef().status;
         expect(status).toBeDefined();
-        expect(status?.isEncodable()).toBe(true);
         expect(status?.getFontType()).toBe(FontType.EMBEDDED);
         expect(status?.isModified()).toBe(true);
 
@@ -282,7 +277,6 @@ describe('Paragraph E2E Tests (Showcase)', () => {
         const [updated] = await pdf.page(0).selectParagraphsStartingWith(SAMPLE_PARAGRAPH);
         const status = updated.objectRef().status;
         expect(status).toBeDefined();
-        expect(status?.isEncodable()).toBe(true);
         expect(status?.getFontType()).toBe(FontType.STANDARD);
         expect(status?.isModified()).toBe(true);
 
@@ -300,7 +294,6 @@ describe('Paragraph E2E Tests (Showcase)', () => {
         const [updated] = await pdf.page(0).selectParagraphsStartingWith(SAMPLE_PARAGRAPH);
         const status = updated.objectRef().status;
         expect(status).toBeDefined();
-        expect(status?.isEncodable()).toBe(true);
         expect(status?.getFontType()).toBe(FontType.EMBEDDED);
         expect(status?.isModified()).toBe(false);
 
@@ -517,7 +510,6 @@ describe('Paragraph E2E Tests (Showcase)', () => {
 
         const status = moved[0].objectRef().status;
         expect(status).toBeDefined();
-        expect(status?.isEncodable()).toBe(true);
         expect(status?.getFontType()).toBe(FontType.EMBEDDED);
         expect(status?.isModified()).toBe(false);
     });

package/src/__tests__/e2e/paragraph.test.ts

@@ -32,7 +32,6 @@ describe('Paragraph E2E Tests (v2 API)', () => {
         expectWithin(last.position.boundingRect?.y, 496, 2);
 
         expect(last.objectRef().status).toBeDefined();
-        expect(last.objectRef().status?.isEncodable()).toBe(true);
         expect(last.objectRef().status?.getFontType()).toBe(FontType.EMBEDDED);
         expect(last.objectRef().status?.isModified()).toBe(false);
     });
@@ -112,7 +111,6 @@ describe('Paragraph E2E Tests (v2 API)', () => {
         expect(movedParas.length).toBeGreaterThan(0);
         const moved = movedParas[0];
         expect(moved.objectRef().status).toBeDefined();
-        expect(moved.objectRef().status?.isEncodable()).toBe(true);
         expect(moved.objectRef().status?.getFontType()).toBe(FontType.STANDARD);
         expect(moved.objectRef().status?.isModified()).toBe(true);
 
@@ -134,7 +132,7 @@ describe('Paragraph E2E Tests (v2 API)', () => {
         // This should issue a warning about an embedded font modification
         expect(typeof result).toBe('object');
         expect((result as any).warning).toBeDefined();
-        expect((result as any).warning).toContain('You are using an embedded font and modified the text.');
+        expect((result as any).warning).toBe("Text is not encodable with your current font, we are using 'Poppins-Bold' as a fallback font instead.");
 
         await assertNewParagraphExists(pdf);
 
@@ -142,13 +140,12 @@ describe('Paragraph E2E Tests (v2 API)', () => {
         expect(modifiedParas.length).toBeGreaterThan(0);
         const modified = modifiedParas[0];
         expect(modified.objectRef().status).toBeDefined();
-        expect(modified.objectRef().status?.isEncodable()).toBe(true);
         expect(modified.objectRef().status?.getFontType()).toBe(FontType.EMBEDDED);
         expect(modified.objectRef().status?.isModified()).toBe(true);
 
         const assertions = await PDFAssertions.create(pdf);
-        await assertions.assertTextlineHasFont('Awesomely', 'IXKSWR+Poppins-Bold', 45, 0);
-        await assertions.assertTextlineHasFont('Obvious!', 'IXKSWR+Poppins-Bold', 45, 0);
+        await assertions.assertTextlineHasFontMatching('Awesomely', 'Poppins-Bold', 45, 0);
+        await assertions.assertTextlineHasFontMatching('Obvious!', 'Poppins-Bold', 45, 0);
         await assertions.assertTextlineHasColor('Awesomely', new Color(255, 255, 255), 0);
         await assertions.assertTextlineHasColor('Obvious!', new Color(255, 255, 255), 0);
     });
@@ -543,8 +540,8 @@ describe('Paragraph E2E Tests (v2 API)', () => {
         await para.edit().replace('Awesomely\nObvious!').apply();
 
         const assertions = await PDFAssertions.create(pdf);
-        await assertions.assertTextlineHasFont('Awesomely', 'IXKSWR+Poppins-Bold', 45, 0);
-        await assertions.assertTextlineHasFont('Obvious!', 'IXKSWR+Poppins-Bold', 45, 0);
+        await assertions.assertTextlineHasFontMatching('Awesomely', 'Poppins-Bold', 45, 0);
+        await assertions.assertTextlineHasFontMatching('Obvious!', 'Poppins-Bold', 45, 0);
         await assertions.assertTextlineHasColor('Awesomely', new Color(255, 255, 255), 0);
         await assertions.assertTextlineHasColor('Obvious!', new Color(255, 255, 255), 0);
     });
@@ -624,4 +621,63 @@ describe('Paragraph E2E Tests (v2 API)', () => {
         expect(StandardFonts.ZAPF_DINGBATS).toBe('ZapfDingbats');
     });
 
+    // Tests for singular select methods
+    test('selectParagraph returns first paragraph or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        // Test with results
+        const para = await pdf.page(0).selectParagraph();
+        expect(para).not.toBeNull();
+        expect(para!.internalId).toBe('PARAGRAPH_000003');
+
+        // Test with PDFDancer class
+        const paraFromPdf = await pdf.selectParagraph();
+        expect(paraFromPdf).not.toBeNull();
+        expect(paraFromPdf!.internalId).toBe('PARAGRAPH_000003');
+    });
+
+    test('selectParagraphStartingWith returns first match or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        const para = await pdf.page(0).selectParagraphStartingWith('The Complete');
+        expect(para).not.toBeNull();
+        expect(para!.internalId).toBe('PARAGRAPH_000004');
+
+        // Test with no match
+        const noMatch = await pdf.page(0).selectParagraphStartingWith('NoMatch');
+        expect(noMatch).toBeNull();
+    });
+
+    test('selectParagraphMatching returns first match or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        const para = await pdf.page(0).selectParagraphMatching('.*Complete.*');
+        expect(para).not.toBeNull();
+        expect(para!.internalId).toBe('PARAGRAPH_000004');
+
+        // Test with PDFDancer class
+        const paraFromPdf = await pdf.selectParagraphMatching('.*Complete.*');
+        expect(paraFromPdf).not.toBeNull();
+
+        // Test with no match
+        const noMatch = await pdf.page(0).selectParagraphMatching('.*NOT FOUND.*');
+        expect(noMatch).toBeNull();
+    });
+
+    test('selectParagraphAt returns first paragraph at position or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        const para = await pdf.page(0).selectParagraphAt(54, 496, 10);
+        expect(para).not.toBeNull();
+        expect(para!.internalId).toBe('PARAGRAPH_000004');
+
+        // Test with no match
+        const noMatch = await pdf.page(0).selectParagraphAt(1000, 1000, 1);
+        expect(noMatch).toBeNull();
+    });
+
 });

package/src/__tests__/e2e/path.test.ts

@@ -76,4 +76,33 @@ describe('Path E2E Tests (New API)', () => {
         const assertions = await PDFAssertions.create(pdf);
         await assertions.assertPathIsAt('PATH_000001', 50.1, 100);
     });
+
+    // Tests for singular select methods
+    test('selectPath returns first path or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('basic-paths.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        // Test with PDFDancer class (document-level)
+        const pathFromPdf = await pdf.selectPath();
+        expect(pathFromPdf).not.toBeNull();
+        expect(pathFromPdf!.internalId).toBe('PATH_000001');
+
+        // Test with page-level using position since paths may require coordinates
+        const pathOnPage = await pdf.page(0).selectPathAt(80, 720);
+        expect(pathOnPage).not.toBeNull();
+        expect(pathOnPage!.internalId).toBe('PATH_000001');
+    });
+
+    test('selectPathAt returns first path at position or null', async () => {
+        const [baseUrl, token, pdfData] = await requireEnvAndFixture('basic-paths.pdf');
+        const pdf = await PDFDancer.open(pdfData, token, baseUrl);
+
+        const path = await pdf.page(0).selectPathAt(80, 720);
+        expect(path).not.toBeNull();
+        expect(path!.internalId).toBe('PATH_000001');
+
+        // Test with no match
+        const noMatch = await pdf.page(0).selectPathAt(1000, 1000);
+        expect(noMatch).toBeNull();
+    });
 });

package/src/__tests__/e2e/test-helpers.ts

@@ -4,12 +4,13 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import os from "os";
 
 /**
  * Get the base URL from environment variable or default
  */
 export function getBaseUrl(): string {
-    return process.env.PDFDANCER_BASE_URL || 'http://localhost:8080';
+    return (process.env.PDFDANCER_BASE_URL || 'http://localhost:8080').trim();
 }
 
 /**
@@ -102,7 +103,12 @@ export async function requireEnvAndFixture(pdfFilename: string): Promise<[string
  * Helper to open temporary file path (for Node.js environment)
  */
 export function createTempPath(filename: string): string {
-    const tmpDir = process.env.TMPDIR || '/tmp';
+    const tmpDir =
+        process.env.TMPDIR ||
+        process.env.TEMP ||
+        process.env.TMP ||
+        os.tmpdir(); // reliable built-in fallback
+
     return path.join(tmpDir, filename);
 }
 

package/src/__tests__/e2e/token_from_env.test.ts

@@ -3,7 +3,6 @@ import {PDFDancer} from "../../pdfdancer_v1";
 import {HttpClientException, ValidationException} from "../../exceptions";
 
 describe('Env Token E2E Tests', () => {
-    const MISSING_TOKEN_MESSAGE = "Missing PDFDancer API token. Pass a token via the `token` argument or set the PDFDANCER_TOKEN environment variable.";
     let originalToken: string | undefined;
     let originalBaseUrl: string | undefined;
     let baseUrl: string;