Перейти к основному содержимому

JavaScript SDK

JavaScript SDK (@emd-cloud/sdk) — это основная библиотека для работы с EMD Cloud API в ваших JavaScript и TypeScript приложениях.

Требования​

  • Node.js v22.0.0 или выше (для нативной поддержки WebSocket)
  • Современный браузер (для client-side использования)

Установка​

Установите SDK и необходимые peer dependencies:

# NPM
npm install @emd-cloud/sdk tus-js-client uuid

# Yarn
yarn add @emd-cloud/sdk tus-js-client uuid

# PNPM
pnpm add @emd-cloud/sdk tus-js-client uuid
Peer Dependencies

Пакеты tus-js-client и uuid необходимы для функциональности загрузки файлов.

Быстрый старт​

1. Получите API токен​

  1. Зарегистрируйтесь на EMD Cloud
  2. Создайте новое приложение
  3. Скопируйте API токен из настроек приложения

2. Импортируйте SDK​

import { EmdCloud, AuthType, AppEnvironment } from '@emd-cloud/sdk';

3. Создайте экземпляр SDK​

Server-side (Node.js)​

const emdCloud = new EmdCloud({
  environment: AppEnvironment.Server,
  appId: 'your-app-id',
  apiToken: 'your-api-token',
  defaultAuthType: AuthType.ApiToken // Опционально
});

Client-side (Browser)​

const emdCloud = new EmdCloud({
  environment: AppEnvironment.Client,
  appId: 'your-app-id'
  // defaultAuthType автоматически устанавливается в AuthType.AuthToken
});

// Установите токен пользователя после авторизации
emdCloud.setAuthToken('user-auth-token');

Параметры конфигурации​

При создании экземпляра EmdCloud вы можете передать следующие параметры:

ПараметрТипОбязательныйОписание
environmentAppEnvironment✅Окружение: AppEnvironment.Client или AppEnvironment.Server
appIdstring✅Уникальный идентификатор вашего приложения
apiTokenstring⚠️API токен (обязателен для Server окружения)
apiUrlstring❌URL API endpoint (по умолчанию: https://api.emd.one)
authSchemastring❌Схема авторизации (по умолчанию: token)
defaultAuthTypeAuthType❌Тип авторизации по умолчанию

Типы окружений​

AppEnvironment.Server​

Используется для серверных приложений (Node.js, backend):

  • Требует API токен приложения
  • Полный доступ ко всем данным
  • Используется для административных операций

AppEnvironment.Client​

Используется для клиентских приложений (браузер, frontend):

  • Использует токен авторизованного пользователя
  • Доступ ограничен правами пользователя
  • Безопасно для публичного кода

Типы авторизации​

import { AuthType } from '@emd-cloud/sdk';

// AuthType.ApiToken - для серверных запросов с API токеном
// AuthType.AuthToken - для клиентских запросов с токеном пользователя

Базовые методы​

setAuthToken()​

Устанавливает токен авторизации для текущего экземпляра SDK.

emdCloud.setAuthToken('new-auth-token');

Параметры:

  • token (string) — токен авторизации пользователя

Использование: Обычно вызывается после успешной авторизации пользователя для сохранения токена в SDK.

Модули SDK​

SDK организован в несколько модулей для работы с различными сервисами EMD Cloud:

🔐 Авторизация​

emdCloud.auth.login({ login, password })
emdCloud.auth.register({ email, password })
emdCloud.auth.authorization()

💾 База данных​

const db = emdCloud.database('collection-id');
await db.getRows({ query, sort, limit });
await db.createRow({ data });

💬 Чаты​

emdCloud.chat.listChannels({ type, limit });
emdCloud.chat.sendMessage({ channelId, text });

📁 Хранилище​

emdCloud.uploader.upload(file, options);

🔗 Вебхуки​

emdCloud.webhook.trigger(webhookId, data);

Примеры использования​

Полный пример авторизации​

import { EmdCloud, AppEnvironment } from '@emd-cloud/sdk';

// Создаем экземпляр для клиента
const emdCloud = new EmdCloud({
  environment: AppEnvironment.Client,
  appId: 'your-app-id'
});

// Авторизуем пользователя
try {
  const user = await emdCloud.auth.login({
    login: 'user@example.com',
    password: 'password123'
  });
  
  console.log('Авторизован:', user.email);
  console.log('Токен:', user.token);
  
  // Токен автоматически сохраняется в SDK
  // Теперь можно делать запросы от имени пользователя
  
} catch (error) {
  console.error('Ошибка авторизации:', error);
}

Работа с базой данных​

// Создаем экземпляр для работы с коллекцией
const usersDb = emdCloud.database('users-collection-id');

// Получаем записи с фильтрацией
const result = await usersDb.getRows({
  query: {
    "$and": [
      { "data.status": { "$eq": "active" } }
    ]
  },
  sort: [{ column: "createdAt", sort: "desc" }],
  limit: 20
});

console.log('Найдено пользователей:', result.count);
console.log('Данные:', result.data);

TypeScript поддержка​

SDK полностью поддерживает TypeScript с типизацией всех методов и параметров:

import { EmdCloud, AppEnvironment, AuthType, User } from '@emd-cloud/sdk';

const emdCloud = new EmdCloud({
  environment: AppEnvironment.Client,
  appId: 'your-app-id'
});

// Типизированный ответ
const user: User = await emdCloud.auth.login({
  login: 'user@example.com',
  password: 'password123'
});

Обработка ошибок​

SDK использует Promise-based API, поэтому все ошибки можно обрабатывать через try/catch:

try {
  const user = await emdCloud.auth.login({ login, password });
} catch (error) {
  if (error.status === 401) {
    console.error('Неверный логин или пароль');
  } else if (error.status === 500) {
    console.error('Ошибка сервера');
  } else {
    console.error('Произошла ошибка:', error.message);
  }
}

Следующие шаги​

Полезные ссылки​