@ntr.dev/monday-kit v0.0.9

@ntr.dev/monday-kit

A powerful, type-safe TypeScript wrapper for the Monday.com SDK with built-in column value parsing, transformation, and validation. Designed specifically for seamless integration with Pipedream workflows and automation platforms.

🚀 Features

• 🎯 Type-Safe: Full TypeScript support with comprehensive type definitions
• 🔄 Smart Column Parsing: Automatic transformation of Monday.com column values to usable data types
• ⚡ Optimized for Pipedream: Pre-configured for Pipedream workflow integration
• 🧠 Intelligent Caching: Built-in board column caching to reduce API calls
• 🛡️ Error Handling: Robust validation and error handling for production use
• 📊 All Column Types: Support for all Monday.com column types (35+ types)
• 🔌 Service-Based Architecture: Organized by functionality (Items, Boards, Users, etc.)

📦 Installation

bun add @ntr.dev/monday-kit

🏁 Quick Start

Basic Setup

// Import the library
import { MondayClient } from '@ntr.dev/monday-kit';

// Initialize the client
const monday = new MondayClient('your-monday-api-token');

// Get item with transformed column values
const items = await monday.item.getItem({ 
  itemId: "item-id", 
  columnIds: ["status", "person", "date"] // optional - get specific columns
});

console.log(items); // Transformed, easy-to-use data

Environment Variables

Set your Monday.com API token as an environment variable:

MONDAY_API_TOKEN="your-token-here"

const monday = new MondayClient(process.env.MONDAY_API_TOKEN);

🔧 MondayClient API Reference

Core Services

The MondayClient provides access to six main services:

• item - Item operations (create, read, update, search)
• board - Board information (columns, groups)
• workspace - Workspace and board listing
• user - User management and lookup
• update - Item updates and comments
• subitem - Subitem operations

📋 Items Service

item.getItem(params)

Retrieve a single item with all its column values (parsed and transformed).

Parameters:

{
  itemId: string,       // Monday.com item ID
  columnIds?: string[]  // Optional: specific column IDs to fetch
}

Returns: Promise<Items> - Array of transformed item objects

Example:

const items = await monday.item.getItem({ 
  itemId: "1234567890",
  columnIds: ["status", "person", "date"]
});

// Result:
// [
//   {
//     id: "1234567890",
//     name: "My Task",
//     status: "Working on it",  // Parsed from status column
//     person: [12345, 67890],   // Array of user IDs
//     date: { date: "2024-01-15", time: "14:30:00" }
//   }
// ]

item.createItem(params)

Create a new item on a Monday.com board.

Parameters:

{
  itemName: string,                    // Name of the new item
  boardId: string,                     // Target board ID
  groupId?: string,                    // Optional: specific group ID
  columnValues?: Record<string, any>,  // Optional: Column values to set
  createLabels?: boolean               // Optional: Auto-create missing status labels; (default: false)
}

Returns: Promise<string> - Created item ID

Example:

const itemId = await monday.item.createItem({
  itemName: "New Task",
  boardId: "123456789",
  groupId: "topics",
  columnValues: {
    status: "Working on it",
    person: [12345],
    date: "2024-01-15T14:30:00Z",
    text: "Task description"
  },
  createLabels: true
});

item.updateItem(params)

Update column values for an existing item.

Parameters:

{
  itemId: string,                      // Item ID to update
  columnValues: Record<string, any>,   // Column values to update
  boardId: string,                     // Board ID (required for validation)
  createLabels?: boolean               // Optional: Auto-create missing status labels; (default: false)
}

Returns: Promise<string> - Updated item ID

Example:

const itemId = await monday.item.updateItem({
  itemId: "1234567890",
  boardId: "123456789",
  columnValues: {
    status: "Done",
    person: [12345, 67890],
    numbers: 42
  }
});

item.listItemsByColumnValues(params)

Search for items by specific column values.

Parameters:

