pdfdancer-client-typescript 1.0.9 → 1.0.10

package/README.md

@@ -1,16 +1,28 @@
 # PDFDancer TypeScript Client
 
-A TypeScript client library for the PDFDancer PDF manipulation API.
+**Getting Started with PDFDancer**
 
-## Features
+PDFDancer gives you pixel-perfect programmatic control over any PDF document from TypeScript. Locate existing elements by coordinates or text, adjust them precisely, add brand-new content, and ship the modified PDF in memory or on disk. The same API is also available for Python and Java, so teams can orchestrate identical PDF workflows across stacks.
 
-- Session-based PDF manipulation with automatic session creation
-- Type-safe models and fluent builders for paragraphs and images
-- Page-scoped selectors for paragraphs, text lines, images, forms, and paths
-- Form filling helpers with field-name lookup
-- Custom font registration with on-the-fly TTF uploads
-- Detailed exceptions for validation, HTTP, and session errors
-- Works in both Node.js and browser environments
+> Need the raw API schema? The latest OpenAPI description is published at https://bucket.pdfdancer.com/api-doc/development-0.0.yml.
+
+## Highlights
+
+- Locate paragraphs, text lines, images, vector paths, form fields, and pages by index, coordinates, or text prefixes.
+- Edit existing content in place with fluent editors that apply changes safely.
+- Programmatically control third-party PDFs—modify invoices, contracts, and reports you did not author.
+- Add content with precise XY positioning using paragraph and image builders, custom fonts, and color helpers.
+- Export results as bytes for downstream processing or save directly to disk with one call.
+- Works in both Node.js and browser environments.
+
+## What Makes PDFDancer Different
+
+- **Edit any PDF**: Work with documents from customers, governments, or vendors—not just ones you generated.
+- **Pixel-perfect positioning**: Move or add elements at exact coordinates and keep the original layout intact.
+- **Surgical text replacement**: Swap or rewrite paragraphs without reflowing the rest of the page.
+- **Form manipulation**: Inspect, fill, and update AcroForm fields programmatically.
+- **Coordinate-based selection**: Select objects by position, bounding box, or text patterns.
+- **Real PDF editing**: Modify the underlying PDF structure instead of merely stamping overlays.
 
 ## Installation
 
@@ -18,36 +30,109 @@ A TypeScript client library for the PDFDancer PDF manipulation API.
 npm install pdfdancer-client-typescript
 ```
 
-## Quick Start
+Requires Node.js 18+ (or a modern browser) and a PDFDancer API token.
+
+## Quick Start — Edit an Existing PDF
 
 ```typescript
