@zenalexa/unicli 0.220.1 → 0.221.0

package/src/adapters/cnipa/search.ts

@@ -0,0 +1,229 @@
+/**
+ * @owner       src::adapters::cnipa::search
+ * @does        Browser-driven search of CNIPA 公众查询 system at pss-system.cponline.cnipa.gov.cn — the only programmatic route for CN patents (CNIPA has no open API today). Drives a real Chrome session via the mcp-browser transport, extracts result rows, normalizes through assemblePatentRecord.
+ * @needs       src/engine/transport/mcp-browser.ts, src/engine/normalizer/patent-envelope.ts, src/types/patent.ts, src/adapters/cnipa/_shared.ts, src/registry.ts
+ * @feeds       src/commands/patent.ts (meta-command discovers via patent.search capability tag)
+ * @breaks      emits PATENT_BROWSER_CAPTCHA envelope when zero rows return from a navigation that did not error (CNIPA almost always shows a captcha gate); emits PATENT_API_DEPRECATED with MCP_BUS_MISSING context when no outbound MCP transport is registered
+ * @invariants  result rows always include source_adapter='cnipa'; publication_number canonicalized via assemblePatentRecord; never returns a synthetic row when extraction fails
+ * @side-effects controls the user's Chrome browser via MCP; reads no env vars
+ * @perf        single navigation + one evaluate; ~2-5 s wall-clock when active
+ * @concurrency safe — every call opens a fresh tab via mcpBrowserNavigate
+ * @test        tests/unit/adapters/cnipa/search.test.ts
+ * @stability   experimental
+ * @since       2026-05-18
+ * @verification browser-only — no upstream API; gated on a live mcp-browser transport
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import { TransportError } from "../../engine/transport/mcp-browser.js";
+import { assemblePatentRecord } from "../../engine/normalizer/patent-envelope.js";
+import {
+  cnipaEnvelope,
+  looksLikeCaptcha,
+  navigateAndExtract,
+  transportErrorToEnvelope,
+} from "./_shared.js";
+
+const ADAPTER_PATH = "src/adapters/cnipa/search.ts";
+const CNIPA_SEARCH_URL =
+  "https://pss-system.cponline.cnipa.gov.cn/conventionalSearch";
+
+interface CnipaRow {
+  publication_number: string;
+  application_number?: string;
+  title?: string;
+  applicant?: string;
+  publication_date?: string;
+  filing_date?: string;
+  source_url?: string;
+}
+
+interface CnipaExtractResult {
+  rows: CnipaRow[];
+  html_marker?: string;
+}
+
+/**
+ * DOM extractor executed inside the page via mcp-browser. The selectors are
+ * the documented ones for the CNIPA 公众查询 result table; when CNIPA
+ * changes the markup an agent reads the failure envelope and updates the
+ * selector here (rule 02 self-repair).
+ */
+const EXTRACTOR = `(() => {
+  const rows = Array.from(
+    document.querySelectorAll('table.result-table tbody tr, .result-list .result-item')
+  ).map((el) => {
+    const text = (sel) => {
+      const node = el.querySelector(sel);
+      return node ? (node.textContent || '').trim() : '';
+    };
+    return {
+      publication_number: text('.publication-number, [data-field="pubNo"]'),
+      application_number: text('.application-number, [data-field="appNo"]'),
+      title: text('.title, [data-field="title"]'),
+      applicant: text('.applicant, [data-field="applicant"]'),
+      publication_date: text('.publication-date, [data-field="pubDate"]'),
+      filing_date: text('.filing-date, [data-field="appDate"]'),
+      source_url: (el.querySelector('a[href]') || {}).href || '',
+    };
+  });
+  const html_marker = (document.body && document.body.innerText
+    ? document.body.innerText.slice(0, 200)
+    : '');
+  return { rows, html_marker };
+})()`;
+
+function buildSearchUrl(query: string, limit: number, offset: number): string {
+  const params = new URLSearchParams({
+    q: query,
+    pageSize: String(limit),
+    pageNo: String(Math.floor(offset / Math.max(1, limit)) + 1),
+  });
+  return `${CNIPA_SEARCH_URL}?${params.toString()}`;
+}
+
+export async function runCnipaSearch(kwargs: {
+  query: string;
+  limit?: number;
+  offset?: number;
+}): Promise<unknown[]> {
+  const limit =
+    typeof kwargs.limit === "number" && Number.isFinite(kwargs.limit)
+      ? Math.max(1, Math.min(100, Math.floor(kwargs.limit)))
+      : 25;
+  const offset =
+    typeof kwargs.offset === "number" && Number.isFinite(kwargs.offset)
+      ? Math.max(0, Math.floor(kwargs.offset))
+      : 0;
+  const query = String(kwargs.query ?? "").trim();
+  if (query.length === 0) {
+    return [
+      {
+        envelope: cnipaEnvelope(
+          "PATENT_UNSUPPORTED_QUERY",
+          ADAPTER_PATH,
+          "validate",
+          "cnipa search requires a non-empty query string",
+        ),
+      },
+    ];
+  }
+  const url = buildSearchUrl(query, limit, offset);
+  let extract: CnipaExtractResult;
+  try {
+    const result = await navigateAndExtract<CnipaExtractResult>(url, EXTRACTOR);
+    if (!result.data) {
+      return [
+        {
+          envelope: cnipaEnvelope(
+            "PATENT_SCHEMA_DRIFT",
+            ADAPTER_PATH,
+            "evaluate",
+            "mcp-browser evaluate returned no data; check selector schema in src/adapters/cnipa/search.ts",
+          ),
+        },
+      ];
+    }
+    extract = result.data;
+  } catch (err) {
+    if (err instanceof TransportError) {
+      return [
+        {
+          envelope: transportErrorToEnvelope(err, ADAPTER_PATH, "navigate"),
+        },
+      ];
+    }
+    throw err;
+  }
+
+  if (looksLikeCaptcha(extract.rows.length, extract.html_marker)) {
+    return [
+      {
+        envelope: cnipaEnvelope(
+          "PATENT_BROWSER_CAPTCHA",
+          ADAPTER_PATH,
+          "evaluate",
+          "CNIPA returned no rows for a non-empty query; solve the 验证码 in the open browser tab and re-run",
+          ["espacenet", "lens"],
+        ),
+      },
+    ];
+  }
+
+  const out: unknown[] = [];
+  for (const row of extract.rows.slice(0, limit)) {
+    if (!row.publication_number) continue;
+    try {
+      out.push(
+        assemblePatentRecord({
+          publication_number: row.publication_number,
+          application_number: row.application_number || undefined,
+          title: row.title || undefined,
+          assignees: row.applicant
+            ? [{ name: row.applicant, country: "CN" }]
+            : undefined,
+          publication_date: row.publication_date || undefined,
+          filing_date: row.filing_date || undefined,
+          source_adapter: "cnipa",
+          source_url: row.source_url || url,
+        } as Parameters<typeof assemblePatentRecord>[0]),
+      );
+    } catch {
+      // Skip malformed row rather than synthesize — rule 02.
+    }
+  }
+  if (out.length === 0) {
+    out.push({
+      envelope: cnipaEnvelope(
+        "PATENT_NOT_FOUND",
+        ADAPTER_PATH,
+        "normalize",
+        "cnipa returned rows but none carried a publication_number; report as schema drift",
+        ["espacenet"],
+      ),
+    });
+  }
+  return out;
+}
+
+cli({
+  site: "cnipa",
+  name: "search",
+  description:
+    "Search CNIPA via the public 公众查询 browser interface (no API)",
+  domain: "pss-system.cponline.cnipa.gov.cn",
+  strategy: Strategy.PUBLIC,
+  adapter_path: ADAPTER_PATH,
+  args: [
+    {
+      name: "query",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Free-text query — matched against title/abstract/claims",
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 25,
+      description: "Maximum results to return (1-100)",
+    },
+    {
+      name: "offset",
+      type: "int",
+      default: 0,
+      description: "Result offset for pagination",
+    },
+  ],
+  columns: ["publication_number", "title", "publication_date", "source_url"],
+  capabilities: [
+    "mcp-browser.navigate",
+    "mcp-browser.evaluate",
+    "patent.search",
+  ],
+  minimum_capability: "mcp-browser.evaluate",
+  func: async (_page, kwargs) =>
+    runCnipaSearch(
+      kwargs as { query: string; limit?: number; offset?: number },
+    ),
+});

