node-pivotal : Node.JS API Library for PivotalTracker

License: MIT

To install:

npm install pivotal

To use:

var pivotal = require("pivotal");
pivotal.useToken("myToken");

You can also retrieve the token initially by using the pivotal.getToken function

Contributing

When making changes to the library, please run make doc before submitting pull requests.

Tests

Tests are located in test/ directory. To run them you need to install the required dependencies

    npm install

and either set your pivotal api-token as a variable

    export token=xxxxxxxxxxxxxx

or your username and password (which will result in an additional test for creating the token)

    export username=tester
    export password=testpw

for testing against a specific project/story/member

    export project_id=123456
    export story_id=9876546
    export member_id=192837

finally run the tests using:

    make test

For more information:

• PivotalTracker API v3 Documentation

API methods

For examples see tests/test.js

pivotal.getToken : retrieve a user's token

ref: https://www.pivotaltracker.com/help/api?version=v3#retrieve_token_post

Arguments

• user : user name (email)
• pass : the user's password

pivotal.useToken : set the token to use for all Pivotal callso

Arguments

• token: A valid Pivotal Token

pivotal.getActivities: list activities for the projects you have access to

ref: https://www.pivotaltracker.com/help/api?version=v3#get_all_activity

Arguments

• filters : Limits the return data

{
    project (int)       : project id
    limit               : maximum return entries
    occurred_since_date : earliest date for return entries
    newer_than_version  : allows restricting the activity feed to only those items that have a greater than supplied version
}

pivotal.getProjectActivities: list activities for the projects you have access to

ref: https://www.pivotaltracker.com/help/api?version=v3#get_project_activity

Arguments

• project (int) : project id
• filters : Limits the return data

{
    limit               : maximum return entries
    occurred_since_date : earliest date for return entries
    newer_than_version  : allows restricting the activity feed to only those items that have a greater than supplied version
}

pivotal.getProjects : get all the projects you have access to

ref: https://www.pivotaltracker.com/help/api?version=v3#get_project_all_projects

pivotal.getProject : access a project

ref: https://www.pivotaltracker.com/help/api?version=v3#get_project_info

Arguments

• id (int) : id of the project

pivotal.addProject : create a project

ref: https://www.pivotaltracker.com/help/api?version=v3#add_project

Arguments

• project : Data of the project to add

{
    name (string)                   : The project's name
    iteration_length (int)          : Iteration length
    no_owner (boolean, optional)    : Does the project have an owner?
}

pivotal.getMemberships : get the members of this projects

ref: https://www.pivotaltracker.com/help/api?version=v3#get_memberships

Arguments

• projectId (int) : id of the project

pivotal.getMembership : get a single member of this projects

ref: https://www.pivotaltracker.com/help/api?version=v3#get_membership_info

Arguments

• projectId (int) : id of the project
• membershipId (int) : id of the member

pivotal.addMembership : add a member to this projects

ref: https://www.pivotaltracker.com/help/api?version=v3#add_membership

Arguments

• projectId (int) : id of the project
• membershipData : Data of the new member

{
    role : Member or Owner
    person : Personal information {
        name     : Person's full name
        initials : Name's initials
        email    : E-mail
    }
}

Note: The user does not have to be in the system already. He will receieve an email asking him to join if he does not have a project already.

pivotal.removeMembership : remove a single member of this projects

ref: https://www.pivotaltracker.com/help/api?version=v3#remove_membership

Arguments

• projectId (int) : id of the project
• membershipId (int) : id of the member

pivotal.getIterations : get a project list of iterations

ref: https://www.pivotaltracker.com/help/api?version=v3#get_iterations

Arguments

• projectId (int) : id of the project
• filters : Limits the return data

{
    group               : filter by iteration type [done|current|backlog|current_backlog]
    limit               : maximum return entries
    offset              : start from story num. N in the list
}

pivotal.getDoneIterations: get a project completed iterations

ref: https://www.pivotaltracker.com/help/api?version=v3#get_iterations

Arguments

• projectId (int) : id of the project
• filters : Limits the return data

{
    limit               : maximum return entries
    offset              : start from story num. N in the list
}

pivotal.getCurrentIteration : get a project current iteration

ref: https://www.pivotaltracker.com/help/api?version=v3#get_iterations

Arguments

• projectId (int) : id of the project

pivotal.getBacklogIterations: get a project backlog

ref: https://www.pivotaltracker.com/help/api?version=v3#get_iterations

Arguments

• projectId (int) : id of the project
• filters : Limits the return data

