Metadata-Version: 2.4
Name: workhub-bot-sdk
Version: 0.3.0
Summary: Workhub Bot SDK — Build bots for the Workhub collaboration platform
Author: Workhub Team
License-Expression: MIT
Keywords: bot,collaboration,mcp,sdk,workhub
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# workhub-bot-sdk

Workhub 협업 플랫폼용 Python Bot SDK

## 설치

```bash
pip install workhub-bot-sdk
```

## 빠른 시작

```python
from workhub_bot_sdk import WorkhubBot

bot = WorkhubBot(
    base_url="https://your-workhub.com",
    api_key="whb_xxxxxxxx_live_xxxxxxxxxxxxxxxx",
)

# 메시지 보내기
bot.send_message(channel_id="...", content="안녕하세요!")

# 태스크 생성
bot.create_task(topic_id="...", title="새 태스크", priority="high")

# 검색
result = bot.search("배포", type="tasks")
print(f"{result.total}건 검색됨")
```

## 웹훅 이벤트 수신

```python
from workhub_bot_sdk import WorkhubBot, WebhookServer

bot = WorkhubBot(base_url="http://localhost:8080", api_key="whb_xxx")
webhook = WebhookServer(port=9000, secret="your-secret")

@webhook.on("message.created")
def on_message(event):
    bot.send_message(channel_id=event.data["channel_id"], content="수신 확인!")

webhook.start()
```

## API 레퍼런스

### 인증 / 세션
| 메서드 | 설명 |
|--------|------|
| `authenticate(**options)` | 봇 인증 (웹훅 URL / 이벤트 등록) |
| `initialize()` | MCP 세션 초기화 |
| `list_tools()` | 사용 가능한 MCP 도구 목록 |
| `ping()` | 서버 헬스체크 |

### 메시지
| 메서드 | 설명 |
|--------|------|
| `send_message(...)` | 메시지 발송 |
| `read_messages(...)` | 메시지 읽기 |
| `add_reaction(message_id, emoji)` | 반응 추가 (v0.2.0) |
| `remove_reaction(message_id, emoji)` | 반응 제거 (v0.2.0) |
| `get_reactions(message_id)` | 반응 목록 조회 (v0.2.0) |
| `pin_message(message_id)` | 메시지 고정 (v0.2.0) |
| `unpin_message(message_id)` | 고정 해제 (v0.2.0) |
| `list_thread(message_id)` | 스레드 답글 조회 (v0.2.0) |

### 채널
| 메서드 | 설명 |
|--------|------|
| `list_channels(...)` | 채널 목록 |
| `list_channel_members(channel_id)` | 채널 멤버 조회 |
| `list_channel_files(channel_id, ...)` | 채널 파일 목록 |
| `create_channel(name, ...)` | 채널 생성 (v0.2.0) |
| `update_channel(channel_id, ...)` | 채널 수정 (v0.2.0) |
| `delete_channel(channel_id)` | 채널 삭제 (v0.2.0) |
| `join_channel(channel_id)` | 채널 참여 (v0.2.0) |
| `leave_channel(channel_id)` | 채널 나가기 (v0.2.0) |
| `add_channel_member(channel_id, user_id)` | 멤버 추가 (v0.2.0) |
| `remove_channel_member(channel_id, user_id)` | 멤버 제거 (v0.2.0) |

### 북마크
| 메서드 | 설명 |
|--------|------|
| `create_bookmark(channel_id, message_id)` | 북마크 생성 |
| `delete_bookmark(channel_id, message_id)` | 북마크 제거 |
| `list_bookmarks(channel_id, ...)` | 북마크 목록 |

### DM
| 메서드 | 설명 |
|--------|------|
| `get_dm_room(user_id)` | 1:1 DM 방 조회/생성 |
| `create_dm_room(user_ids, name=None)` | 1:1/그룹 DM 방 생성 (v0.2.0) |
| `list_dm_rooms()` | DM 방 목록 (v0.2.0) |
| `send_dm_message(room_id, content)` | DM 메시지 발송 (v0.2.0) |
| `list_dm_messages(room_id, ...)` | DM 메시지 목록 (v0.2.0) |
| `leave_dm_room(room_id)` | DM 방 나가기 (v0.2.0) |