package/src/adapters/dpma/get.yaml

@@ -0,0 +1,67 @@
+# @owner       src::adapters::dpma::get
+# @does        Fetch a German patent record by publication number via DPMAconnectPlus REST.
+# @needs       src/engine/steps/fetch.ts, src/engine/steps/select-xml.ts, src/engine/steps/map.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on 401/403, 404, 5xx
+# @invariants  output row conforms to PatentRecord
+# @side-effects reads env DPMA_AUTHORIZATION; HTTPS egress to dpmaconnect.dpma.de
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-subscription
+site: dpma
+name: get
+description: Fetch a German patent record by publication number (subscription)
+domain: dpmaconnect.dpma.de
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  publication_number:
+    type: str
+    required: true
+    positional: true
+    description: German publication number (e.g. DE102023012345)
+
+pipeline:
+  - fetch:
+      url: "https://dpmaconnect.dpma.de/dpmaconnectplus/rest/document/${{ args.publication_number | urlencode }}"
+      method: GET
+      headers:
+        Accept: application/xml
+        Authorization: "${{ env.DPMA_AUTHORIZATION || '' }}"
+
+  - select-xml:
+      xpath: "//record"
+      unwrap_single: true
+
+  - map:
+      publication_number: "${{ 'DE-' + (item.publicationNumber || args.publication_number || '') + '-' + (item.kindCode || '') }}"
+      application_number: "${{ item.applicationNumber || '' }}"
+      title: "${{ item.title || item.titleDe || item.titleEn || '' }}"
+      abstract: "${{ item.abstract || item.abstractDe || item.abstractEn || '' }}"
+      kind_code: "${{ item.kindCode || '' }}"
+      filing_date: "${{ item.filingDate || '' }}"
+      publication_date: "${{ item.publicationDate || '' }}"
+      grant_date: "${{ item.grantDate || '' }}"
+      priority_date: "${{ item.priorityDate || '' }}"
+      legal_status: "${{ item.legalStatus || item.status || '' }}"
+      inventors: "${{ JSON.stringify((function(){ var i=item.inventor || item.inventors; if(!i) return []; var arr = Array.isArray(i) ? i : [i]; return arr.map(n => ({ name: typeof n === 'string' ? n : (n.name || n.fullName || ''), country: 'DE' })).filter(x => x.name); })()) }}"
+      assignees: "${{ JSON.stringify((function(){ var a=item.applicant || item.applicants; if(!a) return []; var arr = Array.isArray(a) ? a : [a]; return arr.map(n => ({ name: typeof n === 'string' ? n : (n.name || n.fullName || ''), country: 'DE' })).filter(x => x.name); })()) }}"
+      classifications: "${{ JSON.stringify((function(){ var c=item.ipc || item.classifications; if(!c) return []; var arr = Array.isArray(c) ? c : [c]; return arr.map(x => ({ scheme: 'ipc', code: typeof x === 'string' ? x : (x.code || '') })).filter(x => x.code); })()) }}"
+      source_adapter: dpma
+      source_url: "${{ 'https://register.dpma.de/DPMAregister/pat/register?AKZ=' + (item.applicationNumber || '') }}"
+      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/dpma/search.yaml

