@authon/vue 0.2.1 → 0.3.0

package/README.ko.md

@@ -0,0 +1,170 @@
+[English](./README.md) | **한국어**
+
+# @authon/vue
+
+[Authon](https://authon.dev)용 Vue 3 SDK — 플러그인, composable, 컴포넌트를 제공합니다.
+
+## 설치
+
+```bash
+npm install @authon/vue
+# 또는
+pnpm add @authon/vue
+```
+
+`vue >= 3.3.0`이 필요합니다.
+
+## 빠른 시작
+
+### 1. 플러그인 설치
+
+```ts
+// main.ts
+import { createApp } from 'vue';
+import { AuthonPlugin } from '@authon/vue';
+import App from './App.vue';
+
+const app = createApp(App);
+app.use(AuthonPlugin, {
+  publishableKey: 'pk_live_...',
+});
+app.mount('#app');
+```
+
+### 2. Composable 사용
+
+```vue
+<script setup lang="ts">
+import { useAuthon, useUser } from '@authon/vue';
+
+const { isSignedIn, openSignIn, signOut } = useAuthon();
+const { user, isLoading } = useUser();
+</script>
+
+<template>
+  <div v-if="isLoading">Loading...</div>
+  <div v-else-if="isSignedIn">
+    <p>Welcome, {{ user?.displayName }}</p>
+    <button @click="signOut()">Sign Out</button>
+  </div>
+  <div v-else>
+    <button @click="openSignIn()">Sign In</button>
+  </div>
+</template>
+```
+
+### 3. 컴포넌트 사용
+
+```vue
+<template>
+  <SignedIn>
+    <UserButton />
+  </SignedIn>
+  <SignedOut>
+    <button @click="openSignIn()">Sign In</button>
+  </SignedOut>
+</template>
+
+<script setup lang="ts">
+import { SignedIn, SignedOut, UserButton, useAuthon } from '@authon/vue';
+
+const { openSignIn } = useAuthon();
+</script>
+```
+
+## API 레퍼런스
+
+### 플러그인
+
+```ts
+app.use(AuthonPlugin, {
+  publishableKey: string;
+  apiUrl?: string;
+  theme?: 'light' | 'dark' | 'auto';
+  locale?: string;
+  appearance?: Partial<BrandingConfig>;
+});
+```
+
+### Composable
+
+#### `useAuthon()`
+
+```ts
+const {
+  isSignedIn,  // Ref<boolean>
+  isLoading,   // Ref<boolean>
+  user,        // Ref<AuthonUser | null>
+  signOut,     // () => Promise<void>
+  openSignIn,  // () => Promise<void>
+  openSignUp,  // () => Promise<void>
+  getToken,    // () => string | null
+  client,      // Authon 인스턴스
+} = useAuthon();
+```
+
+#### `useUser()`
+
+```ts
+const { user, isLoading } = useUser();
+```
+
+### 컴포넌트
+
+| 컴포넌트 | 설명 |
+|----------|------|
+| `<SignedIn>` | 로그인 상태일 때만 슬롯을 렌더링 |
+| `<SignedOut>` | 로그아웃 상태일 때만 슬롯을 렌더링 |
+| `<UserButton>` | 로그아웃 기능이 포함된 아바타 드롭다운 |
+| `<Protect>` | fallback 슬롯을 지원하는 조건부 렌더링 |
+
+## Multi-Factor Authentication (MFA)
+
+`useAuthon()`의 `client` 인스턴스를 통해 MFA 메서드에 접근합니다.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useAuthon } from '@authon/vue';
+import { AuthonMfaRequiredError } from '@authon/js';
+
+const { client } = useAuthon();
+const qrSvg = ref('');
+const mfaToken = ref('');
+
+// MFA 설정
+async function enableMfa() {
+  const setup = await client.value!.setupMfa();
+  qrSvg.value = setup.qrCodeSvg;  // 인증 앱에 표시할 QR 코드
+}
+
+async function verifySetup(code: string) {
+  await client.value!.verifyMfaSetup(code);
+}
+
+// MFA를 사용한 로그인
+async function signIn(email: string, password: string) {
+  try {
+    await client.value!.signInWithEmail(email, password);
+  } catch (err) {
+    if (err instanceof AuthonMfaRequiredError) {
+      mfaToken.value = err.mfaToken;  // TOTP 입력 화면 표시
+    }
+  }
+}
+
+async function verifyMfa(code: string) {
+  await client.value!.verifyMfa(mfaToken.value, code);
+}
+</script>
+```
+
+전체 API 레퍼런스는 [`@authon/js` MFA 문서](../js/README.md#multi-factor-authentication-mfa)를 참고하세요.
+
+## 문서
+
+[authon.dev/docs](https://authon.dev/docs)
+
+## 라이선스
+
+[MIT](../../LICENSE)

package/README.md

@@ -1,120 +1,465 @@
+**English** | [한국어](./README.ko.md)
+
 # @authon/vue
 
-Vue 3 SDK for [Authon](https://authon.dev) — plugin, composables, and components.
+Vue 3 Composition API integration for [Authon](https://authon.dev) — plugin setup, composables, and pre-built components.
 
 ## Install
 
 ```bash
