Giter Club home page Giter Club logo

node-pivotal's Introduction

node-pivotal : Node.JS API Library for PivotalTracker

NPM

License: MIT

To install:

npm install pivotal

To use:

var Pivotal = require("pivotal");
var pivotal = new Pivotal("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:

API methods

For examples see tests/test.js

pivotal constructor : set the token to use for all Pivotal calls

Arguments

  • token: A valid Pivotal Token

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
  • storyId (int) : id of the story
  • storyData (obj) : data of the story
  • callback (function) : callback function
{
    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

node-pivotal's People

Stargazers

avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar avatar avatar avatar avatar avatar

Forkers

kuccello shumkov tpmo lawnsea stelcheck tiii jakerella mrdnk d7p hshimo redrabbitdevelopment fpt mansuleman vanm nmcclay realyze cobjet-dev thujikun enterstudio demariainfo

node-pivotal's Issues

getToken() errors out...

Attempts to use getToken() return the error "The Pivotal API does not support file upload and XML POSTing at the same time".

useToken example not working

the api calls are all failing because passing the result of getToken to useToken isn't right, it needs to be result.guid: (note the differences of the second line in each segment below)

FAILS:
pivotal.getToken result.email, result.password, (err, token) ->
pivotal.useToken token
pivotal.getProjects (err, projects)->
console.log projects

passes:
pivotal.getToken result.email, result.password, (err, token) ->
pivotal.useToken token.guid
pivotal.getProjects (err, projects)->
console.log projects

Not sure whether the best option is to ammend .getApi or to just make note of this in the docs.

Thanks for the hard work!

xml2js failing on line 216

after I've set my token when the user hits the following route:

app.get('/projects', function(req, res) {
  var projects = pivotal.getProjects();
  res.send(projects);
});
/Users/Rob/Developer/Node/pivotal/node_modules/pivotal/node_modules/xml2js/lib/xml2js.js:216
          throw ex;
                ^
TypeError: undefined is not a function
    at /Users/Rob/Developer/Node/pivotal/node_modules/pivotal/index.js:648:17
    at Parser.<anonymous> (/Users/Rob/Developer/Node/pivotal/node_modules/pivotal/node_modules/xml2js/lib/xml2js.js:201:18)
    at Parser.emit (events.js:67:17)
    at Object.onclosetag (/Users/Rob/Developer/Node/pivotal/node_modules/pivotal/node_modules/xml2js/lib/xml2js.js:183:24)
    at emit (/Users/Rob/Developer/Node/pivotal/node_modules/pivotal/node_modules/xml2js/node_modules/sax/lib/sax.js:322:32)
    at emitNode (/Users/Rob/Developer/Node/pivotal/node_modules/pivotal/node_modules/xml2js/node_modules/sax/lib/sax.js:327:3)
    at closeTag (/Users/Rob/Developer/Node/pivotal/node_modules/pivotal/node_modules/xml2js/node_modules/sax/lib/sax.js:540:5)
    at Object.write (/Users/Rob/Developer/Node/pivotal/node_modules/pivotal/node_modules/xml2js/node_modules/sax/lib/sax.js:949:29)
    at Parser.<anonymous> (/Users/Rob/Developer/Node/pivotal/node_modules/pivotal/node_modules/xml2js/lib/xml2js.js:213:31)
    at Parser.parseString (/Users/Rob/Developer/Node/pivotal/node_modules/pivotal/node_modules/xml2js/lib/xml2js.js:6:61)

I added some console logs to xml2js and I can see that the correct xml is coming back from pivotal but it fails somewhere in that method.

Should work with multiple users.

I'm only just recently skimming through this as an option to playing with Pivotal Tracker's API, and I noticed that the process revolves around only one user using one Secret Key. If I want multiple users to use my dashboard, then I'd run into complications. Maybe it should be something along the lines of:

pivotalUser = pivotal.new(<api token>);
pivotalUser.command(data);

What do you think?

Feature: cli tool/shell

Create a CLI binary tool which allow a user to operate with PT. I know there is already https://github.com/baldrailers/pivotcli available, but I would like to gave a tool which allows the following:

  • shell mode, potentially with an auto activity watch
  • auto-configuration: first time you run the command, we ask for username and password, and store the token
  • Any suggestions welcome

Feature request: activity web hook

I would like to see an integration point for the PT activity web hook (https://www.pivotaltracker.com/help/integrations#activity_web_hook). The idea would be that Node accepts a post, and then the app passes the request on to this library which processes it, send the response, and makes a callback for processing by the app.

In pseudo-code:

// note that this is an Express post handler, but it should not require Express
app.post('/pt-activity-hook', function(req, res){
    // pivotal library would extract data and fill the response appropriately
    pivotal.handleActivityhook(req, res, function(activity) {
        // "activity" is the data in the <activity> xml node as JSON
        console.log("Activity captured!".green, activity);
        // any other processing
    });
});

I may try to implement this myself and I'll contribute if anything comes of it.

Completely non-functional now with the release of the validator module v3.0.0

The package.json file specifies version ">=0.3.9" for dependency module "validator". The problem is that major, breaking changes were introduced in their most recent release, v3.0.0. Any process running this module's code after a fresh npm install/update will crash to do unguarded references to properties of non-existent objects and/or calls on non-existent functions.

Feature: All API calls returning lists should return arrays

  • getActivities
  • getProjectActivities
  • getProjects
  • getMemberships
  • getIterations
  • getDoneIterations
  • getBacklogIterations
  • getCurrentBacklogIterations
  • getStories (already done in 0.2.0)
  • getTasks

Ideally, we will want to have some factory function for dealing with lists, and allowing us to simply plug that extra parser in each list API calls.

TypeError when adding memberships 

/Users/kevin/cumulus/node_modules/pivotal/index.js:913
                    val = sanitize(data[d].toString()).entityEncode();
                          ^
TypeError: undefined is not a function
  at Object.pivotal.toXml (/Users/kevin/cumulus/node_modules/pivotal/index.js:913:27)
  at Object.pivotal.toXml (/Users/kevin/cumulus/node_modules/pivotal/index.js:911:32)

The reason seems that Entity encoding is no longer in validator.js since version 3: https://github.com/chriso/validator.js#deprecations

How to get stories from all projects?

I am trying something like this:

app.get('/delivered_stories', function(request, response) { 
  pivotal.useToken("token");

  function get_stories(project_ids) {
    var array = []
    project_ids.forEach(function(id) {
      pivotal.getStories(340755, { filter: "state:finished" }, function(err, project_stories) {
        console.log("Project stories: ".blue + project_stories);
        array.push(project_stories);
      });
    });
    response.send(array);
  }

  pivotal.getProjects(function (err, data) {
    var project_ids = data.project.map(function(x) { return parseInt(x.id); });
    get_stories(project_ids);
  });
});

Could you help me with that?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.