npm package: @kibaofficial/kio-auth-client
Description: Official client SDK for KioAuth - Self-hosted authentication service
Author: KibaOfficial
Latest version: 0.1.0

# @kibaofficial/kio-auth-client

Official client SDK for [KioAuth](https://github.com/KibaOfficial/kio-auth) - Self-hosted authentication service.

## Installation

```bash
npm install @kibaofficial/kio-auth-client
# or
pnpm add @kibaofficial/kio-auth-client
# or
yarn add @kibaofficial/kio-auth-client
```

## Quick Start

### Core Client (Framework-agnostic)

```typescript
import { createClient } from '@kibaofficial/kio-auth-client';

const auth = createClient({
  baseUrl: 'https://auth.example.com'
});

// Sign in
try {
  const { user } = await auth.signIn({
    email: 'user@example.com',
    password: 'password123'
  });
  console.log('Signed in as:', user.name);
} catch (error) {
  if (error.code === '2FA_REQUIRED') {
    // Show 2FA input
  }
}

// Get current user
const user = await auth.getUser();

// Sign out
await auth.signOut();
```

### React Integration

```tsx
import { KioAuthProvider, useUser, useAuth } from '@kibaofficial/kio-auth-client/react';

function App() {
  return (
    <KioAuthProvider 
      baseUrl="https://auth.example.com"
      redirectUrl="/dashboard"
    >
      <MyApp />
    </KioAuthProvider>
  );
}

function Profile() {
  const { user, isLoading } = useUser();
  const { signOut } = useAuth();
  
  if (isLoading) return <div>Loading...</div>;
  if (!user) return <div>Not signed in</div>;
  
  return (
    <div>
      <p>Hello {user.name}</p>
      <button onClick={() => signOut()}>Sign Out</button>
    </div>
  );
}
```

### Next.js Integration

```typescript
// middleware.ts
import { createAuthMiddleware } from '@kibaofficial/kio-auth-client/next';

export default createAuthMiddleware({
  publicRoutes: ['/', '/about', '/auth(.*)'],
  protectedRoutes: ['/dashboard(.*)'],
  authUrl: 'https://auth.example.com',
});

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};
```

## API Reference

### `createClient(config)`

Creates a new KioAuth client instance.

```typescript
const auth = createClient({
  baseUrl: string;          // Required: Your KioAuth server URL
  credentials?: 'include';  // Optional: Cookie handling (default: 'include')
  timeout?: number;         // Optional: Request timeout in ms (default: 30000)
});
```

### Client Methods

#### Authentication
- `signIn({ email, password, totp? })` - Sign in with credentials
- `signUp({ email, password, username? })` - Create new account
- `signOut()` - Sign out current user
- `requestPasswordReset(email)` - Request password reset email
- `resetPassword(token, password)` - Reset password with token

#### User
- `getUser()` - Get current authenticated user
- `updateProfile({ name?, email? })` - Update user profile

#### Sessions
- `getSessions()` - Get all active sessions
- `revokeSession(sessionId)` - Revoke a specific session
- `validateSession()` - Check if current session is valid

#### OAuth
- `getAccounts()` - Get linked OAuth accounts
- `unlinkAccount(accountId)` - Unlink an OAuth account
- `getOAuthLinkUrl(provider)` - Get OAuth linking URL

#### Two-Factor Authentication
- `get2FAStatus()` - Check if 2FA is enabled
- `setup2FA()` - Generate 2FA secret and QR code
- `verify2FA(code)` - Verify and enable 2FA
- `disable2FA(code)` - Disable 2FA

#### Login History
- `getLoginHistory()` - Get login history

## Error Handling

```typescript
import { KioAuthError } from '@kibaofficial/kio-auth-client';

try {
  await auth.signIn({ email, password });
} catch (error) {
  if (error instanceof KioAuthError) {
    switch (error.code) {
      case '2FA_REQUIRED':
        // Show 2FA input
        break;
      case 'INVALID_CREDENTIALS':
        // Show error message
        break;
      case 'RATE_LIMITED':
        // Too many attempts
        break;
      case 'ACCOUNT_BANNED':
        // Account is banned
        break;
    }
  }
}
```

## Requirements

- Node.js 18+
- React 18+ (for React integration)
- Next.js 13+ (for Next.js integration)

## License

MIT © [KibaOfficial](https://github.com/KibaOfficial)