summaryrefslogtreecommitdiff
path: root/README.md
blob: 6c813782ca886a8bbb75e0850af5c5af9302d521 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
VKHS
====

VKHS provides access to [Vkontakte](http://vk.com) 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 various API methods to -query audio files-
(disabled by VK) or retrieve wall messages.

Features
--------

* Provides access to VK API. Interface options include: VK monad and `vkq` command
  line tool.
* Uses HTTPS protocol.
* Solves login form interaction, may be used to operate new/disposable VK accounts.
* VK monad is designed as an interruptable coroutine. The supervisor supports
  ondemand re-login, and may be used for long-running tasks.
* Project includes a set of `Web.VKHS.API.Simple` wrappers designed to be
  copied into `runhaskell` scripts and tweaked according to ones need.
* No more dependencies on curlhs/taglib.

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.
* Re-implement VK monad as a Free monad special case
* Runhaskell: handle some standard command line arguments
* Minor issues here and there. Use `git grep FIXME` to find them
* File uploading still not functioning.
* Network connection timeout is not handled by the coroutine supervisor.
* Enhance the way `vkq` accepts arguments, support multy-line messages.
* Grammatical mistakes. Any corrections will be kindly accepted.

Installing
==========

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](http://nixos.org) as a main development
platform. The `default.nix` file contain Nix expression describing the environment

#### Entering Nix shell environment

    $ git clone https://github.com/grwlf/vkhs
    $ cd vkhs
    $ nix-shell

#### Usual development

    $ ghci -isrc:app/vkq:app/common
    $ cabal install
    $ ^D

#### Returning to the system shell

    $ ^D
    $ nix-build
    $ ls ./result


Building ctags file
-------------------

`./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.


Performing API calls
--------------------

`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 "messages.send" "user_id=111111,message=\"test\""  --pretty
    bd7da7e9cfb4cc12c0a49093173ca8785c7d6c918f00edb7315bb8526f5f372f1174b643e50e1a47d35da

    $ vkq api "users.get" ""
    {"response":[{"first_name":"Сергей","uid":222222,"last_name":"Миронов"}]}

    $ vkq api "messages.send" "user_id=333333,message=Hi theree!"
    {"response":57505}

    $ vkq api "groups.search" "q=Haskell"
		$ vkq api "groups.search" "q=Haskell" --pretty
    {
        "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
==========
* Implicit-flow authentication, see
  [documentation in Russian](http://vk.com/developers.php?oid=-1&p=Авторизация_клиентских_приложений)
  for details
* [VK API documentation](https://vk.com/dev/methods)

License
=======

BSD3 license

Copyright (c) 2014, Sergey Mironov <grrwlf@gmail.com>