Skip to content

API_Documentation

Jasonlin1198 edited this page Jun 11, 2020 · 20 revisions

API Documentation

Members

workspaceRef : Reference

The Reference to signed in Member's specific Workspace

currentIterationId : number

The ID of the current iteration that the member is in

memberRef : Reference

The Reference to the locally stored member inside the database

member : Member

The current Member using our extension that is stored locally

API_TOKEN : string

Signed-in member's API key

WORKSPACE : string

Name of the workspace (workspace URL slug, actually) that the signed-in member is a part of

MEMBER_ID : string

Signed-in member's member ID

MEMBER_MAP : object.<string, Member>

Object mapping member ID -> member object. Contains all members

STORIES : Array.<Story>

All stories in the workspace

CURRENT_ITERATION : Iteration

The current iteration that the signed-in member is in; the first 'started' iteration of all iterations.

SETUP : Promise.<void>

A promise to all global variables being initialized; promise that fulfills when all global vars are initialized. Once all global vars are initialized (without errors), all methods can execute correctly.

Constants

firebaseConfig : Object

Firebase configuration object

DATABASE : Database

The reference to the Database service of our extension

DATABASE_REF : Reference

The root Reference of our Database

WORKSPACES_REF : Reference

The Reference to all the Workspaces in our Database

Functions

fetchFromClubhouse(url, params)Promise.<(Array.<(Project|Story|BasicMember)>|MemberInfo|Error)>

Fetch from a Clubhouse API endpoint. Fetch calls from this method differ from regular fetches in that they send the desired fetch call through a CORS proxy.

fetchMemberInfoAsync(apiToken)Promise.<MemberInfo>

Fetch info about a member

fetchIterationsAsync(apiToken)Promise.<Array.<Iteration>>
fetchIterationStoriesAsync(apiToken, iterationId)Promise.<Array.<Story>>

Fetch all stories in an iteration

fetchMembersAsync(apiToken)Promise.<Array.<BasicMember>>

Fetch all members in the workspace

completeStoryAsync(apiToken, storyId)Promise.<Story>

Request update to story info using workflow_state_id and time completed

honorDatabaseMember(memberId, honoredMemberId)

Add additional honors to the id of the honored Member into our database (a Member can only honor an individual Member once)

getHonoredByMap(allMemberIds)Promise.<object.<string, Array.<string>>>

Get the lists of all Members that have honored the corresponding Member for every Member in the Workspace

memberLogin(memberId, allMemberIds, workspace, iterationId)

Checks if the member logging in is already within the database and adds them to the database if they are not. Also makes sure to get the Reference to the passed in workspace.

checkIfExists(nodeRef, key)Promise

Check to see if the passed in key already exists within the passed in reference

validateMember(apiKey)

Validates a potential member using their API key. First, validates their API key by checking with the Clubhouse API. If the API key is valid, stores the member's API key, member ID, name, and workspace in browser storage, then changes window to popup. If the API key is invalid or another error occurs, this method does nothing (TODO).

isComplete(story)boolean

Check if a story is complete

getStories([params])Array.<Story>

Get stories - using optional filters - from the set of all stories in the workspace (STORIES).

getMyIncompleteStories()Array.<Story>

Get incomplete stories that are assigned to the signed-in member

getAllIncompleteStories()Array.<Story>

Get all incomplete stories in the workspace

getTopWarriors()Array.<Contributor>

Get up to top 3 point contributors. If less than 3 members have completed any stories (and have more than 0 points), only return those that do.

getMember(memberId)Member

Get a member

getSignedInMember()Member

Get the signed-in member

getAllMembers()Array.<Member>

Get all team members.

getBattleLog()Array.<Story>

Returns stories in sorted by most recently completed Get stories to show in the battle log - all completed stories sorted by most recently completed.

getMemberName(memberId)string

Get the name of a member

getMemberProfile()MemberDisplay

Get the display info - workspace, name, and display icon - of the signed-in member.

getProgress()Progress

Get the overall progress of stories, in terms of points completed

getIterationTimeline()IterationDisplay

Get display information about the current iteration

getCurrentIterationId()number

Get the ID of the current iteration

getCurrentIterationIndex()number

Get the index of the current iteration

setup()Promise.<void>

Get the SETUP promise. If SETUP hasn't been initialized yet, create it. Otherwise, return the existing promise - do not recreate/restart it.

