pdfdancer-client-typescript 1.0.1

package/example.ts

@@ -0,0 +1,103 @@
+/**
+ * Example usage of the PDFDancer TypeScript client
+ */
+
+import {
+  ClientV1,
+  Position,
+  Color,
+  Font,
+  ValidationException,
+  HttpClientException
+} from './src/index';
+
+async function exampleUsage() {
+  try {
+    // Create a sample PDF data (in a real application, this would be loaded from a file)
+    const pdfData = new Uint8Array([
+      0x25, 0x50, 0x44, 0x46, // %PDF header
+      // ... rest of PDF data would go here
+    ]);
+
+    // Initialize the client with authentication token and PDF data
+    const client = new ClientV1('your-auth-token', pdfData, 'http://localhost:8080');
+
+    // Initialize the session (must be called before using the client)
+    await client.init();
+
+    // Example 1: Find all paragraphs on page 1
+    const page1Position = Position.fromPageIndex(1);
+    const paragraphs = await client.findParagraphs(page1Position);
+    console.log(`Found ${paragraphs.length} paragraphs on page 1`);
+
+    // Example 2: Add a new paragraph using the builder pattern
+    const newParagraph = client.paragraphBuilder()
+      .fromString('Hello, PDFDancer!', new Color(255, 0, 0)) // Red text
+      .withFont(new Font('Arial', 12))
+      .withPosition(Position.onPageCoordinates(1, 100, 200))
+      .withLineSpacing(1.5)
+      .build();
+
+    await client.addParagraph(newParagraph);
+    console.log('Added new paragraph successfully');
+
+    // Example 3: Find and modify existing text
+    const textLines = await client.findTextLines(page1Position);
+    if (textLines.length > 0) {
+      await client.modifyTextLine(textLines[0], 'Modified text content');
+      console.log('Modified first text line');
+    }
+
+    // Example 4: Get the modified PDF
+    const modifiedPdf = await client.getPdfFile();
+    console.log(`Generated PDF size: ${modifiedPdf.length} bytes`);
+
+    // Example 5: Save PDF (in browser environment)
+    // await client.savePdf('modified-document.pdf');
+
+  } catch (error) {
+    if (error instanceof ValidationException) {
+      console.error('Validation error:', error.message);
+    } else if (error instanceof HttpClientException) {
+      console.error('HTTP error:', error.message, 'Status:', error.statusCode);
+    } else {
+      console.error('Unexpected error:', error);
+    }
+  }
+}
+
+// Example of using with custom font
+async function exampleWithCustomFont() {
+  try {
+    const pdfData = new Uint8Array([0x25, 0x50, 0x44, 0x46]);
+    const client = new ClientV1('your-auth-token', pdfData);
+    await client.init();
+
+    // Register a custom font (example with dummy TTF data)
+    const customFontData = new Uint8Array([/* TTF font data here */]);
+    const fontName = await client.registerFont(customFontData);
+    console.log(`Registered font: ${fontName}`);
+
+    // Use the custom font in a paragraph
+    const paragraph = client.paragraphBuilder()
+      .fromString('Text with custom font')
+      .withFont(new Font(fontName, 14))
+      .withPosition(Position.onPageCoordinates(1, 50, 300))
+      .build();
+
+    await client.addParagraph(paragraph);
+    console.log('Added paragraph with custom font');
+
+  } catch (error) {
+    console.error('Error with custom font:', error);
+  }
+}
+
+// Note: These examples show the API usage patterns.
+// In a real application, you would need:
+// 1. A valid authentication token
+// 2. Actual PDF data
+// 3. A running PDFDancer server at the specified URL
+// 4. Proper error handling for your use case
+
+export { exampleUsage, exampleWithCustomFont };

package/fixtures/README.md

