melon-love / elm-gab-api / Gab

Client for the Gab.com API, documented at developers.gab.com.

This does NOT do authentication. You'll need to use billstclair/elm-oauth-middleware to get a Token. See the example directory.

The requests all come in two flavors, one which has the decoder built in, and returns a Cmd msg, and one for which you provide your own decoder. E.g.:

type Msg
   = ReceiveUser (Result Http.Error User)
   | ReceiveUserValue (Result Http.Error Value)
   ...

getTorbaCmd : OAuth.Token -> Cmd Msg
getTorbaCmd token =
    userProfile ReceiveUser token "a"

getTorbaParts : OAuth.Token -> RequestParts Msg
getTorbaParts token =
    userProfileParts Json.Decode.value ReceiveUserValue token "a"

Normal, Auto-Decoding Functions

You'll usually use these, not the Parts functions below.

Users

me : (Result Http.Error Types.User -> msg) -> OAuth.Token -> Platform.Cmd.Cmd msg

Return the logged-in user's profile information as a User record.

userProfile : (Result Http.Error Types.User -> msg) -> OAuth.Token -> String -> Platform.Cmd.Cmd msg

Return the logged-in user's profile information as a User record.

userFollowers : (Result Http.Error Types.UserList -> msg) -> OAuth.Token -> String -> Basics.Int -> Platform.Cmd.Cmd msg

Return the logged-in user's followers as a UserList record.

userFollowers wrapper token username before

before is the number of following users to skip before the listing starts. This enables scrolling through a long list.

userFollowing : (Result Http.Error Types.UserList -> msg) -> OAuth.Token -> String -> Basics.Int -> Platform.Cmd.Cmd msg

Return a list of users following the logged-in user, as a UserList record.

userFollowing wrapper token username before

before is the number of followers to skip before the listing starts. This enables scrolling through a long list.

User Interaction

followUser : (Result Http.Error Types.Success -> msg) -> OAuth.Token -> String -> Basics.Bool -> Platform.Cmd.Cmd msg

Follow or unfollow a user. Return value not interesting.

followUser wrapper token username unfollow

muteUser : (Result Http.Error Types.Success -> msg) -> OAuth.Token -> String -> Basics.Bool -> Platform.Cmd.Cmd msg

Mute or unmute a user. Return value not interesting.

muteUser wrapper token username unmute

This isn't currently implemented by the API, but I expect that to change.

Feeds

homeFeed : (Result Http.Error Types.ActivityLogList -> msg) -> OAuth.Token -> String -> Platform.Cmd.Cmd msg

Return posts in the home feed.

homeFeed wrapper token before

The posts returned will have dates before before. Pass the empty string to get the beginning of the list.

userFeed : (Result Http.Error Types.ActivityLogList -> msg) -> OAuth.Token -> String -> String -> Platform.Cmd.Cmd msg

Return posts for a user feed.

userFeed wrapper token user before

The posts returned will have dates before before. Pass the empty string to get the beginning of the list.

groupFeed : (Result Http.Error Types.ActivityLogList -> msg) -> OAuth.Token -> String -> String -> Platform.Cmd.Cmd msg

Return posts for a group feed.

groupFeed wrapper token group before

The posts returned will have dates before before. Pass the empty string to get the beginning of the list.

This is a guess at what this API command will look like. It doesn't yet exist.

popularFeed : (Result Http.Error Types.ActivityLogList -> msg) -> OAuth.Token -> Platform.Cmd.Cmd msg

Return the posts in the "popular" feed, as a ActivityLogList.

popularFeed wrapper token

popularUsers : (Result Http.Error Types.UserList -> msg) -> OAuth.Token -> Platform.Cmd.Cmd msg

Return a list of popular users, as a UserList record.

popularUsers wrapper token

Notifications

notifications : (Result Http.Error Types.NotificationsLog -> msg) -> OAuth.Token -> String -> Platform.Cmd.Cmd msg

Return notifications for the logged in user.

notifications wrapper token before

For notifications, the before parameter is a notification ID, not a date.

Posts

getPost : (Result Http.Error Types.Post -> msg) -> OAuth.Token -> String -> Platform.Cmd.Cmd msg

Get a single post.

getPost wrapper token postid

upvotePost : (Result Http.Error Types.Success -> msg) -> OAuth.Token -> String -> Basics.Bool -> Platform.Cmd.Cmd msg

Upvote or unupvote a post. Return value not interesting.

upvotePost wrapper token postid unupvote

downvotePost : (Result Http.Error Types.Success -> msg) -> OAuth.Token -> String -> Basics.Bool -> Platform.Cmd.Cmd msg

Downvote or undownvote a post. Return value not interesting.

downvotePost wrapper token postid undownvote

This will return an Http BadStatus error if you you're not authorized to downvote.

repost : (Result Http.Error Types.Success -> msg) -> OAuth.Token -> String -> Basics.Bool -> Platform.Cmd.Cmd msg

Repost or unrepost. Return value not interesting.

repost wrapper token postid unrepost

New Posts

newPost : (Result Http.Error Types.ActivityLog -> msg) -> OAuth.Token -> Types.PostForm -> Platform.Cmd.Cmd msg

Posting uses JSON, which is not in the spec, but is what the web client does.

postImage : (Result Http.Error String -> msg) -> OAuth.Token -> File -> Platform.Cmd.Cmd msg

Posting an image.

The String that comes back is a media ID, to be used in PostForm.media_attachments.

Parts Functions The Return a Value