signout()

Signout by removing all items from StorageArea storage.sync

toggleBossMap()

Show member profile menu

toggleMemberMenu()

Show or hide the boss map

selectTab(tabIndex)

Apply appropriate styles to selected tab and panel item

honorMember(honoredMember)

Record honoring of member in database

setTopWarriors()

Sets the top 3 warrior names and point values

onCompleteStory(story)

Callback to be called when the user wants to mark a story completed. First, tries to update the story using the Clubhouse API. If successful, remove the story from local references (i.e. myStories) and from the tab that it is in. If the update fails, handle the error (TODO).

getFNameAndLInitial(name)string

Converts a full (i.e. first and last) name into first name and last initial format.

getStoryNodeFromContainer(nodeContainer, story)Element

Get the node with storyName from a known container/parent

addToMyStoriesSection(story)

Adds the passed in story to the myStories section of the stories tab

addToAllStoriesSection(story)

Adds the passed in story to the allStories section of the stories tab

addToBattleLogTab(story, [addToTop])

Add the passed in story to the battleLog tab

initBossMap()

Populate the map with bosses

updateHealthBar()

Calculate the amount of health the boss has left and display it as a health bar in the DOM

updateHealthBarColor()

Update the color of the health bar display depending on how much health left

Typedefs

Project : object
Story : object
BasicMember : object

Basic (not modified/enhanced by us) member object fetched from Clubhouse

Member : object

BasicMember that we have enhanced with additional attributes (i.e. points)

MemberDisplay : object

Sub-object of BasicMember, with simplified structure

Contributor : object

Sub-object of Member, with simplified structure

MemberInfo : object

Member object, containing workspace info (but less member info than BasicMember), fetched from Clubhouse

Iteration : object

Iteration object that contains all info about an iteration from Clubhouse

IterationDisplay : object

Sub-object of Iteration, with additional days_remaining attribute

Progress : object
Database : object
Reference : object
DataSnapshot : object
Member : object
Workspace : object

workspaceRef : Reference

The Reference to signed in Member's specific Workspace

Kind: global variable

currentIterationId : number

The ID of the current iteration that the member is in

Kind: global variable

memberRef : Reference

The Reference to the locally stored member inside the database

Kind: global variable

member : Member

The current Member using our extension that is stored locally

Kind: global variable

API_TOKEN : string

Signed-in member's API key

Kind: global variable

WORKSPACE : string

Name of the workspace (workspace URL slug, actually) that the signed-in member is a part of

Kind: global variable

MEMBER_ID : string

Signed-in member's member ID

Kind: global variable

MEMBER_MAP : object.<string, Member>

Object mapping member ID -> member object. Contains all members

Kind: global variable

STORIES : Array.<Story>

All stories in the workspace

Kind: global variable

CURRENT_ITERATION : Iteration

The current iteration that the signed-in member is in; the first 'started' iteration of all iterations.

Kind: global variable

SETUP : Promise.<void>

A promise to all global variables being initialized; promise that fulfills when all global vars are initialized. Once all global vars are initialized (without errors), all methods can execute correctly.

Kind: global variable
See: setup

firebaseConfig : Object

Firebase configuration object

Kind: global constant

DATABASE : Database

The reference to the Database service of our extension

Kind: global constant

DATABASE_REF : Reference

The root Reference of our Database

Kind: global constant

WORKSPACES_REF : Reference

The Reference to all the Workspaces in our Database

Kind: global constant

fetchFromClubhouse(url, params) ⇒ Promise.<(Array.<(Project|Story|BasicMember)>|MemberInfo|Error)>

Fetch from a Clubhouse API endpoint. Fetch calls from this method differ from regular fetches in that they send the desired fetch call through a CORS proxy.

Kind: global function
Returns: Promise.<(Array.<(Project|Story|BasicMember)>|MemberInfo|Error)> - If successful, a promise to the requested object. Otherwise, an Error with message equal to the value of:

  • ERR_MSG_INTERNET
  • ERR_MSG_INVALID_API_TOKEN
  • ERR_MSG_CLUBHOUSE_API_QUOTA_EXCEEDED
  • ERR_MSG_UNKNOWN_CLUBHOUSE_RESPONSE
