type: object
description: |
    Entry in a user's social history — a room they joined, a person they met,
    or an activity they engaged in. The shape here is the **public projection**
    returned from `getPublicData()` on `HistoryItem` in
    [`cloud/src/SocialAPI/Schemas.ts`](../../../../cloud/src/SocialAPI/Schemas.ts) —
    the stored row also carries a `bigscreenAccountId` (owner) and a `ttl`
    that are not surfaced.

    Two snapshot fields are present depending on `historyItemType`:
    - `historyItemType=Room` — `room` is set (a `SimpleRoomSnapshot`),
      `socialProfileSnapshot` is unset.
    - `historyItemType=User` — both `room` and `socialProfileSnapshot` are set.
    - `historyItemType=Activity` — neither snapshot is guaranteed.
required: [id, createdAt, historyItemType, historyVisibility]
properties:
    id:
        type: string
        description: |
            Stable hash of `(owner, target, room)` — used as the upsert key so
            re-encountering the same user in the same room does not duplicate
            history rows.
    createdAt:
        type: integer
        description: First-encounter time, Unix timestamp in **milliseconds**.
    historyItemType: { $ref: "./HistoryItemType.yaml" }
    historyVisibility: { $ref: "./HistoryItemVisibility.yaml" }
    roomId:
        type: string
        description: Room the encounter happened in (when applicable).
    room:
        type: object
        description: |
            `SimpleRoomSnapshot` of the room at the time of the encounter — a
            denormalized copy so the history entry survives room deletion.
        additionalProperties: true
    socialProfileSnapshot:
        description: |
            Snapshot of the encountered user's `PublicSocialProfile` at
            encounter time. Only present when `historyItemType=User`.
        oneOf:
            - $ref: "./PublicSocialProfile.yaml"
            - type: "null"
    metaData:
        type: object
        description: Free-form payload attached at write time.
        additionalProperties: true
example:
    id: "0a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789"
    createdAt: 1762462440000
    historyItemType: User
    historyVisibility: Default
    roomId: "room:abc1234567"
    room:
        roomId: "room:abc1234567"
        title: "Movie Night"
        visibility: "FriendsOnly"
    socialProfileSnapshot:
        socialId: "soc_01HZR67890ABC678DEF90GHJKM"
        username: "bob"
        smallImageUrl: "https://cdn.bigscreenvr.com/avatars/bob_sm.png"
    metaData: {}
