JavaScript SDK monday.com (@mondaydotcomorg/api) zapewnia typowany i wygodny sposób komunikacji z GraphQL API monday.com w środowisku Node.js lub przeglądarki. Opakowuje bibliotekę graphql-request i zawiera gotowe operacje, pełne typy TypeScript wygenerowane na podstawie schematu API oraz automatyczne wersjonowanie API.

Powiązany pakiet (@mondaydotcomorg/setup-api) przygotowuje szkielet procesu GraphQL codegen, dzięki czemu możesz tworzyć własne zapytania z pełnym bezpieczeństwem typów.

Pakiet	Zastosowanie	Najnowsza wersja
@mondaydotcomorg/api	Klient API, typy, gotowe operacje	14.0.0
@mondaydotcomorg/setup-api	CLI do przygotowania szkieletu GraphQL codegen	2.1.1

---

Instalacja

npm install @mondaydotcomorg/api

Pakiet działa zarówno w środowisku Node.js (v18+), jak i przeglądarki.

Zależności

SDK korzysta z graphql, graphql-request, graphql-tag i zod. Pakiety te instalują się automatycznie.

---

ApiClient

ApiClient to główny punkt wejścia. Wymaga tokenu API, a opcjonalnie przyjmuje wersję API i konfigurację żądania.

Tworzenie klienta

import { ApiClient } from '@mondaydotcomorg/api';

const client = new ApiClient({
  token: '<YOUR_API_TOKEN>',
});

Opcje konstruktora

Opcja	Typ	Wymagana	Wartość domyślna	Opis
token	string	Tak	-	Twój token API monday.com (osobisty lub OAuth). Jest wysyłany w nagłówku Authorization.
apiVersion	string	Nie	'2026-01' (aktualna w chwili wydania SDK)	Wersja API w formacie yyyy-mm. Dozwolone miesiące: 01, 04, 07, 10. Akceptowana jest również wartość 'dev'.
endpoint	string	Nie	'https://api.monday.com/v2'	Zastępuje adres URL punktu końcowego API.
requestConfig	RequestConfig	Nie	{}	Przekazywana do bazowego klienta graphql-request. Obejmuje m.in. errorPolicy, headers, fetch i requestMiddleware.

const client = new ApiClient({
  token: '<YOUR_API_TOKEN>',
  apiVersion: '2025-10',
  requestConfig: {
    errorPolicy: 'all',
  },
});

📘 Weryfikacja wersji API

Konstruktor zgłasza błąd, jeśli apiVersion nie pasuje do formatu yyyy-mm z miesiącem 01, 04, 07 lub 10 (albo wartością 'dev'). Na przykład wartość '2025-03' zostanie odrzucona.

---

Dowolne zapytania

Użyj client.request(), aby wykonać dowolne zapytanie lub mutację GraphQL.

Podstawowe zapytanie

const result = await client.request(`
  query {
    boards(ids: [12345]) {
      id
      name
      columns { id title type }
    }
  }
`);

console.log(result.boards);

Z użyciem zmiennych

const result = await client.request(
  `query ($ids: [ID!]!) {
    boards(ids: $ids) {
      id
      name
      items_page(limit: 5) {
        items { id name }
      }
    }
  }`,
  { ids: ["12345", "67890"] }
);

Z użyciem generyków TypeScript

Możesz przekazać parametr typu do request(), aby określić typ odpowiedzi:

import { Board } from '@mondaydotcomorg/api';

const { boards } = await client.request<{ boards: Board[] }>(
  `query { boards(ids: [12345]) { id name } }`
);

👍 Wskazówka

SDK eksportuje wszystkie typy GraphQL ze schematu monday.com (np. Board, Item, Column, User, Group, ColumnType itd.). Importuj je bezpośrednio, aby zapewnić bezpieczeństwo typów w odpowiedziach.

Opcje żądania

Trzeci parametr request() przyjmuje:

Opcja	Typ	Opis
versionOverride	string	Zastępuje wersję API dla pojedynczego żądania. Obowiązują te same zasady weryfikacji co w konstruktorze.
timeoutMs	number	Limit czasu żądania w milisekundach (maks. 60 000). Żądanie zostaje przerwane, jeśli API nie odpowie na czas.

