Create a new Client for API access, given an AuthConfig. This client is required to run all actions in this library.

See loadClient if you have a ScriptApp or ApplicationOnly app and would like to load your auth details from an ini file

Create a new client with an existing refresh token, for WebApps and InstalledApps. The initial refresh token is provided with a TokenManager that will also handle saving and loading refresh tokens over the life of the new Client

Load a client from saved credentials, which are stored in an ini file. Files should conform to the following formats:

For ScriptApps:

[NAME]
id = <clientID>
secret = <clientSecret>
username = <username>
password = <password>
agent = <platform>,<appID>,<version>,<author>

For ApplicationOnly apps without a user context:

[NAME]
id = <clientID>
secret = <clientSecret>
agent = <platform>,<appID>,<version>,<author>

Where NAME corresponds to a ClientSite that you pass to this function. You can have various different distinct sites in a single ini file. When invoking this function, if the provided client site is Nothing, a section labeled [DEFAULT] will be used. If none is provided, an exception will be thrown. Note that all section labels are case-insensitive.

The following locations are searched for an ini file, in order:

• $PWD/auth.ini
• $XDG_CONFIG_HOME/heddit/auth.ini

Note: Only ScriptApps and ApplicationOnly are supported via this method

Get the URL required to authorize your application, for WebApps and InstalledApps

Run an action with your Reddit Client. This will catch any exceptions related to POST rate-limiting for you. After sleeping for the indicated duration, it will attempt to re-run the action that triggered the exception. If you do not wish to catch these exceptions, or would like to handle them in a different way, use runRedditT, which simply runs the provided action

Note: Confusingly, Reddit uses two different rate-limiting mechanisms. This action only catches rate limiting applied to POST requests. Another form of rate limiting is applied to API requests in general. This library does not automatically deal with this second type. If you wish to deal with this yourself, see the action withRateLimitDelay, which automatically applies a delay based on the most recent rate limit headers returned from Reddit

Run a RedditT action

Run an action with your Reddit Client, catching the exception specified and returning an Either in case of failure. It may be best to use TypeApplications to specify the exception type.

For example, to try to see the user FlairTemplates for a subreddit which may or may not allow user flair:

>>> tryReddit @APIException c $ getUserFlairTemplates =<< mkSubredditName "haskell"
Left (ErrorWithStatus (StatusMessage {statusCode = 403, message = "Forbidden"}))

Get current information on rate limiting, if any

Run the provided MonadReddit action with a delay, if rate-limiting information is currently available

Run a MonadReddit action in a read-only context, as if you were using an ApplicationOnly client

Note: To avoid cases where the current AccessToken expires while running an action in this environment, the token will be refreshed before running the provided action

This is an example TokenManager that can be used to store and retrieve OAUth refresh tokens, which could be used with newClientWithManager. For a real application, you would probably want to use a more sophisticated manager

Convenience wrapper for actions taking a Paginator and which return a Listing. This runs the action with a default initial paginator, and extracts the children from the returned Listing. This discards all of the pagination controls that are returned in the Listing. This is useful if you only care about the child contents of the first "page" of results

For example, to get only the first page of results for a user's comments, you could use the following:

runReddit yourClient . firstPage $ getUserComments someUsername

Update a Paginator with a Listing to make a query for the next "page" of content. If the first argument is Nothing, defaults will be used for the options, partially depending on the type of paginator

Note: You cannot supply both the before and after fields when making requests to API endpoints. If both fields are Just in the Paginator you get back from this function, the after field will take precedence. If you want to use before in such a scenario, make sure to set it to Nothing before using the paginator in an action

Example:

>>> best1 <- runReddit yourClient $ getBest emptyPaginator
>>> best2 <- runReddit yourClient . getBest $ nextPage Nothing best1

An empty, default Paginator. Includes the default PaginateOptions for the type a

Transform an action producing a Listing of items into an infinite stream. Items are pushed to the stream as they are fetched, with oldest items yielded first. New items are fetched in 100-item batches. If nothing new arrives in the stream, a jittered exponential backoff is applied, up to a cap of ~16s, resetting once new items arrive again.

For example, to fetch new submissions published to "r/haskell", as they are created, and print their IDs to the console:

>>> import Conduit
>>> subName <- mkSubredditName "haskell"
>>> action = getNewSubmissions subName
>>> printTitle = liftIO . print . (^. #title)
>>> runReddit c . runConduit $ stream Nothing action  .| mapM_C printTitle
SubmissionID "o6948i"
SubmissionID "o6b0w0"
SubmissionID "o6cqof"
SubmissionID "o6ddl9"
SubmissionID "o6dlas"
...

Synonym for constraints that RedditT actions must satisfy

The monad tranformer in which Reddit API transactions can be executed

A client facilitating access to Reddit's API

Rate limit info

Certain API endpoints are listings, which can be paginated and filtered using a Paginator

This represents the protocol that Reddit uses to control paginating and filtering entries. These can be applied to Listing endpoints. The first four fields below are common parameters that are applied to each Listing. The opts field takes extended PaginateOptions based on the second type parameter

Represents requests that can take additional options in a Paginator. This can be used to filter/sort Listing endpoints

Pattern for "[deleted]" username

Test if a user has the "[deleted]" username. Also see the DeletedUser pattern synonym

Options that can be applied to comments or submissions

Defaults for fetching items, like comments or submissions

How to sort items in certain Listings. Not every option is guaranteed to be accepted by a given endpoint

A user- or moderator-generated report on a submission

Sigils that a moderator can add to distinguish comments or submissions. Note that the Admin and Special distinctions require special privileges to use

Time range when fetching comments or submissions

Type of comments, for filtering in Listings

A URL pointing to a resource hosted by Reddit. These should only be obtained by parsing the JSON of existing resources or through particular actions that perform the upload transaction and return the URL, e.g. uploadWidgetImage

Type synonym for bodies of submissions, comments, messages, etc...

Type synonym for titles of submissions, etc...

Type synonym for URLs

Type synonym for subjects of messages, etc...

Type synonym RGB color strings

Type synonym for names of items

Type synonym for domains

Type synonym for fieldLabelModifiers in FromJSON instances

Base exception type for Reddit API client

Exceptions generated within the Reddit API client

Exceptions returned from API endpoints

An error which occurs when attempting to authenticate via OAuth

A specific error message

Details about a non-200 HTTP response

Type synonym for status codes in responses

Details about a non-200 response when sending a POST request

Information about a banned user

Stateful data that may be updated over the course of a Client lifetime

The three forms of application that may use the Reddit API, each having different API access patterns

A configuration

A unique user agent to identify your application; Reddit applies rate-limiting to common agents, and actively bans misleading ones

Token received after authentication

Type synonym for the text of a token

Type synonym for the text of codes returned from auth URLs, for WebApps and InstalledApps

Represents a specific Reddit functionality that must be explicitly requested