Param Type Description
url string The Clubhouse URL to fetch from
params object Optional parameters to pass to fetch (i.e. headers)

fetchMemberInfoAsync(apiToken) ⇒ Promise.<MemberInfo>

Fetch info about a member

Kind: global function
Returns: Promise.<MemberInfo> - A promise to the member info object

Param Type Description
apiToken string Member's API token

fetchIterationsAsync(apiToken) ⇒ Promise.<Array.<Iteration>>

Kind: global function
Returns: Promise.<Array.<Iteration>> - A promise of an array of iteration objects

Param Type Description
apiToken string Member's API token

fetchIterationStoriesAsync(apiToken, iterationId) ⇒ Promise.<Array.<Story>>

Fetch all stories in an iteration

Kind: global function
Returns: Promise.<Array.<Story>> - A promise to all stories in the iteration

Param Type Description
apiToken string Member's API token
iterationId string ID of the iteration

fetchMembersAsync(apiToken) ⇒ Promise.<Array.<BasicMember>>

Fetch all members in the workspace

Kind: global function
Returns: Promise.<Array.<BasicMember>> - A promise to the array of member objects

Param Type Description
apiToken string Member's API token

completeStoryAsync(apiToken, storyId) ⇒ Promise.<Story>

Request update to story info using workflow_state_id and time completed

Kind: global function
Returns: Promise.<Story> - A promise to the updated story

Param Type Description
apiToken string Member's API token
storyId string ID of the story

honorDatabaseMember(memberId, honoredMemberId)

Add additional honors to the id of the honored Member into our database (a Member can only honor an individual Member once)

Kind: global function

Param Type Description
memberId string The id of the (locally stored) Member currently logged in and using our extension
honoredMemberId string The id of the Member that the (locally stored) Member currently logged in and using our extension would like to honor (cannot equal memberId)

getHonoredByMap(allMemberIds) ⇒ Promise.<object.<string, Array.<string>>>

Get the lists of all Members that have honored the corresponding Member for every Member in the Workspace

Kind: global function
Returns: Promise.<object.<string, Array.<string>>> - a Promise resolved to an object mapping each member's id to an array of other member ids that have honored them. A member's array will be empty if they have not been honored by other members

Param Type Description
allMemberIds Array.<string> Array containing the ids of all the members within the workspace

memberLogin(memberId, allMemberIds, workspace, iterationId)

Checks if the member logging in is already within the database and adds them to the database if they are not. Also makes sure to get the Reference to the passed in workspace.

Kind: global function

Param Type Description
memberId string The id of the member whose data we are storing
allMemberIds Array.<string> Member ids of all members in the workspace
workspace string The key identifying the workspace the member is in
iterationId number ID of the current iteration

checkIfExists(nodeRef, key) ⇒ Promise

Check to see if the passed in key already exists within the passed in reference

Kind: global function
Returns: Promise - A Promise resolve to true if the key already exists, false otherwise

Param Type Description
nodeRef Reference The Reference where the key might exist
key string The key whose existence we are checking

validateMember(apiKey)

Validates a potential member using their API key. First, validates their API key by checking with the Clubhouse API. If the API key is valid, stores the member's API key, member ID, name, and workspace in browser storage, then changes window to popup. If the API key is invalid or another error occurs, this method does nothing (TODO).

Kind: global function

Param Type Description
apiKey string The API key of the potential member

isComplete(story) ⇒ boolean

Check if a story is complete

Kind: global function
Returns: boolean - True if the story is complete, false otherwise

Param Type Description
story Story Story to check

getStories([params]) ⇒ Array.<Story>

Get stories - using optional filters - from the set of all stories in the workspace (STORIES).

Kind: global function
Returns: Array.<Story> - Stories specified by the filters (if any). If no filters are specified, returns all stories in the workspace (STORIES). If STORIES is null, returns null.

Param Type Default Description
[params] object.<string, boolean> Optional parameter to specify filter flags.
[params.memberOnly] boolean false Flag to only include stories assigned to the signed-in member.
[params.incompleteOnly] boolean false Flag to only include stories that are incomplete.
[params.completeOnly] boolean false Flag to only include stories that are complete.

getMyIncompleteStories() ⇒ Array.<Story>

Get incomplete stories that are assigned to the signed-in member

Kind: global function
Returns: Array.<Story> - Incomplete stories assigned to the signed-in member. If STORIES is null, returns null.
See: getStories

