#1059 — Refactor master document upload/download endpoints

Repo: Twill-AI/facade State: closed | Status: done Assignee: meliascosta

Created: 2026-02-25 · Updated: 2026-02-27

Description

Review of master-user document endpoints:

POST /api/v1/master/partners/{partner_id}/merchants/{merchant_id}/documents
GET /api/v1/master/partners/{partner_id}/merchants/{merchant_id}/documents/{document_id}/download-link

Master and partner upload/download logic have drifted and now behave inconsistently in important edge cases.

No AI-failure fallback in master upload path (inconsistent with partner route)
- If AI classification returns empty type/category, master flow can proceed with invalid/inconsistent classification values.
Duplicate detection happens after AI classification in master upload
- Master flow does unnecessary AI work for already-duplicate files.
Download-link endpoint can return 200 with empty URL
- API may report success while returning an unusable link.
Coverage gap for master download-link behavior
- Missing focused tests for success/error handling around storage responses.

Refactor document upload/download flow to use shared helper(s) called by both partner and master endpoints (single implementation for core business logic; router functions should mainly handle request/response wiring and auth).
Master and partner upload endpoints follow the same behavior for AI fallback:
- If AI classification fails and no explicit type is provided, fallback to OTH.
- If AI classification fails and explicit type is provided, use the provid

Add implementation notes, blockers, and context here

Add wikilinks to related people, meetings, or other tickets