--[[
    The shape every housing adapter returns.

        {
            id          = "94273",          -- string, unique, stable
            label       = "Ocean Drive 23", -- what the player calls the place
            tag         = "#1",             -- the small second line
            owned       = true,             -- false when it is only a key
            keyholders  = {                 -- always a list, may be empty
                { id = "char1:abc", name = "John Doe" }
            },
            garage      = true,             -- boolean
            coords      = { x = 0.0, y = 0.0, z = 0.0 },  -- nil if unknown
            tier        = 3,                -- optional
            price       = 1000,             -- optional
            apartment   = false,            -- optional
            canTransfer = true,             -- this script can hand the place over
            canLocate   = true,             -- this script can point a GPS at it
            canGiveKey  = true,             -- this script can grant someone a key
            canRemoveKey = true,            -- ...and take one back
            canLock     = true,             -- ...and lock the front door
            locked      = false,            -- the door's state, when it is known
            bills       = {                 -- what is owed on the place
                { id = 'water', amount = 1210, paid = false }
            },
            services    = {                 -- and what has been used
                { id = 'water', connected = true, used = 1210.35, unit = 'L' }
            },
            upgrades    = { 'doorbell' }    -- ids of what the place has
        }

]]


---@param fields table
---@return table
function HouseEntry(fields)
    fields = fields or {}

    local id = fields.id
    if id ~= nil then id = tostring(id) end

    return {
        id = id,
        label = fields.label or fields.name or (id and ('#' .. id)) or 'Unknown',
        tag = fields.tag,
        owned = fields.owned ~= false,
        keyholders = fields.keyholders or {},
        garage = fields.garage and true or false,
        coords = fields.coords,
        tier = fields.tier,
        price = fields.price,
        apartment = fields.apartment and true or false,
        canTransfer = fields.canTransfer and true or false,
        canLocate = fields.canLocate and true or false,
        canGiveKey = fields.canGiveKey and true or false,
        canRemoveKey = fields.canRemoveKey and true or false,
        canLock = fields.canLock and true or false,
        bills = fields.bills or {},
        services = fields.services or {},
        upgrades = fields.upgrades or {},
        locked = fields.locked
    }
end


---@param id string|nil the identifier the script knows them by
---@param name string|nil
---@return table
function HouseKey(id, name)
    return {
        id = id and tostring(id) or nil,
        name = name or (id and tostring(id)) or 'Unknown'
    }
end


---@param source table|nil
---@param map fun(key: any, value: any): table|nil
---@return table
function HouseKeys(source, map)
    local out = {}

    if type(source) ~= 'table' then
        return out
    end

    for key, value in pairs(source) do
        local entry = map(key, value)
        if entry then
            out[#out + 1] = entry
        end
    end

    return out
end


---@param coords table|vector3|nil
---@return boolean
function HouseWaypoint(coords)
    if not coords then return false end

    local x = coords.x or coords[1]
    local y = coords.y or coords[2]

    if not x or not y then return false end

    SetNewWaypoint(x + 0.0, y + 0.0)
    return true
end