@tvbs-ai/tvbs-trends
v0.3.0
Published
CLI for the TVBS Trends API — surging Google Trends analysed against TVBS news coverage. Thin wrapper over the v2 REST API; designed for AI agents and terminals.
Maintainers
Readme
@tvbs-ai/tvbs-trends
CLI for the TVBS Trends API — surging Google Trends analysed against TVBS news coverage. A thin, zero-dependency wrapper over the v2 REST API, designed for AI agents (single npx call, JSON on stdout) and for people in a terminal (--pretty tables).
Quick start
npx -y @tvbs-ai/tvbs-trends auth login # sign in once with your TVBS account
npx -y @tvbs-ai/tvbs-trends opportunities --geo TW --window-hours 24Default output is the raw API response (an Envelope { meta, data }) as JSON on stdout — ready for an agent to parse. Add --pretty for a human-readable table.
Auth
Every call needs a credential, sent as X-API-Key. Two kinds work:
- Personal token (recommended) —
tvbs-trends auth loginprints a link and a code. Open the link, sign in with your TVBS account, check the code matches, and press 允許. The CLI saves your token to$XDG_CONFIG_HOME/tvbs-trends/token(default~/.config/tvbs-trends/token, mode 600 on macOS/Linux); it is never printed. Tokens expire after 90 days; revoke one any time athttps://trends.tvbs.ai/accountor withtvbs-trends auth logout. Every token is re-checked daily, so an account that is deleted, banned or locked in the company sign-in (Clerk) loses access within a day. - Team API key — for servers and automation, from the AI department. Set
TVBS_TRENDS_API_KEY.
Precedence: --api-key, then TVBS_TRENDS_API_KEY, then the token saved for that server. A saved token is only ever sent to the server that issued it; TVBS_TRENDS_API_KEY is only sent to TVBS servers (*.tvbs.ai) and localhost — anywhere else needs an explicit --api-key. --base-url must be just an https:// origin (plain http only for localhost), and redirects are never followed. No credential / wrong credential → HTTP 401 and a non-zero exit code. Never commit a credential.
| Command | What it does |
|---------|--------------|
| auth login | Sign in and save a personal token. Waits up to 10 minutes for approval; does nothing if already signed in. |
| auth login --no-wait | Print the link and code, then exit; run auth login again to finish. |
| auth login --name <label> | How this connection is labelled on the approval page. |
| auth login --force | Sign in again even if the saved token works; the old one is revoked. |
| auth status | Which credential is in use, and whose it is. |
| auth logout | Revoke the saved token on the server and delete it. |
AI agents: run auth login --no-wait, show the person the link and the code from the JSON output, ask them to approve it, then run auth login to finish. Never ask the person to paste a token into the chat — the login flow exists so that it never passes through the conversation.
Commands
The v2 API splits routes by data source, so the cost of a call is visible from its name — live/* scrapes Google (slow, rate-limited), snapshots/* reads the database (fast), and opportunities/topic/digest combine both.
| Command | Endpoint | Cost | Purpose |
|---------|----------|------|---------|
| trending | live/trending | slow (scrape) | Current surging keywords |
| interest | live/interest | slow (scrape) | Keyword search-interest time series |
| momentum | live/momentum | slow (scrape) | Rising / stable / falling interest per keyword (volume only, not sentiment) |
| latest | snapshots/latest | fast (DB) | Most recent stored snapshot |
| snapshot | snapshots | fast (DB) | Nearest snapshot before a timestamp |
| timeline | snapshots/timeline | fast (DB) | One keyword's volume trajectory |
| opportunities | opportunities | slow (hybrid) | News opportunities: scoop / follow-up |
| topic | topic | slow (hybrid) | Surging trends matching a topic, flagged with TVBS coverage |
| digest | digest | slow (hybrid) | Opportunities as a ready-to-send newsroom notification |
Run tvbs-trends <command> --help for per-command options. --window-hours accepts only 4, 24, or 48 (the windows the scheduler snapshots).
Global options
| Option | Description |
|--------|-------------|
| --pretty | Render a human-readable table instead of JSON |
| --api-key <key> | Team API key or personal token (overrides TVBS_TRENDS_API_KEY and the saved token) |
| --base-url <url> | API base URL (default: https://trends.tvbs.ai) |
| -h, --help | Show help |
Examples
# Today's news opportunities as JSON, piped to jq
tvbs-trends opportunities --window-hours 24 --num-trends 5 | jq '.data[].keyword'
# A ready-to-send newsroom digest, plain text
tvbs-trends digest --window-hours 24 --format plain --pretty
# Fast latest snapshot (no scraping cost), human table
tvbs-trends latest --geo TW --window-hours 24 --pretty
# One keyword's trajectory over stored snapshots
tvbs-trends timeline --keyword 颱風 --window-hours 24
# Entertainment trends TVBS has not covered yet (story picking)
tvbs-trends topic --topic 娛樂 --only-uncovered --pretty
# Is a person or topic heating up or cooling down over the past week?
tvbs-trends momentum --keywords "颱風,地震" --prettyNotes for AI agents
- Default stdout is the raw Envelope. Read
meta.staleness_secondsto judge freshness,meta.is_new_reliablebefore trustingisNew, andmeta.warningsfor caveats. - Prefer
snapshots/*(latest,snapshot,timeline) when up-to-one-hour-stale data is acceptable — they are much faster and do not consume the scraping quota. - Use
opportunitieswhen the question is "is this a news opportunity / did TVBS cover it"; usetrendingfor raw surging searches only. - Use
topicfor "what is surging around X, and what haven't we written". The topic filter is approximate: a category name (娛樂,體育,政治,財經,科技,健康,天氣… or the English name, e.g.Sports) matches Google's topic category on each trend; any other word (e.g.AI, a celebrity name) is a substring match on the trend's keywords; an emptytvbs_similar_newsmeans TVBS has not covered it, andisNewisnull(useopportunitiesfor new-vs-seen). - Use
momentumfor "is X rising or cooling". It compares the first and last points of the interest series againstdata.threshold_pct.--geodefaults toTW; pass--geo ""for worldwide. It measures search volume only — it cannot tell whether coverage is positive or negative, so say so if asked about sentiment. - All commands are read-only.
Requirements
Node.js ≥ 18.3.0 (uses built-in fetch and util.parseArgs — the latter landed in 18.3; no runtime dependencies).
