@zenalexa/unicli 0.220.1 → 0.221.1

package/src/adapters/unpaywall/works.ts

@@ -0,0 +1,138 @@
+/**
+ * @owner       src::adapters::unpaywall::works
+ * @does        Registers Unpaywall DOI open-access lookup for PDF availability.
+ * @needs       api.unpaywall.org v2, UNPAYWALL_EMAIL or --email, src/registry.ts
+ * @feeds       src/commands/scholar.ts via scholar.pdf and scholar.get
+ * @breaks      Missing email is an explicit invalid-input error; Unpaywall drift surfaces as adapter error, never as a fabricated PDF.
+ * @invariants  Only DOI-shaped references are accepted; best_oa_location is preferred for PDF and landing URLs.
+ * @side-effects HTTPS egress to api.unpaywall.org only
+ * @perf        O(1) per DOI
+ * @concurrency safe
+ * @test        tests/unit/adapters/scholar-sources.test.ts
+ * @stability   experimental
+ * @since       2026-05-19
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import type { ScholarlyWorkRecord } from "../../types/scholarly.js";
+
+const API = "https://api.unpaywall.org/v2";
+
+interface OaLocation {
+  url_for_pdf?: unknown;
+  url_for_landing_page?: unknown;
+  host_type?: unknown;
+  version?: unknown;
+  license?: unknown;
+}
+
+interface UnpaywallWork {
+  doi?: unknown;
+  title?: unknown;
+  is_oa?: unknown;
+  oa_status?: unknown;
+  best_oa_location?: OaLocation | null;
+}
+
+function str(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function bareDoi(value: unknown): string {
+  return str(value)
+    .replace(/^doi:/i, "")
+    .replace(/^https?:\/\/(?:dx\.)?doi\.org\//i, "");
+}
+
+export function requireUnpaywallDoi(value: unknown): string {
+  const doi = bareDoi(value);
+  if (!/^10\.\S+\/\S+/.test(doi)) {
+    throw new Error(
+      `unpaywall DOI "${String(value ?? "")}" is not recognised.`,
+    );
+  }
+  return doi;
+}
+
+function requireEmail(value: unknown): string {
+  const email = str(value) || process.env.UNPAYWALL_EMAIL?.trim() || "";
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+    throw new Error("unpaywall lookup requires --email or UNPAYWALL_EMAIL.");
+  }
+  return email;
+}
+
+export function mapUnpaywallWork(
+  work: UnpaywallWork,
+  source: string,
+): ScholarlyWorkRecord {
+  const doi = requireUnpaywallDoi(work.doi);
+  const best = work.best_oa_location ?? {};
+  return {
+    id: doi,
+    title: str(work.title),
+    doi,
+    is_open_access: work.is_oa === true,
+    oa_status: str(work.oa_status) || undefined,
+    pdf_url: str(best.url_for_pdf) || undefined,
+    landing_url: str(best.url_for_landing_page) || `https://doi.org/${doi}`,
+    type:
+      [str(best.host_type), str(best.version), str(best.license)]
+        .filter(Boolean)
+        .join(":") || undefined,
+    source_adapter: source,
+    source_url: str(best.url_for_landing_page) || `https://doi.org/${doi}`,
+    retrieved_at: new Date().toISOString(),
+  };
+}
+
+async function fetchUnpaywall(
+  doi: string,
+  email: string,
+): Promise<UnpaywallWork> {
+  const response = await fetch(
+    `${API}/${encodeURIComponent(doi)}?email=${encodeURIComponent(email)}`,
+    {
+      headers: {
+        Accept: "application/json",
+        "User-Agent":
+          "unicli-unpaywall/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+      },
+    },
+  );
+  if (response.status === 404)
+    throw new Error(`Unpaywall returned no result for ${doi}.`);
+  if (response.status === 422)
+    throw new Error("Unpaywall rejected the email parameter.");
+  if (response.status === 429) throw new Error("Unpaywall returned HTTP 429.");
+  if (!response.ok)
+    throw new Error(`Unpaywall returned HTTP ${response.status}.`);
+  return response.json() as Promise<UnpaywallWork>;
+}
+
+cli({
+  site: "unpaywall",
+  name: "oa",
+  description: "Find open-access PDF availability for a DOI via Unpaywall",
+  domain: "api.unpaywall.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    { name: "doi", type: "str", required: true, positional: true },
+    { name: "email", type: "str", description: "Unpaywall requester email" },
+  ],
+  columns: [
+    "id",
+    "title",
+    "doi",
+    "is_open_access",
+    "oa_status",
+    "pdf_url",
+    "source_url",
+  ],
+  capabilities: ["http.fetch", "scholar.get", "scholar.pdf"],
+  func: async (_page, kwargs) => {
+    const doi = requireUnpaywallDoi(kwargs.doi ?? kwargs.id ?? kwargs.ref);
+    const email = requireEmail(kwargs.email);
+    return [mapUnpaywallWork(await fetchUnpaywall(doi, email), "unpaywall")];
+  },
+});

package/src/adapters/uspto/get.yaml

@@ -0,0 +1,67 @@
+# @owner       src::adapters::uspto::get
+# @does        Fetch a single USPTO patent/application by application number via the ODP detail endpoint.
+# @needs       src/engine/steps/fetch.ts, src/engine/steps/map.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on 401/403 (missing/invalid X-API-KEY), 404 (number not found) or 5xx
+# @invariants  output row conforms to PatentRecord; publication_number is canonicalized to ST.16 form
+# @side-effects reads env USPTO_ODP_API_KEY; HTTPS egress to api.uspto.gov
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key — needs USPTO_ODP_API_KEY
+site: uspto
+name: get
+description: Fetch a USPTO patent/application by application number
+domain: api.uspto.gov
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  application_number:
+    type: str
+    required: true
+    positional: true
+    description: USPTO application number (e.g. 16/123,456 with or without slash)
+
+pipeline:
+  - fetch:
+      url: "https://api.uspto.gov/api/v1/patent/applications/${{ args.application_number | replace('/', '') | replace(',', '') }}"
+      method: GET
+      headers:
+        Accept: application/json
+        X-API-KEY: "${{ env.USPTO_ODP_API_KEY || '' }}"
+
+  # ODP single-record detail endpoint returns the same `applicationMetaData`
+  # envelope as search, plus a richer `patentTermAdjustment` / `inventor` /
+  # `applicant` set on the detail path. Every field reference below maps to a
+  # documented ODP path; adapters do not synthesise.
+  - map:
+      publication_number: "${{ item.applicationMetaData && item.applicationMetaData.earliestPublicationNumber ? ('US-' + item.applicationMetaData.earliestPublicationNumber) : ('US-' + (item.applicationNumberText || '')) }}"
+      application_number: "${{ item.applicationNumberText || '' }}"
+      title: "${{ item.applicationMetaData ? (item.applicationMetaData.inventionTitle || '') : '' }}"
+      abstract: "${{ item.applicationMetaData ? (item.applicationMetaData.abstractText || '') : '' }}"
+      filing_date: "${{ item.applicationMetaData ? (item.applicationMetaData.filingDate || '') : '' }}"
+      publication_date: "${{ item.applicationMetaData ? (item.applicationMetaData.earliestPublicationDate || '') : '' }}"
+      grant_date: "${{ item.applicationMetaData ? (item.applicationMetaData.grantDate || '') : '' }}"
+      priority_date: "${{ item.applicationMetaData ? (item.applicationMetaData.firstInventorToFileIndicator ? item.applicationMetaData.filingDate : (item.applicationMetaData.earliestPriorityDate || '')) : '' }}"
+      kind_code: "${{ (item.applicationMetaData && item.applicationMetaData.earliestPublicationNumber) ? (item.applicationMetaData.earliestPublicationNumber.match(/[A-Z]\\d?$/) || [''])[0] : '' }}"
+      inventors: "${{ JSON.stringify((item.applicationMetaData && item.applicationMetaData.inventorBag) ? item.applicationMetaData.inventorBag.map(p => ({ name: p.inventorNameText || ((p.firstName || '') + ' ' + (p.lastName || '')).trim(), country: p.countryCode || undefined })) : []) }}"
+      assignees: "${{ JSON.stringify((item.applicationMetaData && item.applicationMetaData.applicantBag) ? item.applicationMetaData.applicantBag.map(p => ({ name: p.applicantNameText || p.organizationNameText || '', country: p.countryCode || undefined })) : []) }}"
+      classifications: "${{ JSON.stringify((item.applicationMetaData && item.applicationMetaData.cpcClassificationBag) ? item.applicationMetaData.cpcClassificationBag.map(c => ({ scheme: 'cpc', code: c.cpcSymbol || c })) : []) }}"
+      legal_status: "${{ item.applicationMetaData ? (item.applicationMetaData.applicationStatusDescriptionText || '') : '' }}"
+      source_adapter: uspto
+      source_url: "${{ 'https://ppubs.uspto.gov/dirsearch-public/patents/' + (item.applicationNumberText || '') }}"
+      retrieved_at: ""
+
+columns: [publication_number, title, filing_date, publication_date]
+
+# schema-v2 metadata
+capabilities: ["http.fetch", "patent.get"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/uspto/legal-status.yaml

@@ -0,0 +1,58 @@
+# @owner       src::adapters::uspto::legal-status
+# @does        Fetch USPTO transaction history (PAIR) for an application — used to derive legal-status (issued, abandoned, pending, etc.).
+# @needs       src/engine/steps/fetch.ts, src/engine/steps/select.ts, src/engine/steps/map.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on 401/403/404
+# @invariants  output rows conform to PatentRecord; legal_status carries the latest transaction description
+# @side-effects reads env USPTO_ODP_API_KEY; HTTPS egress to api.uspto.gov
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key — needs USPTO_ODP_API_KEY
+site: uspto
+name: legal-status
+description: Legal-status / transaction history of a USPTO application
+domain: api.uspto.gov
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  application_number:
+    type: str
+    required: true
+    positional: true
+    description: USPTO application number
+
+pipeline:
+  - fetch:
+      url: "https://api.uspto.gov/api/v1/patent/applications/${{ args.application_number | replace('/', '') | replace(',', '') }}/transactions"
+      method: GET
+      headers:
+        Accept: application/json
+        X-API-KEY: "${{ env.USPTO_ODP_API_KEY || '' }}"
+
+  - select: eventDataBag
+
+  # Each row is a transaction event; the ODP `transactions` endpoint returns
+  # eventCode + eventDescriptionText + eventDate per transaction.
+  - map:
+      publication_number: "${{ 'US-' + (args.application_number || '') }}"
+      application_number: "${{ args.application_number }}"
+      legal_status: "${{ (item.eventCode || '') + (item.eventDescriptionText ? (' ' + item.eventDescriptionText) : '') }}"
+      filing_date: "${{ item.eventDate || '' }}"
+      source_adapter: uspto
+      source_url: "${{ 'https://ppubs.uspto.gov/dirsearch-public/patents/' + (args.application_number || '') }}"
+      retrieved_at: ""
+
+columns: [publication_number, legal_status, filing_date]
+
+# schema-v2 metadata
+capabilities: ["http.fetch", "patent.legal-status"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/uspto/search.yaml

@@ -0,0 +1,88 @@
+# @owner       src::adapters::uspto::search
+# @does        Search USPTO patents/applications via the Open Data Portal (ODP) `applications/search` endpoint.
+# @needs       src/engine/steps/fetch.ts, src/engine/steps/select.ts, src/engine/steps/map.ts, src/engine/steps/limit.ts
+# @feeds       src/commands/patent.ts (meta-command aggregator)
+# @breaks      throws PipelineError on 401/403 (missing/invalid X-API-KEY) or 5xx; ODP enforces a 6 MB response cap — narrow the query if hit
+# @invariants  output rows conform to PatentRecord; publication_number is canonicalized to ST.16 form `US-<doc>-<kind>`
+# @side-effects reads env USPTO_ODP_API_KEY; HTTPS egress to api.uspto.gov
+# @perf        single request, ODP returns up to 500 records per page
+# @concurrency single-call; no shared mutable state
+# @test        none yet (adapter ships; live verification gated on key)
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key — needs USPTO_ODP_API_KEY (free tier at developer.uspto.gov)
+site: uspto
+name: search
+description: Search USPTO patents/applications via the Open Data Portal (ODP)
+domain: api.uspto.gov
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Free-text query (mapped to ODP `q` field, matches title/abstract/claims)
+  limit:
+    type: int
+    default: 25
+    description: Maximum results to return (ODP allows up to 500 per page)
+  offset:
+    type: int
+    default: 0
+    description: Result offset for pagination
+
+pipeline:
+  - fetch:
+      url: "https://api.uspto.gov/api/v1/patent/applications/search"
+      method: GET
+      headers:
+        Accept: application/json
+        X-API-KEY: "${{ env.USPTO_ODP_API_KEY || '' }}"
+      params:
+        q: "${{ args.query }}"
+        limit: "${{ args.limit }}"
+        offset: "${{ args.offset }}"
+
+  - select: patentFileWrapperDataBag
+
+  # Field mapping references data.uspto.gov/swagger v1 patent applications schema.
+  # Every field below maps to a documented ODP response path — adapters must
+  # not synthesise values upstream did not return.
+  - map:
+      publication_number: "${{ item.applicationMetaData && item.applicationMetaData.earliestPublicationNumber ? ('US-' + item.applicationMetaData.earliestPublicationNumber) : ('US-' + (item.applicationNumberText || '')) }}"
+      application_number: "${{ item.applicationNumberText || '' }}"
+      title: "${{ item.applicationMetaData ? (item.applicationMetaData.inventionTitle || '') : '' }}"
+      abstract: "${{ item.applicationMetaData ? (item.applicationMetaData.abstractText || '') : '' }}"
+      filing_date: "${{ item.applicationMetaData ? (item.applicationMetaData.filingDate || '') : '' }}"
+      publication_date: "${{ item.applicationMetaData ? (item.applicationMetaData.earliestPublicationDate || '') : '' }}"
+      grant_date: "${{ item.applicationMetaData ? (item.applicationMetaData.grantDate || '') : '' }}"
+      # ODP `applicationMetaData.earliestPublicationNumber` is the compact form
+      # (`20240123456A1`); the trailing A1/A2/B1/B2 IS the ST.16 kind code.
+      kind_code: "${{ (item.applicationMetaData && item.applicationMetaData.earliestPublicationNumber) ? (item.applicationMetaData.earliestPublicationNumber.match(/[A-Z]\\d?$/) || [''])[0] : '' }}"
+      # ODP `inventorBag[]` and `applicantBag[]` carry per-party records.
+      # We serialise via JSON.stringify so the array survives the template
+      # engine's string projection; coerceToPatentRecords parses it back.
+      inventors: "${{ JSON.stringify((item.applicationMetaData && item.applicationMetaData.inventorBag) ? item.applicationMetaData.inventorBag.map(p => ({ name: p.inventorNameText || ((p.firstName || '') + ' ' + (p.lastName || '')).trim(), country: p.countryCode || undefined })) : []) }}"
+      assignees: "${{ JSON.stringify((item.applicationMetaData && item.applicationMetaData.applicantBag) ? item.applicationMetaData.applicantBag.map(p => ({ name: p.applicantNameText || p.organizationNameText || '', country: p.countryCode || undefined })) : []) }}"
+      # `cpcClassificationBag[]` is the ODP path for Cooperative Patent Classification codes.
+      classifications: "${{ JSON.stringify((item.applicationMetaData && item.applicationMetaData.cpcClassificationBag) ? item.applicationMetaData.cpcClassificationBag.map(c => ({ scheme: 'cpc', code: c.cpcSymbol || c })) : []) }}"
+      legal_status: "${{ item.applicationMetaData ? (item.applicationMetaData.applicationStatusDescriptionText || '') : '' }}"
+      source_adapter: uspto
+      source_url: "${{ 'https://ppubs.uspto.gov/dirsearch-public/patents/' + (item.applicationNumberText || '') }}"
+      # retrieved_at is stamped by assemblePatentRecord in the normalizer; YAML emits the empty string
+      retrieved_at: ""
+
+  - limit: "${{ args.limit }}"
+
+columns: [publication_number, title, filing_date, publication_date]
+
+# schema-v2 metadata
+capabilities: ["http.fetch", "patent.search"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/wipo-patentscope/info.yaml

@@ -0,0 +1,43 @@
+# @owner       src::adapters::wipo-patentscope::info
+# @does        Registry placeholder for WIPO PATENTSCOPE — surfaces a structured PATENT_API_DEPRECATED envelope so `unicli patent doctor` and `unicli list` advertise the gap, without claiming false coverage.
+# @needs       src/engine/steps/assert.ts
+# @feeds       src/commands/patent.ts (meta-command discovery via `patent.*` capability)
+# @breaks      always throws PipelineError carrying a PATENT_API_DEPRECATED message; never silently returns rows
+# @invariants  no HTTPS egress; no env reads; no caller-visible state beyond the error envelope
+# @side-effects none — the assertion is purely local
+# @perf        n/a — fails before any I/O
+# @concurrency safe (pure local assertion)
+# @test        none yet
+# @stability   experimental — replace with a real adapter when WIPO ships a token-based REST/GraphQL API
+# @since       2026-05-18
+# @verification blocked-by-subscription — PATENTSCOPE exposes only a SOAP web service that requires a paid subscription (~CHF 600/year per third-party gem README; see https://patentscope.wipo.int/search/en/sub_user.jsf). Until WIPO ships a token-based REST/GraphQL surface, this adapter is a registry placeholder.
+site: wipo-patentscope
+name: info
+description: WIPO PATENTSCOPE registry placeholder — no public REST API; SOAP requires subscription
+domain: patentscope.wipo.int
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args: {}
+
+pipeline:
+  # Fail closed with a structured envelope that the agent can read and act on.
+  # The message names the upstream channel and the subscription URL so the
+  # caller has a concrete next step — no silent fallback, no fake row.
+  - assert:
+      condition: "false"
+      message: "PATENT_API_DEPRECATED: WIPO PATENTSCOPE exposes only a SOAP web service that requires a paid subscription. Subscribe at https://patentscope.wipo.int/search/en/sub_user.jsf, or fall back to Espacenet for WO-prefixed publications (EPO brokers PCT family lookups)."
+
+columns: []
+
+# schema-v2 metadata
+# The patent.* capability is what makes `unicli patent doctor` discover this
+# adapter so the gap is reported in the doctor table; assert.fail is the
+# step the dispatcher actually invokes at runtime.
+capabilities: ["assert", "patent.search", "patent.get"]
+minimum_capability: assert
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/xiaohongshu/browser-state.ts

@@ -0,0 +1,95 @@
+/**
+ * @owner   Xiaohongshu browser adapters.
+ * @does    Detects login, risk-control, and rendered-feed state in XHS web pages.
+ * @needs   Browser-backed IPage from Uni-CLI runtime.
+ * @feeds   xiaohongshu.search and xiaohongshu.trending.
+ * @breaks  XHS copy or route changes can require updating page-state detection.
+ */
+
+import type { IPage } from "../../types.js";
+import {
+  socialAuthError,
+  socialChallengeError,
+} from "../../social/browser-errors.js";
+
+interface XhsPageState {
+  url: string;
+  title: string;
+  text: string;
+}
+
+export async function readXhsPageState(page: IPage): Promise<XhsPageState> {
+  const raw = await page.evaluate(`
+    (() => ({
+      url: window.location.href,
+      title: document.title || '',
+      text: (document.body?.innerText || '').replace(/\\s+/g, ' ').slice(0, 2000)
+    }))()
+  `);
+  const state = raw as Partial<XhsPageState>;
+  return {
+    url: String(state.url ?? ""),
+    title: String(state.title ?? ""),
+    text: String(state.text ?? ""),
+  };
+}
+
+export function assertXhsReadableState(
+  command: string,
+  state: XhsPageState,
+): void {
+  const haystack = `${state.url}\n${state.title}\n${state.text}`;
+  if (
+    /website-login\/error|安全限制|IP存在风险|风险|风控|安全验证|验证码|人机验证|verify|captcha/i.test(
+      haystack,
+    )
+  ) {
+    throw socialChallengeError(
+      "xiaohongshu",
+      command,
+      `Xiaohongshu is showing a risk-control or verification page: ${state.title || state.url}`,
+    );
+  }
+  if (/登录后查看|登录后|请先登录|login/i.test(haystack)) {
+    throw socialAuthError("xiaohongshu", command);
+  }
+}
+
+export async function assertXhsReadable(
+  page: IPage,
+  command: string,
+): Promise<void> {
+  assertXhsReadableState(command, await readXhsPageState(page));
+}
+
+export async function fetchXhsFeedItems(page: IPage): Promise<unknown[]> {
+  const raw = await page.evaluate(`
+    (async () => {
+      const app = document.querySelector('#app')?.__vue_app__;
+      if (!app) throw new Error('Xiaohongshu Vue app not found');
+      const pinia = app.config?.globalProperties?.$pinia;
+      if (!pinia || !pinia._s?.has('feed')) throw new Error('Xiaohongshu feed store not found');
+      const store = pinia._s.get('feed');
+      const captured = [];
+      const originalFetch = window.fetch;
+      window.fetch = async (...args) => {
+        const response = await originalFetch(...args);
+        try {
+          const url = String(args[0]?.url || args[0] || '');
+          if (/homefeed|feed/i.test(url)) {
+            captured.push(await response.clone().json());
+          }
+        } catch {}
+        return response;
+      };
+      try {
+        await store.fetchFeeds();
+      } finally {
+        window.fetch = originalFetch;
+      }
+      const payload = captured.find((item) => item?.data?.items?.length) || captured[0];
+      return payload?.data?.items || [];
+    })()
+  `);
+  return Array.isArray(raw) ? raw : [];
+}

