pdfdancer-client-typescript 1.0.1

package/.eslintrc.js

@@ -0,0 +1,19 @@
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'eslint:recommended',
+  ],
+  root: true,
+  env: {
+    node: true,
+    jest: true,
+  },
+  ignorePatterns: ['.eslintrc.js', 'dist/', 'node_modules/'],
+  rules: {
+    '@typescript-eslint/interface-name-prefix': 'off',
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/no-explicit-any': 'warn',
+  },
+};

package/README.md

@@ -0,0 +1,267 @@
+# PDFDancer TypeScript Client
+
+A TypeScript client library for the PDFDancer PDF manipulation API. This client provides a clean, TypeScript interface for PDF operations that closely mirrors the Python client structure and functionality.
+
+## Features
+
+- **Session-based PDF manipulation** - Upload PDF, perform operations, download modified PDF
+- **Type-safe API** - Full TypeScript support with proper types and interfaces
+- **Fluent Builder Pattern** - Easy paragraph construction with method chaining
+- **Comprehensive Search** - Find PDF objects by type, position, and other criteria
+- **Custom Font Support** - Register and use custom TTF fonts
+- **Error Handling** - Detailed exceptions for different error scenarios
+- **Browser Compatible** - Works in both Node.js and browser environments
+
+## Installation
+
+```bash
+npm install pdfdancer-client-typescript
+```
+
+## Basic Usage
+
+```typescript
+import { ClientV1, Position, Color, Font } from 'pdfdancer-client-typescript';
+
+async function example() {
+  // Load PDF data (from file upload, fetch, etc.)
+  const pdfData = new Uint8Array(/* your PDF data */);
+
+  // Create client with authentication token
+  const client = new ClientV1('your-auth-token', pdfData);
+
+  // Initialize session (required before using the client)
+  await client.init();
+
+  // Find all paragraphs on page 1
+  const paragraphs = await client.findParagraphs(Position.fromPageIndex(1));
+
+  // Add a new paragraph
+  const newParagraph = client.paragraphBuilder()
+    .fromString('Hello, PDFDancer!', new Color(255, 0, 0))
+    .withFont(new Font('Arial', 12))
+    .withPosition(Position.onPageCoordinates(1, 100, 200))
+    .build();
+
+  await client.addParagraph(newParagraph);
+
+  // Get the modified PDF
+  const modifiedPdf = await client.getPdfFile();
+
+  // Save PDF (browser environment)
+  await client.savePdf('modified-document.pdf');
+}
+```
+
+## API Overview
+
+### Client Initialization
+
+```typescript
+const client = new ClientV1(
+  token,        // Authentication token
+  pdfData,      // PDF data as Uint8Array, File, or ArrayBuffer
+  baseUrl,      // Optional: API server URL (default: http://localhost:8080)
+  readTimeout   // Optional: Request timeout in ms (default: 30000)
+);
+
+await client.init(); // Required before using the client
+```
+
+### Search Operations
+
+```typescript
+// Find objects by type and position
+const objects = await client.find(ObjectType.PARAGRAPH, position);
+
+// Convenience methods for specific object types
+const paragraphs = await client.findParagraphs(position);
+const images = await client.findImages(position);
+const forms = await client.findForms(position);
+const paths = await client.findPaths(position);
+const textLines = await client.findTextLines(position);
+
+// Page operations
+const pages = await client.getPages();
+const page = await client.getPage(1); // 1-based index
+```
+
+### Position Specification
+
+```typescript
+// Page-based position
+const pagePosition = Position.fromPageIndex(1);
+
+// Coordinate-based position
+const coordPosition = Position.onPageCoordinates(1, 100, 200);
+
+// Position with movement
+const movedPosition = coordPosition.copy().moveX(50).moveY(30);
+```
+
+### Adding Content
+
+```typescript
+// Add paragraph using builder pattern
+const paragraph = client.paragraphBuilder()
+  .fromString('Your text here')
+  .withFont(new Font('Arial', 12))
+  .withColor(new Color(0, 0, 0))
+  .withPosition(Position.onPageCoordinates(1, 100, 200))
+  .withLineSpacing(1.2)
+  .build();
+
+await client.addParagraph(paragraph);
+
+// Add image
+const image = new Image(position, 'PNG', 100, 50, imageData);
+await client.addImage(image);
+```
+
+### Modifying Content
+
+```typescript
+// Modify paragraph text
+await client.modifyParagraph(paragraphRef, 'New text content');
+
+// Modify text line
+await client.modifyTextLine(textLineRef, 'New line content');
+
+// Move object to new position
+await client.move(objectRef, newPosition);
+
+// Delete object
+await client.delete(objectRef);
+```
+
+### Font Management
+
+```typescript
+// Find available fonts
+const fonts = await client.findFonts('Arial', 12);
+
+// Register custom font
+const ttfData = new Uint8Array(/* TTF font data */);
+const fontName = await client.registerFont(ttfData);
+
+// Use custom font
+const customFont = new Font(fontName, 14);
+```
+
+### Document Operations
+
+```typescript
+// Get modified PDF data
+const pdfBytes = await client.getPdfFile();
+
+// Save PDF file (browser)
+await client.savePdf('output.pdf');
+
+// Delete page
+await client.deletePage(pageRef);
+```
+
+## Error Handling
+
+The client provides specific exception types for different error scenarios:
+
+```typescript
+import {
+  ValidationException,
+  HttpClientException,
+  SessionException,
+  FontNotFoundException,
+  PdfDancerException
+} from 'pdfdancer-client-typescript';
+
+try {
+  await client.addParagraph(paragraph);
+} catch (error) {
+  if (error instanceof ValidationException) {
+    console.error('Invalid input:', error.message);
+  } else if (error instanceof HttpClientException) {
+    console.error('API error:', error.message, 'Status:', error.statusCode);
+  } else if (error instanceof FontNotFoundException) {
+    console.error('Font not found:', error.message);
+  } else if (error instanceof SessionException) {
+    console.error('Session error:', error.message);
+  }
+}
+```
+
+## Types and Enums
+
+### ObjectType
+- `IMAGE` - Image objects
+- `FORM` - Form field objects
+- `PATH` - Vector path objects
+- `PARAGRAPH` - Paragraph objects
+- `TEXT_LINE` - Text line objects
+- `PAGE` - Page objects
+
+### PositionMode
+- `INTERSECT` - Objects that intersect with the specified area
+- `CONTAINS` - Objects completely contained within the specified area
+
+### ShapeType
+- `POINT` - Single point coordinate
+- `LINE` - Linear shape between two points
+- `CIRCLE` - Circular area with radius
+- `RECT` - Rectangular area with width and height
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run all tests
+npm test
+
+# Run only unit tests
+npm run test:unit
+
+# Run only e2e tests (requires fixtures and server)
+npm run test:e2e
+
+# Run linter
+npm run lint
+```
+
+### E2E Tests
+
+The project includes comprehensive end-to-end tests that mirror the Python client test suite. To run e2e tests:
+
+1. **Start PDFDancer server** at `http://localhost:8080` (or set `PDFDANCER_BASE_URL`)
+
+2. **Set authentication token**:
+   - Environment variable: `export PDFDANCER_TOKEN=your-token`
+   - Or place a `jwt-token-*.txt` file in the project root
+
+3. **Add test fixtures** in the `fixtures/` directory:
+   - `ObviouslyAwesome.pdf` - Main test document
+   - `mixed-form-types.pdf` - Document with form fields
+   - `basic-paths.pdf` - Document with vector paths
+   - `logo-80.png` - Test image file
+   - `DancingScript-Regular.ttf` - Test font file
+
+4. **Run e2e tests**: `npm run test:e2e`
+
+The e2e tests cover:
+- **Paragraph operations**: Find, add, modify, delete paragraphs with custom fonts
+- **Page operations**: Get pages, delete pages
+- **Text line operations**: Find, modify, move, delete text lines
+- **Image operations**: Find, add, move, delete images
+- **Form operations**: Find and delete form fields
+- **Path operations**: Find, move, delete vector paths
+
+## Compatibility
+
+This TypeScript client is designed to be functionally equivalent to the PDFDancer Python client, providing the same API patterns and capabilities with TypeScript type safety and modern JavaScript features.
+
+## License
+
+MIT

