Have ideas to improve npm?Join in the discussion! »

    This package has been deprecated

    Author message:

    We have abandoned this project.

    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published


    We have abandoned this project/module after switching to a different service.

    You're welcome to fork this project and keep it going if you've found it useful!

    BscotchMonday: The Monday.com API API

    WARNING: This project is in active development and will likely have breaking changes in each new version.

    Monday.com has a robust GraphQL API for automating tasks and building tools, but using it requires a lot of documentation-reading and additional infrastructure to keep track of all the data.

    This project aims to provide an API for the API, abstracting away the GraphQL bits and making it easier to collect, manage, update, and track data.

    BscotchMonday is designed around Node/JavaScript tooling to make it so that your tools (like VSCode, Typescript, ESLint, etc) can help you as much as possible.


    Install from npm: `npm i

    Typescript (node.js)

    import {fetchMondayAccount} from "@bscotch/monday";
    const yourMondayAPIToken = 'your private token';
    // Load an account in an async function somewhere:
    const account = await fetchMondayAccount(yourMondayAPIToken);
    // ...or by chaining with `then`:
      .then(account=>{/** do something */});

    JavaScript (node.js):

    const {fetchMondayBoard} = require('@bscotch/monday');
    /** @typedef {import('@bscotch/monday').MondayAccount} MondayAccount
     * (load other types similarly for typing via JSDoc)
     * /

    Your API Token can be specified via the environment variable MONDAY_API_TOKEN, in which case you can leave it out of the account options.



    BscotchMonday creates a heirarchy of classes starting with a MondayAccount. A MondayAccount contains and manages users, tags, boards, and other account-wide data. Each type of complex data has its own class. A MondayBoard contains a list of MondayGroups, which are the level at which you'll manage MondayItems.

    // Get an account and account-wide data
    const account  = await fetchMondayAccount('your-api-token');
    const users    = account.users;
    const myUser   = account.getUserByEmail('email@example.com');
    const tags     = account.tags;
    const myTag    = account.getTagByName('my-tag');
    // Get a board and its data
    const board    = account.getBoardById('your-board-id');
    const groups   = board.groups;
    const myGroup  = board.getGroupByName('My Group');
    const tags     = board.tags;
    const columns  = board.columns;
    const myColumn = board.getColumnByName('My Column');
    // Items are managed at the Group level
    const newItem = await myGroup.createItem('Item name');
    // Column Values are managed at the Item level.
    // Change sare only submitted upon `item.push()`
    const itemCheckbox = newItem.getColumnValueByName("Checkbox Column");
    const itemTags = newItem.getColumnValueByName("Tags");
    itemTags.setTags(['a-tag','another-tag']); // Must already exist
    await newItem.push(); // Submit changed values to Monday.com
    await newItem.delete(); // Perhaps you need to clean up after yourself.


    BscotchMonday caches data but has no automatic cache-updating behavior. Where relevant, instances have a .pull() method that will fetch up-to-date data at that heirarchical level (and replace local data with it).

    If you are using long-lived instances (which would be a good idea, since a lot of data has to be fetched on MondayBoard instancing) you may also want to set up some refresh logic.

    WARNING: To keep things generally immutable, when you obtain arrays of things (like users, tags, etc) you'll usually end up with a shallow copy. While .pull()ed data tries to update instances in-place, it can't update your shallow copies. So always use BscotchMonday getters when you need to guarantee that you have complete and up-to-date data.

    // Refresh the list of users, tags, boards, and any other
    // account-wide data
    // Perhaps you need a specific board to be refreshed more frequently
    // than others. Refresh a specific board:
    await board.pull();
    // Set an interval to guarantee freshness
    setInterval(board.pull, 60000); // refresh every minute
    // Make sure your Item is up to date before making a change
    // Items must be refreshed individually, since they are not
    // stored by any BscotchMonday instances.
    await item.pull();
    // ... do some stuff to the item
    await item.push();


    Testing acts against the live Monday.com servers to ensure that behavior matches how Monday.com currently works.

    To test, set up a root .env file and specify the environment variables you see in ./src/test/index.ts to match your Monday.com test account.




    npm i @bscotch/monday

    DownloadsWeekly Downloads






    Unpacked Size

    70.1 kB

    Total Files


    Last publish


    • avatar