t5de-hub/docs/hosted-rooms.md

# T5DE-hosted rooms (phase 1)

A hosted room lives on the hub (design.md, Rooms): T5DE users find it in the client's room list, join it, sit and
chat, and its owner decorates it. The client treats it as an ordinary IMVU room: T5DE's proxy answers the client's
room calls and runs the room's IMQ queue against the hub (imq-rooms.md has what the client expects). IMVU never
hears of hosted rooms.

Phase 1: rooms created on the website; joining, seats, chat (`messages` and `control` mounts), the scene (the
owner's furniture), occupancy in the room list. Phase 2 (below): moderators, boots and bans, private rooms,
invitations, images, favorites, ratings, recent rooms, occupancy pushed to watchers, participant names.

## IDs

IDs IMVU won't use, so the proxy can tell hosted rooms apart:

- A room has a number `n` (1, 2, ...), its **instance ID** is `<owner's IMVU ID>-<2100000000 + n>` and its
  **chat ID** is `2100000000 + n`. The client takes a room's owner from the instance ID's first part (so the owner
  can decorate it); IMVU's own room numbers are small. (IMVU's chat IDs were about 1,390,000,000 in 2026-10, and XML-RPC integers end at
  2,147,483,647; IMVU customer IDs, the first part of its instance IDs, are far below 2,100,000,000.)
- The room shell is an IMVU product (`roomPid`), chosen when the room is made (any room product; the client loads
  it like any room).

## REST (bearer or cookie session)

| Route | |
| --- | --- |
| `POST /api/v1/hosted-rooms` | `{name, description, roomPid, rating, maxUsers, imvuId}`: make a room. `imvuId` is one of the person's linked IMVU accounts, shown as the owner. `rating` `general` or `adult` (adult needs an adult person). `maxUsers` 2-30, default 10. Name 1-64 characters, description up to 512. A person may own up to 10 open rooms. |
| `GET /api/v1/hosted-rooms` | (also signed out) `{rooms: [room]}`, open rooms, newest first; adult rooms only for adults. `?mine=1`: the person's own. |
| `GET /api/v1/hosted-rooms/:n` | (also signed out) `{room, scene: {contents, hash}}`; 404 `not_found` (or adult, for others), 410 `closed`. |
| `PATCH /api/v1/hosted-rooms/:n` | owner: `{name?, description?, rating?, maxUsers?, roomPid?}`. |
| `PUT /api/v1/hosted-rooms/:n/scene` | owner: `{contents, roomPid?}`, from the client's `test.setRoomState`. |
| `DELETE /api/v1/hosted-rooms/:n` | owner (or moderator console): closes it; everyone in it is told (`room.closed`). |

