@authon/vue 0.3.0 → 0.3.1

package/README.md

@@ -2,469 +2,214 @@
 
 # @authon/vue
 
-Vue 3 Composition API integration for [Authon](https://authon.dev) — plugin setup, composables, and pre-built components.
+> Drop-in Vue 3 authentication with composables and components — self-hosted Clerk alternative, Auth0 alternative
 
-## Install
+[![npm version](https://img.shields.io/npm/v/@authon/vue?color=6d28d9)](https://www.npmjs.com/package/@authon/vue)
+[![License](https://img.shields.io/badge/license-MIT-blue)](../../LICENSE)
 
-```bash
-npm install @authon/vue @authon/js
-```
+## Prerequisites
 
-Requires `vue >= 3.3.0`.
+Before installing the SDK, create an Authon project and get your API keys:
 
-## Setup
+1. **Create a project** at [Authon Dashboard](https://authon.dev/dashboard/overview)
+   - Click "Create Project" and enter your app name
+   - Select the authentication methods you want (Email/Password, OAuth providers, etc.)
 
-Register the plugin in `main.ts`:
-
-```ts
-import { createApp } from 'vue'
-import { createAuthon } from '@authon/vue'
-import App from './App.vue'
-
-const app = createApp(App)
-
-app.use(createAuthon({
-  publishableKey: 'pk_live_...',
-  config: {
-    theme: 'auto',
-    locale: 'en',
-  },
-}))
-
-app.mount('#app')
-```
+2. **Get your API keys** from Project Settings → API Keys
+   - **Publishable Key** (`pk_live_...` or `pk_test_...`) — safe to use in client-side code
+   - **Secret Key** (`sk_live_...` or `sk_test_...`) — server-side only, never expose to clients
 
-## Composables
+3. **Configure OAuth providers** (optional) in Project Settings → OAuth
+   - Add Google, Apple, GitHub, etc. with their respective Client ID and Secret
+   - Set the redirect URL to `https://api.authon.dev/v1/auth/oauth/redirect`
 
-### `useAuthon()`
+> **Test vs Live keys:** Use `pk_test_...` during development. Switch to `pk_live_...` before deploying to production. Test keys use a sandbox environment with no rate limits.
 
-Returns the full auth state and helper methods. The `client` property exposes the underlying `@authon/js` `Authon` instance for all advanced operations.
+## Install
 
-```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()
+```bash
+npm install @authon/vue
 ```
 
-### `useUser()`
-
-Returns only the user and loading state as computed refs.
+## Quick Start
 
 ```ts
-import { useUser } from '@authon/vue'
+// src/main.ts
+import { createApp } from 'vue';
+import { createAuthon } from '@authon/vue';
+import App from './App.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'
+const app = createApp(App);
+app.use(createAuthon({
+  publishableKey: 'pk_live_YOUR_PUBLISHABLE_KEY',
+  config: { apiUrl: 'https://your-authon-server.com' },
+}));
+app.mount('#app');
 ```
 
-| 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>
-
+<!-- src/App.vue -->
 <script setup lang="ts">
-import { useAuthon, AuthonSignedIn, AuthonSignedOut, AuthonUserButton } from '@authon/vue'
-
-const { user, signOut } = useAuthon()
+import { useAuthon, useUser, AuthonSignedIn, AuthonSignedOut, AuthonUserButton } from '@authon/vue';
+const { openSignIn, signOut } = useAuthon();
+const { user } = useUser();
 </script>
-```
 
-### Email + password sign-in
-
-```vue
 <template>
-  <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>
+  <AuthonSignedOut>
+    <button @click="openSignIn()">Sign In</button>
+  </AuthonSignedOut>
+  <AuthonSignedIn>
+    <p>Welcome, {{ user?.email }}</p>
+    <AuthonUserButton />
+    <button @click="signOut()">Sign Out</button>
+  </AuthonSignedIn>
 </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
+## Common Tasks
+
+### Add Google OAuth Login
 
 ```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')
-}
+import { useAuthon } from '@authon/vue';
+const { client } = useAuthon();
 </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>
-```
-
-### MFA setup
-
-```vue
-<template>
-  <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>
+  <button @click="client?.signInWithOAuth('google')">Sign in with Google</button>
 </template>
-
-<script setup lang="ts">
-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
-}
-
-async function confirmSetup() {
-  await client!.verifyMfaSetup(verifyCode.value)
-  alert('MFA enabled successfully')
-}
-</script>
 ```
 
-### MFA verification on sign-in
+### Protect a Route
 
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import { useAuthon } from '@authon/vue'
-import { AuthonMfaRequiredError } from '@authon/js'
-
-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
-    }
+```ts
+// src/router/index.ts
+import { createRouter, createWebHistory } from 'vue-router';
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    { path: '/', component: () => import('../views/Home.vue') },
+    { path: '/dashboard', component: () => import('../views/Dashboard.vue'), meta: { requiresAuth: true } },
+    { path: '/sign-in', component: () => import('../views/SignIn.vue') },
+  ],
+});
+
+router.beforeEach((to, _from, next) => {
+  if (to.meta.requiresAuth) {
+    const authon = router.app?.config.globalProperties.$authon;
+    if (!authon?.isSignedIn) return next({ path: '/sign-in', query: { redirect: to.fullPath } });
   }
-}
+  next();
+});
 
