@arela/uploader 1.1.3 → 1.2.0

package/.claude/worktrees/agent-multi-profile/.env.template

@@ -0,0 +1,224 @@
+# Arela Uploader Environment Configuration
+# Copy this to your .env file and adjust values for your setup
+
+# =============================================================================
+# BASIC CONFIGURATION
+# =============================================================================
+
+# Arela API Configuration
+ARELA_API_URL=https://your-arela-api-url.com
+ARELA_API_TOKEN=your-api-token-here
+
+# API Agencia - Configura aquí la URL y Token de la agencia activa
+ARELA_API_AGENCIA_URL=https://agencia-api-example.com
+ARELA_API_AGENCIA_TOKEN=your-agencia-api-token-here
+
+# API Cliente - Configura aquí la URL y Token del cliente activo
+ARELA_API_CLIENTE_URL=https://cliente-api-example.com
+ARELA_API_CLIENTE_TOKEN=your-cliente-api-token-here
+
+
+# Supabase Configuration (fallback)
+SUPABASE_URL=https://your-supabase-url.supabase.co
+SUPABASE_KEY=your-supabase-key-here
+SUPABASE_BUCKET=your-bucket-name
+
+# Upload Sources (separate with |)
+UPLOAD_BASE_PATH=/path/to/your/upload/base
+UPLOAD_SOURCES=folder1|folder2|folder3
+UPLOAD_RFCS=rfc1|rfc2|rfc3
+
+# =============================================================================
+# SCAN CONFIGURATION (for arela scan command)
+# =============================================================================
+
+# Company identifier for this CLI instance (required)
+# Use a short, descriptive slug for your company/agency/client
+# Examples: "acme_corp", "cliente_123", "agencia_xyz"
+ARELA_COMPANY_SLUG=
+
+# Server identifier (required)
+# Use a unique ID for each server/NAS where arela-cli is installed
+# Examples: "nas01", "server-mx", "storage-01"
+ARELA_SERVER_ID=
+
+# Base path label (optional, auto-derived from UPLOAD_BASE_PATH if not set)
+# Short label describing the base path being scanned
+# Examples: "data", "documents", "archive"
+ARELA_BASE_PATH_LABEL=
+
+# System file patterns to exclude from scan (comma-separated)
+# These files will be filtered before uploading stats to reduce payload
+SCAN_EXCLUDE_PATTERNS=.DS_Store,Thumbs.db,desktop.ini,__pycache__,.pyc,.tmp,.swp,$RECYCLE.BIN,System Volume Information,~$*
+
+# Batch size for scan operations (default: 2000 records per API call)
+SCAN_BATCH_SIZE=2000
+
+# Directory depth level for creating separate tables (default: 0)
+# 0 = single table for entire base path
+# 1 = one table per first-level subdirectory
+# 2 = one table per second-level subdirectory, etc.
+# Example: with level=1 and base=/data, creates tables for /data/folder1, /data/folder2, etc.
+SCAN_DIRECTORY_LEVEL=0
+
+# =============================================================================
+# PUSH CONFIGURATION (for arela push command)
+# =============================================================================
+
+# Filter files to upload by RFC (pipe-separated, optional)
+# If not set, all files with arela_path will be uploaded
+# Examples: "RFC123456ABC|RFC789012DEF"
+PUSH_RFCS=
+
+# Filter files to upload by year (pipe-separated, optional)
+# If not set, all files with arela_path will be uploaded
+# Examples: "2023|2024|2025"
+PUSH_YEARS=
+
+# Batch size for fetching files from database (default: 100)
+PUSH_BATCH_SIZE=100
+
+# Concurrent upload batch size (default: 10)
+# Number of files to upload simultaneously
+PUSH_UPLOAD_BATCH_SIZE=10
+
+# Storage bucket for uploaded files (optional, defaults to SUPABASE_BUCKET)
+# Examples: "archivos", "documents", "storage"
+PUSH_BUCKET=arela
+
+# Folder structure prefix for uploaded files (optional)
+# This prefix is prepended to the arela_path when uploading files
+# Examples: "agencia/cliente", "2024/docs", "imports/batch1"
+PUSH_FOLDER_STRUCTURE=
+
+# =============================================================================
+# PERFORMANCE OPTIMIZATION FOR MULTIPLE API REPLICAS
+# =============================================================================
+
+# API Connection Configuration
+# Set this to match your number of API replicas (e.g., if you have 10 API instances, set to 10)
+MAX_API_CONNECTIONS=10
+
+# API Connection Timeout (milliseconds)
+API_CONNECTION_TIMEOUT=60000
+
+# API Retry Configuration
+# Maximum number of retry attempts for failed API requests
+API_MAX_RETRIES=3
+
+# Enable exponential backoff for retries (true/false)
+# When true, retry delays increase: 1s, 2s, 4s, 8s, 16s
+# When false, uses fixed delay (API_RETRY_DELAY)
+API_RETRY_EXPONENTIAL_BACKOFF=true
+
+# Fixed retry delay in milliseconds (only used if exponential backoff is disabled)
+API_RETRY_DELAY=1000
+
+# Batch Processing Configuration
+# Files processed concurrently per batch (should be >= MAX_API_CONNECTIONS for best performance)
+BATCH_SIZE=100
+
+# Delay between batches (0 for maximum speed)
+BATCH_DELAY=0
+
+# Source Processing Concurrency
+# Number of upload sources/folders to process simultaneously
+MAX_CONCURRENT_SOURCES=2
+
+# =============================================================================
+# EXAMPLE CONFIGURATIONS FOR DIFFERENT SCENARIOS
+# =============================================================================
+
+# For 10 API Replicas (High Performance Setup):
+# MAX_API_CONNECTIONS=10
+# BATCH_SIZE=100
+# MAX_CONCURRENT_SOURCES=3
+# BATCH_DELAY=0
+
+# For 5 API Replicas (Medium Performance Setup):
+# MAX_API_CONNECTIONS=5
+# BATCH_SIZE=50
+# MAX_CONCURRENT_SOURCES=2
+# BATCH_DELAY=0
+
+# For 1 API Instance (Single Instance Setup):
+# MAX_API_CONNECTIONS=5
+# BATCH_SIZE=20
+# MAX_CONCURRENT_SOURCES=1
+# BATCH_DELAY=100
+
+# =============================================================================
+# WATCH MODE CONFIGURATION
+# =============================================================================
+
+# Habilitar watch mode (true/false)
+WATCH_ENABLED=false
+
+# Configuración de directorios a observar (formato JSON)
+# Cada directorio puede tener su propia folderStructure para organizar en el bucket
+# Formato: {"ruta/directorio1":"estructura-1","ruta/directorio2":"estructura-2"}
+# 
+# IMPORTANTE: El folderStructure se usa en el comando:
+# upload --upload-by-rfc --folder-structure <estructura>
+# 
+# Ejemplo:
+WATCH_DIRECTORY_CONFIGS={"../../Documents/2022":"estructura-2022","../../Documents/2023":"estructura-2023"}
+
+# DEPRECATED: Configuración antigua (se mantiene para compatibilidad hacia atrás)
+# WATCH_DIRECTORIES=/ruta/carpeta1,/ruta/carpeta2
+
+# Estrategia de upload (opciones: individual|batch|full-structure)
+# - individual: Sube solo el archivo modificado más reciente
+# - batch: Sube un lote de N archivos recientes
+# - full-structure: Sube la estructura completa de carpetas
+WATCH_STRATEGY=batch
+
+# Debouncing en milisegundos (esperar entre eventos antes de procesar)
+WATCH_DEBOUNCE_MS=1000
+
+# Tamaño de batch para strategy batch
+WATCH_BATCH_SIZE=10
+
+# Usar polling en lugar de eventos nativos del filesystem
+# Útil para sistemas de archivos remotos o NFS
+WATCH_USE_POLLING=false
+
+# Interval de polling en milisegundos (solo si WATCH_USE_POLLING=true)
+WATCH_POLL_INTERVAL=100
+
+# Umbral de estabilidad en ms (esperar a que el archivo deje de cambiar)
+WATCH_STABILITY_THRESHOLD=300
+
+# Patrones a ignorar (separados por coma, se usan como regex)
+WATCH_IGNORE_PATTERNS=*.tmp,*.bak,*.swp
+
+# Detección automática de tipos de documento
+WATCH_AUTO_DETECT=false
+
+# Organización automática de archivos
+WATCH_AUTO_ORGANIZE=false
+
+# =============================================================================
+# WATCH MODE - AUTOMATIC PROCESSING PIPELINE
+# =============================================================================
+# 
+# El pipeline automático ejecuta la siguiente secuencia cuando se detecta un archivo nuevo:
+# 1. Stats Collection   → stats --stats-only (recopila información del archivo)
+# 2. PDF Detection      → detect --detect-pdfs (identifica pedimentos simplificados)
+# 3. Path Propagation   → detect --propagate-arela-path (propaga a documentos relacionados)
+# 4. RFC Upload         → upload --upload-by-rfc --folder-structure (sube con estructura)
+#
+# El pipeline se habilita automáticamente en watch mode y usa la folderStructure
+# definida para cada WATCH_DIRECTORY_CONFIGS
+#
+# Para deshabilitar en CLI, usa: arela watch --no-auto-processing
+
+# =============================================================================
+# LOGGING AND MONITORING
+# =============================================================================
+
+# Progress bar update frequency
+PROGRESS_UPDATE_INTERVAL=10
+
+# Enable verbose logging (true/false)
+VERBOSE_LOGGING=false