-npm install @authon/vue
-# or
-pnpm add @authon/vue
+npm install @authon/vue @authon/js
 ```
 
 Requires `vue >= 3.3.0`.
 
-## Quick Start
+## Setup
 
-### 1. Install the Plugin
+Register the plugin in `main.ts`:
 
 ```ts
-// main.ts
-import { createApp } from 'vue';
-import { AuthonPlugin } from '@authon/vue';
-import App from './App.vue';
+import { createApp } from 'vue'
+import { createAuthon } from '@authon/vue'
+import App from './App.vue'
+
+const app = createApp(App)
 
-const app = createApp(App);
-app.use(AuthonPlugin, {
+app.use(createAuthon({
   publishableKey: 'pk_live_...',
-});
-app.mount('#app');
+  config: {
+    theme: 'auto',
+    locale: 'en',
+  },
+}))
+
+app.mount('#app')
+```
+
+## Composables
+
+### `useAuthon()`
+
+Returns the full auth state and helper methods. The `client` property exposes the underlying `@authon/js` `Authon` instance for all advanced operations.
+
+```ts
+import { useAuthon } from '@authon/vue'
+
+const {
+  isSignedIn,  // boolean — reactive
+  isLoading,   // boolean — reactive
+  user,        // AuthonUser | null — reactive
+  client,      // Authon instance from @authon/js
+  signOut,     // () => Promise<void>
+  openSignIn,  // () => Promise<void>
+  openSignUp,  // () => Promise<void>
+  getToken,    // () => string | null
+} = useAuthon()
 ```
 
-### 2. Use Composables
+### `useUser()`
+
+Returns only the user and loading state as computed refs.
+
+```ts
+import { useUser } from '@authon/vue'
+
+const { user, isLoading } = useUser()
+// user: ComputedRef<AuthonUser | null>
+// isLoading: ComputedRef<boolean>
+```
+
+## Components
+
+```ts
+import {
+  AuthonSignIn,
+  AuthonSignUp,
+  AuthonUserButton,
+  AuthonSignedIn,
+  AuthonSignedOut,
+  AuthonSocialButton,
+  AuthonSocialButtons,
+} from '@authon/vue'
+```
+
+| Component | Description |
+|---|---|
+| `<AuthonSignIn mode="popup" />` | Opens sign-in UI. `mode`: `'popup'` (default) or `'embedded'` |
+| `<AuthonSignUp mode="popup" />` | Opens sign-up UI. `mode`: `'popup'` (default) or `'embedded'` |
+| `<AuthonUserButton />` | Avatar button with dropdown — shows user info and sign-out |
+| `<AuthonSignedIn>` | Renders default slot only when the user is authenticated |
+| `<AuthonSignedOut>` | Renders default slot only when the user is not authenticated |
+| `<AuthonSocialButton provider="google" />` | Single branded OAuth provider button |
+| `<AuthonSocialButtons />` | Renders all configured OAuth provider buttons automatically |
+
+## Examples
+
+### Basic auth state in a navbar
 
 ```vue
