723 lines
18 KiB
Elixir
723 lines
18 KiB
Elixir
defmodule Hunter.Api do
|
|
@moduledoc """
|
|
Hunter API contract
|
|
"""
|
|
|
|
## Account
|
|
|
|
@doc """
|
|
Retrieve account of authenticated user
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
|
|
"""
|
|
@callback verify_credentials(conn :: Hunter.Client.t()) :: Hunter.Account.t()
|
|
|
|
@doc """
|
|
Make changes to the authenticated user
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `data` - data payload
|
|
|
|
## Possible keys for payload
|
|
|
|
* `display_name` - name to display in the user's profile
|
|
* `note` - new biography for the user
|
|
* `avatar` - base64 encoded image to display as the user's avatar (e.g. `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAUoAAADrCAYAAAA...`)
|
|
* `header` - base64 encoded image to display as the user's header image (e.g. `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAUoAAADrCAYAAAA...`)
|
|
|
|
"""
|
|
@callback update_credentials(Hunter.Client.t(), map) :: Hunter.Account.t()
|
|
|
|
@doc """
|
|
Retrieve account
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - account identifier
|
|
|
|
"""
|
|
@callback account(conn :: Hunter.Client.t(), id :: non_neg_integer) :: Hunter.Account.t()
|
|
|
|
@doc """
|
|
Get a list of followers
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - account identifier
|
|
* `options` - options list
|
|
|
|
## Options
|
|
|
|
* `max_id` - get a list of followings with id less than or equal this value
|
|
* `since_id` - get a list of followings with id greater than this value
|
|
* `limit` - maximum number of followings to get, default: 40, maximum: 80
|
|
|
|
"""
|
|
@callback followers(conn :: Hunter.Client.t(), id :: non_neg_integer, options :: Keyword.t()) ::
|
|
Hunter.Account.t()
|
|
|
|
@doc """
|
|
Get a list of followed accounts
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - account identifier
|
|
* `options` - options list
|
|
|
|
## Options
|
|
|
|
* `max_id` - get a list of followings with id less than or equal this value
|
|
* `since_id` - get a list of followings with id greater than this value
|
|
* `limit` - maximum number of followings to get, default: 40, maximum: 80
|
|
|
|
"""
|
|
@callback following(conn :: Hunter.Client.t(), id :: non_neg_integer, options :: Keyword.t()) ::
|
|
Hunter.Account.t()
|
|
|
|
@doc """
|
|
Follow a remote user
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `uri` - URI of the remote user, in the format of `username@domain`
|
|
|
|
"""
|
|
@callback follow_by_uri(conn :: Hunter.Client.t(), id :: non_neg_integer) :: Hunter.Account.t()
|
|
|
|
@doc """
|
|
Search for accounts
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `options` - option list
|
|
|
|
## Options
|
|
|
|
* `q`: what to search for
|
|
* `limit`: maximum number of matching accounts to return, default: 40
|
|
|
|
"""
|
|
@callback search_account(conn :: Hunter.Client.t(), options :: map) :: [Hunter.Account.t()]
|
|
|
|
@doc """
|
|
Retrieve user's blocks
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
|
|
## Options
|
|
|
|
* `max_id` - get a list of blocks with id less than or equal this value
|
|
* `since_id` - get a list of blocks with id greater than this value
|
|
* `limit` - maximum number of blocks to get, default: 40, max: 80
|
|
|
|
"""
|
|
@callback blocks(conn :: Hunter.Client.t(), options :: Keyword.t()) :: [Hunter.Account.t()]
|
|
|
|
@doc """
|
|
Retrieve a list of follow requests
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `options` - option list
|
|
|
|
## Options
|
|
|
|
* `max_id` - get a list of follow requests with id less than or equal this value
|
|
* `since_id` - get a list of follow requests with id greater than this value
|
|
* `limit` - maximum number of requests to get, default: 40, max: 80
|
|
|
|
"""
|
|
@callback follow_requests(conn :: Hunter.Client.t(), options :: Keyword.t()) :: [
|
|
Hunter.Account.t()
|
|
]
|
|
|
|
@doc """
|
|
Retrieve user's mutes
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `options` - option list
|
|
|
|
## Options
|
|
|
|
* `max_id` - get a list of mutes with id less than or equal this value
|
|
* `since_id` - get a list of mutes with id greater than this value
|
|
* `limit` - maximum number of mutes to get, default: 40, max: 80
|
|
|
|
"""
|
|
@callback mutes(conn :: Hunter.Client.t(), options :: Keyword.t()) :: [Hunter.Account.t()]
|
|
|
|
@doc """
|
|
Accepts or Rejects a follow request
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - follow request id
|
|
* `action` - action to take
|
|
|
|
## Actions
|
|
|
|
* `:authorize` - authorize a follow request
|
|
* `:reject` - reject a follow request
|
|
|
|
"""
|
|
@callback follow_request_action(
|
|
conn :: Hunter.Client.t(),
|
|
id :: non_neg_integer,
|
|
action :: atom
|
|
) :: boolean
|
|
|
|
## Application
|
|
|
|
@doc """
|
|
Register a new OAuth client app on the target instance
|
|
|
|
## Parameters
|
|
|
|
* `name` - name of your application
|
|
* `redirect_uri` - where the user should be redirected after authorization,
|
|
for no redirect, use `urn:ietf:wg:oauth:2.0:oob`
|
|
* `scopes` - scope list, see the scope section for more details
|
|
* `website` - URL to the homepage of your app
|
|
* `base_url` - base url
|
|
|
|
## Scopes
|
|
|
|
* `read` - read data
|
|
* `write` - post statuses and upload media for statuses
|
|
* `follow` - follow, unfollow, block, unblock
|
|
|
|
Multiple scopes can be requested during the authorization phase with the `scope` query param
|
|
|
|
"""
|
|
@callback create_app(
|
|
name :: String.t(),
|
|
redirect_uri :: String.t(),
|
|
scopes :: [String.t()],
|
|
website :: nil | String.t(),
|
|
base_url :: String.t()
|
|
) :: Hunter.Application.t()
|
|
|
|
@doc """
|
|
Upload a media file
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `file` - media to be uploaded
|
|
* `options` - option list
|
|
|
|
## Options
|
|
|
|
* `description` - plain-text description of the media for accessibility (max 420 chars)
|
|
* `focus` - two floating points, comma-delimited.
|
|
|
|
"""
|
|
@callback upload_media(conn :: Hunter.Client.t(), file :: Path.t(), options :: Keyword.t()) ::
|
|
Hunter.Attachment.t()
|
|
|
|
## Relationship
|
|
|
|
@doc """
|
|
Get the relationships of authenticated user towards given other users
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - list of relationship IDs
|
|
|
|
"""
|
|
@callback relationships(conn :: Hunter.Client.t(), ids :: [non_neg_integer]) :: [
|
|
Hunter.Relationship.t()
|
|
]
|
|
|
|
@doc """
|
|
Follow a user
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - user id
|
|
|
|
"""
|
|
@callback follow(conn :: Hunter.Client.t(), id :: non_neg_integer) :: Hunter.Relationship.t()
|
|
|
|
@doc """
|
|
Unfollow a user
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - user identifier
|
|
|
|
"""
|
|
@callback unfollow(conn :: Hunter.Client.t(), id :: non_neg_integer) :: Hunter.Relationship.t()
|
|
|
|
@doc """
|
|
Block a user
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - user identifier
|
|
|
|
"""
|
|
@callback block(conn :: Hunter.Client.t(), id :: non_neg_integer) :: Hunter.Relationship.t()
|
|
|
|
@doc """
|
|
Unblock a user
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - user identifier
|
|
|
|
"""
|
|
@callback unblock(conn :: Hunter.Client.t(), id :: non_neg_integer) :: Hunter.Relationship.t()
|
|
|
|
@doc """
|
|
Mute a user
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - user identifier
|
|
|
|
"""
|
|
@callback mute(conn :: Hunter.Client.t(), id :: non_neg_integer) :: Hunter.Relationship.t()
|
|
|
|
@doc """
|
|
Unmute a user
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - user identifier
|
|
|
|
"""
|
|
@callback unmute(conn :: Hunter.Client.t(), id :: non_neg_integer) :: Hunter.Relationship.t()
|
|
|
|
## Result
|
|
|
|
@doc """
|
|
Search for content
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `q` - the search query
|
|
* `options` - option list
|
|
|
|
## Options
|
|
|
|
* `resolve` - whether to resolve non-local accounts
|
|
|
|
"""
|
|
@callback search(conn :: Hunter.Client.t(), query :: String.t(), options :: Keyword.t()) ::
|
|
Hunter.Result.t()
|
|
|
|
## Status
|
|
|
|
@doc """
|
|
Create new status
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `status` - text of the status
|
|
* `options` - option list
|
|
|
|
## Options
|
|
|
|
* `in_reply_to_id` - local ID of the status you want to reply to
|
|
* `media_ids` - list of media IDs to attach to the status (maximum: 4)
|
|
* `sensitive` - whether the media of the status is NSFW
|
|
* `spoiler_text` - text to be shown as a warning before the actual content
|
|
* `visibility` - either `direct`, `private`, `unlisted` or `public`
|
|
|
|
"""
|
|
@callback create_status(conn :: Hunter.Client.t(), status :: String.t(), options :: Keyword.t()) ::
|
|
Hunter.Status.t() | no_return
|
|
|
|
@doc """
|
|
Retrieve status
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - status identifier
|
|
|
|
"""
|
|
@callback status(conn :: Hunter.Client.t(), id :: non_neg_integer) :: Hunter.Status.t()
|
|
|
|
@doc """
|
|
Destroy status
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - status identifier
|
|
|
|
"""
|
|
@callback destroy_status(conn :: Hunter.Client.t(), id :: non_neg_integer) :: boolean
|
|
|
|
@doc """
|
|
Reblog a status
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - status identifier
|
|
|
|
"""
|
|
@callback reblog(conn :: Hunter.Client.t(), id :: non_neg_integer) :: Hunter.Status.t()
|
|
|
|
@doc """
|
|
Undo a reblog of a status
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - status identifier
|
|
|
|
"""
|
|
@callback unreblog(conn :: Hunter.Client.t(), id :: non_neg_integer) :: Hunter.Status.t()
|
|
|
|
@doc """
|
|
Fetch the list of users who reblogged the status.
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - status identifier
|
|
* `options` - option list
|
|
|
|
## Options
|
|
|
|
* `max_id` - get a list of *reblogged by* ids less than or equal this value
|
|
* `since_id` - get a list of *reblogged by* ids greater than this value
|
|
* `limit` - maximum number of *reblogged by* to get, default: 40, max: 80
|
|
|
|
"""
|
|
@callback reblogged_by(conn :: Hunter.Client.t(), id :: non_neg_integer, options :: Keyword.t()) ::
|
|
[Hunter.Account.t()]
|
|
|
|
@doc """
|
|
Favorite a status
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - status identifier
|
|
|
|
"""
|
|
@callback favourite(conn :: Hunter.Client.t(), id :: non_neg_integer) :: Hunter.Status.t()
|
|
|
|
@doc """
|
|
Undo a favorite of a status
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - status identifier
|
|
|
|
"""
|
|
@callback unfavourite(conn :: Hunter.Client.t(), id :: non_neg_integer) :: Hunter.Status.t()
|
|
|
|
@doc """
|
|
Fetch a user's favourites
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `options` - option list
|
|
|
|
## Options
|
|
|
|
* `max_id` - get a list of favourites with id less than or equal this value
|
|
* `since_id` - get a list of favourites with id greater than this value
|
|
* `limit` - maximum of favourites to get, default: 20, max: 40
|
|
|
|
"""
|
|
@callback favourites(conn :: Hunter.Client.t(), options :: Keyword.t()) :: [Hunter.Status.t()]
|
|
|
|
@doc """
|
|
Fetch the list of users who favourited the status.
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - status identifier
|
|
* `options` - option list
|
|
|
|
## Options
|
|
|
|
* `max_id` - get a list of *favourited by* ids less than or equal this value
|
|
* `since_id` - get a list of *favourited by* ids greater than this value
|
|
* `limit` - maximum number of *favourited by* to get, default: 40, max: 80
|
|
|
|
"""
|
|
@callback favourited_by(
|
|
conn :: Hunter.Client.t(),
|
|
id :: non_neg_integer,
|
|
options :: Keyword.t()
|
|
) :: [Hunter.Account.t()]
|
|
|
|
@doc """
|
|
Get a list of statuses by a user
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `account_id` - account identifier
|
|
* `options` - option list
|
|
|
|
## Options
|
|
|
|
* `only_media` - only return `Hunter.Status.t` that have media attachments
|
|
* `exclude_replies` - skip statuses that reply to other statuses
|
|
* `max_id` - get a list of statuses with id less than or equal this value
|
|
* `since_id` - get a list of statuses with id greater than this value
|
|
* `limit` - maximum number of statuses to get, default: 20, max: 40
|
|
|
|
"""
|
|
@callback statuses(conn :: Hunter.Client.t(), account_id :: non_neg_integer, options :: map) ::
|
|
[Hunter.Status.t()]
|
|
|
|
@doc """
|
|
Retrieve statuses from the home timeline
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `options` - option list
|
|
|
|
## Options
|
|
|
|
* `max_id` - get a list of timelines with id less than or equal this value
|
|
* `since_id` - get a list of timelines with id greater than this value
|
|
* `limit` - maximum number of statuses on the requested timeline to get, default: 20, max: 40
|
|
|
|
"""
|
|
@callback home_timeline(conn :: Hunter.Client.t(), options :: map) :: [Hunter.Status.t()]
|
|
|
|
@doc """
|
|
Retrieve statuses from the public timeline
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `options` - option list
|
|
|
|
## Options
|
|
|
|
* `local` - only return statuses originating from this instance
|
|
* `max_id` - get a list of timelines with id less than or equal this value
|
|
* `since_id` - get a list of timelines with id greater than this value
|
|
* `limit` - maximum number of statuses on the requested timeline to get, default: 20, max: 40
|
|
|
|
"""
|
|
@callback public_timeline(conn :: Hunter.Client.t(), options :: map) :: [Hunter.Status.t()]
|
|
|
|
@doc """
|
|
Retrieve statuses from a hashtag
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `hashtag` - list of strings
|
|
* `options` - option list
|
|
|
|
## Options
|
|
|
|
* `local` - only return statuses originating from this instance
|
|
* `max_id` - get a list of timelines with id less than or equal this value
|
|
* `since_id` - get a list of timelines with id greater than this value
|
|
* `limit` - maximum number of statuses on the requested timeline to get, default: 20, max: 40
|
|
|
|
"""
|
|
@callback hashtag_timeline(conn :: Hunter.Client.t(), hashtag :: [String.t()], options :: map) ::
|
|
[Hunter.Status]
|
|
|
|
@doc """
|
|
Retrieve instance information
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
|
|
"""
|
|
@callback instance_info(conn :: Hunter.Client.t()) :: Hunter.Instance.t()
|
|
|
|
@doc """
|
|
Retrieve user's notifications
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `options` - option list
|
|
|
|
## Options
|
|
|
|
* `max_id` - get a list of notifications with id less than or equal this value
|
|
* `since_id` - get a list of notifications with id greater than this value
|
|
* `limit` - maximum number of notifications to get, default: 15, max: 30
|
|
|
|
"""
|
|
@callback notifications(conn :: Hunter.Client.t(), options :: Keyword.t()) :: [
|
|
Hunter.Notification.t()
|
|
]
|
|
|
|
@doc """
|
|
Retrieve single notification
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - notification identifier
|
|
|
|
"""
|
|
@callback notification(conn :: Hunter.Client.t(), non_neg_integer) :: Hunter.Notification.t()
|
|
|
|
@doc """
|
|
Deletes all notifications from the Mastodon server for the authenticated user
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
|
|
"""
|
|
@callback clear_notifications(conn :: Hunter.Client.t()) :: boolean
|
|
|
|
@doc """
|
|
Dismiss a single notification
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - notification id
|
|
|
|
"""
|
|
@callback clear_notification(conn :: Hunter.Client.t(), id :: non_neg_integer) :: boolean
|
|
|
|
@doc """
|
|
Retrieve a user's reports
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
|
|
"""
|
|
@callback reports(conn :: Hunter.Client.t()) :: [Hunter.Report.t()]
|
|
|
|
@doc """
|
|
Report a user
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `account_id` - the ID of the account to report
|
|
* `status_ids` - the IDs of statuses to report
|
|
* `comment` - a comment to associate with the report
|
|
|
|
"""
|
|
@callback report(
|
|
conn :: Hunter.Client.t(),
|
|
account_id :: non_neg_integer,
|
|
status_ids :: [non_neg_integer],
|
|
comment :: String.t()
|
|
) :: Hunter.Report.t()
|
|
|
|
@doc """
|
|
Retrieve status context
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - status identifier
|
|
|
|
"""
|
|
@callback status_context(conn :: Hunter.Client.t(), id :: non_neg_integer) :: Hunter.Context.t()
|
|
|
|
@doc """
|
|
Retrieve a card associated with a status
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `id` - status id
|
|
|
|
"""
|
|
@callback card_by_status(conn :: Hunter.Client.t(), id :: non_neg_integer) :: Hunter.Card.t()
|
|
|
|
@doc """
|
|
Retrieve access token
|
|
|
|
## Parameters
|
|
|
|
* `app` - application details, see: `Hunter.Application.create_app/5` for more details.
|
|
* `username` - your account's email
|
|
* `password` - your password
|
|
* `base_url` - API base url, default: `https://mastodon.social`
|
|
|
|
"""
|
|
@callback log_in(
|
|
app :: Hunter.Application.t(),
|
|
username :: String.t(),
|
|
password :: String.t(),
|
|
base_url :: String.t()
|
|
) :: Hunter.Client.t()
|
|
|
|
@doc """
|
|
Fetch user's blocked domains
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `options` - option list
|
|
|
|
## Options
|
|
|
|
* `max_id` - get a list of blocks with id less than or equal this value
|
|
* `since_id` - get a list of blocks with id greater than this value
|
|
* `limit` - maximum number of blocks to get, default: 40, max: 80
|
|
|
|
"""
|
|
@callback blocked_domains(conn :: Hunter.Client.t(), options :: Keyword.t()) :: list
|
|
|
|
@doc """
|
|
Block a domain
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `domain` - domain to block
|
|
|
|
"""
|
|
@callback block_domain(conn :: Hunter.Client.t(), domain :: String.t()) :: boolean
|
|
|
|
@doc """
|
|
Unblock a domain
|
|
|
|
## Parameters
|
|
|
|
* `conn` - connection credentials
|
|
* `domain` - domain to unblock
|
|
|
|
"""
|
|
@callback unblock_domain(conn :: Hunter.Client.t(), domain :: String.t()) :: boolean
|
|
end
|