@zenalexa/unicli 0.220.0 → 0.221.0

package/src/adapters/ukipo/info.yaml

@@ -0,0 +1,43 @@
+# @owner       src::adapters::ukipo::info
+# @does        Registry placeholder for the UK Intellectual Property Office — surfaces a structured PATENT_API_DEPRECATED envelope until UK IPO ships the OneIPO programmatic API listed on its 2026 roadmap.
+# @needs       src/engine/steps/assert.ts
+# @feeds       src/commands/patent.ts (meta-command discovery via `patent.*` capability)
+# @breaks      always throws PipelineError carrying a PATENT_API_DEPRECATED message; never silently returns rows
+# @invariants  no HTTPS egress; no env reads; no caller-visible state beyond the error envelope
+# @side-effects none
+# @perf        n/a — fails before any I/O
+# @concurrency safe (pure local assertion)
+# @test        none yet
+# @stability   experimental — replace with a real adapter when UK IPO publishes the OneIPO API spec
+# @since       2026-05-18
+# @verification waiting-for-api — UK IPO retired Ipsum on 2025-01; the OneIPOSearch web UI is live at https://www.search-for-intellectual-property.service.gov.uk/patent and a programmatic OneIPO API is listed on the 2026 roadmap with no fixed launch date. Until the API ships, callers can run searches manually through the OneIPOSearch UI.
+site: ukipo
+name: info
+description: UK IPO registry placeholder — Ipsum retired 2025-01; OneIPO API on 2026 roadmap
+domain: search-for-intellectual-property.service.gov.uk
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args: {}
+
+pipeline:
+  # Fail closed with a structured envelope. The message points at the
+  # OneIPOSearch web UI so a caller has a concrete next step today, and
+  # names the OneIPO API roadmap so future repair loops know where the
+  # gap is going to close.
+  - assert:
+      condition: "false"
+      message: "PATENT_API_DEPRECATED: UK IPO retired Ipsum on 2025-01. Use the OneIPOSearch web UI at https://www.search-for-intellectual-property.service.gov.uk/patent for now; the OneIPO programmatic API is listed on the UK IPO 2026 roadmap (https://www.gov.uk/government/organisations/intellectual-property-office) but has not shipped."
+
+columns: []
+
+# schema-v2 metadata
+# The patent.* capability lets `unicli patent doctor` discover this adapter
+# so the gap surfaces in the doctor table; the runtime step is `assert`.
+capabilities: ["assert", "patent.search", "patent.get"]
+minimum_capability: assert
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/uspto/get.yaml

