### Complete Next.js K-Auth Integration Example

Source: https://context7.com/relkimm/k-auth/llms.txt

Provides a full setup guide for integrating K-Auth into a Next.js application. It covers authentication configuration, API route setup, creating a login page with provider buttons, and using session data in pages.

```typescript
// 1. Configure authentication (src/auth.ts)
import { KAuth } from '@relkimm/k-auth';

export const { handlers, auth, signIn, signOut } = KAuth({
  kakao: {
    clientId: process.env.KAKAO_CLIENT_ID!,
    clientSecret: process.env.KAKAO_CLIENT_SECRET!,
    collectPhone: true,
  },
  naver: {
    clientId: process.env.NAVER_CLIENT_ID!,
    clientSecret: process.env.NAVER_CLIENT_SECRET!,
  },
});

// 2. Setup API route (app/api/auth/[...nextauth]/route.ts)
import { handlers } from '@/auth';
export const GET = handlers;
export const POST = handlers;

// 3. Create login page (app/login/page.tsx)
'use client';

import { Button } from '@relkimm/k-auth/ui';
import { signIn } from 'next-auth/react';

export default function LoginPage() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <div className="w-full max-w-md space-y-8">
        <h1 className="text-center text-2xl font-bold">로그인</h1>

        <Button.Group>
          <Button.Kakao onClick={() => signIn('kakao', { callbackUrl: '/' })} />
          <Button.Naver onClick={() => signIn('naver', { callbackUrl: '/' })} />
        </Button.Group>
      </div>
    </div>
  );
}

// 4. Use session in pages (app/page.tsx)
import { auth, signOut } from '@/auth';

export default async function Home() {
  const session = await auth();

  if (!session?.user) {
    return <a href="/login">로그인하기</a>;
  }

  return (
    <div>
      <h1>안녕하세요, {session.user.name}님</h1>
      <form action={async () => {
        'use server';
        await signOut({ redirectTo: '/' });
      }}>
        <button type="submit">로그아웃</button>
      </form>
    </div>
  );
}

// 5. Environment variables (.env.local)
// KAKAO_CLIENT_ID=your_kakao_client_id
// KAKAO_CLIENT_SECRET=your_kakao_client_secret
// NAVER_CLIENT_ID=your_naver_client_id
// NAVER_CLIENT_SECRET=your_naver_client_secret

```

--------------------------------

### Configure Apple Sign In Provider

Source: https://context7.com/relkimm/k-auth/llms.txt

Sets up the Apple Sign In provider for authentication. It requires client ID and secret, and offers options to collect user name and email. Name is only provided on the first login.

```typescript
import { Apple } from '@relkimm/k-auth/providers';
import NextAuth from 'next-auth';

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    Apple({
      clientId: process.env.APPLE_ID!,
      clientSecret: process.env.APPLE_SECRET!,
      collectName: true,  // Default: true, adds 'name' scope
      collectEmail: true, // Default: true, adds 'email' scope
    }),
  ],
});

// IMPORTANT: Apple only provides name on first login
// Store it in your database immediately as it won't be available on subsequent logins
// response_mode: 'form_post' is automatically configured
```

--------------------------------

### K-Auth Error Handling System

Source: https://context7.com/relkimm/k-auth/llms.txt

Implements a Korean-language error system for K-Auth, providing detailed information like error code, message, hints, documentation links, and additional details. It allows for structured error catching and developer-friendly logging.

```typescript
import { KAuthError, createError, ERROR_CODES } from '@relkimm/k-auth';

try {
  const { handlers, auth } = KAuth({
    kakao: {
      clientId: '', // Missing!
      clientSecret: process.env.KAKAO_SECRET!,
    },
  });
} catch (error) {
  if (error instanceof KAuthError) {
    // Structured error information
    console.log(error.code);    // 'MISSING_CLIENT_ID'
    console.log(error.message); // 'clientId가 설정되지 않았습니다.'
    console.log(error.hint);    // '환경 변수를 확인해주세요.'
    console.log(error.docs);    // Documentation URL if available
    console.log(error.details); // { provider: 'kakao' }

    // Developer-friendly console output
    error.log();
    // Output:
    // ==================================================
    // [K-Auth 오류] MISSING_CLIENT_ID
    // ==================================================
    //
    // 메시지: clientId가 설정되지 않았습니다.
    // 힌트: 환경 변수를 확인해주세요.
    //
    // 상세 정보: { provider: 'kakao' }
    // ==================================================
  }
}

// Manual error creation
const error = createError(
  'KAKAO_PHONE_NOT_ENABLED',
  { attempted: 'phone_number' }
);

// Available error codes:
// - MISSING_CLIENT_ID, MISSING_CLIENT_SECRET, NO_PROVIDERS
// - KAKAO_CONSENT_REQUIRED, KAKAO_PHONE_NOT_ENABLED, KAKAO_INVALID_REDIRECT_URI
// - NAVER_INVALID_CALLBACK, NAVER_SERVICE_URL_MISMATCH
// - OAUTH_CALLBACK_ERROR, ACCESS_TOKEN_ERROR, USER_INFO_ERROR
// - UNKNOWN_ERROR
```

