@drmhse/authos-vue 0.1.3 → 0.1.5

package/README.md

@@ -5,22 +5,13 @@
 
 Vue 3 adapter for [AuthOS](https://authos.dev) - the multi-tenant authentication platform. Provides Vue composables, components, and Nuxt module.
 
-## Installation
+## Quick Start (5 minutes)
 
 ```bash
 npm install @drmhse/authos-vue
 ```
 
-Peer dependencies:
-```bash
-npm install vue
-```
-
-## Quick Start
-
-### Vue App
-
-Install the plugin and use the composables/components:
+Install the plugin and you're ready to go:
 
 ```ts
 // main.ts
@@ -31,43 +22,122 @@ import App from './App.vue';
 const app = createApp(App);
 
 app.use(createAuthOS({
-  // Required: AuthOS API URL (e.g., https://sso.example.com)
-  baseUrl: 'https://sso.example.com'
+  baseURL: 'https://sso.example.com',
 }));
 
 app.mount('#app');
 ```
 
-### Nuxt App
+```vue
+<!-- App.vue -->
+<script setup>
+import { SignIn, SignedIn, SignedOut, UserButton } from '@drmhse/authos-vue';
+</script>
+
+<template>
+  <SignedOut>
+    <SignIn @success="console.log('Welcome!')" />
+  </SignedOut>
+  <SignedIn>
+    <UserButton />
+    <p>You're signed in!</p>
+  </SignedIn>
+</template>
+```
+
+That's it. You now have:
+- Email/password authentication with MFA support
+- Automatic session management
+- User dropdown with logout
+- Conditional rendering based on auth state
+
+## Usage Modes
+
+AuthOS supports two usage modes:
+
+### Platform-Level Access
+
+For platform owners and administrators, use without `org`/`service`:
+
+```ts
+app.use(createAuthOS({
+  baseURL: 'https://sso.example.com',
+}));
+```
+
+### Multi-Tenant Access (Organizations)
+
+For tenant applications with OAuth support, add `org` and `service`:
 
 ```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ['@drmhse/authos-vue/nuxt']
+app.use(createAuthOS({
+  baseURL: 'https://sso.example.com',
+  org: 'acme-corp',    // Organization slug
+  service: 'main-app', // Service slug  
+}));
+```
+
+### Using an Existing Client
+
+For advanced use cases, you can pass a pre-configured `SsoClient`:
+
+```ts
+import { SsoClient } from '@drmhse/sso-sdk';
+import { createAuthOS } from '@drmhse/authos-vue';
+
+// Create client with custom configuration
+const client = new SsoClient({
+  baseURL: 'https://sso.example.com',
+  storage: customStorage,
 });
+
+app.use(createAuthOS({ client }));
+```
+
+## OAuth / Social Login
+
+To use OAuth providers (GitHub, Google, Microsoft), configure your organization and service (see Multi-Tenant Access above):
+
+```ts
+app.use(createAuthOS({
+  baseURL: 'https://sso.example.com',
+  org: 'my-org',           // Your organization slug
+  service: 'my-app',       // Your service slug
+  redirectUri: 'https://app.example.com/callback', // Optional
+}));
+```
+
+Then use individual OAuth buttons:
+
+```vue
+<script setup>
+import { OAuthButton } from '@drmhse/authos-vue';
+</script>
+
+<template>
+  <OAuthButton provider="github" />
+  <OAuthButton provider="google">Sign in with Google</OAuthButton>
+  <OAuthButton provider="microsoft" />
+</template>
 ```
 
 ## Components
 
 ### SignIn
 
-Pre-built sign-in form with email/password and OAuth provider buttons.
+Complete sign-in form with email/password authentication. Supports scoped slots for custom UI.
 
 ```vue
-<script setup lang="ts">
+<script setup>
 import { SignIn } from '@drmhse/authos-vue';
 
 function handleSuccess() {
-  console.log('Logged in!');
-}
-
-function handleError(err: Error) {
-  console.error(err);
+  router.push('/dashboard');
 }
 </script>
 
 <template>
-  <SignIn @success="handleSuccess" @error="handleError" />
+  <SignIn @success="handleSuccess" @error="console.error" />
 </template>
 ```
 
@@ -77,52 +147,74 @@ function handleError(err: Error) {
 | `@success` | - | Fired after successful login |
 | `@error` | `Error` | Fired on login error |
 
+**Scoped Slot:**
+```vue
+<SignIn v-slot="{ email, password, step, error, isSubmitting, updateEmail, updatePassword, submit }">
+  <form @submit.prevent="submit">
+    <input :value="email" @input="e => updateEmail(e.target.value)" />
+    <input :value="password" type="password" @input="e => updatePassword(e.target.value)" />
+    <button :disabled="isSubmitting">Sign In</button>
+    <p v-if="error">{{ error }}</p>
+  </form>
+</SignIn>
+```
+
 ### SignUp
 
 Registration form for new users.
 
 ```vue
-<script setup lang="ts">
-import { SignUp } from '@drmhse/authos-vue';
-</script>
+<SignUp @success="console.log('Check your email!')" @error="console.error" />
+```
 
-<template>
-  <SignUp />
-</template>
+### MagicLinkSignIn
+
+Sign-in component for Magic Links (passwordless).
+
+```vue
+<MagicLinkSignIn @success="console.log('Magic link sent!')" />
 ```
 
-**Events:** Same as `SignIn`
+### PasskeySignIn
 
-### UserButton
+Sign-in component for Passkeys (WebAuthn).
 
-User menu button that shows avatar/name and dropdown with profile/signout.
+```vue
+<PasskeySignIn @success="console.log('Authenticated!')" />
+```
+
+### SignedIn / SignedOut
+
+Conditional rendering based on authentication state. Inspired by Clerk's API.
 
 ```vue
-<script setup lang="ts">
-import { UserButton } from '@drmhse/authos-vue';
-</script>
+<SignedIn>
+  <!-- Only shown when user is logged in -->
+  <UserButton />
+</SignedIn>
+
+<SignedOut>
+  <!-- Only shown when user is logged out -->
+  <SignIn />
+</SignedOut>
+```
 
-<template>
-  <header>
-    <UserButton />
-  </header>
-</template>
+### UserButton
+
+User menu button with avatar and logout.
+
+```vue
+<UserButton @logout="router.push('/')" />
 ```
 
 ### OrganizationSwitcher
 
-Dropdown to switch between organizations (for multi-tenant users).
+Dropdown to switch between organizations.
 
-```vue
-<script setup lang="ts">
-import { OrganizationSwitcher } from '@drmhse/authos-vue';
-</script>
+When switching organizations, the SDK automatically issues new JWT tokens with the new organization context, enabling seamless multi-tenant switching without re-authentication.
 
-<template>
-  <aside>
-    <OrganizationSwitcher />
-  </aside>
-</template>
+```vue
+<OrganizationSwitcher @switch="org => console.log('Switched to:', org.name)" />
 ```
 
 ### Protect
@@ -130,68 +222,58 @@ import { OrganizationSwitcher } from '@drmhse/authos-vue';
 Conditional rendering based on user permissions.
 
 ```vue
-<script setup lang="ts">
-import { Protect } from '@drmhse/authos-vue';
-</script>
+<Protect permission="admin:access">
+  <template #default>
+    <AdminDashboard />
+  </template>
+  <template #fallback>
+    <p>Access denied</p>
+  </template>
+</Protect>
+```
 
-<template>
-  <Protect permission="admin:access">
-    <template #default>
-      <AdminDashboard />
-    </template>
-    <template #fallback>
-      <p>Access denied. Admins only.</p>
-    </template>
-  </Protect>
-</template>
+### OAuthButton
+
+Individual OAuth provider button. Requires `org` and `service` in plugin options.
+
+```vue
+<OAuthButton provider="github" />
+<OAuthButton provider="google">Continue with Google</OAuthButton>
 ```
 
-**Props:**
-| Prop | Type | Description |
-|------|------|-------------|
-| `permission` | `string` | Required permission to access content |
-| `fallback` | `slot` | Shown when user lacks permission |
-| `default` | `slot` | Protected content |
+**Scoped Slot:**
+```vue
+<OAuthButton provider="github" v-slot="{ providerName, isConfigured, handleClick }">
+  <button @click="handleClick" :disabled="!isConfigured">
+    Continue with {{ providerName }}
+  </button>
+</OAuthButton>
+```
 
 ## Composables
 
 ### useAuthOS
 
-Access the AuthOS client directly.
+Access the AuthOS client, state, and configuration.
 
 ```vue
-<script setup lang="ts">
+<script setup>
 import { useAuthOS } from '@drmhse/authos-vue';
 
-const { client, isAuthenticated, isLoading } = useAuthOS();
+const { client, options, isAuthenticated, isLoading } = useAuthOS();
 
 async function handleLogout() {
   await client.auth.logout();
 }
 </script>
-
-<template>
-  <div v-if="isLoading">Loading...</div>
-  <div v-else-if="!isAuthenticated">Please log in</div>
-  <div v-else>
-    <button @click="handleLogout">Logout</button>
-  </div>
-</template>
 ```
 
-**Returns:**
-| Property | Type | Description |
-|----------|------|-------------|
-| `client` | `SsoClient` | The AuthOS SDK client |
-| `isLoading` | `Ref<boolean>` | True while checking auth state |
-| `isAuthenticated` | `Ref<boolean>` | True if user is logged in |
-
 ### useUser
 
 Get the current user's profile.
 
 ```vue
-<script setup lang="ts">
+<script setup>
 import { useUser } from '@drmhse/authos-vue';
 
 const { user, isLoading } = useUser();
@@ -203,73 +285,64 @@ const { user, isLoading } = useUser();
 </template>
 ```
 
-**Returns:**
-| Property | Type | Description |
-|----------|------|-------------|
-| `user` | `Ref<UserProfile | null>` | Current user profile |
-| `isLoading` | `Ref<boolean>` | True while checking auth state |
-
 ### useOrganization
 
-Get the current organization and list of organizations.
+Get and switch between organizations.
 
 ```vue
-<script setup lang="ts">
+<script setup>
 import { useOrganization } from '@drmhse/authos-vue';
 
-const { currentOrganization, organizations, switchOrganization } = useOrganization();
+const { currentOrganization, organizations, switchOrganization, isSwitching } = useOrganization();
 </script>
 
 <template>
-  <div>
-    <h3>{{ currentOrganization?.name }}</h3>
-    <ul>
-      <li v-for="org in organizations" :key="org.id">
-        {{ org.name }}
-      </li>
-    </ul>
-  </div>
+  <h3>{{ currentOrganization?.name }}</h3>
+  <ul>
+    <li v-for="org in organizations" :key="org.id">
+      <button @click="switchOrganization(org.slug)">{{ org.name }}</button>
+    </li>
+  </ul>
 </template>
 ```
 
-**Returns:**
-| Property | Type | Description |
-|----------|------|-------------|
-| `currentOrganization` | `Ref<Organization | null>` | Current organization |
-| `organizations` | `Ref<Organization[]>` | All user's organizations |
-| `switchOrganization` | `(slug: string) => Promise<void>` | Switch to a different org |
-| `isSwitching` | `Ref<boolean>` | True while switching |
-
-## Nuxt Module
+### usePermission / useAnyPermission / useAllPermissions
 
-When using the Nuxt module, the plugin is auto-installed and provides additional server utilities:
+Check user permissions.
 
 ```vue
-<!-- app.vue -->
-<script setup lang="ts">
-// Plugin is auto-installed, composables work automatically
-import { useUser } from '@drmhse/authos-vue';
+<script setup>
+import { usePermission, useAnyPermission, useAllPermissions } from '@drmhse/authos-vue';
 
-const { user } = useUser();
+const canAccessAdmin = usePermission('admin:access');
+const canReadOrWrite = useAnyPermission(['read:data', 'write:data']);
+const hasFullAccess = useAllPermissions(['read:data', 'write:data', 'delete:data']);
 </script>
 
 <template>
-  <div v-if="user">
-    Welcome, {{ user.email }}
-  </div>
+  <button v-if="canAccessAdmin">Admin Panel</button>
 </template>
 ```
 
-### Nuxt Auth Middleware
+## Nuxt Integration
+
+### Plugin Installation
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@drmhse/authos-vue/nuxt'],
+});
+```
 
-Protect pages with the auth middleware:
+### Auth Middleware
 
 ```ts
 // middleware/auth.ts
 import { authMiddleware } from '@drmhse/authos-vue/nuxt';
 
 export default authMiddleware({
-  redirectTo: '/login'
+  redirectTo: '/login',
 });
 ```
 
@@ -278,7 +351,7 @@ Then use in your pages:
 ```vue
 <script setup>
 definePageMeta({
-  middleware: ['auth']
+  middleware: ['auth'],
 });
 </script>
 
@@ -299,7 +372,7 @@ export default defineEventHandler(async (event) => {
   if (!user) {
     throw createError({
       statusCode: 401,
-      message: 'Unauthorized'
+      message: 'Unauthorized',
     });
   }
 
@@ -307,30 +380,50 @@ export default defineEventHandler(async (event) => {
 });
 ```
 
-## SsoClient API
-
-The underlying client from `@drmhse/sso-sdk`. See [SDK docs](https://www.npmjs.com/package/@drmhse/sso-sdk) for full API.
-
-```ts
-const { client } = useAuthOS();
-
-// Authentication
-await client.auth.login({ email, password });
-await client.auth.logout();
-await client.auth.register({ email, password, org_slug });
+## Configuration Reference
+
+### createAuthOS Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `baseURL` | `string` | ✅ | AuthOS API URL |
+| `org` | `string` | For OAuth | Organization slug for OAuth flows |
+| `service` | `string` | For OAuth | Service slug for OAuth flows |
+| `redirectUri` | `string` | - | OAuth redirect URI (defaults to origin + '/callback') |
+| `afterSignInUrl` | `string` | - | Redirect URL after sign-in |
+| `afterSignUpUrl` | `string` | - | Redirect URL after sign-up |
+| `storage` | `TokenStorage` | - | Custom token storage |
+| `autoRefresh` | `boolean` | - | Auto-refresh expired tokens (default: true) |
+| `initialToken` | `string` | - | SSR token for hydration |
+
+## Styling
+
+All components use data attributes for styling hooks:
+
+```css
+[data-authos-signin] { /* Container */ }
+[data-authos-field="email"] { /* Email field wrapper */ }
+[data-authos-field="password"] { /* Password field wrapper */ }
+[data-authos-submit] { /* Submit button */ }
+[data-authos-error] { /* Error message */ }
+[data-authos-oauth] { /* OAuth button */ }
+[data-authos-oauth][data-provider="github"] { /* GitHub button */ }
+[data-authos-divider] { /* "or" divider */ }
+```
 
-// User
-await client.user.getProfile();
-await client.user.updateProfile({ name });
-await client.user.changePassword({ old, new });
+## Migration from v1
 
-// Organizations
-await client.organizations.list();
-await client.organizations.get(slug);
+If you're upgrading from v1, note the following breaking change:
 
-// And more...
+```diff
+ app.use(createAuthOS({
+-  baseUrl: 'https://sso.example.com',
++  baseURL: 'https://sso.example.com',
+ }));
 ```
 
+The `baseUrl` property has been renamed to `baseURL` (uppercase URL) for consistency with the React package and underlying SDK.
+
 ## License
 
 MIT © DRM HSE

package/dist/{chunk-OGRUDANK.mjs → chunk-YED35B36.mjs}

@@ -6,12 +6,16 @@ var AUTH_OS_INJECTION_KEY = /* @__PURE__ */ Symbol("authOS");
 function useAuthOS() {
   const context = inject(AUTH_OS_INJECTION_KEY);
   if (!context) {
+    const defaultOptions = {
+      baseURL: "http://localhost:3001"
+    };
     const defaultClient = new SsoClient({
-      baseURL: "http://localhost:3001",
+      baseURL: defaultOptions.baseURL,
       storage: new MemoryStorage()
     });
     return {
       client: defaultClient,
+      options: defaultOptions,
       isLoading: computed(() => false),
       isAuthenticated: computed(() => false)
     };
@@ -20,6 +24,7 @@ function useAuthOS() {
   const isAuthenticated = computed(() => context.state.isAuthenticated);
   return {
     client: context.client,
+    options: context.options,
     isLoading,
     isAuthenticated
   };