naverworks-ws

네이버웍스 봇(Naver Works Bot) 개발을 위한 통합 TypeScript SDK입니다. 웹소켓 게이트웨이 서버와 클라이언트 SDK를 제공합니다.

주요 기능

• 통합 서버: Ingress (웹훅 수신) 및 Gateway (웹소켓) 서버 기능 통합.
• 클라이언트 SDK: 게이트웨이에 연결하여 이벤트를 수신하고 메시지를 전송하는 직관적인 클라이언트.
• 유연한 구조: 단일 테넌트(직접 연결) 또는 멀티 테넌트(게이트웨이) 아키텍처 지원.
• 메시지 빌더: 복잡한 Flex 메시지와 템플릿을 쉽게 생성할 수 있는 빌더 제공.

설치

npm install naverworks-ws

사용법

1. 서버 설정 (Server Setup)

서버는 네이버웍스 웹훅과 사용자 웹소켓 클라이언트 사이의 다리 역할을 합니다.

import { NaverWorksServer } from 'naverworks-ws';

const server = new NaverWorksServer({
    ingressPort: 3000,      // 네이버웍스 웹훅 수신 포트
    gatewayPort: 8080,      // 웹소켓 클라이언트 연결 포트
    gatewaySecret: 'secret', // (선택) 클라이언트 연결 시 인증할 시크릿 키
    botSecret: '...',       // 네이버웍스 Bot Secret (서명 검증용)
    auth: {
        clientId: '...',
        clientSecret: '...',
        serviceAccount: '...',
        privateKey: '...',
        botId: '...'
    }
});

server.start();

1-1. 서버에서 직접 메시지 처리 (Direct Server Handling)

별도의 웹소켓 클라이언트 없이 서버 프로세스에서 직접 웹훅 이벤트를 받아 처리할 수도 있습니다.

// 웹훅 이벤트 수신
server.on('message', async (event) => {
    console.log('Wehook 수신:', event);
    
    if (event.content && event.channelId) {
        // 직접 메시지 발송
        await server.sendMessage(event.channelId, {
            content: {
                type: 'text',
                text: `서버에서 직접 응답: ${event.content.text}`
            }
        });
    }
});

2. 클라이언트 설정 (Client Setup)

게이트웨이 서버에 연결하여 이벤트를 처리하고 메시지를 보냅니다.

import { Client } from 'naverworks-ws';

const { NaverWorksClient } = Client;

const client = new NaverWorksClient({
    gatewayUrl: 'ws://localhost:8080',
    autoReconnect: true
});

client.on('message', (msg) => {
    console.log('메시지 수신:', msg.content.text);
    
    // 채널에 답장 보내기
    client.sendMessage(msg.source.channelId, '안녕하세요!');
});

// 연결 시작
client.login('your-bot-id', 'secret');

3. 메시지 빌더 사용 (Message Builders)

복잡한 메시지 포맷도 빌더를 통해 쉽게 작성하세요.

import { Client } from 'naverworks-ws';
const { MessageBuilder, FlexBubbleBuilder } = Client;

const message = new MessageBuilder()
    .setFlex('알림',
        new FlexBubbleBuilder()
            .setHeader('경고')
            .addText('확인이 필요합니다!')
            .build()
    )
    .build();

client.sendMessage(channelId, message);