{
    limit               : maximum return entries
    offset              : start from story num. N in the list
}

pivotal.getCurrentBacklogIterations: get a project backlog and current iterations

ref: https://www.pivotaltracker.com/help/api?version=v3#get_iterations

Arguments

• projectId (int) : id of the project

pivotal.getStories: Get a list of stories for this project

ref: https://www.pivotaltracker.com/help/api?version=v3#get_all_stories

Arguments

• projectId (int) : id of the project
• filters : Limits the return data

{
    limit               : maximum return entries
    offset              : start from story num. N in the list
    filter              : search string to use (ex: filter=label:"needs feedback" type:bug)
}

pivotal.getStory: Get a story from a project

ref: https://www.pivotaltracker.com/help/api?version=v3#get_story

Arguments

• projectId (int) : id of the project
• storyId (int) : id of the story

pivotal.addStory: Add a story to a project

ref: https://www.pivotaltracker.com/help/api?version=v3#add_story

    and

 https://www.pivotaltracker.com/help/api?version=v3#link_story

Arguments

• projectId (int) : id of the project
• storyData : data of the story

{
    name           : Name of this story
    story_type     : bug, feature, chore, release
    estimate (int) : number which indicates the level of difficulty of the story
    description    : description,
    labels         : Comma-separated list of labels
    requested_by   : Name of the requester
                   (should be an existing member person name,
                   but I dont know if this is an actual limitation)
}

pivotal.addStoryAttachment: Add a file to a story

ref: https://www.pivotaltracker.com/help/api?version=v3#upload_attachment

Arguments

• projectId (int) : id of the project
• storyId (int) : id of the story
• fileData : information of file to upload

{
    name : filename of the file after upload
    path : path to the file on disk
    data : if no path is provided, one may
           simply put the data of the file in there instead
}

pivotal.addStoryComment: Add a comment to a story

ref: https://www.pivotaltracker.com/help/api?version=v3#add_note

Arguments

• projectId (int) : id of the project
• storyId (int) : id of the story
• comment (string) : The text of the comment to add

pivotal.updateStory: Update story infos and/or move a story to a different project

ref: https://www.pivotaltracker.com/help/api?version=v3#update_story

Arguments

• projectId (int) : id of the project
• storyData : data of the story

{
    project_id     : Id of the project
    name           : Name of this story
    story_type     : bug, feature, chore, release
    estimate (int) : number which indicates the level of difficulty of the story
    description    : description,
    labels         : Comma-separated list of labels
    requested_by   : Name of the requester
                   (should be an existing member person name,
                   but I dont know if this is an actual limitation)
}

pivotal.moveStory: move a story in the list of priority

ref: https://www.pivotaltracker.com/help/api?version=v3#move_stories

Arguments

• projectId (int) : id of the project
• storyId (int) : id of the story
• moveData : Information on how the move should happen

{
    target : Id of the destination story
    move   : before or after (the target story)
}

pivotal.removeStory: remove a story from a project

ref: https://www.pivotaltracker.com/help/api?version=v3#delete_story

Arguments

• projectId (int) : id of the project
• storyId (int) : id of the story

pivotal.deliverAllFinishedStories: self-explanatory

ref: https://www.pivotaltracker.com/help/api?version=v3#deliver_all_finished

Arguments

• projectId (int) : id of the project

pivotal.getTasks: Get tasks for a story

ref: https://www.pivotaltracker.com/help/api?version=v3#view_task

Arguments

• projectId (int) : id of the project
• storyId (int) : id of the story

pivotal.getTask: Get a task from a story

ref: https://www.pivotaltracker.com/help/api?version=v3#view_task

Arguments

• projectId (int) : id of the project
• storyId (int) : id of the story
• taskId (int) : id of the task

pivotal.addTask : add a task to a story

ref: https://www.pivotaltracker.com/help/api?version=v3#add_task

Arguments

• projectId (int) : id of the project
• storyId (int) : id of the story
• taskData : data of the task

{
    description : text of the task
    complete    : true of false
}

pivotal.updateTask : add a task to a story

ref: https://www.pivotaltracker.com/help/api?version=v3#update_task

Arguments

• projectId (int) : id of the project
• storyId (int) : id of the story
• taskId (int) : id of the task
• taskData : data of the task

{
    description : text of the task
    complete    : true of false
}

pivotal.removeTask : remove a task from a story

ref: https://www.pivotaltracker.com/help/api?version=v3#delete_task

Arguments

• projectId (int) : id of the project
• storyId (int) : id of the story
• taskId (int) : id of the task