Added new feature for document export, including API contracts, data model, implementation plan, and tests. Updated related configurations and instructions.

2026-03-10 16:25:09 -05:00
parent 2acb04ad76
commit bf6f2eebd6
22 changed files with 2856 additions and 64 deletions
--- a/specs/002-document-export/contracts/documents-export-api.md
+++ b/specs/002-document-export/contracts/documents-export-api.md
@@ -0,0 +1,113 @@
+# API Contract: Document Export Endpoint
+
+**Feature**: 002-document-export  
+**Version**: 1.0  
+**Date**: 2026-03-09  
+**Base URL**: `http://localhost:3000` (configurable via config/default.json)
+
+## Overview
+
+HTTP endpoint for exporting Google Drive documents in multiple formats. Fetches document metadata, selects optimal export format, and streams content with appropriate headers.
+
+---
+
+## Endpoint
+
+### Export Document
+
+```
+GET /documents/:documentId
+```
+
+Exports a single Google Drive document in the best available format (Markdown > HTML > PDF). For native PDF files, streams content directly.
+
+---
+
+## Request
+
+### Path Parameters
+
+| Parameter | Type | Required | Description | Example |
+|-----------|------|----------|-------------|---------|
+| `documentId` | string | Yes | Google Drive file ID | `1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms` |
+
+### Headers
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| `Authorization` | Yes (implicit) | Google OAuth2 access token (handled by proxy auth layer) |
+
+### Example Request
+
+```http
+GET /documents/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms HTTP/1.1
+Host: localhost:3000
+```
+
+---
+
+## Response
+
+### Success Responses
+
+#### 200 OK - Document Exported
+
+**Headers**:
+```http
+Content-Type: text/x-markdown | text/html | application/pdf
+Content-Disposition: inline; filename="[document-name].[extension]"
+```
+
+**Body**: Binary stream of document content
+
+**Format Selection**:
+- Markdown (text/x-markdown, .md): Preferred if available
+- HTML (text/html, .html): Fallback if Markdown unavailable
+- PDF (application/pdf, .pdf): Final fallback or native PDF files
+
+---
+
+### Error Responses
+
+| Status Code | Message | Condition |
+|-------------|---------|-----------|
+| 401 | Unauthorized | User lacks permissions or auth failed |
+| 403 | mimetype not supported | Document type not supported |
+| 404 | Document not found | Invalid/non-existent document ID |
+| 413 | Payload Too Large | Document exceeds 10MB |
+| 500 | Export failed - unable to retrieve document content | Export link malformed/inaccessible |
+| 502 | Bad Gateway - Google Drive API unavailable | Google Drive API error |
+| 504 | Gateway Timeout | Operation exceeded 30 seconds |
+
+---
+
+## Behavior Specifications
+
+### Format Selection Algorithm
+
+1. Fetch document metadata from Google Drive API
+2. Check if `exportLinks` exists:
+   - If yes: Select first available from [Markdown, HTML, PDF]
+   - If no and mimeType=PDF: Stream native PDF
+   - Otherwise: Return 403
+
+### Timeouts & Limits
+
+- **Timeout**: 30 seconds per request
+- **Size Limit**: 10MB (10,485,760 bytes)
+- **Streaming**: Content never buffered, piped directly
+
+---
+
+## Testing Contract
+
+### Required Tests
+
+1. **200**: Valid document returns content with correct headers
+2. **401**: Invalid token returns Unauthorized
+3. **403**: Unsupported mimetype returns error
+4. **404**: Invalid ID returns Document not found
+5. **413**: Document >10MB returns Payload Too Large
+6. **504**: Timeout >30s returns Gateway Timeout
+7. **Headers**: Content-Type and Content-Disposition correct
+8. **Streaming**: Large files stream without buffering