A room: `{n, instanceId, chatId, name, description, roomPid, rating, maxUsers, ownerImvuId, ownerName, occupancy,
createdAt}` (`ownerName`: the owner's IMVU name as linked; `occupancy`: people in it now). A room whose owner account
is no longer linked to its owner (unlinked, or moved to another person), or whose owner is banned, is hidden (not
listed, `not_found`) until it's linked again. Closed rooms stay closed; their numbers aren't reused.

The scene's `contents` is the client's `room_contents`: a list of `[furniture instance ID (integer), product ID
(integer or a hub product ID string), placement (string)]`, up to 500 items, placement up to 200 characters. `hash`
is a hash of the stored scene (the client caches scenes by it): sha256, hex, of `[roomPid, contents]` as JSON.

## Realtime (the proxy's WebSocket)

From the proxy (the session's IMVU account, sent with `session`, must be linked to the person):

- `{"type": "room.join", "room": n}`: join. Answer `{"type": "room.joined", "room": n, "chat": chatId,
  "participants": [{"imvu_id", "seat"}], "sequence": s}` (the room's latest message number), or
  `{"type": "room.error", "room": n, "reason": "full" | "closed" | "adult" | "not_found" | "not_linked" | "too_many",
  "message": "..."}` (`too_many`: the session is in 5 hosted rooms already). Joining again (a reconnect) answers the
  same. A newcomer's seat is 0 until it sends `room.seat`. `maxUsers` counts IMVU accounts, so the same account
  joining from a second session isn't refused as full.
- `{"type": "room.leave", "room": n}`.
- `{"type": "room.seat", "room": n, "seat": k}`: the person sat down (`*seat k`); 0-99.
- `{"type": "room.send", "room": n, "mount": "messages" | "control", "message": "..."}` (up to 64 KB): to everyone
  else in the room. For `messages` the hub checks the JSON's `userId` is the sender's IMVU account and drops it
  otherwise (silently). Each session may send bursts of 20, then 10 a second; more is dropped. Malformed messages
  (bad room, seat, mount, a message over 64 KB, sending to a room it isn't in) get `{"type": "error", "message"}`.

From the hub:

- `{"type": "room.message", "room": n, "from": imvuId, "mount": "...", "message": "...", "sequence": s}`: numbered
  per room, from 1.
- `{"type": "room.participants", "room": n, "participants": [{"imvu_id", "seat"}]}`: whenever someone joins, leaves
  or sits (not to the one joining: `room.joined` has the list).
- `{"type": "room.closed", "room": n}`: the room closed, or this session is out of it: its IMVU account was unlinked
  or it sent `session` with another account, or the room became adult and its account isn't. (A lower `maxUsers`
  sends no one out; it only stops newcomers.)

A session closing leaves its rooms. The hub keeps the participants and message numbers in memory; messages aren't
stored (design.md: chat retention).

## The proxy's part

- **XML-RPC** for hosted IDs, answered by the proxy (never sent to IMVU): `test.getRoomCardInfo`,
  `chat.getOrMakeChat` (activity `publicroom-<owner>-<2100000000+n>`: joins, answers `chatId`, `seat`, `lastMessageId`,
  `participantUrl`), `test.getRoomState` (the scene, with community products as local IDs), `chat.getParticipants`,
  `chat.terminateChat`, `test.setRoomState` (owners: saved with `PUT .../scene`).
- **IMQ**: subscribing to `/chat/<chatId>` of a hosted room is answered by the proxy (result, `JoinedQueue`,
  `CreateMount`s for `control`, `messages`, `participants`); `SendMessage` on it goes to the hub as `room.send`, and
  `room.message` comes back as `G2cSendMessage`. `inv:/room/room-<owner>-<2100000000+n>` is answered with a result and a
  `node` mount, and nothing more.
- **Room list**: hosted rooms are added to `rooms_list_paginated.php`'s answer, and `room_occupancy/<owner>-<2100000000+n>`
  queues are answered from `room.participants`.

## Phase 2

Moderators, boots and bans, private rooms, invitations, images, favorites, ratings, recent rooms, occupancy pushed
to watchers, and participants' names. Everything in phase 1 still holds; this adds to it.

### Rooms (REST)

A room (in every answer that has one) also has:

| Field | |
| --- | --- |
| `privacy` | `"public"` (default) or `"private"` |
| `moderators` | IMVU account IDs, up to 20, in the order the owner gave them (never the owner's own account) |
| `moderatorNames` | their IMVU names, same order: the name of the linked account, or as IMVU gave it when added by name; `""` when not known |
| `image` | `<API URL>/api/v1/hosted-rooms/<n>/image?v=<16 hex>` (absolute; `v` changes with the image), or `null` |
| `favorite` | whether it's one of the signed-in person's favorites (`false` signed out) |
| `score` | the average rating, 1-5, two decimals; `0` if nobody rated it. (Named `score`, not `rating`: `rating` is already the room's `general`/`adult`.) |
| `ratings` | how many people rated it |

Who's who: the room's **owner** is, over REST, the person who made it; over realtime, its owner IMVU account
(`ownerImvuId`). A **moderator** is an IMVU account in `moderators`; over REST, a person is a moderator if one of their
linked accounts is.

| Route | |
| --- | --- |
| `POST /api/v1/hosted-rooms` | also takes `privacy?` |
| `PATCH /api/v1/hosted-rooms/:n` | (owner) also takes `privacy?` and `moderators?`: up to 20 entries, each an IMVU ID (integer, or a string of digits) or an IMVU name (looked up: linked accounts first, then IMVU, rate-limited; unknown: 404 `no_such_imvu_account`). Replaces the list; duplicates and the owner's account are dropped. More than 20: 400 `invalid`. Making a room private sends no one out. |
| `GET /api/v1/hosted-rooms` | public rooms, and private ones the person owns or moderates. `?mine=1`: the person's own (private too). `?favorites=1`: their favorites, latest starred first. `?recent=1`: the last 20 distinct rooms they joined (any of their accounts), latest first. Those three need a signed-in person (401 `signed_out`); adult rooms only for adults, as before; closed and hidden rooms left out. |
| `GET /api/v1/hosted-rooms/:n` | anyone may get a private room (it's unlisted, not secret). Also `myRating`: the person's own rating, `0` if none or signed out. |
| `GET /api/v1/hosted-rooms/:n/participants` | (anyone who may `GET /:n`, also signed out; same 404/410) `{participants: [{imvu_id, seat, name}]}`, as in `room.participants` |
| `GET /api/v1/hosted-rooms/:n/bans` | (owner or moderator) `{bans: [{imvuId, byImvuId, until, createdAt}]}`: bans in force, latest first; `until` ISO time or `null` (for good). Others: 403 `forbidden`. |
| `DELETE /api/v1/hosted-rooms/:n/bans/:imvu` | (owner only) lifts a ban: 204; 404 if there's none. Logged (`hosted_room.unban`). |
| `PUT /api/v1/hosted-rooms/:n/image` | (owner) multipart, field `image`: a PNG or JPEG (by its magic bytes, whatever the declared type), up to 512 KB; else 400 `invalid`. Stored as uploaded. → `{room}`. 30 an hour. |
| `DELETE /api/v1/hosted-rooms/:n/image` | (owner) → `{room}` with `image: null` |
| `GET /api/v1/hosted-rooms/:n/image` | (anyone who may `GET /:n`) the image, with its `Content-Type`, `ETag` (`If-None-Match` answers 304), `Cache-Control: public, max-age=3600` (`private` for adult rooms), `X-Content-Type-Options: nosniff`; 404 if none |
| `PUT /api/v1/hosted-rooms/:n/favorite` | (signed in, a room they may see) stars it: 204, also if starred already |
| `DELETE /api/v1/hosted-rooms/:n/favorite` | 204 |
| `PUT /api/v1/hosted-rooms/:n/rating` | `{score}` (integer 1-5) → `{room, myRating}`; replaces their earlier rating. Owners can't rate their own room (403 `forbidden`). |
| `DELETE /api/v1/hosted-rooms/:n/rating` | removes their rating: 204 |

A visit is recorded when an IMVU account joins a hosted room (a new member; not a re-join of a session already in
it): per person, the room, the account and the time; the latest 50 per person are kept.

### Realtime

**Participants** everywhere (`room.joined`, `room.participants`, `room.occupancy`, `GET .../participants`) are
`{"imvu_id": X, "seat": k, "name": "..."}`; `name` is the IMVU username of the hub's verified link for that account
(as of when it joined), `""` if unknown.

**Joining** (`room.join`) may carry `"invite": id`. New `room.error` reasons, checked in this order after phase 1's
`not_linked`, `not_found`, `closed`, `adult`: `"banned"` (a ban in force on the session's account), then `"private"`
(a private room, and the account isn't its owner account, a moderator, already let in, or holding an accepted,
unexpired invite for this room and account), then `too_many`, `full`.

An invite used to join is spent, and the account is **let in**: it may join again without one (a reconnect, another
session) until it sends `room.leave` and none of its sessions is still in the room, or it's booted. (A connection
dropping doesn't end it. It's kept in memory: a hub restart ends it.)

**Boot and ban**, from the owner account or a moderator (needn't be in the room):

- proxy → hub `{"type": "room.boot", "room": n, "imvu_id": X, "ban"?: false, "minutes"?: 0}`. `ban` true stores a
  ban; `minutes` 0 (default) is for good, else 1 to 5,270,400 (about ten years). Malformed: `{"type": "error",
  "message": "bad imvu_id" | "bad ban" | "bad minutes" | "bad room"}`.
- hub → proxy (the sender) `{"type": "room.boot_result", "room": n, "imvu_id": X, "ok": true, "ban": bool}`, or
  `{"type": "room.boot_result", "room": n, "imvu_id": X, "ok": false, "reason": "...", "message": "..."}` with
  `reason` `"not_linked"`, `"not_found"`, `"closed"` or `"forbidden"`: the sender isn't the owner account or a
  moderator; X is the owner account (nobody boots the owner); X is a moderator and the sender isn't the owner
  account; or X is the sender.
- Every session of X in the room gets `{"type": "room.closed", "room": n, "reason": "booted"}` and is out; the others
  get `room.participants`; watchers `room.occupancy`. A boot without a ban doesn't stop X coming back (except into
  a private room, which needs a new invite).
- Logged: `hosted_room.boot` or `hosted_room.ban`, target the room number, detail `{imvu: X, by: sender's IMVU ID}`
  (and `minutes` for a ban), actor the sender's person. A banned moderator stays a moderator (the owner removes them
  from `moderators`).

**Invitations**:

- proxy → hub `{"type": "room.invite", "room": n, "imvu_id": X}`: from a session in the room (public rooms), or from
  the owner account or a moderator, in it or not (private rooms). 10, then 10 a minute per session.
- hub → proxy (the sender) `{"type": "room.invite_result", "room": n, "imvu_id": X, "ok": true, "invite": id}`, or
  `ok: false` with `reason` `"not_linked"`, `"not_found"`, `"closed"`, `"forbidden"` (private room, not owner or
  moderator), `"not_in_room"` (public room, the sender isn't in it), `"banned"` (X is banned from the room),
  `"adult"` (an adult room, and none of X's sessions counts as adult) or `"rate_limited"`, and `message`. X being the
  sender: `{"type": "error", "message": "bad imvu_id"}`.
- When `ok`: every session whose IMVU account is X gets `{"type": "room.invited", "room": n, "invite": id, "from":
  sender's IMVU ID, "room_name": "...", "owner_name": "..."}` (`owner_name`: the owner account's IMVU name). If X has
  no session, the sender instead gets `{"type": "room.invite_answer", "invite": id, "to": X, "accept": false,
  "offline": true}` right after the result, and the invite is dropped.
- proxy (X's) → hub `{"type": "room.invite_reply", "invite": id, "accept": bool, "note"?: "..."}`. The first answer
  counts. `note`: control characters become spaces, trimmed, up to 200 characters, left out when empty. Errors:
  `{"type": "error", "message": "no such invite" | "already answered" | "bad accept" | "bad note"}` (`no such invite`
  also when it expired or the session's account isn't X).
- hub → proxy (every session of the sender's IMVU account) `{"type": "room.invite_answer", "invite": id, "to": X,
  "accept": bool, "note"?: "..."}`.
- An invite: single use, valid 10 minutes from when it was made (accepting doesn't extend it), for that room and
  account. Kept in memory only; closing the room drops its invites. `invite` ids are opaque strings (base64url).

**Occupancy**:

- proxy → hub `{"type": "room.watch", "rooms": [n, ...]}`: replaces the session's watched set (up to 100; `[]`
  stops). Not a list of room numbers, or over 100: `{"type": "error", "message": "bad rooms"}`. Rooms the session
  may not see are left out silently: no such room, closed or hidden; adult rooms for a session whose account isn't
  adult; private rooms unless its account is the owner account or a moderator. That's checked when it watches.
- hub → proxy, once per watched room right after, then whenever the room's participants change (join, leave, seat,
  boot): `{"type": "room.occupancy", "room": n, "participants": [{"imvu_id", "seat", "name"}]}`. A room closing sends
  `participants: []` and stops watching it. A session closing stops its watching.

### The proxy's part (phase 2)

- Room cards and lists: `privacy`, `image`, `score`/`ratings` from the room views; people in a room by name from
  `participants` (`name`), or `GET .../participants` for a room it isn't in or watching.
- `room_occupancy/<owner>-<2100000000+n>` queues: from `room.watch`/`room.occupancy` instead of polling.