{
  boardId: string,                              // Board to search in
  columns: Record<string, string | string[]>,   // Column filters
  limit?: number,                               // Optional: Max results (default: 25)
  columnIds?: string[]                          // Optional: Columns to return
}

Returns: Promise<Items> - Array of matching items

Example:

const items = await monday.item.listItemsByColumnValues({
  boardId: "123456789",
  columns: {
    status: "Working on it",
    person: ["12345"]
  },
  limit: 50,
  columnIds: ["status", "date", "text"]
});

📊 Boards Service

board.listBoardColumns(params)

Get all columns for a specific board.

Parameters:

{
  boardId: string  // Board ID
}

Returns: Promise<Column[]> - Array of board columns

Example:

const columns = await monday.board.listBoardColumns({ boardId: "123456789" });

// Result:
// [
//   { id: "status", title: "Status", type: "status" },
//   { id: "person", title: "Person", type: "people" },
//   { id: "date", title: "Due Date", type: "date" }
// ]

board.listBoardGroups(params)

Get all groups for a specific board.

Parameters:

{
  boardId: string  // Board ID
}

Returns: Promise<Group[]> - Array of board groups

Example:

const groups = await monday.board.listBoardGroups({ boardId: "123456789" });

🏢 Workspaces Service

workspace.listWorkspaces()

Get all workspaces accessible to the current user.

Parameters: None

Returns: Promise<Workspace[]> - Array of workspaces

Example:

const workspaces = await monday.workspace.listWorkspaces();

workspace.listWorkspaceBoards(params)

Get all boards in a specific workspace.

Parameters:

{
  workspaceId: string  // Workspace ID
}

Returns: Promise<Board[]> - Array of boards

Example:

const boards = await monday.workspace.listWorkspaceBoards({ 
  workspaceId: "12345" 
});

👥 Users Service

user.listUsers()

Get all users in the account.

Parameters: None

Returns: Promise<User[]> - Array of users

Example:

const users = await monday.user.listUsers();

user.getUserById(params)

Get a specific user by their ID.

Parameters:

{
  userId: string  // User ID
}

Returns: Promise<User> - User object

Example:

const user = await monday.user.getUserById({ userId: "12345" });

user.getUserByEmail(params)

Get a specific user by their email address.

Parameters:

{
  email: string  // User email
}

Returns: Promise<User> - User object

Example:

const user = await monday.user.getUserByEmail({ 
  email: "user@company.com" 
});

💬 Updates Service

update.createUpdate(params)

Create an update (comment) on an item.

Parameters:

{
  itemId: string,      // Item ID
  updateBody: string   // Update content
}

Returns: Promise<string> - Created update ID

Example:

const updateId = await monday.update.createUpdate({
  itemId: "1234567890",
  updateBody: "Task completed successfully!"
});

📎 Subitems Service

subitem.listSubitems(params)

Get all subitems for a parent item.

Parameters:

{
  itemId: string,       // Parent item ID
  columnIds?: string[]  // Optional: specific columns to fetch
}

Returns: Promise<Subitems> - Array of transformed subitem objects

Example:

const subitems = await monday.subitem.listSubitems({ 
  itemId: "1234567890",
  columnIds: ["status", "person"]
});

subitem.createSubitem(params)

Create a new subitem under a parent item.

Parameters:

{
  itemName: string,                    // Name of the new subitem
  parentItemId: string,                // Parent item ID
  columnValues?: Record<string, any>,  // Optional: Column values to set
  createLabels?: boolean               // Optional: Auto-create missing status labels; (default: false)
}

Returns: Promise<string> - Created subitem ID

Example:

const subitemId = await monday.subitem.createSubitem({
  itemName: "New Subtask",
  parentItemId: "1234567890",
  columnValues: {
    status: "Working on it",
    person: [12345]
  },
  createLabels: true
});

🔄 Column Value Transformation

The library automatically transforms Monday.com's complex column values into simple, usable formats:

