Skip to content

Feedback (beta tester widget) ​

This module receives the feedback users send from the floating widget that appears across the whole application. It is a global platform resource — it is not associated with, or filtered by, a company/tenant — and it targets the beta phase: anyone using the platform, signed in or not, can leave a 1-to-5-star rating and an optional comment.

The module was built across several tasks, all complete:

  • FEEDBACK-001 — created FeedbackEntity and the empty module.
  • FEEDBACK-002 — public submission endpoint POST /feedback.
  • FEEDBACK-003 — listing/management for the super admin.
  • FEEDBACK-004 — in-app notifications when new feedback arrives (see Notifications).

Sending feedback ​

http
POST /feedback
Content-Type: application/json

{
  "rating": 5,
  "comment": "I loved the new dashboard",
  "url": "https://app.nimobase.com/dashboard",
  "userAgent": "Mozilla/5.0 (...)",
  "browser": "Chrome",
  "browserVersion": "128.0",
  "os": "macOS",
  "deviceModel": "MacBook Pro",
  "screenResolution": "1920x1080",
  "viewportSize": "1440x900",
  "browserLanguage": "es-ES"
}
  • rating (1-5) is mandatory; every other field is optional.
  • No session required. It is a public endpoint — any visitor can submit it.
  • If the request carries a valid token (Authorization: Bearer <token> or X-API-Key), the feedback is associated with the sender's userId, role and companyId. With no session, those fields are stored as null (anonymous feedback).
  • The technical metadata (browser, operating system, resolution, etc.) is captured and sent by the client itself (frontend / SDK launcher) — the backend does not derive it from the User-Agent.
  • Metadata fields have a length cap in the API (@MaxLength). The launcher client truncates auto-captured values to those caps before sending, so an abnormally long UA or URL cannot break the submission with a 400. A hand-made POST with oversized fields still answers 400.
  • Every new piece of feedback is internally marked as "unread" (read: false), pending review by a super admin.
  • When new feedback arrives, every platform super administrator receives an in-app notification (FEEDBACK_RECEIVED) — see Notifications.

Submission limit (rate limiting) ​

To prevent abuse from the public widget, the endpoint accepts at most 5 submissions per hour from the same IP address. Past that limit it answers 429 Too Many Requests until the one-hour window resets.

Reading and managing feedback (super admin) ​

Feedback is a platform resource, just like billing plans (BillingPlanEntity) — it has no companyId of its own to scope by tenant. That is why read/management access is not controlled by a company role (OWNER/ADMIN) but by the user's global isSuperAdmin flag, following the same pattern as PlansService.assertSuperAdmin():

  • Any authenticated user who is not a super admin receives 403 Forbidden.
  • A request with no token receives 401 Unauthorized (both routes sit behind the global JwtAuthGuard; they are not @Public()).

Listing feedback ​

http
GET /feedback
GET /feedback?read=false
Authorization: Bearer <super-admin-token>
  • Returns every piece of feedback received, newest first, with all its context (rating, comment, technical metadata, identity when applicable, timestamps).
  • The optional read query parameter (true/false) filters the listing by read/unread state.

Marking as read ​

http
PATCH /feedback/:id/read
Authorization: Bearer <super-admin-token>
  • Marks the given feedback as read: true.
  • The read/unread state is single and shared: there is no per-super-admin tracking. When one super admin marks it read, it is read for everyone.

Out of scope ​

  • Attaching screenshots, export or aggregated analytics — explicitly out of scope for the full spec.
  • Resolution/follow-up states beyond read/unread — explicitly out of scope.
  • Replying to the user who sent the feedback — there is no conversation thread and no return email.