askaipods 0.2.0 → 0.2.2

package/README.md

@@ -7,7 +7,7 @@ $ askaipods "what are people saying about test-time compute"
 
 # askaipods · "what are people saying about test-time compute"
 
-*Tier: anonymous · Results: 20 · Quota: 1/5 daily*
+*Tier: anonymous · Results: 20 · Quota: 1/10 daily*
 
 ## Results — newest first
 
@@ -83,7 +83,7 @@ askaipods "Anthropic safety research" --format json
 # Restrict to recent episodes only (anonymous tier caps --days at 90; member tier accepts any value)
 askaipods "GPU shortage" --days 90
 
-# Use a member-tier API key for 50/day instead of 5/day
+# Use a member-tier API key for 50/day instead of 10/day
 ASKAIPODS_API_KEY=pk_xxx askaipods "your query"
 askaipods "your query" --api-key pk_xxx
 ```
@@ -100,7 +100,7 @@ Your agent will recognize the trigger phrase, invoke `askaipods`, and present th
 
 | | Anonymous (default) | Member |
 |---|---|---|
-| **Daily quota** | 5 searches per IP | 50 searches per user |
+| **Daily quota** | 10 searches per IP | 50 searches per user |
 | **Results returned** | 20 (deterministic top 20, sorted newest-first) | 20 (deterministic top 20, sorted by relevance) |
 | **Text length** | Full text | Full text |
 | **Date precision** | Month only (`2025-10`) | Full date (`2025-10-15`) |
@@ -108,7 +108,7 @@ Your agent will recognize the trigger phrase, invoke `askaipods`, and present th
 | **Setup** | Nothing | `ASKAIPODS_API_KEY` env var |
 | **Sign up** | n/a | https://podlens.net |
 
-The anonymous tier exists so you can try the skill end-to-end with zero setup. Sign up for member access only when you outgrow the 5/day quota or need full dates and unlimited lookback.
+The anonymous tier exists so you can try the skill end-to-end with zero setup. Sign up for member access only when you outgrow the 10/day quota or need full dates and unlimited lookback.
 
 ## Honest limitations
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askaipods",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Search AI podcast quotes by topic — recent episode excerpts from Lex Fridman, Dwarkesh Patel, No Priors, Latent Space, and dozens more. Universal agentskills.io skill compatible with Claude Code, OpenAI Codex, Hermes Agent, OpenClaw, and any other agent that supports the open skill standard. Powered by podlens.net.",
   "type": "module",
   "bin": {

package/skill/askaipods/SKILL.md

@@ -2,7 +2,7 @@
 name: askaipods
 description: Search AI podcast quotes about a topic. Use whenever the user asks "what are people saying about X", "latest takes on Y", "find AI podcast quotes about Z", "who is discussing <model/concept>", or wants to know how AI researchers, founders, or VCs are publicly discussing any AI topic — even when they don't say "podcast". Returns recent excerpts from real episodes of Lex Fridman, Dwarkesh Patel, No Priors, Latent Space, and dozens more, sorted newest-first via the podlens.net semantic search API. Trigger eagerly on AI-research, ML-engineering, AI-investing, or AI-policy questions where real-human commentary beats a web search summary. Do not use for general web search, full transcript reading, or non-AI topics.
 license: MIT
-requirements: Node.js 18.3.0+ on PATH (the CLI uses `node:util.parseArgs`, which was added in 18.3.0), internet access to podlens.net. Optional ASKAIPODS_API_KEY env var unlocks the 50/day member tier with full dates and unlimited lookback; without it the skill works on the 5/day anonymous tier (per-IP, month-precision dates, `--days` capped at 90 when specified).
+requirements: Node.js 18.3.0+ on PATH (the CLI uses `node:util.parseArgs`, which was added in 18.3.0), internet access to podlens.net. Optional ASKAIPODS_API_KEY env var unlocks the 50/day member tier with full dates and unlimited lookback; without it the skill works on the 10/day anonymous tier (per-IP, month-precision dates, `--days` capped at 90 when specified).
 ---
 
 # askaipods — AI podcast quote search
@@ -21,6 +21,7 @@ Trigger eagerly. The Anthropic skill best-practices warn that models tend to **u
 - "Who is discussing <model / company / paper / concept>?"
 - "What are VCs / researchers / founders saying about <X>?"
 - "Has anyone on a podcast talked about <X>?"
+- "What does <person> think about <X>?" / "<人名>怎么看<X>?" — invoke even though the API does not return speaker attribution. The semantic search will still find quotes from episodes featuring that person; you just cannot confirm who in the episode said each line (see Honest limitations below).
 - Any AI-research, ML-engineering, AI-investing, AI-safety, or AI-policy question where the user would clearly benefit from real-human commentary (as opposed to a textbook summary or a web search snippet)
 
 You may invoke even when the user does not say "podcast" — if the question is about *what people think* on an AI topic, this skill is the right tool.
@@ -40,6 +41,8 @@ Run the bundled CLI and pass `--format json`. The flag matters because without i
 npx askaipods search "<USER QUERY>" --format json
 ```
 
+The `search` subcommand is optional — `npx askaipods "<USER QUERY>" --format json` works identically. Both forms are supported; use whichever reads better in context.
+
 The package is published on npm as `askaipods`, so `npx` will resolve it regardless of whether the user has it installed globally. If `npx` is unavailable in the host environment, the user can install globally once with `npm install -g askaipods` and the skill will run the same command.
 
 To restrict to recent episodes only, add `--days N`. When `--days` is passed, the API clamps the value to a maximum of 90 for anonymous tier (member tier accepts any value). When `--days` is omitted entirely, there is no time filter — the API returns all-time results.
