askaipods 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askaipods",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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

@@ -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.
@@ -87,7 +98,8 @@ Do NOT silently default every query to `--days 90` — omitting `--days` on broa
     "total_returned": 20,
     "quota": { "used": 3, "limit": 50, "period": "daily" },
     "restrictions": null,
-    "query_hash": "..."
+    "query_hash": "...",
+    "window": { "requested_days": 7, "served_days": 30, "expanded": true, "reason_code": "expanded_on_empty_window" }
   }
 }
 ```
@@ -95,12 +107,14 @@ 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.
 - **`results[].date` format** — `YYYY-MM-DD` (or full ISO timestamp) for member tier; `YYYY-MM` only for anonymous tier (deliberately fuzzed by the API). Display whatever you got — don't guess a day.
 - **`meta.quota`** — passed through from the podlens.net API. Sub-fields like `used`, `limit`, `period` are reliably present; other sub-fields (e.g., a reset timestamp) may or may not appear depending on the server version. Treat all sub-fields as optional and degrade gracefully.
 - **`meta.restrictions`** — `null` for member tier; for anonymous tier, an object describing the cap (e.g., `{ max_results: 20, text_truncated: false, results_randomized: false, date_precision: "month", max_days: 90, order: "published_at_desc" }`). If non-null, the closing anonymous-tier note (templated below) is the right way to surface it; do not parse the object field-by-field.
+- **`meta.window`** — present when the API includes window expansion metadata (may be `null` for older server versions). When the user passes `--days` and the requested window has no results, the API automatically retries with wider windows (`[30, 60, 90]` days). The `window` object contains: `requested_days` (what was asked), `served_days` (what actually returned results), `expanded` (boolean — `true` when the window was widened), `reason_code` (`"expanded_on_empty_window"` when expanded), and optionally `truncated` (`true` when a fallback query errored mid-expansion). **When `expanded` is `true`**, tell the user: "No results in the requested N-day window; showing results from the last M days" (using `requested_days` and `served_days`). When `expanded` is `false` and results are empty, the API tried all available windows and genuinely found nothing.
 - **No speaker name and no episode URL.** The corpus is indexed at the key-point level without per-speaker attribution (the upstream pipeline intentionally avoids attributing quotes to individuals because automatic speaker diarization is unreliable). Episode URLs are also not exposed by the public API. Render `Podcast — Episode` only; do not fabricate "Dario said" if the text doesn't already attribute itself.
 
 ## How to render the response
@@ -191,11 +205,15 @@ 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. |
 
-If the `results` array is empty (zero matches above the similarity threshold), say so explicitly: "No quotes found for that topic. The corpus is AI-focused — for non-AI topics, try a web search instead. For AI topics, try rephrasing or broadening the query." Do not invent quotes to fill the gap.
+If the `results` array is empty (zero matches above the similarity threshold), check `meta.window` first:
+- If `meta.window.expanded` is `true`: the API already widened the search window (e.g., from 7 to 30 days) and still found nothing — tell the user: "No quotes found. The API expanded the search from N to M days but found no matches. Try rephrasing or broadening the query."
+- If `meta.window.truncated` is `true`: the expansion was interrupted by a transient error — tell the user to retry in a moment.
+- Otherwise (no expansion, or `meta.window` is `null`): say "No quotes found for that topic. The corpus is AI-focused — for non-AI topics, try a web search instead. For AI topics, try rephrasing or broadening the query."
+Do not invent quotes to fill the gap.
 
 Never silently swallow an error. Never fabricate quotes when the API returns nothing.
 

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.3";
 
 const HELP_TEXT = `askaipods ${VERSION} — search AI podcast quotes by topic
 

package/src/client.js

@@ -99,7 +99,8 @@ function isValidPublishedAt(v) {
 //
 // Optional (kept loose on purpose):
 //   data.meta.quota.period, data.meta.quota.next_reset,
-//   data.meta.query_hash, data.meta.restrictions, data.meta.cta
+//   data.meta.query_hash, data.meta.restrictions, data.meta.cta,
+//   data.meta.window
 function isValidSuccessEnvelope(data) {
   if (!isPlainObject(data)) return false;
   if (typeof data.total !== "number" || !Number.isFinite(data.total)) return false;
@@ -136,7 +137,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.3 (+https://github.com/Delibread0601/askaipods)",
   };
   if (apiKey) {
     headers["X-PodLens-API-Key"] = apiKey;

package/src/format.js

@@ -91,6 +91,7 @@ export function toStructured(query, response) {
       quota: response.meta.quota,
       restrictions: response.meta.restrictions ?? null,
       query_hash: response.meta.query_hash ?? null,
+      window: response.meta.window ?? null,
     },
   };
 }
@@ -115,7 +116,18 @@ export function renderMarkdown(query, response) {
   lines.push("");
 
   if (data.results.length === 0) {
-    lines.push("No results found. Try a different phrasing or broader topic.");
+    const win = data.meta.window;
+    if (win && win.expanded) {
+      lines.push(
+        `No results found. The API expanded the search window from ${win.requested_days} to ${win.served_days} days but still found no matches. Try a different phrasing or broader topic.`,
+      );
+    } else if (win && win.truncated) {
+      lines.push(
+        "No results found (search window expansion was interrupted by a transient error). Try again in a moment, or try a different phrasing.",
+      );
+    } else {
+      lines.push("No results found. Try a different phrasing or broader topic.");
+    }
     if (data.tier === "anonymous") {
       lines.push("");
       lines.push(`> ${ANONYMOUS_NOTE}`);
@@ -123,6 +135,15 @@ export function renderMarkdown(query, response) {
     return lines.join("\n");
   }
 
+  // Surface window expansion so the user knows the actual time range
+  const win = data.meta.window;
+  if (win && win.expanded) {
+    lines.push(
+      `*Note: No results in the requested ${win.requested_days}-day window; showing results from the last ${win.served_days} days.*`,
+    );
+    lines.push("");
+  }
+
   lines.push("## Results — newest first");
   lines.push("");