# 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