@@ -0,0 +1,67 @@
+# @owner       src::adapters::uspto::get
+# @does        Fetch a single USPTO patent/application by application number via the ODP detail endpoint.
+# @needs       src/engine/steps/fetch.ts, src/engine/steps/map.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on 401/403 (missing/invalid X-API-KEY), 404 (number not found) or 5xx
+# @invariants  output row conforms to PatentRecord; publication_number is canonicalized to ST.16 form
+# @side-effects reads env USPTO_ODP_API_KEY; HTTPS egress to api.uspto.gov
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key — needs USPTO_ODP_API_KEY
+site: uspto
+name: get
+description: Fetch a USPTO patent/application by application number
+domain: api.uspto.gov
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  application_number:
+    type: str
+    required: true
+    positional: true
+    description: USPTO application number (e.g. 16/123,456 with or without slash)
+
+pipeline:
+  - fetch:
+      url: "https://api.uspto.gov/api/v1/patent/applications/${{ args.application_number | replace('/', '') | replace(',', '') }}"
+      method: GET
+      headers:
+        Accept: application/json
+        X-API-KEY: "${{ env.USPTO_ODP_API_KEY || '' }}"
+
+  # ODP single-record detail endpoint returns the same `applicationMetaData`
+  # envelope as search, plus a richer `patentTermAdjustment` / `inventor` /
+  # `applicant` set on the detail path. Every field reference below maps to a
+  # documented ODP path; adapters do not synthesise.
+  - map:
+      publication_number: "${{ item.applicationMetaData && item.applicationMetaData.earliestPublicationNumber ? ('US-' + item.applicationMetaData.earliestPublicationNumber) : ('US-' + (item.applicationNumberText || '')) }}"
+      application_number: "${{ item.applicationNumberText || '' }}"
+      title: "${{ item.applicationMetaData ? (item.applicationMetaData.inventionTitle || '') : '' }}"
+      abstract: "${{ item.applicationMetaData ? (item.applicationMetaData.abstractText || '') : '' }}"
+      filing_date: "${{ item.applicationMetaData ? (item.applicationMetaData.filingDate || '') : '' }}"
+      publication_date: "${{ item.applicationMetaData ? (item.applicationMetaData.earliestPublicationDate || '') : '' }}"
+      grant_date: "${{ item.applicationMetaData ? (item.applicationMetaData.grantDate || '') : '' }}"
+      priority_date: "${{ item.applicationMetaData ? (item.applicationMetaData.firstInventorToFileIndicator ? item.applicationMetaData.filingDate : (item.applicationMetaData.earliestPriorityDate || '')) : '' }}"
+      kind_code: "${{ (item.applicationMetaData && item.applicationMetaData.earliestPublicationNumber) ? (item.applicationMetaData.earliestPublicationNumber.match(/[A-Z]\\d?$/) || [''])[0] : '' }}"
+      inventors: "${{ JSON.stringify((item.applicationMetaData && item.applicationMetaData.inventorBag) ? item.applicationMetaData.inventorBag.map(p => ({ name: p.inventorNameText || ((p.firstName || '') + ' ' + (p.lastName || '')).trim(), country: p.countryCode || undefined })) : []) }}"
+      assignees: "${{ JSON.stringify((item.applicationMetaData && item.applicationMetaData.applicantBag) ? item.applicationMetaData.applicantBag.map(p => ({ name: p.applicantNameText || p.organizationNameText || '', country: p.countryCode || undefined })) : []) }}"
+      classifications: "${{ JSON.stringify((item.applicationMetaData && item.applicationMetaData.cpcClassificationBag) ? item.applicationMetaData.cpcClassificationBag.map(c => ({ scheme: 'cpc', code: c.cpcSymbol || c })) : []) }}"
+      legal_status: "${{ item.applicationMetaData ? (item.applicationMetaData.applicationStatusDescriptionText || '') : '' }}"
+      source_adapter: uspto
+      source_url: "${{ 'https://ppubs.uspto.gov/dirsearch-public/patents/' + (item.applicationNumberText || '') }}"
+      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/uspto/legal-status.yaml

@@ -0,0 +1,58 @@
+# @owner       src::adapters::uspto::legal-status
+# @does        Fetch USPTO transaction history (PAIR) for an application — used to derive legal-status (issued, abandoned, pending, etc.).
+# @needs       src/engine/steps/fetch.ts, src/engine/steps/select.ts, src/engine/steps/map.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on 401/403/404
+# @invariants  output rows conform to PatentRecord; legal_status carries the latest transaction description
+# @side-effects reads env USPTO_ODP_API_KEY; HTTPS egress to api.uspto.gov
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key — needs USPTO_ODP_API_KEY
+site: uspto
+name: legal-status
+description: Legal-status / transaction history of a USPTO application
+domain: api.uspto.gov
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  application_number:
+    type: str
+    required: true
+    positional: true
+    description: USPTO application number
+
+pipeline:
+  - fetch:
+      url: "https://api.uspto.gov/api/v1/patent/applications/${{ args.application_number | replace('/', '') | replace(',', '') }}/transactions"
+      method: GET
+      headers:
+        Accept: application/json
+        X-API-KEY: "${{ env.USPTO_ODP_API_KEY || '' }}"
+
+  - select: eventDataBag
+
+  # Each row is a transaction event; the ODP `transactions` endpoint returns
+  # eventCode + eventDescriptionText + eventDate per transaction.
+  - map:
+      publication_number: "${{ 'US-' + (args.application_number || '') }}"
+      application_number: "${{ args.application_number }}"
+      legal_status: "${{ (item.eventCode || '') + (item.eventDescriptionText ? (' ' + item.eventDescriptionText) : '') }}"
+      filing_date: "${{ item.eventDate || '' }}"
+      source_adapter: uspto
+      source_url: "${{ 'https://ppubs.uspto.gov/dirsearch-public/patents/' + (args.application_number || '') }}"
+      retrieved_at: ""
+
+columns: [publication_number, legal_status, filing_date]
+
+# 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/uspto/search.yaml

