TASK-API-DIRECT-SAVE-IMPLEMENTATION.md•7.81 kB
# Task: Implement API Direct Save Mechanism
**Task ID**: TASK-API-DIRECT-SAVE-001
**Priority**: Critical
**Status**: Ready for Execution
**Owner**: Claude Code
**Created**: 2025-07-03 21:25 EST
**Dependencies**: Analysis document api-direct-save-implementation-analysis.md
---
## 📋 **Objective**
Implement the API direct save mechanism discovered by user's tech team to replace localStorage injection approach and achieve 100% functional composition creation with immediate visualization.
## 🎯 **Requirements**
### **Core Implementation**
- [ ] Extract authentication data from localStorage (`rdp-composer-active-project`, `rdp-composer-user-data`)
- [ ] Implement `getCorrectConnector()` function to find appropriate API connector
- [ ] Implement `saveLessonComposition()` function for direct API upload
- [ ] Replace localStorage injection workflow with direct API save
- [ ] Handle FormData creation and file upload process
- [ ] Implement proper error handling and user feedback
### **Technical Specifications**
- [ ] **Authentication Extraction**: Extract required tokens via `page.evaluate()`
- [ ] **API Endpoint**: Use `https://api.digitalpages.com.br/storage/v1.0/upload/connector/uid/{connector.uid}`
- [ ] **File Format**: Upload composition as `.rdpcomposer` file via FormData
- [ ] **Headers**: Include Authorization, Project-Key, and Api-Env headers
- [ ] **Navigation**: Use returned UID for proper `#/composer/{id}` redirection
### **Integration Points**
- [ ] **Replace Step 4-7** in current `executeWorkflow()` (localStorage injection + save button)
- [ ] **Maintain Steps 1-3** (authentication, navigation, blank composition creation)
- [ ] **Update Step 8+** to handle API response and navigation
- [ ] **Preserve browser persistence** functionality
## 🛠️ **Implementation Notes**
### **Code Structure Updates**
#### **1. Add Authentication Extraction**
```javascript
async extractAuthenticationData(page) {
return await page.evaluate(() => {
const activeProject = localStorage.getItem('rdp-composer-active-project');
const userData = localStorage.getItem('rdp-composer-user-data');
if (!activeProject || !userData) {
throw new Error('Authentication data not found - user must be logged in');
}
return {
activeProject: JSON.parse(activeProject),
userData: JSON.parse(userData)
};
});
}
```
#### **2. Implement Connector Selection**
```javascript
getCorrectConnector(connectors) {
let connector = connectors.find(item => item.type === "Composer_1");
if (!connector) {
connector = connectors.find(connector => connector.scope === "Project");
}
if (!connector) {
throw new Error('No suitable connector found');
}
return connector;
}
```
#### **3. Direct API Save Implementation**
```javascript
async saveCompositionDirectly(page, compositionData, authData) {
return await page.evaluate(async (data, auth) => {
const { activeProject, userData } = auth;
const connector = /* getCorrectConnector logic */;
const url = `https://api.digitalpages.com.br/storage/v1.0/upload/connector/uid/${connector.uid}?manual_project_uid=${activeProject.uid}`;
const compositionBlob = new Blob([JSON.stringify(data, null, 2)], {
type: 'application/json'
});
const formData = new FormData();
formData.append('file', compositionBlob, 'composition.rdpcomposer');
const response = await fetch(url, {
method: 'POST',
body: formData,
headers: {
"Authorization": `${userData.type} ${userData.access_token}`,
"Project-Key": "e3894d14dbb743d78a7efc5819edc52e",
"Api-Env": "prd"
}
});
if (!response.ok) {
throw new Error(`API upload failed: ${response.status}`);
}
const result = await response.json();
return result[0].uid;
}, compositionData, authData);
}
```
### **Workflow Integration**
#### **Updated executeWorkflow() Structure**
```javascript
async executeWorkflow(page, compositionData) {
try {
// Steps 1-3: Existing authentication and navigation (PRESERVE)
console.log('[API-DIRECT] Step 1-3: Authentication and setup');
// NEW Step 4: Extract authentication data
console.log('[API-DIRECT] Step 4: Extract authentication');
const authData = await this.extractAuthenticationData(page);
// NEW Step 5: Direct API save
console.log('[API-DIRECT] Step 5: Direct API save');
const newCompositionId = await this.saveCompositionDirectly(page, compositionData, authData);
// NEW Step 6: Navigate to composition
console.log('[API-DIRECT] Step 6: Navigate to saved composition');
const composerUrl = `http://localhost:8080/composer#/composer/${newCompositionId}`;
await page.goto(composerUrl, { waitUntil: 'networkidle' });
// Step 7: Verify and return success
console.log('[API-DIRECT] Step 7: Composition created and visible');
return { success: true, url: composerUrl, compositionId: newCompositionId };
} catch (error) {
console.error('[API-DIRECT] Workflow failed:', error);
return { success: false, error: error.message };
}
}
```
## ✅ **Success Criteria**
### **Functional Requirements**
- **Composition Creation**: Successfully uploads composition to backend API
- **Authentication**: Properly extracts and uses existing user tokens
- **Navigation**: Redirects to correct edit mode URL (`#/composer/{id}`)
- **Visualization**: Composition immediately visible and interactive
- **Error Handling**: Graceful failure with informative error messages
### **Performance Requirements**
- **Workflow Time**: < 30 seconds end-to-end
- **Success Rate**: 100% when user is properly authenticated
- **Browser Persistence**: Browser remains open for immediate user interaction
### **Quality Requirements**
- **No localStorage Manipulation**: Eliminates all injection-related issues
- **Native Mechanism**: Uses Composer's intended save workflow
- **Robust Authentication**: Validates required tokens before API calls
## 🧪 **Testing Plan**
### **Phase 1: Authentication Testing**
1. **Valid Session**: Test with logged-in user
2. **Missing Auth**: Test error handling for unauthenticated state
3. **Invalid Tokens**: Test with expired/invalid authentication
### **Phase 2: API Integration Testing**
1. **Simple Composition**: Test with minimal JSON structure
2. **Complex Composition**: Test with full educational content
3. **Error Scenarios**: Test network failures and API errors
### **Phase 3: End-to-End Validation**
1. **Complete Workflow**: Full automation from creation to visualization
2. **Interactive Elements**: Verify flashcards, quizzes function correctly
3. **Multiple Compositions**: Test repeated creation workflow
## 🔄 **Implementation Phases**
### **Phase 1: Core Implementation** (1-2 hours)
- Implement authentication extraction
- Create direct API save functions
- Update workflow integration
- Basic error handling
### **Phase 2: Testing & Refinement** (30-60 minutes)
- Test with simple compositions
- Validate authentication handling
- Refine error messages
### **Phase 3: Production Deployment** (15-30 minutes)
- Update MCP server configuration
- Deploy updated version
- Validate end-to-end functionality
## 📄 **Related Documents**
- **Analysis**: `docs/analysis/api-direct-save-implementation-analysis.md`
- **Tech Team Script**: User-provided `saveLessonComposition()` implementation
- **Current Implementation**: `dist/browser-automation-fixed-v3.0.0.js`
---
**Expected Outcome**: 100% functional composition creation system with immediate visualization using Composer's native API mechanism, eliminating all current technical challenges.
**Timeline**: 2-3 hours implementation + testing for complete solution.