From c1ad4ae84949a72f3ac0eca9b94d2e7158d4b34c Mon Sep 17 00:00:00 2001 From: Alistair Brown Date: Mon, 10 Apr 2017 21:53:36 +0100 Subject: [PATCH] Update documentation and examples --- README.md | 92 ++++++++++++------- example/logging-in-and-out.js | 55 ----------- .../add-series-to-pull-list.js | 0 {example => examples}/compare-collections.js | 0 .../find-detective-series.js | 0 {example => examples}/get-new-comics.js | 0 examples/logging-in-and-out.js | 85 +++++++++++++++++ 7 files changed, 145 insertions(+), 87 deletions(-) delete mode 100644 example/logging-in-and-out.js rename {example => examples}/add-series-to-pull-list.js (100%) rename {example => examples}/compare-collections.js (100%) rename {example => examples}/find-detective-series.js (100%) rename {example => examples}/get-new-comics.js (100%) create mode 100644 examples/logging-in-and-out.js diff --git a/README.md b/README.md index a1da75f..2a5dfaf 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # leagueofcomicgeeks -Unofficial Node.js library for interacting with [League of Comic Geeks](http://leagueofcomicgeeks.com/). This provides an API for any system wishing to interact with an account on League of Comic Geeks and supports authentication and all lists. It has has a comprehensive integration test setup to detect when the site has made breaking changes. Please create an issue or (better yet) a pull request if you see a problem or need additional features! +Unofficial Node.js library for interacting with [League of Comic Geeks](http://leagueofcomicgeeks.com/). This provides an API for any system wishing to interact with an account on League of Comic Geeks and supports authentication and all lists. It has a comprehensive integration test setup to detect when the site makes breaking changes. Please create an issue or (better yet) a pull request if you see a problem or need additional features! + +--- ## Resources @@ -12,72 +14,98 @@ Unofficial Node.js library for interacting with [League of Comic Geeks](http://l 1. Wish List 1. Pull List +All methods on resources are asynchronous and follow the nodejs "error-first callback" pattern. For use with promises, consider using something like [Bluebird's promisification functions](http://bluebirdjs.com/docs/api/promisification.html). + +There are examples on using the different resources in the `examples` directory. + ### Session Methods on the session object: - - `.create` - - `.validate` - - `.destroy` - - `.get` - - `.set` + - `.create` - Create a new session using the provided username and password. This sets up the session for all subsequent calls. + - `.validate` - Validate that the active session is still valid. + - `.destroy` - Destroy the current session both locally and on the site. + - `.get` - Get the active session object. + - `.set` - Set a previously retrieved session object. -Used to log in and out of the application. The current user session can be retrieved and loaded for serialisation. +Used to log in and out of the application. You can get the current session object for saving, as well as set the current session by setting a previously retrieved session object. The active session can then be validated to confirm it's working. ### Lists Calls to get list data all follow a standard format: -``` +```js list.get(identifier, options, callback); ``` -Where identifiers can be an issue id, series id, search term, pull list date, etc. depending on the list being accessed (see below for examples) +Where the `identifier` can be an issue id, series id, search term, pull list date, etc. depending on the list being accessed. + +The `options` parameter is optional, but is used to specify the type returned (eg. "series" or "issue") and for any sorting or filtering. + +Options support: + - `type` - "series" or "issue". Defaults to "issue". + - Use the `lofcg.types` helper for getting type values, eg. `lofcg.types.ISSUE` + - `publishers` - an array of publisher names to filter on. Default to no filtering. + +```js +const lofcg = require('leagueofcomicgeeks'); +const options = { + type: lofcg.types.SERIES, + publishers: ['Marvel Comics', 'DC Comics', 'Other'] +} +lofcg.searchResults.get('detective', options, function (err, results) { + // ... +}); +``` + +The exception to this is the Pull List, which also requires a date: + +```js +const lofcg = require('leagueofcomicgeeks'); +const myUserId = 26853; // alistairjcbrown +lofcg.pullList.get(myUserId, '2017-03-29', function (err, pullList) { + // ... +}); +``` + +Again, additional examples can be found in the `examples` directory. #### Read-only Lists Methods on read-only lists: - - `.get` + - `.get` - Get a list of comic issues or series for a user -New Comics and Search Results are read-only lists, meaning you can only get data from them, you cannot update them. +New Comics and Search Results are read-only lists - you can only get data from them, you cannot update them. #### User Lists Methods on user lists: - - `.get` - - `.add` - - `.remove` + - `.get` - Get a list of comic issues or series for a user + - `.add` - Add a comic issue or series to my list + - `.remove` - Add a comic issue or series to my list **Note:** `.add` and `.remove` require you to be authenticated. `.get` does not and can be called on any user. +--- ## To do - - Need ability to check session and log out - - [X] Validate session by pulling a protected page - - [X] Use `/logout` to destroy the session, also destroying locally - - Tests - - [X] Integration tests - - [X] Update read-only integration tests to use a specificly set up test account, and confirm response content - [ ] Provide sorting to prevent test data changing - [ ] Unit tests + - [ ] Jenkins integration + - [ ] Periodic run for integration tests + - [ ] PR run for unit tests - - API - - [X] Does search and new comics need a user Id to be passed? - - - Tooling - - [X] Linting - - [ ] Documentation - - [ ] Additional examples - - [ ] Publish module + - Additional functionality + - [ ] Sorting - A-Z, Z-A + - [ ] Pull lists can have "most pulled" + - [ ] Filtering - owned, not owned, read, not read + - [ ] New comics can have "only #1s" - - Can we dynamically load the publishers list in / update it periodically? + - Get publishers list in / update it periodically? - [ ] Perhaps a publisher module which can be called to get latest, which by default falls back to JSON file - [ ] Without coupling the code, can we use the session check to get the updated list of providers? - - Additional filters - - [ ] New comics; only #1s, sorting, etc. - ## Who am I? Just a comic fan and someone who wanted to build on top of the awesome system in place at League of Comic Geeks. diff --git a/example/logging-in-and-out.js b/example/logging-in-and-out.js deleted file mode 100644 index a52f057..0000000 --- a/example/logging-in-and-out.js +++ /dev/null @@ -1,55 +0,0 @@ -/* eslint-disable no-console */ -const lofcg = require('../'); - -const username = ''; -const password = ''; - -// Check no valid session -lofcg.session.validate((errValidate, isValidInitially) => { - if (errValidate) { - console.log('An error has occurred validating session:', errValidate); - return; - } - - console.log('Is session valid?', isValidInitially); - - // Log in - lofcg.session.create(username, password, (errCreate, userId) => { - if (errCreate) { - console.log('An error has occurred logging in:', errCreate); - return; - } - - console.log('Logged in as:', userId); - - // Check session is now valid - lofcg.session.validate((errValidate2, isValidAfterLogin) => { - if (errValidate2) { - console.log('An error has occurred validating session:', errValidate2); - return; - } - - console.log('Is session valid?', isValidAfterLogin); - - // Log out - lofcg.session.destroy((errDestroy) => { - if (errDestroy) { - console.log('An error has occurred logging out:', errDestroy); - return; - } - - console.log('Logged out'); - - // Check session has invalidated - lofcg.session.validate((errValidate3, isValidAfterLogout) => { - if (errValidate3) { - console.log('An error has occurred validating session:', errValidate3); - return; - } - - console.log('Is session valid?', isValidAfterLogout); - }); - }); - }); - }); -}); diff --git a/example/add-series-to-pull-list.js b/examples/add-series-to-pull-list.js similarity index 100% rename from example/add-series-to-pull-list.js rename to examples/add-series-to-pull-list.js diff --git a/example/compare-collections.js b/examples/compare-collections.js similarity index 100% rename from example/compare-collections.js rename to examples/compare-collections.js diff --git a/example/find-detective-series.js b/examples/find-detective-series.js similarity index 100% rename from example/find-detective-series.js rename to examples/find-detective-series.js diff --git a/example/get-new-comics.js b/examples/get-new-comics.js similarity index 100% rename from example/get-new-comics.js rename to examples/get-new-comics.js diff --git a/examples/logging-in-and-out.js b/examples/logging-in-and-out.js new file mode 100644 index 0000000..06da4fd --- /dev/null +++ b/examples/logging-in-and-out.js @@ -0,0 +1,85 @@ +/* eslint-disable no-console */ +const lofcg = require('../'); + +const username = ''; +const password = ''; + +// Check no valid session +lofcg.session.validate((errValidate, isValidInitially) => { + if (errValidate) { + console.log('An error has occurred validating session:', errValidate); + return; + } + + console.log('Is session valid?', isValidInitially); + + // Log in + lofcg.session.create(username, password, (errCreate, userId) => { + if (errCreate) { + console.log('An error has occurred logging in:', errCreate); + return; + } + + console.log('Logged in as:', userId); + + // Check session is now valid + lofcg.session.validate((errValidate2, isValidAfterLogin) => { + if (errValidate2) { + console.log('An error has occurred validating session:', errValidate2); + return; + } + + console.log('Is session valid?', isValidAfterLogin); + + // Get session value + lofcg.session.get((errGet, session) => { + if (errGet) { + console.log('An error has occurred getting session:', errGet); + return; + } + + console.log('Got session for:', session.username); + + // Log out + lofcg.session.destroy((errDestroy) => { + if (errDestroy) { + console.log('An error has occurred logging out:', errDestroy); + return; + } + + console.log('Logged out'); + + // Check session has invalidated + lofcg.session.validate((errValidate3, isValidAfterLogout) => { + if (errValidate3) { + console.log('An error has occurred validating session:', errValidate3); + return; + } + + console.log('Is session valid?', isValidAfterLogout); + + // Get session value + lofcg.session.set(session, (errSet, success) => { + if (errSet) { + console.log('An error has occurred setting session:', errSet); + return; + } + + console.log('Set session', success); + + // Check session has loaded + lofcg.session.validate((errValidate4, isValidAfterLoading) => { + if (errValidate4) { + console.log('An error has occurred validating session:', errValidate4); + return; + } + + console.log('Is session valid?', isValidAfterLoading); + }); + }); + }); + }); + }); + }); + }); +});