speckle-server/packages/server/modules/comments/graph/schemas/comments.gql

extend type Query {
  comment(id: String!, streamId: String!): Comment
  """
  This query can be used in the follwing ways: 
  - get all the comments for a stream: **do not pass in any resource identifiers**.
  - get the comments targeting any of a set of provided resources (comments/objects): **pass in an array of resources.**
  """
  comments(streamId: String!, resources: [ResourceIdentifierInput], limit: Int = 25, cursor: String, archived: Boolean! = false): CommentCollection
}

extend type Stream{
  """
  The total number of comments for this stream. To actually get the comments, use the comments query without passing in a resource array. E.g.:

  ```
  query{
    comments(streamId:"streamId"){
      ...
    }
  ```
  """
  commentCount: Int!
}

extend type Commit{
  """
  The total number of comments for this commit. To actually get the comments, use the comments query and pass in a resource array consisting of of this commit's id.
  E.g., 
  ```
  query{
    comments(streamId:"streamId" resources:[{resourceType: commit, resourceId:"commitId"}] ){
      ...
    }
  ```
  """
  commentCount: Int!
}

extend type CommitCollectionUserNode{
  """
  The total number of comments for this commit. To actually get the comments, use the comments query and pass in a resource array consisting of of this commit's id.
  E.g., 
  ```
  query{
    comments(streamId:"streamId" resources:[{resourceType: commit, resourceId:"commitId"}] ){
      ...
    }
  ```
  """
  commentCount: Int!
}

extend type Object{
  """
  The total number of comments for this commit. To actually get the comments, use the comments query and pass in a resource array consisting of of this object's id.
  E.g., 
  ```
  query{
    comments(streamId:"streamId" resources:[{resourceType: object, resourceId:"objectId"}] ){
      ...
    }
  ```
  """
  commentCount: Int!
}

type Comment {
  id: String!
  authorId: String!
  archived: Boolean!
  screenshot: String
  text: String!
  data: JSONObject
  """
  Resources that this comment targets. Can be a mixture of either one stream, or multiple commits and objects.
  """
  resources: [ResourceIdentifier]!
  createdAt: DateTime
  """
  The time this comment was last updated. Corresponds also to the latest reply to this comment, if any.
  """
  updatedAt: DateTime
  """
  The last time you viewed this comment. Present only if an auth'ed request. Relevant only if a top level commit.
  """
  viewedAt: DateTime
  """
  Gets the replies to this comment.
  """
  replies(limit: Int = 25, cursor: String): CommentCollection
  reactions: [String]
}

type CommentCollection {
  totalCount: Int!
  cursor: DateTime
  items: [Comment]!
}

type ResourceIdentifier {
  resourceId: String!
  resourceType: ResourceType!
}

input ResourceIdentifierInput {
  resourceId: String!
  resourceType: ResourceType!
}

enum ResourceType {
  comment
  object
  commit
  stream
}

input CommentCreateInput {
  streamId: String!
  """
  Specifies the resources this comment is linked to. There are several use cases:
  - a comment targets only one resource (commit or object)
  - a comment targets one or more resources (commits or objects)
  - a comment targets only a stream
  """
  resources: [ResourceIdentifierInput]!
  text: String!
  data: JSONObject!
  screenshot: String
}

input ReplyCreateInput {
  streamId: String!
  parentComment: String!
  text: String!
  data: JSONObject
}

input CommentEditInput {
  streamId: String!
  id: String!
  text: String!
}

extend type Mutation {
  """
  Used for broadcasting real time chat head bubbles and status. Does not persist any info.
  """
  userViewerActivityBroadcast(
    streamId: String!
    resourceId: String!
    data: JSONObject
  ): Boolean!  
  @hasRole(role: "server:user")
  
  """
  Used for broadcasting real time typing status in comment threads. Does not persist any info.
  """
  userCommentThreadActivityBroadcast(
    streamId: String!
    commentId: String!
    data: JSONObject
  ): Boolean!
  @hasRole(role: "server:user")

  """
  Creates a comment
  """
  commentCreate(input: CommentCreateInput! ): String!
    @hasRole(role: "server:user")
    @hasScope(scope: "streams:read")

  """
  Flags a comment as viewed by you (the logged in user).
  """
  commentView(streamId: String!, commentId: String!): Boolean! 
    @hasRole(role: "server:user")
    @hasScope(scope: "streams:read")

  """
  Archives a comment.
  """
  commentArchive( streamId: String!, commentId: String!, archived: Boolean! = true ): Boolean!
    @hasRole(role: "server:user")
    @hasScope(scope: "streams:read")

  """
  Edits a comment.
  """
  commentEdit( input: CommentEditInput! ): Boolean!
    @hasRole(role: "server:user")
    @hasScope(scope: "streams:read")

  """
  Adds a reply to a comment.
  """
  commentReply( input: ReplyCreateInput! ): String!
    @hasRole(role: "server:user")
    @hasScope(scope: "streams:read")

  commentReactionToggle(streamId: String!, commentId: String!, reaction: String!): Boolean!
    @hasRole(role: "server:user")
    @hasScope(scope: "streams:read")
}

extend type Subscription {
  """
  Broadcasts "real-time" location data for viewer users.
  """
  userViewerActivity(streamId: String!, resourceId: String!): JSONObject

  """
  Subscribe to comment events. There's two ways to use this subscription: 
  - for a whole stream: do not pass in any resourceIds; this sub will get called whenever a comment (not reply) is added to any of the stream's resources.
  - for a specific resource/set of resources: pass in a list of resourceIds (commit or object ids); this sub will get called when *any* of the resources provided get a comment.
  """
  commentActivity(streamId: String!, resourceIds: [String]): JSONObject
    @hasRole(role: "server:user")
    @hasScope(scope: "streams:read")

  """
  Subscribes to events on a specific comment. Use to find out when:
  - a top level comment is deleted (trigger a deletion event outside)
  - a top level comment receives a reply. 
  """
  commentThreadActivity(streamId: String!, commentId: String!): JSONObject
    @hasRole(role: "server:user")
    @hasScope(scope: "streams:read")
}