--------------------------------

### Pre-built Login Button Components

Source: https://context7.com/relkimm/k-auth/llms.txt

Provides ready-to-use login button components for various providers (Kakao, Naver, Google, Apple) that follow official design guidelines. These components accept standard HTML button props and have predefined sizes.

```tsx
'use client';

import { Button } from '@relkimm/k-auth/ui';
import { signIn } from 'next-auth/react';

export function LoginButtons() {
  return (
    <Button.Group direction="column" gap="md">
      {/* Kakao: Yellow background (#FEE500) with black text */}
      <Button.Kakao
        size="default"
        onClick={() => signIn('kakao', { callbackUrl: '/' })}
      >
        카카오 로그인
      </Button.Kakao>

      {/* Naver: Green background (#03C75A) with white text */}
      <Button.Naver
        size="lg"
        onClick={() => signIn('naver', { callbackUrl: '/' })}
      />

      {/* Google: White background with gray border */}
      <Button.Google
        size="sm"
        onClick={() => signIn('google', { callbackUrl: '/' })}
      />

      {/* Apple: Black background with white text */}
      <Button.Apple
        size="icon" // Icon-only mode
        onClick={() => signIn('apple', { callbackUrl: '/' })}
      />
    </Button.Group>
  );
}

// Individual button imports also available:
import { KakaoButton, NaverButton, GoogleButton, AppleButton, ButtonGroup } from '@relkimm/k-auth/ui';

// Sizes: 'default' | 'sm' | 'lg' | 'icon'
// All buttons support standard HTML button props
```

--------------------------------

### Google() Provider Configuration for NextAuth

Source: https://context7.com/relkimm/k-auth/llms.txt

The Google() provider from '@relkimm/k-auth/providers' sets up Google OAuth integration with NextAuth. It allows configuration for collecting profile and email information, which directly translates to the scopes requested.

```typescript
import { Google } from '@relkimm/k-auth/providers';
import NextAuth from 'next-auth';

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    Google({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      collectProfile: true, // Default: true, adds 'profile' scope
      collectEmail: true,   // Default: true, adds 'email' scope
    }),
  ],
});

// Scopes: ['openid', 'profile', 'email']
// Authorization includes: access_type: 'offline', prompt: 'consent'
```

--------------------------------

### KAuth() Main Authentication Wrapper for NextAuth

Source: https://context7.com/relkimm/k-auth/llms.txt

The KAuth() function acts as a main authentication wrapper, integrating Korean providers with NextAuth v5. It simplifies configuration by automatically handling OAuth scopes based on provided flags. This function returns NextAuth handlers and authentication functions.

```typescript
import { KAuth } from '@relkimm/k-auth';

export const { handlers, auth, signIn, signOut } = KAuth({
  kakao: {
    clientId: process.env.KAKAO_CLIENT_ID!,
    clientSecret: process.env.KAKAO_CLIENT_SECRET!,
    collectPhone: true,
    collectBirth: true,
    collectGender: true,
    collectAgeRange: true,
    collectCI: false, // Kakao Sync Business only
  },
  naver: {
    clientId: process.env.NAVER_CLIENT_ID!,
    clientSecret: process.env.NAVER_CLIENT_SECRET!,
    collectPhone: true,
    collectBirth: true,
    collectGender: true,
    collectAge: true,
    collectName: true,
  },
  // Optional: Pass additional NextAuth config
  nextAuthConfig: {
    callbacks: {
      async session({ session, token }) {
        // Custom session handling
        return session;
      },
    },
  },
});

// Usage in Next.js API route: app/api/auth/[...nextauth]/route.ts
export { handlers as GET, handlers as POST };
```

--------------------------------

### Naver() Provider Configuration for NextAuth

Source: https://context7.com/relkimm/k-auth/llms.txt

The Naver() provider from '@relkimm/k-auth/providers' configures Naver OAuth integration with NextAuth. It allows enabling collection of phone, birth, gender, age, and name, affecting the profile transformation.

```typescript
import { Naver } from '@relkimm/k-auth/providers';
import NextAuth from 'next-auth';

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    Naver({
      clientId: process.env.NAVER_CLIENT_ID!,
      clientSecret: process.env.NAVER_CLIENT_SECRET!,
      collectPhone: true,
      collectBirth: true,
      collectGender: true,
      collectAge: true,
      collectName: true,
    }),
  ],
});

// Profile transformation:
// Returns: { id, name, email, image }
// where name uses response.name ?? response.nickname fallback
```

