VKHS
VKHS provides access to Vkontakte social network, popular
mainly in Russia. Library can be used to login into the network as a
standalone application (OAuth implicit flow as they call it). Having the access
token, it is possible to call VK API methods.
Features
- Provides access to VK API via
VKT monad and vkq command line tool.
- Supports HTTPS protocol.
- Supports
http_proxy variables.
- Handles interaction with VK Login form.
VKT monad is designed to handle long-running tasks and allows programs to recover
from errors like network errors or token expirations.
- Web.VKHS.API.Simple module defines handy API wrappers.
See example
runhaskell scripts.
TODO
Decrypt 'RepeatedForm' errors
Support storing access-tokens in a temp file
Still no support for captchas, one probably should hack defaultSupervisor
and add them.
File uploading still not functioning.
- Preserve cookies between sessions
- Make user-friendly multy-platform captcha display.
- Fix login automata behaviour regarding captcha failures.
- Re-test existing captcha-related functionality
- Re-implement VK monad as a Free monad special case.
- Runhaskell: handle some standard command line arguments.
- Network connection timeout is not handled by the coroutine supervisor.
- Enhance the way
vkq accepts arguments, support multy-line messages.
- Fix grammatical mistakes here and there. Any corrections will be kindly accepted.
- Minor issues here and there. Use
git grep FIXME to find them.
- Write simple RSS-feeder server, see specs
Installing
TODO: Drop a note about Stack
Installing from Hackage
In order to install VKHS, one typically should do the following
$ cabal update
$ cabal install VKHS
Installing from source
$ git clone https://github.com/grwlf/vkhs
$ cd vkhs
$ cabal install
Developing using Nix
The author of this project uses Nix as a main development
platform. The default.nix file contain Nix expression describing the environment
Developing via Nix shell environment
TODO: Check and document the usage of cabal repl with this package
$ git clone https://github.com/grwlf/vkhs
$ cd vkhs
$ nix-shell # Entering NIX development shell
# ./ghci.sh # GHCI wrapper script
> :lo Main # Usual development
> ^D
# cabal install # Shell provides access to cabal
# cabal sdist
# ^D
$ ...
Usual development
$ ghci -isrc:app/vkq:app/common
$ ^D
$ cabal install
./mktags.sh script may be used to build ctags tags file supported by many
text editors. The script uses hasktags via haskdogs tools, available on
Hackage.
$ haskdogs
VKQ command line application
vkq is a command line tool which demonstrates API usage. It can be used for
logging in, -downloading music- and reading wall messages. Call vkq --help or
vkq command --help to read online help.
Logging in to VK
In order to send API requests, the VK client typically needs an access token.
vkq receives it as a result of signing in. Once received, the token may be
saved to VKQ_ACCESS_TOKEN environment variable, into .vkhs-access-token
file or passed to future instances directly using -a argument.
Saving access token in the environment variable
$ vkq login user@mail.org pass123
d8a41221616ef5ba19537125dc0349bad9d529fa15314ad765911726fe98b15185ac41a7ca2c62f3bf4b9
$ export VKQ_ACCESS_TOKEN=d785932b871f096bd73aac6a35d7a7c469dd788d796463a871e5beb5c61bc6c96788ec2
Alternatively, result may be achieved using --eval option
$ eval `vkq login user@mail.org pass123 --eval`
Saving access token to file
VKQ will cache the access token into a file. Newer versions of VKHS have
--access-token-flag option enabled by default. Set it to empty value to
disable the caching.
vkq allows user to call arbitrary API method. The generic interface is as follows:
$ vkq api --help
Usage: vkq api [--verbose] [--req-per-sec N] [--interactive] [--appid APPID]
[--user USER] [--pass PASS] [-a ACCESS_TOKEN]
[--access-token-file FILE] METHOD [PARAMS] [--pretty]
Call VK API method
Available options:
--verbose Be verbose
--req-per-sec N Max number of requests per second
--interactive Allow interactive queries
--appid APPID Application ID, defaults to VKHS
--user USER User name or email
--pass PASS User password
-a ACCESS_TOKEN Access token. Honores VKQ_ACCESS_TOKEN environment
variable
--access-token-file FILE Filename to store actual access token, should be used
to pass its value between sessions
METHOD Method name
PARAMS Method arguments, KEY=VALUE[,KEY2=VALUE2[,,,]]
--pretty Pretty print resulting JSON
-h,--help Show this help text
The session may look like the following:
$ vkq api 'users.get'
{"response":[{"first_name":"Сергей","uid":222222,"last_name":"Миронов"}]}
$ vkq api 'messages.send' 'user_id=333333' 'message="Hi there!!!"'
{"response":57505}
$ vkq api 'groups.search' 'q=Haskell'
{
"response": [
30,
{
"screen_name": "ml_mat_asm",
"photo": "https://pp.userapi.com/c638217/v638217626/54113/v5Ib71-dDzo.jpg",
"is_closed": 0,
"photo_medium": "https://pp.userapi.com/c638217/v638217626/54112/Nu_si987vOc.jpg",
"name": "Matlab | Assembler | MathCAD | Haskell | Prolog",
"photo_big": "https://pp.userapi.com/c638217/v638217626/54111/HGnUbgUorVU.jpg",
"gid": 78651325,
"is_admin": 0,
"is_member": 0,
"type": "page"
},
...
}
VKHS library/runhaskell mode
Starting from 1.7.2 the library supports runhaskell-mode.
#!/usr/bin/env runhaskell
{-# LANGUAGE RecordWildCards #-}
import Web.VKHS
import Web.VKHS.Imports
main :: IO ()
main = runVK_ defaultOptions $ do
Sized cnt cs <- getCountries
forM_ cs $ \Country{..} -> do
liftIO $ tputStrLn co_title
When executed, the program asks for login/password and outputs list of countries
known to VK. getCountries and several other methods are defined in
Web.VKHS.API.Simple.
The distribuption contains ./app/runhaskell folder with a couple of examples.
Debugging
Verbosity may be increased using --verbose flag or o_verbose field of
GenericOptions. Login automata saves latest.html file during operation.
References
License
BSD3 license
Copyright (c) 2018, Sergey Mironov grrwlf@gmail.com