---
title: "@vonvon-kit/core"
description: "セッション状態、短期 JWT アクセス、Management API ヘルパー向けのブラウザークライアント。"
locale: "ja"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/ja/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# @vonvon-kit/core

## インストールと設定

Registry 状態: UNPUBLISHED。この SDK はリポジトリのソース checkout からのみインストールし、外部 package registry は使用しないでください。

別の origin にある開発者アプリでは、issuer、clientId、完全一致する redirectUri を指定して `mode: 'oidc'` を設定してください。same-origin mode は、アプリケーションが自身と完全に同じ origin で Core auth endpoints をルーティングする場合にのみ使用してください。Vonvon に publishable-key credential はありません。

```ts
import { VonvonClient } from '@vonvon-kit/core'

const vonvon = new VonvonClient({
  mode: 'oidc',
  issuer: 'https://vonvon.id',
  clientId: 'client_abc123',
  redirectUri: 'https://app.example.com/auth/callback',
})

const authorization = await vonvon.createAuthorizationUrl({ returnUrl: '/dashboard' })
if (!authorization.ok) throw new Error(authorization.error.message)
window.location.assign(authorization.value)
```

## セッションのライフサイクル

- `load()` は `/v1/me` を読み取り、ユーザー、セッション、アクティブな組織を初期化します。
- `signInPassword()` は Hosted Auth のパスワードフローを通じて cookie セッションを確立します。
- `getToken()` は API 呼び出し用の短期 JWT を返します。バックエンドで JWKS を使ってネットワーク不要で検証してください。
- `setActiveOrganization()` は組織コンテキストを切り替え、状態を再読み込みする前にトークンキャッシュをクリアします。
- `signOut()` はブラウザーのセッション cookie を取り消します。

## Management API ヘルパー

Management API helpers は `server-side または完全一致する same-origin でのみ`使用できます。サーバー上で `sk_live_*` または sk\_test\_\* を指定した別の client を構築してください。OIDC browser mode ではこれらの操作が拒否されます。

```ts
const management = new VonvonClient({
  apiUrl: 'https://vonvon.id',
  secretKey: process.env.VONVON_SECRET_KEY,
})

const keys = await management.listApiKeys()
if (!keys.ok) throw new Error(keys.error.message)

const created = await management.createApiKey({ name: 'CI deploy', scopes: ['read'] })
if (!created.ok) throw new Error(created.error.message)

const revoked = await management.revokeApiKey({ id: created.value.id })
if (!revoked.ok) throw new Error(revoked.error.message)
```

## エクスポートされた API

| エクスポート | 種別 | 目的 |
| --- | --- | --- |
| `VonvonClient` | class | トップレベルブラウザークライアント：load、signIn、getToken、setActiveOrganization、signOut、Management API ヘルパー |
| `VonvonStore` | class | フレームワーク非依存のリアクティブストア。フレームワークバインディングでは useSyncExternalStore でサブスクライブします |
| `TokenManager` | class | 短期 JWT キャッシュとスケジュール更新（高度な使用およびテスト向け） |
| `VonvonApiClient` | class | /v1/me およびトークンエンドポイント向けの HTTP クライアント |
| `VonvonNetworkError` | class | トランスポート失敗（ネットワークエラー、非 JSON レスポンス、構造化ボディなしの 5xx）でスローされます |
| `makeVonvonError` | function | ネットワーク往復なしにローカル検証失敗用の構造化 VonvonError を構築します |
| `isVonvonErrorShape` | function | 型ガード：不明な値がワイヤーからの VonvonError 形状に準拠しているか確認します |
| `decodeTokenClaims` | function | 有効期限スケジューリング専用に JWT ペイロードクレームをデコードします。署名は検証しません |
| `isTokenExpiring` | function | トークンが許容ウィンドウ内（デフォルト 10 秒）で期限切れになる場合に true を返します |
| `SESSION_STATUS` | as const タプル | 有効なセッション状態値：active、pending、expired、removed、ended、revoked |
| `CLIENT_STATUS` | as const タプル | 有効なクライアント状態値：loading、ready、degraded、error |
| `PACKAGE` | 文字列定数 | パッケージ名識別子 '@vonvon-kit/core' |

## 型

| 種別 | 説明 |
| --- | --- |
| `VonvonUser` | 認証済みユーザーの読み取り専用ビュー（シークレットやハッシュなし） |
| `VonvonOrganization` | 組織の公開ビュー |
| `VonvonOrganizationMembership` | ロールと権限を持つ組織内のユーザーメンバーシップ |
| `VonvonSession` | 状態、有効期限、アクティブな組織を含むセッションビュー |
| `VonvonApiKey` | シークレットなしの API キー（一覧表示） |
| `VonvonApiKeyWithSecret` | 作成時に一度だけ返される API キー。key フィールドを含みます |
| `VonvonPage<T>` | カーソルページネーション対応のレスポンスエンベロープ |
| `CreateApiKeyInput` | createApiKey の入力型 |
| `SignInPasswordInput` | signInPassword の入力型 |
| `SignInResult` | signInPassword の結果：次のステップまたはリダイレクト URL |
| `SessionStatus` | SESSION\_STATUS 値のユニオン |
| `ClientStatus` | CLIENT\_STATUS 値のユニオン |
| `VonvonState` | VonvonStore からサブスクライブされた完全な SDK 状態スナップショット |
| `VonvonStateListener` | 状態変化リスナーコールバック型 |
| `Unsubscribe` | VonvonStore.subscribe の戻り値の型 |
| `GetTokenOptions` | getToken のオプション：skipCache、leewaySeconds、signal |
| `VonvonClientOptions` | 判別可能な VonvonClient constructor options です。same-origin は apiUrl、secretKey、fetcher、now を受け取り、oidc には issuer、clientId、redirectUri が必要です。 |
| `TokenResponse` | トークンエンドポイントレスポンスの生の形状 |
| `ClientStateResponse` | /v1/me レスポンスの生の形状 |
| `DecodedTokenClaims` | decodeTokenClaims が返す JWT ペイロードクレーム |

## 関連ドキュメント

フレームワークバインディング：[@vonvon-kit/react](/ja/sdks/react)。サーバー検証：[@vonvon-kit/backend](/ja/sdks/backend)。

Source: https://vonvon.id/ja/sdks/core/index.mdx