@@ -0,0 +1,77 @@
+# @owner       src::adapters::dpma::search
+# @does        Search German patents via the DPMAconnectPlus REST API (XML / OAI-PMH-style envelope).
+# @needs       src/engine/steps/fetch.ts, src/engine/steps/select-xml.ts, src/engine/steps/map.ts, src/engine/steps/limit.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on 401/403 (missing DPMA_AUTHORIZATION precomputed `Basic <base64>` header), 4xx, 5xx
+# @invariants  output rows conform to PatentRecord; publication_number is `DE-<doc>-<kind>`
+# @side-effects reads env DPMA_AUTHORIZATION (precomputed `Basic <base64(user:pass)>`); HTTPS egress to dpmaconnect.dpma.de
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-subscription — DPMAconnectPlus requires a paid connection contract (~200 EUR setup). Adapter ships so contracted users can run it; precompute `DPMA_AUTHORIZATION="Basic $(printf '%s:%s' "$USER" "$PASS" | base64)"` before invocation.
+site: dpma
+name: search
+description: Search German patents via DPMAconnectPlus REST (subscription)
+domain: dpmaconnect.dpma.de
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: DPMA query (free-text, mapped to title/abstract)
+  limit:
+    type: int
+    default: 25
+    description: Maximum results
+
+pipeline:
+  - fetch:
+      url: "https://dpmaconnect.dpma.de/dpmaconnectplus/rest/search/published"
+      method: GET
+      headers:
+        Accept: application/xml
+        Authorization: "${{ env.DPMA_AUTHORIZATION || '' }}"
+      params:
+        query: "${{ args.query }}"
+        maximumRecords: "${{ args.limit }}"
+        startRecord: "1"
+
+  - select-xml:
+      xpath: "//record"
+
+  # DPMAconnectPlus XML mirrors INPI / EPO field naming; preserve German
+  # script in title / abstract.
+  - map:
+      publication_number: "${{ 'DE-' + (item.publicationNumber || '') + '-' + (item.kindCode || '') }}"
+      application_number: "${{ item.applicationNumber || '' }}"
+      title: "${{ item.title || item.titleDe || item.titleEn || '' }}"
+      abstract: "${{ item.abstract || item.abstractDe || item.abstractEn || '' }}"
+      kind_code: "${{ item.kindCode || '' }}"
+      filing_date: "${{ item.filingDate || '' }}"
+      publication_date: "${{ item.publicationDate || '' }}"
+      grant_date: "${{ item.grantDate || '' }}"
+      priority_date: "${{ item.priorityDate || '' }}"
+      inventors: "${{ JSON.stringify((function(){ var i=item.inventor || item.inventors; if(!i) return []; var arr = Array.isArray(i) ? i : [i]; return arr.map(n => ({ name: typeof n === 'string' ? n : (n.name || n.fullName || ''), country: 'DE' })).filter(x => x.name); })()) }}"
+      assignees: "${{ JSON.stringify((function(){ var a=item.applicant || item.applicants; if(!a) return []; var arr = Array.isArray(a) ? a : [a]; return arr.map(n => ({ name: typeof n === 'string' ? n : (n.name || n.fullName || ''), country: 'DE' })).filter(x => x.name); })()) }}"
+      classifications: "${{ JSON.stringify((function(){ var c=item.ipc || item.classifications; if(!c) return []; var arr = Array.isArray(c) ? c : [c]; return arr.map(x => ({ scheme: 'ipc', code: typeof x === 'string' ? x : (x.code || '') })).filter(x => x.code); })()) }}"
+      source_adapter: dpma
+      source_url: "${{ 'https://register.dpma.de/DPMAregister/pat/register?AKZ=' + (item.applicationNumber || '') }}"
+      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/duckduckgo/search.yaml

