@bagelink/auth

A user-centric authentication library with Vue support. Handles both person and entity accounts seamlessly.

Features

• 🎯 User-Centric Design - Access user data directly, not buried in account objects
• 🔄 Multi-Account Support - Works with person, entity, and service accounts
• 🛡️ Type-Safe - Full TypeScript support
• ⚡ Vue Integration - Reactive refs with Vue 3 composables
• 🔐 Complete Auth Flow - Login, signup, password management, email verification
• 📡 Session Management - View, refresh, and revoke sessions
• 🎪 Event System - Listen to authentication state changes
• 🌐 Framework Agnostic - Core auth logic works anywhere

Installation

pnpm add @bagelink/auth
# or
npm install @bagelink/auth
# or
bun add @bagelink/auth

Quick Start

1. Initialize Auth

import { initAuth, AuthState } from '@bagelink/auth'

const auth = initAuth({ 
  baseURL: 'https://api.example.com'
})

// Listen to auth events
auth.on(AuthState.LOGIN, () => console.log('User logged in!'))

2. Use in Vue Components

<script setup lang="ts">
import { useAuth } from '@bagelink/auth'

const { 
  user,           // Primary state - use this!
  sso,            // SSO providers
  getIsLoggedIn,
  login,
  logout 
} = useAuth()

const handlePasswordLogin = async () => {
  await login({ 
    email: '[email protected]', 
    password: 'password' 
  })
}

const handleSSOLogin = async () => {
  // SSO is just this simple!
  await sso.google.redirect()
}
</script>

<template>
  <div v-if="user">
    <h1>Welcome, {{ user.name }}!</h1>
    <p>Email: {{ user.email }}</p>
    <button @click="logout">Logout</button>
  </div>
  <div v-else>
    <button @click="handlePasswordLogin">Login with Password</button>
    <button @click="handleSSOLogin">Login with Google</button>
  </div>
</template>

Core Concepts

The user Object

The user is a computed ref that provides a unified interface for both person and entity accounts:

const { user } = useAuth()

// Available for all account types
user.value?.id          // Person ID or Entity ID
user.value?.name        // Display name
user.value?.email       // Email address
user.value?.type        // 'person', 'entity', or 'service'
user.value?.isActive    // Is account active
user.value?.isVerified  // Is account verified

// Person-specific
user.value?.roles       // User roles (e.g., ['admin', 'user'])

// Entity-specific
user.value?.entityType  // Entity type (e.g., 'company', 'organization')
user.value?.metadata    // Additional entity metadata

Account Info (Advanced)

For authentication-specific data, use accountInfo:

const { accountInfo } = useAuth()

accountInfo.value?.authentication_methods  // Auth methods
accountInfo.value?.last_login              // Last login timestamp
accountInfo.value?.person                  // Raw person data
accountInfo.value?.entity                  // Raw entity data

API Reference

State

const {
  user,        // Computed<User | null> - Primary state
  accountInfo, // Ref<AccountInfo | null> - Full account data
} = useAuth()

Getters

const {
  getFullName,      // () => string
  getIsLoggedIn,    // () => boolean
  getEmail,         // () => string
  getRoles,         // () => string[]
  getAccountType,   // () => 'person' | 'entity' | 'service'
  isPersonAccount,  // () => boolean
  isEntityAccount,  // () => boolean
} = useAuth()

Authentication

// Login
await login({ email: '[email protected]', password: 'password' })

// Signup
await signup({ 
  email: '[email protected]',
  first_name: 'John',
  last_name: 'Doe',
  password: 'password',
  confirmPassword: 'password'
})

// Logout
await logout()

// Check auth status
const isAuthenticated = await checkAuth()

// Refresh session
await refreshSession()

Password Management

// Change password (requires current password)
await changePassword({
  current_password: 'oldPassword',
  new_password: 'newPassword',
  confirmNewPassword: 'newPassword'
})

// Forgot password
await forgotPassword('[email protected]')

// Verify reset token
await verifyResetToken(token)

// Reset password with token
await resetPassword(token, 'newPassword')

Email Verification

// Send verification email
await sendVerification('[email protected]')

// Verify email with token
await verifyEmail(token)

Profile Management

// Update profile
await updateProfile({
  first_name: 'Jane',
  last_name: 'Smith',
  email: '[email protected]'
})

// Delete current user account
await deleteCurrentUser()

Session Management

// Get active sessions
const { data } = await getSessions()
const sessions = data.sessions

// Revoke specific session
await revokeSession(sessionToken)

// Revoke all sessions
await revokeAllSessions()

Admin Actions

// Activate/deactivate accounts
await activateAccount(accountId)
await deactivateAccount(accountId)

// Delete account
await deleteAccount(accountId)

Event System

Listen to authentication state changes:

import { initAuth, AuthState } from '@bagelink/auth'

const auth = initAuth({ axios })

// Login
auth.on(AuthState.LOGIN, () => {
  console.log('User logged in')
})

// Logout
auth.on(AuthState.LOGOUT, () => {
  console.log('User logged out')
})

// Signup
auth.on(AuthState.SIGNUP, () => {
  console.log('User signed up')
})

// Password changed
auth.on(AuthState.PASSWORD_CHANGE, () => {
  console.log('Password changed')
})

// Password reset
auth.on(AuthState.PASSWORD_RESET, () => {
  console.log('Password reset')
})

// Profile updated
auth.on(AuthState.PROFILE_UPDATE, () => {
  console.log('Profile updated')
})

// Auth check completed
auth.on(AuthState.AUTH_CHECK, () => {
  console.log('Auth verified')
})

// Email verified
auth.on(AuthState.EMAIL_VERIFIED, () => {
  console.log('Email verified')
})

// Session refreshed
auth.on(AuthState.SESSION_REFRESH, () => {
  console.log('Session refreshed')
})

Event Methods

// Add listener
auth.on(AuthState.LOGIN, handler)

// Remove listener
auth.off(AuthState.LOGIN, handler)

// Remove all listeners for an event
auth.removeAllListeners(AuthState.LOGIN)

// Remove all listeners
auth.removeAllListeners()

TypeScript Support

Full TypeScript support with exported types:

import type { 
  User,
  AccountInfo,
  PersonInfo,
  EntityInfo,
  RegisterRequest,
  UpdateAccountRequest,
  AuthenticationResponse,
  SessionInfo,
  // ... and more
} from '@bagelink/auth'

Migration

Upgrading from an older version? See MIGRATION.md for detailed migration instructions.

License

MIT