pachca

pachca это полностью типизированный, лёгкий и современный JS клиент для мессенджера Пачка. Документация к API Пачки доступна здесь.

Использование

Установка

npm

npm i pachca

Другие менеджеры пакетов

pnpm

pnpm add pachca

Yarn

yarn add pachca

bun

bun add pachca

Deno

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.