@zenalexa/unicli 0.220.1 → 0.221.1

package/src/adapters/crossref/works.ts

@@ -0,0 +1,209 @@
+/**
+ * @owner       src::adapters::crossref::works
+ * @does        Registers Crossref REST work search and DOI lookup commands for publisher metadata.
+ * @needs       api.crossref.org REST API, optional CROSSREF_MAILTO, src/registry.ts
+ * @feeds       src/commands/scholar.ts via scholar.search and scholar.get
+ * @breaks      Crossref response-shape drift or rate limiting surfaces as explicit adapter errors.
+ * @invariants  DOI lookup accepts only DOI-shaped references; output maps to ScholarlyWorkRecord.
+ * @side-effects HTTPS egress to api.crossref.org only
+ * @perf        O(limit) JSON mapping
+ * @concurrency safe
+ * @test        tests/unit/adapters/scholar-sources.test.ts
+ * @stability   experimental
+ * @since       2026-05-19
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import type { ScholarlyWorkRecord } from "../../types/scholarly.js";
+
+const API = "https://api.crossref.org";
+
+interface CrossrefPerson {
+  given?: unknown;
+  family?: unknown;
+  name?: unknown;
+}
+
+interface CrossrefItem {
+  DOI?: unknown;
+  title?: unknown[];
+  subtitle?: unknown[];
+  author?: CrossrefPerson[];
+  "container-title"?: unknown[];
+  issued?: { "date-parts"?: unknown[][] };
+  published?: { "date-parts"?: unknown[][] };
+  "is-referenced-by-count"?: unknown;
+  reference?: unknown[];
+  URL?: unknown;
+  type?: unknown;
+  abstract?: unknown;
+}
+
+function str(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function arrFirst(value: unknown): string {
+  return Array.isArray(value) ? str(value[0]) : str(value);
+}
+
+function num(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+function dateParts(item: CrossrefItem): unknown[] {
+  return (
+    item.issued?.["date-parts"]?.[0] ??
+    item.published?.["date-parts"]?.[0] ??
+    []
+  );
+}
+
+function year(item: CrossrefItem): number | undefined {
+  const first = dateParts(item)[0];
+  return typeof first === "number" && Number.isFinite(first)
+    ? first
+    : undefined;
+}
+
+function date(item: CrossrefItem): string | undefined {
+  const parts = dateParts(item).filter(
+    (part): part is number => typeof part === "number",
+  );
+  if (parts.length === 0) return undefined;
+  return [
+    String(parts[0]).padStart(4, "0"),
+    String(parts[1] ?? 1).padStart(2, "0"),
+    String(parts[2] ?? 1).padStart(2, "0"),
+  ].join("-");
+}
+
+function authors(value: CrossrefPerson[] | undefined): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out = value
+    .map(
+      (person) =>
+        str(person.name) ||
+        [person.given, person.family].map(str).filter(Boolean).join(" "),
+    )
+    .filter(Boolean);
+  return out.length > 0 ? out : undefined;
+}
+
+function bareDoi(value: unknown): string {
+  return str(value)
+    .replace(/^doi:/i, "")
+    .replace(/^https?:\/\/(?:dx\.)?doi\.org\//i, "");
+}
+
+export function requireCrossrefDoi(value: unknown): string {
+  const doi = bareDoi(value);
+  if (!/^10\.\S+\/\S+/.test(doi)) {
+    throw new Error(`crossref DOI "${String(value ?? "")}" is not recognised.`);
+  }
+  return doi;
+}
+
+function maybeMailto(params: URLSearchParams): void {
+  const mailto = process.env.CROSSREF_MAILTO?.trim();
+  if (mailto) params.set("mailto", mailto);
+}
+
+async function fetchCrossref(path: string, label: string): Promise<unknown> {
+  const response = await fetch(`${API}${path}`, {
+    headers: {
+      Accept: "application/json",
+      "User-Agent":
+        "unicli-crossref/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+    },
+  });
+  if (response.status === 404) throw new Error(`${label} returned no result.`);
+  if (response.status === 429) throw new Error(`${label} returned HTTP 429.`);
+  if (!response.ok)
+    throw new Error(`${label} returned HTTP ${response.status}.`);
+  return response.json();
+}
+
+export function mapCrossrefItem(
+  item: CrossrefItem,
+  source: string,
+): ScholarlyWorkRecord {
+  const doi = requireCrossrefDoi(item.DOI);
+  return {
+    id: doi,
+    title: arrFirst(item.title),
+    authors: authors(item.author),
+    year: year(item),
+    date: date(item),
+    venue: arrFirst(item["container-title"]) || undefined,
+    type: str(item.type) || undefined,
+    abstract: str(item.abstract).replace(/<[^>]+>/g, " ") || undefined,
+    doi,
+    cited_by_count: num(item["is-referenced-by-count"]),
+    references_count: Array.isArray(item.reference)
+      ? item.reference.length
+      : undefined,
+    source_adapter: source,
+    source_url: str(item.URL) || `https://doi.org/${doi}`,
+    retrieved_at: new Date().toISOString(),
+  };
+}
+
+cli({
+  site: "crossref",
+  name: "search",
+  description:
+    "Search Crossref Works by title, author, DOI, or bibliographic text",
+  domain: "api.crossref.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    { name: "query", type: "str", required: true, positional: true },
+    { name: "limit", type: "int", default: 20 },
+  ],
+  columns: ["id", "title", "authors", "year", "venue", "doi", "source_url"],
+  capabilities: ["http.fetch", "scholar.search"],
+  func: async (_page, kwargs) => {
+    const query = String(kwargs.query ?? "").trim();
+    if (!query) throw new Error("crossref search query cannot be empty.");
+    const limit = Math.min(Math.max(Number(kwargs.limit ?? 20), 1), 100);
+    const params = new URLSearchParams({ query, rows: String(limit) });
+    maybeMailto(params);
+    const body = (await fetchCrossref(
+      `/works?${params.toString()}`,
+      "crossref search",
+    )) as {
+      message?: { items?: CrossrefItem[] };
+    };
+    const rows = (body.message?.items ?? []).map((item) =>
+      mapCrossrefItem(item, "crossref"),
+    );
+    if (rows.length === 0)
+      throw new Error(`No Crossref works matched "${query}".`);
+    return rows;
+  },
+});
+
+cli({
+  site: "crossref",
+  name: "work",
+  description: "Fetch one Crossref Work by DOI",
+  domain: "api.crossref.org",
+  strategy: Strategy.PUBLIC,
+  args: [{ name: "doi", type: "str", required: true, positional: true }],
+  columns: ["id", "title", "authors", "year", "venue", "doi", "source_url"],
+  capabilities: ["http.fetch", "scholar.get"],
+  func: async (_page, kwargs) => {
+    const doi = requireCrossrefDoi(kwargs.doi ?? kwargs.id ?? kwargs.ref);
+    const params = new URLSearchParams();
+    maybeMailto(params);
+    const suffix = params.size > 0 ? `?${params.toString()}` : "";
+    const body = (await fetchCrossref(
+      `/works/${encodeURIComponent(doi)}${suffix}`,
+      `crossref work ${doi}`,
+    )) as { message?: CrossrefItem };
+    if (!body.message) throw new Error(`Crossref returned no work for ${doi}.`);
+    return [mapCrossrefItem(body.message, "crossref")];
+  },
+});

package/src/adapters/cvf/papers.ts

@@ -0,0 +1,136 @@
+/**
+ * @owner       src::adapters::cvf::papers
+ * @does        Registers CVF OpenAccess conference paper search for CVPR/ICCV/ECCV-style proceedings pages.
+ * @needs       openaccess.thecvf.com static proceedings HTML, src/registry.ts
+ * @feeds       src/commands/scholar.ts via scholar.search, scholar.pdf, and scholar.venue
+ * @breaks      CVF markup drift surfaces as empty/parse errors rather than non-CVF fallbacks.
+ * @invariants  Venue/year map to explicit CVF event pages; PDF URLs are absolutized against openaccess.thecvf.com.
+ * @side-effects HTTPS egress to openaccess.thecvf.com only
+ * @perf        O(N) over one proceedings HTML page
+ * @concurrency safe
+ * @test        tests/unit/adapters/scholar-sources.test.ts
+ * @stability   experimental
+ * @since       2026-05-19
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import type { ScholarlyWorkRecord } from "../../types/scholarly.js";
+
+const ORIGIN = "https://openaccess.thecvf.com";
+
+function decode(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function absolute(path: string): string {
+  return /^https?:\/\//i.test(path)
+    ? path
+    : `${ORIGIN}${path.startsWith("/") ? "" : "/"}${path}`;
+}
+
+function eventId(venue: unknown, year: unknown): string {
+  const v = String(venue ?? "CVPR")
+    .trim()
+    .toUpperCase();
+  const y = String(year ?? "").trim();
+  if (!/^(CVPR|ICCV|ECCV|WACV)$/.test(v))
+    throw new Error(`unsupported CVF venue: ${v}`);
+  if (!/^\d{4}$/.test(y)) throw new Error(`cvf year "${y}" is not valid.`);
+  return `${v}${y}`;
+}
+
+export function parseCvfRows(
+  html: string,
+  event = "CVPR2024",
+): ScholarlyWorkRecord[] {
+  const out: ScholarlyWorkRecord[] = [];
+  const re =
+    /<dt class="ptitle">[\s\S]*?<a href="([^"]+)">([\s\S]*?)<\/a><\/dt>([\s\S]*?)(?=<dt class="ptitle">|$)/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(html)) !== null) {
+    const sourceUrl = absolute(match[1]);
+    const title = decode(match[2].replace(/<[^>]+>/g, " "));
+    const block = match[3];
+    const pdf = block.match(/<a href="([^"]+\.pdf)">pdf<\/a>/i)?.[1] ?? "";
+    const authorText = block
+      .replace(/\[[\s\S]*?\]/g, " ")
+      .replace(/<form[\s\S]*?<\/form>/g, " ")
+      .replace(/<[^>]+>/g, " ");
+    const authors = decode(authorText)
+      .split(",")
+      .map((author) => author.trim())
+      .filter(Boolean);
+    out.push({
+      id:
+        sourceUrl
+          .split("/")
+          .pop()
+          ?.replace(/\.html$/, "") ?? title,
+      title,
+      authors: authors.length > 0 ? authors : undefined,
+      year: Number(event.slice(-4)),
+      venue: event.replace(/\d{4}$/, ""),
+      pdf_url: pdf ? absolute(pdf) : undefined,
+      source_adapter: "cvf",
+      source_url: sourceUrl,
+      retrieved_at: new Date().toISOString(),
+    });
+  }
+  return out;
+}
+
+cli({
+  site: "cvf",
+  name: "search",
+  description: "Search CVF OpenAccess proceedings (CVPR/ICCV/ECCV/WACV)",
+  domain: "openaccess.thecvf.com",
+  strategy: Strategy.PUBLIC,
+  args: [
+    { name: "query", type: "str", required: true, positional: true },
+    { name: "venue", type: "str", default: "CVPR" },
+    { name: "year", type: "str", default: "2024" },
+    { name: "limit", type: "int", default: 20 },
+  ],
+  columns: ["id", "title", "authors", "year", "venue", "pdf_url", "source_url"],
+  capabilities: [
+    "http.fetch",
+    "scholar.search",
+    "scholar.venue",
+    "scholar.pdf",
+  ],
+  func: async (_page, kwargs) => {
+    const query = String(kwargs.query ?? "")
+      .trim()
+      .toLowerCase();
+    if (!query) throw new Error("cvf search query cannot be empty.");
+    const event = eventId(kwargs.venue, kwargs.year);
+    const response = await fetch(`${ORIGIN}/${event}?day=all`, {
+      headers: {
+        Accept: "*/*",
+        "User-Agent": "unicli-cvf/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+      },
+    });
+    if (response.status === 404)
+      throw new Error(`CVF ${event} returned no proceedings page.`);
+    if (!response.ok)
+      throw new Error(`CVF ${event} returned HTTP ${response.status}.`);
+    const limit = Math.min(Math.max(Number(kwargs.limit ?? 20), 1), 200);
+    const rows = parseCvfRows(await response.text(), event)
+      .filter((row) =>
+        `${row.title} ${row.authors?.join(" ") ?? ""}`
+          .toLowerCase()
+          .includes(query),
+      )
+      .slice(0, limit);
+    if (rows.length === 0)
+      throw new Error(`No CVF ${event} papers matched "${query}".`);
+    return rows;
+  },
+});

