AtlatestRepositorysigil-twitch

sigil-twitch / treeREADME.md

Read it rendered

1# sigil-twitch
2
3Twitch Helix API client library for Sigil.
4
5Provides functions for stream management, scheduling, analytics, chat
6interaction, and EventSub real-time events.
7
8## Features
9
10- **Channel management** — get/modify channel info (title, game, tags)
11- **Stream info** — query live streams, get stream keys
12- **User lookup** — find users by ID or login
13- **Search** — search categories and channels
14- **Schedule** — CRUD for recurring/non-recurring schedule segments, vacation mode, iCal export
15- **Analytics** — followers, subscribers, clips, VODs, extension/game analytics
16- **Chat** — send messages, list chatters, manage settings, announcements
17- **EventSub** — WebSocket message parsing, subscription management, convenience helpers
18- **Pagination** — generic cursor-based paginator for any list endpoint
19- **Record types** — typed records for channels, streams, users, clips, videos, schedule segments
21## Modules
23| Module | Description |
24|--------|-------------|
25| `(twitch)` | Core client, auth, HTTP helpers, channels, streams, users, search, pagination |
26| `(twitch schedule)` | Schedule segments, vacation, iCalendar export |
27| `(twitch analytics)` | Followers, subscribers, clips, VODs, extension/game analytics |
28| `(twitch chat)` | Chat messages, chatters, settings, announcements |
29| `(twitch eventsub)` | EventSub WebSocket message parsing, subscription management |
30| `(twitch oauth)` | OAuth 2.0 integration via sigil-oauth (token management, auto-refresh) |
32## Usage
34### Client Setup
36```scheme
37(import (twitch))
39;; Create a client with your Twitch credentials
40(define client
41 (twitch-client client-id: "your-client-id"
42 access-token: "your-oauth-token"))
44;; For local development with the Twitch CLI mock server:
45(define mock-client
46 (twitch-client client-id: "test-id"
47 access-token: "test-token"
48 base-url: "http://localhost:8080/mock"))
49```
51### OAuth 2.0 Token Management
53```scheme
54(import (twitch oauth))
56;; Create an OAuth config for Twitch
57(define config
58 (twitch-oauth-config "your-client-id" "your-client-secret"))
60;; Load stored tokens (from ~/.config/sigil/twitch/tokens.json)
61(define tokens (twitch-load-tokens))
63;; Build a client with auto-refresh
64(let-values (((client fresh-tokens)
65 (twitch-ensure-client config tokens (current-second))))
66 ;; client is ready to use with both Client-Id and Bearer headers
67 (twitch-channel-info client "141981764"))
69;; Run the full authorization flow (opens browser, starts callback server)
70(define tokens
71 (oauth-run-authorization-flow config (current-second)))
72(twitch-save-tokens tokens)
73```
75### Channel Info
77```scheme
78;; Get channel info (returns a list of twitch-channel records)
79(let ((channels (twitch-channel-info client "141981764")))
80 (for-each (lambda (ch)
81 (display (twitch-channel-title ch)))
82 channels))
84;; Modify channel title and category
85(twitch-modify-channel client "141981764"
86 #{ title: "Building a Twitch bot in Sigil"
87 game-id: "509670" })
88```
90### Streams
92```scheme
93;; Get live streams for specific users
94(let ((streams (twitch-streams client
95 #{ user-login: "twitchdev" })))
96 (for-each (lambda (s)
97 (display (twitch-stream-title s))
98 (display (twitch-stream-viewer-count s)))
99 streams))
100```
102### Users
104```scheme
105;; Look up users by login name
106(let ((users (twitch-users client #{ login: "twitchdev" })))
107 (for-each (lambda (u)
108 (display (twitch-user-display-name u)))
109 users))
110```
112### Pagination
114```scheme
115;; Auto-paginate through all followers
116(import (twitch analytics))
118(let ((all-followers
119 (twitch-paginate
120 (lambda (cursor)
121 (let ((params (list
122 (cons "broadcaster_id" "141981764")
123 (cons "first" "100")
124 (cons "after" cursor))))
125 (twitch-get/json client
126 (string-append
127 (twitch-api-url client "channels" "followers")
128 (build-query-string params)))))
129 (lambda (item) item) ;; or a custom parse function
130 10))) ;; max 10 pages
131 (display (length all-followers)))
132```
134### Schedule
136```scheme
137(import (twitch schedule))
139;; Get the schedule
140(let ((result (twitch-schedule client "141981764")))
141 (for-each (lambda (seg)
142 (display (twitch-schedule-segment-title seg)))
143 (dict-ref result segments:)))
145;; Create a recurring weekly segment
146(twitch-create-segment client "141981764"
147 "2026-04-04T18:00:00Z" "America/New_York"
148 #{ title: "Friday Coding Stream"
149 duration: 240
150 category-id: "509670"
151 is-recurring: #t })
152```
154### Chat
156```scheme
157(import (twitch chat))
159;; Send a chat message
160(twitch-send-chat-message client
161 "141981764" ;; broadcaster-id
162 "12345678" ;; sender-id (your user ID)
163 "Hello from Sigil!")
164```
166### EventSub
168```scheme
169(import (twitch eventsub))
171;; After connecting to the WebSocket and receiving a welcome message:
172(let* ((msg (parse-eventsub-message raw-json))
173 (session (eventsub-session-from-welcome msg))
174 (session-id (twitch-eventsub-session-id session)))
176 ;; Subscribe to stream online events
177 (twitch-subscribe-stream-online client session-id "141981764")
179 ;; Later, when notifications arrive:
180 (let ((notification (parse-eventsub-message notification-json)))
181 (when (string=? (eventsub-message-type notification) "notification")
182 (let ((event (eventsub-notification-event notification))
183 (type (eventsub-notification-subscription-type notification)))
184 (display type) ;; "stream.online"
185 (display event))))) ;; event data dict
186```
188## Authentication
190All Helix API requests require both a **Client-Id** and a **Bearer access token**.
191The `twitch-client` record holds both and the library adds the appropriate
192headers to every request automatically.
194### Required Scopes
196| Operation | Scope |
197|-----------|-------|
198| Modify channel | `channel:manage:broadcast` |
199| Read stream key | `channel:read:stream_key` |
200| Manage schedule | `channel:manage:schedule` |
201| Read followers | `moderator:read:followers` |
202| Read subscribers | `channel:read:subscriptions` |
203| Send chat messages | `user:write:chat` |
204| Read chat messages (EventSub) | `user:read:chat` |
205| Create clips | `clips:edit` |
206| Extension analytics | `analytics:read:extensions` |
207| Game analytics | `analytics:read:games` |
209## Building
211```bash
212sigil deps install
213sigil build
214```
216## Testing
218```bash
219sigil test
220```
222## Dependencies
224- sigil-stdlib
225- sigil-http
226- sigil-json
227- sigil-oauth