@zenalexa/unicli 0.220.1 → 0.221.0

package/src/adapters/freepatentsonline-web/get.ts

@@ -0,0 +1,144 @@
+/**
+ * @owner       src::adapters::freepatentsonline-web::get
+ * @does        Keyless single-publication detail fetch from FreePatentsOnline — parses the SSR detail page label/value blocks plus the disp_elm_name_kcode kind-code island so we can canonicalise the publication number even for bare-id US grants where the search-listing URL alone was ambiguous.
+ * @needs       src/adapters/freepatentsonline-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 no Title is parseable; PATENT_INVALID_NUMBER for empty input; PATENT_API_DEPRECATED on non-2xx HTTP
+ * @invariants  output is a single canonical PatentRecord whenever both the document-type label and kind code are present; otherwise emit PATENT_SCHEMA_DRIFT rather than canonicalise from an era heuristic
+ * @side-effects HTTPS egress to www.freepatentsonline.com only
+ * @perf        single page fetch (~130 KB); regex parse 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 {
+  FpoHttpError,
+  buildFpoDetailUrl,
+  fetchFpoHtml,
+  parseFpoDetail,
+  reconstructCanonicalPubNo,
+} from "./_shared.js";
+
+const ADAPTER_PATH = "src/adapters/freepatentsonline-web/get.ts";
+
+interface GetArgs {
+  publication_number?: unknown;
+}
+
+export async function runFreePatentsOnlineGet(
+  kwargs: GetArgs,
+): 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: "freepatentsonline-web get requires a publication_number",
+        }),
+      },
+    ];
+  }
+  const url = buildFpoDetailUrl(raw);
+  let html: string;
+  try {
+    html = await fetchFpoHtml(url);
+  } catch (err) {
+    if (err instanceof FpoHttpError) {
+      return [
+        {
+          envelope: buildPatentEnvelope({
+            code:
+              err.status === 404 ? "PATENT_NOT_FOUND" : "PATENT_API_DEPRECATED",
+            adapter_path: ADAPTER_PATH,
+            step: "fetch",
+            suggestion: `FreePatentsOnline returned HTTP ${err.status} for ${err.url}`,
+            alternatives: ["google-patents-web", "espacenet"],
+          }),
+        },
+      ];
+    }
+    throw err;
+  }
+  const detail = parseFpoDetail(html);
+  if (!detail.title) {
+    return [
+      {
+        envelope: buildPatentEnvelope({
+          code: "PATENT_NOT_FOUND",
+          adapter_path: ADAPTER_PATH,
+          step: "select",
+          suggestion: `freepatentsonline-web detail page for "${raw}" yielded no Title field`,
+          alternatives: ["google-patents-web", "espacenet"],
+        }),
+      },
+    ];
+  }
+  const canonical =
+    reconstructCanonicalPubNo(detail.doc_type_label, detail.kind_code) ?? raw;
+  try {
+    return [
+      assemblePatentRecord({
+        publication_number: canonical,
+        application_number: detail.application_number || undefined,
+        title: detail.title,
+        abstract: detail.abstract,
+        assignees: detail.assignee ? [{ name: detail.assignee }] : undefined,
+        filing_date: detail.filing_date,
+        publication_date: detail.publication_date,
+        source_adapter: "freepatentsonline-web",
+        source_url: url,
+      } as Parameters<typeof assemblePatentRecord>[0]),
+    ];
+  } catch {
+    return [
+      {
+        envelope: buildPatentEnvelope({
+          code: "PATENT_SCHEMA_DRIFT",
+          adapter_path: ADAPTER_PATH,
+          step: "normalize",
+          suggestion: `freepatentsonline-web detail page for "${raw}" did not yield a canonicalisable publication_number (doc_type=${detail.doc_type_label}; kind_code=${detail.kind_code})`,
+          alternatives: ["google-patents-web", "espacenet"],
+        }),
+      },
+    ];
+  }
+}
+
+cli({
+  site: "freepatentsonline-web",
+  name: "get",
+  description:
+    "Retrieve a single FreePatentsOnline bibliographic record (keyless, no Chrome)",
+  domain: "www.freepatentsonline.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. US20240220787 or EP3716153A1)",
+    },
+  ],
+  columns: [
+    "publication_number",
+    "title",
+    "publication_date",
+    "assignees",
+    "source_url",
+  ],
+  capabilities: ["http.fetch", "patent.get"],
+  minimum_capability: "http.fetch",
+  func: async (_page, kwargs) => runFreePatentsOnlineGet(kwargs as GetArgs),
+});

package/src/adapters/freepatentsonline-web/search.ts

@@ -0,0 +1,170 @@
+/**
+ * @owner       src::adapters::freepatentsonline-web::search
+ * @does        Keyless patent search via www.freepatentsonline.com's SSR `result.html` listing — older site, still maintained, no JS gate, no auth. Complements google-patents-web as a second day-zero source.
+ * @needs       src/adapters/freepatentsonline-web/_shared.ts, src/engine/normalizer/patent-envelope.ts, src/registry.ts
+ * @feeds       src/commands/patent.ts (capability tag patent.search)
+ * @breaks      PATENT_API_DEPRECATED on non-2xx HTTP; PATENT_NOT_FOUND on empty listing; PATENT_SCHEMA_DRIFT when the listing_table selector no longer matches
+ * @invariants  output rows are canonical PatentRecord; publication_number is decoded from the FPO link path (URL-encoded structural signal) — rows whose link does not encode a kind code are dropped, never fabricated
+ * @side-effects HTTPS egress to www.freepatentsonline.com only
+ * @perf        single page fetch (~50 KB); FPO returns 50 results per page
+ * @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 {
+  FpoHttpError,
+  buildFpoSearchUrl,
+  fetchFpoHtml,
+  parseFpoListing,
+} from "./_shared.js";
+
+const ADAPTER_PATH = "src/adapters/freepatentsonline-web/search.ts";
+
+interface SearchArgs {
+  query?: unknown;
+  limit?: unknown;
+}
+
+function clampLimit(raw: unknown): number {
+  const num = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(num) || num <= 0) return 25;
+  return Math.min(50, Math.max(1, Math.floor(num)));
+}
+
+export async function runFreePatentsOnlineSearch(
+  kwargs: SearchArgs,
+): Promise<unknown[]> {
+  const query = String(kwargs.query ?? "").trim();
+  if (query.length === 0) {
+    return [
+      {
+        envelope: buildPatentEnvelope({
+          code: "PATENT_UNSUPPORTED_QUERY",
+          adapter_path: ADAPTER_PATH,
+          step: "validate",
+          suggestion: "freepatentsonline-web search requires a non-empty query",
+          alternatives: ["google-patents-web"],
+        }),
+      },
+    ];
+  }
+  const limit = clampLimit(kwargs.limit);
+  const url = buildFpoSearchUrl(query, 1);
+  let html: string;
+  try {
+    html = await fetchFpoHtml(url);
+  } catch (err) {
+    if (err instanceof FpoHttpError) {
+      return [
+        {
+          envelope: buildPatentEnvelope({
+            code:
+              err.status === 429
+                ? "PATENT_RATE_LIMIT"
+                : "PATENT_API_DEPRECATED",
+            adapter_path: ADAPTER_PATH,
+            step: "fetch",
+            suggestion: `FreePatentsOnline returned HTTP ${err.status} for ${err.url}; retry with --sources google-patents-web`,
+            alternatives: ["google-patents-web", "espacenet"],
+            retryable: err.status === 429,
+          }),
+        },
+      ];
+    }
+    throw err;
+  }
+
+  const rows = parseFpoListing(html);
+  if (rows.length === 0) {
+    return [
+      {
+        envelope: buildPatentEnvelope({
+          code: html.includes('class="listing_table"')
+            ? "PATENT_NOT_FOUND"
+            : "PATENT_SCHEMA_DRIFT",
+          adapter_path: ADAPTER_PATH,
+          step: "select",
+          suggestion: html.includes('class="listing_table"')
+            ? `freepatentsonline-web returned no listing rows for "${query}"`
+            : "freepatentsonline-web no longer ships listing_table — the parseFpoListing extractor needs updating",
+          alternatives: ["google-patents-web", "espacenet"],
+        }),
+      },
+    ];
+  }
+
+  const out: unknown[] = [];
+  for (const row of rows.slice(0, limit)) {
+    const canonical = row.publication_number_canonical;
+    if (!canonical) {
+      // Row's link path did not encode a kind code (e.g. bare US grant
+      // number). Skip rather than fabricate.
+      continue;
+    }
+    try {
+      out.push(
+        assemblePatentRecord({
+          publication_number: canonical,
+          title: row.title || undefined,
+          abstract: row.abstract || undefined,
+          source_adapter: "freepatentsonline-web",
+          source_url: row.detail_url,
+        } as Parameters<typeof assemblePatentRecord>[0]),
+      );
+    } catch {
+      // Defensive: skip rows that fail canonicalisation rather than
+      // synthesise.
+    }
+  }
+
+  if (out.length === 0) {
+    return [
+      {
+        envelope: buildPatentEnvelope({
+          code: "PATENT_NOT_FOUND",
+          adapter_path: ADAPTER_PATH,
+          step: "normalize",
+          suggestion: `freepatentsonline-web returned ${rows.length} listing rows but none had a structurally decodable kind code; run \`unicli freepatentsonline-web get <pub_no>\` against an individual hit to retrieve its kind code from the detail page`,
+          alternatives: ["google-patents-web", "espacenet"],
+        }),
+      },
+    ];
+  }
+  return out;
+}
+
+cli({
+  site: "freepatentsonline-web",
+  name: "search",
+  description:
+    "Keyless FreePatentsOnline search via the public SSR listing (no API key, no Chrome)",
+  domain: "www.freepatentsonline.com",
+  strategy: Strategy.PUBLIC,
+  adapter_path: ADAPTER_PATH,
+  args: [
+    {
+      name: "query",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Free-text query (FreePatentsOnline xprtsrch syntax)",
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 25,
+      description: "Max results to return (1-50, FPO paginates at 50)",
+    },
+  ],
+  columns: ["publication_number", "title", "abstract", "source_url"],
+  capabilities: ["http.fetch", "patent.search"],
+  minimum_capability: "http.fetch",
+  func: async (_page, kwargs) =>
+    runFreePatentsOnlineSearch(kwargs as SearchArgs),
+});

package/src/adapters/google-patents-bq/prior-art.yaml

@@ -0,0 +1,80 @@
+# Google Patents BigQuery — keyword-based prior-art fan-out.
+#
+# verification_status: blocked-by-key
+#
+# This command is the keyword arm of `unicli patent prior-art`. It tokenises
+# the abstract argument into noun phrases (handled by the substring LIKE
+# template) and joins against the publication table, returning the top-N
+# candidates by recency. The full fusion happens in `unicli patent prior-art`,
+# which combines this with PQAI semantic embedding and EPO CPC classification.
+site: google-patents-bq
+name: prior-art
+description: Keyword-arm of the prior-art fusion against BigQuery public dataset
+domain: bigquery.googleapis.com
+type: web-api
+strategy: header
+
+args:
+  abstract:
+    type: str
+    required: true
+    description: Candidate abstract — long-form natural language
+  limit:
+    type: int
+    default: 20
+  project:
+    type: str
+    default: ""
+
+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(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(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
+          FROM `patents-public-data.patents.publications`
+          WHERE LOWER(abstract_localized[OFFSET(0)].text) LIKE LOWER('%${{ args.abstract | truncate(80) }}%')
+          GROUP BY publication_number
+          ORDER BY ANY_VALUE(publication_date) DESC
+          LIMIT ${{ args.limit }}
+        useLegacySql: false
+
+  - select: rows
+
+  - map:
+      publication_number: "${{ item.f[0].v }}"
+      kind_code: "${{ item.f[1].v || '' }}"
+      title: "${{ item.f[2].v }}"
+      abstract: "${{ item.f[3].v }}"
+      publication_date: "${{ item.f[4].v }}"
+      filing_date: "${{ item.f[5].v }}"
+      family_id: "${{ item.f[6].v }}"
+      inventors: "${{ JSON.stringify((function(){ try { var arr = JSON.parse(item.f[7].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[8].v || '[]'); return Array.isArray(arr) ? arr.map(a => ({ name: a.name || a, country: a.country_code || undefined })) : []; } catch(e) { return []; } })()) }}"
+      classifications: "${{ JSON.stringify((function(){ try { var cpc = JSON.parse(item.f[9].v || '[]'); return Array.isArray(cpc) ? cpc.map(c => ({ scheme: 'cpc', code: c.code || c })).filter(x => x.code) : []; } catch(e){ return []; } })()) }}"
+      source_adapter: google-patents-bq
+      source_url: "${{ 'https://patents.google.com/patent/' + (item.f[0].v || '') }}"
+      retrieved_at: "${{ now }}"
+
+columns: [publication_number, title, abstract]
+
+capabilities: ["http.fetch", "patent.prior-art"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

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