const result = await client.request(
  `query { me { id name } }`,
  undefined,
  { versionOverride: '2025-10', timeoutMs: 10000 }
);

---

Surowe żądania

Użyj client.rawRequest(), jeśli potrzebujesz pełnej struktury odpowiedzi, obejmującej data, errors i extensions:

const response = await client.rawRequest(`query { me { id name } }`);

console.log(response.data);       // { me: { id: '...', name: '...' } }
console.log(response.extensions);  // API metadata (complexity, etc.)
console.log(response.errors);      // Any GraphQL errors (if errorPolicy allows)

rawRequest() przyjmuje te same parametry co request() (zapytanie, zmienne, opcje).

---

Gotowe operacje

SDK zawiera gotowe operacje dostępne przez client.operations. Są to typowane dokumenty GraphQL z dedykowanymi metodami - nie musisz samodzielnie pisać zapytań.

Dostępne operacje

Metoda	Typ	Opis
getMeOp()	Zapytanie	Zwraca id, name i email uwierzytelnionego użytkownika.
getBoardItemsOp({ ids })	Zapytanie	Zwraca elementy (wraz z wartościami kolumn) z określonych tablic.
getBoardGroupsOp({ ids })	Zapytanie	Zwraca grupy (z id i title) z określonych tablic.
createItemOp({ boardId, groupId, itemName })	Mutacja	Tworzy nowy element w określonej tablicy i grupie.
changeSimpleColumnValueOp({ boardId, itemId, columnId, value })	Mutacja	Ustawia wartość kolumny za pomocą zwykłego ciągu znaków.
changeColumnValueOp({ boardId, itemId, columnId, value })	Mutacja	Ustawia wartość kolumny za pomocą wartości JSON.
changeMultipleColumnValuesOp({ boardId, itemId, columnValues })	Mutacja	Ustawia jednocześnie wartości kilku kolumn za pomocą ciągu JSON.

Przykłady

Pobieranie bieżącego użytkownika

const { me } = await client.operations.getMeOp();
console.log(me.name, me.email);

Pobieranie elementów z tablicy

const { boards } = await client.operations.getBoardItemsOp({
  ids: ["12345"],
});

for (const board of boards) {
  for (const item of board.items_page.items) {
    console.log(item.id, item.name);
    for (const col of item.column_values) {
      console.log(`  ${col.id} (${col.type}): ${col.value}`);
    }
  }
}

Tworzenie elementu

const { create_item } = await client.operations.createItemOp({
  boardId: "12345",
  groupId: "topics",
  itemName: "New task from SDK",
});

console.log("Created item:", create_item.id);

Zmiana wartości pojedynczej kolumny

// Simple string value (for text columns)
await client.operations.changeSimpleColumnValueOp({
  boardId: "12345",
  itemId: "67890",
  columnId: "text_column",
  value: "Hello from SDK!",
});

// JSON value (for structured columns like status, date, etc.)
await client.operations.changeColumnValueOp({
  boardId: "12345",
  itemId: "67890",
  columnId: "status_column",
  value: JSON.stringify({ label: "Done" }),
});

Jednoczesna zmiana wartości kilku kolumn

await client.operations.changeMultipleColumnValuesOp({
  boardId: "12345",
  itemId: "67890",
  columnValues: JSON.stringify({
    text_column: "Updated text",
    status_column: { label: "Working on it" },
    date_column: { date: "2026-04-01" },
  }),
});

📘 Format wartości kolumn

Parametr value w metodach changeColumnValueOp i changeMultipleColumnValuesOp musi zawierać wartość przekonwertowaną na ciąg JSON. Każdy typ kolumny wymaga określonej struktury JSON. Szczegóły znajdziesz w dokumentacji wartości kolumn.

---

Przesyłanie plików

SDK obsługuje przesyłanie plików za pomocą standardowej mutacji GraphQL add_file_to_column. Przekaż obiekt Node.js File lub Blob w zmiennych, a klient automatycznie zmieni żądanie na wieloczęściowe.

import { ApiClient } from '@mondaydotcomorg/api';
import { readFileSync } from 'fs';

const client = new ApiClient({ token: '<YOUR_API_TOKEN>' });

const file = new File(
  [readFileSync('./report.pdf')],
  'report.pdf',
  { type: 'application/pdf' }
);