@@ -0,0 +1,25 @@
+# Test Fixtures
+
+This directory contains test fixtures used by the e2e tests.
+
+For the e2e tests to run, you need to place the following files here:
+
+- `ObviouslyAwesome.pdf` - Main test PDF document
+- `mixed-form-types.pdf` - PDF with form fields for form tests
+- `basic-paths.pdf` - PDF with vector paths for path tests
+- `logo-80.png` - Small PNG image for image tests
+- `DancingScript-Regular.ttf` - TTF font file for custom font tests
+
+These files should match the fixtures used by the Python client tests.
+
+The e2e tests will be skipped if these files are not present or if the required environment variables are not set:
+
+- `PDFDANCER_TOKEN` - Authentication token for the PDFDancer API
+- `PDFDANCER_BASE_URL` - Optional: URL of the PDFDancer server (defaults to http://localhost:8080)
+
+## Running E2E Tests
+
+1. Start the PDFDancer server
+2. Set the required environment variables
+3. Place the fixture files in this directory
+4. Run: `npm test -- --testPathPattern=e2e`

package/jest.config.js

@@ -0,0 +1,26 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/__tests__/**/*.ts', '**/?(*.)+(spec|test).ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/**/*test-helpers.ts',
+  ],
+  projects: [
+    {
+      preset: 'ts-jest',
+      testEnvironment: 'node',
+      displayName: 'unit',
+      testMatch: ['<rootDir>/src/**/*.test.ts'],
+      testPathIgnorePatterns: ['<rootDir>/src/__tests__/e2e/'],
+    },
+    {
+      preset: 'ts-jest',
+      testEnvironment: 'node',
+      displayName: 'e2e',
+      testMatch: ['<rootDir>/src/__tests__/e2e/**/*.test.ts'],
+    }
+  ]
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "pdfdancer-client-typescript",
+  "version": "1.0.1",
+  "description": "A TypeScript client library for the PDFDancer PDF manipulation API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:unit": "jest --selectProjects unit",
+    "test:e2e": "jest --selectProjects e2e",
+    "test:watch": "jest --watch",
+    "lint": "eslint src/**/*.ts",
+    "prepublishOnly": "npm run build",
+    "release": "node scripts/release.js",
+    "release:skip-tests": "node scripts/release.js --skip-tests",
+    "release:test": "node scripts/test-release.js"
+  },
+  "keywords": [
+    "pdf",
+    "manipulation",
+    "typescript",
+    "client"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {}
+}