Supported Column Types (35+)

• Auto Number, Button, Checkbox, Color Picker
• Board Relation, Country, Creation Log, Date
• Dependency, Dropdown, Email, Files
• Formula, Hour, Item ID, Last Updated
• Link, Location, Long Text, Mirror
• Doc, Name, Numbers, People
• Phone, Progress, Rating, Status
• Tags, Text, Timeline, Time Tracking
• Vote, Week, World Clock

🔌 Pipedream Integration

Basic Pipedream Workflow

import { MondayClient } from '@ntr.dev/monday-kit';

export default defineComponent({
  props: {
    monday_api_token: {
      type: "string",
      secret: true,
      label: "Monday.com API Token"
    }
  },
  async run({ steps, $ }) {
    const monday = new MondayClient(this.monday_api_token);
    
    // Example: Get item and transform data
    const items = await monday.item.getItem({ 
      itemId: steps.trigger.event.itemId,
      columnIds: ["status", "person", "date"]
    });
    
    return { 
      transformed_items: items,
      count: items.length 
    };
  }
});

Pipedream Webhook Handler

export default defineComponent({
  async run({ steps, $ }) {
    const monday = new MondayClient(process.env.MONDAY_API_TOKEN);
    
    // Handle Monday.com webhook data
    const webhookData = steps.trigger.event;
    
    if (webhookData.event.type === 'create_item') {
      const items = await monday.item.getItem({ 
        itemId: webhookData.event.itemId 
      });
      
      // Process the transformed data
      return { processed_item: items[0] };
    }
  }
});

Error Handling in Pipedream

export default defineComponent({
  async run({ steps, $ }) {
    const monday = new MondayClient(this.monday_api_token);
    
    try {
      const items = await monday.item.getItem({ itemId: "invalid-id" });
      return { success: true, data: items };
    } catch (error) {
      // Pipedream will catch and display this error
      throw new Error(`Monday.com API error: ${error.message}`);
    }
  }
});

🛠️ Advanced Usage

Legacy Method Support

For backward compatibility, the original method structure is still available:

// New service-based approach (recommended)
const items = await monday.item.getItem({ itemId: "123" });

// Legacy method approach (still supported)
const items = await monday.items.get({ itemId: "123" });

Caching Control

// Clear cache for a specific board (available on ItemService and SubitemService)
monday.item.clearCache("board-id");

// Clear all cached data
monday.item.clearCache();

Direct API Access

// Access the underlying Monday.com SDK
const response = await monday.api({
  query: 'query { me { name email } }',
  variables: {}
});

Batch Operations

// Create multiple items efficiently
const itemIds = await Promise.all([
  monday.item.createItem({ itemName: "Task 1", boardId: "123" }),
  monday.item.createItem({ itemName: "Task 2", boardId: "123" }),
  monday.item.createItem({ itemName: "Task 3", boardId: "123" })
]);

🐛 Error Handling

The library provides comprehensive error handling:

try {
  const items = await monday.item.getItem({ itemId: "item-id" });
} catch (error) {
  if (error.message.includes('itemId is required')) {
    // Handle validation error
  } else if (error.message.includes('API')) {
    // Handle API error
  }
}

📝 TypeScript Support

Full TypeScript definitions are included:

import { MondayClient, Items, Column, User } from '@ntr.dev/monday-kit';

const monday: MondayClient = new MondayClient(token);
const items: Items = await monday.item.getItem({ itemId: "123" });

📈 Performance Tips

1. Use Column Filtering: Specify columnIds to fetch only needed data
2. Leverage Caching: Board columns are automatically cached
3. Batch Operations: Use Promise.all() for multiple concurrent requests
4. Error Boundaries: Implement proper error handling in production

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

ISC License

🔗 Related Links

• Monday.com API Documentation
• Pipedream Documentation
• TypeScript Documentation

Made with ❤️ by NTR.DEV for the automation community.