const result = await client.request(
  `mutation ($file: File!, $itemId: ID!, $columnId: String!) {
    add_file_to_column(file: $file, item_id: $itemId, column_id: $columnId) {
      id
      name
      url
    }
  }`,
  {
    file,
    itemId: '67890',
    columnId: 'files',
  }
);

console.log(result.add_file_to_column);

⚠️ Ważne

Przesyłanie plików korzysta z wbudowanych w Node obiektów File i Blob (dostępnych od Node 18). Middleware SDK do przesyłania plików wykrywa te obiekty i automatycznie zmienia żądanie na multipart/form-data.

---

Obsługa błędów

ClientError

Gdy żądanie GraphQL się nie powiedzie, SDK zgłasza błąd ClientError (eksportowany ponownie z graphql-request):

import { ApiClient, ClientError } from '@mondaydotcomorg/api';

const client = new ApiClient({ token: '<YOUR_API_TOKEN>' });

try {
  await client.request(`query { invalid_field }`);
} catch (error) {
  if (error instanceof ClientError) {
    console.error('GraphQL errors:', error.response.errors);
    // [{ message: 'Cannot query field "invalid_field" on type "Query".', locations: [...] }]
  } else {
    console.error('Network or other error:', error);
  }
}

Zasady obsługi błędów

Domyślnie klient zgłasza błąd przy każdym błędzie GraphQL. Możesz zmienić to zachowanie za pomocą errorPolicy w konstruktorze:

Zasada	Działanie
'none' (domyślnie)	Zgłasza błąd przy każdym błędzie.
'ignore'	Zwraca rozwiązaną obietnicę i całkowicie ignoruje błędy.
'all'	Zwraca zarówno dane, jak i błędy. Użyj z rawRequest(), aby uzyskać częściowe dane razem z błędami.

const client = new ApiClient({
  token: '<YOUR_API_TOKEN>',
  requestConfig: { errorPolicy: 'all' },
});

const response = await client.rawRequest(`query { ... }`);
console.log(response.data);    // partial data (if any)
console.log(response.errors);  // error details

---

SeamlessApiClient

SeamlessApiClient jest przeznaczony do kodu po stronie klienta działającego wewnątrz aplikacji monday.com (np. widoku tablicy lub elementu w ramce iframe). Komunikuje się z API monday.com za pośrednictwem wewnętrznego mechanizmu postMessage platformy - nie wymaga tokenu API.

import { SeamlessApiClient, Board } from '@mondaydotcomorg/api';

const client = new SeamlessApiClient();

const { boards } = await client.request<{ boards: Board[] }>(
  `query { boards(ids: [12345]) { id name } }`
);

Konstruktor SeamlessApiClient

Opcja	Typ	Wartość domyślna	Opis
apiVersion	string	Aktualna wersja w chwili wydania SDK	Wersja API używana w żądaniach.

SeamlessApiClient.request()

Parametr	Typ	Wymagany	Opis
query	string	Tak	Ciąg znaków zawierający zapytanie lub mutację GraphQL.
variables	Record<string, any>	Nie	Zmienne zapytania.
version	string	Nie	Zastąpienie wersji API dla pojedynczego żądania.
timeout	number	Nie (domyślnie 60000)	Limit czasu żądania w ms.

Obsługa błędów

Błędy z SeamlessApiClient są instancjami SeamlessApiClientError:

import { SeamlessApiClient, SeamlessApiClientError } from '@mondaydotcomorg/api';

const client = new SeamlessApiClient();

try {
  await client.request(`query { boards { id } }`);
} catch (error) {
  if (error instanceof SeamlessApiClientError) {
    console.error(error.message);
    console.error(error.response.errors);
  }
}

⚠️ Tylko przeglądarka

SeamlessApiClient korzysta z window.postMessage i działa tylko wewnątrz ramki iframe aplikacji monday.com. W kodzie po stronie serwera lub samodzielnych skryptach użyj ApiClient z tokenem.

---

Wersjonowanie API

API monday.com jest wersjonowane kwartalnie. SDK automatycznie wysyła nagłówek API-Version z każdym żądaniem.

Format wersji

