yamka.sus

include impostor.sus
set output html
set html_topbar_logo /home/portasynthinca3/yamka_press_kit/icons/icon_color_on_transparency.png
set html_topbar_title Yamka API

enum(2) ErrorCode {
    @> Internal server error <@
    internal_error(0),
    @> Invalid email supplied to log_in() <@
    invalid_email(1),
    @> Invalid password supplied to log_in() <@
    invalid_password(2),
    @> Invalid 2FA code supplied to the MFA confirmation <@
    invalid_mfa_code(3),
    @> Missing token permission <@
    token_perm_denied(4),
    @> Permission denied (other reasons) <@
    permission_denied(5),
    @> Invalid access token supplied to auth() <@
    invalid_access_token(6),
    @> Failed to perform a contact-related action <@
    contact_error(7),
    @> Invalid username supplied to User.send_friend_rq() <@
    invalid_username(8),
    @> Invalid invitation code supplied to Group.join() <@
    invalid_invite(9),
    @> Invalid code supplied to confirm_email() <@
    invalid_confirmation_code(10),
    @> Poll-related error <@
    poll_error(11),
    @> Key-related error <@
    key_error(12),
    @> Invalid credential(s) supplied to change_password() <@
    invalid_credential(13)
}

enum(1) State {
    awaiting_login(0)
}
set default_state awaiting_login

@> The user has to solve a captcha <@
confirmation Captcha(0) {
    request {
        image_url: Str[match: /https:\/\/.+\.png/];
    }
    response {
        solved: Str[len: 3..8];
    }
}

@> The user has to provide a 2FA 6-/8-digit code <@
confirmation MFA(1) {
    request { }
    response {
        code: Str[match: /[0-9]{6,8}/];
    }
}

@> Represents access token permissions <@
bitfield(4) AccessTokenPerm {
    see_profile(0),
    see_relationships(1),
    see_groups(2),
    see_direct_messages(3),
    edit_profile(4),
    edit_relationships(5),

    send_group_messages(6),
    send_direct_messages(7),
    receive_group_messages(8),
    read_group_message_history(9),
    receive_direct_messages(10),
    read_direct_message_history(11),
    delete_group_messages(12),
    delete_direct_messages(13),

    create_groups(14),
    edit_groups(15),
    delete_groups(16),
    join_groups(17),
    leave_groups(18),
    ban_memers(19),
    kick_members(20),
    manage_roles(21),
    delete_others_messages(22),

    create_polls(23),
    vote_in_polls(24),

    @> The user is a bot <@
    bot(26)
}

@> Acquire an access token <@
globalmethod log_in(0) {
    email: Str[match: /[^\t \r\n@]+@[^\t \r\n@]+/];
    password: Str[len: 5..64];
    perms: AccessTokenPerm;
    @> A randomly generated string unique for every user agent <@
    id_str: Str[len: 16..64];

    returns {
        token: Str[match: /\w{16,64}/];
    }

    ratelimit 3 every 30s;
    states { awaiting_login }
    errors { invalid_email, invalid_password, invalid_mfa_code }
    confirmations { Captcha, MFA }
}

@> Authorize using an access token <@
globalmethod auth(1) {
    token: Str[match: /\w{16,64}/];

    returns {
        @> The user associated with this token <@
        user: User;
        @> The user agent associated with this token <@
        agent: Agent;
    }

    ratelimit 3 every 60s;
    states { awaiting_login }
    errors { invalid_access_token }
}

entity User(0) {
    id: Int(8);
}

entity Agent(1) {
    id: Int(8);
}