+<template>
+  <nav>
+    <AuthonSignedIn>
+      <span>Hello, {{ user?.displayName }}</span>
+      <button @click="signOut">Sign out</button>
+    </AuthonSignedIn>
+    <AuthonSignedOut>
+      <AuthonUserButton />
+    </AuthonSignedOut>
+  </nav>
+</template>
+
 <script setup lang="ts">
-import { useAuthon, useUser } from '@authon/vue';
+import { useAuthon, AuthonSignedIn, AuthonSignedOut, AuthonUserButton } from '@authon/vue'
 
-const { isSignedIn, openSignIn, signOut } = useAuthon();
-const { user, isLoading } = useUser();
+const { user, signOut } = useAuthon()
 </script>
+```
+
+### Email + password sign-in
 
+```vue
 <template>
-  <div v-if="isLoading">Loading...</div>
-  <div v-else-if="isSignedIn">
-    <p>Welcome, {{ user?.displayName }}</p>
-    <button @click="signOut()">Sign Out</button>
-  </div>
-  <div v-else>
-    <button @click="openSignIn()">Sign In</button>
-  </div>
+  <form @submit.prevent="handleSignIn">
+    <input v-model="email" type="email" placeholder="Email" />
+    <input v-model="password" type="password" placeholder="Password" />
+    <button type="submit" :disabled="loading">Sign in</button>
+    <p v-if="error">{{ error }}</p>
+  </form>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useAuthon } from '@authon/vue'
+import { useRouter } from 'vue-router'
+
+const { client } = useAuthon()
+const router = useRouter()
+const email = ref('')
+const password = ref('')
+const loading = ref(false)
+const error = ref('')
+
+async function handleSignIn() {
+  loading.value = true
+  error.value = ''
+  try {
+    await client!.signInWithEmail(email.value, password.value)
+    router.push('/dashboard')
+  } catch (e: any) {
+    error.value = e.message
+  } finally {
+    loading.value = false
+  }
+}
+</script>
+```
+
+### OAuth sign-in
+
+```vue
+<script setup lang="ts">
+import { useAuthon, AuthonSocialButtons } from '@authon/vue'
+
+const { client } = useAuthon()
+
+// Trigger a specific provider directly
+async function signInWithGoogle() {
+  await client!.signInWithOAuth('google')
+}
+</script>
+
+<template>
+  <!-- Or render all configured providers automatically -->
+  <AuthonSocialButtons
+    :compact="false"
+    :labels="{ google: 'Continue with Google' }"
+    @success="() => router.push('/dashboard')"
+    @error="(e) => console.error(e)"
+  />
 </template>
 ```
 
-### 3. Use Components
+### MFA setup
 
 ```vue
 <template>
-  <SignedIn>
-    <UserButton />
-  </SignedIn>
-  <SignedOut>
-    <button @click="openSignIn()">Sign In</button>
-  </SignedOut>
+  <div>
+    <button @click="initMfaSetup">Enable MFA</button>
+    <div v-if="qrCodeSvg" v-html="qrCodeSvg" />
+    <p v-if="secret">Secret: {{ secret }}</p>
+    <input v-model="verifyCode" placeholder="6-digit code" />
+    <button @click="confirmSetup">Verify</button>
+    <ul v-if="backupCodes.length">
+      <li v-for="c in backupCodes" :key="c">{{ c }}</li>
+    </ul>
+  </div>
 </template>
 
 <script setup lang="ts">
-import { SignedIn, SignedOut, UserButton, useAuthon } from '@authon/vue';
+import { ref } from 'vue'
+import { useAuthon } from '@authon/vue'
+
+const { client } = useAuthon()
+const qrCodeSvg = ref('')
+const secret = ref('')
+const backupCodes = ref<string[]>([])
+const verifyCode = ref('')
+
+async function initMfaSetup() {
+  const res = await client!.setupMfa()
+  qrCodeSvg.value = res.qrCodeSvg   // inline SVG for authenticator app
+  secret.value = res.secret
+  backupCodes.value = res.backupCodes
+}
 