package/.claude/worktrees/agent-multi-profile/.prettierrc

@@ -0,0 +1,13 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "importOrder": ["^\\.\\./services/(.*)$", "^\\.\\./dto/(.*)$", "^[./]"],
+  "importOrderSeparation": true,
+  "importOrderSortSpecifiers": true,
+  "importOrderParserPlugins": [
+    "typescript",
+    "classProperties",
+    "decorators-legacy"
+  ],
+  "plugins": ["@trivago/prettier-plugin-sort-imports"]
+}

package/.claude/worktrees/agent-multi-profile/README.md

@@ -0,0 +1,405 @@
+# arela-uploader
+
+CLI tool to scan, detect, and upload files to the Arela API with multi-tenant support, automatic document detection, and directory watching.
+
+## Installation
+
+```bash
+npm install -g @arela/uploader
+```
+
+## Quick Start
+
+The recommended workflow runs 4 phases in sequence:
+
+```bash
+arela scan                # 1. Discover files and register metadata
+arela identify            # 2. Detect document types from PDF content
+arela propagate           # 3. Propagate paths to related files
+arela push                # 4. Upload files to storage
+```
+
+## Commands
+
+### `arela scan`
+
+Scan the filesystem and register file metadata via the API. Supports streaming discovery and multi-level directory partitioning.
+
+```bash
+arela scan                     # Basic scan
+arela scan --api agencia       # Scan using agencia API
+arela scan --count-first       # Count files first for progress %
+arela scan --no-stream         # Synchronous discovery (no streaming)
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--api <target>` | API target (`default`, `agencia`, `cliente`) | `default` |
+| `--count-first` | Count files before scanning for progress tracking | — |
+| `--no-stream` | Use synchronous file discovery | — |
+
+### `arela identify`
+
+Detect document types (e.g. pedimento simplificado) from PDF content using pattern matchers. Runs against existing database records.
+
+```bash
+arela identify                        # Identify documents
+arela identify --batch-size 200       # Larger batches
+arela identify --show-stats           # Show performance stats
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--api <target>` | API target | `default` |
+| `-b, --batch-size <size>` | Files per batch | `100` |
+| `--show-stats` | Show performance statistics | — |
+
+### `arela propagate`
+
+Propagate `arela_path` from identified pedimento records to related files in the same directory.
+
+```bash
+arela propagate                       # Propagate paths
+arela propagate --batch-size 100      # Process 100 pedimentos per batch
+arela propagate --show-stats          # Show statistics
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--api <target>` | API target | `default` |
+| `-b, --batch-size <size>` | Pedimentos per batch | `50` |
+| `--show-stats` | Show performance statistics | — |
+
+### `arela push`
+
+Upload files to Arela storage, filtered by RFC and/or year. Supports cross-tenant mode.
+
+```bash
+arela push                                          # Upload all files with arela_path
+arela push --rfcs RFC1,RFC2 --years 2023,2024       # Filter by RFC and year
+arela push --source-api agencia --target-api cliente # Cross-tenant upload
+arela push --folder-structure "prefix/path"          # Add storage path prefix
+arela push --no-auto-organize                        # Disable auto-organization
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--api <target>` | API target | `default` |
+| `--scan-api <target>` | API for reading scan data | `default` |
+| `--push-api <target>` | API for uploading files | — |
+| `--source-api <target>` | Source API (cross-tenant) | — |
+| `--target-api <target>` | Target API (cross-tenant) | — |
+| `-b, --batch-size <size>` | Files to fetch per batch | `100` |
+| `--upload-batch-size <size>` | Concurrent uploads | `10` |
+| `--rfcs <rfcs>` | Comma-separated RFCs (overrides `PUSH_RFCS`) | — |
+| `--years <years>` | Comma-separated years (overrides `PUSH_YEARS`) | — |
+| `--folder-structure <path>` | Storage path prefix | — |
+| `--no-auto-organize` | Disable automatic file organization | — |
+| `--show-stats` | Show performance statistics | — |
+
+### `arela upload`
+
+Legacy upload command with multiple modes (stats-only, RFC-based, run-all-phases).
+
+```bash
+arela upload --batch-size 10                        # Basic upload
+arela upload --upload-by-rfc                        # Upload by RFC
+arela upload --run-all-phases                       # Run all phases
+arela upload --force-supabase --prefix "folder"     # Direct Supabase upload
+arela upload --folder-structure "2024/pedimentos"   # Custom folder structure
+arela upload --auto-detect-structure                # Auto-detect year/pedimento from paths
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--api <target>` | API target | `default` |
+| `--source-api <target>` | Source API (cross-tenant) | — |
+| `--target-api <target>` | Target API (cross-tenant) | — |
+| `-b, --batch-size <size>` | Files per batch | `10` |
+| `-p, --prefix <prefix>` | Prefix for uploaded files | — |
+| `--folder-structure <structure>` | Custom folder structure | — |
+| `--client-path <path>` | Override client path for metadata | — |
+| `--auto-detect-structure` | Auto-detect folder structure from paths | — |
+| `--auto-detect` | Enable document type detection | — |
+| `--auto-organize` | Enable automatic file organization | — |
+| `--force-supabase` | Force direct Supabase upload (skip API) | — |
+| `--skip-processed` | Skip already-processed files | — |
+| `--show-stats` | Show performance statistics | — |
+| `--upload-by-rfc` | Upload based on RFC values from `UPLOAD_RFCS` | — |
+| `--run-all-phases` | Run all processing phases sequentially | — |
+
+### `arela watch`
+
+Monitor directories for file changes and process them automatically.
+
+```bash
+arela watch -d "/path/to/dir1,/path/to/dir2"       # Watch directories
+arela watch --api cliente                           # Watch with specific API
+arela watch --source-api agencia --target-api cliente  # Cross-tenant watch
+arela watch --strategy individual                   # Upload each file immediately
+arela watch --auto-processing --batch-size 10       # Auto pipeline (scan→identify→propagate→push)
+arela watch --dry-run                               # Simulate without uploading
+arela watch --poll 5000                             # Use polling (for NFS/remote FS)
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--api <target>` | API target | `default` |
+| `--source-api <target>` | Source API (cross-tenant) | — |
+| `--target-api <target>` | Target API (cross-tenant) | — |
+| `-d, --directories <paths>` | Comma-separated directories to watch | — |
+| `-s, --strategy <strategy>` | `batch`, `individual`, or `full-structure` | `batch` |
+| `--debounce <ms>` | Debounce delay in milliseconds | `1000` |
+| `-b, --batch-size <size>` | Files per batch | `10` |
+| `--poll <ms>` | Use polling with interval in ms | — |
+| `--ignore <patterns>` | Comma-separated patterns to ignore | — |
+| `--auto-detect` | Enable document type detection | — |
+| `--auto-organize` | Enable file organization | — |
+| `--auto-processing` | Enable automatic 4-step pipeline | — |
+| `--dry-run` | Simulate without uploading | — |
+| `--verbose` | Verbose logging | — |
+
+**Watch strategies:**
+- **`batch`** (default) — Groups files and uploads periodically
+- **`individual`** — Uploads each file immediately on change
+- **`full-structure`** — Preserves full directory structure during upload
+
+### `arela stats`
+
+Collect filesystem statistics without uploading (legacy, wraps upload in stats-only mode).
+
+```bash
+arela stats --batch-size 10
+```
+
+### `arela detect`
+
+Legacy document detection command. Prefer `arela identify` and `arela propagate` instead.
+
+```bash
+arela detect --batch-size 10                  # PDF detection
+arela detect --propagate-arela-path           # Path propagation
+```
+
+### `arela query`
+
+Query the database for file status.
+
+```bash
+arela query --ready-files     # Show files ready for upload
+```
+
+### `arela config`
+
+Display current configuration for all API targets and settings.
+
+```bash
+arela config
+```
+
+### `arela agent`
+
+Multi-profile polling agent: ONE process (one terminal) serves every tenant API,
+replacing the N `arela worker --poll` terminals (one per RFC×source folder with
+its own `.env`). Scan directories, tuning and scheduling live **server-side** in
+`pipeline_config`; the only local configuration is `profiles.json`.
+
+```bash
+arela agent                                  # uses ~/.arela/profiles.json
+arela agent --config ./profiles.json         # explicit config path
+arela agent --profile ktj,cem                # run a subset (debugging)
+arela agent --interval 10000                 # idle poll interval in ms
+```
+
+`~/.arela/profiles.json` (keep it private — it contains API keys):
+
+```jsonc
+{
+  "version": 1,
+  "serverId": "PALCO-01",                    // ONE id per machine; must match pipeline_config.serverId (or leave that null)
+  "pollIntervalMs": 5000,                    // optional
+  "logFile": "~/.arela/arela-agent.log",     // optional
+  "profiles": [
+    { "name": "ktj", "url": "https://ktj-api.example.com", "token": "ak_..." },
+    {
+      "name": "cem", "url": "https://cem-api.example.com", "token": "ak_...",
+      // Only for real cross-tenant jobs (sourceApi != targetApi):
+      "targets": { "agencia": { "baseUrl": "https://agencia-api.example.com", "token": "ak_..." } }
+    }
+  ]
+}
+```
+
+Behavior notes:
+
+- Jobs are processed **one at a time globally** (round-robin between profiles).
+  The config singleton and per-job env overrides make in-process parallelism
+  unsafe by design; if parallelism is ever needed, run child processes.
+- An unreachable tenant API backs off exponentially (30s → 10min) without
+  blocking the other profiles.
+- `Ctrl+C` waits for the in-flight job to finish before exiting, so jobs never
+  end up orphaned in RUNNING state.
+- While a long job runs, the OTHER profiles' `worker_status` may show OFFLINE
+  (no poll for >30s). Cosmetic: their jobs stay QUEUED and are picked up next.
+- Server-side setup per tenant: seed `pipeline_config` rows (one per RFC×source,
+  with `scanDirectories`, `extraOptions` tuning and schedule fields) and enable
+  the `PIPELINE_SCHEDULER` cronjob (`PUT /api/cronjobs`).
+
+### `arela agent init`
+
+Migration helper: reads the legacy per-folder `.env` files and generates
+`profiles.json` plus the `pipeline_config` seed payloads — locally, without
+calling any API (tokens never leave the machine).
+
+```bash
+arela agent init --from ../ktj-cli-maya ../ktj-cli-matro ../cem-cli-nas --server-id PALCO-01
+# Generates in ~/.arela/: profiles.json, seed-configs.json, seed-configs.sh
+```
+
+Folders pointing at the same tenant API collapse into one profile; each
+folder×RFC becomes a `pipeline_config` payload (`scheduleEnabled: false`
+initially). Review the generated files, run `bash ~/.arela/seed-configs.sh` to
+seed the server, then start `arela agent`. The old `.env` folders keep working
+during the migration — `arela worker --poll` is untouched.
+
+### Global Options
+
+| Flag | Description |
+|------|-------------|
+| `-v, --verbose` | Enable verbose logging |
+| `--clear-log` | Clear log file before starting |
+| `--version` | Display version number |
+| `-h, --help` | Display help |
+
+## Multi-Tenant API
+
+Three API targets are available: `default`, `agencia`, and `cliente`. Configure each in your `.env` file.
+
+```bash
+# Single-tenant
+arela scan --api cliente
+arela push --api agencia
+
+# Cross-tenant (read from one API, upload to another)
+arela push --source-api agencia --target-api cliente
+```
+
+| Phase | `--source-api` | `--target-api` |
+|-------|-----------------|-----------------|
+| Scan / Identify / Propagate | ✓ | — |
+| Push / Upload | — | ✓ |
+
+## Environment Variables
+
+Copy `.env.template` to `.env` and configure:
+
+### API Configuration
+
+```env
+ARELA_API_URL=https://your-arela-api.example.com
+ARELA_API_TOKEN=your-api-token
+
+ARELA_API_AGENCIA_URL=https://agencia-api.example.com
+ARELA_API_AGENCIA_TOKEN=your-agencia-token
+
+ARELA_API_CLIENTE_URL=https://cliente-api.example.com
+ARELA_API_CLIENTE_TOKEN=your-cliente-token
+```
+
+### Supabase (fallback)
+
+```env
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_KEY=your-supabase-key
+SUPABASE_BUCKET=your-bucket-name
+```
+
+### Upload & File Sources
+
+```env
+UPLOAD_BASE_PATH=/path/to/files
+UPLOAD_SOURCES=folder1|folder2|folder3
+UPLOAD_RFCS=RFC1|RFC2|RFC3
+UPLOAD_YEARS=2023|2024
+```
+
+### Scan Configuration
+
+```env
+ARELA_COMPANY_SLUG=your_company          # Company identifier
+ARELA_SERVER_ID=nas01                     # Server/NAS identifier
+ARELA_BASE_PATH_LABEL=                    # Optional (auto-derived from base path)
+SCAN_EXCLUDE_PATTERNS=.DS_Store,Thumbs.db,desktop.ini
+SCAN_BATCH_SIZE=2000                      # Records per API call
+SCAN_DIRECTORY_LEVEL=0                    # Directory depth for table partitioning
+```
+
+### Push Configuration
+
+```env
+PUSH_RFCS=                               # Pipe-separated RFC filter
+PUSH_YEARS=                              # Pipe-separated year filter
+PUSH_BATCH_SIZE=100                      # Fetch batch size
+PUSH_UPLOAD_BATCH_SIZE=10                # Concurrent uploads
+PUSH_BUCKET=arela                        # Storage bucket
+PUSH_FOLDER_STRUCTURE=                   # Prefix for storage paths
+```
+
+### Performance Tuning
+
+```env
+MAX_API_CONNECTIONS=10                   # Match your API replica count
+API_CONNECTION_TIMEOUT=60000             # Timeout in ms
+API_MAX_RETRIES=3
+API_RETRY_EXPONENTIAL_BACKOFF=true
+BATCH_SIZE=100
+BATCH_DELAY=0
+MAX_CONCURRENT_SOURCES=2
+```
+
+### Watch Mode
+
+```env
+WATCH_ENABLED=false
+WATCH_DIRECTORY_CONFIGS={"../docs/2023":"prefix-2023","../docs/2024":"prefix-2024"}
+WATCH_STRATEGY=batch                     # batch|individual|full-structure
+WATCH_DEBOUNCE_MS=1000
+WATCH_BATCH_SIZE=10
+WATCH_USE_POLLING=false
+WATCH_POLL_INTERVAL=100
+WATCH_STABILITY_THRESHOLD=300
+WATCH_IGNORE_PATTERNS=*.tmp,*.bak,*.swp
+```
+
+## Document Detection
+
+The tool detects and classifies documents:
+
+- **Pedimento Simplificado** — Extracts RFC, pedimento number, patente, aduana, and year from PDF content to compose an `arela_path` (`RFC/Year/Patente/Aduana/Pedimento/`)
+- **Supporting Documents** — XML, TXT, and JSON customs-related documents
+
+## File Sanitization
+
+Filenames are automatically sanitized before upload:
+
+| Original | Sanitized |
+|----------|-----------|
+| `Facturas Importación.pdf` | `Facturas-Importacion.pdf` |
+| `File{with}brackets.pdf` | `File-with-brackets.pdf` |
+| `Document ^& symbols.pdf` | `Document-and-symbols.pdf` |
+| `file with spaces.pdf` | `file-with-spaces.pdf` |
+
+Handles accented characters, Korean glyphs, special symbols, and email addresses.
+
+## Development
+
+```bash
+npm test                    # Run tests
+npm run test:watch          # Run tests in watch mode
+npm run test:coverage       # Run tests with coverage
+npm run format              # Format code with Prettier
+```
+
+## License
+
+ISC