package/src/adapters/xiaohongshu/comments.ts

@@ -7,6 +7,7 @@
 
 import { cli, Strategy } from "../../registry.js";
 import type { IPage } from "../../types.js";
+import { normalizeCommentRows } from "../../social/comments.js";
 import { buildNoteUrl } from "./note-helpers.js";
 
 function parseCommentLimit(raw: unknown, fallback = 20): number {
@@ -42,7 +43,23 @@ cli({
       description: "Include nested replies",
     },
   ],
-  columns: ["rank", "author", "text", "likes", "time", "is_reply", "reply_to"],
+  columns: [
+    "rank",
+    "platform",
+    "content_id",
+    "comment_id",
+    "parent_id",
+    "depth",
+    "path",
+    "author",
+    "text",
+    "likes",
+    "replies",
+    "created",
+    "time",
+    "is_reply",
+    "reply_to",
+  ],
   func: async (page, kwargs) => {
     const p = page as IPage;
     const limit = parseCommentLimit(kwargs.limit);
@@ -100,7 +117,7 @@ cli({
           const likes = parseLikes(item.querySelector('.count'))
           const time = clean(item.querySelector('.date, .time'))
           if (!text) continue
-          results.push({ author, text, likes, time, is_reply: false, reply_to: '' })
+          results.push({ author, text, likes, replies: 0, created: time, time, is_reply: false, reply_to: '' })
           if (withReplies) {
             await expandReplyThreads(p)
             p.querySelectorAll('.reply-container .comment-item-sub, .sub-comment-list .comment-item').forEach(sub => {
@@ -109,7 +126,7 @@ cli({
               const sLikes = parseLikes(sub.querySelector('.count'))
               const sTime = clean(sub.querySelector('.date, .time'))
               if (!sText) return
-              results.push({ author: sAuthor, text: sText, likes: sLikes, time: sTime, is_reply: true, reply_to: author })
+              results.push({ author: sAuthor, text: sText, likes: sLikes, replies: 0, created: sTime, time: sTime, is_reply: true, reply_to: author })
             })
           }
         }
@@ -125,7 +142,7 @@ cli({
       throw new Error("Note comments require login to www.xiaohongshu.com");
     }
 
-    interface CommentRow {
+    interface CommentRow extends Record<string, unknown> {
       author: string;
       text: string;
       likes: number;
@@ -144,9 +161,15 @@ cli({
         if (topCount > limit) break;
         limited.push(c);
       }
-      return limited.map((c, i) => ({ rank: i + 1, ...c }));
+      return normalizeCommentRows(limited, {
+        platform: "xiaohongshu",
+        contentId: raw,
+      }).map((c, i) => ({ rank: i + 1, ...c }));
     }
 
-    return all.slice(0, limit).map((c, i) => ({ rank: i + 1, ...c }));
+    return normalizeCommentRows(all.slice(0, limit), {
+      platform: "xiaohongshu",
+      contentId: raw,
+    }).map((c, i) => ({ rank: i + 1, ...c }));
   },
 });

package/src/adapters/xiaohongshu/download.ts

@@ -7,16 +7,56 @@
 
 import { cli, Strategy } from "../../registry.js";
 import type { IPage } from "../../types.js";
-import { loadCookies, formatCookieHeader } from "../../engine/cookies.js";
+import {
+  loadCookiesWithCDP,
+  formatCookieHeader,
+} from "../../engine/cookies.js";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { USER_AGENT } from "../../constants.js";
 import { parseNoteId, buildNoteUrl } from "./note-helpers.js";
 
 /** Build authenticated headers for Xiaohongshu downloads. */
-function buildCookieHeader(): string {
-  const cookies = loadCookies("xiaohongshu");
+async function buildCookieHeader(): Promise<string> {
+  const cookies = await loadCookiesWithCDP(
+    "xiaohongshu",
+    "www.xiaohongshu.com",
+  );
   if (cookies) return formatCookieHeader(cookies);
   return "";
 }
 
+function extensionForMedia(type: string, url: string): string {
+  try {
+    const pathname = new URL(url).pathname;
+    const match = /\.[a-zA-Z0-9]{2,5}$/.exec(pathname);
+    if (match) return match[0].toLowerCase();
+  } catch {
+    return type === "video" ? ".mp4" : ".jpg";
+  }
+  return type === "video" ? ".mp4" : ".jpg";
+}
+
+async function downloadMedia(
+  url: string,
+  path: string,
+  cookieHeader: string,
+): Promise<void> {
+  const headers: Record<string, string> = {
+    "User-Agent": USER_AGENT,
+    Referer: "https://www.xiaohongshu.com/",
+  };
+  if (cookieHeader) headers.Cookie = cookieHeader;
+  const response = await fetch(url, { headers });
+  if (!response.ok) {
+    throw new Error(
+      `Xiaohongshu media download failed: HTTP ${response.status}`,
+    );
+  }
+  const bytes = Buffer.from(await response.arrayBuffer());
+  await writeFile(path, bytes);
+}
+
 cli({
   site: "xiaohongshu",
   name: "download",
@@ -37,11 +77,12 @@ cli({
       description: "Output directory",
     },
   ],
-  columns: ["index", "type", "url"],
+  columns: ["index", "type", "path", "url"],
   func: async (page, kwargs) => {
     const p = page as IPage;
     const rawInput = String(kwargs["note-id"]);
     const noteId = parseNoteId(rawInput);
+    const outputDir = String(kwargs.output ?? "./xiaohongshu-downloads");
 
     await p.goto(buildNoteUrl(rawInput));
     await p.wait(3);
@@ -158,13 +199,21 @@ cli({
       return [{ index: 0, type: "-", url: "No media found" }];
     }
 
-    // Cookie header available for authenticated downloads when media pipeline is wired
-    void buildCookieHeader();
+    await mkdir(outputDir, { recursive: true });
+    const cookieHeader = await buildCookieHeader();
 
-    return data.media.map((m: { type: string; url: string }, idx: number) => ({
-      index: idx + 1,
-      type: m.type,
-      url: m.url,
-    }));
+    const rows = [];
+    for (const [idx, media] of data.media.entries()) {
+      const ext = extensionForMedia(media.type, media.url);
+      const path = join(outputDir, `${noteId}-${idx + 1}${ext}`);
+      await downloadMedia(media.url, path, cookieHeader);
+      rows.push({
+        index: idx + 1,
+        type: media.type,
+        path,
+        url: media.url,
+      });
+    }
+    return rows;
   },
 });