WIP: documentation

README.md

@@ -1,5 +1,54 @@
 # leagueofcomicgeeks
-Unofficial node.js library for interacting with League of Comic Geeks
+
+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!
+
+## Resources
+
+1. Session
+1. New Comics
+1. Search Results
+1. Collection
+1. Read List
+1. Wish List
+1. Pull List
+
+### Session
+
+Methods on the session object:
+ - `.create`
+ - `.validate`
+ - `.destroy`
+ - `.get`
+ - `.set`
+
+Used to log in and out of the application. The current user session can be retrieved and loaded for serialisation.
+
+### Lists
+
+Calls to get list data all follow a standard format:
+
+```
+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)
+
+#### Read-only Lists
+
+Methods on read-only lists:
+ - `.get`
+
+New Comics and Search Results are read-only lists, meaning you can only get data from them, you cannot update them.
+
+#### User Lists
+
+Methods on user lists:
+ - `.get`
+ - `.add`
+ - `.remove`
+
+**Note:** `.add` and `.remove` require you to be authenticated. `.get` does not and can be called on any user.
+
 
 ## To do
 
@@ -10,10 +59,14 @@ Unofficial node.js library for interacting with League of Comic Geeks
  - 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
 
+ - API
+   - [X] Does search and new comics need a user Id to be passed?
+
  - Tooling
-   - [ ] Linting
+   - [X] Linting
    - [ ] Documentation
    - [ ] Additional examples
    - [ ] Publish module
@@ -24,3 +77,9 @@ Unofficial node.js library for interacting with League of Comic Geeks
 
  - 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.
+
+You can see my profile here: http://leagueofcomicgeeks.com/profile/alistairjcbrown

example/compare-collections.js

@@ -0,0 +1,24 @@
+/* eslint-disable no-console */
+const _ = require('lodash');
+const lofcg = require('../');
+
+const myUserId = 26853; // alistairjcbrown
+const theirUserId = 18979; // midian
+
+// Get new comics for next week
+lofcg.collection.get(myUserId, { type: lofcg.types.SERIES }, (errMine, myCollection) => {
+  if (errMine) {
+    console.log('An error has occurred getting collection:', errMine);
+    return;
+  }
+
+  lofcg.collection.get(theirUserId, { type: lofcg.types.SERIES }, (errTheirs, theirCollection) => {
+    if (errTheirs) {
+      console.log('An error has occurred getting collection:', errTheirs);
+      return;
+    }
+
+    const seriesWeHaveInCommon = _.intersectionBy(myCollection, theirCollection, 'id');
+    console.log(seriesWeHaveInCommon);
+  });
+});

example/find-detective-series.js

@@ -0,0 +1,12 @@
+/* eslint-disable no-console */
+const lofcg = require('../');
+
+// Find detctive series
+lofcg.searchResults.get('detective', { type: lofcg.types.SERIES }, (err, detectiveSeries) => {
+  if (err) {
+    console.log('An error has occurred searching for detective series:', err);
+    return;
+  }
+
+  console.log(detectiveSeries);
+});

example/get-new-comics.js

@@ -0,0 +1,15 @@
+/* eslint-disable no-console */
+const moment = require('moment');
+const lofcg = require('../');
+
+const wednesday = moment().day(3).format('YYYY-MM-DD');
+
+// Get new comics for next week
+lofcg.newComics.get(wednesday, (err, newComics) => {
+  if (err) {
+    console.log('An error has occurred getting new comics:', err);
+    return;
+  }
+
+  console.log(newComics);
+});