@zenalexa/unicli 0.220.1 → 0.221.0

package/src/adapters/mastodon/statuses.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+
+import { mapMastodonStatusRows, normalizeMastodonAccount } from "./statuses.js";
+
+describe("mastodon statuses adapter helpers", () => {
+  it("normalizes account handles and instance overrides", () => {
+    expect(normalizeMastodonAccount("gargron@mastodon.social")).toEqual({
+      acct: "gargron",
+      instance: "mastodon.social",
+    });
+
+    expect(normalizeMastodonAccount("@gargron", "mastodon.social")).toEqual({
+      acct: "gargron",
+      instance: "mastodon.social",
+    });
+  });
+
+  it("maps API statuses into stable social rows", () => {
+    expect(
+      mapMastodonStatusRows(
+        [
+          {
+            created_at: "2026-05-14T10:00:00.000Z",
+            content: "<p>Hello <strong>fediverse</strong></p>",
+            url: "https://mastodon.social/@gargron/1",
+            reblogs_count: 2,
+            favourites_count: 3,
+            replies_count: 4,
+            account: { acct: "gargron", display_name: "Gargron" },
+          },
+        ],
+        10,
+      ),
+    ).toEqual([
+      {
+        rank: 1,
+        author: "Gargron",
+        handle: "@gargron",
+        content: "Hello fediverse",
+        reblogs: 2,
+        favorites: 3,
+        replies: 4,
+        url: "https://mastodon.social/@gargron/1",
+        date: "2026-05-14T10:00:00.000Z",
+      },
+    ]);
+  });
+
+  it("drops empty activity rows and decodes common HTML entities", () => {
+    expect(
+      mapMastodonStatusRows(
+        [
+          {
+            created_at: "2026-05-14T10:00:00.000Z",
+            content: "",
+            url: "https://mastodon.social/users/Gargron/statuses/1/activity",
+            account: { acct: "Gargron", display_name: "Eugen Rochko" },
+          },
+          {
+            created_at: "2026-05-14T11:00:00.000Z",
+            content: "<p>Don&#39;t escape &amp; ship</p>",
+            url: "https://mastodon.social/@Gargron/2",
+            account: { acct: "Gargron", display_name: "Eugen Rochko" },
+          },
+        ],
+        10,
+      ),
+    ).toEqual([
+      {
+        rank: 1,
+        author: "Eugen Rochko",
+        handle: "@Gargron",
+        content: "Don't escape & ship",
+        reblogs: 0,
+        favorites: 0,
+        replies: 0,
+        url: "https://mastodon.social/@Gargron/2",
+        date: "2026-05-14T11:00:00.000Z",
+      },
+    ]);
+  });
+});

package/src/adapters/mastodon/statuses.ts