--------------------------------

### Kakao() Provider Configuration for NextAuth

Source: https://context7.com/relkimm/k-auth/llms.txt

The Kakao() provider from '@relkimm/k-auth/providers' integrates Kakao OAuth with NextAuth. It automatically manages scopes based on boolean flags for data collection like phone, birth, gender, and age range.

```typescript
import { Kakao } from '@relkimm/k-auth/providers';
import NextAuth from 'next-auth';

// Using Kakao provider directly with NextAuth
export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    Kakao({
      clientId: process.env.KAKAO_CLIENT_ID!,
      clientSecret: process.env.KAKAO_CLIENT_SECRET!,
      // Automatically adds 'phone_number' to scope
      collectPhone: true,
      // Automatically adds 'birthday' and 'birthyear' to scope
      collectBirth: true,
      // Automatically adds 'gender' to scope
      collectGender: true,
      // Automatically adds 'age_range' to scope
      collectAgeRange: true,
      // Automatically adds 'account_ci' to scope (Kakao Sync Business)
      collectCI: false,
    }),
  ],
});

// The provider automatically constructs scopes:
// Base: ['profile_nickname', 'profile_image', 'account_email']
// With flags above: adds ['phone_number', 'birthday', 'birthyear', 'gender', 'age_range']
```

--------------------------------

### Utility Function for Merging CSS Class Names

Source: https://context7.com/relkimm/k-auth/llms.txt

A utility function, likely using `clsx` and `tailwind-merge`, to efficiently combine and manage CSS class names. It allows for base classes, conditional classes, and user-provided classes, ensuring proper merging and prioritization.

```typescript
import { cn } from '@relkimm/k-auth';

// Combines clsx and tailwind-merge for optimal class merging
const className = cn(
  'base-class',
  condition && 'conditional-class',
  'text-red-500', // This will be merged
  props.className // User classes override defaults
);

// Example: Custom button styling
import { KakaoButton } from '@relkimm/k-auth/ui';
import { cn } from '@relkimm/k-auth';

<KakaoButton
  className={cn(
    'w-full',           // Override width
    'rounded-lg',       // Override border radius
    'shadow-lg'         // Add shadow
  )
}/>
```

--------------------------------

### ButtonGroup Component for Login Buttons

Source: https://context7.com/relkimm/k-auth/llms.txt

A container component designed to organize multiple login buttons with consistent spacing and layout. It supports 'row' or 'column' direction and various gap sizes.

```tsx
import { ButtonGroup, KakaoButton, NaverButton } from '@relkimm/k-auth/ui';

export function LoginPage() {
  return (
    <ButtonGroup
      direction="row"  // 'row' | 'column' (default: 'column')
      gap="lg"         // 'sm' | 'md' | 'lg' (default: 'md')
      className="w-full max-w-md"
    >
      <KakaoButton onClick={() => signIn('kakao')} />
      <NaverButton onClick={() => signIn('naver')} />
    </ButtonGroup>
  );
}

// Gap sizes:
// sm: gap-2 (8px)
// md: gap-3 (12px)
// lg: gap-4 (16px)
```

--------------------------------

### TypeScript Type Definitions for K-Auth

Source: https://context7.com/relkimm/k-auth/llms.txt

Defines the core TypeScript types used within the K-Auth library, including standardized user profiles (KAuthUser) and raw provider-specific profiles for Kakao and Naver. These types ensure data consistency and aid in development.

```typescript
import type {
  KAuthUser,
  KAuthProvider,
  KakaoProfile,
  NaverProfile,
  GoogleProfile,
  AppleProfile
} from '@relkimm/k-auth';

// Standardized user profile across all providers
interface KAuthUser {
  id: string;
  name?: string | null;
  email?: string | null;
  image?: string | null;
  phone?: string | null;
  birthday?: string | null;
  birthyear?: string | null;
  gender?: 'male' | 'female' | null;
  ageRange?: string | null;
}

// Provider type union
type KAuthProvider = 'kakao' | 'naver';

// Raw provider profiles (before transformation)
interface KakaoProfile {
  id: number;
  connected_at: string;
  kakao_account?: {
    profile?: {
      nickname?: string;
      profile_image_url?: string;
    };
    email?: string;
    phone_number?: string;
    birthday?: string;
    birthyear?: string;
    gender?: 'male' | 'female';
    age_range?: string;
    ci?: string;
  };
}

interface NaverProfile {
  resultcode: string;
  message: string;
  response: {
    id: string;
    nickname?: string;
    name?: string;
    email?: string;
    gender?: 'M' | 'F' | 'U';
    mobile?: string;
    birthday?: string;
    birthyear?: string;
    age?: string;
  };
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.