# NOMAZRA API Endpoints — PDF Export & TTS
Base URL: `https://nomazra.kelthos.com/api/nomazra/`

All endpoints require `Authorization: Bearer <access_token>`

---

## POST /export/pdf/{message_id}/
Export an AI response as a formatted PDF document.

**Path Parameters:**
- `message_id` (required): UUID of the AI message to export

**Request Body (optional):**
```json
{
  "include_question": true,
  "include_timestamp": true,
  "include_disclaimer": true,
  "title": "Legal Opinion - Land Dispute"
}
```

**What happens:**
1. Fetches the AI message (must be role=assistant, owned by user)
2. Optionally fetches the preceding user message (question)
3. Generates PDF with:
   - NOMAZRA header/logo
   - Title (custom or auto-generated)
   - Question (if included)
   - AI response formatted with proper paragraphs
   - Timestamp
   - Legal disclaimer
   - Footer with "Generated by NOMAZRA AI Legal Assistant"
4. PDF uploaded to R2 under `nomazra/{user_id}/documents/`
5. Returns PDF URL + binary download

**Response 200:**
```
Content-Type: application/pdf
Content-Disposition: attachment; filename="nomazra_legal_opinion_2025-01-20.pdf"
```

Binary PDF content.

**Alternative JSON response (if `?format=json`):**
```json
{
  "pdf_url": "https://r2-url/nomazra/user-uuid/documents/export_abc123.pdf",
  "filename": "nomazra_legal_opinion_2025-01-20.pdf",
  "size": 45678,
  "pages": 2
}
```

**Errors:**
- 404: `{"error": "Message not found"}`
- 403: `{"error": "Not your message"}`
- 400: `{"error": "Can only export AI responses"}`

---

## POST /voice/tts/
Convert text to speech using OpenAI TTS API.

**Request Body:**
```json
{
  "text": "Under Article 85 of the Cambodian Civil Code, ownership grants the right to use, enjoy, and dispose of property.",
  "voice": "nova",
  "speed": 1.0,
  "response_format": "mp3"
}
```

**Fields:**
- `text` (required): Text to convert (max 4096 chars)
- `voice` (optional): `alloy`, `echo`, `fable`, `onyx`, `nova` (default), `shimmer`
- `speed` (optional): 0.25 to 4.0 (default 1.0)
- `response_format` (optional): `mp3` (default), `opus`, `aac`, `flac`

**Response 200:**
```
Content-Type: audio/mpeg
Content-Length: 234567
```
Binary audio content.

**Errors:**
- 400: `{"error": "text is required"}` / `{"error": "Text too long (max 4096 chars)"}` / `{"error": "Invalid voice"}`

**Cost:** OpenAI TTS: $15.00 / 1M characters (tts-1), $30.00 / 1M characters (tts-1-hd)

---

## Flutter Integration Notes

### PDF Export
```dart
// Export a message as PDF
final response = await http.post(
  Uri.parse('$baseUrl/export/pdf/$messageId/'),
  headers: {'Authorization': 'Bearer $token'},
  body: jsonEncode({'include_question': true}),
);

// Save PDF to device
final bytes = response.bodyBytes;
final dir = await getApplicationDocumentsDirectory();
final file = File('${dir.path}/nomazra_export.pdf');
await file.writeAsBytes(bytes);

// Open PDF
await OpenFile.open(file.path);
```

### TTS (Read response aloud)
```dart
// Convert AI response to speech
final response = await http.post(
  Uri.parse('$baseUrl/voice/tts/'),
  headers: {
    'Authorization': 'Bearer $token',
    'Content-Type': 'application/json',
  },
  body: jsonEncode({
    'text': aiMessage.content,
    'voice': 'nova',
  }),
);

// Play audio
final bytes = response.bodyBytes;
final tempFile = File('${tempDir.path}/tts_response.mp3');
await tempFile.writeAsBytes(bytes);
await audioPlayer.play(DeviceFileSource(tempFile.path));
```