getAllIncompleteStories() ⇒ Array.<Story>

Get all incomplete stories in the workspace

Kind: global function
Returns: Array.<Story> - All incomplete stories in the workspace. If STORIES is null, returns null.
See: getStories

getTopWarriors() ⇒ Array.<Contributor>

Get up to top 3 point contributors. If less than 3 members have completed any stories (and have more than 0 points), only return those that do.

Kind: global function
Returns: Array.<Contributor> - An array of top contributors (max 3). If less than 3 top contributors exist, the returned array will have length less than 3. If there are no top contributors, an empty array is returned.

getMember(memberId) ⇒ Member

Get a member

Kind: global function
Returns: Member - The member

Param Type Description
memberId string Member ID of the member to get

getSignedInMember() ⇒ Member

Get the signed-in member

Kind: global function
Returns: Member - Signed-in member

getAllMembers() ⇒ Array.<Member>

Get all team members.

Kind: global function
Returns: Array.<Member> - Array of all members.

getBattleLog() ⇒ Array.<Story>

Returns stories in sorted by most recently completed Get stories to show in the battle log - all completed stories sorted by most recently completed.

Kind: global function
Returns: Array.<Story> - Stories for battle log. If STORIES is null, returns null

getMemberName(memberId) ⇒ string

Get the name of a member

Kind: global function
Returns: string - Name of the specified member

Param Type Description
memberId string ID of the member to get the name of

getMemberProfile() ⇒ MemberDisplay

Get the display info - workspace, name, and display icon - of the signed-in member.

Kind: global function
Returns: MemberDisplay - The display info of the signed-in member

getProgress() ⇒ Progress

Get the overall progress of stories, in terms of points completed

Kind: global function
Returns: Progress - Completed points and total points

getIterationTimeline() ⇒ IterationDisplay

Get display information about the current iteration

Kind: global function
Returns: IterationDisplay - Display information about the current iteration, or null if CURRENT_ITERATION is null.

getCurrentIterationId() ⇒ number

Get the ID of the current iteration

Kind: global function
Returns: number - ID of the current iteration

getCurrentIterationIndex() ⇒ number

Get the index of the current iteration

Kind: global function
Returns: number - Index of the current iteration

setup() ⇒ Promise.<void>

Get the SETUP promise. If SETUP hasn't been initialized yet, create it. Otherwise, return the existing promise - do not recreate/restart it.

Kind: global function
Returns: Promise.<void> - A promise to all global variables being initialized without error and all methods being ready for execution.
See: SETUP

signout()

Signout by removing all items from StorageArea storage.sync

Kind: global function

toggleBossMap()

Show member profile menu

Kind: global function

toggleMemberMenu()

Show or hide the boss map

Kind: global function

selectTab(tabIndex)

Apply appropriate styles to selected tab and panel item

Kind: global function

Param Type Description
tabIndex number index of tab

honorMember(honoredMember)

Record honoring of member in database

Kind: global function

Param Type Description
honoredMember Member Member object that is being honored

setTopWarriors()

Sets the top 3 warrior names and point values

Kind: global function

onCompleteStory(story)

Callback to be called when the user wants to mark a story completed. First, tries to update the story using the Clubhouse API. If successful, remove the story from local references (i.e. myStories) and from the tab that it is in. If the update fails, handle the error (TODO).

Kind: global function

Param Type Description
story Story Story that is being completed

getFNameAndLInitial(name) ⇒ string

Converts a full (i.e. first and last) name into first name and last initial format.

Kind: global function
Returns: string - Name in first name and last initial format

Param Type Description
name string Name to convert

getStoryNodeFromContainer(nodeContainer, story) ⇒ Element

Get the node with storyName from a known container/parent

Kind: global function
Returns: Element - The node associated with the story, or null if the node isn't found.

Param Type Description
nodeContainer Element Container of all stories associated with a specific tab in the DOM.
story Story The story of the story node to get

addToMyStoriesSection(story)

Adds the passed in story to the myStories section of the stories tab

Kind: global function

Param Type Description
story Story the story to add to the myStories tab

addToMyStoriesSection~pressingDown()

Sets timer for story completion mousedown event

Kind: inner method of addToMyStoriesSection

addToMyStoriesSection~notPressingDown()