@@ -48,6 +51,14 @@ To restrict to recent episodes only, add `--days N`. When `--days` is passed, th
 npx askaipods search "<USER QUERY>" --days 90 --format json
 ```
 
+To authenticate with a PodLens API key (member tier), pass `--api-key <key>` or set the `ASKAIPODS_API_KEY` environment variable. The flag takes priority over the env var when both are present.
+
+```bash
+npx askaipods search "<USER QUERY>" --api-key pk_abc123... --format json
+```
+
+The query must be 1–300 characters after trimming. Longer queries are rejected locally (exit code 1) before reaching the API.
+
 ### Time-intent mapping (important)
 
 When the user's query implies a time window, you MUST pass the appropriate `--days` value. Without it, the API returns all-time results regardless of recency words in the query.
@@ -95,6 +106,7 @@ Do NOT silently default every query to `--days 90` — omitting `--days` on broa
 Field notes that affect how you render:
 
 - **`tier`** — `member` if the user has a valid API key, `anonymous` otherwise. Drives the rendering branch below. On exit `0`, `tier` is always one of these two values — there is no third "unknown" path to handle (the CLI validates the upstream response and exits `3` if the value is missing or unexpected).
+- **`fetched_at`** — ISO-8601 timestamp set by the CLI at request time (not by the server). Use it for staleness: if the user asks about the same topic again later in the session, compare `fetched_at` against the current time to decide whether to re-query or reuse the cached output. A reasonable freshness threshold is ~30 minutes for time-sensitive queries and ~2 hours for broad research.
 - **`render_hint`** — `dual_view` for member, `single_view` for anonymous. Honor this. The reason: anonymous results are sorted by `published_at` desc (newest-first) by the API, so `api_rank` reflects temporal order, not semantic relevance. Showing a "Top Most Relevant" section for anonymous tier would mislead the user. Member results arrive in similarity order, so `api_rank` is meaningful for relevance-based views.
 - **`results[]`** — already sorted **newest first** by the CLI. Each result carries `api_rank` (1 = most semantically relevant in API order) so you can derive a "Top Relevant" sub-view without re-querying.
 - **`results[].podcast` / `episode` / `date`** — any of these may be `null` if the upstream record is incomplete. Render `Unknown podcast` / `Untitled episode` / `date unknown` rather than dropping the result. The CLI's own markdown renderer falls back the same way.
@@ -191,7 +203,7 @@ The CLI uses stable exit codes so you can branch on the failure mode:
 | Exit code | Meaning | What to tell the user |
 |---|---|---|
 | `0` | Success | Render the results normally |
-| `1` | Usage error / invalid arguments / API key rejected | Surface the stderr message verbatim — it will be a clear actionable error |
+| `1` | Usage error / invalid arguments / API key rejected | Surface the stderr message verbatim — it will be a clear actionable error. Common causes: query exceeds 300 characters (shorten it), empty query, or API key rejected by the server. |
 | `2` | Daily quota exhausted | Surface the CLI's stderr message verbatim — it is already tier-aware (distinct copy for member vs anonymous) and includes the correct reset time and upgrade path. |
 | `3` | Transient or unexpected failure (network error, rate-limit burst, service 503, protocol/shape error, or internal exception) | Retry once after a brief pause. If it fails again, surface the CLI's stderr message verbatim — it distinguishes "rate limited, retry in a minute" from "podlens.net temporarily unavailable" from "unexpected response shape" from internal exceptions, so the user sees the actionable detail. |
 

package/src/cli.js

@@ -14,7 +14,7 @@ import { parseArgs } from "node:util";
 import { search, AskaipodsError } from "./client.js";
 import { renderJson, renderMarkdown } from "./format.js";
 
-const VERSION = "0.2.0";
+const VERSION = "0.2.2";
 
 const HELP_TEXT = `askaipods ${VERSION} — search AI podcast quotes by topic
 
@@ -30,7 +30,7 @@ OPTIONS:
   -v, --version              Show version
 
 ENVIRONMENT:
-  ASKAIPODS_API_KEY          PodLens API key. Without it: 5 searches/day per IP (anonymous).
+  ASKAIPODS_API_KEY          PodLens API key. Without it: 10 searches/day per IP (anonymous).
                              With it: 50 searches/day per user (member).
                              Sign up at https://podlens.net to get one.
 

package/src/client.js

@@ -136,7 +136,7 @@ export async function search({ query, days, apiKey, endpoint = PODLENS_ENDPOINT
 
   const headers = {
     "Content-Type": "application/json",
-    "User-Agent": "askaipods/0.2.0 (+https://github.com/Delibread0601/askaipods)",
+    "User-Agent": "askaipods/0.2.2 (+https://github.com/Delibread0601/askaipods)",
   };
   if (apiKey) {
     headers["X-PodLens-API-Key"] = apiKey;
@@ -196,7 +196,7 @@ export async function search({ query, days, apiKey, endpoint = PODLENS_ENDPOINT
     if (msg.includes("quota")) {
       const quotaMsg = apiKey
         ? "daily search quota exhausted (member tier: 50/day). Quota resets at 00:00 UTC."
-        : "daily search quota exhausted (anonymous tier: 5/day). Quota resets at 00:00 UTC. " +
+        : "daily search quota exhausted (anonymous tier: 10/day). Quota resets at 00:00 UTC. " +
           "For 50 searches/day, set ASKAIPODS_API_KEY (sign up at https://podlens.net).";
       throw exitErr(2, quotaMsg);
     }