# Frontend Integration Guide - Session-Based Batch Processing
## 🚀 NEW ENDPOINTS AVAILABLE
### 1. **Session Management** - `/api/session`
**Purpose**: Initialize and maintain user sessions for temporary file storage
```javascript
// Initialize session when user opens the app
POST /api/session
Response: { sessionId: "1762145344331-h6evl2etm", success: true }
// Keep session alive (call every 5 minutes while user is active)
POST /api/session
Headers: { "X-Session-ID": "session-id-here" }
Response: { success: true, message: "Session refreshed" }
// Get session info and existing batches
GET /api/session?sessionId=session-id-here
Response: {
sessionId: "...",
files: [...],
batches: [...],
expiresIn: "1 hour from last activity"
}
```
### 2. **Batch Upload** - `/api/batch-upload`
**Purpose**: Upload and process multiple DOCX files at once (up to 10 files)
```javascript
// Upload multiple files
POST /api/batch-upload
Headers: { "X-Session-ID": "session-id-here" }
Body: FormData with multiple files
Response: {
sessionId: "session-id-here",
batchId: 1762145344343,
summary: {
totalFiles: 5,
successful: 4,
failed: 1
},
results: [
{
fileIndex: 1,
filename: "document1.docx",
success: true,
reportId: "report-123",
summary: { flagged: 2, fixed: 1 },
details: { ... }
},
// ... more files
],
expiresIn: "1 hour"
}
```
### 3. **Batch Download** - `/api/batch-download`
**Purpose**: Download all remediated files as a ZIP
```javascript
// Download remediated files
GET /api/batch-download?batchId=1762145344343&sessionId=session-id-here
Response: ZIP file containing all remediated documents
```
---
## 📋 FRONTEND IMPLEMENTATION CHECKLIST
### Step 1: **Session Initialization** (Required)
```javascript
class AccessibilityChecker {
constructor() {
this.sessionId = null;
this.heartbeatInterval = null;
}
async initializeSession() {
try {
const response = await fetch('/api/session', {
method: 'POST',
headers: { 'Content-Type': 'application/json' }
});
const data = await response.json();
this.sessionId = data.sessionId;
// Start heartbeat to keep session alive
this.startHeartbeat();
return this.sessionId;
} catch (error) {
console.error('Session initialization failed:', error);
}
}
startHeartbeat() {
// Send heartbeat every 5 minutes while user is active
this.heartbeatInterval = setInterval(async () => {
if (this.sessionId) {
try {
await fetch('/api/session', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Session-ID': this.sessionId
}
});
} catch (error) {
console.warn('Heartbeat failed:', error);
}
}
}, 5 * 60 * 1000); // 5 minutes
}
cleanup() {
if (this.heartbeatInterval) {
clearInterval(this.heartbeatInterval);
}
// Note: Server will auto-cleanup files after 1 hour
}
}
// Initialize when app loads
const checker = new AccessibilityChecker();
checker.initializeSession();
// Cleanup when user leaves
window.addEventListener('beforeunload', () => checker.cleanup());
```
### Step 2: **Multi-File Upload UI** (Recommended)
```javascript
async function uploadMultipleFiles(files) {
if (!checker.sessionId) {
throw new Error('Session not initialized');
}
const formData = new FormData();
files.forEach((file, index) => {
formData.append(`file${index}`, file);
});
const response = await fetch('/api/batch-upload', {
method: 'POST',
headers: {
'X-Session-ID': checker.sessionId
},
body: formData
});
if (!response.ok) {
throw new Error(`Upload failed: ${response.statusText}`);
}
return await response.json();
}
// Usage example:
document.getElementById('fileInput').addEventListener('change', async (e) => {
const files = Array.from(e.target.files);
try {
const result = await uploadMultipleFiles(files);
console.log(`Processed ${result.summary.totalFiles} files`);
console.log(`Batch ID: ${result.batchId}`);
// Show results to user
displayBatchResults(result);
} catch (error) {
console.error('Upload error:', error);
}
});
```
### Step 3: **Download Remediated Files** (Required)
```javascript
function downloadBatch(batchId) {
if (!checker.sessionId) {
alert('Session expired. Please refresh the page.');
return;
}
const downloadUrl = `/api/batch-download?batchId=${batchId}&sessionId=${checker.sessionId}`;
// Create temporary download link
const link = document.createElement('a');
link.href = downloadUrl;
link.download = `batch-${batchId}-remediated.zip`;
document.body.appendChild(link);
link.click();
document.body.removeChild(link);
}
```
---
## 🔄 MIGRATION FROM EXISTING ENDPOINTS
### If you're currently using single-file endpoints:
**Old way:**
```javascript
// Single file upload
POST /api/upload-document
POST /api/download-document
```
**New way (backward compatible):**
```javascript
// Keep using single file endpoints for 1 file
// OR use batch endpoints for 1+ files
// For multiple files:
POST /api/batch-upload (new)
GET /api/batch-download (new)
```
### **Integration Options:**
1. **Quick Integration** (minimal changes):
- Add session initialization on app start
- Keep existing single-file flow
- Add optional multi-file upload as new feature
2. **Full Integration** (recommended):
- Replace single-file with batch endpoints
- Add drag-and-drop for multiple files
- Show batch progress and results
---
## 🎯 UI/UX RECOMMENDATIONS
### **File Upload Area:**
```html
Drop up to 10 DOCX files here, or click to select
Select Files
```
### **Progress Display:**
```javascript
// Show batch processing progress
function displayBatchResults(result) {
const container = document.getElementById('results');
container.innerHTML = `
Batch Processing Complete
Processed: ${result.summary.totalFiles} files
Successful: ${result.summary.successful}
Failed: ${result.summary.failed}
Download All Remediated Files
${result.results.map(file => `
${file.filename}
${file.success ?
`✓ ${file.summary.fixed} issues fixed ` :
`✗ ${file.error} `
}
`).join('')}