First pass at pagination

graph/typeDefs.graphql

@@ -1,21 +1,50 @@
-interface ActionableItem {
-  id: ID!
+# Establishes the ordering of the content by their created_at time stamp.
+enum SORT_ORDER {
+  # newest to oldest order.
+  REVERSE_CHRONOLOGICAL
+
+  # oldest to newer order.
+  CHRONOLOGICAL
 }
 
+# Date represented as an ISO8601 string.
+scalar Date
+
 type UserSettings {
   # bio of the user.
   bio: String
 }
 
-input CommentsInput {
+input CommentsQuery {
   # current status of a comment.
-  status: COMMENT_STATUS
+  statuses: [COMMENT_STATUS]
 
   # asset that a comment is on.
   asset_id: ID
 
-  # action type to find comments that have an action with.
+  # the parent of the comment that we want to retrive.
+  parent_id: ID
+
+  # comments returned will only be ones which have at least one action of this
+  # type.
   action_type: ACTION_TYPE
+
+  # limit the number of results to be returned.
+  limit: Int = 10
+
+  # skip results from the last created_at timestamp.
+  cursor: Date
+
+  # sort the results by created_at.
+  sort: SORT_ORDER = REVERSE_CHRONOLOGICAL
+}
+
+enum USER_ROLES {
+  # an administrator of the site
+  ADMIN
+
+  # a moderator of the site
+  MODERATOR
 }
 
 # Any person who can author comments, create actions, and view comments on a
@@ -29,11 +58,14 @@ type User {
   # actions against a specific user.
   actions: [ActionSummary]
 
+  # the current roles of the user.
+  roles: [USER_ROLES]
+
   # settings for a user.
   settings: UserSettings
 
   # returns all comments based on a query.
-  comments(query: CommentsInput): [Comment]
+  comments(query: CommentsQuery): [Comment]
 }
 
 type Comment {
@@ -46,7 +78,10 @@ type Comment {
   user: User
 
   # the replies that were made to the comment.
-  replies(limit: Int = 3): [Comment]
+  replies(sort: SORT_ORDER = CHRONOLOGICAL, limit: Int = 3): [Comment]
+
+  # the count of replies on a comment
+  replyCount: Int
 
   # the actions made against a comment.
   actions: [ActionSummary]
@@ -58,7 +93,7 @@ type Comment {
   status: COMMENT_STATUS
 
   # the time when the comment was created
-  created_at: String!
+  created_at: Date!
 }
 
 enum ITEM_TYPE {
@@ -78,11 +113,10 @@ type Action {
 
   item_id: ID!
   item_type: ITEM_TYPE!
-  item: ActionableItem
 
   user: User!
-  updated_at: String
-  created_at: String
+  updated_at: Date
+  created_at: Date
 }
 
 type ActionSummary {
@@ -109,13 +143,31 @@ type Settings {
 }
 
 type Asset {
+
+  # The current ID of the asset.
   id: ID!
+
+  # The scraped title of the asset.
   title: String
+
+  # The URL that the asset is locaed on.
   url: String
-  comments: [Comment]
+
+  # The top level comments that are attached to the asset.
+  comments(sort: SORT_ORDER = REVERSE_CHRONOLOGICAL, limit: Int = 10): [Comment]
+
+  # The count of top level comments on the asset.
+  commentCount: Int
+
+  # The settings (rectified with the global settings) that should be applied to
+  # this asset.
   settings: Settings!
-  closedAt: String
-  created_at: String
+
+  # The date that the asset was closed at.
+  closedAt: Date
+
+  # The date that the asset was created.
+  created_at: Date
 }
 
 enum COMMENT_STATUS {
@@ -125,6 +177,7 @@ enum COMMENT_STATUS {
 }
 
 type RootQuery {
+
   # retrieves site wide settings and defaults.
   settings: Settings
 
@@ -135,7 +188,7 @@ type RootQuery {
   asset(id: ID, url: String): Asset
 
   # retrieves comments based on the input query.
-  comments(query: CommentsInput): [Comment]
+  comments(query: CommentsQuery!): [Comment]
 
   # retrieves the current logged in user.
   me: User