diff --git a/PocketSharp/IPocketClient.cs b/PocketSharp/IPocketClient.cs new file mode 100644 index 0000000..11abafc --- /dev/null +++ b/PocketSharp/IPocketClient.cs @@ -0,0 +1,403 @@ +using System; +using System.Collections.Generic; +using System.Threading.Tasks; +using PocketSharp.Models; + +namespace PocketSharp +{ + public interface IPocketClient + { + #region properties + /// + /// callback URL for API calls + /// + string CallbackUri { get; set; } + + /// + /// Accessor for the Pocket API key + /// see: http://getpocket.com/developer + /// + string ConsumerKey { get; set; } + + /// + /// Code retrieved on authentification + /// + string RequestCode { get; set; } + + /// + /// Code retrieved on authentification-success + /// + string AccessCode { get; set; } + #endregion + + #region account methods + /// + /// Retrieves the requestCode from Pocket, which is used to generate the Authentication URI to authenticate the user + /// + /// + /// Authentication methods need a callbackUri on initialization of the PocketClient class + /// + Task GetRequestCode(); + + /// + /// Generate Authentication URI from requestCode + /// + /// The requestCode. If no requestCode is supplied, the property from the PocketClient intialization is used. + /// A valid URI to redirect the user to. + /// Call GetRequestCode() first to receive a request_code + Uri GenerateAuthenticationUri(string requestCode = null); + + /// + /// Requests the access code after authentication + /// The access code has to permanently be stored within the users session, and should be passed in the constructor for all future PocketClient initializations. + /// + /// The requestCode. If no requestCode is supplied, the property from the PocketClient intialization is used. + /// The permanent access code, which is used to authenticate the user with the application + /// Call GetRequestCode() first to receive a request_code + /// + [Obsolete("Please use GetUser instead")] + Task GetAccessCode(string requestCode = null); + + /// + /// Requests the access code and username after authentication + /// The access code has to permanently be stored within the users session, and should be passed in the constructor for all future PocketClient initializations. + /// + /// The request code. + /// The authenticated user + /// Call GetRequestCode() first to receive a request_code + Task GetUser(string requestCode = null); + + /// + /// Registers a new account. + /// Account has to be activated via a activation email sent by Pocket. + /// + /// The username. + /// The email. + /// The password. + /// + /// All parameters are required + /// + /// Invalid email address. + /// or + /// Invalid username. Please only use letters, numbers, and/or dashes and between 1-20 characters. + /// or + /// Invalid password. + /// + /// + Task RegisterAccount(string username, string email, string password); + #endregion + + #region add methods + /// + /// Adds a new item to pocket + /// + /// The URL of the item you want to save + /// A comma-separated list of tags to apply to the item + /// This can be included for cases where an item does not have a title, which is typical for image or PDF URLs. If Pocket detects a title from the content of the page, this parameter will be ignored. + /// If you are adding Pocket support to a Twitter client, please send along a reference to the tweet status id. This allows Pocket to show the original tweet alongside the article. + /// A simple representation of the saved item which doesn't contain all data (is only returned by calling the Retrieve method) + /// + Task Add(Uri uri, string[] tags = null, string title = null, string tweetID = null); + #endregion + + #region get methods + /// + /// Retrieves items from pocket + /// with the given filters + /// + /// The state. + /// The favorite. + /// The tag. + /// Type of the content. + /// The sort. + /// The search. + /// The domain. + /// The since. + /// The count. + /// The offset. + /// + /// + Task> Get( + State? state = null, + bool? favorite = null, + string tag = null, + ContentType? contentType = null, + Sort? sort = null, + string search = null, + string domain = null, + DateTime? since = null, + int? count = null, + int? offset = null + ); + + /// + /// Retrieves an item by a given ID + /// Note: The Pocket API contains no method, which allows to retrieve a single item, so all items are retrieved and filtered locally by the ID. + /// + /// The item ID. + /// + /// + Task Get(int itemID); + + /// + /// Retrieves all items by a given filter + /// + /// The filter. + /// + /// + Task> Get(RetrieveFilter filter); + + /// + /// Retrieves all available tags. + /// Note: The Pocket API contains no method, which allows to retrieve all tags, so all items are retrieved and the associated tags extracted. + /// + /// + /// + Task> GetTags(); + + /// + /// Retrieves items by tag + /// + /// The tag. + /// + /// + Task> SearchByTag(string tag); + + /// + /// Retrieves items which match the specified search string in title and URI + /// + /// The search string. + /// + /// Search string length has to be a minimum of 2 chars + /// + Task> Search(string searchString, bool searchInUri = true); + + /// + /// Finds the specified search string in title and URI for an available list of items + /// + /// The available items. + /// The search string. + /// + /// Search string length has to be a minimum of 2 chars + /// + List Search(List availableItems, string searchString); + #endregion + + #region modify methods + /// + /// Archives the specified item. + /// + /// The item ID. + /// + /// + Task Archive(int itemID); + + /// + /// Archives the specified item. + /// + /// The item. + /// + /// + Task Archive(PocketItem item); + + /// + /// Un-archives the specified item (alias for Readd). + /// + /// The item ID. + /// + /// + Task Unarchive(int itemID); + + /// + /// Unarchives the specified item. + /// + /// The item. + /// + /// + Task Unarchive(PocketItem item); + + /// + /// Favorites the specified item. + /// + /// The item ID. + /// + /// + Task Favorite(int itemID); + + /// + /// Favorites the specified item. + /// + /// The item. + /// + /// + Task Favorite(PocketItem item); + + /// + /// Un-favorites the specified item. + /// + /// The item ID. + /// + /// + Task Unfavorite(int itemID); + + /// + /// Un-favorites the specified item. + /// + /// The item. + /// + /// + Task Unfavorite(PocketItem item); + + /// + /// Deletes the specified item. + /// + /// The item ID. + /// + /// + Task Delete(int itemID); + + /// + /// Deletes the specified item. + /// + /// The item. + /// + Task Delete(PocketItem item); + #endregion + + #region modify tags methods + /// + /// Adds the specified tags to an item. + /// + /// The item ID. + /// The tags. + /// + /// + Task AddTags(int itemID, string[] tags); + + /// + /// Adds the specified tags to an item. + /// + /// The item. + /// The tags. + /// + /// + Task AddTags(PocketItem item, string[] tags); + + /// + /// Removes the specified tags from an item. + /// + /// The item ID. + /// The tags. + /// + /// + Task RemoveTags(int itemID, string[] tags); + + /// + /// Removes the specified tags from an item. + /// + /// The item. + /// The tag. + /// + /// + Task RemoveTags(PocketItem item, string[] tags); + + /// + /// Removes a tag from an item. + /// + /// The item ID. + /// The tag. + /// + /// + Task RemoveTag(int itemID, string tag); + + /// + /// Removes a tag from an item. + /// + /// The item. + /// The tags. + /// + /// + Task RemoveTag(PocketItem item, string tag); + + /// + /// Clears all tags from an item. + /// + /// The item ID. + /// + /// + Task RemoveTags(int itemID); + + /// + /// Clears all tags from an item. + /// + /// The item. + /// + /// + Task RemoveTags(PocketItem item); + + /// + /// Replaces all existing tags with the given tags in an item. + /// + /// The item ID. + /// The tags. + /// + /// + Task ReplaceTags(int itemID, string[] tags); + + /// + /// Replaces all existing tags with the given new ones in an item. + /// + /// The item. + /// The tags. + /// + /// + Task ReplaceTags(PocketItem item, string[] tags); + + /// + /// Renames a tag in an item. + /// + /// The item ID. + /// The old tag. + /// The new tag name. + /// + /// + Task RenameTag(int itemID, string oldTag, string newTag); + + /// + /// Renames a tag in an item. + /// + /// The item. + /// The old tag. + /// The new tag name. + /// + /// + Task RenameTag(PocketItem item, string oldTag, string newTag); + #endregion + + #region statistics methods + /// + /// Statistics from the user account. + /// + /// + /// + Task GetUserStatistics(); + + /// + /// Statistics from the user account. + /// + /// + /// + [Obsolete("Please use GetUserStatistics instead")] + Task Statistics(); + + /// + /// Returns API usage statistics. + /// If a request was made before, the data is returned synchronously from the cache. + /// Note: This method only works for authenticated users with a given AccessCode. + /// + /// + /// + Task GetUsageLimits(); + #endregion + } +} \ No newline at end of file diff --git a/PocketSharp/PocketClient.cs b/PocketSharp/PocketClient.cs index 987f37e..d4f9d8e 100644 --- a/PocketSharp/PocketClient.cs +++ b/PocketSharp/PocketClient.cs @@ -13,7 +13,7 @@ namespace PocketSharp /// /// PocketClient /// - public partial class PocketClient + public partial class PocketClient : IPocketClient { /// /// REST client used for the API communication diff --git a/PocketSharp/PocketSharp.csproj b/PocketSharp/PocketSharp.csproj index 5698068..4431ec3 100644 --- a/PocketSharp/PocketSharp.csproj +++ b/PocketSharp/PocketSharp.csproj @@ -42,6 +42,7 @@ +