Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/InnoDev69/StockManager/llms.txt

Use this file to discover all available pages before exploring further.

StockManager delivers in-app alerts without polling. Instead of having the browser ask the server “any news?” on a timer, the server pushes events over a persistent HTTP connection using the Server-Sent Events protocol. When a sale is recorded, a product drops below its minimum stock, or an admin performs an account action, the affected user’s browser receives an event within milliseconds — no page reload required.

​
SSE stream — GET /api/notifications/stream

Opening a connection to this endpoint establishes a long-lived HTTP response with Content-Type: text/event-stream. The session must be authenticated; unauthenticated requests are rejected. On connect the server immediately sends an init event carrying the user’s current unread notifications (up to 5) and total unread count: 
event: init
data: {"notifications": [...], "count": 3}
When a new notification arrives for the connected user, the server sends an update event with the latest unread notifications (up to 10) and updated count: 
event: update
data: {"notifications": [...], "count": 4}
Heartbeat: if no notification has been sent for 25 seconds, the server sends a comment line (: heartbeat) to keep the connection alive through proxies and load balancers.
Each user maintains at most one active SSE connection. If a second browser tab (or window) connects with the same session, the server cancels the previous connection and attaches the new one. This prevents silent duplicate connections from accumulating.

​
JavaScript example

const stream = new EventSource("/api/notifications/stream");

stream.addEventListener("init", (e) => {
  const { notifications, count } = JSON.parse(e.data);
  renderNotificationBadge(count);
  renderNotificationList(notifications);
});

stream.addEventListener("update", (e) => {
  const { notifications, count } = JSON.parse(e.data);
  renderNotificationBadge(count);
  renderNotificationList(notifications);
});

stream.onerror = () => {
  // Browser will automatically attempt to reconnect
  console.warn("SSE connection lost, retrying...");
};

​
Notification object shape

Every notification returned by the SSE stream or the REST endpoints has the following structure: 
{
  "id": 512,
  "title": "Stock bajo",
  "message": "El producto Whole Milk 1L (ID: 42) tiene stock bajo (4 unidades).",
  "type": "warning",
  "action_url": null,
  "created_at": "2025-07-14 11:45:02",
  "is_read": false
}
FieldDescription
idUnique notification ID
titleShort heading shown in the notification panel
messageFull description of the event
typesuccess, warning, error, or info
action_urlOptional URL the user can follow for context (may be null)
created_atISO-style datetime string
is_readfalse until the user or admin marks it read

​
Automatic notification triggers

StockManager creates notifications automatically in the following situations:

Low stock

Triggered after any product update or bulk sale when a product’s quantity drops below its min_quantity. Type: warning.

Product created

Sent to the acting admin when a new product is added to the catalog. Type: success.

Product updated

Sent to the acting admin when a product’s fields are changed. Type: success.

Product disabled

Sent to the acting admin when a product is soft-deleted. Type: warning.

Product activated

Sent to the acting admin when a disabled product is re-enabled. Type: success.

Sale registered

Sent to the vendor after a successful bulk sale. Type: success.

Sale updated

Sent to the admin after editing a past transaction. Type: success.

Sale error

Sent when a sale attempt fails internally. Type: error.

​
Manual notifications (admin only)

Admins can create a notification for any user via POST /api/notifications/create: 
curl -X POST http://localhost:5000/api/notifications/create \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 7,
    "title": "Scheduled maintenance",
    "message": "The system will restart at 23:00 tonight.",
    "type": "info",
    "action_url": null
  }'
Successful response (HTTP 201): 
{ "message": "Notificación creada exitosamente" }
Required fields: user_id, title, message. The type field defaults to "info" if omitted.

​
Reading notifications

​
Unread notifications

GET /api/notifications/unread returns the last 10 unread notifications for the current user, plus a total unread count: 
{
  "notifications": [...],
  "unread_count": 2
}

​
All notifications (paginated)

GET /api/notifications/all accepts limit (default: 20) and offset (default: 0) query parameters and returns all notifications for the current user, read and unread alike.

​
Marking notifications as read

EndpointEffect
POST /api/notifications/<id>/readMarks a single notification as read
POST /api/notifications/read-allMarks all of the current user’s notifications as read
Both endpoints return HTTP 200 with a confirmation message on success.
Each user can only see their own notifications. There is no endpoint that returns another user’s notifications unless you are operating as that user. Notification isolation is enforced at the database query level using the user_id stored in the session.

Build docs developers (and LLMs) love

Get started for freeTalk to us