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 Canonical Company.id resolved from the active CompanyMembership via authorizationService.resolveActor(userId).
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>, and notifications. Auction channels (auction:<id>, auction:staff:<id>) are joined exclusively via auction.subscribe; direct room.join to any auction:* room is rejected with 403 Forbidden. 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, auction.bid.mark, auction.winner.declare, auction.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
auction.announcement.create Client → Server Implemented — documented in auction.md
auction.presence.floor.update Client → Server Implemented — documented in auction.md and presence.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.state.changed, auction.bid.created, …) 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:<auctionId> you already receive the canonical auction events; company.auction.updated is an aggregation convenience and is not implemented yet.
  • auction.state.changed, auction.bid.created, auction.settings.updated

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.
auction.bid.mark Moderate a bid (DELETE_BID, DISQUALIFY_BIDDER).
auction.winner.declare Declare a winner from a candidate/default or manually.
auction.winner.record_lot Record a manual lot winner + runners-up.
auction.announcement.create Create an auction-scoped announcement; pushes auction.announcement.created.
auction.presence.floor.update Admit and mark a paid subscriber as floor-present, or remove the floor overlay; pushes auction.audience.changed.

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 (see events/room.md for the full room.join / room.leave contract):

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

Best practices for company clients

  1. Subscribe to every auction:<auctionId> your staff operate to receive staff commands results, live bids, and staff-scoped events (staff connections are auto-joined to the auction:staff:<auctionId> staff channel on subscribe).
  2. Join company:<companyId> once to receive company-scoped broadcast events.
  3. Always send an id for command events so a reconnected client does not double-submit.
  4. Treat broadcast:receive events as informational; reconcile from auction.state.snapshot on reconnect.