npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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.

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 24

Default 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 login prints 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 at https://trends.tvbs.ai/account or with tvbs-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 "颱風,地震" --pretty

Notes for AI agents

  • Default stdout is the raw Envelope. Read meta.staleness_seconds to judge freshness, meta.is_new_reliable before trusting isNew, and meta.warnings for 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 opportunities when the question is "is this a news opportunity / did TVBS cover it"; use trending for raw surging searches only.
  • Use topic for "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 empty tvbs_similar_news means TVBS has not covered it, and isNew is null (use opportunities for new-vs-seen).
  • Use momentum for "is X rising or cooling". It compares the first and last points of the interest series against data.threshold_pct. --geo defaults to TW; 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).