chzzk-python 0.1.0__tar.gz → 0.3.1__tar.gz

{chzzk_python-0.1.0 → chzzk_python-0.3.1}/.github/workflows/publish.yml

@@ -1,9 +1,10 @@
 name: Publish to PyPI
 
 on:
-  push:
-    tags:
-      - 'v*'
+  release:
+    types: [published]
+  workflow_call:
+  workflow_dispatch:
 
 jobs:
   build:
@@ -49,6 +50,7 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
 
   publish-pypi:
     needs: publish-testpypi
@@ -67,3 +69,5 @@ jobs:
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

chzzk_python-0.3.1/.github/workflows/release-please.yml

@@ -0,0 +1,29 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          release-type: python
+
+  publish:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created }}
+    uses: ./.github/workflows/publish.yml
+    permissions:
+      contents: read
+      id-token: write

{chzzk_python-0.1.0 → chzzk_python-0.3.1}/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1](https://github.com/hypn4/chzzk-python/compare/v0.3.0...v0.3.1) (2026-01-23)
+
+
+### Bug Fixes
+
+* **ci:** add skip-existing to PyPI publish workflow ([84cce48](https://github.com/hypn4/chzzk-python/commit/84cce48))
+
+## [0.3.0](https://github.com/hypn4/chzzk-python/compare/v0.2.0...v0.3.0) (2026-01-23)
+
+
+### Features
+
+* add unofficial API with Naver cookie authentication ([2481223](https://github.com/hypn4/chzzk-python/commit/2481223672b56c2de102d42fc4f17e7420e9df7a))
+
+
+### Bug Fixes
+
+* **ci:** trigger publish workflow from release-please ([d63302a](https://github.com/hypn4/chzzk-python/commit/d63302a61e683c73246e5fbd62b7e55cd7bfdd02))
+
+
+### Documentation
+
+* add unofficial API documentation to README ([0c7d575](https://github.com/hypn4/chzzk-python/commit/0c7d5756c6905ec9c4fa2715ffc3655516f9c1e3))
+* add unofficial chat WebSocket protocol documentation ([bb2d4d3](https://github.com/hypn4/chzzk-python/commit/bb2d4d3d6fd058d365d8051169ba3318bdbc5c64))
+* **examples:** add unofficial chat client examples ([8b68a41](https://github.com/hypn4/chzzk-python/commit/8b68a41964588ef40d4a5ce9cdd9bc4080cd5c09))
+
+## [0.2.0](https://github.com/hypn4/chzzk-python/compare/v0.1.0...v0.2.0) (2026-01-23)
+
+
+### Features
+
+* **ci:** add Release Please workflow for automated releases ([34be227](https://github.com/hypn4/chzzk-python/commit/34be227f6f75fe769f0a3760673520487b7dd004))
+
 ## [Unreleased]
 
 ### Added

{chzzk_python-0.1.0 → chzzk_python-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chzzk-python
-Version: 0.1.0
+Version: 0.3.1
 Summary: Unofficial Python SDK for Chzzk (NAVER Live Streaming Platform) API
 Project-URL: Homepage, https://github.com/hypn4/chzzk-python
 Project-URL: Repository, https://github.com/hypn4/chzzk-python
@@ -26,6 +26,7 @@ Requires-Dist: httpx>=0.28.0
 Requires-Dist: pydantic>=2.10.0
 Requires-Dist: python-socketio[asyncio-client]<5.0.0,>=4.6.0
 Requires-Dist: websocket-client>=1.9.0
+Requires-Dist: websockets>=12.0
 Description-Content-Type: text/markdown
 
 # chzzk-python
@@ -288,6 +289,75 @@ except ChzzkAPIError as e:
     print(f"API Error: [{e.status_code}] {e.error_code}: {e.message}")
 ```
 
+## Unofficial API
+
+In addition to the official API, we provide an unofficial API using Naver cookie authentication.
+This enables real-time chat receiving/sending functionality.
+
+> ⚠️ The unofficial API may change at any time and is not officially supported.
+
+### Unofficial Chat Client
+
+**Synchronous version:**
+
+```python
+from chzzk.unofficial import UnofficialChatClient, ChatMessage
+
+chat = UnofficialChatClient(
+    nid_aut="your-nid-aut-cookie",
+    nid_ses="your-nid-ses-cookie",
+)
+
+@chat.on_chat
+def on_chat(msg: ChatMessage):
+    print(f"{msg.nickname}: {msg.content}")
+
+@chat.on_donation
+def on_donation(msg):
+    print(f"{msg.nickname} donated {msg.pay_amount}won")
+
+chat.connect("channel-id")
+chat.send_message("Hello!")
+chat.run_forever()
+```
+
+**Asynchronous version:**
+
+```python
+from chzzk.unofficial import AsyncUnofficialChatClient, ChatMessage
+
+async with AsyncUnofficialChatClient(
+    nid_aut="your-nid-aut-cookie",
+    nid_ses="your-nid-ses-cookie",
+) as chat:
+    @chat.on_chat
+    async def on_chat(msg: ChatMessage):
+        print(f"{msg.nickname}: {msg.content}")
+
+    await chat.connect("channel-id")
+    await chat.send_message("Hello!")
+    await chat.run_forever()
+```
+
+### How to Get Naver Cookies
+
+1. Log in to Naver
+2. Browser Developer Tools (F12) → Application → Cookies
+3. Copy `NID_AUT` and `NID_SES` cookie values
+
+### Unofficial API Exception Handling
+
+```python
+from chzzk import ChatConnectionError, ChatNotLiveError
+
+try:
+    chat.connect("channel-id")
+except ChatNotLiveError:
+    print("Channel is not currently live")
+except ChatConnectionError as e:
+    print(f"Connection failed: {e}")
+```
+
 ## Examples
 
 See the [examples](examples/) directory for complete working examples:
@@ -296,6 +366,8 @@ See the [examples](examples/) directory for complete working examples:
 - `realtime_chat.py` - Realtime chat/donation/subscription events (sync)
 - `realtime_chat_async.py` - Realtime events (async)
 - `session_management.py` - Session management example
+- `unofficial_chat.py` - Unofficial chat client (sync)
+- `unofficial_chat_async.py` - Unofficial chat client (async)
 
 ## API Reference
 

{chzzk_python-0.1.0 → chzzk_python-0.3.1}/README.md

@@ -258,6 +258,75 @@ except ChzzkAPIError as e:
     print(f"API Error: [{e.status_code}] {e.error_code}: {e.message}")
 ```
 
+## Unofficial API
+
+In addition to the official API, we provide an unofficial API using Naver cookie authentication.
+This enables real-time chat receiving/sending functionality.
+
+> ⚠️ The unofficial API may change at any time and is not officially supported.
+
+### Unofficial Chat Client
+
+**Synchronous version:**
+
+```python
+from chzzk.unofficial import UnofficialChatClient, ChatMessage
+
+chat = UnofficialChatClient(
+    nid_aut="your-nid-aut-cookie",
+    nid_ses="your-nid-ses-cookie",
+)
+
+@chat.on_chat
+def on_chat(msg: ChatMessage):
+    print(f"{msg.nickname}: {msg.content}")
+
+@chat.on_donation
+def on_donation(msg):
+    print(f"{msg.nickname} donated {msg.pay_amount}won")
+
+chat.connect("channel-id")
+chat.send_message("Hello!")
+chat.run_forever()
+```
+
+**Asynchronous version:**
+
+```python
+from chzzk.unofficial import AsyncUnofficialChatClient, ChatMessage
+
+async with AsyncUnofficialChatClient(
+    nid_aut="your-nid-aut-cookie",
+    nid_ses="your-nid-ses-cookie",
+) as chat:
+    @chat.on_chat
+    async def on_chat(msg: ChatMessage):
+        print(f"{msg.nickname}: {msg.content}")
+
+    await chat.connect("channel-id")
+    await chat.send_message("Hello!")
+    await chat.run_forever()
+```
+
+### How to Get Naver Cookies
+
+1. Log in to Naver
+2. Browser Developer Tools (F12) → Application → Cookies
+3. Copy `NID_AUT` and `NID_SES` cookie values
+
+### Unofficial API Exception Handling
+
+```python
+from chzzk import ChatConnectionError, ChatNotLiveError
+
+try:
+    chat.connect("channel-id")
+except ChatNotLiveError:
+    print("Channel is not currently live")
+except ChatConnectionError as e:
+    print(f"Connection failed: {e}")
+```
+
 ## Examples
 
 See the [examples](examples/) directory for complete working examples:
@@ -266,6 +335,8 @@ See the [examples](examples/) directory for complete working examples:
 - `realtime_chat.py` - Realtime chat/donation/subscription events (sync)
 - `realtime_chat_async.py` - Realtime events (async)
 - `session_management.py` - Session management example
+- `unofficial_chat.py` - Unofficial chat client (sync)
+- `unofficial_chat_async.py` - Unofficial chat client (async)
 
 ## API Reference
 

{chzzk_python-0.1.0 → chzzk_python-0.3.1}/README_KO.md

@@ -258,6 +258,75 @@ except ChzzkAPIError as e:
     print(f"API 오류: [{e.status_code}] {e.error_code}: {e.message}")
 ```
 
+## 비공식 API (Unofficial API)
+
+공식 API 외에도 네이버 쿠키 인증을 통한 비공식 API를 제공합니다.
+이를 통해 실시간 채팅 수신/전송이 가능합니다.
+
+> ⚠️ 비공식 API는 언제든 변경될 수 있으며, 공식적으로 지원되지 않습니다.
+
+### 비공식 채팅 클라이언트
+
+**동기 버전:**
+
+```python
+from chzzk.unofficial import UnofficialChatClient, ChatMessage
+
+chat = UnofficialChatClient(
+    nid_aut="your-nid-aut-cookie",
+    nid_ses="your-nid-ses-cookie",
+)
+
+@chat.on_chat
+def on_chat(msg: ChatMessage):
+    print(f"{msg.nickname}: {msg.content}")
+
+@chat.on_donation
+def on_donation(msg):
+    print(f"{msg.nickname} donated {msg.pay_amount}won")
+
+chat.connect("channel-id")
+chat.send_message("안녕하세요!")
+chat.run_forever()
+```
+
+**비동기 버전:**
+
+```python
+from chzzk.unofficial import AsyncUnofficialChatClient, ChatMessage
+
+async with AsyncUnofficialChatClient(
+    nid_aut="your-nid-aut-cookie",
+    nid_ses="your-nid-ses-cookie",
+) as chat:
+    @chat.on_chat
+    async def on_chat(msg: ChatMessage):
+        print(f"{msg.nickname}: {msg.content}")
+
+    await chat.connect("channel-id")
+    await chat.send_message("안녕하세요!")
+    await chat.run_forever()
+```
+
+### 네이버 쿠키 획득 방법
+
+1. 네이버에 로그인
+2. 브라우저 개발자 도구 (F12) → Application → Cookies
+3. `NID_AUT`와 `NID_SES` 쿠키 값 복사
+
+### 비공식 API 예외 처리
+
+```python
+from chzzk import ChatConnectionError, ChatNotLiveError
+
+try:
+    chat.connect("channel-id")
+except ChatNotLiveError:
+    print("채널이 현재 라이브 중이 아닙니다")
+except ChatConnectionError as e:
+    print(f"연결 실패: {e}")
+```
+
 ## 예제 코드
 
 완전한 작동 예제는 [examples](examples/) 디렉토리를 참조하세요:
@@ -266,6 +335,8 @@ except ChzzkAPIError as e:
 - `realtime_chat.py` - 실시간 채팅/후원/구독 이벤트 (동기)
 - `realtime_chat_async.py` - 실시간 이벤트 (비동기)
 - `session_management.py` - 세션 관리 예제
+- `unofficial_chat.py` - 비공식 채팅 클라이언트 (동기)
+- `unofficial_chat_async.py` - 비공식 채팅 클라이언트 (비동기)
 
 ## API 문서
 

chzzk_python-0.3.1/docs/unofficial-chat-websocket-protocol.md

@@ -0,0 +1,272 @@
+# Chzzk 비공식 채팅 WebSocket 프로토콜 분석
+
+> 최종 업데이트: 2026-01-23
+> 분석 방법: Chrome DevTools WebSocket 메시지 캡처
+
+## 개요
+
+치지직(Chzzk) 라이브 채팅은 WebSocket을 통해 실시간으로 메시지를 주고받습니다. 이 문서는 브라우저에서 캡처한 실제 WebSocket 메시지를 기반으로 프로토콜 구조를 정리한 것입니다.
+
+---
+
+## 용어 정리
+
+| 용어 | 설명 | 예시 |
+|------|------|------|
+| `channelId` (스트리밍) | 스트리머의 채널 ID. 방송 URL에 포함됨 | `14f67c97d654f655afc0c9b3********` |
+| `cid` (채팅) | 채팅 채널 ID. live-detail API에서 획득 | `N2FOy2` |
+| `sid` (세션) | WebSocket 세션 ID. CONNECTED 응답에서 획득 | `S9g51s_L99y1f_qm4yfhMCdDV6Vxoi...` |
+| `uid` | 사용자 ID 해시. getUserStatus API에서 획득 | `14f67c97d654f655afc0c9b3********` |
+| `accTkn` | 채팅 액세스 토큰. access-token API에서 획득 | `EcXl9izPI9otGQ5yUr1i0wWLKH******` |
+| `extraToken` | 추가 토큰. access-token API에서 획득 (채팅 전송 시 필요) | `uyZcBSQyl3OVq/hVGsuwTCh2Qm******` |
+
+---
+
+## 프로토콜 버전
+
+- **현재 버전**: `"3"`
+- 모든 메시지의 `ver` 필드에 프로토콜 버전을 명시해야 함
+
+---
+
+## 명령어 코드 (cmd)
+
+| 코드 | 이름 | 방향 | 설명 |
+|------|------|------|------|
+| `0` | PING | Server → Client | 서버에서 보내는 핑 |
+| `10000` | PONG | Client → Server | 클라이언트의 퐁 응답 |
+| `100` | CONNECT | Client → Server | 연결 요청 |
+| `10100` | CONNECTED | Server → Client | 연결 완료 응답 |
+| `3101` | SEND_CHAT | Client → Server | 채팅 메시지 전송 |
+| `5101` | REQUEST_RECENT_CHAT | Client → Server | 최근 채팅 요청 |
+| `15101` | RECENT_CHAT | Server → Client | 최근 채팅 응답 |
+| `93101` | CHAT | Server → Client | 실시간 채팅 메시지 |
+| `93102` | DONATION | Server → Client | 후원 메시지 |
+| `93006` | EVENT | Server → Client | 이벤트 메시지 |
+| `94005` | KICK | Server → Client | 강제퇴장 |
+| `94006` | BLOCK | Server → Client | 차단 |
+| `94008` | BLIND | Server → Client | 블라인드 처리 |
+| `94010` | NOTICE | Server → Client | 공지 |
+| `94015` | PENALTY | Server → Client | 제재 |
+
+---
+
+## 메시지 구조
+
+### 1. PONG (cmd: 10000)
+
+서버의 PING에 대한 응답.
+
+```json
+{
+  "ver": "3",
+  "cmd": 10000
+}
+```
+
+### 2. CONNECT (cmd: 100)
+
+WebSocket 연결 후 인증 요청.
+
+```json
+{
+  "ver": "3",
+  "cmd": 100,
+  "svcid": "game",
+  "cid": "N2FOy2",
+  "bdy": {
+    "uid": "14f67c97d654f655afc0c9b3********",
+    "devType": 2001,
+    "accTkn": "EcXl9izPI9otGQ5yUr1i0wWLKHqfPCFTsn/hV+Ec5b5jmyEiTDARbYOZ8OxYGkjq****************",
+    "auth": "SEND"
+  },
+  "tid": 1
+}
+```
+
+**필드 설명:**
+- `svcid`: 서비스 ID (항상 `"game"`)
+- `cid`: 채팅 채널 ID
+- `bdy.uid`: 사용자 ID 해시 (메시지 전송 시 필수)
+- `bdy.devType`: 디바이스 타입 (`2001` = PC)
+- `bdy.accTkn`: 채팅 액세스 토큰
+- `bdy.auth`: 인증 모드 (`"SEND"` = 전송 가능, `"READ"` = 읽기 전용)
+- `tid`: 트랜잭션 ID
+
+### 3. CONNECTED (cmd: 10100)
+
+연결 완료 응답. **중요: `sid`를 저장해야 함.**
+
+```json
+{
+  "ver": "3",
+  "cmd": 10100,
+  "bdy": {
+    "sid": "S9g51s_L99y1f_qm4yfhMCdDV6VxoiPz!fqyXd_8tXFYKo!Qa_War3NOEcVK!84Y7Scugt3t********"
+  }
+}
+```
+
+**중요**: `bdy.sid`를 저장하여 이후 채팅 전송 시 사용해야 합니다.
+
+### 4. REQUEST_RECENT_CHAT (cmd: 5101)
+
+최근 채팅 메시지 요청.
+
+```json
+{
+  "ver": "3",
+  "cmd": 5101,
+  "svcid": "game",
+  "cid": "N2FOy2",
+  "sid": 1,
+  "bdy": {
+    "recentMessageCount": 50
+  },
+  "tid": 3
+}
+```
+
+**참고**: 이 요청의 `sid`는 세션 ID가 아닌 숫자 `1`입니다.
+
+### 5. SEND_CHAT (cmd: 3101) - 핵심
+
+채팅 메시지 전송. **가장 중요한 메시지 구조.**
+
+```json
+{
+  "ver": "3",
+  "cmd": 3101,
+  "svcid": "game",
+  "cid": "N2FOy2",
+  "sid": "S9g51s_L99y1f_qm4yfhMCdDV6VxoiPz!fqyXd_8tXFYKo!Qa_War3NOEcVK!84Y7Scugt3t********",
+  "retry": false,
+  "bdy": {
+    "msg": "메시지 내용",
+    "msgTypeCode": 1,
+    "extras": "{\"chatType\":\"STREAMING\",\"osType\":\"PC\",\"extraToken\":\"uyZcBSQyl3OVq/hVGsuwTCh2Qm+RMtLIY0+FqBimmo1D2KWUKNlzCbrXxR81QZ8Vx5yIqW4oaz9u********\",\"streamingChannelId\":\"14f67c97d654f655afc0c9b3********\",\"emojis\":{}}",
+    "msgTime": 1769139665965
+  },
+  "tid": 6
+}
+```
+
+**필드 설명:**
+- `sid`: CONNECTED 응답에서 받은 세션 ID 문자열 (숫자 아님!)
+- `retry`: 재시도 여부
+- `bdy.msg`: 메시지 내용
+- `bdy.msgTypeCode`: 메시지 타입 (`1` = 일반 텍스트)
+- `bdy.extras`: JSON 문자열로 인코딩된 추가 데이터
+- `bdy.msgTime`: 밀리초 단위 타임스탬프
+
+**extras 필드 상세 (JSON 파싱 후):**
+
+```json
+{
+  "chatType": "STREAMING",
+  "osType": "PC",
+  "extraToken": "uyZcBSQyl3OVq/hVGsuwTCh2Qm+RMtLIY0+FqBimmo1D2KWUKNlzCbrXxR81QZ8Vx5yIqW4oaz9u********",
+  "streamingChannelId": "14f67c97d654f655afc0c9b3********",
+  "emojis": {}
+}
+```
+
+| 필드 | 필수 | 설명 |
+|------|------|------|
+| `chatType` | O | 채팅 타입 (`"STREAMING"`) |
+| `osType` | O | OS 타입 (`"PC"`, `"MOBILE"` 등) |
+| `extraToken` | O | access-token API에서 받은 `extraToken` |
+| `streamingChannelId` | O | 스트리밍 채널 ID (connect 시 사용한 원래 channel ID) |
+| `emojis` | X | 이모지 데이터 (빈 객체 가능) |
+
+---
+
+## 채팅 전송 플로우
+
+```
+1. live-detail API 호출
+   └─> chatChannelId 획득 (예: "N2FOy2")
+
+2. access-token API 호출 (channelId, chatType=STREAMING)
+   └─> accessToken, extraToken 획득
+
+3. getUserStatus API 호출
+   └─> userIdHash 획득 (uid로 사용)
+
+4. WebSocket 연결
+   └─> wss://kr-ss1.chat.naver.com/chat
+
+5. CONNECT 메시지 전송 (cmd: 100)
+   └─> uid, accTkn, auth="SEND" 포함
+
+6. CONNECTED 응답 수신 (cmd: 10100)
+   └─> bdy.sid 저장 (중요!)
+
+7. 채팅 전송 시 SEND_CHAT 메시지 (cmd: 3101)
+   └─> sid (세션 ID 문자열)
+   └─> extras에 extraToken, streamingChannelId 포함
+   └─> msgTime에 현재 시간(ms) 포함
+```
+
+---
+
+## API 엔드포인트
+
+### access-token API
+
+```
+GET https://api.chzzk.naver.com/service/v3/channel/{channelId}/chat/access-token
+```
+
+**Query Parameters:**
+- `channelId`: 스트리밍 채널 ID
+- `chatType`: `STREAMING`
+
+**Response:**
+```json
+{
+  "code": 200,
+  "content": {
+    "accessToken": "EcXl9izPI9otGQ5yUr1i0wWLKH******",
+    "extraToken": "uyZcBSQyl3OVq/hVGsuwTCh2Qm******",
+    "realNameAuth": false,
+    "temporaryRestrict": null
+  }
+}
+```
+
+### getUserStatus API
+
+```
+GET https://api.chzzk.naver.com/service/v1/user/status
+```
+
+**Response:**
+```json
+{
+  "code": 200,
+  "content": {
+    "loggedIn": true,
+    "userIdHash": "14f67c97d654f655afc0c9b3********",
+    ...
+  }
+}
+```
+
+---
+
+## 주의사항
+
+1. **프로토콜 버전**: 모든 메시지에 `"ver": "3"` 사용
+2. **세션 ID**: CONNECTED 응답의 `sid`는 문자열이며, SEND_CHAT에서 반드시 사용해야 함
+3. **extras**: JSON 문자열로 인코딩하여 전송
+4. **extraToken**: 채팅 전송 시 반드시 포함해야 함
+5. **msgTime**: 밀리초 단위의 현재 타임스탬프 사용
+
+---
+
+## 변경 이력
+
+| 날짜 | 변경 내용 |
+|------|----------|
+| 2026-01-23 | 최초 작성. Chrome DevTools WebSocket 캡처 기반 프로토콜 분석 |

chzzk_python-0.3.1/examples/.env.example

@@ -0,0 +1,20 @@
+# Chzzk OAuth Configuration
+# Copy this file to .env and fill in your credentials
+
+CHZZK_CLIENT_ID=your-client-id
+CHZZK_CLIENT_SECRET=your-client-secret
+CHZZK_REDIRECT_URI=http://localhost:8080/callback
+CHZZK_TOKEN_FILE=~/.chzzk_token.json
+CHZZK_PORT=8080
+
+# Unofficial API (Naver Cookie Authentication)
+# 브라우저에서 네이버 로그인 후 개발자 도구에서 쿠키 확인
+# 1. 브라우저에서 chzzk.naver.com에 로그인
+# 2. 개발자 도구 (F12) -> Application -> Cookies -> chzzk.naver.com
+# 3. NID_AUT와 NID_SES 값을 복사
+CHZZK_NID_AUT=your-nid-aut-cookie
+CHZZK_NID_SES=your-nid-ses-cookie
+
+# 시청할 채널 ID (선택사항, 명령행에서도 지정 가능)
+# 채널 ID는 https://chzzk.naver.com/채널ID 형식의 URL에서 확인 가능
+CHZZK_CHANNEL_ID=