Test Report: Unified Converter API

Generated: 2025-07-24 10:39 UTC
Status: Complete
Verified:

Executive Summary

All converter functions have been successfully integrated into the unified API. Unit tests are passing 100%, and the API is responding correctly with proper authentication requirements.

Test Results

Unit Tests (Jest)

Test Suites: 1 passed, 1 total
Tests:       8 passed, 8 total
Time:        3.117 s

Test Suite	Tests	Status	Time
Excel Converters	2	Pass	1.2s
PDF Converter	1	Pass	1.2s
Word Converters	2	Pass	<10ms
Utility Functions	3	Pass	<10ms

Integration Tests

Health endpoint: Working
Authentication: Properly enforced
Error handling: Structured errors returned
CORS: Enabled

API Endpoints

Base URL

Local: http://localhost:8080
Production: https://convert-api-qpg64cvnga-uk.a.run.app
Custom Domain: https://convert-to-markdown.knowcode.tech (after DNS propagation)

Available Endpoints

Method	Path	Description
GET	`/v1/health`	Health check (no auth)
GET	`/v1`	List endpoints (no auth)
POST	`/v1/convert/excel-to-json`	Convert Excel to JSON
POST	`/v1/convert/excel-to-markdown`	Convert Excel to Markdown
POST	`/v1/convert/pdf-to-markdown`	Convert PDF to Markdown
POST	`/v1/convert/word-to-html`	Convert Word to HTML
POST	`/v1/convert/word-to-markdown`	Convert Word to Markdown

Curl Command Examples

1. Health Check (No Authentication)

curl http://localhost:8080/v1/health

2. List Available Endpoints

curl http://localhost:8080/v1

3. Convert Excel to JSON (Requires API Key)

# With X-API-Key header
curl -X POST \
  -H "X-API-Key: your-api-key-here" \
  -F "file=@test-documents/CJK ABC Analysis TSAT V3 with OP labels.xlsm" \
  http://localhost:8080/v1/convert/excel-to-json

# With Bearer token
curl -X POST \
  -H "Authorization: Bearer your-api-key-here" \
  -F "file=@test-documents/CJK ABC Analysis TSAT V3 with OP labels.xlsm" \
  http://localhost:8080/v1/convert/excel-to-json

4. Convert Excel to Markdown

curl -X POST \
  -H "X-API-Key: your-api-key-here" \
  -F "file=@test-documents/CJK ABC Analysis TSAT V3 with OP labels.xlsm" \
  http://localhost:8080/v1/convert/excel-to-markdown

5. Convert PDF to Markdown

curl -X POST \
  -H "X-API-Key: your-api-key-here" \
  -F "file=@test-documents/SaaS_AssessmentQuestionnaire.pdf" \
  http://localhost:8080/v1/convert/pdf-to-markdown

6. Convert Word to HTML

curl -X POST \
  -H "X-API-Key: your-api-key-here" \
  -F "file=@your-document.docx" \
  http://localhost:8080/v1/convert/word-to-html

7. Convert Word to Markdown

curl -X POST \
  -H "X-API-Key: your-api-key-here" \
  -F "file=@your-document.docx" \
  http://localhost:8080/v1/convert/word-to-markdown

8. Test Error Handling (No API Key)

curl -X POST \
  -F "file=@test.pdf" \
  http://localhost:8080/v1/convert/pdf-to-markdown

Expected response:

{
  "error": {
    "code": "AUTH_001",
    "message": "API key is required",
    "details": {
      "headers": ["X-API-Key", "Authorization"],
      "example": "X-API-Key: your-api-key-here"
    },
    "timestamp": "2025-07-24T10:38:23.614Z"
  },
  "help": "Include your API key in X-API-Key header or Authorization: Bearer {key}",
  "documentation": "https://convert-to-markdown.knowcode.tech/docs/errors#AUTH_001",
  "support": "lindsay@knowcode.tech"
}

9. Pretty Print JSON Response

curl -s -X POST \
  -H "X-API-Key: your-api-key-here" \
  -F "file=@test.xlsx" \
  http://localhost:8080/v1/convert/excel-to-json | jq '.'

10. Save Output to File

# Save markdown output
curl -X POST \
  -H "X-API-Key: your-api-key-here" \
  -F "file=@test.pdf" \
  http://localhost:8080/v1/convert/pdf-to-markdown \
  | jq -r '.document' > output.md

# Save JSON output
curl -X POST \
  -H "X-API-Key: your-api-key-here" \
  -F "file=@test.xlsx" \
  http://localhost:8080/v1/convert/excel-to-json \
  | jq '.content' > output.json

Production Testing

Health Check (Production)

curl https://convert-api-qpg64cvnga-uk.a.run.app/v1/health

Convert with Production API

curl -X POST \
  -H "X-API-Key: your-production-api-key" \
  -F "file=@document.pdf" \
  https://convert-api-qpg64cvnga-uk.a.run.app/v1/convert/pdf-to-markdown

Response Format Examples

Success Response (Excel to JSON)

{
  "content": "{\"Sheet1\": [{\"Name\": \"John\", \"Age\": 30}]}",
  "statistics": {
    "fileName": "test.xlsx",
    "fileSize": {
      "bytes": 1024679,
      "KB": "1000.66",
      "MB": "0.98"
    },
    "sheets": [...],
    "totalSheets": 14,
    "estimatedTokens": 319230
  }
}

Success Response (PDF to Markdown)

{
  "document": "---\ntitle: Document Title\n...",
  "stats": {
    "sizeInBytes": 61183,
    "numberOfPages": 27,
    "estimatedTokens": 12456,
    "pdfInfo": {...}
  }
}

Performance Benchmarks

Converter	File Size	Processing Time	Memory Usage
Excel to JSON	1MB	~650ms	Low
Excel to Markdown	1MB	~465ms	Low
PDF to Markdown	271KB	~408ms	Medium
Word to HTML	Varies	<1s	Low
Word to Markdown	Varies	<1s	Low

Troubleshooting

Common Issues

401 Unauthorized
- Ensure API key is included in headers
- Check API key is active in Firestore
413 File Too Large
- Maximum file size is 10MB
- Compress or split large files
400 Invalid File Type
- Check file extension matches converter
- Ensure MIME type is correct
500 Internal Server Error
- Check server logs for details
- Verify file is not corrupted

Next Steps

Get API Key: Contact lindsay@knowcode.tech
Test with your files: Use the curl commands above
Monitor usage: Check /v1/usage/current endpoint
Review documentation: https://convert-to-markdown.knowcode.tech/docs

Notes

All endpoints require authentication except health and root
File uploads use multipart/form-data
Responses are JSON formatted
Token estimation helps with LLM context planning
Statistics provide insights into document complexity