com.github.twitch4j.kraken.TwitchKraken Maven / Gradle / Ivy
package com.github.twitch4j.kraken;
import com.github.twitch4j.common.annotation.Unofficial;
import com.github.twitch4j.kraken.domain.*;
import com.netflix.hystrix.HystrixCommand;
import feign.Body;
import feign.CollectionFormat;
import feign.Headers;
import feign.Param;
import feign.RequestLine;
import org.jetbrains.annotations.ApiStatus;
import java.net.URI;
import java.time.Instant;
import java.util.Collection;
import java.util.List;
import java.util.function.Supplier;
/**
* Twitch - Kraken API
*
* Kraken is already deprecated, so we only offer methods which haven't been added to the new helix api yet. Please use the helix api if available.
* @deprecated Kraken is deprecated and has been shut down on Febuary 28, 2022.
* More details about the deprecation are available here.
*
*/
@Deprecated
@ApiStatus.ScheduledForRemoval(inVersion = "2.0.0")
public interface TwitchKraken {
/**
* The default baseUrl to pass to {@link TwitchKraken#uploadVideoPart(URI, String, String, int, byte[])} and {@link TwitchKraken#completeVideoUpload(URI, String, String)}
*/
URI UPLOADS_BASE_URL = ((Supplier) () -> {
// Not pretty but needed for "Overriding the Request Line" - see: https://github.com/OpenFeign/feign/blob/master/README.md#interface-annotations
try {
return new URI("https://uploads.twitch.tv");
} catch (Exception e) {
return null;
}
}).get();
/**
* Get Channel Editors
*
* Gets a list of users who are editors for a specified channel.
*
* @param authToken User Access Token (scope: channel_read)
* @param channelId The ID of the channel to retrieve editors from
* @return {@link KrakenUserList}
*/
@RequestLine("GET /channels/{channelId}/editors")
@Headers({
"Authorization: OAuth {token}",
})
HystrixCommand getChannelEditors(
@Param("token") String authToken,
@Param("channelId") String channelId
);
/**
* Get Channel Followers
*
* Gets a list of users who follow a specified channel, sorted by the date when they started following the channel (newest first, unless specified otherwise).
*
* @param channelId Channel Id
* @param limit Maximum number of objects to return. Default: 25. Maximum: 100.
* @param offset Object offset for pagination of results. Default: 0.
* @param cursor Tells the server where to start fetching the next set of results, in a multi-page response.
* @param direction Direction of sorting. Valid values: asc, desc (newest first). Default: desc.
* @return {@link KrakenFollowList}
*/
@RequestLine("GET /channels/{channelId}/follows?limit={limit}&offset={offset}&cursor={cursor}&direction={direction}")
HystrixCommand getChannelFollowers(
@Param("channelId") String channelId,
@Param("limit") Integer limit,
@Param("offset") Integer offset,
@Param("cursor") String cursor,
@Param("direction") String direction
);
/**
* Reset Channel Stream Key
*
* Deletes the stream key for a specified channel. Once it is deleted, the stream key is automatically reset.
*
* @param authToken User Access Token (scope: channel_stream)
* @param channelId Channel Id
* @return {@link KrakenChannel}
*/
@RequestLine("DELETE /channels/{channelId}/stream_key")
@Headers({
"Authorization: OAuth {token}"
})
HystrixCommand resetChannelStreamKey(
@Param("token") String authToken,
@Param("channelId") String channelId
);
/**
* Get Channel Subscribers
*
* Gets a list of users subscribed to a specified channel, sorted by the date when they subscribed.
*
* @param authToken Auth Token
* @param channelId Channel Id
* @param limit Maximum number of objects to return. Default: 25. Maximum: 100.
* @param offset Object offset for pagination of results. Default: 0.
* @param direction Sorting direction. Valid values: asc, desc. Default: asc (oldest first).
* @return Object
*/
@RequestLine("GET /channels/{channelId}/subscriptions?limit={limit}&offset={offset}&direction={direction}")
@Headers({
"Authorization: OAuth {token}"
})
HystrixCommand getChannelSubscribers(
@Param("token") String authToken,
@Param("channelId") String channelId,
@Param("limit") Integer limit,
@Param("offset") Integer offset,
@Param("direction") String direction
);
/**
* Gets a list of badges that can be used in chat for a specified channel.
*
* @param channelId The ID for the specific channel.
* @return ChatBadges
*/
@RequestLine("GET /chat/{channel_id}/badges")
HystrixCommand getChatBadgesByChannel(
@Param("channel_id") String channelId
);
/**
* Gets all chat emoticons (not including their images).
*
* Caution: this endpoint returns a large amount of data.
*
* @return SimpleEmoticonList
*/
@RequestLine("GET /chat/emoticon_images")
HystrixCommand getChatEmoticons();
/**
* Gets all chat emoticons (not including their images) in one or more specified sets.
*
* @param emoteSets Specifies the set(s) of emoticons to retrieve.
* @return EmoticonSetList
*/
@RequestLine("GET /chat/emoticon_images?emotesets={emotesets}")
HystrixCommand getChatEmoticonsBySet(
@Param("emotesets") Collection emoteSets
);
/**
* Gets all chat emoticons (including their images).
*
* Caution: This endpoint returns a large amount of data.
*
* @return EmoticonList
*/
@RequestLine("GET /chat/emoticons")
HystrixCommand getAllChatEmoticons();
/**
* Approve Automod
*
* Approve a message that was flagged by Automod
*
* @param authToken Auth Token
* @param msgId unique id for the message
* @return no content for a successful call
* @deprecated in favor of TwitchHelix#manageAutoModHeldMessage
*/
@Unofficial
@Deprecated
@RequestLine("POST /chat/twitchbot/approve")
@Headers({
"Authorization: OAuth {token}"
})
@Body("%7B\"msg_id\":\"{msg_id}\"%7D")
HystrixCommand approveAutomodMessage(
@Param("token") String authToken,
@Param("msg_id") String msgId
);
/**
* Deny Automod
*
* Deny a message that was flagged by Automod
*
* @param authToken Auth Token
* @param msgId unique id for the message
* @return no content for a successful call
* @deprecated in favor of TwitchHelix#manageAutoModHeldMessage
*/
@Unofficial
@Deprecated
@RequestLine("POST /chat/twitchbot/deny")
@Headers({
"Authorization: OAuth {token}"
})
@Body("%7B\"msg_id\":\"{msg_id}\"%7D")
HystrixCommand denyAutomodMessage(
@Param("token") String authToken,
@Param("msg_id") String msgId
);
/**
* Get Clip
*
* Gets details about a specified clip.
*
* @param slug The globally unique string to reference the clip
* @return {@link KrakenClip}
*/
@RequestLine("GET /clips/{slug}")
HystrixCommand getClip(
@Param("slug") String slug
);
/**
* Get Collection Metadata
*
* Gets summary information about a specified collection.
*
* @param collectionId The ID of the collection. (Required)
* @return {@link KrakenCollectionMetadata}
*/
@RequestLine("GET /collections/{collection_id}")
HystrixCommand getCollectionMetadata(
@Param("collection_id") String collectionId
);
/**
* Get Collection
*
* Gets all items (videos) in a specified collection.
*
* @param collectionId The ID of the collection. (Required)
* @return {@link KrakenCollection}
*/
@RequestLine("GET /collections/{collection_id}/items")
HystrixCommand getCollection(
@Param("collection_id") String collectionId
);
/**
* Get Collections by Channel
*
* Gets all collections owned by a specified channel.
*
* @param channelId The ID of the channel. (Required)
* @param limit Maximum number of most-recent objects to return. (Optional)
* @param cursor Tells the server where to start fetching the next set of results in a multi-page response. (Optional)
* @param videoId Returns only collections containing the specified video. Example: "video:89917098". (Optional)
* @return {@link KrakenCollectionList}
*/
@RequestLine("GET /channels/{channel_id}/collections?limit={limit}&cursor={cursor}&containing_item={containing_item}")
HystrixCommand getCollectionsByChannel(
@Param("channel_id") String channelId,
@Param("limit") Integer limit,
@Param("cursor") String cursor,
@Param("containing_item") String videoId
);
/**
* Create Collection
*
* Creates a new collection owned by a specified channel.
*
* @param token User Access Token for the broadcaster or channel editor with the collections_edit scope. (Required)
* @param channelId The ID of the channel. (Required)
* @param title The title of the collection. (Required)
* @return {@link KrakenCollectionMetadata}
*/
@RequestLine("POST /channels/{channel_id}/collections")
@Headers({
"Authorization: OAuth {token}"
})
@Body("%7B\"title\":\"{title}\"%7D")
HystrixCommand createCollection(
@Param("token") String token,
@Param("channel_id") String channelId,
@Param("title") String title
);
/**
* Get Hosts of a Target Channel
*
* This endpoint returns a "host" record for each channel hosting the channel with the provided targetId.
*
* @param channelId The user ID of the channel for which to get host information.
* @return KrakenHostList
* @deprecated Decommissioned by Twitch.
*/
@Unofficial
@RequestLine("GET /channels/{channel_id}/hosts")
@Deprecated
HystrixCommand getHostsOf(
@Param("channel_id") String channelId
);
/**
* Update Collection
*
* Updates the title of a specified collection.
*
* @param token User Access Token with the collections_edit scope. (Required)
* @param collectionId The id of tne collection. (Required)
* @param title The new title of the collection. (Required)
* @return 204 No Content upon a successful request
*/
@RequestLine("PUT /collections/{collection_id}")
@Headers({
"Authorization: OAuth {token}"
})
@Body("%7B\"title\":\"{title}\"%7D")
HystrixCommand updateCollection(
@Param("token") String token,
@Param("collection_id") String collectionId,
@Param("title") String title
);
/**
* Create Collection Thumbnail
*
* Adds the thumbnail of a specified collection item as the thumbnail for the specified collection.
*
* @param token User Access Token with the collections_edit scope. (Required)
* @param collectionId The id of tne collection. (Required)
* @param itemId The id of a video which must already be in the collection. (Required)
* @return 204 No Content upon a successful request
*/
@RequestLine("PUT /collections/{collection_id}/thumbnail")
@Headers({
"Authorization: OAuth {token}",
})
@Body("%7B\"item_id\":\"{item_id}\"%7D")
HystrixCommand createCollectionThumbnail(
@Param("token") String token,
@Param("collection_id") String collectionId,
@Param("item_id") String itemId
);
/**
* Delete Collection
*
* Deletes a specified collection.
*
* @param token User Access Token with the collections_edit scope. (Required)
* @param collectionId The id of tne collection. (Required)
* @return 204 No Content upon a successful request
*/
@RequestLine("DELETE /collections/{collection_id}")
@Headers({
"Authorization: OAuth {token}"
})
HystrixCommand deleteCollection(
@Param("token") String token,
@Param("collection_id") String collectionId
);
/**
* Add Item to Collection
*
* Adds a specified video to a specified collection.
*
* @param token User Access Token with the collections_edit scope. (Required)
* @param collectionId The id of tne collection. (Required)
* @param videoId The id of a video. (Required)
* @return {@link KrakenCollectionItem}
*/
@RequestLine("POST /collections/{collection_id}/items")
@Headers({
"Authorization: OAuth {token}",
})
@Body("%7B\"id\":\"{id}\",\"type\":\"video\"%7D")
HystrixCommand addItemToCollection(
@Param("token") String token,
@Param("collection_id") String collectionId,
@Param("id") String videoId
);
/**
* Delete Item from Collection
*
* Deletes a specified collection item from a specified collection.
*
* @param token User Access Token with the collections_edit scope. (Required)
* @param collectionId The id of tne collection. (Required)
* @param itemId The id of a collection item. (Required)
* @return 204 No Content upon a successful request
*/
@RequestLine("DELETE /collections/{collection_id}/items/{collection_item_id}")
@Headers({
"Authorization: OAuth {token}"
})
HystrixCommand deleteItemFromCollection(
@Param("token") String token,
@Param("collection_id") String collectionId,
@Param("collection_item_id") String itemId
);
/**
* Move Item within Collection
*
* Moves a specified collection item to a different position within a collection.
*
* @param token User Access Token with the collections_edit scope. (Required)
* @param collectionId The id of tne collection. (Required)
* @param itemId The id of a collection item. (Required)
* @param position The new position of the item. (Required)
* @return 204 No Content upon a successful request
*/
@RequestLine("PUT /collections/{collection_id}/items/{collection_item_id}")
@Headers({
"Authorization: OAuth {token}"
})
@Body("%7B\"position\":\"{position}\"%7D")
HystrixCommand moveItemWithinCollection(
@Param("token") String token,
@Param("collection_id") String collectionId,
@Param("collection_item_id") String itemId,
@Param("position") Integer position
);
/**
* Get User Block List
*
* Gets a specified user’s block list. List sorted by recency, newest first.
*
* @param authToken User Access Token (scope: user_blocks_read)
* @param userId The user ID associated with the token
* @param limit Maximum number of objects in array. Default: 25. Maximum: 100.
* @param offset Object offset for pagination. Default: 0.
* @return {@link KrakenBlockList}
*/
@RequestLine("GET /users/{user}/blocks?limit={limit}&offset={offset}")
@Headers({
"Authorization: OAuth {token}"
})
HystrixCommand getUserBlockList(
@Param("token") String authToken,
@Param("user") String userId,
@Param("limit") Integer limit,
@Param("offset") Integer offset
);
/**
* Block User
*
* Blocks a user; that is, adds a specified target user to the blocks list of a specified source user.
*
* @param authToken User Access Token (scope: user_blocks_edit)
* @param sourceUserId The ID of the user that is doing the blocking.
* @param targetUserId The ID of the user that is getting blocked by the source.
* @return {@link KrakenBlockTransaction}
*/
@RequestLine("PUT /users/{from_id}/blocks/{to_id}")
@Headers({
"Authorization: OAuth {token}"
})
HystrixCommand blockUser(
@Param("token") String authToken,
@Param("from_id") String sourceUserId,
@Param("to_id") String targetUserId
);
/**
* Unblock User
*
* Unblocks a user; that is, deletes a specified target user from the blocks list of a specified source user.
*
* @param authToken User Access Token (scope: user_blocks_edit)
* @param sourceUserId The ID of the user that is doing the unblocking.
* @param targetUserId The ID of the user that is getting unblocked by the source.
* @return 204 No Content upon a successful request
*/
@RequestLine("DELETE /users/{from_id}/blocks/{to_id}")
@Headers({
"Authorization: OAuth {token}"
})
HystrixCommand unblockUser(
@Param("token") String authToken,
@Param("from_id") String sourceUserId,
@Param("to_id") String targetUserId
);
/**
* Get User Emotes
*
* Gets a list of the emojis and emoticons that the specified user can use in chat.
* These are both the globally available ones and the channel-specific ones (which can be accessed by any user subscribed to the channel).
*
* @param authToken User Access Token (scope: user_subscriptions)
* @param userId The user ID associated with the token
* @return {@link KrakenEmoticonSetList}
*/
@RequestLine("GET /users/{user}/emotes")
@Headers({
"Authorization: OAuth {token}"
})
HystrixCommand getUserEmotes(
@Param("token") String authToken,
@Param("user") String userId
);
/**
* Follow Channel
*
* Adds a specified user to the followers of a specified channel.
*
* @param authToken Auth Token
* @param userId User Id
* @param targetUserId Target User Id (the Channel the user will follow)
* @return Object
* @deprecated Decommissioned by Twitch.
*/
@Deprecated
@RequestLine("PUT /users/{user}/follows/channels/{targetUser}")
@Headers({
"Authorization: OAuth {token}"
})
HystrixCommand