These are mostly for the example, but if you need to get your hands on the raw return Value from the API, use these intead of the auto-decoding versions.

Users

meParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> Types.RequestParts msg

Return the logged-in user's profile information, using a custom decoder.

userProfileParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Types.RequestParts msg

Return the logged-in user's profile information, using a custom decoder.

userFollowersParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Basics.Int -> Types.RequestParts msg

Return the logged-in user's followers, using a custom decoder.

userFollowersParts wrapper decoder token username before

before is the number of following users to skip before the listing starts. This enables scrolling through a long list.

userFollowingParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Basics.Int -> Types.RequestParts msg

Return a list of users following the logged-in user, using a custom decoder.

userFollowingParts wrapper decoder token username before

before is the number of followers to skip before the listing starts. This enables scrolling through a long list.

User Interaction

followUserParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Basics.Bool -> Types.RequestParts msg

Follow or unfollow a user, with a custom decoder.

followUserParts decoder wrapper token username unfollow

muteUserParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Basics.Bool -> Types.RequestParts msg

Mute or unmute a user, with a custom decoder.

muteUserParts decoder wrapper token username unmute

This isn't currently implemented by the API, but I expect that to change.

Feeds

homeFeedParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Types.RequestParts msg

Return posts in the home feed, using a custom encoder.

homeFeedParts decoder wrapper token before

The posts returned will have dates before before. Pass the empty string to get the beginning of the list.

userFeedParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> String -> Types.RequestParts msg

Return posts for a user feed, using a custom decoder.

userFeedParts decoder wrapper user token before

The posts returned will have dates before before. Pass the empty string to get the beginning of the list.

groupFeedParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> String -> Types.RequestParts msg

Return posts for a group feed, using a custom decoder.

groupFeedParts decoder wrapper token groupid before

The posts returned will have dates before before. Pass the empty string to get the beginning of the list.

This is a guess at what this API command will look like. It doesn't yet exist.

popularFeedParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> Types.RequestParts msg

Return the posts in the "popular" feed, using a custom decoder.

popularFeedParts decoder wrapper token

popularUsersParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> Types.RequestParts msg

Return a list of popular users, using a custom decoder.

popularUserParts wrapper decoder token

Notifications

notificationsParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Types.RequestParts msg

Return notifications, using a custom decoder.

notificationsParts decoder wrapper token before

For notifications, the before parameter is a notification ID, not a date.

Posts

getPostParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Types.RequestParts msg

Get a single post, using a custom decoder.

getPostParts decoder wrapper token postid

upvotePostParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Basics.Bool -> Types.RequestParts msg

Upvote or unupvote a post, with a custom decoder.

upvotePostParts decoder wrapper token postid unupvote

downvotePostParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Basics.Bool -> Types.RequestParts msg

Downvote or undownvote a post, with a custom decoder.

downvotePostParts decoder wrapper token postid undownvote

repostParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Basics.Bool -> Types.RequestParts msg

Repost or unrepost, with a custom decoder.

repostParts decoder wrapper token postid unrepost

New Posts

newPostParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> Types.PostForm -> Types.RequestParts msg

Create a new post with a custom decoder.

postImageParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> File -> Types.RequestParts msg

Post an image with a custom decoder

Generic requests

These are low-level functions used to implement the others. You won't need them unless you need to implement new API functionality that isn't yet in this module.

doParts : String -> String -> Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Basics.Bool -> Types.RequestParts msg

Shared by doUsersParts and doPostParts

doParts prefix operation decoder wrapper token identifier undo

prefix can be "users" or "posts".

If undo is True, does a DELETE. Otherwise, does a POST.

doUsersParts : String -> Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Basics.Bool -> Types.RequestParts msg

Shared by followUserParts and muteUserParts

doUsersParts operation decoder wrapper token username undo

operation can be "follow" or "mute".

doPostsParts : String -> Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Basics.Bool -> Types.RequestParts msg

Shared by upvotePostParts, downvotePostParts, repostParts

doPostsParts operation decoder wrapper token username undo

operation can be "upvote", "downvote" or "repost".

Persistent tokens

savedTokenFromResponseToken : Time.Posix -> OAuthMiddleware.ResponseToken.ResponseToken -> Types.SavedToken

Convert an OAuthMiddleWare.ResponseToken to Gab.Types.SavedToken.

Use Gab.EncodeDecode.savedTokenEncoder and Gab.EncodeDecode.savedTokenDecoder to persist it.

Low-level Http interface

gabApiUri : String

The base URI for GAB API requests. Automatically prepended to path args.

request : Types.RequestParts msg -> Platform.Cmd.Cmd msg

Turn parts into a ready-to-send Cmd msg.

getParts : Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Types.RequestParts msg

Simple HTTP GET request. Empty body, no custom headers.

get decoder wrapper token wrapper path

requestParts : String -> List Http.Header -> Types.HttpBody -> Json.Decode.Decoder a -> (Result Http.Error a -> msg) -> OAuth.Token -> String -> Types.RequestParts msg

General-purpose Http.Request constructor.

request method headers wrapper token path body decoder

method is the Http method, e.g. "GET".

headers is a list of custom Http.Headers.

wrapper maps a Result to a msg.

token is an OAuth token, often gotten with billstclair/elm-oauth-middleware.

path is the path to the API endpoint, with NO leading slash.

decoder is a JSON decoder for the result.

Debugging

bodyToString : Basics.Int -> Types.HttpBody -> String

Debugging function for displaying a request body.