@synapsea/auth-js

Proprietary software — use only with the Synapsea Auth platform. See LICENSE.
Проприетарное ПО — только для использования с платформой Synapsea Auth, условия в LICENSE.

Официальный vanilla JavaScript/TypeScript SDK для Synapsea Auth: OAuth, Telegram (виджет и Mini App), email/SMS OTP, сессия и профиль. Работает в браузере (fetch + localStorage); отдельные методы можно вызывать в Node при наличии глобального fetch.

Для React используйте @synapsea/auth-react — он построен на тех же эндпоинтах.

Установка

npm install @synapsea/auth-js

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

import { SynapseaAuth } from '@synapsea/auth-js';

const auth = new SynapseaAuth({
  apiKey: 'sa_live_xxxxxxx',
  // baseURL: 'https://auth.synapsea.agency', // по умолчанию
});

// OAuth: редирект на провайдера
await auth.signIn.social({ provider: 'vk', callbackURL: 'https://yoursite.com/auth/callback' });

// На странице callback — обмен sa_code на токен (токен не должен быть в query)
const exchanged = await auth.handleCallback();
if (exchanged) {
  const session = await auth.getSession();
  console.log(session?.user);
}

OAuth callback

После успешного входа провайдер возвращает пользователя на ваш callbackURL. В URL приходит одноразовый sa_code (не передавайте долгоживущий токен в query).

На странице callback вызовите handleCallback(): SDK обменяет код на сессию, сохранит токен в localStorage (sa_session_token) и очистит чувствительные параметры из адреса через history.replaceState.

Сессия и хранилище

• Токен хранится в localStorage под ключом sa_session_token.
• onAuthStateChange при старте запрашивает сессию и подписывается на storage (синхронизация между вкладками).

API

new SynapseaAuth(config)

| Поле | Тип | Описание | |------|-----|----------| | apiKey | string | API-ключ проекта (sa_live_… / sa_test_…) | | baseURL | string? | Базовый URL API (по умолчанию https://auth.synapsea.agency) |

Свойства экземпляра:

| Свойство | Тип | Описание | |----------|-----|----------| | token | string \| null | Текущий Bearer-токен сессии | | isAuthenticated | boolean | Есть ли токен в памяти |

signIn.social({ provider, callbackURL? })

Редирект на страницу провайдера. callbackURL по умолчанию — текущий window.location.href.

Тип провайдера — Provider: vk, yandex, google, telegram, twitter, facebook, instagram, apple, discord, github, steam, reddit, twitch, esia, ok, mailru (фактическая доступность зависит от настроек проекта в консоли Synapsea).

signIn.telegram(data)

Вход по данным Telegram Login Widget. Тело запроса — объект с полями id, first_name, auth_date, hash и опционально last_name, username, photo_url. Возвращает { token, user }, токен сохраняется.

signIn.telegramMiniApp(initData)

Telegram Mini App: передайте строку WebApp.initData.

signIn.verifyToken(params)

Токены провайдеров без полного редиректа (например Google One Tap, VK silent flow). Формат: { provider, method, ... } — дополнительные поля зависят от провайдера (credential, idToken, silent_token, uuid и т.д.).

signIn.emailOtp / signIn.smsOtp

| Метод | Описание | |-------|----------| | send({ email }) / send({ phone }) | Отправить код | | verify({ email, code }) / verify({ phone, code }) | Проверить код и создать сессию |

getSession() → Promise<SessionData | null>

Загружает пользователя, сессию и привязанные аккаунты. При 401 токен сбрасывается.

signOut() → Promise<void>

Инвалидирует сессию на сервере (если был токен) и очищает локальное хранилище.

user

| Метод | Описание | |-------|----------| | get() | Профиль текущего пользователя | | update({ name?, metadata? }) | Обновить профиль | | accounts() | Список связанных провайдеров | | linkAccount({ provider, callbackURL? }) | Редирект для привязки ещё одного OAuth |

consent (ФЗ-152)

| Метод | Описание | |-------|----------| | give({ version? }) | Зафиксировать согласие (версия по умолчанию 1.0) | | revoke() | Отозвать согласие |

handleCallback() → Promise<{ token, userId } | null>

Только в браузере. Обрабатывает sa_code (и опционально sa_user_id) в query, обменивает код, чистит URL от sa_code, устаревших sa_token / session_token.

onAuthStateChange(callback) → () => void

callback получает SessionData | null. Возвращаемая функция — отписка.

SynapseaError

Наследник Error с полем status (HTTP-код ответа API).

Сборка из исходников

npm run build

Артефакты — каталог dist/ (index.js, типы .d.ts).

Документация

• Документация Synapsea Auth (в т.ч. SDK)

Лицензия

Проприетарное ПО. Использование только для интеграции с сервисом Synapsea Auth на условиях файла LICENSE. Это не MIT и не open-source лицензия.