Run on the same machine as an enabled LIVE Studio installation. Credentials stay in memory and are sent only after a matching SERVER_HELLO. This starter never retries automatically.
Not connected
Gift mappings in this sample: 5655 → drop-rose, 6064 → show-gg, 7569 → controller-boost. Replace these with your own rules. Viewer text and credentials are never printed here.
```
---
https://tiktok-live-studio-local-data-access.pages.dev/samples/preview.mjsdocs/public/samples/preview.mjs
```javascript
// Serve only this starter's two assets, only on loopback. No credential endpoint.
import { createServer } from 'node:http'
import { readFile } from 'node:fs/promises'
const files = { '/': ['local-overlay.html', 'text/html'], '/local-client.mjs': ['local-client.mjs', 'text/javascript'] }
const server = createServer(async (request, response) => {
const asset = files[request.url]
if (request.method !== 'GET' || !Array.isArray(asset)) { response.writeHead(404).end(); return }
try {
const content = await readFile(new URL(asset[0], import.meta.url))
response.writeHead(200, { 'Content-Type': asset[1] + '; charset=utf-8', 'Cache-Control': 'no-store',
'Content-Security-Policy': "default-src 'none'; script-src 'self' 'unsafe-inline'; style-src 'unsafe-inline'; connect-src ws://127.0.0.1:*; form-action 'none'; frame-ancestors 'none'",
'X-Content-Type-Options': 'nosniff' })
response.end(content)
} catch { response.writeHead(500).end('Download local-overlay.html and local-client.mjs into the same folder as preview.mjs.'); }
})
server.on('error', () => { console.error('Could not start preview. Check whether 127.0.0.1:4178 is already in use.'); process.exitCode = 1 })
server.listen(4178, '127.0.0.1', () => console.log('Open http://127.0.0.1:4178 — press Ctrl+C to stop.'))
```
---
https://raw.githubusercontent.com/liangpeiran-bit/tiktok-live-studio-local-data-access/main/.agents/skills/tiktok-live-studio-local-data-access/SKILL.md.agents/skills/tiktok-live-studio-local-data-access/SKILL.md
# TikTok LIVE Studio Local Data Access
Build a safe, protocol-correct local client without forcing the project into a particular language, framework, engine, or WebSocket library.
## Scope
Use this skill for software that runs on the same creator machine as TikTok LIVE Studio and needs to consume approved local room events.
Do not treat this protocol as a remote API. The service binds to `127.0.0.1`; a cloud server, another computer, or a mobile device cannot connect to it directly.
## Read the references
Before implementing or diagnosing a connection, read [references/protocol.md](https://raw.githubusercontent.com/liangpeiran-bit/tiktok-live-studio-local-data-access/main/.agents/skills/tiktok-live-studio-local-data-access/references/protocol.md).
Also read the files that match the task:
- Event models, dispatch, or deduplication: [references/events.md](https://raw.githubusercontent.com/liangpeiran-bit/tiktok-live-studio-local-data-access/main/.agents/skills/tiktok-live-studio-local-data-access/references/events.md)
- Gift catalog lookup or gift-to-effect mapping: [references/gift-triggers.md](https://raw.githubusercontent.com/liangpeiran-bit/tiktok-live-studio-local-data-access/main/.agents/skills/tiktok-live-studio-local-data-access/references/gift-triggers.md)
- Language, framework, runtime, or game-engine adaptation: [references/stack-adaptation.md](https://raw.githubusercontent.com/liangpeiran-bit/tiktok-live-studio-local-data-access/main/.agents/skills/tiktok-live-studio-local-data-access/references/stack-adaptation.md)
- Tests, review, or completion checks: [references/verification.md](https://raw.githubusercontent.com/liangpeiran-bit/tiktok-live-studio-local-data-access/main/.agents/skills/tiktok-live-studio-local-data-access/references/verification.md)
The repository documentation is the public source of truth. If it disagrees with this packaged skill, follow the repository docs and update the skill in the same change.
## Workflow
### 1. Establish feasibility
Determine where the client actually runs.
- Continue when the WebSocket client runs on the same Windows machine as TikTok LIVE Studio.
- For Electron, desktop apps, game engines, local services, and command-line tools, put the connection in a long-lived local runtime.
- For H5, continue only when the page runs locally on the creator machine and the browser permits loopback WebSockets. Never embed production credentials in public web assets.
- If the proposed client runs remotely, explain the loopback limitation. Do not invent a remote proxy or ask the developer to expose the local endpoint.
Confirm which events the application needs and how credentials will be supplied at runtime. Never request that a developer paste a raw secret into source control, chat logs, screenshots, or test fixtures.
### 2. Inspect the existing project
Before writing code:
1. Identify the language, runtime, lifecycle model, concurrency model, dependency manager, and test framework.
2. Find an existing WebSocket client or platform API and reuse it when suitable.
3. Locate the project's configuration or secret-storage pattern.
4. Locate existing logging, cancellation, retry, and event-dispatch patterns.
5. Preserve the project's architecture and naming conventions.
Do not migrate frameworks or add a large dependency merely to open one WebSocket. Add a library only when the runtime lacks a suitable client and the project owner permits the dependency.
### 3. Design explicit components
Keep these responsibilities separable even when the project uses a small single-file implementation:
- **Discovery** scans `127.0.0.1:49152-65535` in small, bounded parallel batches and accepts only a verified server hello.
- **Transport** owns exactly one active socket, text-message decoding, close handling, and cancellation.
- **Authentication** sends `AUTH` only after hello validation and waits for `AUTH_RESULT`.
- **Dispatcher** validates the envelope, routes known event names, and ignores unknown events safely.
- **Reconnect policy** rediscoveries and reauthenticates with bounded exponential backoff and jitter.
- **Application adapter** translates protocol events into domain actions, UI updates, overlay actions, or game-engine main-thread work.
Do not couple credentials or socket lifecycle to a UI component that may mount repeatedly.
### 4. Implement the state machine
Use explicit states or equivalent guards:
```text
idle -> scanning -> waiting_hello -> authenticating -> authenticated
| invalid/timeout | rejected
v v
scanning closed
authenticated -> closed -> backoff -> scanning
```
Required behavior:
1. Scan candidate ports in ascending, bounded parallel batches and apply short, cancellable connect/hello timeouts. Never open the entire range at once.
2. Inspect the first server JSON message.
3. Accept the endpoint only when `type`, `product`, `channel`, and supported `version` match the protocol.
4. Send credentials only to that verified endpoint.
5. Send `AUTH` as the first client JSON message.
6. Do not dispatch events until `AUTH_RESULT.success` is `true`.
7. On every new socket, repeat discovery, hello validation, and authentication.
8. Prevent concurrent scan attempts, duplicate sockets, and reconnect timers that survive shutdown.
### 5. Handle events defensively
- Dispatch by the envelope's `event` value, not by guessing from payload fields.
- Deduplicate payloads with a `message_id` using `{event}:{message_id}`.
- Preserve documented string count fields as strings unless the application performs an explicit checked conversion.
- Treat `user` and all user fields as optional.
- Treat chat `content` as untrusted plain text; escape it before rendering into HTML or rich UI.
- Ignore unknown event names and tolerate unknown enum values.
- Isolate malformed or unsupported events; one bad payload must not terminate an otherwise healthy connection.
- For gift-driven behavior, key rules by the string `gift.id`, not by localized name or diamond value. Read [references/gift-triggers.md](https://raw.githubusercontent.com/liangpeiran-bit/tiktok-live-studio-local-data-access/main/.agents/skills/tiktok-live-studio-local-data-access/references/gift-triggers.md) before implementing combo-sensitive effects.
### 6. Apply security and retry rules
- Send the raw issued `secret`; do not hash or transform it.
- Keep credentials out of source files, browser bundles, version control, telemetry, exception messages, and normal logs.
- Redact `secret` and preferably credential identifiers in diagnostic output.
- Never send credentials before validating `SERVER_HELLO`.
- Use the library's native WebSocket ping/pong behavior. Do not create a JSON `HEARTBEAT` message.
- Reuse one connection per local app/client.
- Back off after failures. Do not retry invalid credentials or policy failures in a tight loop.
- Treat disconnect reason `510` as requiring credential or policy intervention; stop automatic retry until configuration changes or the user explicitly retries.
### 7. Verify before handing off
Read [references/verification.md](https://raw.githubusercontent.com/liangpeiran-bit/tiktok-live-studio-local-data-access/main/.agents/skills/tiktok-live-studio-local-data-access/references/verification.md), then run the checks supported by the project. Prefer deterministic tests with a mock WebSocket server; a live smoke test is optional and must use credentials supplied through a secure runtime mechanism.
## Completion report
When implementation is complete, report:
- where the long-lived connection is owned;
- how credentials are supplied without being committed;
- which events are supported;
- how reconnect and reason `510` behave;
- which build, lint, and tests were run;
- any runtime limitation or manual live-test step that remains.
Do not claim live connectivity when only mock tests were run.
---
https://raw.githubusercontent.com/liangpeiran-bit/tiktok-live-studio-local-data-access/main/.agents/skills/tiktok-live-studio-local-data-access/references/protocol.md.agents/skills/tiktok-live-studio-local-data-access/references/protocol.md
# Protocol contract
This is the implementation contract for protocol version `1.0.0`.
## Deployment boundary
The service is local to the creator machine.
| Setting | Value |
| --- | --- |
| Host | `127.0.0.1` |
| Port range | `49152` through `65535`, inclusive |
| Path | `/v1/third-party` |
| URL | `ws://127.0.0.1:{port}/v1/third-party` |
| Protocol version | `1.0.0` |
| Authentication timeout | 20 seconds |
| Native WebSocket ping interval | 30 seconds |
Do not replace `127.0.0.1` with a LAN address, public hostname, or cloud endpoint. Do not expose or proxy this endpoint to a network.
## Discovery and message order
LIVE Studio probes this range from low to high and binds the first available port. The selected port is not stable across launches and must not be hard-coded or treated as permanent discovery state.
Because the range contains 16,384 candidates, scan it in small, bounded parallel batches. Do not scan one port at a time with a long timeout, and do not open the entire range at once. For each candidate in the current batch:
1. Open the candidate WebSocket with a bounded timeout.
2. Wait for the first server text message with a bounded timeout.
3. Parse it as JSON and validate all `SERVER_HELLO` identity fields.
4. If connection, timeout, parsing, or validation fails, close that socket and continue scanning.
5. When one candidate returns a valid hello, keep that socket, close every losing candidate socket, and stop scanning.
6. Send `AUTH` as the first client JSON message.
7. Wait for `AUTH_RESULT` before accepting events.
Never send credentials to a socket that has not produced a valid hello.
## `SERVER_HELLO`
Direction: server to client. It is sent immediately after the WebSocket opens.
```json
{
"type": "SERVER_HELLO",
"product": "tiktok_live_studio",
"channel": "third-party-im",
"version": "1.0.0"
}
```
Validate exact values for `type`, `product`, and `channel`. For `version`, accept only versions the client explicitly supports. Do not silently assume an unknown version is compatible.
## `AUTH`
Direction: client to server. It must be the first client JSON message.
```json
{
"type": "AUTH",
"app_id": "your_app_id",
"key_id": "your_key_id",
"secret": "your_raw_secret",
"version": "1.0.0"
}
```
| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `type` | string | yes | Exactly `AUTH` |
| `app_id` | string | yes | Issued application ID |
| `key_id` | string | yes | Issued key version ID |
| `secret` | string | yes | Raw issued secret; do not hash or transform |
| `version` | string | no | Client protocol version |
Do not log the serialized `AUTH` message.
## `AUTH_RESULT`
Direction: server to client.
```json
{
"type": "AUTH_RESULT",
"success": true,
"app_id": "your_app_id",
"app_name": "Example App",
"message": "Authentication successful",
"server_time": 1786010400000,
"version": "1.0.0"
}
```
| Field | Type | Required |
| --- | --- | --- |
| `type` | string | yes |
| `success` | boolean | yes |
| `app_id` | string | yes |
| `app_name` | string | no |
| `message` | string | yes |
| `server_time` | number | yes, Unix milliseconds |
| `version` | string | yes |
| `error_code` | string | only on relevant failures |
Branch program logic on `success` and `error_code`, not on human-readable `message`.
Authentication error codes:
| Code | Meaning | Retry guidance |
| --- | --- | --- |
| `INVALID_FORMAT` | Malformed JSON or AUTH contract | Fix the client; do not loop |
| `ACCESS_DISABLED` | Local access disabled | Wait for policy/user intervention |
| `INVALID_CREDENTIALS` | App, key, or secret mismatch | Refresh credentials; do not loop |
| `CONNECTION_LIMIT` | Total or per-app limit reached | Close duplicates; back off |
| `AUTH_TIMEOUT` | AUTH not accepted within 20 seconds | Fix ordering/timing; then retry |
| `SERVER_ERROR` | Local gateway failure | Back off and retry with a cap |
## `EVENT`
Direction: server to client, only after successful authentication.
```json
{
"type": "EVENT",
"event": "live.chat",
"timestamp": 1786010400000,
"payload": {}
}
```
The envelope requires `type`, string `event`, numeric millisecond `timestamp`, and object `payload`. See [events.md](https://raw.githubusercontent.com/liangpeiran-bit/tiktok-live-studio-local-data-access/main/.agents/skills/tiktok-live-studio-local-data-access/references/events.md) for event payloads.
## `DISCONNECT`
The server may send this before intentionally closing an authenticated socket.
```json
{
"type": "DISCONNECT",
"app_id": "your_app_id",
"reason_code": 510,
"reason": "Application access policy changed",
"timestamp": 1786010400000
}
```
Required fields are `type`, `app_id`, numeric `reason_code`, human-readable `reason`, and numeric millisecond `timestamp`. Branch program logic on `reason_code`, not `reason`.
| Code | Name | Client behavior |
| --- | --- | --- |
| `100` | `UserInitiated` | Close cleanly |
| `200` | `PeerClosed` | Reconnect only if the app still needs data |
| `201` | `ClientError` | Inspect the client failure before retrying |
| `300` | `HeartbeatTimeout` | Check event-loop stalls; back off and reconnect |
| `400` | `AuthFailed` | Use auth failure handling |
| `500` | `ServerShutdown` | Back off and rediscover later |
| `510` | `AccessPolicyChanged` | Stop automatic retry until credentials or policy change |
## Close, heartbeat, and reconnect
- The server uses native WebSocket ping/pong. Standard clients normally answer ping automatically.
- There is no protocol-level JSON `HEARTBEAT` message.
- A closed socket loses authentication state.
- Every reconnect must scan again, validate a new hello, send AUTH, and await AUTH_RESULT.
- Use cancellable exponential backoff with jitter and a reasonable cap.
- Ensure application shutdown cancels active scans, sockets, and pending reconnect timers.
---
https://raw.githubusercontent.com/liangpeiran-bit/tiktok-live-studio-local-data-access/main/.agents/skills/tiktok-live-studio-local-data-access/references/events.md.agents/skills/tiktok-live-studio-local-data-access/references/events.md
# Event contracts
Events arrive inside the authenticated `EVENT` envelope.
## Common envelope
```json
{
"type": "EVENT",
"event": "live.like",
"timestamp": 1786010400000,
"payload": {}
}
```
Dispatch by `event`. Ignore unknown event names without closing the connection.
When `payload.message_id` exists, the recommended deduplication key is:
```text
{event}:{message_id}
```
Choose a bounded cache with expiration so a long-running client does not leak memory.
## Public user
The `user` object is optional. Every nested field is also optional.
| Field | Type |
| --- | --- |
| `id` | string |
| `nickname` | string |
| `display_id` | string |
| `avatar_url` | string |
Do not reject an otherwise valid event because `user` or one of these fields is absent.
## `live.like`
| Payload field | Type | Required | Notes |
| --- | --- | --- | --- |
| `message_id` | string | yes | Deduplication ID; invalid IDs are not delivered |
| `room_id` | string | yes | May be empty |
| `count` | string | yes | Per-message count; may be empty |
| `total` | string | yes | Accumulated count; may be empty |
| `user` | object | no | Public user |
Keep `count` and `total` as strings at the protocol boundary. If the domain needs numbers, parse them with checked conversion and retain a safe fallback.
## `live.gift`
| Payload field | Type | Required | Notes |
| --- | --- | --- | --- |
| `message_id` | string | yes | Deduplication ID |
| `room_id` | string | yes | May be empty |
| `gift` | object | yes | Gift data |
| `group_id` | string | yes | May be empty |
| `group_count` | string | yes | May be empty |
| `repeat_count` | string | yes | May be empty |
| `combo_count` | string | yes | May be empty |
| `repeat_end` | boolean | yes | Combo/repeat completion |
| `user` | object | no | Public user |
Gift object:
| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `id` | string | yes | Gift ID |
| `name` | string | yes | May be empty |
| `type` | number | yes | May be `0`; tolerate unknown enum values |
| `diamond_count` | number | yes | Per-gift value; may be `0` |
| `image_url` | string | yes | May be empty |
All gift count fields documented as strings must remain strings at the protocol boundary. Use `repeat_end` when the application needs to finalize combo presentation.
For gift selection and effect dispatch, read [gift-triggers.md](https://raw.githubusercontent.com/liangpeiran-bit/tiktok-live-studio-local-data-access/main/.agents/skills/tiktok-live-studio-local-data-access/references/gift-triggers.md). Match configuration by the string `gift.id`; do not use name, price, image URL, or catalog position as identity. The bundled catalog at `../assets/gifts.json` is an authoring snapshot, while each live event is the runtime source of truth.
## `live.chat`
| Payload field | Type | Required | Notes |
| --- | --- | --- | --- |
| `message_id` | string | yes | Deduplication ID |
| `room_id` | string | yes | May be empty |
| `content` | string | yes | Untrusted plain text |
| `user` | object | no | Public user |
Render `content` as text. Escape or sanitize it before inserting it into HTML, rich text, command interpreters, logs, or overlays.
## Compatibility rules
- Validate fields needed for the application's action, but do not crash the connection on one malformed event.
- Tolerate extra object fields for forward compatibility.
- Tolerate unknown enum values.
- Keep transport DTOs separate from stricter domain models when the application needs stronger invariants.
- Do not invent undocumented event names or payload fields.
---
https://raw.githubusercontent.com/liangpeiran-bit/tiktok-live-studio-local-data-access/main/.agents/skills/tiktok-live-studio-local-data-access/references/gift-triggers.md.agents/skills/tiktok-live-studio-local-data-access/references/gift-triggers.md
# Gift selection and effect mapping
Read this file when a task maps `live.gift` events to application or game effects.
The skill ships a curated snapshot at `../assets/gifts.json`. The public source is:
```text
https://tiktok-live-studio-local-data-access.pages.dev/data/gifts.json
```
The catalog is a discovery aid, not a permanent global allowlist. Its metadata records region, capture time, `is_full_gift_data`, captured count, displayed count, and limitations. Gift availability and presentation can vary by region, room, account, campaign, and time.
## Identity rules
- Key application configuration by the string value of `payload.gift.id`.
- Do not key by `gift.name`; names can be duplicated and localized.
- Do not key by `diamond_count`, image URL, or catalog order; these are mutable presentation data.
- Use the live event values for display and keep a fallback for unknown IDs.
Example domain configuration:
```json
{
"5655": { "effect": "drop-rose", "trigger": "combo-end" },
"6064": { "effect": "show-gg", "trigger": "immediate" },
"7569": { "effect": "controller-boost", "trigger": "combo-end" }
}
```
Keep this mapping outside discovery, transport, authentication, and protocol DTOs. Validate configured IDs as strings, but do not reject a running connection when an event contains an unconfigured gift.
## Combo policy
`repeat_count`, `combo_count`, and `group_count` are strings and may represent cumulative progress. Choose a policy explicitly:
1. **Combo end**: if `repeat_end` is false, wait; when true, execute once with the final checked count. Prefer this for state-changing effects.
2. **Immediate update**: execute a lightweight update once per deduplicated `message_id`; never interpret a cumulative count as an event delta.
3. **Per unit**: maintain the last checked count per non-empty `group_id`, calculate `max(0, current - previous)`, and remove state at `repeat_end=true`.
Checked parsing must reject negative, fractional, non-finite, or unsafe values and use an application-defined fallback. Bound and expire per-group state so malformed or abandoned combos cannot leak memory.
## Verification
Test at least:
- two same-name gifts with different IDs select different rules;
- string and numeric-looking IDs are normalized to the documented string key;
- an unknown ID takes the intended ignore or fallback path;
- duplicate `message_id` values do not repeat an effect;
- intermediate cumulative combo updates do not multiply the final effect;
- `repeat_end=true` clears per-group state;
- gameplay or UI effects run on the runtime's required main thread;
- the static catalog is never treated as runtime authorization or availability.
---
https://raw.githubusercontent.com/liangpeiran-bit/tiktok-live-studio-local-data-access/main/.agents/skills/tiktok-live-studio-local-data-access/references/stack-adaptation.md.agents/skills/tiktok-live-studio-local-data-access/references/stack-adaptation.md
# Technology-stack adaptation
The protocol is stack-independent. Adapt its state machine to the project's existing runtime instead of translating one sample line by line.
## Selection rules
1. Reuse the project's current WebSocket client or platform API when it supports text messages, close/error handling, cancellation, and native ping/pong.
2. Match the existing synchronous, callback, promise, coroutine, task, or async-stream model.
3. Keep socket I/O off UI or game render loops.
4. Marshal domain/UI work onto the framework's required main thread.
5. Make shutdown explicit and idempotent.
6. Use the project's dependency manager and quality commands. Do not introduce a second package manager.
7. Keep gift-to-effect rules in domain configuration keyed by `gift.id`; do not put gift names, prices, or effect execution into the transport layer.
8. Discover the dynamic `49152-65535` endpoint with cancellable, bounded-concurrency batches. Never open the full range at once.
## Browser and H5 overlays
- A browser page can connect only when it runs on the creator machine and browser policy permits `ws://127.0.0.1`.
- Use the native `WebSocket` API unless the application already has a wrapper.
- Browser JavaScript cannot control native ping/pong; the browser handles it.
- Never compile real `app_id`, `key_id`, or `secret` into a public/static bundle.
- Render chat with `textContent` or the framework's escaped text binding, not raw HTML.
- Close the socket and cancel retries when the page or component is disposed.
If secure runtime credential delivery is impossible, recommend a trusted local desktop/service host instead of weakening credential handling.
## Node.js and Electron
- Prefer the runtime's supported WebSocket implementation or an existing project library.
- In Electron, keep the connection in a long-lived main/service process rather than a remounting renderer component.
- Expose a narrow, validated IPC event surface to renderers. Never forward the secret.
- Tie retry cancellation to application shutdown and prevent multiple windows from creating duplicate connections.
## .NET desktop and Unity
- Prefer `ClientWebSocket` when compatible with the target runtime; otherwise reuse the project's established Unity WebSocket package.
- Run connect/receive loops in cancellable tasks or coroutines without blocking the game loop.
- Marshal Unity object, scene, and UI updates onto Unity's main thread.
- Own the connection in a persistent service or object and avoid reconnecting from `Update()`.
- Cancel and dispose on application quit, domain reload, or owner teardown.
## Java and Kotlin
- Prefer the platform HTTP/WebSocket client or an existing OkHttp-style dependency.
- Use the project's executor, coroutine scope, or lifecycle owner.
- Serialize state transitions so callbacks cannot create two authenticated sockets.
- Cancel callbacks and retry jobs when the owner stops.
## Python
- Reuse the project's sync or async WebSocket library; do not mix event-loop models.
- In async applications, make scan, receive, and backoff cancellation-aware.
- In GUI applications, forward events to the toolkit's main/UI thread.
- Avoid logging exception objects that embed request payloads or credentials.
## Go
- Reuse the project's WebSocket library and `context.Context` cancellation pattern.
- Give one goroutine ownership of connection state or protect transitions explicitly.
- Stop read loops and retry timers when the context is canceled.
- Bound deduplication storage and avoid goroutine leaks during repeated discovery.
## Rust
- Match the project's existing async runtime; do not add a second runtime solely for WebSockets.
- Model connection state with enums and use cancellation/drop semantics consistently.
- Avoid holding locks while awaiting socket operations or backoff timers.
- Keep secret values out of `Debug` output and error contexts.
## C++ and Unreal Engine
- Prefer the engine/framework WebSocket module already enabled by the project.
- Bind callbacks with lifetime-safe weak references and unbind on shutdown.
- Dispatch gameplay and UI work to the game thread.
- Keep discovery/reconnect logic out of tick functions and prevent stale callbacks from previous sockets.
## Other stacks
For any other runtime, map the same responsibilities:
| Protocol concern | Runtime capability needed |
| --- | --- |
| Port discovery | Cancellable bounded-concurrency batches with short connect/hello deadlines |
| Hello validation | Text frame reception, JSON parsing, deadline |
| Authentication | Ordered text send after validation |
| Event loop | Long-lived receive callback/stream/task |
| Native heartbeat | Standards-compliant WebSocket ping/pong |
| Reconnect | Cancellation-aware timer with backoff and jitter |
| App integration | Safe thread/executor/lifecycle handoff |
| Secret handling | Runtime configuration or OS/project secret store |
If the runtime cannot meet one of these requirements, surface the limitation before implementation rather than weakening the protocol.
---
https://raw.githubusercontent.com/liangpeiran-bit/tiktok-live-studio-local-data-access/main/.agents/skills/tiktok-live-studio-local-data-access/references/verification.md.agents/skills/tiktok-live-studio-local-data-access/references/verification.md
# Verification checklist
Use the project's existing test framework and commands. A mock WebSocket server should emulate the protocol without using real credentials.
## Automated cases
At minimum, verify:
- Discovery skips connection failures, timeouts, non-JSON first messages, and invalid hello identity fields.
- Credentials are never sent to an endpoint with an invalid hello.
- `AUTH` is the first client JSON message after a valid hello.
- Events are not delivered to application handlers before `AUTH_RESULT.success=true`.
- Each documented auth error reaches the intended retry or intervention branch.
- `live.like`, `live.gift`, and `live.chat` preserve documented field types.
- Gift rules match by the string `gift.id`; same-name IDs remain distinguishable and unknown IDs take the intended fallback path.
- Combo-sensitive effects do not replay a cumulative count on every update, and per-group state is cleared at `repeat_end=true`.
- Missing `user` and missing optional user fields are accepted.
- Unknown events and unknown gift type values do not close the connection.
- Duplicate `{event}:{message_id}` values are suppressed within the cache window.
- Chat content is rendered or forwarded as plain text, not executable markup.
- A malformed event is isolated without killing the receive loop.
- Socket close causes a fresh discovery and authentication cycle.
- Repeated failures use backoff rather than a tight loop.
- Reason `510` stops automatic retry pending intervention.
- Shutdown cancels discovery, receive work, active sockets, and retry timers.
- Starting twice does not create two active connections.
## Security review
Search the changed files and test snapshots for:
- real or placeholder-like production credentials;
- logging of AUTH payloads, secrets, or configuration objects containing secrets;
- secrets embedded in browser bundles, checked-in config, URLs, query strings, telemetry, or exception text;
- credentials sent before exact hello validation;
- a remote proxy, non-loopback binding, or advice to expose the service to a network.
## Quality commands
Run the narrowest relevant commands first, followed by the project's normal build/type-check/lint/test commands in proportion to the change. Use the repository's required package manager and task runner.
Do not claim that a build or test passed unless its command completed successfully.
## Optional live smoke test
Run only when TikTok LIVE Studio and approved credentials are available on the same machine.
1. Supply credentials through the project's secure runtime mechanism.
2. Start the client and confirm it finds a valid hello.
3. Confirm successful authentication without printing credentials.
4. Trigger one enabled event and confirm exactly one application action.
5. Stop/restart the local service and confirm rediscovery plus reauthentication.
6. Remove credentials and diagnostic artifacts after the test when appropriate.
Record whether testing was mock-only or included a live smoke test.