namespace files

import common
import async

alias TagText = String(min_length=1, max_length=32, pattern="[\\w]+")

union Tag
    "Tag that can be added in multiple ways."

    user_generated_tag UserGeneratedTag
        "Tag generated by the user."

    example default
        user_generated_tag = default


struct UserGeneratedTag
    tag_text TagText

    example default
        tag_text = "my_tag"


union BaseTagError
    path LookupError


#####################################
#      Add Tag to an item
#####################################
struct AddTagArg
    path Path
        "Path to the item to be tagged."

    tag_text TagText
        "The value of the tag to add. Will be automatically converted to lowercase letters."

    example default
        path = "/Prime_Numbers.txt"
        tag_text = "my_tag"

union AddTagError extends BaseTagError
    too_many_tags
        "The item already has the maximum supported number of tags."

route tags/add(AddTagArg, Void, AddTagError)
    "Add a tag to an item. A tag is a string. The strings are automatically converted to lowercase letters. No more than 20 tags can be added to a given item."

    attrs
        auth = "user"
        is_preview = true
        scope = "files.metadata.write"


#####################################
#      Remove Tag from a item
#####################################

struct RemoveTagArg
    path Path
        "Path to the item to tag."

    tag_text TagText
        "The tag to remove. Will be automatically converted to lowercase letters."

    example default
        path = "/Prime_Numbers.txt"
        tag_text = "my_tag"

union RemoveTagError extends BaseTagError
    tag_not_present
        "That tag doesn't exist at this path."

route tags/remove(RemoveTagArg, Void, RemoveTagError)
    "Remove a tag from an item."

    attrs
        auth = "user"
        is_preview = true
        scope = "files.metadata.write"

###############################################
#      Get tags by item
###############################################
struct GetTagsArg
    paths List(Path)
        "Path to the items."

    example default
        paths = ["/Prime_Numbers.txt"]

struct PathToTags
    path Path
        "Path of the item."
    tags List(Tag)
        "Tags assigned to this item."
    example default
        path = "/Prime_Numbers.txt"
        tags = [default]

struct GetTagsResult
    paths_to_tags List(PathToTags)
        "List of paths and their corresponding tags."

    example default
        paths_to_tags = [default]

route tags/get(GetTagsArg, GetTagsResult, BaseTagError)
    "Get list of tags assigned to items."

    attrs
        auth = "user"
        is_preview = true
        scope = "files.metadata.read"