-import { PDFDancer, Color } from 'pdfdancer-client-typescript';
+import { PDFDancer, Color, StandardFonts } from 'pdfdancer-client-typescript';
 import { promises as fs } from 'node:fs';
 
 async function run() {
   const pdfBytes = await fs.readFile('input.pdf');
 
-  // Token defaults to PDFDANCER_TOKEN when omitted.
-  const pdf = await PDFDancer.open(pdfBytes, 'your-auth-token');
+  // Token defaults to PDFDANCER_TOKEN environment variable when omitted
+  const pdf = await PDFDancer.open(
+    pdfBytes,
+    'your-api-token',              // optional when PDFDANCER_TOKEN is set
+    'https://api.pdfdancer.com'    // optional base URL
+  );
+
+  // Locate and update an existing paragraph
+  const heading = (await pdf.page(0).selectParagraphsStartingWith('Executive Summary'))[0];
+  await heading.moveTo(72, 680);
 
-  const page0 = pdf.page(0); // Page indexes are zero-based
+  const result = await heading.edit()
+    .replace('Overview')
+    .apply();
 
-  await page0.newParagraph()
-    .text('Hello, PDFDancer!')
-    .font('Roboto-Regular', 14)
-    .color(new Color(255, 64, 64))
-    .lineSpacing(1.1)
-    .at(100, 200)
+  // Add a new paragraph with precise placement
+  await pdf.page(0).newParagraph()
+    .text('Generated with PDFDancer')
+    .font(StandardFonts.HELVETICA, 12)
+    .color(new Color(70, 70, 70))
+    .lineSpacing(1.4)
+    .at(72, 520)
     .apply();
 
-  const updated = await pdf.getBytes();
-  await fs.writeFile('output.pdf', updated);
+  // Persist the modified document
+  await pdf.save('output.pdf');
+  // or keep it in memory
+  const updatedBytes = await pdf.getBytes();
 }
 
 run().catch(console.error);
 ```
 
-## Authentication & Configuration
+## Create a Blank PDF
+
+```typescript
+import { PDFDancer, Color, StandardFonts } from 'pdfdancer-client-typescript';
+
+async function createNew() {
+  const pdf = await PDFDancer.new('your-api-token');
+
+  await pdf.page(0).newParagraph()
+    .text('Quarterly Summary')
+    .font(StandardFonts.TIMES_BOLD, 18)
+    .color(new Color(10, 10, 80))
+    .lineSpacing(1.2)
+    .at(72, 730)
+    .apply();
+
+  await pdf.newImage()
+    .fromFile('logo.png')
+    .at(0, 420, 710)
+    .add();
+
+  await pdf.save('summary.pdf');
+}
+
+createNew().catch(console.error);
+```
+
+## Work with Forms and Layout
+
+```typescript
+import { PDFDancer } from 'pdfdancer-client-typescript';
+
+async function workWithForms() {
+  const pdf = await PDFDancer.open('contract.pdf');
+
+  // Inspect global document structure
+  const pages = await pdf.pages();
+  console.log('Total pages:', pages.length);
+
+  // Update form fields
+  const signature = (await pdf.selectFieldsByName('signature'))[0];
+  await signature.fill('Signed by Jane Doe');
+
+  // Trim or move content at specific coordinates
+  const images = await pdf.page(1).selectImages();
+  for (const image of images) {
+    const x = image.position.boundingRect?.x;
+    if (x !== undefined && x < 100) {
+      await image.delete();
+    }
+  }
+
+  await pdf.save('contract-updated.pdf');
+}
+```
+
+Selectors return typed objects (`ParagraphObject`, `TextLineObject`, `ImageObject`, `FormFieldObject`, `PageRef`, …) with helpers such as `delete()`, `moveTo(x, y)`, or `edit()` depending on the object type.
+
+## Configuration
 
 ```typescript
 const pdf = await PDFDancer.open(
@@ -58,8 +143,9 @@ const pdf = await PDFDancer.open(
 );
 ```
 
-- Set `PDFDANCER_TOKEN` to avoid passing the token explicitly.
-- Override the API endpoint with `PDFDANCER_BASE_URL`.
+- Set `PDFDANCER_TOKEN` for authentication (preferred for local development and CI).
+- Override the API host with `PDFDANCER_BASE_URL` (e.g., sandbox environments).
+- Tune HTTP read timeouts via the `timeout` argument on `PDFDancer.open()` and `PDFDancer.new()`.
 - Page indexes start at `0` throughout the API.
 
 ## Working with Pages
@@ -112,17 +198,46 @@ await pdf.page(0).newParagraph()
 const [para] = await pdf.page(0).selectParagraphsStartingWith('The Complete');
 
 if (para) {
-  await para.edit()
+  const result = await para.edit()
     .replace('Awesomely\nObvious!')
     .font('Helvetica', 12)
     .color(new Color(0, 0, 0))
     .moveTo(280, 460)
     .apply();
+
+  // Check for warnings (e.g., embedded font modifications)
+  if (typeof result === 'object' && result.warning) {
+    console.warn('Operation warning:', result.warning);
+  }
 }
 ```
 
+**Note:** When modifying text with embedded fonts, you may receive warnings. Embedded fonts have limited character sets, and modifying text may result in unrenderable characters. Consider using standard fonts when possible.
+
 `ParagraphBuilder` also supports `.fontFile(ttfBytes, size)` to register a custom font before applying.
 
+### Text Object Status
+
+Text objects (paragraphs and lines) include status information about their font and modification state:
+
+```typescript
+const lines = await pdf.page(0).selectTextLines();
+const line = lines[0];
+
+// Check text object status
+const status = line.objectRef().status;
+if (status) {
+  console.log('Font type:', status.getFontType());        // SYSTEM, STANDARD, or EMBEDDED
+  console.log('Is modified:', status.isModified());       // true if text was changed
+  console.log('Is encodable:', status.isEncodable());     // true if text can be rendered
+
+  // Get font recommendation if available
+  const recommendation = status.getFontRecommendation();
+  console.log('Recommended font:', recommendation.getFontName());
+  console.log('Similarity score:', recommendation.getSimilarityScore());
+}
+```
+
 ## Working with Images
 
 ```typescript
@@ -164,6 +279,15 @@ await pdf.save('output.pdf'); // Node.js helper that writes the file
 
 ## Error Handling
 
+Operations raise subclasses of `PdfDancerException`:
+
+- `ValidationException`: input validation problems (missing token, invalid coordinates, etc.).
+- `FontNotFoundException`: requested font unavailable on the service.
+- `HttpClientException`: transport or server errors with detailed context.
+- `SessionException`: session creation and lifecycle failures.
+
+Wrap automated workflows in `try/catch` blocks to surface actionable errors to your users:
+
 ```typescript
 import {
   ValidationException,
@@ -221,6 +345,39 @@ try {
 - `CIRCLE` - Circular area with radius
 - `RECT` - Rectangular area with width and height
 
+### FontType
+
+- `SYSTEM` - System fonts available on the local machine
+- `STANDARD` - Standard PDF fonts (14 built-in fonts)
+- `EMBEDDED` - Fonts embedded in the PDF document
+
+### Text Modification Results
+
+When modifying text objects (paragraphs or lines), the operation returns a `CommandResult`:
+
+```typescript
+interface CommandResult {
+  commandName: string;    // Name of the operation
+  elementId: string | null;  // ID of the affected element
+  message: string | null;    // Optional status message
+  success: boolean;          // Operation success status
+  warning: string | null;    // Warning message (e.g., embedded font issues)
+}
+```
+
+### Text Status
+
+Text objects include status information via `TextStatus`:
+
+```typescript
+interface TextStatus {
+  modified: boolean;           // Whether text has been modified
+  encodable: boolean;          // Whether text is encodable with current font
+  fontType: FontType;         // Type of font being used
+  fontRecommendation: FontRecommendation;  // Recommended alternative font
+}
+```
+
 ## Development
 
 ```bash
@@ -259,6 +416,11 @@ The project includes comprehensive end-to-end tests. To run them:
 
 The e2e suite covers paragraphs, pages, text lines, images, form fields, and path manipulation scenarios.
 
+## Related SDKs
+
+- Python client: https://github.com/MenschMachine/pdfdancer-client-python
+- Java client: https://github.com/MenschMachine/pdfdancer-client-java
+
 ## License
 
-MIT
+MIT © The Famous Cat Ltd.

package/dist/__tests__/e2e/pdf-assertions.d.ts

@@ -1,18 +1,35 @@
 /**
  * PDF Assertions helper for e2e tests
  */
-import { Color, PDFDancer } from '../../index';
+import { Color, Orientation, PDFDancer } from '../../index';
 export declare class PDFAssertions {
     private pdf;
     private constructor();
     static create(sourcePdf: PDFDancer): Promise<PDFAssertions>;
-    assertTextHasColor(text: string, color: Color, page?: number): Promise<this>;
-    assertTextHasFont(text: string, fontName: string, fontSize: number, page?: number): Promise<this>;
+    private aggregateCounts;
+    assertTotalNumberOfElements(expected: number, pageIndex?: number): Promise<this>;
+    assertPageCount(expected: number): Promise<this>;
+    assertPageDimension(width: number, height: number, orientation?: Orientation, pageIndex?: number): Promise<this>;
     assertParagraphIsAt(text: string, x: number, y: number, page?: number, epsilon?: number): Promise<this>;
+    assertTextHasFont(text: string, fontName: string, fontSize: number, page?: number): Promise<this>;
     assertTextHasFontMatching(text: string, fontName: string, fontSize: number, page?: number): Promise<this>;
+    assertTextHasColor(text: string, color: Color, page?: number): Promise<this>;
     assertTextlineHasColor(text: string, color: Color, page?: number): Promise<this>;
     assertTextlineHasFont(text: string, fontName: string, fontSize: number, page?: number): Promise<this>;
     assertTextlineHasFontMatching(text: string, fontName: string, fontSize: number, page?: number): Promise<this>;
     assertTextlineIsAt(text: string, x: number, y: number, page?: number, epsilon?: number): Promise<this>;
+    assertPathIsAt(internalId: string, x: number, y: number, page?: number, epsilon?: number): Promise<this>;
+    assertNoPathAt(x: number, y: number, page?: number): Promise<this>;
+    assertNumberOfPaths(expected: number, page?: number): Promise<this>;
+    assertNumberOfImages(expected: number, page?: number): Promise<this>;
+    assertImageAt(x: number, y: number, page?: number): Promise<this>;
+    assertNoImageAt(x: number, y: number, page?: number): Promise<this>;
+    assertImageWithIdAt(internalId: string, x: number, y: number, page?: number): Promise<this>;
+    assertNumberOfFormXObjects(expected: number, page?: number): Promise<this>;
+    assertNumberOfFormFields(expected: number, page?: number): Promise<this>;
+    assertParagraphExists(text: string, page?: number): Promise<this>;
+    assertParagraphDoesNotExist(text: string, page?: number): Promise<this>;
+    assertTextlineExists(text: string, page?: number): Promise<this>;
+    assertTextlineDoesNotExist(text: string, page?: number): Promise<this>;
 }
 //# sourceMappingURL=pdf-assertions.d.ts.map

package/dist/__tests__/e2e/pdf-assertions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pdf-assertions.d.ts","sourceRoot":"","sources":["../../../src/__tests__/e2e/pdf-assertions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EAAC,KAAK,EAAE,SAAS,EAAC,MAAM,aAAa,CAAC;AAG7C,qBAAa,aAAa;IACtB,OAAO,CAAC,GAAG,CAAY;IAEvB,OAAO;WAIM,MAAM,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC;IAiB3D,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB/E,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAapG,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,EAAE,OAAO,GAAE,MAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBlH,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5G,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBnF,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxG,6BAA6B,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAWhH,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,EAAE,OAAO,GAAE,MAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAiB1H"}
+{"version":3,"file":"pdf-assertions.d.ts","sourceRoot":"","sources":["../../../src/__tests__/e2e/pdf-assertions.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/e2e/pdf-assertions.js

@@ -2,44 +2,14 @@
 /**
  * PDF Assertions helper for e2e tests
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PDFAssertions = void 0;
-const fs = __importStar(require("fs"));
-const os = __importStar(require("os"));
-const path = __importStar(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
 const index_1 = require("../../index");
 const assertions_1 = require("../assertions");
 class PDFAssertions {
@@ -52,94 +22,189 @@ class PDFAssertions {
         const token = sourcePdf._token;
         const baseUrl = sourcePdf._baseUrl;
         // Create a temporary file
-        const tempFile = path.join(os.tmpdir(), `test-${Date.now()}.pdf`);
+        const tempFile = path_1.default.join(os_1.default.tmpdir(), `test-${Date.now()}.pdf`);
         await sourcePdf.save(tempFile);
         // Reopen the PDF with the same token and baseUrl
-        const pdfData = fs.readFileSync(tempFile);
+        const pdfData = fs_1.default.readFileSync(tempFile);
         const pdf = await index_1.PDFDancer.open(new Uint8Array(pdfData), token, baseUrl);
         return new PDFAssertions(pdf);
     }
-    async assertTextHasColor(text, color, page = 0) {
-        await this.assertTextlineHasColor(text, color, page);
-        const paragraphs = await this.pdf.page(page).selectParagraphsMatching(text);
-        expect(paragraphs).toHaveLength(1);
-        const reference = paragraphs[0].ref();
-        expect(reference.text).toContain(text);
-        // Compare RGB values, alpha channel may differ
-        expect(reference.color.r).toBe(color.r);
-        expect(reference.color.g).toBe(color.g);
-        expect(reference.color.b).toBe(color.b);
+    async aggregateCounts(pageIndex) {
+        const [paragraphs, textLines, images, paths, forms, fields] = await Promise.all([
+            this.pdf.selectParagraphs(),
+            this.pdf.selectLines(),
+            this.pdf.selectImages(),
+            this.pdf.selectPaths(),
+            this.pdf.selectForms(),
+            this.pdf.selectFormFields()
+        ]);
+        const filter = (items) => {
+            if (pageIndex === undefined) {
+                return items;
+            }
+            return items.filter(item => item.position.pageIndex === pageIndex);
+        };
+        return {
+            paragraphs: filter(paragraphs).length,
+            textLines: filter(textLines).length,
+            images: filter(images).length,
+            paths: filter(paths).length,
+            forms: filter(forms).length,
+            fields: filter(fields).length
+        };
+    }
+    async assertTotalNumberOfElements(expected, pageIndex) {
+        const totals = await this.aggregateCounts(pageIndex);
+        const actual = Object.values(totals).reduce((acc, count) => acc + count, 0);
+        expect(actual).toBe(expected);
         return this;
     }
-    async assertTextHasFont(text, fontName, fontSize, page = 0) {
-        await this.assertTextlineHasFont(text, fontName, fontSize, page);
+    async assertPageCount(expected) {
+        const pages = await this.pdf.pages();
+        expect(pages.length).toBe(expected);
+        return this;
+    }
+    async assertPageDimension(width, height, orientation, pageIndex = 0) {
+        const pages = await this.pdf.pages();
+        expect(pageIndex).toBeLessThan(pages.length);
+        const page = pages[pageIndex];
+        expect(page.pageSize?.width).toBeCloseTo(width, 6);
+        expect(page.pageSize?.height).toBeCloseTo(height, 6);
+        if (orientation) {
+            expect(page.orientation).toBe(orientation);
+        }
+        return this;
+    }
+    async assertParagraphIsAt(text, x, y, page = 0, epsilon = 1e-4) {
         const paragraphs = await this.pdf.page(page).selectParagraphsMatching(`.*${text}.*`);
-        expect(paragraphs).toHaveLength(1);
-        const reference = paragraphs[0].ref();
-        expect(reference.fontName).toBe(fontName);
-        expect(reference.fontSize).toBe(fontSize);
+        expect(paragraphs.length).toBeGreaterThan(0);
+        const reference = paragraphs[0].objectRef();
+        (0, assertions_1.expectWithin)(reference.position.getX(), x, epsilon);
+        (0, assertions_1.expectWithin)(reference.position.getY(), y, epsilon);
+        const byPosition = await this.pdf.page(page).selectParagraphsAt(x, y);
+        expect(byPosition.length).toBeGreaterThan(0);
         return this;
     }
-    async assertParagraphIsAt(text, x, y, page = 0, epsilon = 0.0001) {
+    async assertTextHasFont(text, fontName, fontSize, page = 0) {
+        await this.assertTextlineHasFont(text, fontName, fontSize, page);
         const paragraphs = await this.pdf.page(page).selectParagraphsMatching(`.*${text}.*`);
-        expect(paragraphs.length).toBe(1);
-        const reference = paragraphs[0].ref();
-        const posX = reference.position.getX();
-        const posY = reference.position.getY();
-        (0, assertions_1.expectWithin)(posX, x, epsilon);
-        (0, assertions_1.expectWithin)(posY, y, epsilon);
-        const paragraphByPosition = await this.pdf.page(page).selectParagraphsAt(x, y);
-        expect(paragraphByPosition.length).toBeGreaterThan(0);
-        expect(paragraphs[0].internalId).toBe(paragraphByPosition[0].internalId);
+        expect(paragraphs.length).toBeGreaterThan(0);
+        const reference = paragraphs[0].objectRef();
+        expect(reference.fontName).toBe(fontName);
+        (0, assertions_1.expectWithin)(reference.fontSize, fontSize, 1e-6);
         return this;
     }
     async assertTextHasFontMatching(text, fontName, fontSize, page = 0) {
         await this.assertTextlineHasFontMatching(text, fontName, fontSize, page);
-        const paragraphs = await this.pdf.page(page).selectParagraphsMatching(`.*${text}.*`);
-        expect(paragraphs).toHaveLength(1);
-        const reference = paragraphs[0].ref();
-        expect(reference.fontName).toContain(fontName);
-        expect(reference.fontSize).toBe(fontSize);
+        return this;
+    }
+    async assertTextHasColor(text, color, page = 0) {
+        await this.assertTextlineHasColor(text, color, page);
         return this;
     }
     async assertTextlineHasColor(text, color, page = 0) {
         const lines = await this.pdf.page(page).selectTextLinesMatching(text);
         expect(lines.length).toBe(1);
-        const reference = lines[0].ref();
-        // Compare RGB values, alpha channel may differ
-        expect(reference.color.r).toBe(color.r);
-        expect(reference.color.g).toBe(color.g);
-        expect(reference.color.b).toBe(color.b);
+        const reference = lines[0].objectRef();
+        const refColor = reference.color;
+        expect(refColor).toEqual(color);
         expect(reference.text).toContain(text);
         return this;
     }
     async assertTextlineHasFont(text, fontName, fontSize, page = 0) {
         const lines = await this.pdf.page(page).selectTextLinesStartingWith(text);
         expect(lines.length).toBe(1);
-        const reference = lines[0].ref();
+        const reference = lines[0].objectRef();
         expect(reference.fontName).toBe(fontName);
-        expect(reference.fontSize).toBe(fontSize);
+        (0, assertions_1.expectWithin)(reference.fontSize, fontSize, 1e-6);
         return this;
     }
     async assertTextlineHasFontMatching(text, fontName, fontSize, page = 0) {
         const lines = await this.pdf.page(page).selectTextLinesStartingWith(text);
         expect(lines.length).toBe(1);
-        const reference = lines[0].ref();
-        expect(reference.fontName).toContain(fontName);
-        expect(reference.fontSize).toBe(fontSize);
+        const reference = lines[0].objectRef();
+        expect((reference.fontName ?? '').includes(fontName)).toBe(true);
+        (0, assertions_1.expectWithin)(reference.fontSize, fontSize, 1e-6);
         return this;
     }
-    async assertTextlineIsAt(text, x, y, page = 0, epsilon = 0.0001) {
+    async assertTextlineIsAt(text, x, y, page = 0, epsilon = 1e-4) {
         const lines = await this.pdf.page(page).selectTextLinesStartingWith(text);
         expect(lines.length).toBe(1);
-        const reference = lines[0].ref();
-        const posX = reference.position.getX();
-        const posY = reference.position.getY();
-        (0, assertions_1.expectWithin)(posX, x, epsilon);
-        (0, assertions_1.expectWithin)(posY, y, epsilon);
+        const reference = lines[0].objectRef();
+        (0, assertions_1.expectWithin)(reference.position.getX(), x, epsilon);
+        (0, assertions_1.expectWithin)(reference.position.getY(), y, epsilon);
         const byPosition = await this.pdf.page(page).selectTextLinesAt(x, y);
         expect(byPosition.length).toBeGreaterThan(0);
-        expect(lines[0].internalId).toBe(byPosition[0].internalId);
+        return this;
+    }
+    async assertPathIsAt(internalId, x, y, page = 0, epsilon = 1e-4) {
+        const paths = await this.pdf.page(page).selectPathsAt(x, y);
+        expect(paths.length).toBe(1);
+        const reference = paths[0];
+        expect(reference.internalId).toBe(internalId);
+        (0, assertions_1.expectWithin)(reference.position.getX(), x, epsilon);
+        (0, assertions_1.expectWithin)(reference.position.getY(), y, epsilon);
+        return this;
+    }
+    async assertNoPathAt(x, y, page = 0) {
+        const paths = await this.pdf.page(page).selectPathsAt(x, y);
+        expect(paths.length).toBe(0);
+        return this;
+    }
+    async assertNumberOfPaths(expected, page) {
+        const paths = page === undefined ? await this.pdf.selectPaths() : await this.pdf.page(page).selectPaths();
+        expect(paths.length).toBe(expected);
+        return this;
+    }
+    async assertNumberOfImages(expected, page) {
+        const images = page === undefined ? await this.pdf.selectImages() : await this.pdf.page(page).selectImages();
+        expect(images.length).toBe(expected);
+        return this;
+    }
+    async assertImageAt(x, y, page = 0) {
+        const images = await this.pdf.page(page).selectImagesAt(x, y);
+        expect(images.length).toBe(1);
+        return this;
+    }
+    async assertNoImageAt(x, y, page = 0) {
+        const images = await this.pdf.page(page).selectImagesAt(x, y);
+        expect(images.length).toBe(0);
+        return this;
+    }
+    async assertImageWithIdAt(internalId, x, y, page = 0) {
+        const images = await this.pdf.page(page).selectImagesAt(x, y);
+        expect(images.length).toBe(1);
+        expect(images[0].internalId).toBe(internalId);
+        return this;
+    }
+    async assertNumberOfFormXObjects(expected, page) {
+        const forms = page === undefined ? await this.pdf.selectForms() : await this.pdf.page(page).selectForms();
+        expect(forms.length).toBe(expected);
+        return this;
+    }
+    async assertNumberOfFormFields(expected, page) {
+        const fields = page === undefined ? await this.pdf.selectFormFields() : await this.pdf.page(page).selectFormFields();
+        expect(fields.length).toBe(expected);
+        return this;
+    }
+    async assertParagraphExists(text, page = 0) {
+        const paragraphs = await this.pdf.page(page).selectParagraphsStartingWith(text);
+        expect(paragraphs.length).toBeGreaterThan(0);
+        return this;
+    }
+    async assertParagraphDoesNotExist(text, page = 0) {
+        const paragraphs = await this.pdf.page(page).selectParagraphsStartingWith(text);
+        expect(paragraphs.length).toBe(0);
+        return this;
+    }
+    async assertTextlineExists(text, page = 0) {
+        const lines = await this.pdf.page(page).selectTextLinesStartingWith(text);
+        expect(lines.length).toBeGreaterThan(0);
+        return this;
+    }
+    async assertTextlineDoesNotExist(text, page = 0) {
+        const lines = await this.pdf.page(page).selectTextLinesStartingWith(text);
+        expect(lines.length).toBe(0);
         return this;
     }
 }