Wersje mają format yyyy-mm, gdzie miesiąc to 01, 04, 07 lub 10 (wydania kwartalne). Specjalna wartość 'dev' wskazuje wersję deweloperską lub poglądową.

Cykl życia wersji

Etap	Opis
current	Bieżąca stabilna wersja.
release_candidate	Następna wersja, dostępna w wersji poglądowej.
maintenance	Poprzednia wersja, która jest nadal obsługiwana.
deprecated	Wersja, która nie jest już obsługiwana i z czasem przestanie działać.
dev	Niestabilna wersja poglądowa z nadchodzącymi zmianami.

Ustawianie wersji

// Set at client creation (applies to all requests including operations)
const client = new ApiClient({
  token: '<YOUR_API_TOKEN>',
  apiVersion: '2025-10',
});

// Override per-request
const result = await client.request(
  `query { me { id } }`,
  undefined,
  { versionOverride: '2026-01' }
);

Eksportowane stałe

import { DEFAULT_VERSION, MONDAY_API_ENDPOINT, AvailableVersions } from '@mondaydotcomorg/api';

console.log(DEFAULT_VERSION);        // '2026-01'
console.log(MONDAY_API_ENDPOINT);    // 'https://api.monday.com/v2'
console.log(AvailableVersions);      // { CURRENT_VERSION: '2026-01', CURRENT: 'current', ... }

---

Typy TypeScript

SDK eksportuje wszystkie typy ze schematu GraphQL monday.com. Są one generowane na podstawie schematu API aktualnego w chwili opublikowania pakietu.

Często używane typy

Typ	Opis
Board	Tablica monday.com ze wszystkimi polami.
Item	Element (wiersz) na tablicy.
Column	Definicja kolumny na tablicy.
ColumnValue	Podstawowy interfejs dla wartości kolumn. Typ unii obejmujący konkretne typy wartości, np. TextValue, StatusValue, DateValue itd.
ColumnType	Enum wszystkich typów kolumn (text, status, date, people itd.).
Group	Grupa elementów na tablicy.
User	Użytkownik monday.com.
Workspace	Obszar roboczy.
Account	Informacje na poziomie konta.
Asset	Przesłany plik.
Update	Aktualizacja (komentarz) dotycząca elementu.
Tag	Etykieta.
Team	Zespół.
Folder	Folder w obszarze roboczym.
Doc	Dokument monday.
AppSubscription	Szczegóły subskrypcji aplikacji związane z monetyzacją.

Typy Enum

SDK eksportuje także przydatne typy enum:

Enum	Przykładowe wartości
BoardKind	public, private, share
ColumnType	text, status, date, numbers, people, timeline itd.
BoardObjectType	board, sub_items_board, document
BoardSubscriberKind	owner, subscriber
WorkspaceKind	open, closed
State	active, archived, deleted, all
FirstDayOfTheWeek	sunday, monday

Przykład użycia

import { Board, Item, ColumnType, BoardKind } from '@mondaydotcomorg/api';

const processItem = (item: Item) => {
  for (const col of item.column_values) {
    if (col.type === ColumnType.Status) {
      console.log(`Status column ${col.id}:`, col.value);
    }
  }
};

---

Konfiguracja GraphQL codegen (@mondaydotcomorg/setup-api)

Jeśli projekt wymaga własnych zapytań z pełnym bezpieczeństwem typów, użyj powiązanego pakietu konfiguracyjnego, aby przygotować szkielet procesu GraphQL codegen.

Uruchamianie konfiguracji

Uruchom to polecenie w katalogu głównym projektu:

npx @mondaydotcomorg/setup-api

⚠️ Tylko Bash

To CLI wymaga środowiska podobnego do Bash (Terminal w macOS, powłoka Linux lub Git Bash w Windows). Nie działa w wierszu poleceń systemu Windows (cmd).

Pliki tworzone przez konfigurację

Plik/folder	Zastosowanie
codegen.yml	Konfiguracja GraphQL Code Generator.
graphql.config.yml	Konfiguracja rozszerzenia GraphQL IDE. Zapewnia automatyczne uzupełnianie i weryfikację w edytorze.
src/queries.graphql.ts	Plik początkowy, w którym zapisujesz zapytania i mutacje GraphQL. Zawiera przykładowe zapytanie i mutację.
fetch-schema.sh	Skrypt pobierający najnowszy schemat API monday.com.
Skrypty npm w package.json	fetch:schema, codegen i fetch:generate.

