@zenalexa/unicli 0.220.1 → 0.221.0

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

package/src/adapters/kipris/get.yaml

@@ -0,0 +1,69 @@
+# @owner       src::adapters::kipris::get
+# @does        Fetch a single Korean patent bibliographic record from KIPRIS Plus REST by application number.
+# @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 missing key, 4xx, 5xx
+# @invariants  output row conforms to PatentRecord
+# @side-effects reads env KIPRIS_ACCESS_KEY; HTTPS egress to plus.kipris.or.kr
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key
+site: kipris
+name: get
+description: Fetch a KIPRIS biblio record by application number
+domain: plus.kipris.or.kr
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  application_number:
+    type: str
+    required: true
+    positional: true
+    description: Korean application number (e.g. 1020230012345)
+
+pipeline:
+  - fetch:
+      url: "https://plus.kipris.or.kr/openapi/rest/patUtiModInfoSearchSevice/getBibliographyDetailInfoSearch"
+      method: GET
+      headers:
+        Accept: application/xml
+      params:
+        applicationNumber: "${{ args.application_number }}"
+        accessKey: "${{ env.KIPRIS_ACCESS_KEY || '' }}"
+
+  - select-xml:
+      xpath: "//biblioSummaryInfo"
+      unwrap_single: true
+
+  - map:
+      publication_number: "${{ 'KR-' + (item.openNumber || args.application_number || '') + '-' + (item.openType || '') }}"
+      application_number: "${{ item.applicationNumber || args.application_number || '' }}"
+      title: "${{ item.inventionTitle || '' }}"
+      abstract: "${{ item.astrtCont || '' }}"
+      kind_code: "${{ item.openType || '' }}"
+      filing_date: "${{ item.applicationDate || '' }}"
+      publication_date: "${{ item.openDate || '' }}"
+      grant_date: "${{ item.registerDate || '' }}"
+      priority_date: "${{ item.priorityDate || '' }}"
+      legal_status: "${{ item.registerStatus || '' }}"
+      inventors: "${{ JSON.stringify(item.inventor ? [{ name: item.inventor, country: 'KR' }] : []) }}"
+      assignees: "${{ JSON.stringify(item.applicant ? [{ name: item.applicant, country: 'KR' }] : []) }}"
+      classifications: "${{ JSON.stringify((function(){ var c=item.ipcNumber; if(!c) return []; var arr = String(c).split('|').map(s => s.trim()).filter(s => s); return arr.map(code => ({ scheme: 'ipc', code: code })); })()) }}"
+      source_adapter: kipris
+      source_url: "${{ 'https://kpat.kipris.or.kr/kpat/biblioa.do?method=biblioFrame&applno=' + (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/kipris/legal-status.yaml

