trendsearch 0.0.1 → 0.1.0

package/README.md

@@ -11,17 +11,46 @@ Modern Google Trends SDK for Node.js and Bun, built with native `fetch`, strict
 - 🛡️ Built-in retry/backoff + rate limiting (`p-retry` + `p-queue`)
 - 🍪 Optional cookie persistence support
 - 🖥️ First-class `trendsearch` CLI for every endpoint
-- 🌐 Stable Google Trends API endpoints + experimental RPC/picker endpoints
+- 🌐 Stable Google Trends API endpoints + experimental RPC/picker/CSV/top charts endpoints
 - 🧪 Deterministic fixture contracts + optional live endpoint tests
 
 ## 📦 Install
 
+### Install as a library dependency
+
 ```bash
 bun add trendsearch
-# or
 npm install trendsearch
+pnpm add trendsearch
+yarn add trendsearch
+```
+
+### Run the CLI without installing globally (always latest)
+
+```bash
+npx trendsearch@latest --help
+pnpm dlx trendsearch@latest --help
+yarn dlx trendsearch@latest --help
+bunx trendsearch@latest --help
+```
+
+### Install the CLI globally (`@latest`)
+
+Use `@latest` so your global binary is always installed from the newest published version.
+
+```bash
+npm install --global trendsearch@latest
+pnpm add --global trendsearch@latest
+bun add --global trendsearch@latest
+yarn global add trendsearch@latest
 ```
 
+For Yarn Berry/Modern, prefer `yarn dlx trendsearch@latest` (shown above) instead of global install.
+
+### Update an existing global install to latest
+
+Re-run your package manager's global install command with `@latest`.
+
 ## ✅ Runtime Contract
 
 - 🟢 Node.js `>=20`
@@ -35,7 +64,9 @@ If you are in a CJS project, use dynamic import:
 const trendsearch = await import("trendsearch");
 ```
 
-## 🚀 Quick Start
+## 🚀 Library Usage Guide
+
+### 1) Quick start with endpoint helpers
 
 ```ts
 import { interestOverTime } from "trendsearch";
