@boostmoveo/monday-kit

The one toolkit to handle all things monday.com related with ease.

Quick Start

Installation

Install via npm:

using npm

npm install @boostmoveo/monday-kit

using yarn

yarn add @boostmoveo/monday-kit

Import & Initialization

import { MondayApi, SeamlessMondayApi } from '@boostmoveo/monday-kit';

// Server-side
const monday = new MondayApi({ token: '<YOUR_MONDAY_API_TOKEN>' });

// Client-side (monday.com apps)
const monday = new SeamlessMondayApi();

Note: MondayApi requires an API token and is intended for backend/server use. SeamlessMondayApi is for use inside monday.com apps and does not require a token.

Peer Dependencies

• @mondaydotcomorg/api (installed automatically)

Mutations

Create an Item

const result = await monday.mutate.items.createItem({
  boardId: 12345,
  groupId: 'topics',
  itemName: 'New Task',
});
console.log(result.create_item.id);

Send a Notification

await monday.notify({
  userId: 12345,
  targetId: 67890,
  targetType: NotificationTargetType.Project, // or 'Post'
  text: 'You have a new task!',
});

Upload a File

const fileBuffer = await readFile('/path/to/file');
await monday.files.addFileToColumn({
  itemId: 12345,
  columnId: 'files',
  file: fileBuffer,
  filename: 'example.pdf',
});

Queries

Pagination with Reader Interface

See the API docs and code comments for more advanced configuration and extension options.

const itemsReader = monday.query.boards.getBoardItems({ boardId: 12345 });
for await (const page of itemsReader) {
  console.log(page.items);
}

Automatic Retry Logic

When enabled (retryIfNeeded: true), the client will automatically retry requests that fail due to rate limits or complexity errors, using the recommended delay from the API. You can also use the static shouldRetry method to analyze errors:

try {
  await monday.query.boards.getBoards({ limit: 1 });
} catch (err) {
  const { retry, delayMs } = MondayApi.shouldRetry(err);
  if (retry) {
    setTimeout(() => {
      /* retry logic */
    }, delayMs);
  }
}

Override options

If you need to use a different api version or if you want to override the query you send, you may pass the wanted values into the options

const query = `
  query {
    me {
      id
      name
    }
  }
`;

const customQueryResult = await monday.query.me.getMe<{
  me: { id: number; name: string };
}>({ queryOverride: query, versionOverride: '2025-04' });

Note on type safety: To maintain full IntelliSense and type safety, pass your custom response type as a generic to the function. If your query includes variables, ensure you also define the variable types, especially for pagination-related queries, to ensure the library handles the underlying request correctly.

API Structure

• MondayApi: For server-side (Node.js) integrations. Requires an API token.
• SeamlessMondayApi: For client-side (monday.com apps) integrations. No token required.

Advanced Usage & Customization

Custom GraphQL Queries

You can send any custom query or mutation using the request or rawRequest method:

const query = `
  query ($boardId: ID!) {
    boards(ids: [$boardId]) { id name }
  }
`;
const result = await monday.rawRequest(query, { boardId: 12345 });
console.log(result.data.boards);

Access queries from the library

On each resource you can access the queries that are used for each method by using the queries field on it

Supported Resources & Types

Both MondayApi and SeamlessMondayApi expose the following main interfaces:

• query: Read/query operations (boards, items, users, etc.)
• mutate: Write/mutation operations (create/update boards, items, etc.)
• files: File upload and management
• notify: Send notifications to users

This library provides full, type-safe access to all major monday.com API resources, including:

• Boards
• Items
• Users
• Groups
• Columns & Column Values
• Files
• Notifications
• Tags
• Teams
• Updates
• Workspaces
• Account & Roles
• Activity Logs
• Audit Logs
• Folders & Docs
• Webhooks

Note: All types are based on the official monday.com API schema and are kept up-to-date with the upstream SDK. If you need a type that is missing, you can extend or override types using TypeScript's utility types.

Tooling to work with the monday api

To make working with the monday GraphQL API easier and fully type-safe, there is a simple setup command that prepares your project with all the required tooling.

You can run:

npx @mondaydotcomorg/setup-api@latest

Or, if you already have the mapps CLI installed:

mapps api:generate

Generating the schema and types

After running one of the commands above, make sure to run:

npm run fetch:generate

This will:

• Fetch the latest monday GraphQL schema
• Generate TypeScript types for all your GraphQL queries

Important: Your GraphQL queries must be placed in files whose names end with .graphql.ts (for example: me.graphql.ts). Only queries in files with this suffix are picked up by the code generator and included in the generated types.

Once you add or update a query, run:

npm run codegen

to generate (or update) the corresponding TypeScript types.

Example: a type-safe query

import { gql } from 'graphql-request';
import { MondayApi } from '@boostmoveo/monday-kit';

const meQuery = gql`
  query getMe {
    me {
      id
      name
    }
  }
`;

const mondayApi = new MondayApi({ token: '<API_TOKEN>' });
const getMeResponse = await mondayApi.request<GetMeQuery>(meQuery);

To read more you can go to the official tooling here

Troubleshooting & FAQ

Type Errors

• For custom types, use the utility types provided (Maybe, DeeplyPartial, etc.).

API Errors

• If you receive rate limit or complexity errors, enable retryIfNeeded or handle retries manually using shouldRetry.
• Ensure your API token has the correct scopes for the operations you are performing.

General

• For issues with file uploads, ensure you are passing a valid file stream or buffer.
• If you encounter a bug, please open an issue with a minimal reproduction.

Contributing, License & Contact

Contributing

Contributions, bug reports, and feature requests are welcome! Please open an issue or submit a pull request on GitHub.

Contact

Maintained by Idan Dover.