Skip to content

Company Events

This page covers the real-time surface available to company connections (COMPANY role), which correspond to the auctioneer / staff persona. Company users share the standard room and system events, receive company-scoped broadcasts, and execute staff auction commands. There is no separate endpoint for companies; everything flows through /ws with the company role's permission set.

Reference: authentication.md · rooms.md · events/auction.md

Company identity

Property Value
Role COMPANY
Authentication Same JWT access-token handshake as other roles.
companyId Derived from userId (companyId = userId) in the token-derived socket user.
Dedicated room company:<companyId>
Permissions auction:subscribe, auction:staff, broadcast:receive, room:join, room:leave

The company connection can join company:<its own id>, user:<its own id>, any auction:<id>, and notifications. It cannot join admins (that is SUPERADMIN only) or a different company's company:<id>.

Event list

Event Direction Status
company.broadcast Server → Client Planned
company.auction.updated Server → Client Planned alias of auction staff events
Staff auction commands (auction.pause, auction.resume, auction.end, bid.mark, winner.declare, winner.record_lot, auction.status.update) Client → Server Implemented — documented in auction.md
Staff offline bid (auction.bid.place by a company on behalf of an offline subscriber) Client → Server Implemented — documented in auction.md

Company operational traffic is dominated by the implemented staff command events. The remaining company-scoped events below are planned and use the company:<companyId> room.

company.broadcast

Description

A server-pushed message addressed to a company's connections, delivered over the company:<companyId> room (e.g. audit alerts, policy updates, or auction-control notices broadcast to every company staff connection).

Rules

Field Value
Direction Server → Client
Roles COMPANY (and SUPERADMIN)
Permissions none for receiving (delivery follows company:<id> membership)

Example Response

{
  "type": "company.broadcast",
  "data": {
    "companyId": "com_01HQ5BWYP1Y5RX0W5X0W5X0W5X",
    "kind": "AUCTION_ALERT",
    "title": "Auction closing",
    "body": "Auction for cycle cyc_01H... closes in 5 minutes",
    "data": { "cycleId": "cyc_01HQ5BWYP1Y5RX0W5X0W5X0W5X" },
    "createdAt": "2026-08-03T10:00:00.000Z"
  }
}

Error Responses

None (server-pushed).

company.auction.updated

Description

Planned alias surface for the auction staff events. It represents a company-scoped summary of auction state transitions relevant to the company (e.g. a program's auction started/ended) broadcast over the company:<id> room.

Direction

Server → Client (planned). The canonical server events remain the auction events (auction.started, auction.closed, …) documented in events/auction.md.

Example Response

{
  "type": "company.auction.updated",
  "data": {
    "companyId": "companyId_01HQ5BWYP1Y5RX0W5X0W5X0W5X",
    "cycleId": "cyc_01HQ5BW3P1Y5RX0W5X0W5X0W5X",
    "status": "STARTED",
    "occurredAt": "2026-08-03T10:00:00.000Z"
  }
}

Notes

  • If you subscribe to auction:<cycleId> you already receive the canonical auction events; company.auction.updated is an aggregation convenience and is not implemented yet.
  • auction.started, auction.closed, auction.status_changed

Staff command events (implemented)

The following events require the auction:staff permission (available to COMPANY and SUPERADMIN). Full request/response schemas and validation are in events/auction.md.

Event Meaning
auction.status.update Start the live auction (status: "START").
auction.pause Pause the auction with a reason.
auction.resume Resume the auction with a reason.
auction.end End the auction with a reason.
bid.mark Moderate a bid (DELETE_BID, DISQUALIFY_BIDDER, DISQUALIFY_CANDIDATE_AND_DECLARE_NEXT).
winner.declare Declare a winner from a candidate/default or manually.
winner.record_lot Record a manual lot winner + runners-up.

Staff offline bids

A company staff member may place a live bid on behalf of an offline subscriber using auction.bid.place with enrolledSubscriberId. This is valid only when the target subscriber is offline and the auction settings allow offline staff bids. Wrong target or an online subscriber returns FORBIDDEN/BAD REQUEST.

Company room membership

Joining the company room:

{
  "type": "room.join",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "data": { "room": "company:companyId_01HQ2QWYP1Y5RX0W5X0W5X0W5X" }
}

Best practices for company clients

  1. Subscribe to every auction:<cycleId> your staff operate to receive staff commands results and live bids.
  2. Join company:<companyId> once to receive company-scoped broadcast events.
  3. Always send an idempotencyKey for command events so a reconnected client does not double-submit.
  4. Treat broadcast:receive events as informational; reconcile from auction.snapshot on reconnect.