@zenalexa/unicli 0.220.0 → 0.221.0

package/src/adapters/google-patents-bq/search.yaml

@@ -0,0 +1,97 @@
+# Google Patents Public Datasets via BigQuery REST.
+#
+# verification_status: blocked-by-key
+#
+# The dataset `patents-public-data.patents.publications` is free to query but
+# requires a Google Cloud project with billing enabled (queries are billed at
+# the standard BigQuery rate; the 1 TB / month free tier covers exploratory
+# work). Auth path is OAuth2 — read $GCLOUD_ACCESS_TOKEN first; the adapter
+# self-repair sequence asks the user to run `gcloud auth print-access-token`
+# and re-export the value.
+#
+# The query template uses standard SQL against the public publications table.
+# `args.query` is interpolated as a substring match on title/abstract — adapt
+# the template for richer CQL when needed.
+site: google-patents-bq
+name: search
+description: BigQuery search over the Google Patents Public Datasets corpus
+domain: bigquery.googleapis.com
+type: web-api
+strategy: header
+lint_listing_detail: skip
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Substring matched against title and abstract (case-insensitive)
+  limit:
+    type: int
+    default: 20
+  project:
+    type: str
+    default: ""
+    description: GCP project ID — falls back to $GCLOUD_PROJECT
+
+pipeline:
+  - fetch:
+      url: "https://bigquery.googleapis.com/bigquery/v2/projects/${{ args.project || env.GCLOUD_PROJECT || '' }}/queries"
+      method: POST
+      headers:
+        Authorization: "Bearer ${{ env.GCLOUD_ACCESS_TOKEN || '' }}"
+        Content-Type: application/json
+      body:
+        query: |-
+          SELECT
+            publication_number,
+            ANY_VALUE(country_code) AS country_code,
+            ANY_VALUE(kind_code) AS kind_code,
+            ANY_VALUE(title_localized)[OFFSET(0)].text AS title,
+            ANY_VALUE(abstract_localized)[OFFSET(0)].text AS abstract,
+            ANY_VALUE(publication_date) AS publication_date,
+            ANY_VALUE(filing_date) AS filing_date,
+            ANY_VALUE(grant_date) AS grant_date,
+            ANY_VALUE(priority_date) AS priority_date,
+            ANY_VALUE(application_number) AS application_number,
+            ANY_VALUE(family_id) AS family_id,
+            TO_JSON_STRING(ANY_VALUE(inventor_harmonized)) AS inventors,
+            TO_JSON_STRING(ANY_VALUE(assignee_harmonized)) AS assignees,
+            TO_JSON_STRING(ANY_VALUE(cpc)) AS cpc,
+            TO_JSON_STRING(ANY_VALUE(ipc)) AS ipc,
+            ANY_VALUE(claims_localized_html)[OFFSET(0)].text AS claims_text
+          FROM `patents-public-data.patents.publications`
+          WHERE LOWER(title_localized[OFFSET(0)].text) LIKE LOWER('%${{ args.query }}%')
+             OR LOWER(abstract_localized[OFFSET(0)].text) LIKE LOWER('%${{ args.query }}%')
+          GROUP BY publication_number
+          LIMIT ${{ args.limit }}
+        useLegacySql: false
+
+  - select: rows
+
+  - map:
+      publication_number: "${{ item.f[0].v }}"
+      kind_code: "${{ item.f[2].v || '' }}"
+      title: "${{ item.f[3].v }}"
+      abstract: "${{ item.f[4].v }}"
+      publication_date: "${{ item.f[5].v }}"
+      filing_date: "${{ item.f[6].v }}"
+      grant_date: "${{ item.f[7].v }}"
+      priority_date: "${{ item.f[8].v }}"
+      application_number: "${{ item.f[9].v }}"
+      family_id: "${{ item.f[10].v }}"
+      inventors: "${{ JSON.stringify((function(){ try { var arr = JSON.parse(item.f[11].v || '[]'); return Array.isArray(arr) ? arr.map(i => ({ name: i.name || i, country: i.country_code || undefined })) : []; } catch(e) { return []; } })()) }}"
+      assignees: "${{ JSON.stringify((function(){ try { var arr = JSON.parse(item.f[12].v || '[]'); return Array.isArray(arr) ? arr.map(a => ({ name: a.name || a, country: a.country_code || undefined })) : []; } catch(e) { return []; } })()) }}"
+      classifications: "${{ JSON.stringify((function(){ var out = []; try { var cpc = JSON.parse(item.f[13].v || '[]'); if(Array.isArray(cpc)){ for (var i=0;i<cpc.length;i++) out.push({ scheme: 'cpc', code: cpc[i].code || cpc[i] }); } } catch(e){} try { var ipc = JSON.parse(item.f[14].v || '[]'); if(Array.isArray(ipc)){ for (var j=0;j<ipc.length;j++) out.push({ scheme: 'ipc', code: ipc[j].code || ipc[j] }); } } catch(e){} return out.filter(x => x.code); })()) }}"
+      source_adapter: google-patents-bq
+      source_url: "${{ 'https://patents.google.com/patent/' + (item.f[0].v || '') }}"
+      retrieved_at: "${{ now }}"
+
+columns: [publication_number, title, publication_date, source_adapter]
+
+capabilities: ["http.fetch", "patent.search"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/google-patents-web/_shared.ts

@@ -0,0 +1,242 @@
+/**
+ * @owner       src::adapters::google-patents-web::_shared
+ * @does        Shared HTTP helpers and types for the KEYLESS Google Patents web adapter — distinct from the BigQuery-backed google-patents-bq adapter (which requires a billed GCP project). This adapter uses the public XHR endpoint that drives patents.google.com and the SSR /patent/<id>/en bibliography page, both of which are reachable with only a real-browser User-Agent header.
+ * @needs       src/engine/normalizer/patent-envelope.ts, src/types/patent.ts, node:fetch (global)
+ * @feeds       src/adapters/google-patents-web/search.yaml, src/adapters/google-patents-web/get.ts
+ * @breaks      throws GooglePatentsHttpError when the endpoint returns non-2xx or unparseable JSON; callers surface PATENT_API_DEPRECATED to the meta-command
+ * @invariants  every outbound request carries a real-browser User-Agent — Google rejects bare `node-fetch`/`python-requests`; the @keyless-best-effort verification tag is emitted in adapter file headers
+ * @side-effects HTTPS egress to patents.google.com only; no env reads, no cookies
+ * @perf        single request per call; XHR responses are ~40-100 KB
+ * @concurrency safe — pure functions plus stateless `fetch`
+ * @test        covered transitively via tests/unit/adapters/google-patents-web/*.test.ts (none yet — adapters ship with live verification proof in docs/skills/patent-cookbook.md)
+ * @stability   experimental — Google does not publish a stability contract for this XHR
+ * @since       2026-05-18
+ * @verification keyless-best-effort
+ */
+
+import type { PatentRecord } from "../../types/patent.js";
+
+/**
+ * Local verification-status alias for the keyless-web adapter family.
+ *
+ * Distinct from the canonical `PatentVerificationStatus` union in
+ * `src/types/patent.ts` — adding a new variant there is owned by another
+ * agent in this batch, so we expose it as a *local* string-literal type
+ * alias the file headers can advertise without forcing a cross-cutting
+ * type change. The meta-command does not branch on this value; it is
+ * documentation-grade only.
+ */
+export type KeylessBestEffortStatus = "keyless-best-effort";
+export const KEYLESS_BEST_EFFORT: KeylessBestEffortStatus =
+  "keyless-best-effort";
+
+/**
+ * Real-browser User-Agent string. Google's XHR endpoint returns 403 for the
+ * default `node/undici` UA; a Chrome string fixes that. Mirror the version
+ * Chrome currently ships rather than freezing on an old number so the header
+ * stays plausible if Google starts UA-version-gating in future.
+ */
+export const GOOGLE_PATENTS_UA =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36";
+
+export class GooglePatentsHttpError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly url: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "GooglePatentsHttpError";
+  }
+}
+
+/**
+ * GET <url> with a real-browser UA. Returns parsed JSON; throws
+ * GooglePatentsHttpError on non-2xx or JSON parse failure.
+ */
+export async function fetchGooglePatentsJson<T>(url: string): Promise<T> {
+  const response = await fetch(url, {
+    method: "GET",
+    headers: {
+      "User-Agent": GOOGLE_PATENTS_UA,
+      Accept: "application/json",
+    },
+  });
+  if (!response.ok) {
+    throw new GooglePatentsHttpError(
+      response.status,
+      url,
+      `Google Patents XHR returned HTTP ${response.status}`,
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = await response.json();
+  } catch (err) {
+    throw new GooglePatentsHttpError(
+      response.status,
+      url,
+      `Google Patents XHR returned non-JSON body: ${(err as Error).message}`,
+    );
+  }
+  return parsed as T;
+}
+
+/**
+ * GET <url> with a real-browser UA, return raw HTML text. Throws
+ * GooglePatentsHttpError on non-2xx.
+ */
+export async function fetchGooglePatentsHtml(url: string): Promise<string> {
+  const response = await fetch(url, {
+    method: "GET",
+    headers: {
+      "User-Agent": GOOGLE_PATENTS_UA,
+      Accept: "text/html,application/xhtml+xml",
+    },
+  });
+  if (!response.ok) {
+    throw new GooglePatentsHttpError(
+      response.status,
+      url,
+      `Google Patents detail page returned HTTP ${response.status}`,
+    );
+  }
+  return await response.text();
+}
+
+/**
+ * Build the public XHR query URL. Accepts a plain free-text query string and
+ * an optional limit (`num` parameter) and earliest-publication-year filter.
+ *
+ * The XHR endpoint expects a percent-encoded *inner* query string under the
+ * `url` parameter — the outer query is `?url=q%3Dfoo&exp=`. We percent-encode
+ * the inner once.
+ */
+export function buildGooglePatentsXhrUrl(
+  query: string,
+  limit?: number,
+  sinceYear?: string,
+): string {
+  const cleaned = query.trim();
+  let inner = `q=${cleaned.replace(/\s+/g, "+")}`;
+  if (typeof limit === "number" && Number.isFinite(limit) && limit > 0) {
+    inner += `&num=${Math.min(100, Math.max(1, Math.floor(limit)))}`;
+  }
+  if (sinceYear && /^\d{4}$/.test(sinceYear)) {
+    inner += `&after=publication:${sinceYear}0101`;
+  }
+  return `https://patents.google.com/xhr/query?url=${encodeURIComponent(inner)}&exp=`;
+}
+
+/**
+ * Build the public detail page URL for a given publication number. Google
+ * accepts the segmented form `US-11741188-B2` and the compact form
+ * `US11741188B2`; we send the compact form to keep the URL short.
+ */
+export function buildGooglePatentsDetailUrl(pubNo: string): string {
+  const compact = pubNo.replace(/-/g, "").toUpperCase();
+  return `https://patents.google.com/patent/${encodeURIComponent(compact)}/en`;
+}
+
+/**
+ * XHR response shape. We intentionally type only the fields we read —
+ * Google ships many more (figure thumbnails, family metadata, language) that
+ * we either ignore or carry through verbatim in `raw`.
+ */
+export interface GoogleXhrResultRow {
+  id: string;
+  rank?: number;
+  patent?: {
+    title?: string;
+    snippet?: string;
+    publication_number?: string;
+    inventor?: string;
+    assignee?: string;
+    filing_date?: string;
+    publication_date?: string;
+    grant_date?: string;
+    priority_date?: string;
+    language?: string;
+  };
+}
+
+export interface GoogleXhrResponse {
+  results?: {
+    cluster?: Array<{ result?: GoogleXhrResultRow[] }>;
+    total_num_results?: number;
+  };
+}
+
+/**
+ * Flatten the nested `results.cluster[].result[]` into a single array, in
+ * server-supplied order.
+ */
+export function flattenGoogleXhrResults(
+  body: GoogleXhrResponse,
+): GoogleXhrResultRow[] {
+  const clusters = body.results?.cluster ?? [];
+  const out: GoogleXhrResultRow[] = [];
+  for (const cluster of clusters) {
+    const rows = cluster.result ?? [];
+    for (const row of rows) out.push(row);
+  }
+  return out;
+}
+
+/**
+ * Project a single XHR row to the upstream-facing partial-PatentRecord
+ * shape. Empty / missing fields are left undefined rather than synthesised.
+ * Snippets contain HTML markup (e.g. `<b>` tags) which we strip.
+ */
+export function projectGoogleRowToRecord(
+  row: GoogleXhrResultRow,
+  sourceUrl: string,
+): Partial<PatentRecord> & {
+  publication_number: string;
+  source_adapter: string;
+} {
+  const patent = row.patent ?? {};
+  const pubNo =
+    (typeof patent.publication_number === "string" &&
+      patent.publication_number) ||
+    deriveCanonicalFromId(row.id);
+  const cleanSnippet = patent.snippet ? stripHtml(patent.snippet) : undefined;
+  return {
+    publication_number: pubNo,
+    title: patent.title ? patent.title.trim() : undefined,
+    abstract: cleanSnippet,
+    inventors: patent.inventor ? [{ name: patent.inventor.trim() }] : undefined,
+    assignees: patent.assignee ? [{ name: patent.assignee.trim() }] : undefined,
+    filing_date: patent.filing_date || undefined,
+    publication_date: patent.publication_date || undefined,
+    grant_date: patent.grant_date || undefined,
+    priority_date: patent.priority_date || undefined,
+    source_adapter: "google-patents-web",
+    source_url: sourceUrl,
+  };
+}
+
+/** `patent/US11741188B2/en` → `US11741188B2`. */
+function deriveCanonicalFromId(id: string): string {
+  const match = /patent\/([^/]+)/.exec(id);
+  return match ? match[1] : id;
+}
+
+const TAG_RE = /<[^>]+>/g;
+const ENTITY_MAP: Record<string, string> = {
+  "&amp;": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&quot;": '"',
+  "&#39;": "'",
+  "&hellip;": "…",
+  "&nbsp;": " ",
+};
+
+export function stripHtml(input: string): string {
+  return input
+    .replace(TAG_RE, "")
+    .replace(/&(?:amp|lt|gt|quot|#39|hellip|nbsp);/g, (m) => ENTITY_MAP[m] ?? m)
+    .replace(/\s+/g, " ")
+    .trim();
+}

package/src/adapters/google-patents-web/get.ts

@@ -0,0 +1,224 @@
+/**
+ * @owner       src::adapters::google-patents-web::get
+ * @does        Keyless single-publication detail fetch — parses the SSR meta-tag and `<abstract>` block on https://patents.google.com/patent/<id>/en using regex projection (no DOM, no Chrome).
+ * @needs       src/adapters/google-patents-web/_shared.ts, src/engine/normalizer/patent-envelope.ts, src/registry.ts
+ * @feeds       src/commands/patent.ts (capability tag patent.get)
+ * @breaks      PATENT_NOT_FOUND when the detail page returns 200 but carries no DC.title; PATENT_INVALID_NUMBER for empty input; PATENT_API_DEPRECATED on non-2xx HTTP
+ * @invariants  output is a single canonical PatentRecord; abstract whitespace is normalised; HTML entities decoded; source_url is the literal page we hit
+ * @side-effects HTTPS egress to patents.google.com only
+ * @perf        single page load (~350 KB); regex parse is linear in document length
+ * @concurrency safe — stateless
+ * @test        verification proof in docs/skills/patent-cookbook.md
+ * @stability   experimental
+ * @since       2026-05-18
+ * @verification keyless-best-effort
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import { assemblePatentRecord } from "../../engine/normalizer/patent-envelope.js";
+import { buildPatentEnvelope } from "../../engine/normalizer/patent-envelope.js";
+import {
+  GooglePatentsHttpError,
+  buildGooglePatentsDetailUrl,
+  fetchGooglePatentsHtml,
+  stripHtml,
+} from "./_shared.js";
+
+const ADAPTER_PATH = "src/adapters/google-patents-web/get.ts";
+
+interface DetailPageFields {
+  title?: string;
+  abstract?: string;
+  inventors: string[];
+  assignees: string[];
+  filing_date?: string;
+  publication_date?: string;
+  application_number?: string;
+}
+
+function extractMetaContent(html: string, name: string): string[] {
+  const out: string[] = [];
+  const re = new RegExp(
+    `<meta[^>]+name=["']${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["'][^>]*content=["']([^"']*)["']`,
+    "gi",
+  );
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(html)) !== null) {
+    if (match[1]) out.push(match[1].trim());
+  }
+  return out;
+}
+
+/**
+ * Parse the Google Patents detail HTML into the subset of fields we surface
+ * on PatentRecord. The DC.* meta tags are the documented machine-readable
+ * surface (Dublin Core), and citation_* mirrors what Google Scholar's
+ * indexing crawler consumes.
+ */
+export function parseGooglePatentsDetail(html: string): DetailPageFields {
+  const titleRaw =
+    extractMetaContent(html, "DC.title")[0] ??
+    extractMetaContent(html, "citation_title")[0];
+  const dcDates = extractMetaContent(html, "DC.date");
+  const dcContributors = extractMetaContent(html, "DC.contributor");
+
+  // DC.date is emitted twice on Google Patents: filing then publication.
+  const filingDate = dcDates[0];
+  const publicationDate = dcDates[1];
+
+  // DC.contributor mixes inventors (personal names) and assignees (org
+  // names). Google's convention is inventors first, the assignee last —
+  // approximate that, with the last-item-is-assignee heuristic.
+  const inventors: string[] = [];
+  let assignee: string | undefined;
+  if (dcContributors.length > 0) {
+    assignee = dcContributors[dcContributors.length - 1];
+    for (let i = 0; i < dcContributors.length - 1; i++) {
+      inventors.push(dcContributors[i]);
+    }
+  }
+
+  const applicationNumber = extractMetaContent(
+    html,
+    "citation_patent_application_number",
+  )[0];
+
+  // The bibliographic abstract sits in a single `<abstract …>...</abstract>`
+  // element. Use a non-greedy match because some pages embed multiple
+  // localised abstracts; we want the first.
+  let abstractText: string | undefined;
+  const abstractMatch = /<abstract\b[^>]*>([\s\S]*?)<\/abstract>/i.exec(html);
+  if (abstractMatch) {
+    const cleaned = stripHtml(abstractMatch[1]);
+    if (cleaned.length > 0) abstractText = cleaned;
+  }
+
+  return {
+    title: titleRaw ? titleRaw.trim() : undefined,
+    abstract: abstractText,
+    inventors,
+    assignees: assignee ? [assignee] : [],
+    filing_date: filingDate,
+    publication_date: publicationDate,
+    application_number: applicationNumber,
+  };
+}
+
+export async function runGooglePatentsWebGet(kwargs: {
+  publication_number?: unknown;
+}): Promise<unknown[]> {
+  const raw = String(kwargs.publication_number ?? "").trim();
+  if (raw.length === 0) {
+    return [
+      {
+        envelope: buildPatentEnvelope({
+          code: "PATENT_INVALID_NUMBER",
+          adapter_path: ADAPTER_PATH,
+          step: "validate",
+          suggestion:
+            "google-patents-web get requires a publication_number (e.g. US11741188B2)",
+        }),
+      },
+    ];
+  }
+  const url = buildGooglePatentsDetailUrl(raw);
+  let html: string;
+  try {
+    html = await fetchGooglePatentsHtml(url);
+  } catch (err) {
+    if (err instanceof GooglePatentsHttpError) {
+      return [
+        {
+          envelope: buildPatentEnvelope({
+            code:
+              err.status === 404 ? "PATENT_NOT_FOUND" : "PATENT_API_DEPRECATED",
+            adapter_path: ADAPTER_PATH,
+            step: "fetch",
+            suggestion: `Google Patents detail page returned HTTP ${err.status}; verify the publication number or retry against --sources espacenet`,
+            alternatives: ["espacenet", "freepatentsonline-web"],
+          }),
+        },
+      ];
+    }
+    throw err;
+  }
+  const detail = parseGooglePatentsDetail(html);
+  if (!detail.title) {
+    return [
+      {
+        envelope: buildPatentEnvelope({
+          code: "PATENT_NOT_FOUND",
+          adapter_path: ADAPTER_PATH,
+          step: "select",
+          suggestion: `google-patents-web detail page for "${raw}" yielded no DC.title meta tag`,
+          alternatives: ["espacenet", "freepatentsonline-web"],
+        }),
+      },
+    ];
+  }
+  try {
+    return [
+      assemblePatentRecord({
+        publication_number: raw,
+        application_number: detail.application_number || undefined,
+        title: detail.title,
+        abstract: detail.abstract,
+        inventors:
+          detail.inventors.length > 0
+            ? detail.inventors.map((name) => ({ name }))
+            : undefined,
+        assignees:
+          detail.assignees.length > 0
+            ? detail.assignees.map((name) => ({ name }))
+            : undefined,
+        filing_date: detail.filing_date,
+        publication_date: detail.publication_date,
+        source_adapter: "google-patents-web",
+        source_url: url,
+      } as Parameters<typeof assemblePatentRecord>[0]),
+    ];
+  } catch {
+    return [
+      {
+        envelope: buildPatentEnvelope({
+          code: "PATENT_NOT_FOUND",
+          adapter_path: ADAPTER_PATH,
+          step: "normalize",
+          suggestion: `google-patents-web detail page for "${raw}" did not yield a canonicalisable publication_number`,
+          alternatives: ["espacenet"],
+        }),
+      },
+    ];
+  }
+}
+
+cli({
+  site: "google-patents-web",
+  name: "get",
+  description:
+    "Retrieve a single Google Patents bibliographic record (keyless, no Chrome)",
+  domain: "patents.google.com",
+  strategy: Strategy.PUBLIC,
+  adapter_path: ADAPTER_PATH,
+  args: [
+    {
+      name: "publication_number",
+      type: "str",
+      required: true,
+      positional: true,
+      description:
+        "ST.16 publication number, compact or segmented (e.g. US11741188B2 or US-11741188-B2)",
+    },
+  ],
+  columns: [
+    "publication_number",
+    "title",
+    "publication_date",
+    "assignees",
+    "source_url",
+  ],
+  capabilities: ["http.fetch", "patent.get"],
+  minimum_capability: "http.fetch",
+  func: async (_page, kwargs) =>
+    runGooglePatentsWebGet(kwargs as { publication_number?: unknown }),
+});