pdfdancer-client-typescript 1.0.9 → 1.0.10

package/src/paragraph-builder.ts

@@ -3,12 +3,12 @@
  */
 
 import {ValidationException} from './exceptions';
-import {Color, Font, ObjectRef, Paragraph, Position, TextObjectRef} from './models';
+import {Color, CommandResult, Font, ObjectRef, Paragraph, Position, TextObjectRef} from './models';
 import {PDFDancer} from "./pdfdancer_v1";
 
 // 👇 Internal view of PDFDancer methods, not exported
 interface PDFDancerInternals {
-    modifyParagraph(objectRefOrPageIndex: ObjectRef, text: string | Paragraph): Promise<boolean>;
+    modifyParagraph(objectRefOrPageIndex: ObjectRef, text: string | Paragraph): Promise<CommandResult>;
 
     addParagraph(paragraph: Paragraph): Promise<boolean>;
 }
@@ -226,7 +226,7 @@ export class ParagraphBuilder {
         return lines;
     }
 
-    async apply() {
+    async apply(): Promise<boolean | CommandResult> {
         // Wait for all deferred operations (e.g., fontFile, images, etc.)
         if (this._pending.length) {
             await Promise.all(this._pending);
@@ -247,7 +247,11 @@ export class ParagraphBuilder {
                 this._font === undefined &&
                 this._textColor === undefined) {
                 // Simple text-only modification
-                return await this._internals.modifyParagraph(originalRef, this._text!);
+                const result = await this._internals.modifyParagraph(originalRef, this._text!);
+                if (result.warning) {
+                    process.stderr.write(`WARNING: ${result.warning}\n`);
+                }
+                return result;
             } else {
                 // Full paragraph modification - build new paragraph using getter methods to preserve original values
                 const newParagraph = new Paragraph();
@@ -257,7 +261,11 @@ export class ParagraphBuilder {
                 newParagraph.textLines = this._text ? this._processTextLines(this._text) : this._processTextLines(originalRef.text!);
                 newParagraph.color = this._getColor(originalRef);
 
-                return await this._internals.modifyParagraph(originalRef, newParagraph);
+                const result = await this._internals.modifyParagraph(originalRef, newParagraph);
+                if (result.warning) {
+                    process.stderr.write(`WARNING: ${result.warning}\n`);
+                }
+                return result;
             }
         } else {
             // Adding new paragraph

package/src/pdfdancer_v1.ts

@@ -15,22 +15,32 @@ import {
     AddRequest,
     BoundingRect,
     ChangeFormFieldRequest,
+    Color,
+    CommandResult,
+    CreatePdfRequest,
     DeleteRequest,
     FindRequest,
     Font,
+    FontRecommendation,
+    FontType,
     FormFieldRef,
     Image,
     ModifyRequest,
     ModifyTextRequest,
     MoveRequest,
+    MovePageRequest,
     ObjectRef,
     ObjectType,
+    PageRef,
+    PageSize,
+    PageSizeInput,
+    Orientation,
     Paragraph,
     Position,
     PositionMode,
     ShapeType,
     TextObjectRef,
-    Color
+    TextStatus
 } from './models';
 import {ParagraphBuilder} from './paragraph-builder';
 import {FormFieldObject, FormXObject, ImageObject, ParagraphObject, PathObject, TextLineObject} from "./types";
@@ -47,8 +57,6 @@ interface PDFDancerInternals {
 
     toFormXObjects(objectRefs: ObjectRef[]): FormXObject[];
 
-    deletePage(objectRef: ObjectRef): Promise<boolean>;
-
     toTextLineObjects(objectRefs: ObjectRef[]): TextLineObject[];
 
     toFormFields(formFieldRefs: FormFieldRef[]): FormFieldObject[];
@@ -75,13 +83,17 @@ class PageClient {
     type: ObjectType = ObjectType.PAGE;
     position: Position;
     internalId: string;
+    pageSize?: PageSize;
+    orientation?: Orientation;
     private _internals: PDFDancerInternals;
 
-    constructor(client: PDFDancer, pageIndex: number) {
+    constructor(client: PDFDancer, pageIndex: number, pageRef?: PageRef) {
         this._client = client;
         this._pageIndex = pageIndex;
-        this.internalId = `PAGE-${this._pageIndex}`;
-        this.position = Position.atPage(this._pageIndex);
+        this.internalId = pageRef?.internalId ?? `PAGE-${this._pageIndex}`;
+        this.position = pageRef?.position ?? Position.atPage(this._pageIndex);
+        this.pageSize = pageRef?.pageSize;
+        this.orientation = pageRef?.orientation;
         // Cast to the internal interface to get access
         this._internals = this._client as unknown as PDFDancerInternals;
     }
@@ -90,6 +102,10 @@ class PageClient {
         return this._internals.toPathObjects(await this._internals.findPaths(Position.atPageCoordinates(this._pageIndex, x, y)));
     }
 
+    async selectPaths() {
+        return this._internals.toPathObjects(await this._internals.findPaths(Position.atPage(this._pageIndex)));
+    }
+
     async selectImages() {
         return this._internals.toImageObjects(await this._internals._findImages(Position.atPage(this._pageIndex)));
     }
@@ -98,12 +114,18 @@ class PageClient {
         return this._internals.toImageObjects(await this._internals._findImages(Position.atPageCoordinates(this._pageIndex, x, y)));
     }
 
-    async delete() {
-        return this._internals.deletePage(this.ref());
+    async delete(): Promise<boolean> {
+        return this._client.deletePage(this._pageIndex);
     }
 
-    private ref() {
-        return new ObjectRef(this.internalId, this.position, this.type);
+    async moveTo(targetPageIndex: number): Promise<PageRef> {
+        const pageRef = await this._client.movePage(this._pageIndex, targetPageIndex);
+        this._pageIndex = pageRef.position.pageIndex ?? targetPageIndex;
+        this.position = pageRef.position;
+        this.internalId = pageRef.internalId;
+        this.pageSize = pageRef.pageSize;
+        this.orientation = pageRef.orientation;
+        return pageRef;
     }
 
     // noinspection JSUnusedGlobalSymbols
@@ -243,6 +265,94 @@ export class PDFDancer {
         return await client.init();
     }
 
+    /**
+     * Creates a new, blank PDF document with the specified parameters.
+     *
+     * @param options Configuration options for the new PDF
+     * @param options.pageSize Page size (default: "A4")
+     * @param options.orientation Page orientation (default: "PORTRAIT")
+     * @param options.initialPageCount Number of initial pages (default: 1)
+     * @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: 30000)
+     */
+    static async new(
+        options?: {
+            pageSize?: PageSizeInput;
+            orientation?: Orientation;
+            initialPageCount?: number;
+        },
+        token?: string,
+        baseUrl?: string,
+        timeout?: number
+    ): Promise<PDFDancer> {
+        const resolvedToken = token ?? process.env.PDFDANCER_TOKEN;
+        const resolvedBaseUrl =
+            baseUrl ??
+            process.env.PDFDANCER_BASE_URL ??
+            "https://api.pdfdancer.com";
+        const resolvedTimeout = timeout ?? 30000;
+
+        if (!resolvedToken) {
+            throw new Error("Missing PDFDancer token (pass it explicitly or set PDFDANCER_TOKEN in environment).");
+        }
+
+        let createRequest: CreatePdfRequest;
+        try {
+            createRequest = new CreatePdfRequest(
+                options?.pageSize ?? "A4",
+                options?.orientation ?? Orientation.PORTRAIT,
+                options?.initialPageCount ?? 1
+            );
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new ValidationException(message);
+        }
+
+        try {
+            // Build URL ensuring no double slashes
+            const base = resolvedBaseUrl.replace(/\/+$/, '');
+            const endpoint = '/session/new'.replace(/^\/+/, '');
+            const url = `${base}/${endpoint}`;
+
+            // Make request to create endpoint
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${resolvedToken}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(createRequest.toDict()),
+                signal: resolvedTimeout > 0 ? AbortSignal.timeout(resolvedTimeout) : undefined
+            });
+
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new HttpClientException(`Failed to create new PDF: ${errorText}`, response);
+            }
+
+            const sessionId = (await response.text()).trim();
+
+            if (!sessionId) {
+                throw new SessionException("Server returned empty session ID");
+            }
+
+            const client = Object.create(PDFDancer.prototype) as PDFDancer;
+            client._token = resolvedToken.trim();
+            client._baseUrl = resolvedBaseUrl.replace(/\/+$/, '');
+            client._readTimeout = resolvedTimeout;
+            client._pdfBytes = new Uint8Array();
+            client._sessionId = sessionId;
+            return client;
+        } catch (error) {
+            if (error instanceof HttpClientException || error instanceof SessionException || error instanceof ValidationException) {
+                throw error;
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new HttpClientException(`Failed to create new PDF: ${errorMessage}`, undefined, error as Error);
+        }
+    }
+
     /**
      * Process PDF data from various input types with strict validation.
      */
@@ -277,6 +387,16 @@ export class PDFDancer {
         }
     }
 
+    /**
+     * Build a URL path ensuring no double slashes.
+     * Combines baseUrl and path while handling trailing/leading slashes.
+     */
+    private _buildUrl(path: string): string {
+        const base = this._baseUrl.replace(/\/+$/, '');
+        const endpoint = path.replace(/^\/+/, '');
+        return `${base}/${endpoint}`;
+    }
+
     /**
      * Extract meaningful error messages from API response.
      * Parses JSON error responses with _embedded.errors structure.
@@ -335,7 +455,7 @@ export class PDFDancer {
                 formData.append('pdf', blob, 'document.pdf');
             }
 
-            const response = await fetch(`${this._baseUrl}/session/create`, {
+            const response = await fetch(this._buildUrl('/session/create'), {
                 method: 'POST',
                 headers: {
                     'Authorization': `Bearer ${this._token}`
@@ -374,7 +494,7 @@ export class PDFDancer {
         data?: Record<string, any>,
         params?: Record<string, string>
     ): Promise<Response> {
-        const url = new URL(`${this._baseUrl}${path}`);
+        const url = new URL(this._buildUrl(path));
         if (params) {
             Object.entries(params).forEach(([key, value]) => {
                 url.searchParams.append(key, value);
@@ -512,16 +632,16 @@ export class PDFDancer {
     /**
      * Retrieves references to all pages in the PDF document.
      */
-    private async getPages(): Promise<ObjectRef[]> {
+    private async getPages(): Promise<PageRef[]> {
         const response = await this._makeRequest('POST', '/pdf/page/find');
         const pagesData = await response.json() as any[];
-        return pagesData.map((pageData: any) => this._parseObjectRef(pageData));
+        return pagesData.map((pageData: any) => this._parsePageRef(pageData));
     }
 
     /**
      * Retrieves a reference to a specific page by its page index.
      */
-    private async _getPage(pageIndex: number): Promise<ObjectRef | null> {
+    private async _getPage(pageIndex: number): Promise<PageRef | null> {
         if (pageIndex < 0) {
             throw new ValidationException(`Page index must be >= 0, got ${pageIndex}`);
         }
@@ -534,13 +654,62 @@ export class PDFDancer {
             return null;
         }
 
-        return this._parseObjectRef(pagesData[0]);
+        return this._parsePageRef(pagesData[0]);
+    }
+
+    /**
+     * Moves an existing page to a new index.
+     */
+    async movePage(pageIndex: number, targetPageIndex: number): Promise<PageRef> {
+        this._validatePageIndex(pageIndex, 'pageIndex');
+        this._validatePageIndex(targetPageIndex, 'targetPageIndex');
+
+        // Ensure the source page exists before attempting the move
+        await this._requirePageRef(pageIndex);
+
+        const request = new MovePageRequest(pageIndex, targetPageIndex).toDict();
+        const response = await this._makeRequest('PUT', '/pdf/page/move', request);
+        const success = await response.json() as boolean;
+
+        if (!success) {
+            throw new HttpClientException(`Failed to move page from ${pageIndex} to ${targetPageIndex}`, response);
+        }
+
+        // Fetch the page again at its new position for up-to-date metadata
+        return await this._requirePageRef(targetPageIndex);
+    }
+
+    /**
+     * Deletes the page at the specified index.
+     */
+    async deletePage(pageIndex: number): Promise<boolean> {
+        this._validatePageIndex(pageIndex, 'pageIndex');
+
+        const pageRef = await this._requirePageRef(pageIndex);
+        return this._deletePage(pageRef);
+    }
+
+    private _validatePageIndex(pageIndex: number, fieldName: string): void {
+        if (!Number.isInteger(pageIndex)) {
+            throw new ValidationException(`${fieldName} must be an integer, got ${pageIndex}`);
+        }
+        if (pageIndex < 0) {
+            throw new ValidationException(`${fieldName} must be >= 0, got ${pageIndex}`);
+        }
+    }
+
+    private async _requirePageRef(pageIndex: number): Promise<PageRef> {
+        const pageRef = await this._getPage(pageIndex);
+        if (!pageRef) {
+            throw new ValidationException(`Page not found at index ${pageIndex}`);
+        }
+        return pageRef;
     }
 
     /**
      * Deletes a page from the PDF document.
      */
-    private async deletePage(pageRef: ObjectRef): Promise<boolean> {
+    private async _deletePage(pageRef: ObjectRef): Promise<boolean> {
         if (!pageRef) {
             throw new ValidationException("Page reference cannot be null");
         }
@@ -649,31 +818,31 @@ export class PDFDancer {
     /**
      * Modifies a paragraph object or its text content.
      */
-    private async modifyParagraph(objectRef: ObjectRef, newParagraph: Paragraph | string): Promise<boolean> {
+    private async modifyParagraph(objectRef: ObjectRef, newParagraph: Paragraph | string): Promise<CommandResult> {
         if (!objectRef) {
             throw new ValidationException("Object reference cannot be null");
         }
         if (newParagraph === null || newParagraph === undefined) {
-            throw new ValidationException("New paragraph cannot be null");
+            return CommandResult.empty("ModifyParagraph", objectRef.internalId);
         }
 
         if (typeof newParagraph === 'string') {
-            // Text modification
+            // Text modification - returns CommandResult
             const requestData = new ModifyTextRequest(objectRef, newParagraph).toDict();
             const response = await this._makeRequest('PUT', '/pdf/text/paragraph', requestData);
-            return await response.json() as boolean;
+            return CommandResult.fromDict(await response.json());
         } else {
             // Object modification
             const requestData = new ModifyRequest(objectRef, newParagraph).toDict();
             const response = await this._makeRequest('PUT', '/pdf/modify', requestData);
-            return await response.json() as boolean;
+            return CommandResult.fromDict(await response.json());
         }
     }
 
     /**
      * Modifies a text line object.
      */
-    private async modifyTextLine(objectRef: ObjectRef, newText: string): Promise<boolean> {
+    private async modifyTextLine(objectRef: ObjectRef, newText: string): Promise<CommandResult> {
         if (!objectRef) {
             throw new ValidationException("Object reference cannot be null");
         }
@@ -683,7 +852,7 @@ export class PDFDancer {
 
         const requestData = new ModifyTextRequest(objectRef, newText).toDict();
         const response = await this._makeRequest('PUT', '/pdf/text/line', requestData);
-        return await response.json() as boolean;
+        return CommandResult.fromDict(await response.json());
     }
 
     // Font Operations
@@ -745,7 +914,7 @@ export class PDFDancer {
             const blob = new Blob([fontData.buffer as ArrayBuffer], {type: 'font/ttf'});
             formData.append('ttfFile', blob, filename);
 
-            const response = await fetch(`${this._baseUrl}/font/register`, {
+            const response = await fetch(this._buildUrl('/font/register'), {
                 method: 'POST',
                 headers: {
                     'Authorization': `Bearer ${this._token}`,
@@ -809,6 +978,10 @@ export class PDFDancer {
 
         const objectType = objData.type as ObjectType;
 
+        if (objectType === ObjectType.PAGE) {
+            return this._parsePageRef(objData);
+        }
+
         if (this._isTextObjectData(objData, objectType)) {
             return this._parseTextObjectRef(objData);
         }
@@ -836,6 +1009,32 @@ export class PDFDancer {
         const lineSpacings = Array.isArray(objData.lineSpacings) ? objData.lineSpacings : null;
         const internalId = objData.internalId ?? fallbackId ?? '';
 
+        // Parse status if present
+        let status: TextStatus | undefined;
+        const statusData = objData.status;
+        if (statusData && typeof statusData === 'object') {
+            // Parse font recommendation
+            const fontRecData = statusData.fontRecommendation;
+            let fontRec: FontRecommendation;
+            if (fontRecData && typeof fontRecData === 'object') {
+                fontRec = new FontRecommendation(
+                    fontRecData.fontName || '',
+                    (fontRecData.fontType as FontType) || FontType.SYSTEM,
+                    fontRecData.similarityScore || 0.0
+                );
+            } else {
+                // Create empty font recommendation if not provided
+                fontRec = new FontRecommendation('', FontType.SYSTEM, 0.0);
+            }
+
+            status = new TextStatus(
+                statusData.modified || false,
+                statusData.encodable !== undefined ? statusData.encodable : true,
+                (statusData.fontType as FontType) || FontType.SYSTEM,
+                fontRec
+            );
+        }
+
         const textObject = new TextObjectRef(
             internalId,
             position,
@@ -845,7 +1044,8 @@ export class PDFDancer {
             typeof objData.fontSize === 'number' ? objData.fontSize : undefined,
             lineSpacings,
             undefined,
-            this._parseColor(objData.color)
+            this._parseColor(objData.color),
+            status
         );
 
         if (Array.isArray(objData.children) && objData.children.length > 0) {
@@ -858,6 +1058,55 @@ export class PDFDancer {
         return textObject;
     }
 
+    private _parsePageRef(objData: any): PageRef {
+        const positionData = objData.position || {};
+        const position = positionData ? this._parsePosition(positionData) : new Position();
+
+        const pageSize = this._parsePageSize(objData.pageSize);
+        const orientation = this._parseOrientation(objData.orientation);
+
+        return new PageRef(
+            objData.internalId,
+            position,
+            ObjectType.PAGE,
+            pageSize,
+            orientation
+        );
+    }
+
+    private _parsePageSize(pageSizeData: any): PageSize | undefined {
+        if (!pageSizeData || typeof pageSizeData !== 'object') {
+            return undefined;
+        }
+
+        const name = typeof pageSizeData.name === 'string' ? pageSizeData.name : undefined;
+        const width = typeof pageSizeData.width === 'number' ? pageSizeData.width : undefined;
+        const height = typeof pageSizeData.height === 'number' ? pageSizeData.height : undefined;
+
+        if (name === undefined && width === undefined && height === undefined) {
+            return undefined;
+        }
+
+        return {name, width, height};
+    }
+
+    private _parseOrientation(orientationData: any): Orientation | undefined {
+        if (typeof orientationData !== 'string') {
+            return undefined;
+        }
+
+        if (orientationData === Orientation.PORTRAIT || orientationData === Orientation.LANDSCAPE) {
+            return orientationData;
+        }
+
+        const normalized = orientationData.trim().toUpperCase();
+        if (normalized === Orientation.PORTRAIT || normalized === Orientation.LANDSCAPE) {
+            return normalized as Orientation;
+        }
+
+        return undefined;
+    }
+
     private _parseColor(colorData: any): Color | undefined {
         if (!colorData || typeof colorData !== 'object') {
             return undefined;
@@ -949,8 +1198,8 @@ export class PDFDancer {
     }
 
     async pages() {
-        let pageRefs = await this.getPages();
-        return pageRefs.map((_, pageIndex) => new PageClient(this, pageIndex));
+        const pageRefs = await this.getPages();
+        return pageRefs.map((pageRef, pageIndex) => new PageClient(this, pageIndex, pageRef));
     }
 
     private toFormFields(objectRefs: FormFieldRef[]) {

package/src/types.ts

@@ -1,4 +1,4 @@
-import {Color, FormFieldRef, ObjectRef, ObjectType, Position, TextObjectRef} from "./models";
+import {Color, CommandResult, FormFieldRef, ObjectRef, ObjectType, Position, TextObjectRef} from "./models";
 import {PDFDancer} from "./pdfdancer_v1";
 import {ParagraphBuilder} from "./paragraph-builder";
 
@@ -10,7 +10,7 @@ interface PDFDancerInternals {
 
     changeFormField(formFieldRef: FormFieldRef, value: string): Promise<boolean>;
 
-    modifyTextLine(objectRef: ObjectRef, newText: string): Promise<boolean>;
+    modifyTextLine(objectRef: ObjectRef, newText: string): Promise<CommandResult>;
 }
 
 export class BaseObject<TRef extends ObjectRef = ObjectRef> {
@@ -112,6 +112,30 @@ export class ParagraphObject extends BaseObject<TextObjectRef> {
         return new ParagraphBuilder(this._client, this.ref());
     }
 
+    objectRef() {
+        return this.ref();
+    }
+
+    getText() {
+        return this.text;
+    }
+
+    getFontName() {
+        return this.fontName;
+    }
+
+    getFontSize() {
+        return this.fontSize;
+    }
+
+    getColor() {
+        return this.color;
+    }
+
+    getChildren() {
+        return this.children;
+    }
+
     private setFontName(fontName: string | undefined) {
         this.fontName = fontName;
     }
@@ -185,6 +209,30 @@ export class TextLineObject extends BaseObject<TextObjectRef> {
     private setColor(color: Color | undefined) {
         this.color = color;
     }
+
+    objectRef() {
+        return this.ref();
+    }
+
+    getText() {
+        return this.text;
+    }
+
+    getFontName() {
+        return this.fontName;
+    }
+
+    getFontSize() {
+        return this.fontSize;
+    }
+
+    getColor() {
+        return this.color;
+    }
+
+    getChildren() {
+        return this.children;
+    }
 }
 
 
@@ -207,6 +255,10 @@ class TextLineBuilder {
     }
 
     async apply() {
-        return await this._internals.modifyTextLine(this._objectRef, this._text!);
+        const result = await this._internals.modifyTextLine(this._objectRef, this._text!);
+        if (result.warning) {
+            process.stderr.write(`WARNING: ${result.warning}\n`);
+        }
+        return result;
     }
 }