feat(#274): PaperlessClient — HTTP-Wrapper mit Tests #310

Merged

admin-mrrm merged 1 commit from feat/274-paperless-client into main

2026-05-16 14:54:01 +02:00

admin-mrrm commented

2026-05-16 14:49:37 +02:00

Owner

Summary

Neuer NestJS-Service PaperlessClient unter apps/api/src/modules/documents/ als getypter HTTP-Wrapper fuer Paperless-ngx. Foundation fuer #275 (documents-Modul) und #278 (Mail-Archiv-Service).

Methoden:

listDocuments(query) -> GET /api/documents/ mit Param-Mapping
getDocument(id) -> GET /api/documents/:id/
getPreviewStream(id) -> GET /api/documents/:id/preview/ (PDF-Stream)
getThumbnail(id) -> GET /api/documents/:id/thumb/ (Image-Stream)
uploadDocument(file, meta) -> POST /api/documents/post_document/ (multipart)
listTags(), listCorrespondents(), listDocumentTypes()

Auth: Authorization: Token <PAPERLESS_TOKEN> (Django REST Framework Standard).

Fehlerbehandlung:

ServiceUnavailableException wenn PAPERLESS_BASE_URL oder PAPERLESS_TOKEN fehlt
BadGatewayException bei Non-OK-Antwort

Pattern: globalThis.fetch + ConfigService<AppEnv>, analog zu AfterShipProvider/Track17Provider im tracking-Modul.

Tests (TDD, 17 neue Tests)

Config-Validierung (missing BASE_URL/TOKEN, trailing-slash trim, Auth-Header)
listDocuments Param-Mapping (tags, correspondent, page, ordering) + empty-skipping + Error
getDocument, getPreviewStream (inkl. body-null), getThumbnail
uploadDocument multipart mit Buffer/Tags/Meta + Error-Case
list-Endpoints (tags, correspondents, document_types)

Test plan

pnpm --filter @mrrmlab/api typecheck clean
pnpm --filter @mrrmlab/api test 293/293 gruen (+17 PaperlessClient)
Smoke-Test gegen dev-neu sobald PAPERLESS_TOKEN im Vault ist (Issue-Acceptance "Fixtures aus echter dev-neu-Instanz")

Anmerkung

Issue spricht von nock/msw-node fuer Tests. Ich habe stattdessen vi.stubGlobal('fetch', ...) verwendet, weil das im Projekt etabliertes Pattern ist (siehe aftership.provider.spec.ts, track17.provider.spec.ts) — gleiche Aussagekraft, kein zusaetzliches devDep.

Closes #274

## Summary Neuer NestJS-Service `PaperlessClient` unter `apps/api/src/modules/documents/` als getypter HTTP-Wrapper fuer Paperless-ngx. Foundation fuer #275 (documents-Modul) und #278 (Mail-Archiv-Service). **Methoden:** - `listDocuments(query)` -> GET `/api/documents/` mit Param-Mapping - `getDocument(id)` -> GET `/api/documents/:id/` - `getPreviewStream(id)` -> GET `/api/documents/:id/preview/` (PDF-Stream) - `getThumbnail(id)` -> GET `/api/documents/:id/thumb/` (Image-Stream) - `uploadDocument(file, meta)` -> POST `/api/documents/post_document/` (multipart) - `listTags()`, `listCorrespondents()`, `listDocumentTypes()` **Auth:** `Authorization: Token <PAPERLESS_TOKEN>` (Django REST Framework Standard). **Fehlerbehandlung:** - `ServiceUnavailableException` wenn `PAPERLESS_BASE_URL` oder `PAPERLESS_TOKEN` fehlt - `BadGatewayException` bei Non-OK-Antwort **Pattern:** `globalThis.fetch` + `ConfigService<AppEnv>`, analog zu `AfterShipProvider`/`Track17Provider` im tracking-Modul. ## Tests (TDD, 17 neue Tests) - Config-Validierung (missing BASE_URL/TOKEN, trailing-slash trim, Auth-Header) - `listDocuments` Param-Mapping (tags, correspondent, page, ordering) + empty-skipping + Error - `getDocument`, `getPreviewStream` (inkl. body-null), `getThumbnail` - `uploadDocument` multipart mit Buffer/Tags/Meta + Error-Case - list-Endpoints (tags, correspondents, document_types) ## Test plan - [x] `pnpm --filter @mrrmlab/api typecheck` clean - [x] `pnpm --filter @mrrmlab/api test` 293/293 gruen (+17 PaperlessClient) - [ ] Smoke-Test gegen dev-neu sobald PAPERLESS_TOKEN im Vault ist (Issue-Acceptance "Fixtures aus echter dev-neu-Instanz") ## Anmerkung Issue spricht von `nock`/`msw-node` fuer Tests. Ich habe stattdessen `vi.stubGlobal('fetch', ...)` verwendet, weil das im Projekt etabliertes Pattern ist (siehe `aftership.provider.spec.ts`, `track17.provider.spec.ts`) — gleiche Aussagekraft, kein zusaetzliches devDep. Closes #274

admin-mrrm added 1 commit

2026-05-16 14:49:37 +02:00

feat(#274 ): PaperlessClient — HTTP-Wrapper mit Tests

continuous-integration/drone/push Build is passing

Details

continuous-integration/drone/pr Build is passing

Details

3fdd7004d9

Neuer NestJS-Service unter apps/api/src/modules/documents/:
- paperless.client.ts: globalThis.fetch + ConfigService<AppEnv>
- Token-Auth via Authorization: Token <PAPERLESS_TOKEN>
- Methoden: listDocuments, getDocument, getPreviewStream (PDF),
  getThumbnail, uploadDocument (multipart), listTags,
  listCorrespondents, listDocumentTypes
- ServiceUnavailableException ohne Config, BadGatewayException bei
  Fehlerstatus aus Paperless

17 Tests (paperless.client.spec.ts) decken:
- Config-Validierung (fehlende BASE_URL/TOKEN, trailing-slash trim)
- Param-Mapping (tags__id__in, correspondent__id, page_size, ...)
- multipart Upload mit Buffer/Blob, mehrfache Tags
- Stream-Endpoints (preview/thumb) inkl. body=null Edge-Case
- Error-Handling pro Endpoint

Foundation fuer #275 (documents-Modul mit Controller) und #278 (Mail-Archiv-Service).

Refs #274

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>