package/src/adapters/dblp/publications.ts

@@ -332,6 +332,7 @@ cli({
     "doi",
     "url",
   ],
+  capabilities: ["http.fetch", "scholar.search"],
   func: async (_page, kwargs) => {
     const query = requireDblpQuery(kwargs.query);
     const limit = requireDblpLimit(kwargs.limit, 20, 100);
@@ -375,6 +376,7 @@ cli({
     "open_access_url",
     "dblp_url",
   ],
+  capabilities: ["http.fetch", "scholar.get", "scholar.pdf"],
   func: async (_page, kwargs) => {
     const key = requireRecordKey(kwargs.key);
     const xml = await fetchDblpXml(
@@ -406,6 +408,7 @@ cli({
     { name: "limit", type: "int", default: 20, description: "Max venues" },
   ],
   columns: ["rank", "acronym", "venue", "type", "url"],
+  capabilities: ["http.fetch", "scholar.venue"],
   func: async (_page, kwargs) => {
     const query = requireDblpQuery(kwargs.query);
     const limit = requireDblpLimit(kwargs.limit, 20, 100);
@@ -455,6 +458,7 @@ cli({
     "pid",
     "url",
   ],
+  capabilities: ["http.fetch", "scholar.author", "scholar.search"],
   func: async (_page, kwargs) => {
     const limit = requireDblpLimit(kwargs.limit, 20, 200);
     let pid = kwargs.pid ? requirePid(kwargs.pid) : "";

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