@@ -0,0 +1,58 @@
+# @owner       src::adapters::kipris::legal-status
+# @does        Fetch Korean patent legal-status (right-trans/registration events) from KIPRIS Plus 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 missing key, 4xx, 5xx
+# @invariants  output rows carry legal_status from rightTransRegInfo
+# @side-effects reads env KIPRIS_ACCESS_KEY; HTTPS egress
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key
+site: kipris
+name: legal-status
+description: KIPRIS right-trans / registration events for a Korean application
+domain: plus.kipris.or.kr
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  application_number:
+    type: str
+    required: true
+    positional: true
+    description: Korean application number
+
+pipeline:
+  - fetch:
+      url: "https://plus.kipris.or.kr/openapi/rest/patUtiModInfoSearchSevice/getRightTransRegInfoSearchInfo"
+      method: GET
+      headers:
+        Accept: application/xml
+      params:
+        applicationNumber: "${{ args.application_number }}"
+        accessKey: "${{ env.KIPRIS_ACCESS_KEY || '' }}"
+
+  - select-xml:
+      xpath: "//item"
+
+  - map:
+      publication_number: "${{ 'KR-' + (args.application_number || '') }}"
+      application_number: "${{ args.application_number }}"
+      legal_status: "${{ (item.rightCode || '') + ' ' + (item.contents || '') }}"
+      source_adapter: kipris
+      source_url: "${{ 'https://kpat.kipris.or.kr/kpat/biblioa.do?method=biblioFrame&applno=' + (args.application_number || '') }}"
+      retrieved_at: ""
+
+columns: [publication_number, legal_status]
+
+# schema-v2 metadata
+capabilities: ["http.fetch", "patent.legal-status"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/kipris/search.yaml

@@ -0,0 +1,79 @@
+# @owner       src::adapters::kipris::search
+# @does        Search KIPRIS Plus REST patent search endpoint for Korean patents/utility models.
+# @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 missing/invalid accessKey, 4xx, 5xx
+# @invariants  output rows conform to PatentRecord; publication_number is `KR-<doc>-<kind>`
+# @side-effects reads env KIPRIS_ACCESS_KEY; HTTPS egress to plus.kipris.or.kr
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key — needs KIPRIS_ACCESS_KEY (registration at plus.kipris.or.kr)
+site: kipris
+name: search
+description: Search KIPRIS Plus REST for Korean patents/utility models
+domain: plus.kipris.or.kr
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Free-text query (KIPRIS `word` param)
+  limit:
+    type: int
+    default: 25
+    description: Maximum results (numOfRows)
+
+pipeline:
+  - fetch:
+      url: "https://plus.kipris.or.kr/openapi/rest/patUtiModInfoSearchSevice/getWordSearch"
+      method: GET
+      headers:
+        Accept: application/xml
+      params:
+        word: "${{ args.query }}"
+        numOfRows: "${{ args.limit }}"
+        pageNo: "1"
+        accessKey: "${{ env.KIPRIS_ACCESS_KEY || '' }}"
+
+  - select-xml:
+      xpath: "//item"
+
+  # KIPRIS Plus XML preserves the native Korean script for title / abstract.
+  - map:
+      publication_number: "${{ 'KR-' + (item.openNumber || item.applicationNumber || '') + '-' + (item.openType || '') }}"
+      application_number: "${{ item.applicationNumber || '' }}"
+      title: "${{ item.inventionTitle || '' }}"
+      abstract: "${{ item.astrtCont || '' }}"
+      kind_code: "${{ item.openType || '' }}"
+      filing_date: "${{ item.applicationDate || '' }}"
+      publication_date: "${{ item.openDate || '' }}"
+      grant_date: "${{ item.registerDate || '' }}"
+      priority_date: "${{ item.priorityNumber ? (item.priorityDate || '') : '' }}"
+      legal_status: "${{ item.registerStatus || '' }}"
+      # KIPRIS exposes inventor / applicant as a single concatenated string;
+      # preserve the format the office returns and treat it as one party.
+      inventors: "${{ JSON.stringify(item.inventor ? [{ name: item.inventor, country: 'KR' }] : []) }}"
+      assignees: "${{ JSON.stringify(item.applicant ? [{ name: item.applicant, country: 'KR' }] : []) }}"
+      classifications: "${{ JSON.stringify((function(){ var c=item.ipcNumber; if(!c) return []; var arr = String(c).split('|').map(s => s.trim()).filter(s => s); return arr.map(code => ({ scheme: 'ipc', code: code })); })()) }}"
+      source_adapter: kipris
+      source_url: "${{ 'https://kpat.kipris.or.kr/kpat/biblioa.do?method=biblioFrame&applno=' + (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/lens/get.yaml

@@ -0,0 +1,64 @@
+# Lens.org single-record fetch.
+#
+# verification_status: blocked-by-subscription
+#
+# Lens "patent/search" is the only retrieval endpoint they expose publicly;
+# get is implemented as a one-record query by `doc_key` (publication_number).
+site: lens
+name: get
+description: Retrieve a single Lens.org patent record by publication number
+domain: api.lens.org
+type: web-api
+strategy: header
+
+args:
+  publication_number:
+    type: str
+    required: true
+    positional: true
+
+pipeline:
+  - fetch:
+      url: https://api.lens.org/patent/search
+      method: POST
+      headers:
+        Authorization: "Bearer ${{ env.LENS_API_TOKEN || '' }}"
+        Content-Type: application/json
+      body:
+        query:
+          term:
+            doc_key: "${{ args.publication_number }}"
+        size: 1
+
+  - select: data
+
+  - map:
+      publication_number: "${{ item.doc_key || item.lens_id }}"
+      title: "${{ item.biblio ? (item.biblio.invention_title ? item.biblio.invention_title[0].text : '') : '' }}"
+      abstract: "${{ item.abstract ? (Array.isArray(item.abstract) ? (item.abstract[0] && item.abstract[0].text) : item.abstract) : '' }}"
+      kind_code: "${{ item.biblio && item.biblio.publication_reference ? (item.biblio.publication_reference.kind || '') : '' }}"
+      filing_date: "${{ item.biblio ? (item.biblio.application_reference ? item.biblio.application_reference.date : '') : '' }}"
+      publication_date: "${{ item.date_published || '' }}"
+      priority_date: "${{ item.biblio && item.biblio.priority_claims && item.biblio.priority_claims.claims ? item.biblio.priority_claims.claims[0].date : '' }}"
+      family_id: "${{ item.families ? item.families.simple_family.family_id : '' }}"
+      inventors: "${{ JSON.stringify((function(){ var p=item.biblio && item.biblio.parties; if(!p || !p.inventors) return []; return p.inventors.map(i => ({ name: i.extracted_name ? (i.extracted_name.value || '') : (i.name || ''), country: i.residence || undefined })).filter(x => x.name); })()) }}"
+      assignees: "${{ JSON.stringify((function(){ var p=item.biblio && item.biblio.parties; if(!p || !p.applicants) return []; return p.applicants.map(a => ({ name: a.extracted_name ? (a.extracted_name.value || '') : (a.name || ''), country: a.residence || undefined })).filter(x => x.name); })()) }}"
+      classifications: "${{ JSON.stringify((function(){ var c = item.biblio && item.biblio.classifications_cpc && item.biblio.classifications_cpc.classifications; var out = []; if(c){ for (var i=0;i<c.length;i++) out.push({ scheme: 'cpc', code: c[i].symbol || '' }); } var ipc = item.biblio && item.biblio.classifications_ipcr && item.biblio.classifications_ipcr.classifications; if(ipc){ for (var j=0;j<ipc.length;j++) out.push({ scheme: 'ipc', code: ipc[j].symbol || '' }); } return out.filter(x => x.code); })()) }}"
+      cited_by_count: "${{ item.biblio && item.biblio.cited_by ? (item.biblio.cited_by.patent_count || 0) : '' }}"
+      cites_count: "${{ item.biblio && item.biblio.references_cited && item.biblio.references_cited.patent_count !== undefined ? item.biblio.references_cited.patent_count : '' }}"
+      claims_count: "${{ item.claims_count !== undefined ? item.claims_count : '' }}"
+      legal_status: "${{ item.legal_status ? (item.legal_status.patent_status || '') : '' }}"
+      source_url: "https://www.lens.org/lens/patent/${{ item.lens_id }}"
+      source_adapter: lens
+      retrieved_at: "${{ now }}"
+
+  - limit: 1
+
+columns: [publication_number, title, publication_date]
+
+capabilities: ["http.fetch", "patent.get"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/lens/search.yaml

@@ -0,0 +1,82 @@
+# Lens.org Patent API — POST JSON DSL search.
+#
+# verification_status: blocked-by-subscription
+#
+# Lens.org Patents is a free-to-search, paid-to-API service from Cambia.
+# Institutional / commercial users get tokens via the Lens Toolkit subscription
+# (https://www.lens.org/lens/user/subscriptions). The token is static once
+# issued; no refresh dance, no rotation — set $LENS_API_TOKEN and the adapter
+# works. Until the env var is present, every command emits a structured
+# blocked-by-key envelope so agents can repair by guiding the user through
+# subscription setup rather than retrying the API.
+site: lens
+name: search
+description: Search Lens.org's combined patent corpus via the Scholarly Works DSL
+domain: api.lens.org
+type: web-api
+strategy: header
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Free-text query — mapped to the Lens DSL `query_string`
+  limit:
+    type: int
+    default: 20
+    description: Maximum records returned (Lens caps at 1000)
+  date_from:
+    type: str
+    default: ""
+    description: ISO date — minimum publication date
+
+pipeline:
+  - fetch:
+      url: https://api.lens.org/patent/search
+      method: POST
+      headers:
+        Authorization: "Bearer ${{ env.LENS_API_TOKEN || '' }}"
+        Content-Type: application/json
+      body:
+        query:
+          query_string:
+            query: "${{ args.query }}"
+        size: "${{ args.limit }}"
+        from: 0
+
+  - select: data
+
+  # Lens.org JSON `biblio` is the rich envelope. `_score` is Lens's
+  # relevance score, naturally a float; pass through as relevance_score.
+  - map:
+      publication_number: "${{ item.doc_key || item.lens_id }}"
+      title: "${{ item.biblio ? (item.biblio.invention_title ? item.biblio.invention_title[0].text : '') : '' }}"
+      abstract: "${{ item.abstract ? (Array.isArray(item.abstract) ? (item.abstract[0] && item.abstract[0].text) : item.abstract) : '' }}"
+      publication_date: "${{ item.date_published || '' }}"
+      filing_date: "${{ item.biblio ? (item.biblio.application_reference ? item.biblio.application_reference.date : '') : '' }}"
+      priority_date: "${{ item.biblio && item.biblio.priority_claims && item.biblio.priority_claims.claims ? item.biblio.priority_claims.claims[0].date : '' }}"
+      kind_code: "${{ item.biblio && item.biblio.publication_reference ? (item.biblio.publication_reference.kind || '') : '' }}"
+      family_id: "${{ item.families ? item.families.simple_family.family_id : '' }}"
+      inventors: "${{ JSON.stringify((function(){ var p=item.biblio && item.biblio.parties; if(!p || !p.inventors) return []; return p.inventors.map(i => ({ name: i.extracted_name ? (i.extracted_name.value || '') : (i.name || ''), country: i.residence || undefined })).filter(x => x.name); })()) }}"
+      assignees: "${{ JSON.stringify((function(){ var p=item.biblio && item.biblio.parties; if(!p || !p.applicants) return []; return p.applicants.map(a => ({ name: a.extracted_name ? (a.extracted_name.value || '') : (a.name || ''), country: a.residence || undefined })).filter(x => x.name); })()) }}"
+      classifications: "${{ JSON.stringify((function(){ var c = item.biblio && item.biblio.classifications_cpc && item.biblio.classifications_cpc.classifications; var out = []; if(c){ for (var i=0;i<c.length;i++) out.push({ scheme: 'cpc', code: c[i].symbol || '' }); } var ipc = item.biblio && item.biblio.classifications_ipcr && item.biblio.classifications_ipcr.classifications; if(ipc){ for (var j=0;j<ipc.length;j++) out.push({ scheme: 'ipc', code: ipc[j].symbol || '' }); } return out.filter(x => x.code); })()) }}"
+      cited_by_count: "${{ item.biblio && item.biblio.cited_by ? (item.biblio.cited_by.patent_count || 0) : '' }}"
+      cites_count: "${{ item.biblio && item.biblio.references_cited && item.biblio.references_cited.patent_count !== undefined ? item.biblio.references_cited.patent_count : '' }}"
+      claims_count: "${{ item.claims_count !== undefined ? item.claims_count : '' }}"
+      relevance_score: "${{ item._score !== undefined ? item._score : '' }}"
+      source_url: "https://www.lens.org/lens/patent/${{ item.lens_id }}"
+      source_adapter: lens
+      retrieved_at: "${{ now }}"
+
+  - limit: ${{ args.limit }}
+
+columns: [publication_number, title, publication_date, source_adapter]
+
+# schema-v2 metadata
+capabilities: ["http.fetch", "patent.search"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2