-async function verifyMfa() {
-  await client!.verifyMfa(mfaToken.value, totpCode.value)
-}
-</script>
+export default router;
 ```
 
-### Passwordless — magic link
+### Get Current User
 
 ```vue
 <script setup lang="ts">
-import { ref } from 'vue'
-import { useAuthon } from '@authon/vue'
-
-const { client } = useAuthon()
-const email = ref('')
-const sent = ref(false)
-
-async function sendMagicLink() {
-  await client!.sendMagicLink(email.value)
-  sent.value = true
-}
+import { useUser } from '@authon/vue';
+const { user, isLoading } = useUser();
 </script>
-```
-
-### Passwordless — email OTP
-
-```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>
+<template>
+  <p v-if="isLoading">Loading...</p>
+  <div v-else-if="user">
+    <p>Email: {{ user.email }}</p>
+    <p>Name: {{ user.displayName }}</p>
+  </div>
+  <p v-else>Not signed in</p>
+</template>
 ```
 
-### Passkeys
+### Add Email/Password Auth
 
 ```vue
 <script setup lang="ts">
-import { useAuthon } from '@authon/vue'
-
-const { client } = useAuthon()
+import { ref } from 'vue';
+import { useAuthon } from '@authon/vue';
+const { client } = useAuthon();
+const email = ref('');
+const password = ref('');
 
-// 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)
+async function handleSignIn() {
+  await client?.signInWithEmail(email.value, password.value);
 }
 </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>
+<template>
+  <form @submit.prevent="handleSignIn">
+    <input v-model="email" type="email" placeholder="Email" />
+    <input v-model="password" type="password" placeholder="Password" />
+    <button type="submit">Sign In</button>
+  </form>
+</template>
 ```
 
-### Profile update
+### Handle Sign Out
 
 ```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)
-}
+import { useAuthon } from '@authon/vue';
+const { signOut } = useAuthon();
 </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>
+  <button @click="signOut()">Sign Out</button>
 </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.
+## Environment Variables
 
-**Props:**
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `VITE_AUTHON_API_URL` | Yes | Your Authon server URL |
+| `VITE_AUTHON_PUBLISHABLE_KEY` | Yes | Project publishable key |
 
-| 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 |
+## API Reference
 
-For a single provider button:
+### Plugin
 
-```vue
-<template>
-  <AuthonSocialButton
-    provider="github"
-    :onClick="handleClick"
-    :loading="isLoading"
-    :compact="false"
-  />
-</template>
+```ts
+createAuthon({ publishableKey: string, config?: AuthonConfig })
 ```
 
-**`AuthonSocialButton` props:**
+### Composables
 
-| 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) |
+| Composable | Returns |
+|------------|---------|
+| `useAuthon()` | `{ isSignedIn, isLoading, user, client, signOut, openSignIn, openSignUp, getToken }` |
+| `useUser()` | `{ user: ComputedRef, isLoading: ComputedRef }` |
+| `useAuthonWeb3()` | Web3 wallet auth methods |
+| `useAuthonPasswordless()` | Magic link and OTP methods |
+| `useAuthonPasskeys()` | Passkey registration and auth |
 
-## Plugin options
+### Components
 
-| 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
-
-[authon.dev/docs](https://authon.dev/docs)
+| Component | Description |
+|-----------|-------------|
+| `<AuthonSignIn>` | Sign-in form (`mode="popup"` or `"embedded"`) |
+| `<AuthonSignUp>` | Sign-up form |
+| `<AuthonUserButton>` | Avatar dropdown with sign-out |
+| `<AuthonSignedIn>` | Slot rendered only when signed in |
+| `<AuthonSignedOut>` | Slot rendered only when signed out |
+| `<AuthonSocialButtons>` | All enabled OAuth provider buttons |
+
+## Comparison
+
+| Feature | Authon | Clerk | Auth.js |
+|---------|--------|-------|---------|
+| Self-hosted | Yes | No | Partial |
+| Pricing | Free | $25/mo+ | Free |
+| OAuth providers | 10+ | 20+ | 80+ |
+| ShadowDOM modal | Yes | No | No |
+| MFA/Passkeys | Yes | Yes | Plugin |
+| Web3 auth | Yes | No | No |
 
 ## License
 
-[MIT](../../LICENSE)
+MIT