feat: expose Protocol v1 ingestion over plain JSON and OCS

[vitormattos]

Summary

Expose Usage Statistics Protocol v1 report ingestion through two equivalent Nextcloud routes backed by the same application service:

• a plain HTTP/JSON route for framework-agnostic protocol clients
• an OCS route for Nextcloud-native tooling and API discovery

Both routes accept the same Protocol v1 request fields and persist reports through the same validation and storage path.

Why

The generic PHP client expects the Protocol v1 response body directly, for example {"status":"accepted"}. A report endpoint implemented only as an OCSController wraps that result under ocs.data, coupling the generic protocol client to a Nextcloud-specific response envelope.

The plain route keeps Protocol v1 framework-agnostic. The OCS route remains available for the Nextcloud ecosystem without changing the generic client contract.

Implementation

• add a shared report submission service for parsing, schema lookup, validation and persistence
• expose the plain ingestion route with FrontpageRoute
• expose the OCS ingestion route with ApiRoute
• keep anonymous rate limiting and the same validation/error semantics on both routes
• document that OCS is a reference-server transport detail, not part of Protocol v1
• cover both routes in Behat
• add integration coverage for the shared submission service

OpenAPI

The server now ships the generated OpenAPI contracts and TypeScript types in the repository, following the same drift-check approach used by LibreSign.

The generated default specification contains both ingestion routes:

• /index.php/apps/usage_statistics_server/api/{apiVersion}/reports
• /ocs/v2.php/apps/usage_statistics_server/api/{apiVersion}/reports

Administrative OCS routes remain in openapi-administration.json, while openapi-full.json contains the complete API.

Compatibility

LibreCodeCoop/usage_statistics_client#4 runs the real generic client against this server branch and verifies submission, persistence and aggregation end to end. The client itself remains unaware of OCS.