@@ -49,17 +80,70 @@ const result = await interestOverTime({
 console.log(result.data.timeline.length);
 ```
 
-## 🖥️ CLI
+### 2) Reuse shared defaults with `createClient`
+
+```ts
+import { createClient } from "trendsearch";
+
+const client = createClient({
+  hl: "en-US",
+  tz: 0,
+  timeoutMs: 15_000,
+});
+
+const result = await client.relatedQueries({
+  keywords: ["typescript"],
+  geo: "US",
+});
+
+console.log(result.data.top.length);
+```
+
+### 3) Use exported schemas/types when you need stricter boundaries
+
+```ts
+import { schemas, type ExploreRequest } from "trendsearch";
+
+const request: ExploreRequest = {
+  keywords: ["typescript", "javascript"],
+  geo: "US",
+};
+
+const validated = schemas.exploreRequestSchema.parse(request);
+```
+
+## 🖥️ CLI Usage Guide
 
 `trendsearch` ships with a production-ready CLI that wraps all stable and
 experimental endpoints.
 
+### 1) Start with help
+
+```bash
+trendsearch --help
+trendsearch explore --help
+```
+
+### 2) Run common endpoint commands
+
 ```bash
 trendsearch autocomplete typescript --output json
 trendsearch explore typescript --geo US --time "today 3-m" --output pretty
+trendsearch interest-over-time typescript --geo US --time "today 3-m"
+trendsearch related-queries typescript --geo US --time "today 12-m"
 trendsearch experimental trending-now --geo US --language en --hours 24
 ```
 
+### 3) Pass request payloads with `--input`
+
+`--input` accepts inline JSON, a JSON file path, or `-` for stdin.
+
+```bash
+trendsearch explore --input '{"keywords":["typescript"],"geo":"US"}' --output json
+trendsearch explore --input ./requests/explore.json --output json
+cat ./requests/explore.json | trendsearch explore --input - --output json
+```
+
 ### CLI Output Modes
 
 - `--output pretty` (human-friendly, default in TTY)
@@ -97,13 +181,17 @@ Error envelope (`json`/`jsonl`):
 }
 ```
 
-### CLI Config / Wizard / Completion
+### 4) Persist defaults, use wizard, and generate completion
 
 ```bash
 trendsearch config set output json
+trendsearch config set hl en-US
+trendsearch config get output
 trendsearch config list
+trendsearch config unset hl
+trendsearch config reset
 trendsearch wizard
-trendsearch completion bash
+trendsearch completion zsh
 ```
 
 Config precedence:
@@ -113,6 +201,7 @@ Config precedence:
 Supported env vars include:
 
 - `TRENDSEARCH_OUTPUT`
+- `TRENDSEARCH_SPINNER`
 - `TRENDSEARCH_HL`
 - `TRENDSEARCH_TZ`
 - `TRENDSEARCH_BASE_URL`
@@ -123,6 +212,7 @@ Supported env vars include:
 - `TRENDSEARCH_MAX_CONCURRENT`
 - `TRENDSEARCH_MIN_DELAY_MS`
 - `TRENDSEARCH_USER_AGENT`
+- `TRENDSEARCH_CONFIG_DIR` (override where persisted CLI config is stored)
 
 ## 🧭 API Surface
 
@@ -145,11 +235,54 @@ Supported env vars include:
 - `experimental.trendingArticles`
 - `experimental.geoPicker`
 - `experimental.categoryPicker`
+- `experimental.topCharts`
+- `experimental.interestOverTimeMultirange`
+- `experimental.interestOverTimeCsv`
+- `experimental.interestOverTimeMultirangeCsv`
+- `experimental.interestByRegionCsv`
+- `experimental.relatedQueriesCsv`
+- `experimental.relatedTopicsCsv`
+- `experimental.hotTrendsLegacy`
 
 ⚠️ Experimental endpoints are semver-minor unstable because Google can change internal RPC payloads.
 
 ℹ️ `dailyTrends` and `realTimeTrends` are kept for compatibility and may throw `EndpointUnavailableError` if Google retires those legacy routes.
 
+### Operational Caveats (Important)
+
+- Internal/undocumented Google Trends routes can throttle aggressively (`HTTP 429`) even at low request volume.
+- Some route families can intermittently fail with `HTTP 400`, `401`, `404`, or `410` depending on backend changes.
+- For production use, keep concurrency low, cache aggressively, and use longer backoff windows.
+- Prefer the official Google Trends API (alpha) when available for long-lived production integrations.
+- Related data endpoints can validly return empty lists for some keywords/time windows.
+
+### Reducing `429` in Practice
+
+`trendsearch` automatically retries on `429`, and when Google sends a `Retry-After` header,
+the client respects that wait window before retrying.
+
+Recommended profile for unstable/internal routes:
+
+```ts
+import { MemoryCookieStore, createClient } from "trendsearch";
+
+const client = createClient({
+  timeoutMs: 30_000,
+  retries: {
+    maxRetries: 5,
+    baseDelayMs: 2_500,
+    maxDelayMs: 45_000,
+  },
+  rateLimit: {
+    maxConcurrent: 1,
+    minDelayMs: 5_000,
+  },
+  userAgent:
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36",
+  cookieStore: new MemoryCookieStore(),
+});
+```
+
 ## 🧰 Client Configuration
 
 Use `createClient` when you want shared runtime defaults and transport controls:
@@ -314,6 +447,7 @@ Output:
 - `data.top`
 - `data.rising`
 - `value` can be `number | string` (`"Breakout"`-style upstream values are preserved)
+- `data.top` and `data.rising` may be empty arrays for some requests
 
 ### `relatedTopics`
 
@@ -333,6 +467,7 @@ Output:
 
 - `data.top`
 - `data.rising`
+- `data.top` and `data.rising` may be empty arrays for some requests
 
 ### `dailyTrends`
 
@@ -429,6 +564,60 @@ const result = await experimental.categoryPicker({ hl: "en-US" });
 console.log(result.data.items);
 ```
 
+### `experimental.topCharts`
+
+```ts
+import { experimental } from "trendsearch";
+
+const result = await experimental.topCharts({
+  date: 2024,
+  geo: "GLOBAL",
+});
+
+console.log(result.data.charts);
+console.log(result.data.items);
+```
+
+### `experimental.interestOverTimeMultirange`
+
+```ts
+import { experimental } from "trendsearch";
+
+const result = await experimental.interestOverTimeMultirange({
+  keywords: ["typescript"],
+  geo: "US",
+  time: "today 3-m",
+});
+
+console.log(result.data.timeline);
+```
+
+### CSV Variants (`experimental.*Csv`)
+
+```ts
+import { experimental } from "trendsearch";
+
+const result = await experimental.relatedQueriesCsv({
+  keywords: ["typescript"],
+  geo: "US",
+});
+
+console.log(result.data.csv);
+```
+
+`experimental.interestOverTimeCsv`, `experimental.interestOverTimeMultirangeCsv`,
+`experimental.interestByRegionCsv`, `experimental.relatedQueriesCsv`, and
+`experimental.relatedTopicsCsv` currently return raw CSV text (`data.csv`) in v1.
+
+### `experimental.hotTrendsLegacy`
+
+```ts
+import { experimental } from "trendsearch";
+
+const result = await experimental.hotTrendsLegacy();
+console.log(result.data.payload);
+```
+
 ## 🧾 Schemas and Types
 
 All request/response schemas and inferred types are exported:
@@ -474,6 +663,7 @@ try {
 } catch (error) {
   if (error instanceof RateLimitError) {
     console.error("Rate limited:", error.status);
+    console.error("Retry after ms:", error.retryAfterMs);
   }
 
   if (error instanceof SchemaValidationError) {
@@ -497,6 +687,11 @@ bun run test:all
 TRENDSEARCH_LIVE=1 bun run test:live
 ```
 
+Live test notes:
+
+- The live suite is intentionally slower (conservative pacing) to reduce `429`.
+- Experimental routes are best-effort and can be unavailable depending on backend state.
+
 Package checks:
 
 ```bash

package/dist/cli.d.mts

@@ -1,4 +1,4 @@
-import { a as TrendSearchClient, n as CreateClientConfig } from "./public-types-B6pmbT6Z.mjs";
+import { a as TrendSearchClient, n as CreateClientConfig } from "./public-types-CroPK1QN.mjs";
 import { Command } from "commander";
 
 //#region src/cli/output.d.ts

package/dist/cli.mjs

@@ -1,4 +1,4 @@
-import { a as UnexpectedResponseError, c as RateLimitError, l as EndpointUnavailableError, n as schemas, o as TransportError, r as pickerRequestSchema, s as SchemaValidationError, t as createClient } from "./create-client-B1euQ5Of.mjs";
+import { a as UnexpectedResponseError, c as RateLimitError, l as EndpointUnavailableError, n as schemas, o as TransportError, r as pickerRequestSchema, s as SchemaValidationError, t as createClient } from "./create-client-BQ8bZmFn.mjs";
 import { Command, CommanderError, Option } from "commander";
 import Conf from "conf";
 import { existsSync } from "node:fs";
@@ -177,7 +177,8 @@ const fromUnknownError = (error) => {
 		message: error.message,
 		details: {
 			status: error.status,
-			url: error.url
+			url: error.url,
+			retryAfterMs: error.retryAfterMs
 		},
 		exitCode: EXIT_CODES.rateLimited
 	};
@@ -448,6 +449,17 @@ const readNumber = (value) => {
 	const parsed = Number(value);
 	return Number.isFinite(parsed) ? parsed : void 0;
 };
+const readDateLike = (value) => {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value !== "string") return;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return;
+	if (/^\d+$/.test(trimmed)) {
+		const parsed = Number(trimmed);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	return trimmed;
+};
 const asRequest = (value) => value;
 const readString = (value) => typeof value === "string" && value.length > 0 ? value : void 0;
 const withGeo = (values) => {
@@ -735,6 +747,141 @@ const endpointManifest = [
 		}),
 		invoke: (client, request, debug) => client.trendingArticles(asRequest(request), debug)
 	},
+	{
+		id: "experimental.topCharts",
+		path: ["experimental", "top-charts"],
+		summary: "Fetch experimental top charts data.",
+		requestSchema: schemas.topChartsRequestSchema,
+		options: [
+			{
+				key: "geo",
+				flags: "--geo <geo>",
+				description: "Geo code.",
+				type: "string"
+			},
+			{
+				key: "date",
+				flags: "--date <date>",
+				description: "Date or year.",
+				type: "string"
+			},
+			{
+				key: "isMobile",
+				flags: "--is-mobile",
+				description: "Enable mobile mode.",
+				type: "boolean"
+			}
+		],
+		args: [],
+		buildRequest: (ctx) => ({
+			geo: readString(ctx.options.geo),
+			date: readDateLike(ctx.options.date),
+			isMobile: ctx.options.isMobile === true ? true : void 0
+		}),
+		invoke: (client, request, debug) => client.experimental.topCharts(asRequest(request), debug)
+	},
+	{
+		id: "experimental.interestOverTimeMultirange",
+		path: ["experimental", "interest-over-time-multirange"],
+		summary: "Fetch experimental interest over time (multirange).",
+		requestSchema: schemas.interestOverTimeMultirangeRequestSchema,
+		options: exploreLikeOptions,
+		args: [{
+			label: "[keywords...]",
+			description: "Keyword list."
+		}],
+		buildRequest: buildExploreLikeRequest,
+		invoke: (client, request, debug) => client.experimental.interestOverTimeMultirange(asRequest(request), debug)
+	},
+	{
+		id: "experimental.interestOverTimeCsv",
+		path: ["experimental", "interest-over-time-csv"],
+		summary: "Fetch experimental interest over time CSV.",
+		requestSchema: schemas.interestOverTimeRequestSchema,
+		options: exploreLikeOptions,
+		args: [{
+			label: "[keywords...]",
+			description: "Keyword list."
+		}],
+		buildRequest: buildExploreLikeRequest,
+		invoke: (client, request, debug) => client.experimental.interestOverTimeCsv(asRequest(request), debug)
+	},
+	{
+		id: "experimental.interestOverTimeMultirangeCsv",
+		path: ["experimental", "interest-over-time-multirange-csv"],
+		summary: "Fetch experimental interest over time multirange CSV.",
+		requestSchema: schemas.interestOverTimeMultirangeRequestSchema,
+		options: exploreLikeOptions,
+		args: [{
+			label: "[keywords...]",
+			description: "Keyword list."
+		}],
+		buildRequest: buildExploreLikeRequest,
+		invoke: (client, request, debug) => client.experimental.interestOverTimeMultirangeCsv(asRequest(request), debug)
+	},
+	{
+		id: "experimental.interestByRegionCsv",
+		path: ["experimental", "interest-by-region-csv"],
+		summary: "Fetch experimental interest by region CSV.",
+		requestSchema: schemas.interestByRegionRequestSchema,
+		options: [...exploreLikeOptions, {
+			key: "resolution",
+			flags: "--resolution <resolution>",
+			description: "Geo resolution (COUNTRY, REGION, CITY, DMA).",
+			type: "string",
+			choices: [
+				"COUNTRY",
+				"REGION",
+				"CITY",
+				"DMA"
+			]
+		}],
+		args: [{
+			label: "[keywords...]",
+			description: "Keyword list."
+		}],
+		buildRequest: (ctx) => ({
+			...buildExploreLikeRequest(ctx),
+			resolution: readString(ctx.options.resolution)
+		}),
+		invoke: (client, request, debug) => client.experimental.interestByRegionCsv(asRequest(request), debug)
+	},
+	{
+		id: "experimental.relatedQueriesCsv",
+		path: ["experimental", "related-queries-csv"],
+		summary: "Fetch experimental related queries CSV.",
+		requestSchema: schemas.relatedQueriesRequestSchema,
+		options: exploreLikeOptions,
+		args: [{
+			label: "[keywords...]",
+			description: "Keyword list."
+		}],
+		buildRequest: buildExploreLikeRequest,
+		invoke: (client, request, debug) => client.experimental.relatedQueriesCsv(asRequest(request), debug)
+	},
+	{
+		id: "experimental.relatedTopicsCsv",
+		path: ["experimental", "related-topics-csv"],
+		summary: "Fetch experimental related topics CSV.",
+		requestSchema: schemas.relatedTopicsRequestSchema,
+		options: exploreLikeOptions,
+		args: [{
+			label: "[keywords...]",
+			description: "Keyword list."
+		}],
+		buildRequest: buildExploreLikeRequest,
+		invoke: (client, request, debug) => client.experimental.relatedTopicsCsv(asRequest(request), debug)
+	},
+	{
+		id: "experimental.hotTrendsLegacy",
+		path: ["experimental", "hot-trends-legacy"],
+		summary: "Fetch legacy hot trends endpoint payload.",
+		requestSchema: schemas.hotTrendsLegacyRequestSchema,
+		options: [],
+		args: [],
+		buildRequest: () => ({}),
+		invoke: (client, request, debug) => client.experimental.hotTrendsLegacy(asRequest(request), debug)
+	},
 	{
 		id: "experimental.trendingNow",
 		path: ["experimental", "trending-now"],