### 태스크
| 메서드 | 설명 |
|--------|------|
| `create_task(...)` | 태스크 생성 |
| `update_task(...)` | 태스크 수정 |
| `list_tasks(...)` | 태스크 목록 |
| `update_task_status(task_id, status)` | 상태 변경 (todo/in_progress/review/done) (v0.2.0) |
| `set_task_dependencies(task_id, depends_on)` | 선행 태스크 설정 (v0.2.0) |
| `delete_task(task_id)` | 태스크 삭제 (v0.2.0) |
| `add_task_assignee(task_id, user_id)` | 담당자 추가 (v0.2.0) |
| `remove_task_assignee(task_id, user_id)` | 담당자 제거 (v0.2.0) |

### 작업일지 (Work Log)
| 메서드 | 설명 |
|--------|------|
| `list_work_logs(from_date=..., to_date=..., task_id=...)` | 작업일지 조회 (v0.2.0) |
| `create_work_log(task_id, work_date, start_time, end_time, memo=None)` | 작업일지 작성 (v0.2.0) |
| `delete_work_log(work_log_id)` | 작업일지 삭제 (v0.2.0) |

### Topic / Project
| 메서드 | 설명 |
|--------|------|
| `list_topics(project_id)` | 토픽 목록 (v0.2.0) |
| `update_topic_status(topic_id, status)` | 토픽 상태 변경 (v0.2.0) |
| `delete_topic(topic_id, confirm_name)` | 토픽 삭제 (v0.2.0) |
| `list_projects(status=None, limit=None)` | 프로젝트 목록 (v0.2.0) |
| `get_project(project_id)` | 프로젝트 상세 (v0.2.0) |

### User / Organization
| 메서드 | 설명 |
|--------|------|
| `get_user(...)` | 사용자 정보 |
| `list_users(...)` | 사용자 목록 |
| `get_me()` | 현재 인증 컨텍스트 (v0.2.0) |
| `list_departments()` | 부서 목록 (v0.2.0) |

### 알림
| 메서드 | 설명 |
|--------|------|
| `list_notifications(limit=None, unread_only=False)` | 알림 목록 (v0.2.0) |
| `mark_notification_read(notification_id)` | 알림 읽음 처리 (v0.2.0) |
| `get_unread_count()` | 읽지 않은 알림 수 (v0.2.0) |

### 검색 / 멘션 / 해시태그
| 메서드 | 설명 |
|--------|------|
| `search(...)` | 통합 검색 |
| `search_mentions(q, ...)` | 멘션 타겟 검색 |
| `search_hashtags(q)` | 해시태그 검색 |
| `get_hashtag_preview(type, id)` | 해시태그 미리보기 |

### 파일
| 메서드 | 설명 |
|--------|------|
| `upload_file(filepath, ...)` | 파일 업로드 |
| `download_file(file_id, dest_path)` | 파일 다운로드 |

### 슬래시 커맨드
| 메서드 | 설명 |
|--------|------|
| `list_slash_commands()` | 슬래시 커맨드 목록 |
| `execute_slash_command(text, ...)` | 커맨드 실행 |

### 봇 전용
| 메서드 | 설명 |
|--------|------|
| `list_bot_commands(bot_id)` | 봇 커맨드 목록 |
| `create_bot_command(bot_id, command, description, ...)` | 봇 커맨드 등록 |
| `delete_bot_command(bot_id, command_name)` | 봇 커맨드 삭제 |
| `create_schedule(...)` | 스케줄 생성 |
| `list_schedules(bot_id, ...)` | 스케줄 목록 |
| `update_schedule(schedule_id, ...)` | 스케줄 수정 |
| `delete_schedule(schedule_id)` | 스케줄 삭제 |

### 인터랙티브 메시지
| 메서드 | 설명 |
|--------|------|
| `send_interactive_message(...)` | 인터랙티브 메시지 발송 |
| `record_action(message_id, action_id, ...)` | 액션 기록 |
| `get_message_actions(message_id)` | 액션 응답 조회 |

## 예제

### 태스크 완료 처리 + 작업일지 기록

```python
# 상태를 done으로 변경
bot.update_task_status(task_id, "done")

# 작업일지 작성
bot.create_work_log(
    task_id=task_id,
    work_date="2026-04-18",
    start_time="09:00",
    end_time="18:00",
    memo="구현 완료",
)
```

### 채널 생성 + 멤버 초대 + 환영 메시지

```python
ch = bot.create_channel(
    name="프로젝트-A",
    description="A 프로젝트 전용",
    channel_type="general",
)

bot.add_channel_member(ch["id"], user_id)
bot.send_message(channel_id=ch["id"], content="환영합니다! 🎉")
```

### 메시지 반응 + 고정

```python
bot.add_reaction(message_id, "👍")
bot.pin_message(message_id)
```

## 변경 이력

`sdk/CHANGELOG.md` 참고.

## 라이선스

MIT
