feat: Threads Keyword Search API — search by keyword and topic tag

[Copilot]

Integrates the official Threads Keyword Search API (GET /{user-id}/threads_keyword_search) as a new content source, enabling search of public Threads posts by keyword or topic tag with full parameter support.

API method

• ThreadsClient.keyword_search() — params: q, search_type (TOP/RECENT), search_mode (KEYWORD/TAG), media_type (TEXT/IMAGE/VIDEO), since/until, limit (1–100), author_username
• Input validation for all enum params, limit range, and auto-strips @ from username
• Requires threads_basic + threads_keyword_search permissions; 2,200 queries/24h rate limit

Pipeline integration

• _get_keyword_search_content() — selects best thread from search results (dedup via title history, blocked word filtering), fetches replies via Conversation API
• keyword_search added as content source in get_threads_posts() with fallback chain: keyword_search → trending → user

Config

New fields in [threads.thread]:

• source now accepts "keyword_search"
• search_query — the search term (required when source is keyword_search)
• search_type — TOP (default) or RECENT
• search_mode — KEYWORD (default) or TAG
• search_media_type — optional filter: TEXT, IMAGE, VIDEO

client = ThreadsClient()
results = client.keyword_search(
    q="viral trending",
    search_type="RECENT",
    search_mode="TAG",
    media_type="VIDEO",
    limit=25,
)

[Copilot]

Pull request overview

Adds support for the official Threads Keyword Search API as an additional content source, enabling the pipeline to fetch and build videos from public Threads posts discovered via keyword or topic tag search.

Changes:

• Introduces ThreadsClient.keyword_search() with parameter validation for enum fields, limit bounds, and author_username normalization.
• Adds a new keyword_search content source path (_get_keyword_search_content) and integrates it into get_threads_posts() with fallback to trending then user.
• Updates the config template to expose keyword_search source selection and related search parameters.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
utils/.config.template.toml	Adds keyword_search source option and config keys (search_query, search_type, search_mode, search_media_type).
threads/threads_client.py	Implements Keyword Search API client method and pipeline integration to select a thread + fetch replies, with fallback behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

_KEYWORD_SEARCH_RATE_LIMIT is declared but never used anywhere in the module. If you don’t plan to enforce/track quota client-side, consider removing this constant to avoid dead code; otherwise, wire it into a quota-check/logging mechanism so it stays accurate and discoverable.

Suggested change

	# Keyword search rate limit: 2,200 queries / 24 hours
	_KEYWORD_SEARCH_RATE_LIMIT = 2200

[Copilot]

The since/until parameters are typed as Optional[str], but the docstring says they can be Unix timestamps (ints) or strtotime-like strings, and also documents numeric constraints (e.g., >= 1688540400, comparisons with until). Either update the type hints to accept both (e.g., Union[int, str]) and validate when numeric, or adjust the docstring to avoid stating constraints that the method doesn’t enforce.

Suggested change

	since: Ngày bắt đầu (Unix timestamp hoặc chuỗi strtotime).
	Phải >= 1688540400 và < ``until``.
	until: Ngày kết thúc (Unix timestamp hoặc chuỗi strtotime).
	Phải <= thời điểm hiện tại và > ``since``.
	since: Mốc thời gian bắt đầu để lọc kết quả, truyền dưới dạng chuỗi
	và được gửi nguyên trạng tới API.
	until: Mốc thời gian kết thúc để lọc kết quả, truyền dưới dạng chuỗi
	và được gửi nguyên trạng tới API.

[Copilot]

If none of the search results pass the filtering criteria (non-empty text, not blocked, not a reply, title not used), the code falls back to results[0]. That can reintroduce blocked/duplicate/reply content and contradicts the earlier selection logic. Consider returning None here (to trigger the configured fallback chain) or only falling back to a result that still satisfies the filters.

Suggested change

	# results is guaranteed non-empty here (checked earlier)
	thread = results[0]
	print_substep(
	"⚠️ Không có thread nào phù hợp sau khi áp dụng bộ lọc Keyword Search.",
	style="bold yellow",
	)
	return None