@zenalexa/unicli 0.220.0 → 0.221.0

package/dist/adapters/freepatentsonline-web/search.js

@@ -0,0 +1,149 @@
+/**
+ * @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";
+function clampLimit(raw) {
+    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) {
+    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;
+    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 = [];
+    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,
+            }));
+        }
+        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),
+});
+//# sourceMappingURL=search.js.map

package/dist/adapters/freepatentsonline-web/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../src/adapters/freepatentsonline-web/search.ts"],"names":[],"mappings":"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"}

package/dist/adapters/google-patents-web/_shared.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @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 declare const KEYLESS_BEST_EFFORT: KeylessBestEffortStatus;
+/**
+ * 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 declare 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 declare class GooglePatentsHttpError extends Error {
+    readonly status: number;
+    readonly url: string;
+    constructor(status: number, url: string, message: string);
+}
+/**
+ * GET <url> with a real-browser UA. Returns parsed JSON; throws
+ * GooglePatentsHttpError on non-2xx or JSON parse failure.
+ */
+export declare function fetchGooglePatentsJson<T>(url: string): Promise<T>;
+/**
+ * GET <url> with a real-browser UA, return raw HTML text. Throws
+ * GooglePatentsHttpError on non-2xx.
+ */
+export declare function fetchGooglePatentsHtml(url: string): Promise<string>;
+/**
+ * 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 declare function buildGooglePatentsXhrUrl(query: string, limit?: number, sinceYear?: string): string;
+/**
+ * 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 declare function buildGooglePatentsDetailUrl(pubNo: string): string;
+/**
+ * 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 declare function flattenGoogleXhrResults(body: GoogleXhrResponse): GoogleXhrResultRow[];
+/**
+ * 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 declare function projectGoogleRowToRecord(row: GoogleXhrResultRow, sourceUrl: string): Partial<PatentRecord> & {
+    publication_number: string;
+    source_adapter: string;
+};
+export declare function stripHtml(input: string): string;
+//# sourceMappingURL=_shared.d.ts.map

package/dist/adapters/google-patents-web/_shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_shared.d.ts","sourceRoot":"","sources":["../../../src/adapters/google-patents-web/_shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D;;;;;;;;;GASG;AACH,MAAM,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAC5D,eAAO,MAAM,mBAAmB,EAAE,uBACX,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,0HAC2F,CAAC;AAE1H,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,MAAM,EAAE,MAAM;aACd,GAAG,EAAE,MAAM;gBADX,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EAC3B,OAAO,EAAE,MAAM;CAKlB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CA0BvE;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBzE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAUR;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjE;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE;QACP,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,KAAK,CAAC;YAAE,MAAM,CAAC,EAAE,kBAAkB,EAAE,CAAA;SAAE,CAAC,CAAC;QACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,iBAAiB,GACtB,kBAAkB,EAAE,CAQtB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,kBAAkB,EACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,YAAY,CAAC,GAAG;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;CACxB,CAoBA;AAmBD,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM/C"}

package/dist/adapters/google-patents-web/_shared.js

@@ -0,0 +1,164 @@
+/**
+ * @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
+ */
+export const KEYLESS_BEST_EFFORT = "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 {
+    status;
+    url;
+    constructor(status, url, message) {
+        super(message);
+        this.status = status;
+        this.url = url;
+        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(url) {
+    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;
+    try {
+        parsed = await response.json();
+    }
+    catch (err) {
+        throw new GooglePatentsHttpError(response.status, url, `Google Patents XHR returned non-JSON body: ${err.message}`);
+    }
+    return parsed;
+}
+/**
+ * GET <url> with a real-browser UA, return raw HTML text. Throws
+ * GooglePatentsHttpError on non-2xx.
+ */
+export async function fetchGooglePatentsHtml(url) {
+    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, limit, sinceYear) {
+    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) {
+    const compact = pubNo.replace(/-/g, "").toUpperCase();
+    return `https://patents.google.com/patent/${encodeURIComponent(compact)}/en`;
+}
+/**
+ * Flatten the nested `results.cluster[].result[]` into a single array, in
+ * server-supplied order.
+ */
+export function flattenGoogleXhrResults(body) {
+    const clusters = body.results?.cluster ?? [];
+    const out = [];
+    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, sourceUrl) {
+    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) {
+    const match = /patent\/([^/]+)/.exec(id);
+    return match ? match[1] : id;
+}
+const TAG_RE = /<[^>]+>/g;
+const ENTITY_MAP = {
+    "&amp;": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&quot;": '"',
+    "&#39;": "'",
+    "&hellip;": "…",
+    "&nbsp;": " ",
+};
+export function stripHtml(input) {
+    return input
+        .replace(TAG_RE, "")
+        .replace(/&(?:amp|lt|gt|quot|#39|hellip|nbsp);/g, (m) => ENTITY_MAP[m] ?? m)
+        .replace(/\s+/g, " ")
+        .trim();
+}
+//# sourceMappingURL=_shared.js.map

package/dist/adapters/google-patents-web/_shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_shared.js","sourceRoot":"","sources":["../../../src/adapters/google-patents-web/_shared.ts"],"names":[],"mappings":"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"}

package/dist/adapters/google-patents-web/get.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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
+ */
+interface DetailPageFields {
+    title?: string;
+    abstract?: string;
+    inventors: string[];
+    assignees: string[];
+    filing_date?: string;
+    publication_date?: string;
+    application_number?: string;
+}
+/**
+ * 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 declare function parseGooglePatentsDetail(html: string): DetailPageFields;
+export declare function runGooglePatentsWebGet(kwargs: {
+    publication_number?: unknown;
+}): Promise<unknown[]>;
+export {};
+//# sourceMappingURL=get.d.ts.map

package/dist/adapters/google-patents-web/get.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get.d.ts","sourceRoot":"","sources":["../../../src/adapters/google-patents-web/get.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAcH,UAAU,gBAAgB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAeD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CA+CvE;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAoFrB"}