YouTube Scraper API

# Integrate HasData YouTube API

## Task

Implement only the YouTube workflow the user requests: transcripts, video metadata, channel content, or keyword search.
If no workflow is specified, ask which one before implementing. Add other endpoints only when the requested workflow needs them.
Inspect project instructions, the server-side runtime, existing HTTP client, and tests first.
Follow project conventions and preserve unrelated code. No new SDK is required.
Use the REST API; do not substitute an MCP connection or a custom scraper.

## References

Read the documentation for each endpoint needed by the requested workflow:

- Transcript: https://docs.hasdata.com/apis/youtube/transcript.md
- Video: https://docs.hasdata.com/apis/youtube/video.md
- Channel: https://docs.hasdata.com/apis/youtube/channel.md
- Search: https://docs.hasdata.com/apis/youtube/search.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 relevant endpoint references. 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.

## Endpoint selection

All four endpoints use GET under `https://api.hasdata.com/scrape/youtube/`.

- Transcript: `transcript`, required `v` (11-character video ID), optional `languageCode` and `type=asr`. Choose an available caption track; preserve the exact returned language code. Omission of `languageCode` selects the default track. Use `type=asr` for an auto-generated track; omit it for a human-authored track when one exists. Captions and requested languages are not guaranteed.
- Video: `video`, required `v`, optional `gl`, `hl`, `deviceType`.
- Channel: `channel`, required `channelId` (canonical ID or @handle), optional `tab`, `gl`, `hl`, `deviceType`, `paginationToken`. The default `featured` tab returns Home-page content; other tabs have different shapes. Use only the requested tab.
- Search: `search`, required `q`, optional `gl`, `hl`, `deviceType`, `sortBy`, `date`, `videoType`, `length`, `filters[]`, `paginationToken`. Read current allowed values. `videoType` supports video, shorts, channel, playlist, and movie. A supplied raw `sp` token overrides structured sort and filter parameters.

## Implementation

- Encode query parameters correctly and preserve the returned JSON.
- For transcripts, retain `transcript[].snippet`, `startMs`, `endMs`, and `startTimeText`. Offsets are milliseconds; convert explicitly when generating video links. Preserve `availableTranscripts`, including optional track `type`.
- For video metadata, `description` is an object with `content` and `links`. Use numeric `extractedViews` and `extractedLikes` for calculations while retaining display strings.
- For channel Home content, preserve `channelInfo`, `featuredVideo`, and `sections` when present. Numeric subscriber and video counts can originate from rounded display labels.
- For search, preserve distinct result blocks. `shortsResults[].shorts[]` contains Shorts within shelves; result types are optional. `videoResults[].views` is numeric, and `positionOnPage` belongs to the returned page. Search views are video views, not keyword search volume.
- Follow returned pagination only within a user-requested page limit. Do not silently crawl entire channels or result sets.
- Treat missing optional fields as unknown. Do not infer comment text, audience demographics, unique viewers, revenue, or transcript translations.
- Handle timeouts, documented errors, unavailable videos, missing caption tracks, empty results, and missing optional blocks.
- Keep requests server-side. If no suitable runtime exists, discuss options before changing architecture.

## Credentials

- Implement the integration and mocked tests without requiring a live API key.
- Read `HASDATA_API_KEY` from the 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 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, result URLs, or redirects to another origin.

## Verification

- Add mocked tests for the selected workflow: success, unavailable or empty data, missing optional blocks, and errors. Check endpoint-specific shapes, timestamp units, and pagination limits where relevant.
- Include a usage example and run local checks.
- Only with user authorization and a configured key, make one live verification request for the selected workflow and agreed input. Successful requests consume credits.
- Validate HTTP status, documented API status, and response structure. Empty results can be valid.
- Do not automatically repeat paid requests to obtain nonempty results or test every endpoint.
- Report changed files, setup commands, and test results. State separately whether live verification passed, failed, or was skipped.
- Ask before deploying.