89 lines
5.4 KiB
Markdown
89 lines
5.4 KiB
Markdown
# `GET /events`
|
|
|
|
Protected. Requires a valid session cookie (`credentials: 'include'`).
|
|
|
|
Subscribe to update signals (SSE)
|
|
|
|
Opens a Server-Sent Events stream for the authenticated user.
|
|
Can be opened before a company is selected (`selectedCompanyId == null`);
|
|
when a company is selected or changed, the stream receives `user`
|
|
(`{ selectedCompanyId }`) and `company` (`{ companyId }`) events and
|
|
updates its company scope in-place.
|
|
Clients also receive named signals when another request successfully
|
|
mutates shared data for the active company (including the same
|
|
browser's other tabs).
|
|
|
|
Use `EventSource` with credentials so the session cookie is sent:
|
|
|
|
```js
|
|
const es = new EventSource('https://…/api/events', { withCredentials: true });
|
|
es.addEventListener('user', () => { refetchAuthMe(); });
|
|
es.addEventListener('company', () => { refetchCompany(); });
|
|
es.addEventListener('category', () => { refetchCategoryTree(); });
|
|
es.addEventListener('articles', () => { refetchArticleIndex(); });
|
|
es.addEventListener('article-42000045', () => { refetchArticle('42000045'); });
|
|
```
|
|
|
|
Keep-alive comments (`: heartbeat`) are sent roughly every 20s.
|
|
|
|
## Signals
|
|
|
|
Every SSE event uses the event name as the signal id; payloads are
|
|
JSON and most events send an empty object `{}`. `user` emits
|
|
`{ selectedCompanyId }`, `company` emits `{ companyId }`, and `brand`
|
|
emits `{ sender, brandId }`.
|
|
|
|
| Signal | Payload | Emitted after successful |
|
|
|--------|---------|--------------------------|
|
|
| `user` | `{ selectedCompanyId }` | `PUT /auth/selected-company`, `POST /company`, `DELETE /company/{id}` |
|
|
| `company` | `{ companyId }` | `PUT /auth/selected-company`, `POST /company`, `PUT /company/{id}`, `DELETE /company/{id}` |
|
|
| `category` | `{}` | `POST /category`, `PATCH /category/{id}`, `PUT /category/order`, `DELETE /category/{id}`, `POST /category/{id}/image`, `DELETE /category/{id}/image`, `PUT /category/{id}/property` |
|
|
| `articles` | `{}` | `POST /article`, `PATCH /article/{sku}`, `DELETE /article/{sku}`, `PUT /article/{sku}/articles`-style list-level changes, `POST /category/{id}/article` and related article-assigning category mutations |
|
|
| `article-<sku>` | `{}` | `PUT /article/{sku}/weight`, `PUT /article/{sku}/prices`, `PUT /article/{sku}/eans`, `PUT /article/{sku}/categories`, `PUT /article/{sku}/brand`, `PUT /article/{sku}/images/order`, `POST /article/{sku}/image`, `DELETE /article/{sku}/image/{fullHash}`, supplier/article-property mutations affecting the article |
|
|
| `stock` | `{}` | `POST /stock/adjust`, `POST /company/import` (also `category`, `articles`, `brand`, `attributename`, `warehouse`, `carrier`, `supplier`, `order`, `shipment`, `ledger`) |
|
|
| `ledger` | `{}` | `POST /stock/adjust` |
|
|
| `attributename` | `{}` | `POST /attributename`, `PUT /attributename/order`, `PATCH /attributename/{id}`, `DELETE /attributename/{id}` |
|
|
| `propertyname` | `{}` | `POST /propertyname`, `PUT /propertyname/order`, `PATCH /propertyname/{id}`, `DELETE /propertyname/{id}` |
|
|
| `labeltemplate` | `{}` | `POST /labeltemplate`, `PUT /labeltemplate/{id}`, `PATCH /labeltemplate/{id}`, `DELETE /labeltemplate/{id}` |
|
|
| `printer` | `{}` | `POST /printer`, `PUT /printer/{id}`, `PATCH /printer/{id}`, `DELETE /printer/{id}` |
|
|
| `printeragent` | `{}` | `PUT /printeragent`, `PATCH /printeragent/{id}`, `DELETE /printeragent/{id}`, printer agent connect/disconnect/state |
|
|
| `agentprinter` | `{ printers }` or `{}` | `PATCH /agentprinter/{id}`, `PUT /agentprinter/order`, `DELETE /agentprinter/{id}`, agent state updates / printer discovery |
|
|
| `companyuser` | `{}` | `POST /companyuser`, `PATCH /companyuser/{id}`, `DELETE /companyuser/{id}` |
|
|
| `autoinvite` | `{}` | `POST /autoinvite`, `DELETE /autoinvite/{id}` |
|
|
| `warehouse` | `{}` | `POST /warehouse`, `PUT /warehouse/{id}`, `PATCH /warehouse/{id}`, `DELETE /warehouse/{id}` |
|
|
| `supplier` | `{}` | `POST /supplier`, `PATCH /supplier/{id}`, `DELETE /supplier/{id}` |
|
|
| `vfs` | `{}` | VFS uploads and filesystem mutations such as `POST /vfs/upload`, `POST /vfs/mkdir`, `POST /vfs/rename`, `PUT /vfs/{*path}`, `DELETE /vfs/{*path}` |
|
|
| `modelconversation` | `{}` | `POST /modelconversation`, `DELETE /modelconversation/{id}` |
|
|
| `modelconversation-<id>` | `{}` | Conversation-specific updates on the same model conversation thread; the concrete ID is used in the event name |
|
|
| `brand` | `{ sender, brandId }` | `POST /brand`, `PATCH /brand/{id}`, `DELETE /brand/{id}`, `POST /brand/{id}/image`, `DELETE /brand/{id}/image` |
|
|
|
|
The `brand` payload is `{ sender, brandId }`: `sender` echoes the
|
|
caller's `x-client-id` header (empty string if absent) so the sender
|
|
can ignore its own event; `brandId` is the affected brand id (`null`
|
|
only if unknown). All other signals send `{}`.
|
|
|
|
Signals are only sent when the mutation actually succeeds (2xx).
|
|
Failed or no-op validation errors do not emit. The `article-<sku>`
|
|
and `modelconversation-<id>` event names use the concrete item id at
|
|
runtime (for example `article-42000045` and `modelconversation-123`).
|
|
|
|
|
|
## Response `200`
|
|
|
|
SSE stream (`text/event-stream`). Each signal is an SSE event
|
|
whose name is the signal id. Most signals send `{}` as data;
|
|
`user` sends `{ "selectedCompanyId": 1 }`, `company` sends
|
|
`{ "companyId": 1 }`, and `brand` sends
|
|
`{ "sender": "<x-client-id>", "brandId": 12 }`.
|
|
|
|
|
|
## Errors
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 401 | Unauthorized — `{"error":"…"}` |
|
|
|
|
---
|
|
|
|
_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._
|