Instalowane zależności deweloperskie

Konfiguracja instaluje te pakiety: - @graphql-codegen/cli - @graphql-codegen/typescript - @graphql-codegen/typescript-operations

Przebieg pracy

Po uruchomieniu konfiguracji:

1. Zapisz zapytania

Edytuj src/queries.graphql.ts, aby zdefiniować operacje GraphQL:

import gql from 'graphql-tag';

export const getBoards = gql`
  query GetBoards($ids: [ID!]) {
    boards(ids: $ids) {
      id
      name
      columns { id title type }
      groups { id title }
    }
  }
`;

export const createItem = gql`
  mutation CreateItem($boardId: ID!, $groupId: String!, $itemName: String!) {
    create_item(board_id: $boardId, group_id: $groupId, item_name: $itemName) {
      id
      name
    }
  }
`;

2. Pobierz schemat i wygeneruj typy

npm run fetch:generate

To polecenie pobiera najnowszy schemat API monday.com i generuje typy TypeScript w pliku src/generated/graphql.ts.

3. Użyj wygenerowanych typów

import { ApiClient } from '@mondaydotcomorg/api';
import { GetBoardsQuery, GetBoardsQueryVariables } from './generated/graphql';
import { getBoards } from './queries.graphql';

const client = new ApiClient({ token: '<YOUR_API_TOKEN>' });

const variables: GetBoardsQueryVariables = { ids: ["12345"] };
const data = await client.request<GetBoardsQuery>(getBoards, variables);

// data.boards is fully typed based on your query's selected fields

Ponowne generowanie typów po zmianie zapytań

Za każdym razem, gdy zmienisz zapytania:

npm run codegen

Aby ponownie pobrać również schemat (np. po wydaniu nowej wersji API):

npm run fetch:generate

Obsługa w IDE

Aby uzyskać najlepsze rezultaty, zainstaluj rozszerzenie GraphQL do edytora. Plik graphql.config.yml utworzony przez konfigurację włącza automatyczne uzupełnianie, weryfikację i podgląd dokumentacji zapytań.

VS Code: Zainstaluj rozszerzenia GraphQL: Language Feature Support i GraphQL: Syntax Highlighting.

IDE JetBrains: Zainstaluj wtyczkę GraphQL z menu Preferences > Plugins > Marketplace.

---

Pełne przykłady

Pobieranie tablic i elementów

import { ApiClient, Board, ColumnType } from '@mondaydotcomorg/api';

const client = new ApiClient({ token: '<YOUR_API_TOKEN>' });

// Get board structure
const { boards } = await client.request<{ boards: Board[] }>(`
  query {
    boards(ids: [12345]) {
      id
      name
      columns { id title type }
      groups { id title }
    }
  }
`);

// Get items with column values
const { boards: boardsWithItems } = await client.operations.getBoardItemsOp({
  ids: ["12345"],
});

for (const item of boardsWithItems[0].items_page.items) {
  console.log(`Item: ${item.name}`);
  for (const col of item.column_values) {
    console.log(`  ${col.id}: ${col.value}`);
  }
}

Tworzenie elementów i aktualizowanie kolumn

import { ApiClient } from '@mondaydotcomorg/api';

const client = new ApiClient({ token: '<YOUR_API_TOKEN>' });

// Create an item
const { create_item } = await client.operations.createItemOp({
  boardId: "12345",
  groupId: "topics",
  itemName: "New feature request",
});

// Update multiple columns on the new item
await client.operations.changeMultipleColumnValuesOp({
  boardId: "12345",
  itemId: create_item.id,
  columnValues: JSON.stringify({
    status: { label: "Working on it" },
    text: "Description of the feature",
    date: { date: "2026-04-15" },
    person: { personsAndTeams: [{ id: 12345678, kind: "person" }] },
  }),
});

Korzystanie z codegen w SDK

import { ApiClient, ClientError } from '@mondaydotcomorg/api';
import { GetBoardsQuery, GetBoardsQueryVariables, CreateItemMutation, CreateItemMutationVariables } from './generated/graphql';
import { getBoards, createItem } from './queries.graphql';