Resets timer for sotry completion mouseup event

Kind: inner method of addToMyStoriesSection

addToMyStoriesSection~timer()

Establish timer action during story completion mousedown event

Kind: inner method of addToMyStoriesSection

addToMyStoriesSection~finishHold()

Completes story when pressHoldDuration threshold is met

Kind: inner method of addToMyStoriesSection

addToAllStoriesSection(story)

Adds the passed in story to the allStories section of the stories tab

Kind: global function

Param Type Description
story Story the story to add to the allStories tab

addToBattleLogTab(story, [addToTop])

Add the passed in story to the battleLog tab

Kind: global function

Param Type Default Description
story Story the story to add to the battleLog tab
[addToTop] boolean false whether to add the story to the top of the battleLog tab

initBossMap()

Populate the map with bosses

Kind: global function

updateHealthBar()

Calculate the amount of health the boss has left and display it as a health bar in the DOM

Kind: global function

updateHealthBarColor()

Update the color of the health bar display depending on how much health left

Kind: global function

Project : object

Kind: global typedef
Properties

Name Type Description
id string ID of the project

Story : object

Kind: global typedef
Properties

Name Type Description
completed boolean Whether the story is completed
completed_at string String representation of the time of completion
estimate number Story point estimate
name string Name of the story
owner_ids Array.<string> Member IDs of members assigned to the story

BasicMember : object

Basic (not modified/enhanced by us) member object fetched from Clubhouse

Kind: global typedef
Properties

Name Type Description
profile object Profile of the member containing personal info
profile.name string Name of the member

Member : object

BasicMember that we have enhanced with additional attributes (i.e. points)

Kind: global typedef
Properties

Name Type Description
points number Total story points completed by the member
profile object Profile of the member containing personal info
profile.name string Name of the member

MemberDisplay : object

Sub-object of BasicMember, with simplified structure

Kind: global typedef
Properties

Name Type Description
workspace string Name of the member's workspace
name name Name of the member
icon string URL of the member's display icon

Contributor : object

Sub-object of Member, with simplified structure

Kind: global typedef
Properties

Name Type Description
name string Name of the contributor (member)
points string Total story points completed by the member

MemberInfo : object

Member object, containing workspace info (but less member info than BasicMember), fetched from Clubhouse

Kind: global typedef
Properties

Name Type Description
name string Name of the member
workspace2 object Info about the member's workspace
workspace2.url_slug string Member's workspace URL slug

Iteration : object

Iteration object that contains all info about an iteration from Clubhouse

Kind: global typedef
Properties

Name Type Description
id number ID of the iteration
start_date string String representation (format 'yyyy-mm-dd') of the starting date of the iteration
end_date string String representation (format 'yyyy-mm-dd') of the ending date of the iteration
status string The current status of the iteration. Can be 'started', 'unstarted' or 'done'

IterationDisplay : object

Sub-object of Iteration, with additional days_remaining attribute

Kind: global typedef
Properties

Name Type Description
start_date Date The starting date of the iteration
end_date Date The ending date of the iteration
days_remaining number Days remaining in the iteration

Progress : object

Kind: global typedef
Properties

Name Type Description
total number Number of total story points

Database : object

Kind: global typedef
See: https://firebase.google.com/docs/reference/js/firebase.database.Database
Properties

Name Type Description
app object The app assoiated with the Database service instance

Reference : object

Kind: global typedef
See: https://firebase.google.com/docs/reference/js/firebase.database.Reference
Properties

Name Type Description
key string The last part of the Reference's path (key of a root Reference is null)
parent object The parent location of a Reference (parent of a root Reference is null)
ref object Returns a Reference to the Query's location
root object The root Reference of the Database

DataSnapshot : object

Kind: global typedef
See: https://firebase.google.com/docs/reference/js/firebase.database.DataSnapshot

Member : object

Kind: global typedef
Properties

Name Type Description
honorRecognitionsRemaining number The amount of times the Member can honor a different Member within the same Workspace (the Member being honored must be different each time)
honoredBy object.<string, boolean> Object containing the keys of all users that have honored them

Workspace : object

Kind: global typedef
Properties

Name Type Description
iterationId object.<number, object> The id of the current iteration the Workspace is in
iterationId.members object.<string, Member> Keys of all the Members that belong to the Workspace
Clone this wiki locally