npm package: @skybaer0804/spark-messaging-client
Description: Spark Messaging Server를 위한 Socket.IO 클라이언트 SDK
Author: Nodejs
Latest version: 1.0.2

# Spark Messaging Client SDK

Spark Messaging Server를 위한 Socket.IO 클라이언트 SDK입니다. 실시간 메시징, 방 기능, 에러 처리 등을 제공하는 간결하고 확장 가능한 API를 제공합니다.

## 설치

```bash
npm install spark-messaging-client
```

또는

```bash
yarn add spark-messaging-client
```

## 빠른 시작

### 기본 사용법

```typescript
import SparkMessaging from 'spark-messaging-client';

// SDK 초기화
const client = new SparkMessaging({
    serverUrl: 'http://localhost:3000',
    projectKey: 'default-project-key-12345',
});

// 연결 성공 이벤트
client.onConnected((data) => {
    console.log('연결 성공:', data.message);
    console.log('Socket ID:', data.socketId);
});

// 메시지 수신
client.onMessage((data) => {
    console.log('메시지 수신:', data);
});

// 메시지 전송
client.sendMessage('chat', 'Hello, World!', 'user123');
```

### 환경 변수 사용

브라우저 환경:

```javascript
window.SPARK_MESSAGING_CONFIG = {
    SERVER_URL: 'http://localhost:3000',
    PROJECT_KEY: 'your-project-key',
};

import SparkMessaging from 'spark-messaging-client';
const client = new SparkMessaging(); // 환경 변수에서 자동 로드
```

Node.js 환경:

```bash
export SERVER_URL=http://localhost:3000
export PROJECT_KEY=your-project-key
```

## API 문서

### 초기화

#### `new SparkMessaging(options?)`

SDK 인스턴스를 생성합니다.

**옵션:**

```typescript
interface SparkMessagingOptions {
    serverUrl: string; // 서버 URL (필수)
    projectKey: string; // 프로젝트 키 (필수)
    autoConnect?: boolean; // 자동 연결 (기본값: true)
    reconnection?: boolean; // 자동 재연결 (기본값: true)
    reconnectionAttempts?: number; // 재연결 시도 횟수 (기본값: 5)
    reconnectionDelay?: number; // 재연결 지연 시간(ms) (기본값: 1000)
}
```

**예제:**

```typescript
const client = new SparkMessaging({
    serverUrl: 'http://localhost:3000',
    projectKey: 'your-key',
    autoConnect: false, // 수동 연결
});
```

### 연결 관리

#### `connect(): Promise<void>`

서버에 연결합니다. `autoConnect: false`로 설정한 경우 수동으로 호출해야 합니다.

```typescript
await client.connect();
```

#### `disconnect(): void`

연결을 종료합니다.

```typescript
client.disconnect();
```

#### `isConnected(): boolean`

연결 상태를 확인합니다.

```typescript
if (client.isConnected()) {
    console.log('연결됨');
}
```

#### `getSocketId(): string | undefined`

현재 Socket ID를 가져옵니다.

```typescript
const socketId = client.getSocketId();
```

### 메시지 API

#### `sendMessage(type, content, user?)`

일반 메시지를 전송합니다.

**파라미터:**

-   `type`: 메시지 타입 (`'chat' | 'notification' | 'system' | 'test'`)
-   `content`: 메시지 내용
-   `user`: 사용자 ID (선택)

```typescript
client.sendMessage('chat', 'Hello!', 'user123');
```

#### `onMessage(callback): () => void`

메시지 수신 콜백을 등록합니다. 구독 해제 함수를 반환합니다.

```typescript
const unsubscribe = client.onMessage((data) => {
    console.log('메시지:', data);
});

// 나중에 구독 해제
unsubscribe();
```

#### `sendRoomMessage(room, type, content, user?)`

특정 방에 메시지를 전송합니다.

```typescript
client.sendRoomMessage('room-1', 'chat', 'Hello Room!', 'user123');
```

#### `onRoomMessage(callback): () => void`

방 메시지 수신 콜백을 등록합니다.

```typescript
client.onRoomMessage((data) => {
    console.log('방 메시지:', data);
});
```

### 방 API

#### `joinRoom(roomName): Promise<void>`

방에 입장합니다.

```typescript
try {
    await client.joinRoom('my-room');
    console.log('방 입장 성공');
} catch (error) {
    console.error('방 입장 실패:', error);
}
```