const client = new ApiClient({ token: '<YOUR_API_TOKEN>' });

// Typed query
const queryVars: GetBoardsQueryVariables = { ids: ["12345"] };
const boardData = await client.request<GetBoardsQuery>(getBoards, queryVars);

// Typed mutation
const mutationVars: CreateItemMutationVariables = {
  boardId: "12345",
  groupId: "topics",
  itemName: "Created with typed SDK!",
};
const itemData = await client.request<CreateItemMutation>(createItem, mutationVars);

Wzorzec obsługi błędów

import { ApiClient, ClientError } from '@mondaydotcomorg/api';

const client = new ApiClient({ token: '<YOUR_API_TOKEN>' });

async function safeRequest<T>(query: string, variables?: Record<string, any>): Promise<T | null> {
  try {
    return await client.request<T>(query, variables);
  } catch (error) {
    if (error instanceof ClientError) {
      const gqlErrors = error.response.errors;
      for (const err of gqlErrors) {
        if (err.message.includes('complexity')) {
          console.error('Complexity budget exceeded. Simplify your query.');
        } else if (err.message.includes('Rate limit')) {
          console.error('Rate limited. Implement backoff.');
        } else {
          console.error('GraphQL error:', err.message);
        }
      }
    } else {
      console.error('Unexpected error:', error);
    }
    return null;
  }
}

Przesyłanie pliku

import { ApiClient } from '@mondaydotcomorg/api';
import { readFileSync } from 'fs';

const client = new ApiClient({ token: '<YOUR_API_TOKEN>' });

const fileBuffer = readFileSync('./document.pdf');
const file = new File([fileBuffer], 'document.pdf', { type: 'application/pdf' });

const result = await client.request(
  `mutation ($file: File!, $itemId: ID!, $columnId: String!) {
    add_file_to_column(file: $file, item_id: $itemId, column_id: $columnId) {
      id
      name
      url
    }
  }`,
  { file, itemId: "67890", columnId: "files" }
);

---

Skrócona ściągawka

Podsumowanie eksportów

// Classes
import { ApiClient, SeamlessApiClient } from '@mondaydotcomorg/api';

// Error types
import { ClientError, SeamlessApiClientError } from '@mondaydotcomorg/api';

// Constants
import { DEFAULT_VERSION, MONDAY_API_ENDPOINT, AvailableVersions } from '@mondaydotcomorg/api';

// Types (examples - hundreds are available)
import { Board, Item, Column, ColumnValue, User, Group, Workspace, Asset, Update, Tag } from '@mondaydotcomorg/api';

// Enums (examples)
import { ColumnType, BoardKind, State, WorkspaceKind, BoardObjectType } from '@mondaydotcomorg/api';

Metody ApiClient

Metoda	Sygnatura	Opis
request<T>()	(query: string, variables?: Record<string, any>, options?: RequestOptions) => Promise<T>	Wykonuje zapytanie lub mutację GraphQL. Zwraca typowane dane odpowiedzi.
rawRequest<T>()	(query: string, variables?: Record<string, any>, options?: RequestOptions) => Promise<GraphQLClientResponse<T>>	Wykonuje zapytanie i zwraca pełną odpowiedź zawierającą data, errors i extensions.
operations.getMeOp()	() => Promise<GetMeOpQuery>	Pobiera uwierzytelnionego użytkownika.
operations.getBoardItemsOp()	({ ids: string[] }) => Promise<GetBoardItemsOpQuery>	Pobiera elementy z tablic.
operations.getBoardGroupsOp()	({ ids: string[] }) => Promise<GetBoardGroupsOpQuery>	Pobiera grupy z tablic.
operations.createItemOp()	({ boardId, groupId, itemName }) => Promise<CreateItemOpMutation>	Tworzy element.
operations.changeSimpleColumnValueOp()	({ boardId, itemId, columnId, value: string }) => Promise	Ustawia zwykłą wartość tekstową kolumny.
operations.changeColumnValueOp()	({ boardId, itemId, columnId, value: JSON }) => Promise	Ustawia wartość JSON kolumny.
operations.changeMultipleColumnValuesOp()	({ boardId, itemId, columnValues: JSON }) => Promise	Ustawia wartości kilku kolumn.