@@ -0,0 +1,54 @@
+# DuckDuckGo Search — keyless HTML lite endpoint.
+#
+# verification_status: keyless-best-effort
+#
+# DuckDuckGo runs an Instant-Answer JSON API at api.duckduckgo.com that
+# returns disambiguation pages and zero web results, plus a lite HTML
+# search at https://html.duckduckgo.com/html that returns SSR result rows
+# without JS. We use the lite HTML path so a fresh user gets web results
+# with no token of any kind. DDG rate-limits aggressive scraping; the
+# adapter is for human-scale interactive use.
+site: duckduckgo
+name: search
+description: Search the public web via DuckDuckGo (no API key needed)
+type: web-api
+domain: html.duckduckgo.com
+strategy: public
+lint_listing_detail: skip
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Free-text web search query
+  limit:
+    type: int
+    default: 10
+    description: Maximum results returned (DDG lite caps at ~30 per page)
+
+pipeline:
+  - fetch_text:
+      url: "https://html.duckduckgo.com/html/?q=${{ args.query | url_encode }}"
+      headers:
+        User-Agent: "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"
+        Accept: "text/html,application/xhtml+xml"
+
+  - extract:
+      selector: "div.result"
+      fields:
+        title: "h2.result__title a"
+        url: "h2.result__title a@href"
+        snippet: "a.result__snippet"
+
+  - limit: ${{ args.limit }}
+
+columns: [title, url, snippet]
+
+# schema-v2 metadata
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/duckduckgo/suggest.yaml

