pachca v1.0.0
pachca
pachca это полностью типизированный, лёгкий и современный JS клиент для мессенджера Пачка. Документация к API Пачки доступна здесь.
Использование
Установка
npm
npm i pachcapnpm
pnpm add pachcaYarn
yarn add pachcabun
bun add pachcaDeno
import { Pachca } from "https://esm.sh/pachca";Пример использования
import { CustomPropertyEntityType, Pachca } from "pachca";
const pachca = new Pachca({
accessToken: process.env.PACHCA_ACCESS_TOKEN!, // Токен доступа
});
const { data } = await pachca.customProperties.get({ entity_type: CustomPropertyEntityType.User }); // Получаем все дополнительные поля для пользователей
data.at(0).name; // Результат типизированДокументация
Библиотека использует Web APIs, т.е. fetch, FormData, Blob и т.п. Для использования библиотеки в средах, которые не поддерживают Web APIs, необходимо использовать полифиллы.
Экспорты библиотеки доступны только в формате ESM.
Инициализация
/**
* Опции создания API клиента
*/
export interface ApiClientOptions {
/**
* Базовый URL API
* @default https://api.pachca.com/api/shared/v1
*/
baseUrl?: string;
/**
* Токен доступа
* @see https://crm.pachca.com/dev/getting-started/requests-and-responses/
*/
accessToken: string;
/**
* Заголовок User-Agent в запросах
* @default pachca/${version} (+https://github.com/MonsterDeveloper/pachca)
*/
userAgent?: string;
/** ID пользователя/бота, которому принадлежит токен */
userId?: number;
}
const pachca = new Pachca({
// Опции
});Работа с API
В классе Pachca есть эндпоинты для запросов к API, которые названы в соответствии с URL, описанными в документации Пачки. Доступные эндпоинты описаны в разделе Функционал. Методы эндпоинты названы в соответствии с HTTP методами, которые они используют.
// Получить список сотрудников
const { data: users } = await pachca.users.get();
// Получить сотрудника по id
const { data: user } = await pachca.users.getById(1);
// Удалить сотрудника
await pachca.users.delete(1);
// Обновить беседу или канал
const { data: chat } = await pachca.chats.put(1, { chat: { name: "Новое название" } });Обработка ошибок
Для удобства библиотека экспортирует кастомные классы ошибок:
PachcaError— общая ошибка ПачкиPachcaClientError— клиентская ошибка, которая происходит при ответе с кодом 4xx. Пояснения доступны в документации Пачки
try {
await pachca.chats.post({ chat: { name: "Новая беседа" } });
} catch (error) {
if (error instanceof PachcaClientError) {
console.log(error.errors[0].message);
} else if (error instanceof PachcaError) {
console.log(error.response?.status);
}
}Также во избежание Callback Hell, можно использовать @open-draft/until:
import { until } from "@open-draft/until";
async function getChatById(id: number) {
const { error, data } = await until(() => pachca.chats.getById(id));
if (error) {
// обработать ошибку
return;
}
return data;
}Загрузка файлов
Пример для Bun:
const file = Bun.file("test-pachca.txt");
const uploadsData = await pachca.uploads.post();
await pachca.uploads.postFile(file, uploadsData);Contributing
Пожалуйста, прочитайте гайд перед тем как отправлять PR.
Лицензия
Библиотека лицензирован GPL-3.0.