"/social/rooms":
    get:
        tags: [Social]
        operationId: getRoomsWithQuery
        summary: Search the caller's social rooms
        description: Returns rooms involving the caller's friend graph (friends-only public rooms, etc.).
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        parameters:
            - in: query
              name: query
              schema: { type: string }
            - in: query
              name: limit
              schema: { type: integer }
        responses:
            "200":
                description: Rooms.
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/PublicRoom.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }

"/social/history":
    get:
        tags: [Social]
        operationId: getSocialHistoryForUser
        summary: Caller's social history
        description: |
            Returns the caller's recent social history — rooms joined, users
            met, activities engaged in. Items are the public projection
            (`HistoryItem.getPublicData()`).
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        parameters:
            - in: query
              name: type
              description: Optional `HistoryItemType` filter.
              schema: { $ref: "../components/schemas/HistoryItemType.yaml" }
            - in: query
              name: limit
              schema: { type: integer }
        responses:
            "200":
                description: History page.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [items]
                            properties:
                                items:
                                    type: array
                                    items: { $ref: "../components/schemas/HistoryItem.yaml" }
                                cursorId:
                                    type: string
                                    description: Continuation cursor — pass on the next request to get the next page.
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }

"/social/friends":
    get:
        tags: [Social]
        operationId: getFriends
        summary: Caller's friends
        description: |
            Returns the caller's accepted `Friends` edges. Each item carries
            the public projection of the `SocialGraphItem` (`createdAt`,
            `ownerSocialId`, `targetSocialId`) plus an inlined
            `remoteSocialProfile` — the friend's `PublicSocialProfile`.
            Paginated.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Friends page.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [items]
                            properties:
                                items:
                                    type: array
                                    items:
                                        type: object
                                        properties:
                                            createdAt: { type: integer, description: Unix milliseconds. }
                                            ownerSocialId: { type: string }
                                            targetSocialId: { type: string }
                                            remoteSocialProfile: { $ref: "../components/schemas/PublicSocialProfile.yaml" }
                                cursorId: { type: string }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }

"/social/blocked":
    get:
        tags: [Social]
        operationId: getBlockedUsers
        summary: Caller's blocked users
        description: |
            Returns the users the caller has blocked. Each item carries the
            public projection of the `Blocked` `SocialGraphItem` plus the
            blocked user's `PublicSocialProfile`. Note the inverse —
            users who have blocked the caller — is intentionally not
            exposed. Paginated.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Blocked users page.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [items]
                            properties:
                                items:
                                    type: array
                                    items:
                                        type: object
                                        properties:
                                            createdAt: { type: integer, description: Unix milliseconds. }
                                            ownerSocialId: { type: string }
                                            targetSocialId: { type: string }
                                            remoteSocialProfile: { $ref: "../components/schemas/PublicSocialProfile.yaml" }
                                cursorId: { type: string }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }

"/social/profile/{socialId}":
    parameters:
        - in: path
          name: socialId
          required: true
          schema: { type: string }
          description: |
              Target social id. The path is `{/:socialId}` in Express — when the
              segment is omitted, the caller's own profile is returned. The
              caller's own profile carries the **full** `SocialStats` in `stats`;
              other profiles carry the `PublicSocialStats` projection.
    get:
        tags: [Social]
        operationId: getSocialProfile
        summary: Fetch a social profile
        description: |
            Returns a `PublicSocialProfile` by id. When called without a
            `socialId` segment, returns the caller's own profile (the path is
            registered with an optional segment).
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Profile.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/PublicSocialProfile.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: No profile with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }

"/social/profile/{socialId}/block":
    parameters:
        - in: path
          name: socialId
          required: true
          schema: { type: string }
    put:
        tags: [Social]
        operationId: createBlock
        summary: Block another user
        description: |
            Creates a `Blocked` edge owned by the caller, targeting `socialId`.
            Idempotent — the edge id is a deterministic hash, so re-asserting
            upserts the same row. Returns the JSON-encoded string `"OK"` on
            success.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Block created. Body is the JSON-encoded string `"OK"`.
                content:
                    application/json:
                        schema: { type: string, example: OK }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: No profile with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }

"/social/profile/{socialId}/unblock":
    parameters:
        - in: path
          name: socialId
          required: true
          schema: { type: string }
    put:
        tags: [Social]
        operationId: deleteBlock
        summary: Unblock a user
        description: |
            Deletes the caller's `Blocked` edge against `socialId`. Returns
            the JSON-encoded string `"OK"` on success.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Block removed. Body is the JSON-encoded string `"OK"`.
                content:
                    application/json:
                        schema: { type: string, example: OK }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: No matching block.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }

