TikTok Scraper API

# Integrate HasData TikTok Scraper API

## Task

Add the requested public-video discovery, account-post collection, or user-search workflow to this project using HasData TikTok Scraper API.
Inspect project instructions, the server-side runtime, existing HTTP client, and tests first.
Follow the project's conventions and preserve unrelated code. No new SDK is required.
Implement only the requested workflow. If the workflow is unclear, ask whether the user needs keyword video search, user search, account posts, or a specified combination.
Keep the integration as REST API calls; do not replace it with an MCP connection or a custom TikTok scraper.

## References

Read the endpoint documentation before implementing:

- Keyword video or user search: https://docs.hasdata.com/apis/tiktok/search.md
- Account posts: https://docs.hasdata.com/apis/tiktok/posts.md
- Error handling: https://docs.hasdata.com/api-codes.md
- Documentation index: https://docs.hasdata.com/llms.txt
- Full documentation (fallback): https://docs.hasdata.com/llms-full.txt

Start with the endpoint reference. Use `llms.txt` to find additional pages.
Use `llms-full.txt` only when needed; extract relevant sections instead of loading everything into context.
If a `.md` reference is unavailable, try its HTML URL without `.md`.
If it is still unavailable, ask for the missing documentation rather than guessing.

## Optional agent skill

If the official `hasdata` skill is already available, use its relevant guidance.
Otherwise, if this agent supports skills, ask before installing it in this project:

```sh
npx skills add hasdata/agent-skills --skill hasdata
```

Run from the project directory and select the coding agent in use.
The `hasdata-cli` skill is not required. If installation is declined or unsupported, continue with the docs.
Flag conflicts between skill guidance and current API docs rather than guessing.

## Implementation

- For keyword discovery, use `GET https://api.hasdata.com/scrape/tiktok/search` with required `keyword`. Use the documented `type=video` or `type=user` when mode selection is needed; video is the default.
- For account videos, use `GET https://api.hasdata.com/scrape/tiktok/posts` with required `handle`, with or without `@`. Implement only the modes the user requested.
- Encode query parameters with the project HTTP client. A literal hashtag must reach the API as part of `keyword`, not as a URL fragment. Exact hashtag matching is application filtering.
- Preserve the response modes: video search uses `videos`, account retrieval uses `posts`, and user search uses `users`. Do not assume all modes have the same record shape.
- Keep account, video, and sound IDs as strings. Handle absent captions, hashtags, mentions, music, and optional media URLs.
- For requested pagination, pass the returned `pagination.nextPageToken` as `nextPageToken` for the same query and mode when `pagination.hasMore` is true. Treat tokens as opaque strings and deduplicate by record ID. Do not invent offsets or automatically fetch all pages.
- Keep plays, likes, comment counts, shares, and saves distinct. Comment counts do not include comment text. Do not label plays as unique reach or infer conversions.
- Campaign selection, engagement formulas, publication calendars, sound grouping, scheduling, and historical comparisons belong to application code. Save query context and observation times when comparing results.
- Sound titles can repeat across distinct sound IDs. Attribution and returned media URLs do not grant reuse rights; signed media URLs may expire.
- Profile and posts links on search authors are separate API requests. Do not expand them automatically. Returned pages are not guaranteed exhaustive archives or platform-wide trend measurements.
- Handle timeouts and documented errors before reading data. Keep requests server-side. If no suitable runtime exists, discuss options before changing the architecture.

## Credentials

- Implement the integration and mocked tests without requiring a live API key.
- Read `HASDATA_API_KEY` from the project's existing environment or secret store and send it as `x-api-key`.
- If the key is missing before live verification, ask the user to configure it from https://app.hasdata.com/api-keys.
- Never ask the user to paste the key into chat. Check only that it is configured, without printing its value.
- Never put the key in browser code, logs, or version control. Add only a placeholder to the project's example configuration.
- If using a local `.env` file, make sure it is gitignored.
- Send the key only to `https://api.hasdata.com`. Never forward it to documentation, TikTok, media links, bio links, or redirects to another origin.

## Verification

- Add mocked tests for query encoding, mode-specific response parsing, pagination context, duplicate IDs, success, empty results, missing fields, timeouts, and errors. Include a literal hashtag and a terminal page without a continuation token. Include a usage example and run local checks.
- With a configured key and explicit user approval, including approval already given for this task, make one live verification request with agreed inputs. A successful TikTok request consumes 10 credits.
- Verify one requested endpoint and mode only; cover the remaining modes with mocked tests.
- Validate the HTTP status, documented API status, and response structure. An empty result set can be valid.
- Do not automatically repeat paid requests to obtain a nonempty response or follow pagination during this check.
- Report changed files, setup commands, and test results. State separately whether live verification passed, failed, or was skipped.
- Ask before deploying.