#### `leaveRoom(roomName): Promise<void>`

방에서 나갑니다.

```typescript
await client.leaveRoom('my-room');
```

#### `getJoinedRooms(): string[]`

현재 참여 중인 방 목록을 가져옵니다.

```typescript
const rooms = client.getJoinedRooms();
console.log('참여 중인 방:', rooms);
```

#### `isInRoom(roomName): boolean`

특정 방에 참여 중인지 확인합니다.

```typescript
if (client.isInRoom('my-room')) {
    console.log('방에 참여 중입니다');
}
```

### 이벤트 핸들링

#### `onConnected(callback): () => void`

연결 성공 이벤트를 처리합니다.

```typescript
client.onConnected((data) => {
    console.log('연결됨:', data.message);
    console.log('Socket ID:', data.socketId);
});
```

#### `onError(callback): () => void`

에러 이벤트를 처리합니다.

```typescript
client.onError((error) => {
    console.error('에러:', error.message);
    if (error.code) {
        console.error('에러 코드:', error.code);
    }
});
```

### 유틸리티

#### `getOptions(): SparkMessagingOptions`

현재 설정을 가져옵니다.

```typescript
const options = client.getOptions();
console.log('서버 URL:', options.serverUrl);
```

## 완전한 예제

```typescript
import SparkMessaging from 'spark-messaging-client';

// 1. SDK 초기화
const client = new SparkMessaging({
    serverUrl: 'http://localhost:3000',
    projectKey: 'default-project-key-12345',
});

// 2. 이벤트 핸들링
client.onConnected((data) => {
    console.log('✅ 연결 성공:', data.message);

    // 연결 후 메시지 전송
    client.sendMessage('chat', 'Hello!', 'user123');
});

client.onMessage((data) => {
    console.log('📥 메시지 수신:', data);
});

client.onError((error) => {
    console.error('❌ 에러:', error.message);
});

// 3. 방 기능 사용
async function roomExample() {
    try {
        // 방 입장
        await client.joinRoom('chat-room');

        // 방 메시지 수신
        client.onRoomMessage((data) => {
            console.log('📥 방 메시지:', data);
        });

        // 방 메시지 전송
        client.sendRoomMessage('chat-room', 'chat', 'Hello Room!', 'user123');

        // 나중에 방 나가기
        await client.leaveRoom('chat-room');
    } catch (error) {
        console.error('방 작업 실패:', error);
    }
}

// 4. 연결 종료 (필요시)
// client.disconnect();
```

## 타입 정의

SDK는 TypeScript로 작성되었으며 완전한 타입 정의를 제공합니다.

```typescript
import type {
    MessageData,
    RoomMessageData,
    ConnectedData,
    ErrorData,
    SparkMessagingOptions,
    MessageCallback,
    RoomMessageCallback,
} from 'spark-messaging-client';
```

## 테스트

서버가 실행 중인 상태에서 테스트를 실행합니다:

```bash
# 서버 실행 (다른 터미널)
npm run dev

# SDK 테스트 실행
npm test
```

환경 변수로 서버 URL과 키를 지정할 수 있습니다:

```bash
SERVER_URL=http://localhost:3000 PROJECT_KEY=your-key npm test
```

## 빌드

```bash
npm run build
```

빌드된 파일은 `dist/` 디렉토리에 생성됩니다:

-   `dist/index.js` - CommonJS 형식
-   `dist/index.esm.js` - ES Module 형식
-   `dist/index.d.ts` - TypeScript 타입 정의

## 개발

```bash
# 개발 모드 (watch 모드)
npm run dev
```

## 라이선스

MIT

## 문서

프로젝트 학습 및 개발을 위한 문서:

-   **[FRONTEND_SETUP.md](./FRONTEND_SETUP.md)** - 프론트엔드 설정 가이드 (설정 파일 예시 포함)
-   **[DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md)** - 개발자 가이드 (기술 스택, 아키텍처, API 레퍼런스, 이벤트 시스템, 개발 가이드)
-   **[DEPLOYMENT.md](./DEPLOYMENT.md)** - npm 배포 가이드

## 참고

-   [Spark Messaging Server README](../README.md) - 백엔드 서버 문서
-   Socket.IO 클라이언트는 `socket.io-client`를 사용합니다.