VK API Kotlin Client

В связи с закрытием Bintray библиотека нигде не опубликована, не поддерживается, и из-за любви VK ломать обратную совместимость к использованию не рекомендуется.

Использует:

• kotlinx.coroutines
• kotlinx.serialization
• ktor-client

Статус покрытия методов API:

Раздел	Кол-во методов
Account	18 из 19	✔️
AppWidgets	0 из 8	✖️
Apps	0 из 8	✖️
Auth	0 из 2	✖️
Board	0 из 13	✖️
Database	0 из 10	✖️
Docs	11 из 11	✔️
Fave	23 из 23	✔️
Friends	18 из 18	✔️
Gifts	1 из 1	✔️
Groups	46 из 46	✔️
LeadForms	0 из 7	✖️
Likes	4 из 4	✔️
Market	0 из 24	✖️
Messages	39 из 39	✔️
Newsfeed	0 из 16	✖️
Notes	0 из 10	✖️
Notifications	0 из 3	✖️
Pages	0 из 8	✖️
Photos	46 из 46	✔️
Polls	0 из 9	✖️
PrettyCards	0 из 6	✖️
Search	0 из 1	✖️
Stats	0 из 3	✖️
Status	0 из 2	✖️
Storage	0 из 3	✖️
Stories	0 из 13	✖️
Streaming	0 из 5	✖️
Users	7 из 6	✔️
Utils	7 из 7	✔️
Video	24 из 24	✔️
Wall	23 из 23	✔️
Widgets	0 из 2	✖️

Зачем и чтобы что

Библиотека пишется руками (:see_no_evil:), так как документация у VK не редко серьезно хромает. Преследуется цель сделать использование библиотеки максимально комфортным в плоскости одной из главных фич языка - nullable-типов, а также задействовать другие его особенности: корутины, мультиплатформенный HTTP-клиент (ktor) и мультиплатформенную сериализацию, опциональные именованные параметры функций заместо билдеров и т.д.

Библиотека доступна для большинства платформ (весь список расположен выше), в том числе для Android и iOS.

Примеры использования

Подготовка

Первым делом подключите подходящий вам HTTP-клиент, например CIO:

implementation "io.ktor:ktor-client-cio:1.4.0"

Для Android используейте ktor-client-okhttp или ktor-client-android, для server-side рекомендую ktor-client-apache. Подробнее см. в документации и в репозиториях ktor.

Инициализация клиента

val apiClient = VkApiClient("your_token", HttpClient(CIO))
val api = VkApiUser(apiClient) // для токена пользователя
val api = VkApiCommunity(apiClient) // для токена сообщества

Использование методов

// отправка сообщения
val sendResult = api.messages.send(peerId = 1000000, message = "Hello!").execute()

// получение первых десяти друзей в алфавитном порядке
val friendsResult = api.friends.get(order = FriendsOrder.NAME, count = 10).execute()

Обработка результата

В качестве результата любого запроса возвращается монада объект VkResult. Подробнее ознакомиться с концепцией и примерами использования можно в ReadMe библиотеки, копипастом с которой он является (увы, сама библиотека Kotlin/Multiplatform не поддерживает).

Загрузка файлов (на примере документа)

val file = File("file.txt")
val fileContent = FileContent(file.name, file.readBytes())
val documents = api.docs.getUploadServer().execute()
    .flatMap { api.upload.document(it.uploadUrl, fileContent).execute() }
    .flatMap { api.docs.save(it.file, "Title.txt").execute() }

Использование метода execute

Опишите модель ответа (или используйте имеющиеся):

@Serializable
data class ExampleResponse(
    @SerialName("id") val id: Int,
    @SerialName("value") val value: String
)

Код для выполнения на сервере:

val exampleCode = """
    var response = [];
    var i = 0;

    while (i < 10) {
        response.push({
            "id": i,
            "value": "something"
        });

        i = i + 1;
    }

    return response;
""".trimIndent()

Вызовите метод:

val executeResult = api.execute(
    code = exampleCode,
    serializer = ExampleResponse.serializer().list
).execute()

Дополнительно

Работа с битовыми масками

val scope = AccessPermissionsUser().apply { 
    friends = true
    photos = true
    messages = true
}.mask

DSL-builder клавиатуры для сообщений сообществ

@Serializable
data class ExamplePayload(@SerialName("key") val key: String)

keyboard { 
    buttonsRow { 
        positiveButton("OK")
    }
    buttonsRow { 
        defaultButton("Button with payload") {
            payload = MessagePayload.from(ExamplePayload("value"))
        }
        defaultButton("Simple button")
    }
    buttonsRow { 
        negativeButton("Cancel")
    }
}

Конвертация идентификаторов

1.chatIdToPeerId // == 2000000001
1.communityIdToPeerId // == -1

2000000001.peerIdToChatId // == 1
-1.peerIdToCommunityId // == 1

2000000001.isChatPeerId // == true
-1.isCommunityPeerId // == true
1.isUserPeerId // == true

License

Copyright 2020 Danil Yudov

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0
   
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.