@@ -0,0 +1,208 @@
+/**
+ * @owner   Mastodon user status adapter.
+ * @does    Register a public read command for recent statuses by account handle.
+ * @needs   Mastodon-compatible public API endpoints for account lookup and statuses.
+ * @feeds   Social research workflows and social capability coverage.
+ * @breaks  Instance API drift, blocked public egress, or accounts hidden from public lookup.
+ */
+
+import { USER_AGENT } from "../../constants.js";
+import { cli, Strategy } from "../../registry.js";
+
+interface MastodonAccount {
+  id?: unknown;
+  acct?: unknown;
+  display_name?: unknown;
+}
+
+interface MastodonStatus {
+  created_at?: unknown;
+  content?: unknown;
+  url?: unknown;
+  reblogs_count?: unknown;
+  favourites_count?: unknown;
+  replies_count?: unknown;
+  account?: MastodonAccount;
+}
+
+export interface MastodonAccountRef {
+  acct: string;
+  instance: string;
+}
+
+export interface MastodonStatusRow {
+  rank: number;
+  author: string;
+  handle: string;
+  content: string;
+  reblogs: number;
+  favorites: number;
+  replies: number;
+  url: string;
+  date: string;
+}
+
+function cleanString(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function numberValue(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function stripHtml(value: unknown): string {
+  return cleanString(value)
+    .replace(/<[^>]*>/g, "")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function normalizeMastodonAccount(
+  input: string,
+  instanceOverride = "mastodon.social",
+): MastodonAccountRef {
+  const trimmed = input.trim().replace(/^@/, "");
+  if (!trimmed) throw new Error("Mastodon account cannot be empty");
+  const parts = trimmed.split("@").filter(Boolean);
+  if (parts.length > 2) {
+    throw new Error(`Invalid Mastodon account: ${input}`);
+  }
+  const acct = parts[0];
+  const instance = parts[1] ?? instanceOverride.trim();
+  if (!acct || !instance) {
+    throw new Error(`Invalid Mastodon account: ${input}`);
+  }
+  return { acct, instance };
+}
+
+export function mapMastodonStatusRows(
+  statuses: MastodonStatus[],
+  limit: number,
+): MastodonStatusRow[] {
+  const rows: Omit<MastodonStatusRow, "rank">[] = [];
+  for (const status of statuses) {
+    const content = stripHtml(status.content).slice(0, 500);
+    if (!content) continue;
+    const account = status.account ?? {};
+    const handle = cleanString(account.acct);
+    rows.push({
+      author: cleanString(account.display_name) || handle,
+      handle: handle ? `@${handle}` : "",
+      content,
+      reblogs: numberValue(status.reblogs_count),
+      favorites: numberValue(status.favourites_count),
+      replies: numberValue(status.replies_count),
+      url: cleanString(status.url),
+      date: cleanString(status.created_at),
+    });
+  }
+  return rows.slice(0, limit).map((row, index) => ({
+    rank: index + 1,
+    ...row,
+  }));
+}
+
+function parseLimit(value: unknown): number {
+  const limit = Number(value ?? 20);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 40) {
+    throw new Error(
+      `--limit must be an integer between 1 and 40, got ${value}`,
+    );
+  }
+  return limit;
+}
+
+async function fetchMastodonJson(url: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/json",
+      "User-Agent": USER_AGENT,
+    },
+  });
+  if (!response.ok) {
+    const preview = (await response.text()).slice(0, 200);
+    throw new Error(`Mastodon HTTP ${response.status} from ${url}: ${preview}`);
+  }
+  return response.json() as Promise<unknown>;
+}
+
+function requireAccountId(account: unknown): string {
+  if (!account || typeof account !== "object") {
+    throw new Error("Mastodon account lookup returned a non-object response");
+  }
+  const id = cleanString((account as MastodonAccount).id);
+  if (!id) throw new Error("Mastodon account lookup did not return an id");
+  return id;
+}
+
+cli({
+  site: "mastodon",
+  name: "statuses",
+  description: "Get recent public statuses from a Mastodon account",
+  domain: "mastodon.social",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "account",
+      required: true,
+      positional: true,
+      description: "Account handle, e.g. gargron@mastodon.social",
+    },
+    {
+      name: "instance",
+      type: "str",
+      default: "mastodon.social",
+      description: "Mastodon instance domain used when account omits one",
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 20,
+      description: "Number of statuses, 1-40",
+    },
+  ],
+  columns: [
+    "rank",
+    "author",
+    "handle",
+    "content",
+    "reblogs",
+    "favorites",
+    "replies",
+    "url",
+    "date",
+  ],
+  socialCapabilities: ["read", "user_content", "reactions"],
+  func: async (_page, kwargs) => {
+    const limit = parseLimit(kwargs.limit);
+    const account = normalizeMastodonAccount(
+      String(kwargs.account ?? ""),
+      String(kwargs.instance ?? "mastodon.social"),
+    );
+    const origin = `https://${account.instance}`;
+    const lookupUrl = new URL("/api/v1/accounts/lookup", origin);
+    lookupUrl.searchParams.set("acct", account.acct);
+    const lookup = await fetchMastodonJson(lookupUrl.toString());
+    const accountId = requireAccountId(lookup);
+    const statusesUrl = new URL(
+      `/api/v1/accounts/${encodeURIComponent(accountId)}/statuses`,
+      origin,
+    );
+    statusesUrl.searchParams.set("limit", String(limit));
+    statusesUrl.searchParams.set("exclude_reblogs", "false");
+    statusesUrl.searchParams.set("exclude_replies", "false");
+    const statuses = await fetchMastodonJson(statusesUrl.toString());
+    if (!Array.isArray(statuses)) {
+      throw new Error(
+        "Mastodon statuses endpoint returned a non-array response",
+      );
+    }
+    return mapMastodonStatusRows(statuses as MastodonStatus[], limit);
+  },
+});

package/src/adapters/patsnap/get.yaml

