1.5.0 (2013-09-28) add statistics and registration API
1.4.0 (2013-09-21) rename Retrieve to Get + update IntelliSense documentation + add GetTags method
@@ -314,6 +316,43 @@ Accepts four parameters, with uri being required.
+
+
Article Reader API
+
PocketSharp 2.0 implements a new Reader API.
+
This API does _not _use the official (and private) Article View API by Pocket. It is based on a custom PCL port of NReadability and SgmlReader, which are included in the solution.
+
What's it all about?
+
The Reader API extracts the main content of a website and returns the extracted content as HTML and it's associated title (which should already be available in the PocketItem).
+
This content can be encapsulated in a <body>-Tag and displayed as a readable website with a custom CSS (it's up to you!).
+
Implementation
+
As with all PocketSharp implementations you have to require the main namespace and it's model namespace:
+
+using PocketSharp;
+using PocketSharp.Models;
+
The PocketReader is a seperated class with it's own HttpClient. Create an instance of it:
+
+PocketReader reader = new PocketReader();
+
PocketReader needs a PocketItem as a parameter to correctly identify its ID and Uri. With this requirement you can successfully query for an articles content.
+Don't forget exception handling in case a website is down or not accessible.
diff --git a/README.md b/README.md
index 12c2d2f..ae3a9cf 100644
--- a/README.md
+++ b/README.md
@@ -13,14 +13,9 @@
Install-Package PocketSharp
```
-## Components
+## Documentation
-- [Get](#get) - Retrieve and search for items
-- [Modify](#modify) - Modify items and its tags
-- [Add](#add) - Add new items
-- [Authentication](#account-authentication) - Authenticate users
-- [Registration](#account-registration) - Register new users
-- [Statistics](#statistics) - Retrieve account statistics
+See [wiki](https://github.com/ceee/PocketSharp/wiki) or [website]((http://pocketsharp.frontendplay.com/)).
## Supported platforms
@@ -33,327 +28,8 @@ PocketSharp is a **Portable Class Library** (since 1.0.0), therefore it's compat
You can find examples for Silverlight 5, WP8 and WPF in the `PocketSharp.Examples` ([@github](https://github.com/ceee/PocketSharp/tree/master/PocketSharp.Examples)) folder.
-## Async Support
-
-All public methods, which communicate with the Pocket servers are asynchronous. So they should be called with the preceding `await` keyword, and the encapsulated method marked with `async`.
-
-_In PocketSharp versions < 1.0.0 all methods lacked async support and were blocking._
-
-## What's next
-
-Next is Reading API support (with NReadability implementation). Release: Mid October.
-
-## Usage Example
-
-Request a [Consumer Key on Pocket.](http://getpocket.com/developer/apps/)
-
-Include the PocketSharp namespace and it's associated models (you will need them later):
-
-```csharp
-using PocketSharp;
-using PocketSharp.Models;
-```
-
-Initialize PocketClient with:
-
-```csharp
-PocketClient _client = new PocketClient("[YOUR_CONSUMER_KEY]", "[YOUR_ACCESS_CODE]");
-```
-
-Do a simple request - e.g. a search for `CSS`:
-
-```csharp
-var items = await _client.Search("css");
-items.ForEach(
- item => Debug.WriteLine(item.ID + " | " + item.Title)
-);
-```
-
-Which will output:
-
- 330361896 | CSS Front-end Frameworks with comparison : By usabli.ca
- 345541438 | Editr - HTML, CSS, JavaScript playground
- 251743431 | CSS Architecture
- 343693149 | CSS3 Transitions - Thank God We Have A Specification!
- ...
-
-## Create an instance
-
-Constructor:
-
-```csharp
-PocketClient(string consumerKey, string accessCode = null, Uri callbackUri = null)
-```
-
-`consumerKey`: The API key
-
-`accessCode`: Provide an access code if the user is already authenticated
-
-`callbackUri`: The callback URL is called by Pocket after authentication
-
-Example:
-
-```csharp
-PocketClient _client = new PocketClient(
- consumerKey: "123498237423498723498723",
- callbackUri: new Uri("http://ceecore.com"),
- accessCode: "097809-oi987-izi8-jk98-oiuu89"
-);
-```
-
-You can change the _Access Code_ after initialization:
-
-```csharp
-_client.AccessCode = "[YOU_ACCESS_CODE]";
-```
-
-**Before authentication** you will need to provide the `callbackUri` for authentication requests.
-
-**After authentication** you will need to provide the `accessCode`.
-
-## Account Authentication
-
-In order to communicate with a Pocket User, you will need a consumer key (which is generated by [creating a new application on Pocket](http://getpocket.com/developer/apps/)) and an **Access Code**.
-
-The authentication is a 3-step process:
-
-#### 1) Generate authentication URI
-
-Receive the **request code** and **authentication URI** from the library by calling `string GetRequestCode()`:
-
-```csharp
-string requestCode = await _client.GetRequestCode();
-// 0f453f2d-1605-8584-28fd-39af8e
-Uri authenticationUri = _client.GenerateAuthenticationUri();
-// https://getpocket.com/auth/authorize?request_token=0f453f2d-1605-8584-28fd-39af8e&redirect_uri=http%253a%252f%252fceecore.com
-```
-
-The _request code_ is stored internally, but you can also provide it as param in `GenerateAuthenticationUri(string requestCode = null)`.
-
-#### 2) Redirect to Pocket
-Next you need to redirect the user to the `authenticationUri`, which displays a prompt to grant permissions for the application (see image). After the user granted or denied, he/she is redirected to the `callbackUri`.
-
-
-
-#### 3) Get Access Code
-Call `Task GetAccessCode(string requestCode = null)`
-
-```csharp
-string accessCode = await _client.GetAccessCode();
-// fa8bfc16-69b3-4d22-7db7-84a58d
-```
-
-Again, the received _access code_ is stored internally.
-Note that `GetAccessCode` can only be called with an existing _request code_. If you need to re-authenticate a user, start again with Step 1).
-
-#### Important
-
-**Be sure to permanently store the _Access Code_ for your user.**
-
-Without it you would always have to redo the authentication process.
-
-## Account Registration
-
-The `RegisterAccount` method exists in Pocket API v3, but is currently undocumented.
- The user cannot authenticate directly after registration, as the account has to be activated via an opt-in link, which is sent to the e-mail address.
-
-```csharp
-bool isSuccess = await _client.RegisterAccount("myUsername", "me@mymail.com", "mypassword");
-```
-
-After registration you have to remind the user to check his/her mail account.
-
-## Get
-
-Get list of all items:
-
-```csharp
-List items = await _client.Get();
-// equivalent to: await _client.Get(RetrieveFilter.All)
-```
-
-Get a list with specific parameters (explanation in the [Pocket Docs](http://getpocket.com/developer/docs/v3/retrieve)):
-
-```csharp
-List items = await _client.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
-);
-```
-
-It's best to use parameters as _named parameters_, to avoid typing `null` values:
-
-```csharp
-List items = await _client.Get(count: 10, offset: 20, sort: Sort.oldest);
-```
-
-Get item by ID:
-
-```csharp
-PocketItem item = await _client.Get(1298198);
-```
-
-Find items by a tag:
-
-```csharp
-List items = await _client.SearchByTag("tutorial");
-```
-
-Find items by a search string.
- PocketSharp uses an internal search, which is significantly faster than the Search API by Pocket.
-
-```csharp
-List items = await _client.Search("css");
-```
-
-Find items by a search string by already available items:
-
-```csharp
-List items = await _client.Search(myPocketItemList, "css");
-```
-
-Get all tags:
-
-```csharp
-List items = await _client.GetTags();
-```
-
-Get a filtered list:
-
-```csharp
-List items = await _client.Get(RetrieveFilter.Favorite);
-// returns favorites only
-```
-
-The RetrieveFilter Enum is specified as follows:
-
-```csharp
-enum RetrieveFilter { All, Unread, Archive, Favorite, Article, Video, Image }
-```
-
-## Add
-
-Adds a new item to your pocket list.
-Accepts four parameters, with `uri` being required.
-
-```csharp
-Task Add(Uri uri, string[] tags = null, string title = null, string tweetID = null)
-```
-
-Example:
-
-```csharp
-PocketItem newItem = await _client.Add(
- new Uri("http://www.neowin.net/news/full-build-2013-conference-sessions-listing-revealed"),
- new string[] { "microsoft", "neowin", "build" }
-);
-```
-
-The title 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 (with the tweetID). This allows Pocket to show the original tweet alongside the article.
-
-## Modify
-
-All Modify methods accept either the itemID (as int) or a `PocketItem` as parameter.
-
-Archive the specified item:
-
-```csharp
-bool isSuccess = await _client.Archive(myPocketItem);
-```
-
-Un-archive the specified item:
-
-```csharp
-bool isSuccess = await _client.Unarchive(myPocketItem);
-```
-
-Favorites the specified item:
-
-```csharp
-bool isSuccess = await _client.Favorite(myPocketItem);
-```
-
-Un-favorites the specified item:
-
-```csharp
-bool isSuccess = await _client.Unfavorite(myPocketItem);
-```
-
-Deletes the specified item:
-
-```csharp
-bool isSuccess = await _client.Delete(myPocketItem);
-```
-
-#### Modify tags
-
-Add tags to the specified item:
-
-```csharp
-bool isSuccess = await _client.AddTags(myPocketItem, new string[] { "css", "2013" });
-```
-
-Remove tags from the specified item:
-
-```csharp
-bool isSuccess = await _client.RemoveTags(myPocketItem, new string[] { "css", "2013" });
-```
-
-Remove all tags from the specified item:
-
-```csharp
-bool isSuccess = await _client.RemoveTags(myPocketItem);
-```
-
-Replaces all existing tags with new ones for the specified item:
-
-```csharp
-bool isSuccess = await _client.ReplaceTags(myPocketItem, new string[] { "css", "2013" });
-```
-
-Renames a tag for the specified item:
-
-```csharp
-bool isSuccess = await _client.RenameTag(myPocketItem, "oldTagName", "newTagName");
-```
-
-## Statistics
-
-The Pocket API supports retrieval of a simple statistics object.
-
-```csharp
-PocketStatistics statistics = await client.Statistics();
-// PocketStatistics: [CountAll], [CountRead], [CountUnread]
-```
-
---
-## Release History
-
-- **1.5.1** (2013-09-30) `RetrieveFilter.All` didn't work; improve search speed
-- **1.5.0** (2013-09-28) add statistics and registration API
-- **1.4.0** (2013-09-21) rename `Retrieve` to `Get` + update IntelliSense documentation + add `GetTags` method
-- **1.3.0** (2013-09-19) get Item by ID + tag modification bugfixes
-- **1.2.1** (2013-09-18) correct parameter conversion for DateTime and Boolean
-- **1.2.0** (2013-09-17) simplified retrieve methods
-- **1.1.0** (2013-09-17) fix modification requests
-- **1.0.0** (2013-09-15) convert to PCL & implement async
-- **0.3.2** (2013-08-16) tag modification fixed and full retrieval of items for Retrieve method
-- **0.3.1** (2013-07-07) authentication fixes
-- **0.3.0** (2013-07-02) update authentication process
-- **0.2.0** (2013-06-27) add, modify item & modify tags
-- **0.1.0** (2013-06-26) authentication & retrieve functionality
-
## Dependencies
- [Microsoft.Bcl.Async](https://www.nuget.org/packages/Microsoft.Bcl.Async/)