version: v1-draft
exports:
    nd_scrobbler_is_authorized:
        description: IsAuthorized checks if a user is authorized to scrobble to this service.
        input:
            $ref: '#/components/schemas/IsAuthorizedRequest'
            contentType: application/json
        output:
            type: boolean
            contentType: application/json
    nd_scrobbler_now_playing:
        description: NowPlaying sends a now playing notification to the scrobbling service.
        input:
            $ref: '#/components/schemas/NowPlayingRequest'
            contentType: application/json
    nd_scrobbler_scrobble:
        description: Scrobble submits a completed scrobble to the scrobbling service.
        input:
            $ref: '#/components/schemas/ScrobbleRequest'
            contentType: application/json
    nd_scrobbler_playback_report:
        description: PlaybackReport sends a playback state report to the scrobbling service.
        input:
            $ref: '#/components/schemas/PlaybackReportRequest'
            contentType: application/json
components:
    schemas:
        IsAuthorizedRequest:
            description: IsAuthorizedRequest is the request for authorization check.
            properties:
                username:
                    type: string
                    description: Username is the username of the user.
            required:
                - username
        NowPlayingRequest:
            description: NowPlayingRequest is the request for now playing notification.
            properties:
                username:
                    type: string
                    description: Username is the username of the user.
                track:
                    $ref: '#/components/schemas/TrackInfo'
                    description: Track is the track currently playing.
                position:
                    type: integer
                    format: int32
                    description: Position is the current playback position in seconds.
            required:
                - username
                - track
                - position
        PlaybackReportRequest:
            description: PlaybackReportRequest is the request for playback report notifications.
            properties:
                username:
                    type: string
                    description: Username is the username of the user.
                track:
                    $ref: '#/components/schemas/TrackInfo'
                    description: Track is the track being played.
                state:
                    type: string
                    description: State is the current playback state (starting/playing/paused/stopped/expired).
                positionMs:
                    type: integer
                    format: int64
                    description: PositionMs is the current playback position in milliseconds.
                playbackRate:
                    type: number
                    format: float
                    description: PlaybackRate is the playback speed (1.0 = normal).
                playerId:
                    type: string
                    description: PlayerId is the unique client identifier.
                playerName:
                    type: string
                    description: PlayerName is the human-readable player name.
                timestamp:
                    type: integer
                    format: int64
                    description: Timestamp is the Unix timestamp when this report was generated.
            required:
                - username
                - track
                - state
                - positionMs
                - playbackRate
                - playerId
                - playerName
                - timestamp
        ScrobbleRequest:
            description: ScrobbleRequest is the request for submitting a scrobble.
            properties:
                username:
                    type: string
                    description: Username is the username of the user.
                track:
                    $ref: '#/components/schemas/TrackInfo'
                    description: Track is the track that was played.
                timestamp:
                    type: integer
                    format: int64
                    description: Timestamp is the Unix timestamp when the track started playing.
            required:
                - username
                - track
                - timestamp
        TrackInfo:
            description: TrackInfo contains track metadata.
            properties:
                id:
                    type: string
                    description: ID is the internal Navidrome track ID.
                title:
                    type: string
                    description: Title is the track title.
                album:
                    type: string
                    description: Album is the album name.
                artist:
                    type: string
                    description: Artist is the formatted artist name for display (e.g., "Artist1 • Artist2").
                albumArtist:
                    type: string
                    description: AlbumArtist is the formatted album artist name for display.
                artists:
                    type: array
                    description: Artists is the list of track artists.
                    items:
                        $ref: '#/components/schemas/ArtistRef'
                albumArtists:
                    type: array
                    description: AlbumArtists is the list of album artists.
                    items:
                        $ref: '#/components/schemas/ArtistRef'
                duration:
                    type: number
                    format: float
                    description: Duration is the track duration in seconds.
                trackNumber:
                    type: integer
                    format: int32
                    description: TrackNumber is the track number on the album.
                discNumber:
                    type: integer
                    format: int32
                    description: DiscNumber is the disc number.
                mbzRecordingId:
                    type: string
                    description: MBZRecordingID is the MusicBrainz recording ID.
                mbzAlbumId:
                    type: string
                    description: MBZAlbumID is the MusicBrainz album/release ID.
                mbzReleaseGroupId:
                    type: string
                    description: MBZReleaseGroupID is the MusicBrainz release group ID.
                mbzReleaseTrackId:
                    type: string
                    description: MBZReleaseTrackID is the MusicBrainz release track ID.
                libraryId:
                    type: integer
                    format: int32
                    description: |-
                        LibraryID is the ID of the library the track belongs to.
                        Only included if the plugin has library permission with filesystem access for the track's library.
                path:
                    type: string
                    description: |-
                        Path is the full path to the track file, relative to the library root.
                        Only included if the plugin has library permission with filesystem access for the track's library.
            required:
                - id
                - title
                - album
                - artist
                - albumArtist
                - artists
                - albumArtists
                - duration
                - trackNumber
                - discNumber
        ArtistRef:
            description: |-
                ArtistRef is the minimal information a plugin returns for Navidrome to match an
                artist against the library. It is a reference, not a full artist entity: it
                carries only matching keys (name and optional internal/MusicBrainz IDs) plus a
                few projection fields used when describing a track's participants, never
                descriptive data such as biographies or images.
            properties:
                id:
                    type: string
                    description: ID is the internal Navidrome artist ID (if known).
                name:
                    type: string
                    description: Name is the artist name.
                mbid:
                    type: string
                    description: MBID is the MusicBrainz ID for the artist.
                sortName:
                    type: string
                    description: SortName is the artist name used for sorting (if known).
                role:
                    type: string
                    description: Role is the participation category (e.g. "artist", "composer", "performer").
                subRole:
                    type: string
                    description: SubRole is a specialization within Role (e.g. the instrument for a performer).
            required:
                - name