@@ -0,0 +1,65 @@
+# PatSnap Eureka — single-record fetch.
+#
+# verification_status: blocked-by-subscription
+#
+# Maps to PatSnap's /patent/biblio/{publication_number} endpoint. The same
+# OAuth2 token resolution pattern as `patsnap/search.yaml`.
+site: patsnap
+name: get
+description: Retrieve one PatSnap patent record by publication number
+domain: connect.zhihuiya.com
+type: web-api
+strategy: header
+
+args:
+  publication_number:
+    type: str
+    required: true
+    positional: true
+
+pipeline:
+  - oauth2-token:
+      token_url: https://connect.zhihuiya.com/oauth/token
+      client_id_env: PATSNAP_CLIENT_ID
+      client_secret_env: PATSNAP_CLIENT_SECRET
+      site: patsnap
+      destination: auth.bearer
+
+  - fetch:
+      url: "https://connect.zhihuiya.com/patent/biblio"
+      params:
+        patent_number: "${{ args.publication_number }}"
+      headers:
+        Authorization: "Bearer ${{ auth.bearer }}"
+
+  - select: data
+
+  - map:
+      publication_number: "${{ item.pn }}"
+      title: "${{ item.title }}"
+      abstract: "${{ item.abstract }}"
+      kind_code: "${{ item.kind_code || item.kindcode || '' }}"
+      filing_date: "${{ item.apdt || '' }}"
+      publication_date: "${{ item.pbdt || '' }}"
+      grant_date: "${{ item.grant_date || item.granted || '' }}"
+      priority_date: "${{ item.priority_date || item.prdate || '' }}"
+      application_number: "${{ item.application_number || item.an || '' }}"
+      family_id: "${{ item.simple_family_id || '' }}"
+      legal_status: "${{ item.legal_status || '' }}"
+      inventors: "${{ JSON.stringify((function(){ var i=item.inventor || item.inventors; if(!i) return []; if(typeof i === 'string') return i.split(/\\s*[\\|;,]\\s*/).filter(s => s).map(name => ({ name: name })); return Array.isArray(i) ? i.map(n => ({ name: typeof n === 'string' ? n : (n.name || ''), country: n.country || undefined })) : []; })()) }}"
+      assignees: "${{ JSON.stringify((function(){ var a=item.current_assignee || item.assignee || item.assignees; if(!a) return []; if(typeof a === 'string') return a.split(/\\s*[\\|;,]\\s*/).filter(s => s).map(name => ({ name: name })); return Array.isArray(a) ? a.map(n => ({ name: typeof n === 'string' ? n : (n.name || ''), country: n.country || undefined })) : []; })()) }}"
+      classifications: "${{ JSON.stringify((function(){ var out=[]; var ipc=item.ipc; if(ipc){ var arr = Array.isArray(ipc) ? ipc : String(ipc).split(/[\\|;,]/); for (var i=0;i<arr.length;i++){ var c = arr[i]; var code = typeof c === 'string' ? c.trim() : (c.code || ''); if(code) out.push({ scheme: 'ipc', code: code }); } } var cpc=item.cpc; if(cpc){ var arr2 = Array.isArray(cpc) ? cpc : String(cpc).split(/[\\|;,]/); for (var j=0;j<arr2.length;j++){ var c2 = arr2[j]; var code2 = typeof c2 === 'string' ? c2.trim() : (c2.code || ''); if(code2) out.push({ scheme: 'cpc', code: code2 }); } } return out; })()) }}"
+      cited_by_count: "${{ item.cited_by !== undefined ? item.cited_by : (item.citation_count !== undefined ? item.citation_count : '') }}"
+      cites_count: "${{ item.cites !== undefined ? item.cites : '' }}"
+      source_adapter: patsnap
+      source_url: "${{ 'https://analytics.zhihuiya.com/patent/' + (item.pn || '') }}"
+      retrieved_at: "${{ now }}"
+
+columns: [publication_number, title, legal_status, source_adapter]
+
+capabilities: ["http.fetch", "patent.get"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/patsnap/search.yaml

@@ -0,0 +1,77 @@
+# PatSnap Eureka — OAuth2 client_credentials search.
+#
+# verification_status: blocked-by-subscription
+#
+# PatSnap is a commercial patent intelligence platform. API access requires a
+# Connect / Eureka subscription with two static credentials (CLIENT_ID /
+# CLIENT_SECRET) the buyer pastes into env vars. The `oauth2-token` step
+# resolves the bearer once and caches it; downstream fetch reuses it.
+site: patsnap
+name: search
+description: PatSnap Eureka patent search via OAuth2 client_credentials
+domain: connect.zhihuiya.com
+type: web-api
+strategy: header
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+  limit:
+    type: int
+    default: 20
+
+pipeline:
+  - oauth2-token:
+      token_url: https://connect.zhihuiya.com/oauth/token
+      client_id_env: PATSNAP_CLIENT_ID
+      client_secret_env: PATSNAP_CLIENT_SECRET
+      site: patsnap
+      destination: auth.bearer
+
+  - fetch:
+      url: https://connect.zhihuiya.com/search/patent/query-search-patent/v2
+      method: POST
+      headers:
+        Authorization: "Bearer ${{ auth.bearer }}"
+        Content-Type: application/json
+      body:
+        text: "${{ args.query }}"
+        offset: 0
+        limit: "${{ args.limit }}"
+
+  - select: data.results
+
+  # PatSnap Eureka response carries inventors / assignees / classifications
+  # under documented field names.
+  - map:
+      publication_number: "${{ item.pn || item.pbd_number }}"
+      title: "${{ item.title }}"
+      abstract: "${{ item.abstract }}"
+      kind_code: "${{ item.kind_code || item.kindcode || '' }}"
+      filing_date: "${{ item.apdt || '' }}"
+      publication_date: "${{ item.pbdt || '' }}"
+      grant_date: "${{ item.grant_date || item.granted || '' }}"
+      priority_date: "${{ item.priority_date || item.prdate || '' }}"
+      application_number: "${{ item.application_number || item.an || '' }}"
+      family_id: "${{ item.simple_family_id || '' }}"
+      inventors: "${{ JSON.stringify((function(){ var i=item.inventor || item.inventors; if(!i) return []; if(typeof i === 'string') return i.split(/\\s*[\\|;,]\\s*/).filter(s => s).map(name => ({ name: name })); return Array.isArray(i) ? i.map(n => ({ name: typeof n === 'string' ? n : (n.name || ''), country: n.country || undefined })) : []; })()) }}"
+      assignees: "${{ JSON.stringify((function(){ var a=item.current_assignee || item.assignee || item.assignees; if(!a) return []; if(typeof a === 'string') return a.split(/\\s*[\\|;,]\\s*/).filter(s => s).map(name => ({ name: name })); return Array.isArray(a) ? a.map(n => ({ name: typeof n === 'string' ? n : (n.name || ''), country: n.country || undefined })) : []; })()) }}"
+      classifications: "${{ JSON.stringify((function(){ var out=[]; var ipc=item.ipc; if(ipc){ var arr = Array.isArray(ipc) ? ipc : String(ipc).split(/[\\|;,]/); for (var i=0;i<arr.length;i++){ var c = arr[i]; var code = typeof c === 'string' ? c.trim() : (c.code || ''); if(code) out.push({ scheme: 'ipc', code: code }); } } var cpc=item.cpc; if(cpc){ var arr2 = Array.isArray(cpc) ? cpc : String(cpc).split(/[\\|;,]/); for (var j=0;j<arr2.length;j++){ var c2 = arr2[j]; var code2 = typeof c2 === 'string' ? c2.trim() : (c2.code || ''); if(code2) out.push({ scheme: 'cpc', code: code2 }); } } return out; })()) }}"
+      cited_by_count: "${{ item.cited_by !== undefined ? item.cited_by : (item.citation_count !== undefined ? item.citation_count : '') }}"
+      cites_count: "${{ item.cites !== undefined ? item.cites : '' }}"
+      source_adapter: patsnap
+      source_url: "${{ 'https://analytics.zhihuiya.com/patent/' + (item.pn || item.pbd_number || '') }}"
+      retrieved_at: "${{ now }}"
+
+  - limit: ${{ args.limit }}
+
+columns: [publication_number, title, publication_date, source_adapter]
+
+capabilities: ["http.fetch", "patent.search"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/pqai/prior-art.yaml

@@ -0,0 +1,59 @@
+# Project PQAI — semantic prior-art retrieval.
+#
+# verification_status: blocked-by-key
+#
+# PQAI publishes a permanent free tier for non-commercial use, but rate limits
+# beyond ~100 queries / day require their USD 20 / month plan. The token is a
+# single string passed as a `token=` query param (the only auth scheme PQAI
+# offers today). Set $PQAI_API_TOKEN.
+site: pqai
+name: prior-art
+description: Semantic prior-art retrieval via PQAI's embedding-based ranker
+domain: api.projectpq.ai
+type: web-api
+strategy: public
+
+args:
+  abstract:
+    type: str
+    required: true
+    description: Candidate abstract or claim text
+  limit:
+    type: int
+    default: 20
+
+pipeline:
+  - fetch:
+      url: https://api.projectpq.ai/search/102
+      params:
+        q: "${{ args.abstract }}"
+        n: "${{ args.limit }}"
+        type: patent
+        token: "${{ env.PQAI_API_TOKEN || '' }}"
+
+  - select: results
+
+  # PQAI ships per-result `score` (semantic embedding cosine, ∈ [0, 1]).
+  # Forward as relevance_score so the meta-command's RRF stage can fuse it.
+  - map:
+      publication_number: "${{ item.id }}"
+      title: "${{ item.title }}"
+      abstract: "${{ item.abstract }}"
+      publication_date: "${{ item.publication_date || '' }}"
+      filing_date: "${{ item.filing_date || '' }}"
+      kind_code: "${{ item.kind_code || '' }}"
+      relevance_score: "${{ item.score !== undefined ? item.score : '' }}"
+      source_adapter: pqai
+      source_url: "https://search.projectpq.ai/patent/${{ item.id }}"
+      retrieved_at: "${{ now }}"
+
+  - limit: ${{ args.limit }}
+
+columns: [publication_number, title, abstract]
+
+capabilities: ["http.fetch", "patent.prior-art"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/pqai/search.yaml

@@ -0,0 +1,60 @@
+# Project PQAI — free-text keyword search.
+#
+# verification_status: blocked-by-key
+#
+# PQAI ships a `/search/102` endpoint that accepts both natural-language and
+# Boolean queries. This adapter exposes it as the standard patent.search
+# capability; the prior-art-specific tuning lives in pqai/prior-art.yaml.
+site: pqai
+name: search
+description: Keyword + semantic patent search through PQAI's hybrid index
+domain: api.projectpq.ai
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+  limit:
+    type: int
+    default: 20
+
+pipeline:
+  - fetch:
+      url: https://api.projectpq.ai/search/102
+      params:
+        q: "${{ args.query }}"
+        n: "${{ args.limit }}"
+        type: patent
+        token: "${{ env.PQAI_API_TOKEN || '' }}"
+
+  - select: results
+
+  # PQAI returns `score` (∈ [0, 1] semantic relevance) alongside the patent
+  # record. Surface it as relevance_score so the downstream RRF stage can
+  # consult the per-engine ranking.
+  - map:
+      publication_number: "${{ item.id }}"
+      title: "${{ item.title }}"
+      abstract: "${{ item.abstract }}"
+      publication_date: "${{ item.publication_date || '' }}"
+      filing_date: "${{ item.filing_date || '' }}"
+      kind_code: "${{ item.kind_code || '' }}"
+      relevance_score: "${{ item.score !== undefined ? item.score : '' }}"
+      source_adapter: pqai
+      source_url: "https://search.projectpq.ai/patent/${{ item.id }}"
+      retrieved_at: "${{ now }}"
+
+  - limit: ${{ args.limit }}
+
+columns: [publication_number, title, publication_date]
+
+capabilities: ["http.fetch", "patent.search"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/reddit/comments-tree.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+
+import { extractRedditCommentRows } from "./comments.js";
+import { normalizeCommentRows } from "../../social/comments.js";
+
+describe("reddit comments tree extraction", () => {
+  it("preserves nested reply hierarchy from Reddit JSON listings", () => {
+    const rawRows = extractRedditCommentRows(
+      [
+        { data: { children: [] } },
+        {
+          data: {
+            children: [
+              {
+                kind: "t1",
+                data: {
+                  id: "root",
+                  name: "t1_root",
+                  parent_id: "t3_post",
+                  author: "alice",
+                  body: "root body",
+                  score: 10,
+                  created_utc: 1,
+                  replies: {
+                    data: {
+                      children: [
+                        {
+                          kind: "t1",
+                          data: {
+                            id: "child",
+                            name: "t1_child",
+                            parent_id: "t1_root",
+                            author: "bob",
+                            body: "child body",
+                            score: 3,
+                            created_utc: 2,
+                            replies: "",
+                          },
+                        },
+                      ],
+                    },
+                  },
+                },
+              },
+            ],
+          },
+        },
+      ],
+      "r/test/comments/post/title",
+    );
+
+    const rows = normalizeCommentRows(rawRows, {
+      platform: "reddit",
+      contentId: "r/test/comments/post/title",
+    });
+
+    expect(rows).toEqual([
+      expect.objectContaining({
+        comment_id: "t1_root",
+        parent_id: "",
+        depth: 0,
+        path: "0001",
+        author: "alice",
+        text: "root body",
+        likes: 10,
+        replies: 1,
+      }),
+      expect.objectContaining({
+        comment_id: "t1_child",
+        parent_id: "t1_root",
+        depth: 1,
+        path: "0001.0001",
+        author: "bob",
+        text: "child body",
+        likes: 3,
+      }),
+    ]);
+  });
+});