Briefing Endpoints
Briefing Endpoints
Section titled “Briefing Endpoints”API endpoints and server actions specific to the Briefing Progressivo 4-phase flow.
Server Actions
Section titled “Server Actions”All briefing mutations use Server Actions defined in src/actions/briefing.ts. Each action:
- Is marked with
'use server' - Uses
requireActionAuth()for authentication - Returns a
BriefingFlowStateobject (or an extended variant)
Phase 1 — Diagnosis
Section titled “Phase 1 — Diagnosis”| Action | Signature | Purpose |
|---|---|---|
updateDiagnosis | (sessionId, fields) → BriefingFlowState | Update diagnosis fields (situation, area, tema, tese). Advances from Phase 0 → Phase 1 if needed. |
chooseSituation | (sessionId, situation) → { state, phase2Blocks } | Set user situation. Derives delivery mode and generates Phase 2 blocks. |
addAdditionalContext | (sessionId, text) → BriefingFlowState | Store free-text additional context in briefing state. |
Situation → Delivery Mode mapping:
| Situation | Delivery Mode | Description |
|---|---|---|
pesquisando | sintese | User is researching — gets a concise synthesis |
avaliando | parecer | User is evaluating — gets a formal legal opinion |
atuando | estrategia | User is acting — gets a strategic plan |
estudando | mapa | User is studying — gets a conceptual map |
Phase 2 — Precedents
Section titled “Phase 2 — Precedents”| Action | Signature | Purpose |
|---|---|---|
evaluatePrecedent | (sessionId, processoId, evaluation) → BriefingFlowState | Rate a precedent as 'useful' or 'not_useful'. Advances to Phase 2 if needed. |
Phase 3 — Risks
Section titled “Phase 3 — Risks”| Action | Signature | Purpose |
|---|---|---|
advanceToPhase3 | (sessionId) → { state, phase3Blocks } | Generate risk blocks (risk_balance + chart) from existing case analysis. |
resolveRisk | (sessionId, riskId) → BriefingFlowState | Mark a risk as handled. Updates the risk_balance block in the database. |
Phase 4 — Delivery
Section titled “Phase 4 — Delivery”| Action | Signature | Purpose |
|---|---|---|
generateDelivery | (sessionId) → { state, phase4Blocks } | Generate delivery blocks based on the selected delivery mode. Requires deliveryMode to be set. |
choosePath | (sessionId, pathId) → BriefingFlowState | Set chosen strategic path in the estrategia delivery block. Generates next steps. |
setFaseProcessual | (sessionId, fase) → BriefingFlowState | Update faseProcessual field in the estrategia delivery block. |
Session Finalization
Section titled “Session Finalization”| Action | Signature | Purpose |
|---|---|---|
finalizeSession | (sessionId) → BriefingFlowState | Mark session as finalized. Updates exit_card block to selected: 'concluir'. |
handleExitAction | (sessionId, action) → { state, action } | Handle exit card selection. If action === 'concluir', sets finalized = true. |
PDF Export
Section titled “PDF Export”GET /api/export/pdf/[sessionId]
Section titled “GET /api/export/pdf/[sessionId]”Generate and download a PDF document for a briefing session.
Source: src/app/api/export/pdf/[sessionId]/route.ts
Auth: auth() session check. Bypassed when ENABLE_DEV_AUTH=true.
Path parameters: sessionId: string
Response 200:
| Header | Value |
|---|---|
| Content-Type | application/pdf |
| Content-Disposition | attachment; filename="briefing-{sessionId.slice(0,8)}.pdf" |
Body: raw PDF bytes generated by generateBriefingPDF() from src/lib/pdf/generator.ts.
Error responses:
401—{ error: 'Unauthorized' }404—{ error: 'Session not found' }(no blocks exist for the sessionId)
PDF generation details:
- Uses jsPDF for PDF creation
- Extracts blocks by type from the session database
- Manual Y-position tracking with
checkPage()for page overflow - Text wrapping via
doc.splitTextToSize(text, maxWidth) - Output:
new Uint8Array(doc.output('arraybuffer'))
Transitional Endpoints
Section titled “Transitional Endpoints”These endpoints exist in Juca but are being migrated to Valter. They will be removed in v0.4 after migration is complete:
| Group | Path | Endpoints | Migration Target |
|---|---|---|---|
| Analyzer | /api/analyzer/* | 8 | Valter /v1/factual/*, /v1/retrieve |
| Chat | /api/chat/* | 6 | Valter LLM pipeline |
| KG | /api/kg/* | 14 | Valter /v1/graph/* |
| Reasoning | /api/reasoning/* | 4 | Valter IRAC extraction |
| Search | /api/search/* | 2 | Valter /v1/retrieve |
| Comparator | /api/comparator/* | 2 | Valter multi-model comparison |