clucker-examples

;; To use Twitter's APIs (and thus clucker), you must have:
;; (1) a Twitter account, and
;; (2) an "application" created at https://apps.twitter.com/

;; Once you've created your Twitter application, you can generate the
;; consumer key & secret, and your access-token & access-token-secret
;; at the same URL. Fill those values in below.

;; Clucker organization and usage
;; ----------------------------------

;; The full list of available Twitter REST api endpoints can be found
;; here: https://dev.twitter.com/rest/public

;; Each Twitter api endpoint has a URL beginning with
;; https://api.twitter.com/1.1/ followed by a unique path, followed by
;; an extension (typically .json). The unique path, minus the
;; extension, determines the clucker method. For example, the URL to
;; request a user's timeline (list of tweets) is
;; https://api.twitter.com/1.1/statuses/user_timeline.json
;; The corresponding clucker method is `statuses-user-timeline`.

;; Many Twitter endpoints have optional and/or required parameters.
;; See, for example,
;; https://dev.twitter.com/rest/reference/get/statuses/user_timeline
;; Supply these to clucker methods as keywords. Each keyword value is
;; converted to a URL encoded string. For example:

;; (statuses-user-timeline #:screen_name "theglitchmob" #:count 50)

;; Each clucker method has it's own customizable reader (ultimately
;; passed on to call-with-input-request) that reads out Twitter's
;; response. By default, these readers are `read-line`. You will
;; likely want to set them to something like `read-json` to parse the
;; result. Readers are settable parameters with the naming scheme
;; [method-name]-reader. Thus, the user timeline reader can be set to
;; parse the resulting json by: 

;; (statuses-user-timeline-reader read-json)

;; Once last point:
;; Unlike in the examples below, rather than repeatedly calling
;; (with-oauth ...) over and over, you would likely move this higher
;; up in your code and call it only once in your application. 
;; i.e.,
;; (with-oauth twitter user-token
;; 	    (lambda ()
;; 	      (run-twitter-client ...)))

;; EXAMPLES FOLLOW:

;; Deps
(use clucker medea oauth-client)

;; Let's set some clucker parameters to use read-json
(account-verify-credentials-reader read-json)
(search-tweets-reader read-json)
(followers-list-reader read-json)

;; Replace with valid keys/tokens 
(define twitter
  (twitter-service #:consumer-key "ksHFNafmgp72n54H2"
		   #:consumer-secret "owNlks73nHs0f"))

;; User tokens. 
(define user-token
  (twitter-token-credential #:access-token "1234-ksdfnr"
			    #:access-token-secret "ksdfn7H"))


;; Example 1
;; ------------------------------------------------------------------------
;; Let's verify that we've entered our credentials. NOTE: this step is
;; not necessary to use clucker's methods. But it is likely a step you
;; would want in an application to ensure the user has supplied the
;; correct credentials. If this works, you get confirmation. If not,
;; it returns a 401 status code and an error message
(define result
  (with-oauth twitter user-token
	      (lambda () (account-verify-credentials))))
;; Inspect and enjoy
(pp result)


;; Example 2
;; ------------------------------------------------------------------------
;; Search for 10 tweets including chicken AND scheme
(define tweets
  (with-oauth twitter user-token
	      (lambda ()
		(search-tweets #:q "chicken AND scheme" #:count 10))))
;; Inspect and enjoy
(pp tweets)

;; Let's view the text of each tweet
(let ((statuses (vector->list (alist-ref 'statuses tweets))))
  (for-each
   (lambda (tweet) (print (alist-ref 'text tweet))) statuses))


;; Example 3
;; ------------------------------------------------------------------------
;; Let's check out 20 followers of The Glitch Mob
(define followers
  (with-oauth twitter user-token
	      (lambda ()
		(followers-list #:screen_name "theglitchmob"
				#:count 20))))
;; Inspect and enjoy
(pp followers)

;; List each follower's name next to their screen name
(let ((user-list (vector->list (alist-ref 'users followers))))
  (for-each
   (lambda (indv)
     (display (alist-ref 'screen_name indv))
     (display " ==> ")
     (display (alist-ref 'name indv))
     (newline))
   user-list))