WebSocket API

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

Methods

create

WebSocket 연결 객체를 만들어요. 실제 연결은 connect를 호출할 때 시작돼요.

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

const ws = await posPluginSdk.websocket.create(
    'wss://example.com/socket',
    { Authorization: 'Bearer <token>' },
    {
        rejectUnauthorized: true,
        followRedirects: false,
        timeout: 5000,
    },
);

Parameters

파라미터	타입	필수	설명
url	string	O	WebSocket 서버 URL
headers	Record<string, string>	O	연결에 사용할 헤더
options.rejectUnauthorized	boolean	X	SSL 인증서 검증 여부
options.followRedirects	boolean	X	리다이렉트 허용 여부
options.timeout	number	X	연결 타임아웃 (밀리초)

Response

Promise<Websocket> — 생성된 WebSocket 연결 객체예요. 이 객체의 메서드로 연결을 제어해요.

connect

WebSocket 연결을 시작해요.

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

Parameters

파라미터가 없어요.

Response

반환값이 없어요. 연결에 실패하면 에러를 던져요.

disconnect

WebSocket 연결을 종료해요.

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

Parameters

파라미터가 없어요.

Response

반환값이 없어요.

send

메시지를 WebSocket 서버로 전송해요.

/**
 * 메시지 전송
 * @param data 전송할 메시지와 전송 옵션
 */
ws.send({
    data: JSON.stringify({ type: 'ping' }),
    option: { mask: true },
});

Parameters

파라미터	타입	필수	설명
data	string	O	전송할 메시지
option.mask	boolean	X	메시지 마스킹 여부

Response

반환값이 없어요.

Event Handlers

onMessage

메시지 수신 시 호출되는 콜백을 설정해요.

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

Parameters

파라미터	타입	필수	설명
callback	(message: string) => void	O	수신한 메시지 문자열을 받아 실행돼요

Response

반환값이 없어요.

onError

에러 발생 시 호출되는 콜백을 설정해요.

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

Parameters

파라미터	타입	필수	설명
callback	(errorName?: string, errorMessage?: string) => void	O	에러 이름과 메시지를 받아 실행돼요. 둘 다 없을 수 있어요

Response

반환값이 없어요.

onClose

연결 종료 시 호출되는 콜백을 설정해요.

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

Parameters

파라미터	타입	필수	설명
callback	(code: string) => void	O	연결 종료 코드를 받아 실행돼요

Response

반환값이 없어요.

onOpen

연결 성공 시 호출되는 콜백을 설정해요.

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

Parameters

파라미터	타입	필수	설명
callback	() => void	O	연결이 열리면 실행돼요

Response

반환값이 없어요.

사용 예시

실시간 주문 상태 모니터링

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

class OrderMonitor {
    private ws: Websocket;

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

    async connect() {
        // WebSocket 연결 생성
        this.ws = await posPluginSdk.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();
    }
}