package/dist/__tests__/e2e/test-helpers.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Helper functions for e2e tests
+ */
+/**
+ * Get the base URL from environment variable or default
+ */
+export declare function getBaseUrl(): string;
+/**
+ * Read authentication token from environment or token files
+ */
+export declare function readToken(): string | null;
+/**
+ * Check if server is up and running
+ */
+export declare function serverUp(baseUrl: string): Promise<boolean>;
+/**
+ * Require environment variables and PDF fixture for testing
+ */
+export declare function requireEnvAndFixture(pdfFilename: string): Promise<[string, string, Uint8Array]>;
+/**
+ * Helper to create temporary file path (for Node.js environment)
+ */
+export declare function createTempPath(filename: string): string;
+/**
+ * Helper to read image file for tests
+ */
+export declare function readImageFixture(filename: string): Uint8Array;
+/**
+ * Helper to read font file for tests
+ */
+export declare function readFontFixture(filename: string): Uint8Array;
+//# sourceMappingURL=test-helpers.d.ts.map

package/dist/__tests__/e2e/test-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["../../../src/__tests__/e2e/test-helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,GAAG,IAAI,CAmBzC;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUhE;AAiBD;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAsBrG;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAU7D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAU5D"}

package/dist/__tests__/e2e/test-helpers.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * Helper functions 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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBaseUrl = getBaseUrl;
+exports.readToken = readToken;
+exports.serverUp = serverUp;
+exports.requireEnvAndFixture = requireEnvAndFixture;
+exports.createTempPath = createTempPath;
+exports.readImageFixture = readImageFixture;
+exports.readFontFixture = readFontFixture;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Get the base URL from environment variable or default
+ */
+function getBaseUrl() {
+    return process.env.PDFDANCER_BASE_URL || 'http://localhost:8080';
+}
+/**
+ * Read authentication token from environment or token files
+ */
+function readToken() {
+    const token = process.env.PDFDANCER_TOKEN;
+    if (token) {
+        return token.trim();
+    }
+    // Try common token files in project root
+    const projectRoot = path.resolve(__dirname, '../../..');
+    const candidates = findFiles(projectRoot, 'jwt-token-*.txt');
+    for (const file of candidates) {
+        try {
+            return fs.readFileSync(file, 'utf-8').trim();
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Check if server is up and running
+ */
+async function serverUp(baseUrl) {
+    try {
+        const response = await fetch(`${baseUrl}/ping`, {
+            signal: AbortSignal.timeout(3000)
+        });
+        const text = await response.text();
+        return response.status === 200 && text.includes('Pong');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Helper to find files matching a pattern
+ */
+function findFiles(dir, pattern) {
+    try {
+        const files = fs.readdirSync(dir);
+        const regex = new RegExp(pattern.replace('*', '.*'));
+        return files
+            .filter(file => regex.test(file))
+            .map(file => path.join(dir, file));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Require environment variables and PDF fixture for testing
+ */
+async function requireEnvAndFixture(pdfFilename) {
+    const baseUrl = getBaseUrl();
+    const token = readToken();
+    if (!await serverUp(baseUrl)) {
+        throw new Error(`PDFDancer server not reachable at ${baseUrl}; set PDFDANCER_BASE_URL or start server`);
+    }
+    if (!token) {
+        throw new Error('PDFDANCER_TOKEN not set and no token file found; set env or place jwt-token-*.txt in repo');
+    }
+    // Look for PDF fixture file
+    const fixturesDir = path.resolve(__dirname, '../../../fixtures');
+    const pdfPath = path.join(fixturesDir, pdfFilename);
+    if (!fs.existsSync(pdfPath)) {
+        throw new Error(`${pdfFilename} fixture not found at ${pdfPath}`);
+    }
+    const pdfData = fs.readFileSync(pdfPath);
+    return [baseUrl, token, new Uint8Array(pdfData)];
+}
+/**
+ * Helper to create temporary file path (for Node.js environment)
+ */
+function createTempPath(filename) {
+    const tmpDir = process.env.TMPDIR || '/tmp';
+    return path.join(tmpDir, filename);
+}
+/**
+ * Helper to read image file for tests
+ */
+function readImageFixture(filename) {
+    const fixturesDir = path.resolve(__dirname, '../../../fixtures');
+    const imagePath = path.join(fixturesDir, filename);
+    if (!fs.existsSync(imagePath)) {
+        throw new Error(`Image fixture not found: ${filename}`);
+    }
+    const imageData = fs.readFileSync(imagePath);
+    return new Uint8Array(imageData);
+}
+/**
+ * Helper to read font file for tests
+ */
+function readFontFixture(filename) {
+    const fixturesDir = path.resolve(__dirname, '../../../fixtures');
+    const fontPath = path.join(fixturesDir, filename);
+    if (!fs.existsSync(fontPath)) {
+        throw new Error(`Font fixture not found: ${filename}`);
+    }
+    const fontData = fs.readFileSync(fontPath);
+    return new Uint8Array(fontData);
+}
+//# sourceMappingURL=test-helpers.js.map

package/dist/__tests__/e2e/test-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-helpers.js","sourceRoot":"","sources":["../../../src/__tests__/e2e/test-helpers.ts"],"names":[],"mappings":"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"}

package/dist/client-v1.d.ts

@@ -0,0 +1,169 @@
+/**
+ * PDFDancer TypeScript Client V1
+ *
+ * A TypeScript client that closely mirrors the Python Client class structure and functionality.
+ * Provides session-based PDF manipulation operations with strict validation.
+ */
+import { ObjectRef, Position, ObjectType, Font, Image, Paragraph } from './models';
+import { ParagraphBuilder } from './paragraph-builder';
+/**
+ * REST API client for interacting with the PDFDancer PDF manipulation service.
+ * This client provides a convenient TypeScript interface for performing PDF operations
+ * including session management, object searching, manipulation, and retrieval.
+ * Handles authentication, session lifecycle, and HTTP communication transparently.
+ *
+ * Mirrors the Python Client class functionality exactly.
+ */
+export declare class ClientV1 {
+    private _token;
+    private _baseUrl;
+    private _readTimeout;
+    private _pdfBytes;
+    private _sessionId;
+    /**
+     * Creates a new client with PDF data.
+     * This constructor initializes the client, uploads the PDF data to create
+     * a new session, and prepares the client for PDF manipulation operations.
+     */
+    constructor(token: string, pdfData: Uint8Array | File | ArrayBuffer, baseUrl?: string, readTimeout?: number);
+    /**
+     * Initialize the client by creating a session.
+     * Must be called after constructor before using the client.
+     */
+    init(): Promise<void>;
+    /**
+     * Process PDF data from various input types with strict validation.
+     * Equivalent to readFile() method in Python client.
+     */
+    private _processPdfData;
+    /**
+     * Extract meaningful error messages from API response.
+     * Parses JSON error responses with _embedded.errors structure.
+     */
+    private _extractErrorMessage;
+    /**
+     * Creates a new PDF processing session by uploading the PDF data.
+     * Equivalent to createSession() method in Python client.
+     */
+    private _createSession;
+    /**
+     * Make HTTP request with session headers and error handling.
+     * Equivalent to retrieve() method pattern in Python client.
+     */
+    private _makeRequest;
+    /**
+     * Searches for PDF objects matching the specified criteria.
+     * This method provides flexible search capabilities across all PDF content,
+     * allowing filtering by object type and position constraints.
+     */
+    find(objectType?: ObjectType, position?: Position): Promise<ObjectRef[]>;
+    /**
+     * Searches for paragraph objects at the specified position.
+     * Equivalent to findParagraphs() in Python client.
+     */
+    findParagraphs(position?: Position): Promise<ObjectRef[]>;
+    /**
+     * Searches for image objects at the specified position.
+     * Equivalent to findImages() in Python client.
+     */
+    findImages(position?: Position): Promise<ObjectRef[]>;
+    /**
+     * Searches for form field objects at the specified position.
+     * Equivalent to findForms() in Python client.
+     */
+    findForms(position?: Position): Promise<ObjectRef[]>;
+    /**
+     * Searches for vector path objects at the specified position.
+     * Equivalent to findPaths() in Python client.
+     */
+    findPaths(position?: Position): Promise<ObjectRef[]>;
+    /**
+     * Searches for text line objects at the specified position.
+     * Equivalent to findTextLines() in Python client.
+     */
+    findTextLines(position?: Position): Promise<ObjectRef[]>;
+    /**
+     * Retrieves references to all pages in the PDF document.
+     * Equivalent to getPages() in Python client.
+     */
+    getPages(): Promise<ObjectRef[]>;
+    /**
+     * Retrieves a reference to a specific page by its page index.
+     * Equivalent to getPage() in Python client.
+     */
+    getPage(pageIndex: number): Promise<ObjectRef | null>;
+    /**
+     * Deletes a page from the PDF document.
+     * Equivalent to deletePage() in Python client.
+     */
+    deletePage(pageRef: ObjectRef): Promise<boolean>;
+    /**
+     * Deletes the specified PDF object from the document.
+     * Equivalent to delete() in Python client.
+     */
+    delete(objectRef: ObjectRef): Promise<boolean>;
+    /**
+     * Moves a PDF object to a new position within the document.
+     * Equivalent to move() in Python client.
+     */
+    move(objectRef: ObjectRef, position: Position): Promise<boolean>;
+    /**
+     * Adds an image to the PDF document.
+     * Equivalent to addImage() methods in Python client.
+     */
+    addImage(image: Image, position?: Position): Promise<boolean>;
+    /**
+     * Adds a paragraph to the PDF document.
+     * Equivalent to addParagraph() in Python client with validation.
+     */
+    addParagraph(paragraph: Paragraph): Promise<boolean>;
+    /**
+     * Internal method to add any PDF object.
+     * Equivalent to addObject() in Python client.
+     */
+    private _addObject;
+    /**
+     * Modifies a paragraph object or its text content.
+     * Equivalent to modifyParagraph() methods in Python client.
+     */
+    modifyParagraph(objectRef: ObjectRef, newParagraph: Paragraph | string): Promise<boolean>;
+    /**
+     * Modifies a text line object.
+     * Equivalent to modifyTextLine() in Python client.
+     */
+    modifyTextLine(objectRef: ObjectRef, newText: string): Promise<boolean>;
+    /**
+     * Finds available fonts matching the specified name and size.
+     * Equivalent to findFonts() in Python client.
+     */
+    findFonts(fontName: string, fontSize: number): Promise<Font[]>;
+    /**
+     * Registers a custom font for use in PDF operations.
+     * Equivalent to registerFont() in Python client.
+     */
+    registerFont(ttfFile: Uint8Array | File): Promise<string>;
+    /**
+     * Downloads the current state of the PDF document with all modifications applied.
+     * Equivalent to getPDFFile() in Python client.
+     */
+    getPdfFile(): Promise<Uint8Array>;
+    /**
+     * Saves the current PDF to a file (browser environment).
+     * Downloads the PDF in the browser.
+     */
+    savePdf(filename?: string): Promise<void>;
+    /**
+     * Parse JSON object data into ObjectRef instance.
+     */
+    private _parseObjectRef;
+    /**
+     * Parse JSON position data into Position instance.
+     */
+    private _parsePosition;
+    /**
+     * Creates a new ParagraphBuilder for fluent paragraph construction.
+     * Equivalent to paragraphBuilder() in Python client.
+     */
+    paragraphBuilder(): ParagraphBuilder;
+}
+//# sourceMappingURL=client-v1.d.ts.map

package/dist/client-v1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-v1.d.ts","sourceRoot":"","sources":["../src/client-v1.ts"],"names":[],"mappings":"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"}