/*
 * SPDX-License-Identifier: GPL-3.0-or-later
 */
package com.runicgateway.app.data.api

import com.runicgateway.app.data.api.dto.CharProfileDto
import com.runicgateway.app.data.api.dto.CreateGameAccountRequest
import com.runicgateway.app.data.api.dto.PlayerHouseDto
import com.runicgateway.app.data.api.dto.RosterDto
import com.runicgateway.app.data.api.dto.ShardLinkDto
import com.runicgateway.app.data.api.dto.ShardLinkRequest
import com.runicgateway.app.data.api.dto.ShardLinkResultDto
import com.runicgateway.app.data.api.dto.VendorSaleDto
import com.runicgateway.app.data.api.dto.VendorSnapshotDto
import retrofit2.http.Body
import retrofit2.http.GET
import retrofit2.http.POST
import retrofit2.http.Path

/**
 * A player's own game data + game-account linking (PLAN.md §6.3), over the
 * bearer-gated `/player/shard/…` surface. Every read is ownership-checked
 * server-side; a `503` means the shard/sidecar is down → the UI renders "offline,
 * retry" (§7). All reads ride the main authed client (bearer + refresh-on-401).
 */
interface PlayerShardApi {

    /** Confirm an in-game `[link` one-time code, tagging the game account to the user. */
    @POST("api/v1/player/shard/link")
    suspend fun link(@Body body: ShardLinkRequest): ShardLinkResultDto

    /** Provision a game account (hybrid signup) and auto-link it to the caller. */
    @POST("api/v1/player/shard/account")
    suspend fun createAccount(@Body body: CreateGameAccountRequest): ShardLinkResultDto

    /** The caller's linked game accounts. */
    @GET("api/v1/player/shard/accounts")
    suspend fun accounts(): List<ShardLinkDto>

    /** Character roster for a linked account. */
    @GET("api/v1/player/shard/roster/{account}")
    suspend fun roster(@Path("account") account: String): RosterDto

    /** A character sheet — only for a character on the caller's linked account. */
    @GET("api/v1/player/shard/char/{serial}")
    suspend fun char(@Path("serial") serial: String): CharProfileDto

    /** Player vendors for a linked account. */
    @GET("api/v1/player/shard/vendors/{account}")
    suspend fun vendors(@Path("account") account: String): VendorSnapshotDto

    /** Recent player-vendor sales across the caller's linked accounts. */
    @GET("api/v1/player/shard/sales")
    suspend fun sales(): List<VendorSaleDto>

    /** The caller's own houses (home/decay status). */
    @GET("api/v1/player/shard/houses")
    suspend fun houses(): List<PlayerHouseDto>
}