@@ -0,0 +1,88 @@
+# @owner       src::adapters::uspto::search
+# @does        Search USPTO patents/applications via the Open Data Portal (ODP) `applications/search` endpoint.
+# @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 (meta-command aggregator)
+# @breaks      throws PipelineError on 401/403 (missing/invalid X-API-KEY) or 5xx; ODP enforces a 6 MB response cap — narrow the query if hit
+# @invariants  output rows conform to PatentRecord; publication_number is canonicalized to ST.16 form `US-<doc>-<kind>`
+# @side-effects reads env USPTO_ODP_API_KEY; HTTPS egress to api.uspto.gov
+# @perf        single request, ODP returns up to 500 records per page
+# @concurrency single-call; no shared mutable state
+# @test        none yet (adapter ships; live verification gated on key)
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key — needs USPTO_ODP_API_KEY (free tier at developer.uspto.gov)
+site: uspto
+name: search
+description: Search USPTO patents/applications via the Open Data Portal (ODP)
+domain: api.uspto.gov
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Free-text query (mapped to ODP `q` field, matches title/abstract/claims)
+  limit:
+    type: int
+    default: 25
+    description: Maximum results to return (ODP allows up to 500 per page)
+  offset:
+    type: int
+    default: 0
+    description: Result offset for pagination
+
+pipeline:
+  - fetch:
+      url: "https://api.uspto.gov/api/v1/patent/applications/search"
+      method: GET
+      headers:
+        Accept: application/json
+        X-API-KEY: "${{ env.USPTO_ODP_API_KEY || '' }}"
+      params:
+        q: "${{ args.query }}"
+        limit: "${{ args.limit }}"
+        offset: "${{ args.offset }}"
+
+  - select: patentFileWrapperDataBag
+
+  # Field mapping references data.uspto.gov/swagger v1 patent applications schema.
+  # Every field below maps to a documented ODP response path — adapters must
+  # not synthesise values upstream did not return.
+  - map:
+      publication_number: "${{ item.applicationMetaData && item.applicationMetaData.earliestPublicationNumber ? ('US-' + item.applicationMetaData.earliestPublicationNumber) : ('US-' + (item.applicationNumberText || '')) }}"
+      application_number: "${{ item.applicationNumberText || '' }}"
+      title: "${{ item.applicationMetaData ? (item.applicationMetaData.inventionTitle || '') : '' }}"
+      abstract: "${{ item.applicationMetaData ? (item.applicationMetaData.abstractText || '') : '' }}"
+      filing_date: "${{ item.applicationMetaData ? (item.applicationMetaData.filingDate || '') : '' }}"
+      publication_date: "${{ item.applicationMetaData ? (item.applicationMetaData.earliestPublicationDate || '') : '' }}"
+      grant_date: "${{ item.applicationMetaData ? (item.applicationMetaData.grantDate || '') : '' }}"
+      # ODP `applicationMetaData.earliestPublicationNumber` is the compact form
+      # (`20240123456A1`); the trailing A1/A2/B1/B2 IS the ST.16 kind code.
+      kind_code: "${{ (item.applicationMetaData && item.applicationMetaData.earliestPublicationNumber) ? (item.applicationMetaData.earliestPublicationNumber.match(/[A-Z]\\d?$/) || [''])[0] : '' }}"
+      # ODP `inventorBag[]` and `applicantBag[]` carry per-party records.
+      # We serialise via JSON.stringify so the array survives the template
+      # engine's string projection; coerceToPatentRecords parses it back.
+      inventors: "${{ JSON.stringify((item.applicationMetaData && item.applicationMetaData.inventorBag) ? item.applicationMetaData.inventorBag.map(p => ({ name: p.inventorNameText || ((p.firstName || '') + ' ' + (p.lastName || '')).trim(), country: p.countryCode || undefined })) : []) }}"
+      assignees: "${{ JSON.stringify((item.applicationMetaData && item.applicationMetaData.applicantBag) ? item.applicationMetaData.applicantBag.map(p => ({ name: p.applicantNameText || p.organizationNameText || '', country: p.countryCode || undefined })) : []) }}"
+      # `cpcClassificationBag[]` is the ODP path for Cooperative Patent Classification codes.
+      classifications: "${{ JSON.stringify((item.applicationMetaData && item.applicationMetaData.cpcClassificationBag) ? item.applicationMetaData.cpcClassificationBag.map(c => ({ scheme: 'cpc', code: c.cpcSymbol || c })) : []) }}"
+      legal_status: "${{ item.applicationMetaData ? (item.applicationMetaData.applicationStatusDescriptionText || '') : '' }}"
+      source_adapter: uspto
+      source_url: "${{ 'https://ppubs.uspto.gov/dirsearch-public/patents/' + (item.applicationNumberText || '') }}"
+      # retrieved_at is stamped by assemblePatentRecord in the normalizer; YAML emits the empty string
+      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/vndb/web.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+import { resolveCommand } from "../../registry.js";
+import { mapVndbReleases, mapVndbVisualNovels } from "./web.js";
+
+describe("vndb public commands", () => {
+  it("registers core visual novel discovery commands", () => {
+    expect(
+      Object.keys(resolveCommand("vndb", "search")!.adapter.commands),
+    ).toEqual(
+      expect.arrayContaining([
+        "search",
+        "vn",
+        "releases",
+        "tags",
+        "staff",
+        "producers",
+        "characters",
+      ]),
+    );
+  });
+
+  it("maps visual novel search rows with tags and developers", () => {
+    expect(
+      mapVndbVisualNovels([
+        {
+          id: "v57439",
+          title: "Hanabi no Sakase Kata",
+          alttitle: "花火の咲かせ方",
+          released: "2017-12-29",
+          languages: ["ja"],
+          platforms: ["win"],
+          rating: 70,
+          votecount: 10,
+          image: { url: "https://t.vndb.org/cv/70/112070.jpg" },
+          developers: [{ name: "Ultimate Manju" }],
+          tags: [
+            { name: "Comedy", rating: 1 },
+            { name: "ADV", rating: 2 },
+          ],
+        },
+      ]),
+    ).toEqual([
+      {
+        rank: 1,
+        id: "v57439",
+        title: "Hanabi no Sakase Kata",
+        alttitle: "花火の咲かせ方",
+        released: "2017-12-29",
+        languages: "ja",
+        platforms: "win",
+        rating: 70,
+        votecount: 10,
+        developers: "Ultimate Manju",
+        tags: "ADV, Comedy",
+        image: "https://t.vndb.org/cv/70/112070.jpg",
+        url: "https://vndb.org/v57439",
+      },
+    ]);
+  });
+
+  it("maps release rows", () => {
+    expect(
+      mapVndbReleases([
+        {
+          id: "r91050",
+          title: "U-ena -Toohanabi no Shoujo-",
+          released: "TBA",
+          platforms: ["win"],
+          producers: [{ name: "Hemiola Studio" }],
+          vns: [{ title: "U-ena -Toohanabi no Shoujo-" }],
+        },
+      ]),
+    ).toEqual([
+      {
+        rank: 1,
+        id: "r91050",
+        title: "U-ena -Toohanabi no Shoujo-",
+        released: "TBA",
+        platforms: "win",
+        producers: "Hemiola Studio",
+        vns: "U-ena -Toohanabi no Shoujo-",
+        url: "https://vndb.org/r91050",
+      },
+    ]);
+  });
+});