"/social/profile/{socialId}/remove_friend":
    parameters:
        - in: path
          name: socialId
          required: true
          schema: { type: string }
    get:
        tags: [Social]
        operationId: removeFriend
        summary: Remove a friend
        description: |
            Removes both `Friends` edge rows (the friendship is mutual, so two
            rows exist — one per direction). Returns the JSON-encoded
            string `"OK"` on success.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Friend removed. Body is the JSON-encoded string `"OK"`.
                content:
                    application/json:
                        schema: { type: string, example: OK }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: No matching friend edge.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }

"/social/notification":
    post:
        tags: [Social]
        operationId: createSocialNotification
        summary: Send a notification (e.g. friend request)
        description: |
            Creates a notification destined for another user — typically a
            `FriendRequest` or `RoomInvite`. The cooldown layer may reject
            with `TooSoon` / `AlreadyExists` (see `NotificationCooldownAction`).
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [recipientSocialId, notificationType]
                        properties:
                            recipientSocialId: { type: string }
                            notificationType: { $ref: "../components/schemas/NotificationType.yaml" }
                            title: { type: string }
                            body: { type: string }
                            metaData:
                                type: object
                                description: |
                                    `NotificationMetaData` — `roomId` for
                                    `RoomInvite` / `KnockKnock`, `version`
                                    where relevant.
                                properties:
                                    roomId: { type: string }
                                    version: { type: string }
                                additionalProperties: true
        responses:
            "200":
                description: Created notification.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/PublicNotification.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "403":
                description: Recipient has blocked the caller (or other privacy guard).
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
            "404":
                description: Recipient not found.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }

"/social/notifications":
    get:
        tags: [Social]
        operationId: getSocialNotifications
        summary: Caller's notifications
        description: |
            Returns the caller's notifications as `PublicNotification` objects
            (sender resolved into a `senderSocialProfile`, no
            `bigscreenAccountId` fields).
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Notifications.
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/PublicNotification.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }

"/social/notification/{notificationId}":
    parameters:
        - in: path
          name: notificationId
          required: true
          schema: { type: string }
    get:
        tags: [Social]
        operationId: getSocialNotification
        summary: Fetch one notification
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Notification record.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/PublicNotification.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: No notification with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
    delete:
        tags: [Social]
        operationId: deleteSocialNotification
        summary: Dismiss a notification
        description: |
            Sets `notificationStatus=Deleted`. The row is not hard-deleted —
            see the admin route for that.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Dismissed.
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: No notification with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }

"/social/notification/{notificationId}/read":
    parameters:
        - in: path
          name: notificationId
          required: true
          schema: { type: string }
    put:
        tags: [Social]
        operationId: readSocialNotification
        summary: Mark notification read
        description: Sets `notificationStatus=Read`.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Marked read.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/PublicNotification.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: No notification with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }

"/social/notification/{notificationId}/accept":
    parameters:
        - in: path
          name: notificationId
          required: true
          schema: { type: string }
    put:
        tags: [Social]
        operationId: acceptSocialNotification
        summary: Accept a notification
        description: |
            Sets `notificationStatus=Accepted` and drives any side effect the
            `notificationType` implies — e.g. accepting a `FriendRequest`
            creates the `Friends` edges and triggers an
            `AcceptedFriendRequest` notification back to the original sender.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Accepted; updated notification.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/PublicNotification.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: No notification with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }

"/social/notification/{notificationId}/decline":
    parameters:
        - in: path
          name: notificationId
          required: true
          schema: { type: string }
    put:
        tags: [Social]
        operationId: declineSocialNotification
        summary: Decline a notification
        description: Sets `notificationStatus=Declined` without firing the accept-side effect.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Declined; updated notification.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/PublicNotification.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: No notification with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }

"/social/search":
    post:
        tags: [Social]
        operationId: searchSocialProfiles
        summary: Search social profiles
        description: Searches profiles by username / display name. Rate-limited.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [query]
                        properties:
                            query: { type: string }
                            limit: { type: integer }
        responses:
            "200":
                description: Matching profiles.
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/PublicSocialProfile.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "429": { $ref: "../cloud-api.yaml#/components/responses/TooManyRequests" }