@@ -0,0 +1,52 @@
+# DuckDuckGo Autocomplete — keyless JSON endpoint.
+#
+# verification_status: keyless-best-effort
+#
+# The autocomplete endpoint at https://duckduckgo.com/ac is the JSON used
+# by the DDG search box. No auth, no rate-limit gate at low volumes, and
+# returns a flat list of suggested completions for a prefix.
+site: duckduckgo
+name: suggest
+description: Get query autocompletion suggestions from DuckDuckGo
+type: web-api
+domain: duckduckgo.com
+strategy: public
+lint_listing_detail: skip
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Partial query prefix to autocomplete
+  limit:
+    type: int
+    default: 10
+    description: Maximum suggestions returned
+
+pipeline:
+  - fetch:
+      url: "https://duckduckgo.com/ac/"
+      params:
+        q: "${{ args.query }}"
+        type: list
+      headers:
+        User-Agent: "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"
+        Accept: "application/json"
+
+  - select: "1"
+
+  - map:
+      phrase: "${{ item }}"
+
+  - limit: ${{ args.limit }}
+
+columns: [phrase]
+
+# schema-v2 metadata
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/epo/family.yaml

@@ -0,0 +1,69 @@
+# @owner       src::adapters::epo::family
+# @does        Fetch INPADOC simple family for a publication via EPO Open Patent Services v3.2.
+# @needs       src/engine/steps/oauth2-token.ts, src/engine/steps/fetch.ts, src/engine/steps/select-xml.ts, src/engine/steps/map.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on token failure, 404, 401/403, 5xx
+# @invariants  output rows are family members in PatentRecord shape with `family_id` populated
+# @side-effects reads EPO OAuth2 credentials; HTTPS to ops.epo.org
+# @perf        two HTTPS requests
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key
+site: epo
+name: family
+description: INPADOC simple family for an EPO publication
+domain: ops.epo.org
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  publication_number:
+    type: str
+    required: true
+    positional: true
+    description: Publication number in epodoc format
+
+pipeline:
+  - oauth2-token:
+      site: epo
+      token_url: https://ops.epo.org/3.2/auth/accesstoken
+      client_id_env: EPO_OPS_CLIENT_ID
+      client_secret_env: EPO_OPS_CLIENT_SECRET
+
+  - fetch:
+      url: "https://ops.epo.org/3.2/rest-services/family/publication/epodoc/${{ args.publication_number | urlencode }}"
+      method: GET
+      headers:
+        Authorization: "Bearer ${{ auth.bearer || '' }}"
+        Accept: application/xml
+
+  - select-xml:
+      xpath: "//ops:family-member"
+      namespaces:
+        ops: "http://ops.epo.org"
+
+  # Family endpoint returns ops:family-member nodes with publication-reference,
+  # application-reference, and a `@family-id` attribute on each.
+  - map:
+      publication_number: "${{ ((item['publication-reference'] && item['publication-reference']['document-id']) ? (item['publication-reference']['document-id'].country + '-' + item['publication-reference']['document-id']['doc-number'] + '-' + (item['publication-reference']['document-id'].kind || '')) : '') }}"
+      application_number: "${{ ((item['application-reference'] && item['application-reference']['document-id']) ? (item['application-reference']['document-id'].country + '-' + item['application-reference']['document-id']['doc-number'] + '-' + (item['application-reference']['document-id'].kind || '')) : '') }}"
+      kind_code: "${{ (item['publication-reference'] && item['publication-reference']['document-id']) ? (item['publication-reference']['document-id'].kind || '') : '' }}"
+      publication_date: "${{ (function(d){ if(!d) return ''; var s=String(d); return s.length===8 ? (s.slice(0,4)+'-'+s.slice(4,6)+'-'+s.slice(6,8)) : s; })((item['publication-reference'] && item['publication-reference']['document-id']) ? item['publication-reference']['document-id'].date : '') }}"
+      filing_date: "${{ (function(d){ if(!d) return ''; var s=String(d); return s.length===8 ? (s.slice(0,4)+'-'+s.slice(4,6)+'-'+s.slice(6,8)) : s; })((item['application-reference'] && item['application-reference']['document-id']) ? item['application-reference']['document-id'].date : '') }}"
+      family_id: "${{ item['@_family-id'] || '' }}"
+      source_adapter: epo
+      source_url: "${{ 'https://worldwide.espacenet.com/patent/search/family/' + (item['@_family-id'] || '') }}"
+      retrieved_at: ""
+
+columns: [publication_number, family_id]
+
+# schema-v2 metadata
+capabilities: ["http.fetch", "patent.family"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/epo/get.yaml

@@ -0,0 +1,74 @@
+# @owner       src::adapters::epo::get
+# @does        Fetch DOCDB biblio for a single EPO publication number via Open Patent Services v3.2.
+# @needs       src/engine/steps/oauth2-token.ts, src/engine/steps/fetch.ts, src/engine/steps/select-xml.ts, src/engine/steps/map.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on token failure, 404 (unknown publication), 401/403, 5xx
+# @invariants  output row conforms to PatentRecord
+# @side-effects reads EPO OAuth2 credentials; HTTPS to ops.epo.org
+# @perf        two HTTPS requests (token + data); cached token
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key
+site: epo
+name: get
+description: Fetch EPO DOCDB biblio for a single publication number
+domain: ops.epo.org
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  publication_number:
+    type: str
+    required: true
+    positional: true
+    description: Publication number in epodoc format (e.g. EP.4123456.A1 or US.20240123456.A1)
+
+pipeline:
+  - oauth2-token:
+      site: epo
+      token_url: https://ops.epo.org/3.2/auth/accesstoken
+      client_id_env: EPO_OPS_CLIENT_ID
+      client_secret_env: EPO_OPS_CLIENT_SECRET
+
+  - fetch:
+      url: "https://ops.epo.org/3.2/rest-services/published-data/publication/epodoc/${{ args.publication_number | urlencode }}/biblio"
+      method: GET
+      headers:
+        Authorization: "Bearer ${{ auth.bearer || '' }}"
+        Accept: application/xml
+
+  - select-xml:
+      xpath: "//ops:exchange-document"
+      namespaces:
+        ops: "http://ops.epo.org"
+
+  # Same DOCDB envelope as search; richer biblio fields are present.
+  - map:
+      publication_number: "${{ ((item['bibliographic-data'] && item['bibliographic-data']['publication-reference'] && item['bibliographic-data']['publication-reference']['document-id']) ? (item['bibliographic-data']['publication-reference']['document-id'].country + '-' + item['bibliographic-data']['publication-reference']['document-id']['doc-number'] + '-' + (item['bibliographic-data']['publication-reference']['document-id'].kind || '')) : (args.publication_number || '')) }}"
+      application_number: "${{ ((item['bibliographic-data'] && item['bibliographic-data']['application-reference'] && item['bibliographic-data']['application-reference']['document-id']) ? (item['bibliographic-data']['application-reference']['document-id'].country + '-' + item['bibliographic-data']['application-reference']['document-id']['doc-number'] + '-' + (item['bibliographic-data']['application-reference']['document-id'].kind || '')) : '') }}"
+      title: "${{ (function(t){ if(!t) return ''; if(Array.isArray(t)){ var en=t.find(x=>x['@_lang']==='en'); return en ? (en['#text']||en) : (t[0]['#text']||t[0]); } return t['#text']||t; })(item['bibliographic-data'] ? item['bibliographic-data']['invention-title'] : null) }}"
+      abstract: "${{ (function(a){ if(!a) return ''; if(Array.isArray(a)){ var en=a.find(x=>x['@_lang']==='en'); return en ? ((en.p ? (en.p['#text']||en.p) : (en['#text']||en))) : ''; } return a.p ? (a.p['#text']||a.p) : (a['#text']||a); })(item.abstract) }}"
+      kind_code: "${{ (item['bibliographic-data'] && item['bibliographic-data']['publication-reference'] && item['bibliographic-data']['publication-reference']['document-id']) ? (item['bibliographic-data']['publication-reference']['document-id'].kind || '') : '' }}"
+      publication_date: "${{ (function(d){ if(!d) return ''; var s=String(d); return s.length===8 ? (s.slice(0,4)+'-'+s.slice(4,6)+'-'+s.slice(6,8)) : s; })((item['bibliographic-data'] && item['bibliographic-data']['publication-reference'] && item['bibliographic-data']['publication-reference']['document-id']) ? item['bibliographic-data']['publication-reference']['document-id'].date : '') }}"
+      filing_date: "${{ (function(d){ if(!d) return ''; var s=String(d); return s.length===8 ? (s.slice(0,4)+'-'+s.slice(4,6)+'-'+s.slice(6,8)) : s; })((item['bibliographic-data'] && item['bibliographic-data']['application-reference'] && item['bibliographic-data']['application-reference']['document-id']) ? item['bibliographic-data']['application-reference']['document-id'].date : '') }}"
+      priority_date: "${{ (function(){ var pc = item['bibliographic-data'] && item['bibliographic-data']['priority-claims']; if(!pc || !pc['priority-claim']) return ''; var arr = Array.isArray(pc['priority-claim']) ? pc['priority-claim'] : [pc['priority-claim']]; for (var i=0;i<arr.length;i++){ var did = arr[i]['document-id']; if(Array.isArray(did)){ for (var j=0;j<did.length;j++){ if(did[j].date){ var s=String(did[j].date); return s.length===8 ? (s.slice(0,4)+'-'+s.slice(4,6)+'-'+s.slice(6,8)) : s; } } } else if(did && did.date){ var s=String(did.date); return s.length===8 ? (s.slice(0,4)+'-'+s.slice(4,6)+'-'+s.slice(6,8)) : s; } } return ''; })() }}"
+      inventors: "${{ JSON.stringify((function(){ var p=item['bibliographic-data'] && item['bibliographic-data'].parties; if(!p || !p.inventors || !p.inventors.inventor) return []; var arr = Array.isArray(p.inventors.inventor) ? p.inventors.inventor : [p.inventors.inventor]; return arr.map(i => ({ name: (i['inventor-name'] && (i['inventor-name'].name || i['inventor-name']['#text'])) || '' })).filter(x => x.name); })()) }}"
+      assignees: "${{ JSON.stringify((function(){ var p=item['bibliographic-data'] && item['bibliographic-data'].parties; if(!p || !p.applicants || !p.applicants.applicant) return []; var arr = Array.isArray(p.applicants.applicant) ? p.applicants.applicant : [p.applicants.applicant]; return arr.map(i => ({ name: (i['applicant-name'] && (i['applicant-name'].name || i['applicant-name']['#text'])) || '' })).filter(x => x.name); })()) }}"
+      classifications: "${{ JSON.stringify((function(){ var bd = item['bibliographic-data']; if(!bd) return []; var out = []; var ipcr = bd['classifications-ipcr'] && bd['classifications-ipcr']['classification-ipcr']; if(ipcr){ var arr = Array.isArray(ipcr) ? ipcr : [ipcr]; for (var i=0;i<arr.length;i++) out.push({ scheme: 'ipc', code: arr[i].text || arr[i]['#text'] || '' }); } var pc = bd['patent-classifications'] && bd['patent-classifications']['patent-classification']; if(pc){ var arr2 = Array.isArray(pc) ? pc : [pc]; for (var i=0;i<arr2.length;i++){ var c=arr2[i]; var scheme=(c['classification-scheme'] && (c['classification-scheme']['@_scheme']||'')).toLowerCase()||'cpc'; var section=(c.section||'')+(c.class||'')+(c.subclass||''); var main=(c['main-group']||'')+(c['subgroup']?'/'+c.subgroup:''); out.push({ scheme: scheme, code: (section+main) }); } } return out.filter(x => x.code); })()) }}"
+      family_id: "${{ item['@_family-id'] || '' }}"
+      source_adapter: epo
+      source_url: "${{ 'https://worldwide.espacenet.com/patent/search/publication/' + (args.publication_number || '') }}"
+      retrieved_at: ""
+
+columns: [publication_number, title]
+
+# schema-v2 metadata
+capabilities: ["http.fetch", "patent.get"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2