"/admin/account/{bigscreenAccountId}/social/profile":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Social]
        operationId: getSocialProfileForAccount
        summary: Primary social profile for an account
        description: |
            Returns the account's primary `SocialProfile`. Admin shape — includes
            `bigscreenAccountId` and the full `SocialStats`. Backed by
            `SocialProfileLookup` in the cloud_api social subsystem.
        responses:
            "200":
                description: Social profile.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/SocialProfile.yaml" }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Account has no social profile yet.
                content:
                    application/json:
                        schema: { $ref: "../cloud-admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Moderator]

"/admin/account/{bigscreenAccountId}/social_profiles":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Social]
        operationId: getSocialProfilesForAccount
        summary: All social profiles for an account (debug)
        description: |
            Returns every `SocialProfile` row linked to the account — used for
            debugging migrations or unexpected duplicates. `SocialProfileLookup`
            normally enforces one profile per account, so this should usually
            return a single-element array.
        responses:
            "200":
                description: Social profiles.
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/SocialProfile.yaml" }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]

"/admin/account/{bigscreenAccountId}/social/history/{historyItemType}":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
        - in: path
          name: historyItemType
          required: true
          schema: { $ref: "../components/schemas/HistoryItemType.yaml" }
          description: |
              `HistoryItemType` filter. Optional in the underlying route
              (`/social/history{/:historyItemType}`) — when omitted, all
              classes are returned.
    get:
        tags: [Social]
        operationId: getSocialHistoryForAccount
        summary: Recently encountered users / rooms
        description: |
            Returns the account's social history — rooms joined, users met,
            activities engaged in. Items are the public projection
            (`HistoryItem.getPublicData()`).
        responses:
            "200":
                description: History entries.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [bigscreenAccountId, items, count]
                            properties:
                                bigscreenAccountId: { type: string }
                                historyItemType: { $ref: "../components/schemas/HistoryItemType.yaml" }
                                items:
                                    type: array
                                    items: { $ref: "../components/schemas/HistoryItem.yaml" }
                                count: { type: integer }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]

"/admin/account/{bigscreenAccountId}/social/graph/{socialGraphType}":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
        - in: path
          name: socialGraphType
          required: true
          schema:
              type: string
              enum: [Unknown, Blocked, Friends, Following, Muted, "0", "1", "2", "3", "4"]
          description: |
              `SocialGraphType` filter — see [`SocialGraphType`](../components/schemas/SocialGraphType.yaml).
              Accepts the member name or its numeric value. Optional in the
              underlying route — when omitted, all edges are returned.
    get:
        tags: [Social]
        operationId: getSocialGraphForAccount
        summary: Social graph edges for an account
        description: Returns the social-graph edges (friends / blocked / following / muted) involving this account.
        responses:
            "200":
                description: Graph edges page.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [bigscreenAccountId, items, count]
                            properties:
                                bigscreenAccountId: { type: string }
                                socialGraphType:
                                    $ref: "../components/schemas/SocialGraphType.yaml"
                                items:
                                    type: array
                                    items: { $ref: "../components/schemas/SocialGraphItem.yaml" }
                                count: { type: integer }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]

"/admin/social/graph/{graphItemId}":
    parameters:
        - in: path
          name: graphItemId
          required: true
          schema: { type: string }
    delete:
        tags: [Social]
        operationId: deleteSocialGraphItem
        summary: Delete a social-graph edge
        description: |
            Hard-deletes a single graph edge — used to undo erroneous
            friend / block entries surfaced by support. Restricted to
            `Admin`. **Returns plain text `OK`** — not JSON.
        responses:
            "200":
                description: Edge deleted. Body is the literal string `OK`.
                content:
                    text/plain:
                        schema: { type: string, example: OK }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: No edge with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin]

"/admin/account/{bigscreenAccountId}/social/stats":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Social]
        operationId: getSocialStats
        summary: Social counters for an account
        description: |
            Returns the account's `SocialStats` — friend / follower / blocked /
            notification / history counters plus `lastOnlineDate`.
        responses:
            "200":
                description: Social stats.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/SocialStats.yaml" }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]

"/admin/account/{bigscreenAccountId}/social/notifications":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Social]
        operationId: getSocialNotifications
        summary: List notifications for an account
        description: |
            Returns every `Notification` row stored for the account regardless
            of `notificationStatus` — admin shape, includes
            `senderBigscreenAccountId`, `recipientBigscreenAccountId`, and the
            DynamoDB `ttl`.
        responses:
            "200":
                description: Notifications.
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/SocialNotification.yaml" }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Admin]

"/admin/account/{bigscreenAccountId}/social/notification":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    post:
        tags: [Social]
        operationId: createAdminNotification
        summary: Send an admin notification
        description: |
            Creates a notification destined for the supplied account. Used for
            system messages (`AdminMessage`) and ad-hoc admin nudges. The
            recipient is the path account; the sender is the calling staff
            account.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [notificationType, title]
                        properties:
                            notificationType: { $ref: "../components/schemas/NotificationType.yaml" }
                            title: { type: string }
                            body: { type: string }
                            metaData:
                                type: object
                                description: |
                                    `NotificationMetaData` payload. Common keys:
                                    `roomId` (for `RoomInvite` / `KnockKnock`),
                                    `version`.
                                properties:
                                    roomId: { type: string }
                                    version: { type: string }
                                additionalProperties: true
                            expiryDate:
                                type: integer
                                description: |
                                    Optional override for the default 30-day
                                    application-level expiry (Unix seconds).
        responses:
            "200":
                description: Created notification.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/SocialNotification.yaml" }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Admin]

"/admin/social/notification/{notificationId}":
    parameters:
        - in: path
          name: notificationId
          required: true
          schema: { type: string }
    delete:
        tags: [Social]
        operationId: deleteSocialNotification
        summary: Delete a notification
        description: Hard-deletes a notification.
        responses:
            "200":
                description: Notification deleted.
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: No notification with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin]

"/admin/social/notification/{notificationId}/accept":
    parameters:
        - in: path
          name: notificationId
          required: true
          schema: { type: string }
    get:
        tags: [Social]
        operationId: acceptSocialNotification
        summary: Force-accept a notification (stub)
        description: |
            **Stub** — `acceptNotification` in `cloud/src/CloudAdminApi.ts`
            currently just returns plain text `OK` without firing any
            side effects. The intended behaviour: accept the notification
            on behalf of the recipient (driving e.g. `FriendRequest` →
            create the `Friends` edge, set `notificationStatus=Accepted`).
        deprecated: true
        responses:
            "200":
                description: Body is the literal string `OK`. No actual side effects today.
                content:
                    text/plain:
                        schema: { type: string, example: OK }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: No notification with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin]