-const { openSignIn } = useAuthon();
+async function confirmSetup() {
+  await client!.verifyMfaSetup(verifyCode.value)
+  alert('MFA enabled successfully')
+}
 </script>
 ```
 
-## API Reference
+### MFA verification on sign-in
 
-### Plugin
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useAuthon } from '@authon/vue'
+import { AuthonMfaRequiredError } from '@authon/js'
 
-```ts
-app.use(AuthonPlugin, {
-  publishableKey: string;
-  apiUrl?: string;
-  theme?: 'light' | 'dark' | 'auto';
-  locale?: string;
-  appearance?: Partial<BrandingConfig>;
-});
+const { client } = useAuthon()
+const mfaToken = ref('')
+const totpCode = ref('')
+
+async function signIn(email: string, password: string) {
+  try {
+    await client!.signInWithEmail(email, password)
+  } catch (e) {
+    if (e instanceof AuthonMfaRequiredError) {
+      mfaToken.value = e.mfaToken  // show TOTP input
+    }
+  }
+}
+
+async function verifyMfa() {
+  await client!.verifyMfa(mfaToken.value, totpCode.value)
+}
+</script>
 ```
 
-### Composables
+### Passwordless — magic link
 
-#### `useAuthon()`
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useAuthon } from '@authon/vue'
 
-```ts
-const {
-  isSignedIn,  // Ref<boolean>
-  isLoading,   // Ref<boolean>
-  user,        // Ref<AuthonUser | null>
-  signOut,     // () => Promise<void>
-  openSignIn,  // () => Promise<void>
-  openSignUp,  // () => Promise<void>
-  getToken,    // () => string | null
-  client,      // Authon instance
-} = useAuthon();
+const { client } = useAuthon()
+const email = ref('')
+const sent = ref(false)
+
+async function sendMagicLink() {
+  await client!.sendMagicLink(email.value)
+  sent.value = true
+}
+</script>
 ```
 
-#### `useUser()`
+### Passwordless — email OTP
 
-```ts
-const { user, isLoading } = useUser();
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useAuthon } from '@authon/vue'
+
+const { client } = useAuthon()
+const email = ref('')
+const otp = ref('')
+const step = ref<'email' | 'verify'>('email')
+
+async function sendOtp() {
+  await client!.sendEmailOtp(email.value)
+  step.value = 'verify'
+}
+
+async function verifyOtp() {
+  const user = await client!.verifyPasswordless({ email: email.value, code: otp.value })
+  console.log('Signed in as:', user.email)
+}
+</script>
 ```
 
-### Components
+### Passkeys
 
-| Component | Description |
-|-----------|-------------|
-| `<SignedIn>` | Renders slot only when signed in |
-| `<SignedOut>` | Renders slot only when signed out |
-| `<UserButton>` | Avatar dropdown with sign-out |
-| `<Protect>` | Conditional rendering with fallback slot |
+```vue
+<script setup lang="ts">
+import { useAuthon } from '@authon/vue'
+
+const { client } = useAuthon()
+
+// Register a new passkey (user must be signed in)
+async function registerPasskey() {
+  const credential = await client!.registerPasskey('My MacBook')
+  console.log('Registered passkey:', credential.id)
+}
+
+// Authenticate with an existing passkey
+async function loginWithPasskey() {
+  const user = await client!.authenticateWithPasskey()
+  console.log('Signed in as:', user.email)
+}
+
+// List all registered passkeys
+async function listPasskeys() {
+  const keys = await client!.listPasskeys()
+  console.log(keys)
+}
+</script>
+```
+
+### Web3 wallet authentication
+
+```vue
+<script setup lang="ts">
+import { useAuthon } from '@authon/vue'
+
+const { client } = useAuthon()
+
+async function signInWithWallet() {
+  const address = '0xYourWalletAddress'
+
+  // 1. Get a nonce + signable message from Authon
+  const { nonce, message } = await client!.web3GetNonce(address, 'evm', 'metamask')
+
+  // 2. Sign the message with the wallet
+  const signature = await window.ethereum.request({
+    method: 'personal_sign',
+    params: [message, address],
+  })
+
+  // 3. Verify the signature and sign in
+  const user = await client!.web3Verify(message, signature, address, 'evm', 'metamask')
+  console.log('Signed in as:', user.email)
+}
+
+async function listLinkedWallets() {
+  const wallets = await client!.listWallets()
+  console.log(wallets)
+}
+</script>
+```
+
+### Profile update
+
+```vue
+<script setup lang="ts">
+import { useAuthon } from '@authon/vue'
+
+const { client } = useAuthon()
+
+async function saveProfile() {
+  const updated = await client!.updateProfile({
+    displayName: 'Jane Doe',
+    avatarUrl: 'https://example.com/avatar.png',
+    phone: '+1234567890',
+    publicMetadata: { role: 'admin' },
+  })
+  console.log('Updated user:', updated)
+}
+</script>
+```
+
+### Session management
+
+```vue
+<template>
+  <ul>
+    <li v-for="session in sessions" :key="session.id">
+      {{ session.userAgent }} — {{ session.createdAt }}
+      <button @click="revoke(session.id)">Revoke</button>
+    </li>
+  </ul>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import { useAuthon } from '@authon/vue'
+import type { SessionInfo } from '@authon/shared'
+
+const { client } = useAuthon()
+const sessions = ref<SessionInfo[]>([])
+
+onMounted(async () => {
+  sessions.value = await client!.listSessions()
+})
+
+async function revoke(sessionId: string) {
+  await client!.revokeSession(sessionId)
+  sessions.value = sessions.value.filter(s => s.id !== sessionId)
+}
+</script>
+```
+
+## Social Buttons
+
+`<AuthonSocialButtons>` fetches the enabled OAuth providers from your Authon dashboard and renders branded buttons automatically.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `compact` | `boolean` | `false` | Icon-only square buttons in a row |
+| `gap` | `number` | `10` / `12` | Gap between buttons in px |
+| `labels` | `Record<provider, string>` | — | Override button labels per provider |
+| `onSuccess` | `() => void` | — | Called after successful OAuth sign-in |
+| `onError` | `(error: Error) => void` | — | Called on OAuth error |
+
+For a single provider button:
+
+```vue
+<template>
+  <AuthonSocialButton
+    provider="github"
+    :onClick="handleClick"
+    :loading="isLoading"
+    :compact="false"
+  />
+</template>
+```
+
+**`AuthonSocialButton` props:**
+
+| Prop | Type | Default |
+|---|---|---|
+| `provider` | `OAuthProviderType` | required |
+| `onClick` | `(provider) => void` | required |
+| `loading` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `label` | `string` | `'Continue with {Name}'` |
+| `compact` | `boolean` | `false` |
+| `borderRadius` | `number` | `10` |
+| `height` | `number` | `48` |
+| `size` | `number` | `48` (compact mode) |
+
+## Plugin options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `publishableKey` | `string` | required | Your Authon publishable key |
+| `config.theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | UI theme |
+| `config.locale` | `string` | `'en'` | Language code |
+| `config.apiUrl` | `string` | `'https://api.authon.dev'` | Custom API base URL |
+| `config.mode` | `'popup' \| 'embedded'` | `'popup'` | Modal display mode |
+| `config.appearance` | `Partial<BrandingConfig>` | — | Override branding colors and logo |
+
+## TypeScript
+
+Types are re-exported from `@authon/shared`:
+
+```ts
+import type { AuthonUser, SessionInfo, PasskeyCredential, Web3Wallet } from '@authon/shared'
+import type { AuthonState, AuthonPluginOptions } from '@authon/vue'
+```
 
 ## Documentation