octomments

Octomments client

The core functionality of Octomments.

• Octomments client
  • Setup
  • Usage
  • Options
  • Methods
    • api.init()
    • api.add(text)
    • api.on(event, callback)
    • api.logout(refresh = true)
    • api.page(index)
    • api.generateNewCommentURL()
    • api.off()
  • Errors

Setup

<script src="https://unpkg.com/octomments/build/ocs.min.js"></script>

or

> npm i octomments

Usage

import Octomments from 'octomments';

function Renderer(api, container) {
  api.on(Octomments.USER_NONE, (loginURL) => {
    console.log(loginURL);
  });
}

const octomments = Octomments({
  github: {
    owner: '<username>',
    repo: '<repo name>',
  },
  issueNumber: <issue number>,
  renderer: [Renderer, '<selector>']
});

octomments.init();

Options

• github (required) - object containing owner (GitHub username) and repo (GitHub repository) fields.
• issueNumber (required) - the number of an existing in the repository issue
• renderer (required) - an array where the first element is a renderer function and the second one is a valid DOM element selector.
• debug (optional) - a boolean. If true the library will print each of the dispatched events.
• endpoints (optional) - an object with issue and token fields. The values of these fields are valid URLs pointing to Octomments server endpoints. You'll probably never need to setup those unless you deploy your own server. The already existing one is at ocs.now.sh.

Methods

api.init()

Initiates the comments and user fetching.

api.add(text)

Adding of a new comment where text is the markdown of the comment.

api.on(event, callback)

• event - event type
• callback - function called when the event is triggered

Here is a table with all the possible events:

event	callback params	description
Octomments.ERROR	error type of error	when there is an error. Check the errors section below to see the possible types.
Octomments.COMMENTS_LOADING	none	when the loading of the comments begins
Octomments.COMMENTS_LOADED	comments pagination info	when the comments are loaded
Octomments.COMMENT_SAVING	none	when the user submits a comment
Octomments.COMMENT_SAVED	an array with one item - the new comment	when the comment is saved successfully
Octomments.USER_LOADING	none	when the library initiates a request for the user's data
Octomments.USER_NONE	user login url	when there is no user logged in. Use this event to render a "log in" link.
Octomments.USER_LOADED	user's data first time	when the data of the user is fetched successfully. The second parameter shows if the user is just logged in or his/her data is pulled from the local storage

api.logout(refresh = true)

Removes the user's data from the localStorage and (potentially) refreshes the page.

api.page(index)

Initiating a new comments fetching for a page with specific index.

api.generateNewCommentURL()

Returns a URL which you can use to make the user log in. It will redirect the user to ocs.now.sh/GitHub for authentication and then back to your page.

api.off()

Removes all the listeners added with api.on.

Errors

• 1 - comments: issue doesn't exists
• 2 - comments: other problem loading the issue
• 3 - comments: issue request succeed but can't parse the json response
• 4 - comments: hit the V3 rate limit
• 5 - user: corrupted data in local storage
• 6 - user: can't get the access token
• 7 - user: problem parsing the access token response
• 8 - new comment: adding new comment failed
• 9 - new comment: not authorized
• 10 - new comment: request succeed but can't parse the json response