{"_id":"@authoriza/sdk","name":"@authoriza/sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@authoriza/sdk","version":"0.1.0","description":"SDK for integrating Authoriza authentication","license":"MIT","repository":{"type":"git","url":"git+https://github.com/authoriza-core/sdk.git"},"publishConfig":{"access":"public"},"type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"sideEffects":false,"engines":{"node":">=18"},"pnpm":{"onlyBuiltDependencies":["@biomejs/biome","esbuild"]},"packageManager":"pnpm@10.33.0","scripts":{"build":"tsup","typecheck":"tsc --noEmit","lint":"eslint src test","format":"biome format --write .","format:check":"biome format .","test":"vitest run","test:watch":"vitest"},"devDependencies":{"@biomejs/biome":"^1.9.4","@eslint/js":"^10.0.1","@types/node":"^22.5.0","eslint":"^9.11.0","jsdom":"^25.0.0","tsup":"^8.3.0","typescript":"^5.6.2","typescript-eslint":"^8.8.0","vitest":"^2.1.1"},"_id":"@authoriza/sdk@0.1.0","gitHead":"5d7e250644be0638329f6b4248940b08c5a142a8","bugs":{"url":"https://github.com/authoriza-core/sdk/issues"},"homepage":"https://github.com/authoriza-core/sdk#readme","_nodeVersion":"22.17.1","_npmVersion":"11.5.2","dist":{"integrity":"sha512-CRKzHBPId3gpMX0SV+03g6Iu1Ptvxuoq//nD3WF/1ARD71nmkwkHLFvvVZt/wI+aMdhEPYetyxR1RUPu5OsB8w==","shasum":"e86c5bb98ca38462fd768cfd535d875bd6d420d6","tarball":"https://registry.npmjs.org/@authoriza/sdk/-/sdk-0.1.0.tgz","fileCount":6,"unpackedSize":154979,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD/JjahRLZjF4vXb8oQ8IIRMJ3YUKRbPBEZS5Z3IKLAEAIgWu0VEC+TM3kJRvKWrCm+30tOXyLJYNCodY05gAJZlqc="}]},"_npmUser":{"name":"akalinin","email":"alexkalinin.ru@gmail.com"},"directories":{},"maintainers":[{"name":"akalinin","email":"alexkalinin.ru@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.0_1786967190665_0.47908176341004527"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-17T11:46:30.503Z","0.1.0":"2026-08-17T11:46:30.815Z","modified":"2026-08-17T11:46:31.782Z"},"maintainers":[{"name":"akalinin","email":"alexkalinin.ru@gmail.com"}],"description":"SDK for integrating Authoriza authentication","homepage":"https://github.com/authoriza-core/sdk#readme","repository":{"type":"git","url":"git+https://github.com/authoriza-core/sdk.git"},"bugs":{"url":"https://github.com/authoriza-core/sdk/issues"},"license":"MIT","readme":"# @authoriza/sdk\n\n[README in English](./README.en.md)\n\nFramework-agnostic OIDC SDK для [Авторизы](https://authoriza.ru). Реализует Authorization\nCode Flow с PKCE для браузерных приложений.\n\n## Возможности\n\n- Вход, выход, восстановление сессии после перезагрузки страницы\n- Автоматическое обновление access token с защитой от параллельных запросов\n- Автоматическая обработка OIDC callback\n- Межвкладочная синхронизация состояния\n- Полные TypeScript-типы\n- Нулевые runtime-зависимости\n- SSR-safe импорт и создание экземпляра\n\n## Установка\n\n```bash\nnpm install @authoriza/sdk\n```\n\n## Быстрый старт\n\n```ts\nimport { createAuthoriza } from '@authoriza/sdk';\n\nconst auth = createAuthoriza({\n  clientId: 'YOUR_CLIENT_ID',\n  redirectUri: 'https://example.com/auth/callback',\n});\n\n// Проверка состояния\nauth.isAuthenticated; // boolean\nauth.user;            // User | null\nauth.isLoading;       // boolean\n\n// Вход\nawait auth.login({ redirectAfterLoginTo: '/dashboard' });\n\n// Получение access token для API-запросов\nconst token = await auth.getAccessToken();\n\n// Выход (локальный)\nawait auth.logout();\n```\n\n## Конфигурация\n\n```ts\ninterface AuthorizaConfig {\n  /** Обязательный идентификатор frontend-приложения,\n   *  зарегистрированного в Авторизе */\n  clientId: string;\n  /** Обязательный технический OIDC callback URL. Не является адресом,\n   *  куда пользователь попадает после входа */\n  redirectUri: string;\n  /** URL OIDC-сервера.\n   *  По умолчанию — production Авторизы: https://oidc.authoriza.ru/oidc */\n  issuer?: string;\n  /** Массив scopes. `openid` добавляется автоматически.\n   *  По умолчанию — ['openid', 'profile', 'email', 'offline_access'] */\n  scope?: string[];\n  /** Пользовательская реализация хранилища сессии.\n   *  По умолчанию — `localStorage` */\n  sessionStorage?: SessionStorage;\n  /** Обработчик ошибок, возникающих при асинхронной обработке\n   *  authentication flow (callback, refresh и т. д.) */\n  onError?: (error: AuthorizaError) => void;\n}\n```\n\n## API\n\n### `createAuthoriza(config): Authoriza`\n\nСоздаёт экземпляр клиента. Создание синхронное, без сетевых запросов.\n\n### `auth.login(options?)`\n\nЗапускает authentication flow. Перенаправляет браузер на Авторизу.\n\n```ts\nawait auth.login();\nawait auth.login({ redirectAfterLoginTo: '/dashboard' });\n```\n\n`redirectAfterLoginTo` — относительный путь приложения, на который будет перенаправлен\nпользователь после успешного входа.\n\n### `auth.logout()`\n\nУдаляет локальную сессию. Не выполняет redirect на Авторизу.\n\n```ts\nawait auth.logout();\n```\n\n### `auth.getUser()`\n\nВозвращает текущего пользователя или `null`.\n\n```ts\nconst user = await auth.getUser();\n// { id: string; email?: string; name?: string } | null\n```\n\n### `auth.getAccessToken()`\n\nВозвращает действующий access token. Если токен истёк — автоматически выполняет refresh.\n\n```ts\nconst token = await auth.getAccessToken();\n```\n\nЕсли пользователь не авторизован, выбрасывает `AuthorizaError` с кодом `USER_NOT_AUTHENTICATED`.\n\n### `auth.getAuthState()`\n\nВозвращает текущее состояние авторизации.\n\n```ts\nconst state = auth.getAuthState();\n// { isAuthenticated: boolean; isLoading: boolean; user: User | null }\n```\n\n### `auth.isAuthenticated`\n\n`true`, если есть действующая сессия.\n\n### `auth.isLoading`\n\n`true`, пока SDK восстанавливает сессию после создания экземпляра.\n\n### `auth.user`\n\nТекущий пользователь или `null`.\n\n### `auth.onAuthStateChanged(handler)` / `auth.on('authStateChanged', handler)`\n\nПодписка на изменение состояния авторизации. Возвращает функцию отписки.\n\n```ts\nconst unsubscribe = auth.onAuthStateChanged((state) => {\n  console.log(state.isAuthenticated, state.user);\n});\n\n// отписка\nunsubscribe();\n```\n\n## Обработка ошибок\n\nВсе ошибки SDK представлены классом `AuthorizaError` со стабильным полем `code`:\n\n```ts\nimport { createAuthoriza, isAuthorizaError } from '@authoriza/sdk';\n\nconst auth = createAuthoriza({\n  clientId: 'YOUR_CLIENT_ID',\n  redirectUri: 'https://example.com/auth/callback',\n  onError(error) {\n    switch (error.code) {\n      case 'INVALID_STATE':\n        // подмена callback\n        break;\n      case 'TOKEN_EXCHANGE_FAILED':\n        // ошибка обмена кода на токены\n        break;\n      case 'TOKEN_REFRESH_FAILED':\n        // не удалось обновить access token\n        break;\n      default:\n        // другая ошибка\n        break;\n    }\n  },\n});\n\n// Ошибки синхронных/проmise-методов:\ntry {\n  await auth.getAccessToken();\n} catch (error) {\n  if (isAuthorizaError(error)) {\n    console.error(error.code, error.message);\n  }\n}\n```\n\n### Коды ошибок\n\n| Код                            | Описание                                     |\n|--------------------------------|----------------------------------------------|\n| `INVALID_CONFIG`               | Некорректная конфигурация SDK                |\n| `DISCOVERY_FAILED`             | OIDC Discovery завершился ошибкой            |\n| `NETWORK_ERROR`                | Ошибка сетевого запроса                      |\n| `AUTH_FLOW_IN_PROGRESS`        | Authentication flow уже выполняется          |\n| `INVALID_STATE`                | Несоответствие OAuth state                   |\n| `AUTHORIZATION_ERROR`          | Сервер авторизации вернул ошибку             |\n| `TOKEN_EXCHANGE_FAILED`        | Обмен authorization code на токены не удался |\n| `TOKEN_REFRESH_FAILED`         | Обновление access token не удалось           |\n| `USER_NOT_AUTHENTICATED`       | Пользователь не авторизован                  |\n| `INVALID_SESSION`              | Сессия недействительна                       |\n| `STORAGE_ERROR`                | Ошибка операции хранилища сессии             |\n| `USER_CANCELLED`               | Пользователь отменил авторизацию             |\n| `INVALID_REDIRECT_AFTER_LOGIN` | Некорректное значение `redirectAfterLoginTo` |\n| `INVALID_NONCE`                | Несоответствие nonce ID Token                |\n| `UNSUPPORTED_TOKEN_TYPE`       | Неподдерживаемый тип токена                  |\n\n## Пользовательское хранилище сессии\n\n```ts\nimport { createAuthoriza, type SessionStorage } from '@authoriza/sdk';\n\nconst storage: SessionStorage = {\n  async get() { /* вернуть Session | null */ },\n  async set(session) { /* сохранить сессию */ },\n  async clear() { /* удалить сессию */ },\n};\n\nconst auth = createAuthoriza({\n  clientId: 'YOUR_CLIENT_ID',\n  redirectUri: 'https://example.com/auth/callback',\n  sessionStorage: storage,\n});\n```\n\n## Обработка callback\n\nСоздайте экземпляр SDK на странице, указанной в `redirectUri`, — SDK определит, что текущий\nURL является callback URL, и автоматически обработает ответ. Экземпляр при этом можно\nсоздавать на любой странице приложения.\n\n```ts\n// На странице https://example.com/auth/callback\nconst auth = createAuthoriza({\n  clientId: 'YOUR_CLIENT_ID',\n  redirectUri: 'https://example.com/auth/callback',\n});\n// SDK автоматически определит callback URL и обработает authorization code\n```\n\nОтдельный метод `handleCallback()` не требуется.\n\n## Типы\n\n```ts\nimport type {\n  Authoriza,\n  AuthorizaConfig,\n  AuthState,\n  LoginOptions,\n  Session,\n  SessionStorage,\n  User,\n  AuthorizaError,\n  AuthorizaErrorCode,\n} from '@authoriza/sdk';\n```\n\n## Совместимость\n\n- Современные браузеры: Chrome, Edge, Firefox, Safari\n- ESM-only\n- TypeScript types включены\n- SSR-safe (импорт и создание экземпляра не требуют browser globals)\n\n## Лицензия\n\nMIT\n","readmeFilename":"README.md","_rev":"1-7f00bafb07bbbfe03dd817f29db89244"}