pdfdancer-client-typescript 1.0.4 → 1.0.6

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

@@ -0,0 +1,35 @@
+import {requireEnvAndFixture} from "./test-helpers";
+import {PDFDancer} from "../../pdfdancer_v1";
+import {ObjectType} from "../../models";
+
+describe('Env Token E2E Tests', () => {
+
+    test('get pages with token from env', async () => {
+        process.env.PDFDANCER_TOKEN = "42";
+        process.env.PDFDANCER_BASE_URL = "http://localhost:8080";
+        const [, , pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+        const client = await PDFDancer.open(pdfData);
+        const pages = await client.pages();
+        expect(pages).toBeDefined();
+        expect(pages[0].type).toBe(ObjectType.PAGE);
+        expect(pages).toHaveLength(12);
+    });
+
+    test('fail without token', async () => {
+        delete process.env.PDFDANCER_TOKEN;
+        delete process.env.PDFDANCER_BASE_URL;
+        const [, , pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+        await expect(PDFDancer.open(pdfData))
+            .rejects
+            .toThrow("Missing PDFDancer token");
+    });
+
+    test('fail with wrong token', async () => {
+        process.env.PDFDANCER_TOKEN = "43";
+        process.env.PDFDANCER_BASE_URL = "http://localhost:8080";
+        const [, , pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+        await expect(PDFDancer.open(pdfData))
+            .rejects
+            .toThrow("Failed to create session: Unauthorized");
+    });
+});

package/src/image-builder.ts

@@ -0,0 +1,52 @@
+import {PDFDancer} from "./pdfdancer_v1";
+import fs from "fs";
+import {Image, Position} from "./models";
+
+// 👇 Internal view of PDFDancer methods, not exported
+interface PDFDancerInternals {
+    addImage(image: Image, position: Position): Promise<boolean>;
+}
+
+export class ImageBuilder {
+    private _client: PDFDancer;
+    private _imageData: Uint8Array<ArrayBuffer> | undefined;
+    private _position: Position | undefined;
+    private _internals: PDFDancerInternals;
+
+    constructor(_client: PDFDancer) {
+        this._client = _client;
+        // Cast to the internal interface to get access
+        this._internals = this._client as unknown as PDFDancerInternals;
+    }
+
+    fromFile(imagePath: string) {
+        if (!fs.existsSync(imagePath)) {
+            throw new Error(`Image not found: ${imagePath}`);
+        }
+        this._imageData = new Uint8Array(fs.readFileSync(imagePath));
+        return this
+    }
+
+    // noinspection JSUnusedGlobalSymbols
+    fromBytes(imageData: Uint8Array<ArrayBuffer>) {
+        this._imageData = imageData;
+        return this;
+    }
+
+    at(pageIndex: number, x: number, y: number) {
+        this._position = Position.atPageCoordinates(pageIndex, x, y);
+        return this;
+    }
+
+    async add() {
+        if (!this._imageData) {
+            throw new Error("Image data is not set");
+        }
+        if (!this._position) {
+            throw new Error("Position is not set");
+        }
+        let image = new Image();
+        image.data = this._imageData;
+        return await this._internals.addImage(image, this._position);
+    }
+}

package/src/index.ts

@@ -4,7 +4,7 @@
  * A TypeScript client library for the PDFDancer PDF manipulation API.
  */
 
-export { ClientV1 } from './client-v1';
+export { PDFDancer } from './pdfdancer_v1';
 export { ParagraphBuilder } from './paragraph-builder';
 
 export {

package/src/models.ts

@@ -88,7 +88,8 @@ export class Position {
         public shape?: ShapeType,
         public mode?: PositionMode,
         public boundingRect?: BoundingRect,
-        public textStartsWith?: string
+        public textStartsWith?: string,
+        public textPattern?: string
     ) {
     }
 
@@ -200,8 +201,6 @@ export class Position {
  * Lightweight reference to a PDF object providing identity and type information.
  */
 export class ObjectRef {
-    public name?: string;
-    public value?: string | null;
 
     constructor(
         public internalId: string,
@@ -210,22 +209,6 @@ export class ObjectRef {
     ) {
     }
 
-    getInternalId(): string {
-        return this.internalId;
-    }
-
-    getPosition(): Position {
-        return this.position;
-    }
-
-    setPosition(position: Position): void {
-        this.position = position;
-    }
-
-    getType(): ObjectType {
-        return this.type;
-    }
-
     toDict(): Record<string, any> {
         return {
             internalId: this.internalId,
@@ -244,8 +227,8 @@ export class FormFieldRef extends ObjectRef {
         internalId: string,
         position: Position,
         type: ObjectType,
-        public name?: string,
-        public value?: string | null
+        public name: string,
+        public value: string | null
     ) {
         super(internalId, position, type);
     }
@@ -525,6 +508,7 @@ function positionToDict(position: Position): Record<string, any> {
     const result: Record<string, any> = {
         pageIndex: position.pageIndex,
         textStartsWith: position.textStartsWith,
+        textPattern: position.textPattern,
         name: position.name
     };
 

package/src/paragraph-builder.ts

@@ -2,173 +2,228 @@
  * ParagraphBuilder for the PDFDancer TypeScript client.
  */
 
-import { ValidationException } from './exceptions';
-import { Paragraph, Font, Color, Position } from './models';
-import type { ClientV1 } from './client-v1';
+import {ValidationException} from './exceptions';
+import {Color, Font, ObjectRef, Paragraph, Position} from './models';
+import {PDFDancer} from "./pdfdancer_v1";
+
+// 👇 Internal view of PDFDancer methods, not exported
+interface PDFDancerInternals {
+    modifyParagraph(objectRefOrPageIndex: ObjectRef, text: string | Paragraph): Promise<boolean>;
+
+    addParagraph(paragraph: Paragraph): Promise<boolean>;
+}
 
 /**
  * Builder class for constructing Paragraph objects with fluent interface.
  */
 export class ParagraphBuilder {
-  private _paragraph: Paragraph;
-  private _lineSpacing: number = 1.2;
-  private _textColor: Color = new Color(0, 0, 0); // Black by default
-  private _text?: string;
-  private _font?: Font;
-
-  constructor(private _client: ClientV1) {
-    if (!_client) {
-      throw new ValidationException("Client cannot be null");
-    }
-
-    this._paragraph = new Paragraph();
-  }
-
-  /**
-   * Set the text content for the paragraph.
-   */
-  fromString(text: string, color?: Color): ParagraphBuilder {
-    if (text === null || text === undefined) {
-      throw new ValidationException("Text cannot be null");
-    }
-    if (!text.trim()) {
-      throw new ValidationException("Text cannot be empty");
-    }
-
-    this._text = text;
-    if (color) {
-      this._textColor = color;
-    }
-
-    return this;
-  }
-
-  /**
-   * Set the font for the paragraph using an existing Font object.
-   */
-  withFont(font: Font): ParagraphBuilder {
-    if (!font) {
-      throw new ValidationException("Font cannot be null");
-    }
-
-    this._font = font;
-    return this;
-  }
-
-  /**
-   * Set the font for the paragraph using a TTF file.
-   */
-  async withFontFile(ttfFile: Uint8Array | File, fontSize: number): Promise<ParagraphBuilder> {
-    if (!ttfFile) {
-      throw new ValidationException("TTF file cannot be null");
-    }
-    if (fontSize <= 0) {
-      throw new ValidationException(`Font size must be positive, got ${fontSize}`);
-    }
-
-    // Register font and create Font object
-    this._font = await this._registerTtf(ttfFile, fontSize);
-    return this;
-  }
-
-  /**
-   * Set the line spacing for the paragraph.
-   */
-  withLineSpacing(spacing: number): ParagraphBuilder {
-    if (spacing <= 0) {
-      throw new ValidationException(`Line spacing must be positive, got ${spacing}`);
-    }
-
-    this._lineSpacing = spacing;
-    return this;
-  }
-
-  /**
-   * Set the text color for the paragraph.
-   */
-  withColor(color: Color): ParagraphBuilder {
-    if (!color) {
-      throw new ValidationException("Color cannot be null");
-    }
-
-    this._textColor = color;
-    return this;
-  }
-
-  /**
-   * Set the position for the paragraph.
-   */
-  withPosition(position: Position): ParagraphBuilder {
-    if (!position) {
-      throw new ValidationException("Position cannot be null");
-    }
-
-    this._paragraph.setPosition(position);
-    return this;
-  }
-
-  /**
-   * Build and return the final Paragraph object.
-   */
-  build(): Paragraph {
-    // Validate required fields
-    if (!this._text) {
-      throw new ValidationException("Text must be set before building paragraph");
-    }
-    if (!this._font) {
-      throw new ValidationException("Font must be set before building paragraph");
-    }
-    if (!this._paragraph.getPosition()) {
-      throw new ValidationException("Position must be set before building paragraph");
-    }
-
-    // Set paragraph properties
-    this._paragraph.font = this._font;
-    this._paragraph.color = this._textColor;
-    this._paragraph.lineSpacing = this._lineSpacing;
-
-    // Process text into lines
-    this._paragraph.textLines = this._processTextLines(this._text);
-
-    return this._paragraph;
-  }
-
-  /**
-   * Register a TTF font with the client and return a Font object.
-   */
-  private async _registerTtf(ttfFile: Uint8Array | File, fontSize: number): Promise<Font> {
-    try {
-      const fontName = await this._client.registerFont(ttfFile);
-      return new Font(fontName, fontSize);
-    } catch (error) {
-      throw new ValidationException(`Failed to register font file: ${error}`);
-    }
-  }
-
-  /**
-   * Process text into lines for the paragraph.
-   * This is a simplified version - the full implementation would handle
-   * word wrapping, line breaks, and other text formatting based on the font
-   * and paragraph width.
-   */
-  private _processTextLines(text: string): string[] {
-    // Handle escaped newlines (\\n) as actual newlines
-    const processedText = text.replace(/\\\\n/g, '\n');
-
-    // Simple implementation - split on newlines
-    // In the full version, this would implement proper text layout
-    let lines = processedText.split('\n');
-
-    // Remove empty lines at the end but preserve intentional line breaks
-    while (lines.length > 0 && !lines[lines.length - 1].trim()) {
-      lines.pop();
-    }
-
-    // Ensure at least one line
-    if (lines.length === 0) {
-      lines = [''];
+    private _paragraph: Paragraph;
+    private _lineSpacing: number = 1.2;
+    private _textColor: Color = new Color(0, 0, 0); // Black by default
+    private _text?: string;
+    private _font?: Font;
+    private _pending: Promise<unknown>[] = [];
+    private _registeringFont: boolean = false;
+    private _pageIndex: number;
+    private _internals: PDFDancerInternals;
+
+    constructor(private _client: PDFDancer, private objectRefOrPageIndex?: ObjectRef | number) {
+        if (!_client) {
+            throw new ValidationException("Client cannot be null");
+        }
+
+        this._pageIndex = objectRefOrPageIndex instanceof ObjectRef ? objectRefOrPageIndex.position.pageIndex! : objectRefOrPageIndex!;
+        this._paragraph = new Paragraph();
+
+        // Cast to the internal interface to get access
+        this._internals = this._client as unknown as PDFDancerInternals;
+    }
+
+    /**
+     * Set the text content for the paragraph.
+     */
+    replace(text: string, color?: Color): ParagraphBuilder {
+        if (text === null || text === undefined) {
+            throw new ValidationException("Text cannot be null");
+        }
+        if (!text.trim()) {
+            throw new ValidationException("Text cannot be empty");
+        }
+
+        this._text = text;
+        if (color) {
+            this._textColor = color;
+        }
+
+        return this;
+    }
+
+    /**
+     * Set the font for the paragraph using an existing Font object.
+     */
+    font(font: Font): ParagraphBuilder;
+    font(fontName: string, fontSize: number): ParagraphBuilder;
+    font(fontOrName: Font | string, fontSize?: number): ParagraphBuilder {
+        if (fontOrName instanceof Font) {
+            this._font = fontOrName;
+        } else {
+            if (!fontOrName) {
+                throw new ValidationException("Font name cannot be null");
+            }
+            if (fontSize == null) {
+                throw new ValidationException("Font size cannot be null");
+            }
+            this._font = new Font(fontOrName, fontSize);
+        }
+
+        return this;
+    }
+
+    /**
+     * Set the font for the paragraph using a TTF file.
+     */
+    fontFile(ttfFile: Uint8Array | File, fontSize: number): this {
+        if (!ttfFile) throw new ValidationException("TTF file cannot be null");
+        if (fontSize <= 0) {
+            throw new ValidationException(`Font size must be positive, got ${fontSize}`);
+        }
+
+        this._registeringFont = true;
+        const job = this._registerTtf(ttfFile, fontSize).then(font => {
+            this._font = font;
+        });
+
+        this._pending.push(job);
+        return this;
+    }
+
+    /**
+     * Set the line spacing for the paragraph.
+     */
+    lineSpacing(spacing: number): ParagraphBuilder {
+        if (spacing <= 0) {
+            throw new ValidationException(`Line spacing must be positive, got ${spacing}`);
+        }
+
+        this._lineSpacing = spacing;
+        return this;
+    }
+
+    /**
+     * Set the text color for the paragraph.
+     */
+    color(color: Color): ParagraphBuilder {
+        if (!color) {
+            throw new ValidationException("Color cannot be null");
+        }
+
+        this._textColor = color;
+        return this;
+    }
+
+    /**
+     * Set the position for the paragraph.
+     */
+    moveTo(x: number, y: number): ParagraphBuilder {
+        if (x === null || x === undefined || y === null || y === undefined) {
+            throw new ValidationException("Coordinates cannot be null or undefined");
+        }
+
+        this._paragraph.setPosition(Position.atPageCoordinates(this._pageIndex, x, y));
+        return this;
+    }
+
+    /**
+     * Build and return the final Paragraph object.
+     */
+    private build(): Paragraph {
+        // Validate required fields
+        if (!this._text) {
+            throw new ValidationException("Text must be set before building paragraph");
+        }
+        // Set paragraph properties
+        this._paragraph.font = this._font;
+        this._paragraph.color = this._textColor;
+        this._paragraph.lineSpacing = this._lineSpacing;
+
+        // Process text into lines
+        this._paragraph.textLines = this._processTextLines(this._text);
+
+        return this._paragraph;
+    }
+
+    /**
+     * Register a TTF font with the client and return a Font object.
+     */
+    private async _registerTtf(ttfFile: Uint8Array | File, fontSize: number): Promise<Font> {
+        try {
+            const fontName = await this._client.registerFont(ttfFile);
+            return new Font(fontName, fontSize);
+        } catch (error) {
+            throw new ValidationException(`Failed to register font file: ${error}`);
+        }
+    }
+
+    /**
+     * Process text into lines for the paragraph.
+     * This is a simplified version - the full implementation would handle
+     * word wrapping, line breaks, and other text formatting based on the font
+     * and paragraph width.
+     */
+    private _processTextLines(text: string): string[] {
+        // Handle escaped newlines (\\n) as actual newlines
+        const processedText = text.replace(/\\\\n/g, '\n');
+
+        // Simple implementation - split on newlines
+        // In the full version, this would implement proper text layout
+        let lines = processedText.split('\n');
+
+        // Remove empty lines at the end but preserve intentional line breaks
+        while (lines.length > 0 && !lines[lines.length - 1].trim()) {
+            lines.pop();
+        }
+
+        // Ensure at least one line
+        if (lines.length === 0) {
+            lines = [''];
+        }
+
+        return lines;
+    }
+
+    async apply() {
+        if (!this._text) {
+            throw new ValidationException("Text must be set before building paragraph");
+        }
+        // Wait for all deferred operations (e.g., fontFile, images, etc.)
+        if (this._pending.length) {
+            await Promise.all(this._pending);
+            this._pending = []; // reset if builder is reusable
+        }
+
+        if (this._registeringFont && !this._font) {
+            throw new ValidationException("Font registration is not complete");
+        }
+
+        let paragraph = this.build();
+        if (this.objectRefOrPageIndex instanceof ObjectRef) {
+            if (!this._font || !this._textColor) {
+                return await this._internals.modifyParagraph(this.objectRefOrPageIndex, this._text);
+            } else {
+                return await this._internals.modifyParagraph(this.objectRefOrPageIndex, paragraph);
+            }
+        } else {
+            return await this._internals.addParagraph(paragraph);
+        }
+    }
+
+    text(text: string) {
+        this._text = text;
+        return this;
+    }
+
+    at(x: number, y: number) {
+        return this.moveTo(x, y);
     }
 
-    return lines;
-  }
 }