feat(api): implement OpenAPI/REST API for file conversions

- Add comprehensive REST API at /api/v1 with modular structure - Implement authentication endpoints (register, login, logout, me) - Add converter listing and format discovery endpoints - Create job management and file download endpoints - Add health check endpoint for monitoring - Set up CORS support for browser-based API clients - Create API middleware for JWT authentication - Add environment variables for API configuration - Include comprehensive API documentation and test script Infrastructure: - Enhanced CI/CD workflow for custom Docker registries - Docker Compose setup with dev, prod, and monitoring profiles - Claude.ai integration files for development workflow - Environment-based configuration with .env.development Known limitations: - JWT authentication context needs fixing (using ALLOW_UNAUTHENTICATED=true) - Swagger UI temporarily disabled due to composition error - File upload endpoint needs multipart/form-data support The API code is isolated in src/api/ directory to maintain separation from the existing codebase, making it easy to maintain or contribute back.
2025-07-30 14:18:13 -05:00 · 2025-07-30 14:18:13 -05:00 · 71b52f6c5e
commit 71b52f6c5e
parent 394c98c65a
27 changed files with 3150 additions and 2 deletions
--- a/.claude/build.md
+++ b/.claude/build.md
@ -0,0 +1,50 @@
+# Build and Test Docker Image
+
+Please build and test the Docker image with these steps:
+
+1. **Build the Docker image**:
+   ```bash
+   docker build -t convertx-openapi:local .
+   ```
+
+2. **Verify the build**:
+   - Check image size: `docker images convertx-openapi:local`
+   - Inspect layers: `docker history convertx-openapi:local`
+
+3. **Run container locally**:
+   ```bash
+   docker run -d \
+     --name convertx-test \
+     -p 3000:3000 \
+     -v $(pwd)/data:/app/data \
+     -e JWT_SECRET=test-secret \
+     -e NODE_ENV=production \
+     convertx-openapi:local
+   ```
+
+4. **Test the application**:
+   - Check logs: `docker logs convertx-test`
+   - Test health: `curl http://localhost:3000`
+   - Verify converters load properly
+
+5. **Multi-platform build** (if needed):
+   ```bash
+   docker buildx build \
+     --platform linux/amd64,linux/arm64 \
+     -t convertx-openapi:local \
+     .
+   ```
+
+6. **Push to custom registry** (if configured):
+   ```bash
+   docker tag convertx-openapi:local ${DOCKER_REGISTRY}/convertx:latest
+   docker push ${DOCKER_REGISTRY}/convertx:latest
+   ```
+
+7. **Cleanup**:
+   ```bash
+   docker stop convertx-test
+   docker rm convertx-test
+   ```
+
+Please execute these steps and report any issues.
--- a/.claude/commit.md
+++ b/.claude/commit.md
@ -0,0 +1,37 @@
+# Commit Changes
+
+Please create a git commit with the following requirements:
+
+1. **Review all changes**: First run `git status` and `git diff` to see what has changed
+2. **Stage appropriate files**: Use `git add` to stage the relevant changes
+3. **Commit message format**: Use conventional commit format:
+   - feat: New feature
+   - fix: Bug fix
+   - docs: Documentation changes
+   - style: Code style changes (formatting, etc)
+   - refactor: Code refactoring
+   - test: Adding or updating tests
+   - chore: Maintenance tasks
+   - build: Build system changes
+   - ci: CI/CD changes
+
+3. **Message structure**:
+   ```
+   <type>(<scope>): <subject>
+   
+   <body>
+   
+   <footer>
+   ```
+
+4. **Guidelines**:
+   - Subject line: 50 characters or less
+   - Use imperative mood ("add" not "added")
+   - Reference issues if applicable
+   - Explain the "why" in the body if needed
+
+5. **Run checks**: Before committing, ensure:
+   - `bun run typecheck` passes
+   - `bun run lint` passes (if available)
+
+Please analyze the changes and create an appropriate commit.
--- a/.claude/pr.md
+++ b/.claude/pr.md
@ -0,0 +1,52 @@
+# Create Pull Request
+
+Please create a pull request with the following steps:
+
+1. **Ensure branch is up to date**:
+   - Check current branch with `git branch --show-current`
+   - Pull latest changes from main/master
+   - Push current branch to remote
+
+2. **Create PR using GitHub CLI** (`gh pr create`) with:
+   - Clear, descriptive title
+   - Comprehensive description including:
+     - What changes were made
+     - Why these changes were necessary
+     - How to test the changes
+     - Any breaking changes or migration notes
+
+3. **PR Template**:
+   ```markdown
+   ## Summary
+   Brief description of what this PR does.
+
+   ## Changes
+   - List of specific changes made
+   - Organized by component/feature
+
+   ## Testing
+   - [ ] Unit tests pass
+   - [ ] Integration tests pass
+   - [ ] Manual testing completed
+   - [ ] Documentation updated
+
+   ## Screenshots
+   (If applicable)
+
+   ## Breaking Changes
+   - List any breaking changes
+   - Migration instructions if needed
+
+   ## Related Issues
+   Closes #XXX
+   ```
+
+4. **Labels to consider**:
+   - `enhancement`: New features
+   - `bug`: Bug fixes
+   - `documentation`: Doc updates
+   - `api`: API-related changes
+   - `docker`: Container changes
+   - `dependencies`: Dependency updates
+
+Please analyze the current branch changes and create an appropriate PR.
--- a/.claude/test.md
+++ b/.claude/test.md
@ -0,0 +1,45 @@
+# Run Tests and Checks
+
+Please run the following tests and checks for the ConvertX project:
+
+1. **Type Checking**:
+   ```bash
+   bun run typecheck
+   ```
+   Fix any TypeScript errors found
+
+2. **Linting**:
+   ```bash
+   bun run lint
+   ```
+   Fix any linting issues
+
+3. **Unit Tests** (if available):
+   ```bash
+   bun test
+   ```
+
+4. **Build Check**:
+   ```bash
+   bun run build
+   ```
+   Ensure the build completes successfully
+
+5. **API Tests** (when implemented):
+   - Test authentication endpoints
+   - Test file upload endpoints
+   - Test conversion endpoints
+   - Test error handling
+
+6. **Docker Build Test**:
+   ```bash
+   docker build -t convertx-test .
+   ```
+
+7. **Integration Test** (if safe to run):
+   - Start the application
+   - Upload a test file
+   - Convert it
+   - Verify the output
+
+Please run these checks and report any issues found. If there are failures, analyze and suggest fixes.