trello-helper
v3.0.7
Published
Simpler interface for setting and retrieving data using the Trello API
Downloads
88
Maintainers
Readme
Trello Helper - Simplifying the Trello API
This project is designed to make using the Trello API easier and it provides several dozen higher level functions to perform common tasks. Most of the functions take a single parameter with object property names that help describe the function. This means you can't get the parameters in the wrong order. If you don't need the options or body properties, you can leave the property off. Declaration files have been created so you should get full code assistance if your editor supports it and full type safety if you use it from TypeScript.
Example call to get cards on list with and without option property specified
getCardsOnlist({ listId: "123", options: { limit: 10 } });
// or
getCardsOnList({ listId: "123" });
Additionally, this package wraps the get
, put
, post
, and delete
commands to the Trello API to take card of the authorization elements. But, it also exposes many higher-level commands needed for working with boards, lists, cards, actions, and custom fields. The wrappers all use Promises (no callback syntax support), and the code uses async/await
syntax.
Table of Contents
- Installation
- Cheat Sheet
- Contributing
- Testing
- Integration Tests
- Dependencies
- Available Functions and Documentation
Installation
npm install trello-helper
Cheat Sheet
const { Trello } = require("trello-helper");
const trello = new Trello({ path: "/Users/ENV_VARS/trello.env.json" });
const demo = async () => {
// get all the cards on the specified list
const cardsOnList = await trello.getCardsOnList({
listId: "5c9a9d8afcf46f3f1fdb6698"
});
// get all the actions on card 123 that are of type 'moveToBoard'
const mtbActions = await trello.getActionsOnCard({
cardId: "5c9a9d95f770d24919eb7edb",
options: { filter: "moveToBoard" }
});
// get up to 1000 actions on a card
const actions = await trello.getActionsOnCard({
cardId: "5c9a9d95f770d24919eb7edb"
});
// get all the custom field data for a card
const cf = await trello.getCustomFieldItemsOnCard({
cardId: "5c9a9d95f770d24919eb7edb"
});
// set the value of a custom field
await trello.setCustomFieldValueOnCard({
cardFieldObj: {
cardId: "5c9a9d95f770d24919eb7edb",
fieldId: "5c9e45e513d1db64b50fdca2"
},
type: "text",
value: "some data"
});
};
If you pass an empty string to the Trello
constructor, it will look for your credentials in the root folder of the project in a file named .env.json. If you don't want to store your credentials there, pass the path to where they are. The credentials JSON file needs to have the following form:
{
"trelloHelper": {
"appKey": "your app key",
"token": "your token value"
}
}
You can have other items in this file, but trelloHelper
must be a top-level object in the file with the 'appKey' and 'token' property names. Of course, you must put in a valid app key and token strings for both properties.
If you want to create an environment variable with the proper string and don't want to use any file you can do that with two steps.
STEP 1: You need to create an environment variable named trelloHelper
and then store a string in it that looks like this:{"appKey":"your app key","token":"your token value"}
NOTE: Don't create a JSON object, you want a string. (The JSON.stringify()
version of the JSON Object) The trello helper constructor will JSON.parse() the contents of that variable to create the needed JSON object.
STEP 2: Call the trello helper constructor and tell it the environment variable already exists
const trello = new Trello({ useExistingEnvVar: true });
Contributing
See the Contributing file.
Dependencies
winston logging tool
env-create reads a JSON file and turns top level elements into environment variables
moment flexible handling of JavaScript dates and times
request
request-promise-native
Available Functions
See the GitHub documentation for the list of available functions and signatures.