@zenalexa/unicli 0.220.1 → 0.221.1

package/src/adapters/inpi-br/search.ts

@@ -0,0 +1,206 @@
+/**
+ * @owner       src::adapters::inpi-br::search
+ * @does        Browser-driven INPI Brasil search at busca.inpi.gov.br/pePI/ — Brazil's patent office has no open API (pre-API status); the public web search is the only programmatic surface.
+ * @needs       src/engine/transport/mcp-browser.ts, src/engine/normalizer/patent-envelope.ts, src/adapters/inpi-br/_shared.ts, src/registry.ts
+ * @feeds       src/commands/patent.ts (capability tag patent.search)
+ * @breaks      PATENT_UNSUPPORTED_QUERY (empty), PATENT_NOT_FOUND (no rows), PATENT_API_DEPRECATED with MCP_BUS_MISSING
+ * @invariants  output rows canonicalized into PatentRecord with source_adapter='inpi-br'
+ * @side-effects controls Chrome via MCP
+ * @perf        single navigate + evaluate
+ * @concurrency safe
+ * @test        tests/unit/adapters/inpi-br/search.test.ts
+ * @stability   experimental
+ * @since       2026-05-18
+ * @verification browser-only
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import { TransportError } from "../../engine/transport/mcp-browser.js";
+import { assemblePatentRecord } from "../../engine/normalizer/patent-envelope.js";
+import {
+  inpiBrEnvelope,
+  inpiBrNavigateAndExtract,
+  transportErrorToInpiBrEnvelope,
+} from "./_shared.js";
+
+const ADAPTER_PATH = "src/adapters/inpi-br/search.ts";
+const INPI_BR_SEARCH_URL =
+  "https://busca.inpi.gov.br/pePI/servlet/PatenteServletController";
+
+interface InpiBrRow {
+  publication_number: string;
+  title?: string;
+  applicant?: string;
+  publication_date?: string;
+  filing_date?: string;
+  source_url?: string;
+}
+
+const EXTRACTOR = `(() => {
+  const rows = Array.from(
+    document.querySelectorAll('table.tabela tr.linha, table tr[bgcolor]')
+  ).map((el) => {
+    const text = (sel) => {
+      const node = el.querySelector(sel);
+      return node ? (node.textContent || '').trim() : '';
+    };
+    const cells = Array.from(el.querySelectorAll('td')).map((td) => (td.textContent || '').trim());
+    const linkEl = el.querySelector('a[href]');
+    return {
+      publication_number: text('td.num-pedido, td:first-child') || (cells[0] || ''),
+      title: text('td.titulo, td:nth-child(3)') || (cells[2] || ''),
+      applicant: text('td.depositante, td:nth-child(4)') || (cells[3] || ''),
+      publication_date: text('td.data-pub, td:nth-child(5)') || (cells[4] || ''),
+      filing_date: text('td.data-dep, td:nth-child(2)') || (cells[1] || ''),
+      source_url: linkEl ? linkEl.href : '',
+    };
+  });
+  return { rows };
+})()`;
+
+function buildSearchUrl(query: string): string {
+  const params = new URLSearchParams({
+    Action: "searchPatente",
+    ExpressaoPesquisa: query,
+  });
+  return `${INPI_BR_SEARCH_URL}?${params.toString()}`;
+}
+
+export async function runInpiBrSearch(kwargs: {
+  query: string;
+  limit?: 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 query = String(kwargs.query ?? "").trim();
+  if (query.length === 0) {
+    return [
+      {
+        envelope: inpiBrEnvelope(
+          "PATENT_UNSUPPORTED_QUERY",
+          ADAPTER_PATH,
+          "validate",
+          "inpi-br search requires a non-empty query",
+        ),
+      },
+    ];
+  }
+  const url = buildSearchUrl(query);
+  let extract: { rows: InpiBrRow[] };
+  try {
+    const result = await inpiBrNavigateAndExtract<{ rows: InpiBrRow[] }>(
+      url,
+      EXTRACTOR,
+    );
+    if (!result.data) {
+      return [
+        {
+          envelope: inpiBrEnvelope(
+            "PATENT_SCHEMA_DRIFT",
+            ADAPTER_PATH,
+            "evaluate",
+            "inpi-br evaluate returned no data; selectors likely drifted",
+          ),
+        },
+      ];
+    }
+    extract = result.data;
+  } catch (err) {
+    if (err instanceof TransportError) {
+      return [
+        {
+          envelope: transportErrorToInpiBrEnvelope(
+            err,
+            ADAPTER_PATH,
+            "navigate",
+          ),
+        },
+      ];
+    }
+    throw err;
+  }
+  if (extract.rows.length === 0) {
+    return [
+      {
+        envelope: inpiBrEnvelope(
+          "PATENT_NOT_FOUND",
+          ADAPTER_PATH,
+          "evaluate",
+          `inpi-br returned no rows for query "${query}"`,
+          ["espacenet", "lens"],
+        ),
+      },
+    ];
+  }
+  const out: unknown[] = [];
+  for (const row of extract.rows.slice(0, limit)) {
+    if (!row.publication_number) continue;
+    const normalizedPub = /^BR[-]?/.test(row.publication_number)
+      ? row.publication_number
+      : `BR${row.publication_number}`;
+    try {
+      out.push(
+        assemblePatentRecord({
+          publication_number: normalizedPub,
+          title: row.title || undefined,
+          assignees: row.applicant
+            ? [{ name: row.applicant, country: "BR" }]
+            : undefined,
+          publication_date: row.publication_date || undefined,
+          filing_date: row.filing_date || undefined,
+          source_adapter: "inpi-br",
+          source_url: row.source_url || url,
+        } as Parameters<typeof assemblePatentRecord>[0]),
+      );
+    } catch {
+      // Skip malformed rows.
+    }
+  }
+  if (out.length === 0) {
+    out.push({
+      envelope: inpiBrEnvelope(
+        "PATENT_NOT_FOUND",
+        ADAPTER_PATH,
+        "normalize",
+        "inpi-br returned rows but none normalized to a valid publication_number",
+        ["espacenet"],
+      ),
+    });
+  }
+  return out;
+}
+
+cli({
+  site: "inpi-br",
+  name: "search",
+  description: "Search INPI Brasil patents (browser-only, no upstream API)",
+  domain: "busca.inpi.gov.br",
+  strategy: Strategy.PUBLIC,
+  adapter_path: ADAPTER_PATH,
+  args: [
+    {
+      name: "query",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Free-text query for INPI Brasil patent search",
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 25,
+      description: "Max results (1-100)",
+    },
+  ],
+  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) =>
+    runInpiBrSearch(kwargs as { query: string; limit?: number }),
+});

package/src/adapters/inpi-fr/get.yaml

@@ -0,0 +1,62 @@
+# @owner       src::adapters::inpi-fr::get
+# @does        Fetch a French patent record by publication number via the INPI public open-data API.
+# @needs       src/engine/steps/fetch.ts, src/engine/steps/map.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on 404 or 5xx; some legal-status / inventor fields require an INPI session-login this adapter does not perform
+# @invariants  output row conforms to PatentRecord
+# @side-effects HTTPS egress to api-recherche.inpi.fr
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key — session-cookie auth not implemented; only the open public-record subset is reachable
+site: inpi-fr
+name: get
+description: Fetch a French patent record by publication number (open subset)
+domain: api.inpi.fr
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  publication_number:
+    type: str
+    required: true
+    positional: true
+    description: French publication number (e.g. FR3098765)
+
+pipeline:
+  - fetch:
+      url: "https://api-recherche.inpi.fr/services/patents/${{ args.publication_number | urlencode }}"
+      method: GET
+      headers:
+        Accept: application/json
+
+  - map:
+      publication_number: "${{ 'FR-' + (item.publicationNumber || args.publication_number || '') + '-' + (item.kindCode || '') }}"
+      application_number: "${{ item.applicationNumber || '' }}"
+      title: "${{ item.title || item.titleFr || item.titleEn || '' }}"
+      abstract: "${{ item.abstract || item.abstractFr || item.abstractEn || '' }}"
+      kind_code: "${{ item.kindCode || '' }}"
+      filing_date: "${{ item.filingDate || item.applicationDate || '' }}"
+      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.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: 'FR' })).filter(x => x.name); })()) }}"
+      assignees: "${{ JSON.stringify((function(){ var a=item.applicants || item.holders; if(!a) return []; var arr = Array.isArray(a) ? a : [a]; return arr.map(n => ({ name: typeof n === 'string' ? n : (n.name || n.fullName || ''), country: 'FR' })).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: inpi-fr
+      source_url: "${{ 'https://data.inpi.fr/brevets/' + (args.publication_number || '') }}"
+      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/inpi-fr/search.yaml

@@ -0,0 +1,74 @@
+# @owner       src::adapters::inpi-fr::search
+# @does        Search French patents (FR brevets) via the public INPI search API (open subset, no login).
+# @needs       src/engine/steps/fetch.ts, src/engine/steps/select.ts, src/engine/steps/map.ts, src/engine/steps/limit.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on 5xx or rate limit; INPI's full-feature endpoints require an authenticated session — this adapter implements only the public open-data subset
+# @invariants  output rows conform to PatentRecord; publication_number is `FR-<doc>-<kind>`
+# @side-effects HTTPS egress to api.inpi.fr / api-recherche.inpi.fr; no env reads
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key — INPI public search API throttles anonymous traffic and the full record endpoints require a session cookie. Session-cookie login flow is not implemented in this adapter; the search endpoint exercised here is the open subset documented at data.inpi.fr.
+site: inpi-fr
+name: search
+description: Search French patents via the INPI public open-data search API
+domain: api.inpi.fr
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Free-text query
+  limit:
+    type: int
+    default: 25
+    description: Maximum results
+
+pipeline:
+  - fetch:
+      url: "https://api-recherche.inpi.fr/services/patents/search"
+      method: GET
+      headers:
+        Accept: application/json
+      params:
+        q: "${{ args.query }}"
+        nbResultsParPage: "${{ args.limit }}"
+        page: "1"
+
+  - select: results
+
+  # INPI open-data JSON; field names mirror INPI's documented schema.
+  - map:
+      publication_number: "${{ 'FR-' + (item.publicationNumber || item.applicationNumber || '') + '-' + (item.kindCode || '') }}"
+      application_number: "${{ item.applicationNumber || '' }}"
+      title: "${{ item.title || item.titleFr || item.titleEn || '' }}"
+      abstract: "${{ item.abstract || item.abstractFr || item.abstractEn || '' }}"
+      kind_code: "${{ item.kindCode || '' }}"
+      filing_date: "${{ item.filingDate || item.applicationDate || '' }}"
+      publication_date: "${{ item.publicationDate || '' }}"
+      grant_date: "${{ item.grantDate || '' }}"
+      priority_date: "${{ item.priorityDate || '' }}"
+      inventors: "${{ JSON.stringify((function(){ var i=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: 'FR' })).filter(x => x.name); })()) }}"
+      assignees: "${{ JSON.stringify((function(){ var a=item.applicants || item.holders; if(!a) return []; var arr = Array.isArray(a) ? a : [a]; return arr.map(n => ({ name: typeof n === 'string' ? n : (n.name || n.fullName || ''), country: 'FR' })).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: inpi-fr
+      source_url: "${{ 'https://data.inpi.fr/brevets/' + (item.publicationNumber || 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/instagram/subtitles.ts

@@ -0,0 +1,44 @@
+/**
+ * @owner   Instagram subtitle adapter.
+ * @does    Extracts LLM-readable subtitle text from public Instagram reel and video URLs.
+ * @needs   `yt-dlp` on PATH and an accessible video subtitle track.
+ * @feeds   Cross-platform social video analysis workflows.
+ * @breaks  Instagram or yt-dlp extractor changes can alter subtitle availability.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import { runVideoSubtitleExtraction } from "../../social/video-text.js";
+
+cli({
+  site: "instagram",
+  name: "subtitles",
+  description:
+    "Extract LLM-readable subtitles from an Instagram reel or video URL with optional browser-cookie reuse",
+  domain: "www.instagram.com",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "url",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Instagram reel or video URL",
+      format: "uri",
+    },
+    {
+      name: "languages",
+      type: "str",
+      default: "zh-Hans,zh,en",
+      description: "Comma-separated subtitle languages",
+    },
+    {
+      name: "cookies-from-browser",
+      type: "str",
+      description: "Browser name for yt-dlp --cookies-from-browser",
+    },
+  ],
+  columns: ["language", "text", "path"],
+  socialCapabilities: ["read", "media", "subtitles"],
+  defaultFormat: "json",
+  func: async (_page, kwargs) => runVideoSubtitleExtraction(kwargs),
+});

package/src/adapters/ipaustralia/get.yaml

@@ -0,0 +1,67 @@
+# @owner       src::adapters::ipaustralia::get
+# @does        Fetch an Australian patent record by application number via the IP Australia API portal.
+# @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 IPAUSTRALIA_API_KEY; HTTPS egress to api.ipaustralia.gov.au
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key
+site: ipaustralia
+name: get
+description: Fetch an Australian patent by application number
+domain: api.ipaustralia.gov.au
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  application_number:
+    type: str
+    required: true
+    positional: true
+    description: Australian application number (e.g. 2023000123)
+
+pipeline:
+  - fetch:
+      url: "https://api.ipaustralia.gov.au/patents/v1/patent/${{ args.application_number | urlencode }}"
+      method: GET
+      headers:
+        Accept: application/xml
+        x-api-key: "${{ env.IPAUSTRALIA_API_KEY || '' }}"
+
+  - select-xml:
+      xpath: "//patent"
+      unwrap_single: true
+
+  - map:
+      publication_number: "${{ 'AU-' + (item.publicationNumber || args.application_number || '') + '-' + (item.kindCode || '') }}"
+      application_number: "${{ item.applicationNumber || args.application_number || '' }}"
+      title: "${{ item.title || item.inventionTitle || '' }}"
+      abstract: "${{ item.abstract || '' }}"
+      kind_code: "${{ item.kindCode || '' }}"
+      filing_date: "${{ item.filingDate || item.applicationDate || '' }}"
+      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: 'AU' })).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: 'AU' })).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: ipaustralia
+      source_url: "${{ 'https://search.ipaustralia.gov.au/patents/' + (args.application_number || '') }}"
+      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/ipaustralia/search.yaml

@@ -0,0 +1,74 @@
+# @owner       src::adapters::ipaustralia::search
+# @does        Search Australian patents via the IP Australia API Portal (Open Data services).
+# @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 IPAUSTRALIA_API_KEY), 4xx, 5xx
+# @invariants  output rows conform to PatentRecord; publication_number is `AU-<doc>-<kind>`
+# @side-effects reads env IPAUSTRALIA_API_KEY; HTTPS egress to api.ipaustralia.gov.au
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key — needs IPAUSTRALIA_API_KEY (free registration at api.ipaustralia.gov.au)
+site: ipaustralia
+name: search
+description: Search Australian patents via the IP Australia API portal
+domain: api.ipaustralia.gov.au
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Free-text query (title/abstract)
+  limit:
+    type: int
+    default: 25
+    description: Maximum results
+
+pipeline:
+  - fetch:
+      url: "https://api.ipaustralia.gov.au/patents/v1/search"
+      method: GET
+      headers:
+        Accept: application/xml
+        x-api-key: "${{ env.IPAUSTRALIA_API_KEY || '' }}"
+      params:
+        q: "${{ args.query }}"
+        size: "${{ args.limit }}"
+
+  - select-xml:
+      xpath: "//patent"
+
+  - map:
+      publication_number: "${{ 'AU-' + (item.publicationNumber || item.applicationNumber || '') + '-' + (item.kindCode || '') }}"
+      application_number: "${{ item.applicationNumber || '' }}"
+      title: "${{ item.title || item.inventionTitle || '' }}"
+      abstract: "${{ item.abstract || '' }}"
+      kind_code: "${{ item.kindCode || '' }}"
+      filing_date: "${{ item.filingDate || item.applicationDate || '' }}"
+      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: 'AU' })).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: 'AU' })).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: ipaustralia
+      source_url: "${{ 'https://search.ipaustralia.gov.au/patents/' + (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/jpo/get.yaml

@@ -0,0 +1,63 @@
+# @owner       src::adapters::jpo::get
+# @does        Fetch a single Japanese patent record from JPO Patent Information Retrieval API by application number.
+# @needs       src/engine/steps/fetch.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 JPO_API_TOKEN; HTTPS egress to ip-data.jpo.go.jp
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key
+site: jpo
+name: get
+description: Fetch a JPO application by application number
+domain: ip-data.jpo.go.jp
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  application_number:
+    type: str
+    required: true
+    positional: true
+    description: JPO application number (e.g. 特願2024-012345 numeric form 2024012345)
+
+pipeline:
+  - fetch:
+      url: "https://ip-data.jpo.go.jp/api/v2/patent/applications/${{ args.application_number | urlencode }}"
+      method: GET
+      headers:
+        Accept: application/json
+        Authorization: "Bearer ${{ env.JPO_API_TOKEN || '' }}"
+
+  - map:
+      publication_number: "${{ 'JP-' + (item.publicationNumber || item.applicationNumber || '') + '-' + (item.publicationKindCode || '') }}"
+      application_number: "${{ item.applicationNumber || args.application_number || '' }}"
+      title: "${{ item.inventionTitleJapanese || item.inventionTitleEnglish || '' }}"
+      abstract: "${{ item.abstractJapanese || item.abstractEnglish || '' }}"
+      kind_code: "${{ item.publicationKindCode || '' }}"
+      filing_date: "${{ item.applicationDate || '' }}"
+      publication_date: "${{ item.publicationDate || '' }}"
+      grant_date: "${{ item.registrationDate || '' }}"
+      priority_date: "${{ item.priorityDate || '' }}"
+      legal_status: "${{ item.statusDescription || item.status || '' }}"
+      inventors: "${{ JSON.stringify((function(){ var i=item.inventorName; if(!i) return []; var arr = Array.isArray(i) ? i : [i]; return arr.map(n => ({ name: typeof n === 'string' ? n : (n.name || ''), country: 'JP' })).filter(x => x.name); })()) }}"
+      assignees: "${{ JSON.stringify((function(){ var a=item.applicantName; if(!a) return []; var arr = Array.isArray(a) ? a : [a]; return arr.map(n => ({ name: typeof n === 'string' ? n : (n.name || ''), country: 'JP' })).filter(x => x.name); })()) }}"
+      classifications: "${{ JSON.stringify((function(){ var c=item.ipcClassification; 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: jpo
+      source_url: "${{ 'https://www.j-platpat.inpit.go.jp/p0200' }}"
+      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/jpo/search.yaml

@@ -0,0 +1,76 @@
+# @owner       src::adapters::jpo::search
+# @does        Search JPO Patent Information Retrieval API for Japanese patent applications.
+# @needs       src/engine/steps/fetch.ts, src/engine/steps/select.ts, src/engine/steps/map.ts, src/engine/steps/limit.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on 401/403 (missing JPO_API_TOKEN), 404, 5xx; rate-limited per terms-of-use
+# @invariants  output rows conform to PatentRecord; publication_number is `JP-<doc>-<kind>`
+# @side-effects reads env JPO_API_TOKEN; HTTPS egress to ip-data.jpo.go.jp
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key — needs JPO_API_TOKEN (registration at jpo.go.jp/e/system/laws/koho/internet/api-patent_info.html); exact path verified at live exercise time
+site: jpo
+name: search
+description: Search JPO Patent Information Retrieval API
+domain: ip-data.jpo.go.jp
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Free-text query (JPO maps to title/abstract/applicant fields)
+  limit:
+    type: int
+    default: 25
+    description: Maximum results
+
+pipeline:
+  - fetch:
+      url: "https://ip-data.jpo.go.jp/api/v2/patent/applications/search"
+      method: GET
+      headers:
+        Accept: application/json
+        Authorization: "Bearer ${{ env.JPO_API_TOKEN || '' }}"
+      params:
+        q: "${{ args.query }}"
+        size: "${{ args.limit }}"
+
+  - select: results
+
+  # JPO Patent Information Retrieval JSON; preserve Japanese script in title,
+  # surface English title when JPO returns one, expose IPC + applicant fields.
+  - map:
+      publication_number: "${{ 'JP-' + (item.publicationNumber || item.applicationNumber || '') + '-' + (item.publicationKindCode || '') }}"
+      application_number: "${{ item.applicationNumber || '' }}"
+      title: "${{ item.inventionTitleJapanese || item.inventionTitleEnglish || '' }}"
+      abstract: "${{ item.abstractJapanese || item.abstractEnglish || '' }}"
+      kind_code: "${{ item.publicationKindCode || '' }}"
+      filing_date: "${{ item.applicationDate || '' }}"
+      publication_date: "${{ item.publicationDate || '' }}"
+      grant_date: "${{ item.registrationDate || '' }}"
+      priority_date: "${{ item.priorityDate || '' }}"
+      # JPO returns inventor / applicant as either string or string[]; coerce to array.
+      inventors: "${{ JSON.stringify((function(){ var i=item.inventorName; if(!i) return []; var arr = Array.isArray(i) ? i : [i]; return arr.map(n => ({ name: typeof n === 'string' ? n : (n.name || ''), country: 'JP' })).filter(x => x.name); })()) }}"
+      assignees: "${{ JSON.stringify((function(){ var a=item.applicantName; if(!a) return []; var arr = Array.isArray(a) ? a : [a]; return arr.map(n => ({ name: typeof n === 'string' ? n : (n.name || ''), country: 'JP' })).filter(x => x.name); })()) }}"
+      classifications: "${{ JSON.stringify((function(){ var c=item.ipcClassification; 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: jpo
+      source_url: "${{ 'https://www.j-platpat.inpit.go.jp/p0200' }}"
+      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