WebSocket API

POS 플러그인에서 실시간 양방향 통신을 위한 WebSocket 인터페이스를 제공합니다. 실시간 데이터 동기화나 이벤트 수신이 필요한 경우에 사용할 수 있습니다.

WebSocket 생성

WebSocket 연결을 생성합니다.

const ws = await websocket.create(
    url: string,                    // WebSocket 서버 URL
    headers: Record<string, string>, // 연결 헤더 정보
    options?: {                      // 연결 옵션
        rejectUnauthorized?: boolean;  // SSL 인증서 검증 여부 (기본값: true)
        followRedirects?: boolean;     // 리다이렉트 허용 여부 (기본값: false)
        timeout?: number;              // 연결 타임아웃 시간 (밀리초)
    }
);

Methods

connect

WebSocket 연결을 시작합니다.

/**
 * WebSocket 연결 시작
 * @throws 연결 실패 시 에러 발생
 */
await ws.connect();

disconnect

WebSocket 연결을 종료합니다.

/**
 * WebSocket 연결 종료
 */
await ws.disconnect();

send

메시지를 WebSocket 서버로 전송합니다.

/**
 * 메시지 전송
 * @param data 전송할 메시지
 * @param options 전송 옵션
 */
ws.send({
    data: string,                    // 전송할 메시지
    options?: {                      // 전송 옵션
        mask?: boolean;              // 메시지 마스킹 여부 (기본값: true)
    }
});

Event Handlers

onMessage

메시지 수신 시 호출되는 콜백을 설정합니다.

/**
 * 메시지 수신 핸들러 설정
 * @param callback 메시지 수신 시 호출될 콜백 함수
 */
ws.onMessage((message: string) => {
    console.log('수신된 메시지:', message);
});

onError

에러 발생 시 호출되는 콜백을 설정합니다.

/**
 * 에러 핸들러 설정
 * @param callback 에러 발생 시 호출될 콜백 함수
 */
ws.onError((errorName?: string, errorMessage?: string) => {
    console.error('WebSocket 에러:', errorName, errorMessage);
});

onClose

연결 종료 시 호출되는 콜백을 설정합니다.

/**
 * 연결 종료 핸들러 설정
 * @param callback 연결 종료 시 호출될 콜백 함수
 */
ws.onClose((code: string) => {
    console.log('연결 종료 코드:', code);
});

onOpen

연결 성공 시 호출되는 콜백을 설정합니다.

/**
 * 연결 성공 핸들러 설정
 * @param callback 연결 성공 시 호출될 콜백 함수
 */
ws.onOpen(() => {
    console.log('WebSocket 연결 성공');
});

사용 예시

실시간 주문 상태 모니터링

import { websocket } from '@tossplace/pos-plugin-sdk';

class OrderMonitor {
    private ws: WebSocket;

    constructor(private url: string, private token: string) {}

    async connect() {
        // WebSocket 연결 생성
        this.ws = await websocket.create(this.url, {
            Authorization: `Bearer ${this.token}`,
        }, {
            timeout: 5000,
            rejectUnauthorized: true,
        });

        // 이벤트 핸들러 설정
        this.ws.onOpen(() => {
            console.log('주문 모니터링 시작');
        });

        this.ws.onMessage((message) => {
            const orderUpdate = JSON.parse(message);
            this.handleOrderUpdate(orderUpdate);
        });

        this.ws.onError((errorName, errorMessage) => {
            console.error('모니터링 에러:', errorName, errorMessage);
        });

        this.ws.onClose((code) => {
            console.log('모니터링 종료:', code);
        });

        // 연결 시작
        await this.ws.connect();
    }

    private handleOrderUpdate(update: any) {
        console.log('주문 상태 변경:', update);
        // 주문 상태 변경 처리 로직
    }

    async disconnect() {
        await this.ws.disconnect();
    }
}

// 사용 예시
async function monitorOrders() {
    const monitor = new OrderMonitor(
        'wss://api.example.com/orders',
        'your-auth-token'
    );

    try {
        await monitor.connect();
        // 모니터링 중...
    } catch (error) {
        console.error('모니터링 시작 실패:', error);
    } finally {
        await monitor.disconnect();
    }
}