package/scripts/release.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const packageJsonPath = path.join(__dirname, '..', 'package.json');
+
+function run(command, description) {
+  console.log(`\n🔧 ${description}...`);
+  try {
+    execSync(command, { stdio: 'inherit' });
+    console.log(`✅ ${description} completed`);
+  } catch (error) {
+    console.error(`❌ ${description} failed`);
+    process.exit(1);
+  }
+}
+
+function getCurrentVersion() {
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  return packageJson.version;
+}
+
+function bumpVersion() {
+  console.log('\n📦 Bumping version...');
+  const currentVersion = getCurrentVersion();
+  console.log(`Current version: ${currentVersion}`);
+
+  execSync('npm version patch', { stdio: 'inherit' });
+
+  const newVersion = getCurrentVersion();
+  console.log(`New version: ${newVersion}`);
+  return newVersion;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const skipTests = args.includes('--skip-tests');
+
+  console.log('🚀 Starting release process...\n');
+
+  // Ensure we're on a clean working directory
+  try {
+    execSync('git diff-index --quiet HEAD --', { stdio: 'pipe' });
+  } catch (error) {
+    console.error('❌ Working directory is not clean. Please commit or stash your changes.');
+    process.exit(1);
+  }
+
+  // Run tests (unless skipped)
+  if (!skipTests) {
+    run('npm run test:unit', 'Running unit tests');
+  } else {
+    console.log('⚠️  Skipping tests as requested');
+  }
+
+  // Run linting
+  run('npm run lint', 'Running linter');
+
+  // Build the project
+  run('npm run build', 'Building project');
+
+  // Get current version for confirmation
+  const currentVersion = getCurrentVersion();
+  console.log(`\n📋 About to release version ${currentVersion}`);
+  console.log('This will:');
+  console.log('  1. Publish to npm');
+  console.log('  2. Bump the version number');
+  console.log('  3. Create a git tag');
+  console.log('  4. Push changes to git');
+
+  // Publish to npm
+  run('npm publish', 'Publishing to npm');
+
+  // Bump version and create git tag
+  const newVersion = bumpVersion();
+
+  // Push changes and tags to git
+  run('git push', 'Pushing changes to git');
+  run('git push --tags', 'Pushing tags to git');
+
+  console.log(`\n🎉 Release ${newVersion} completed successfully!`);
+  console.log(`Package is now available at: https://www.npmjs.com/package/pdfdancer-client-typescript`);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { main };

package/scripts/test-release.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const packageJsonPath = path.join(__dirname, '..', 'package.json');
+
+function run(command, description) {
+  console.log(`\n🔧 ${description}...`);
+  try {
+    execSync(command, { stdio: 'inherit' });
+    console.log(`✅ ${description} completed`);
+  } catch (error) {
+    console.error(`❌ ${description} failed`);
+    process.exit(1);
+  }
+}
+
+function getCurrentVersion() {
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  return packageJson.version;
+}
+
+function main() {
+  console.log('🧪 Testing release process (dry run)...\n');
+
+  // Check working directory status
+  try {
+    execSync('git diff-index --quiet HEAD --', { stdio: 'pipe' });
+    console.log('✅ Working directory is clean');
+  } catch (error) {
+    console.log('⚠️  Working directory has changes (this would block real release)');
+  }
+
+  // Run unit tests only (e2e tests have external dependencies)
+  run('npm run test:unit', 'Running unit tests');
+
+  // Run linting
+  run('npm run lint', 'Running linter');
+
+  // Build the project
+  run('npm run build', 'Building project');
+
+  // Simulate version check
+  const currentVersion = getCurrentVersion();
+  console.log(`\n📋 Current version: ${currentVersion}`);
+  console.log('✅ Release script validation complete');
+
+  console.log('\n🎯 To run actual release:');
+  console.log('  npm run release');
+  console.log('\nNote: Make sure working directory is clean before running actual release');
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { main };

package/src/__tests__/client-v1.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Basic tests for the PDFDancer TypeScript client.
+ */
+
+import { ClientV1 } from '../client-v1';
+import { ValidationException } from '../exceptions';
+import { Position, Color, Font, Paragraph } from '../models';
+
+describe('ClientV1', () => {
+  const mockToken = 'test-token';
+  const mockPdfData = new Uint8Array([0x25, 0x50, 0x44, 0x46]); // %PDF header
+
+  describe('constructor validation', () => {
+    test('should throw ValidationException for empty token', () => {
+      expect(() => {
+        new ClientV1('', mockPdfData);
+      }).toThrow(ValidationException);
+    });
+
+    test('should throw ValidationException for null PDF data', () => {
+      expect(() => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        new ClientV1(mockToken, (null as any));
+      }).toThrow(ValidationException);
+    });
+
+    test('should throw ValidationException for empty PDF data', () => {
+      expect(() => {
+        new ClientV1(mockToken, new Uint8Array(0));
+      }).toThrow(ValidationException);
+    });
+
+    test('should accept valid parameters', () => {
+      expect(() => {
+        new ClientV1(mockToken, mockPdfData);
+      }).not.toThrow();
+    });
+  });
+
+  describe('paragraphBuilder', () => {
+    test('should create a ParagraphBuilder instance', () => {
+      const client = new ClientV1(mockToken, mockPdfData);
+      const builder = client.paragraphBuilder();
+      expect(builder).toBeDefined();
+    });
+  });
+});
+
+describe('Position', () => {
+  test('should create position from page index', () => {
+    const position = Position.fromPageIndex(1);
+    expect(position.pageIndex).toBe(1);
+  });
+
+  test('should create position with coordinates', () => {
+    const position = Position.onPageCoordinates(1, 100, 200);
+    expect(position.pageIndex).toBe(1);
+    expect(position.getX()).toBe(100);
+    expect(position.getY()).toBe(200);
+  });
+
+  test('should move position', () => {
+    const position = Position.onPageCoordinates(1, 100, 200);
+    position.moveX(50).moveY(30);
+    expect(position.getX()).toBe(150);
+    expect(position.getY()).toBe(230);
+  });
+});
+
+describe('Color', () => {
+  test('should create valid color', () => {
+    const color = new Color(255, 128, 0, 200);
+    expect(color.r).toBe(255);
+    expect(color.g).toBe(128);
+    expect(color.b).toBe(0);
+    expect(color.a).toBe(200);
+  });
+
+  test('should throw error for invalid color values', () => {
+    expect(() => new Color(256, 0, 0)).toThrow();
+    expect(() => new Color(0, -1, 0)).toThrow();
+  });
+});
+
+describe('Font', () => {
+  test('should create valid font', () => {
+    const font = new Font('Arial', 12);
+    expect(font.name).toBe('Arial');
+    expect(font.size).toBe(12);
+  });
+
+  test('should throw error for invalid font size', () => {
+    expect(() => new Font('Arial', 0)).toThrow();
+    expect(() => new Font('Arial', -5)).toThrow();
+  });
+});
+
+describe('Paragraph', () => {
+  test('should create paragraph with position', () => {
+    const position = Position.fromPageIndex(1);
+    const paragraph = new Paragraph(position);
+    expect(paragraph.getPosition()).toBe(position);
+  });
+
+  test('should set position', () => {
+    const paragraph = new Paragraph();
+    const position = Position.fromPageIndex(2);
+    paragraph.setPosition(position);
+    expect(paragraph.getPosition()).toBe(position);
+  });
+});

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

@@ -0,0 +1,51 @@
+/**
+ * E2E tests for form operations
+ */
+
+import * as fs from 'fs';
+import { ClientV1, Position, ObjectType } from '../../index';
+import { requireEnvAndFixture, createTempPath } from './test-helpers';
+
+describe('Form E2E Tests', () => {
+  // Tests should fail properly if environment is not configured
+
+  test('delete forms', async () => {
+    const [baseUrl, token, pdfData] = await requireEnvAndFixture('mixed-form-types.pdf');
+    const client = new ClientV1(token, pdfData, baseUrl, 30000);
+    await client.init();
+
+    const forms = await client.findForms();
+    expect(forms).toHaveLength(79);
+    expect(forms[0].type).toBe(ObjectType.FORM);
+
+    // Delete all forms
+    for (const f of forms) {
+      expect(await client.delete(f)).toBe(true);
+    }
+
+    expect(await client.findForms()).toHaveLength(0);
+
+    // Save PDF to verify operation
+    const outPath = createTempPath('forms-after-delete.pdf');
+    const outputPdfData = await client.getPdfFile();
+    fs.writeFileSync(outPath, outputPdfData);
+    expect(fs.existsSync(outPath)).toBe(true);
+    expect(fs.statSync(outPath).size).toBeGreaterThan(0);
+
+    // Cleanup
+    fs.unlinkSync(outPath);
+  });
+
+  test('find form by position', async () => {
+    const [baseUrl, token, pdfData] = await requireEnvAndFixture('mixed-form-types.pdf');
+    const client = new ClientV1(token, pdfData, baseUrl, 30000);
+    await client.init();
+
+    let forms = await client.findForms(Position.onPageCoordinates(0, 0, 0));
+    expect(forms).toHaveLength(0);
+
+    forms = await client.findForms(Position.onPageCoordinates(0, 17, 447));
+    expect(forms).toHaveLength(1);
+    expect(forms[0].internalId).toBe('FORM_000001');
+  });
+});

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

@@ -0,0 +1,108 @@
+/**
+ * E2E tests for image operations
+ */
+
+import * as fs from 'fs';
+import { ClientV1, Position, ObjectType, Image } from '../../index';
+import { requireEnvAndFixture, createTempPath, readImageFixture } from './test-helpers';
+
+describe('Image E2E Tests', () => {
+  // Tests should fail properly if environment is not configured
+
+  test('find images', async () => {
+    const [baseUrl, token, pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+    const client = new ClientV1(token, pdfData, baseUrl, 30000);
+    await client.init();
+
+    const images = await client.findImages();
+    expect(images).toHaveLength(3);
+    expect(images[0].type).toBe(ObjectType.IMAGE);
+
+    const imagesPage0 = await client.findImages(Position.fromPageIndex(0));
+    expect(imagesPage0).toHaveLength(2);
+  });
+
+  test('delete images', async () => {
+    const [baseUrl, token, pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+    const client = new ClientV1(token, pdfData, baseUrl, 30000);
+    await client.init();
+
+    const images = await client.findImages();
+    for (const obj of images) {
+      expect(await client.delete(obj)).toBe(true);
+    }
+    expect(await client.findImages()).toHaveLength(0);
+
+    // Save PDF to verify operation
+    const outPath = createTempPath('deleteImage.pdf');
+    const outputPdfData = await client.getPdfFile();
+    fs.writeFileSync(outPath, outputPdfData);
+    expect(fs.existsSync(outPath)).toBe(true);
+    expect(fs.statSync(outPath).size).toBeGreaterThan(0);
+
+    // Cleanup
+    fs.unlinkSync(outPath);
+  });
+
+  test('move image', async () => {
+    const [baseUrl, token, pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+    const client = new ClientV1(token, pdfData, baseUrl, 30000);
+    await client.init();
+
+    let images = await client.findImages();
+    const imageRef = images[2];
+    const position = imageRef.position;
+    expect(position.boundingRect?.x).toBeCloseTo(54, 0.5);
+    expect(position.boundingRect?.y).toBeCloseTo(300, 1);
+
+    expect(await client.move(imageRef, Position.onPageCoordinates(11, 50.1, 100.0))).toBe(true);
+
+    images = await client.findImages();
+    const movedImageRef = images[2];
+    const newPosition = movedImageRef.position;
+    expect(newPosition.boundingRect?.x).toBeCloseTo(50.1, 0.05);
+    expect(newPosition.boundingRect?.y).toBeCloseTo(100.0, 0.05);
+  });
+
+  test('find image by position', async () => {
+    const [baseUrl, token, pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+    const client = new ClientV1(token, pdfData, baseUrl, 30000);
+    await client.init();
+
+    let images = await client.findImages(Position.onPageCoordinates(11, 0, 0));
+    expect(images).toHaveLength(0);
+
+    images = await client.findImages(Position.onPageCoordinates(11, 55, 310));
+    expect(images).toHaveLength(1);
+    expect(images[0].internalId).toBe('IMAGE_000003');
+  });
+
+  test('add image', async () => {
+    const [baseUrl, token, pdfData] = await requireEnvAndFixture('ObviouslyAwesome.pdf');
+    const client = new ClientV1(token, pdfData, baseUrl, 30000);
+    await client.init();
+
+    let images = await client.findImages();
+    expect(images).toHaveLength(3);
+
+    // Prepare image data
+    const imageData = readImageFixture('logo-80.png');
+    const image = new Image();
+    image.data = imageData;
+    const pos = Position.onPageCoordinates(6, 50.1, 98.0);
+
+    expect(await client.addImage(image, pos)).toBe(true);
+
+    images = await client.findImages();
+    expect(images).toHaveLength(4);
+
+    const imagesPage6 = await client.findImages(Position.fromPageIndex(6));
+    expect(imagesPage6).toHaveLength(1);
+
+    const newImage = imagesPage6[0];
+    expect(newImage.position.pageIndex).toBe(6);
+    expect(newImage.internalId).toBe('IMAGE_000003');
+    expect(newImage.position.boundingRect?.x).toBeCloseTo(50.1, 0.05);
+    expect(newImage.position.boundingRect?.y).toBeCloseTo(98.0, 0.05);
+  });
+});