@wentorai/research-plugins 1.3.2 → 1.4.2

package/src/tools/openaire.ts

@@ -0,0 +1,158 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+
+const BASE = "https://api.openaire.eu";
+
+/**
+ * Parse OpenAIRE XML response wrapped in JSON.
+ * OpenAIRE returns XML by default; with format=json it wraps XML nodes in JSON objects.
+ */
+function parseOpenAireResult(result: Record<string, unknown>): Record<string, unknown> {
+  const metadata = result.metadata as Record<string, unknown> | undefined;
+  const oafEntity = metadata?.["oaf:entity"] as Record<string, unknown> | undefined;
+  const oafResult = oafEntity?.["oaf:result"] as Record<string, unknown> | undefined;
+
+  if (!oafResult) {
+    // Flat JSON format (newer API versions)
+    return {
+      title: result.title,
+      authors: result.authors,
+      doi: result.doi,
+      url: result.url,
+    };
+  }
+
+  // Extract title
+  const titleRaw = oafResult.title;
+  let title = "";
+  if (Array.isArray(titleRaw)) {
+    const main = titleRaw.find((t: Record<string, string>) => t["@classid"] === "main title");
+    title = (main ?? titleRaw[0])?.["$"] ?? "";
+  } else if (typeof titleRaw === "object" && titleRaw !== null) {
+    title = (titleRaw as Record<string, string>)["$"] ?? "";
+  }
+
+  // Extract authors
+  const creatorsRaw = oafResult.creator;
+  const authors: string[] = [];
+  if (Array.isArray(creatorsRaw)) {
+    for (const c of creatorsRaw) {
+      const name = typeof c === "string" ? c : (c as Record<string, string>)["$"];
+      if (name) authors.push(name);
+    }
+  } else if (creatorsRaw) {
+    const name = typeof creatorsRaw === "string" ? creatorsRaw : (creatorsRaw as Record<string, string>)["$"];
+    if (name) authors.push(name);
+  }
+
+  // Extract DOI and other identifiers
+  const pidRaw = oafResult.pid;
+  let doi: string | undefined;
+  if (Array.isArray(pidRaw)) {
+    const doiPid = pidRaw.find((p: Record<string, string>) => p["@classid"] === "doi");
+    doi = (doiPid as Record<string, string> | undefined)?.["$"];
+  } else if (typeof pidRaw === "object" && pidRaw !== null) {
+    if ((pidRaw as Record<string, string>)["@classid"] === "doi") {
+      doi = (pidRaw as Record<string, string>)["$"];
+    }
+  }
+
+  // Extract dates
+  const dateRaw = oafResult.dateofacceptance;
+  const date = typeof dateRaw === "string" ? dateRaw : (dateRaw as Record<string, string> | undefined)?.["$"];
+
+  // Extract best access right
+  const accessRaw = oafResult.bestaccessright;
+  const isOa = typeof accessRaw === "object" && accessRaw !== null
+    ? (accessRaw as Record<string, string>)["@classid"] === "OPEN"
+    : false;
+
+  return {
+    title,
+    authors,
+    doi,
+    date,
+    is_oa: isOa,
+    url: doi ? `https://doi.org/${doi}` : undefined,
+  };
+}
+
+export function createOpenAireTools(
+  _ctx: OpenClawPluginToolContext,
+  _api: OpenClawPluginApi,
+) {
+  return [
+    {
+      name: "search_openaire",
+      label: "Search Publications (OpenAIRE)",
+      description:
+        "Search OpenAIRE for publications (170M+ records). Uniquely supports filtering by EU funding source (EC, NSF, etc.) and project ID.",
+      parameters: Type.Object({
+        keywords: Type.String({
+          description: "Search keywords",
+        }),
+        author: Type.Optional(Type.String({ description: "Author name" })),
+        doi: Type.Optional(Type.String({ description: "DOI" })),
+        from_date: Type.Optional(
+          Type.String({ description: "From date (YYYY-MM-DD)" }),
+        ),
+        to_date: Type.Optional(
+          Type.String({ description: "To date (YYYY-MM-DD)" }),
+        ),
+        oa_only: Type.Optional(
+          Type.Boolean({ description: "Only open access results" }),
+        ),
+        funder: Type.Optional(
+          Type.String({
+            description: "Funder abbreviation: 'EC' (EU), 'NSF', 'NIH', 'UKRI', 'DFG', etc.",
+          }),
+        ),
+        max_results: Type.Optional(
+          Type.Number({ description: "Max results (default 10, max 50)" }),
+        ),
+      }),
+      execute: async (input: {
+        keywords: string;
+        author?: string;
+        doi?: string;
+        from_date?: string;
+        to_date?: string;
+        oa_only?: boolean;
+        funder?: string;
+        max_results?: number;
+      }) => {
+        const params = new URLSearchParams({
+          keywords: input.keywords,
+          format: "json",
+          size: String(Math.min(input.max_results ?? 10, 50)),
+        });
+        if (input.author) params.set("author", input.author);
+        if (input.doi) params.set("doi", input.doi);
+        if (input.from_date) params.set("fromDateAccepted", input.from_date);
+        if (input.to_date) params.set("toDateAccepted", input.to_date);
+        if (input.oa_only) params.set("OA", "true");
+        if (input.funder) params.set("funder", input.funder);
+
+        const tracked = await trackedFetch("openaire", `${BASE}/search/publications?${params}`, undefined, 15_000);
+        if (isTrackedError(tracked)) return tracked;
+        const data = await tracked.res.json();
+
+        const response = data.response as Record<string, unknown> | undefined;
+        const header = response?.header as Record<string, unknown> | undefined;
+        const total = header?.total as Record<string, string> | undefined;
+        const results = response?.results as Record<string, unknown> | undefined;
+        const resultList = results?.result;
+
+        const papers = (Array.isArray(resultList) ? resultList : []).map(
+          (r: Record<string, unknown>) => parseOpenAireResult(r),
+        );
+
+        return toolResult({
+          total_results: total?.["$"] ? parseInt(total["$"], 10) : papers.length,
+          papers,
+        });
+      },
+    },
+  ];
+}

package/src/tools/openalex.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError } from "./util.js";
 
 const BASE = "https://api.openalex.org";
 
@@ -58,9 +58,9 @@ export function createOpenAlexTools(
         if (filters.length > 0) params.set("filter", filters.join(","));
         if (input.sort_by) params.set("sort", input.sort_by);
 
-        const res = await fetch(`${BASE}/works?${params}`, { headers });
-        if (!res.ok) return toolResult({ error: `API error: ${res.status} ${res.statusText}` });
-        const data = await res.json();
+        const tracked = await trackedFetch("openalex", `${BASE}/works?${params}`, { headers });
+        if (isTrackedError(tracked)) return tracked;
+        const data = await tracked.res.json();
         return toolResult({
           total_count: data.meta?.count,
           results: data.results?.map((w: Record<string, unknown>) => ({
@@ -78,6 +78,7 @@ export function createOpenAlexTools(
                 )
               : [],
           })),
+          _source_health: { source: "openalex", latency_ms: tracked.latency_ms },
         });
       },
     },
@@ -93,14 +94,15 @@ export function createOpenAlexTools(
         }),
       }),
       execute: async (input: { work_id: string }) => {
+        if (!input?.work_id) {
+          return toolResult({ error: 'work_id parameter is required (e.g., "W2741809807" or a DOI like "10.1234/example")' });
+        }
         const id = input.work_id.startsWith("10.")
           ? `https://doi.org/${input.work_id}`
           : input.work_id;
-        const res = await fetch(`${BASE}/works/${encodeURIComponent(id)}`, {
-          headers,
-        });
-        if (!res.ok) return toolResult({ error: `API error: ${res.status} ${res.statusText}` });
-        const w = await res.json();
+        const tracked = await trackedFetch("openalex", `${BASE}/works/${encodeURIComponent(id)}`, { headers });
+        if (isTrackedError(tracked)) return tracked;
+        const w = await tracked.res.json();
         return toolResult({
           id: w.id,
           doi: w.doi,
@@ -120,6 +122,7 @@ export function createOpenAlexTools(
             ?.slice(0, 10)
             .map((c: Record<string, unknown>) => c.display_name),
           referenced_works_count: w.referenced_works?.length,
+          _source_health: { source: "openalex", latency_ms: tracked.latency_ms },
         });
       },
     },
@@ -135,6 +138,9 @@ export function createOpenAlexTools(
         }),
       }),
       execute: async (input: { author_id: string }) => {
+        if (!input?.author_id) {
+          return toolResult({ error: 'author_id parameter is required (OpenAlex ID e.g. "A5023888391", ORCID, or author name)' });
+        }
         let url: string;
         if (
           input.author_id.startsWith("A") ||
@@ -148,14 +154,18 @@ export function createOpenAlexTools(
             search: input.author_id,
             per_page: "5",
           });
-          const res = await fetch(`${BASE}/authors?${params}`, { headers });
-          if (!res.ok) return toolResult({ error: `API error: ${res.status} ${res.statusText}` });
-          return toolResult(await res.json());
+          const tracked = await trackedFetch("openalex", `${BASE}/authors?${params}`, { headers });
+          if (isTrackedError(tracked)) return tracked;
+          const data = await tracked.res.json();
+          return toolResult({
+            ...data,
+            _source_health: { source: "openalex", latency_ms: tracked.latency_ms },
+          });
         }
 
-        const res = await fetch(url, { headers });
-        if (!res.ok) return toolResult({ error: `API error: ${res.status} ${res.statusText}` });
-        const a = await res.json();
+        const tracked = await trackedFetch("openalex", url, { headers });
+        if (isTrackedError(tracked)) return tracked;
+        const a = await tracked.res.json();
         return toolResult({
           id: a.id,
           display_name: a.display_name,
@@ -171,6 +181,7 @@ export function createOpenAlexTools(
           top_concepts: a.x_concepts
             ?.slice(0, 5)
             .map((c: Record<string, unknown>) => c.display_name),
+          _source_health: { source: "openalex", latency_ms: tracked.latency_ms },
         });
       },
     },

package/src/tools/opencitations.ts

@@ -0,0 +1,112 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+
+const BASE = "https://api.opencitations.net";
+
+/**
+ * Extract DOI from OpenCitations multi-identifier string.
+ * Format: "omid:br/... doi:10.1038/nature12373 openalex:W..."
+ */
+function extractDoi(multiId: string): string | undefined {
+  const match = multiId.match(/doi:(10\.\S+)/);
+  return match ? match[1] : undefined;
+}
+
+export function createOpenCitationsTools(
+  _ctx: OpenClawPluginToolContext,
+  _api: OpenClawPluginApi,
+) {
+  return [
+    {
+      name: "get_citations_open",
+      label: "Get Citations (OpenCitations)",
+      description:
+        "Get all papers citing a given DOI using OpenCitations (2B+ open citation links). Works across all disciplines.",
+      parameters: Type.Object({
+        doi: Type.String({
+          description: "DOI of the paper, e.g. '10.1038/nature12373'",
+        }),
+      }),
+      execute: async (input: { doi: string }) => {
+        if (!input?.doi) {
+          return toolResult({ error: 'doi parameter is required (e.g., "10.1038/nature12373")' });
+        }
+        const doi = input.doi.replace(/^https?:\/\/doi\.org\//, "");
+        const tracked = await trackedFetch("opencitations", `${BASE}/index/v2/citations/doi:${encodeURIComponent(doi)}`);
+        if (isTrackedError(tracked)) return tracked;
+        const data = await tracked.res.json();
+
+        if (!Array.isArray(data)) return toolResult({ error: "Unexpected response format" });
+
+        return toolResult({
+          total_citations: data.length,
+          citations: data.slice(0, 100).map((c: Record<string, string>) => ({
+            citing_doi: extractDoi(c.citing ?? ""),
+            cited_doi: extractDoi(c.cited ?? ""),
+            creation_date: c.creation,
+          })),
+          _source_health: { source: "opencitations", latency_ms: tracked.latency_ms },
+        });
+      },
+    },
+    {
+      name: "get_references_open",
+      label: "Get References (OpenCitations)",
+      description:
+        "Get all references of a paper by DOI. Shows what a paper cites.",
+      parameters: Type.Object({
+        doi: Type.String({
+          description: "DOI of the paper, e.g. '10.1038/nature12373'",
+        }),
+      }),
+      execute: async (input: { doi: string }) => {
+        if (!input?.doi) {
+          return toolResult({ error: 'doi parameter is required (e.g., "10.1038/nature12373")' });
+        }
+        const doi = input.doi.replace(/^https?:\/\/doi\.org\//, "");
+        const tracked = await trackedFetch("opencitations", `${BASE}/index/v2/references/doi:${encodeURIComponent(doi)}`);
+        if (isTrackedError(tracked)) return tracked;
+        const data = await tracked.res.json();
+
+        if (!Array.isArray(data)) return toolResult({ error: "Unexpected response format" });
+
+        return toolResult({
+          total_references: data.length,
+          references: data.slice(0, 100).map((r: Record<string, string>) => ({
+            cited_doi: extractDoi(r.cited ?? ""),
+            citing_doi: extractDoi(r.citing ?? ""),
+            creation_date: r.creation,
+          })),
+          _source_health: { source: "opencitations", latency_ms: tracked.latency_ms },
+        });
+      },
+    },
+    {
+      name: "get_citation_count",
+      label: "Get Citation Count (OpenCitations)",
+      description:
+        "Get the total citation count for a DOI from OpenCitations open data.",
+      parameters: Type.Object({
+        doi: Type.String({
+          description: "DOI of the paper, e.g. '10.1038/nature12373'",
+        }),
+      }),
+      execute: async (input: { doi: string }) => {
+        if (!input?.doi) {
+          return toolResult({ error: 'doi parameter is required (e.g., "10.1038/nature12373")' });
+        }
+        const doi = input.doi.replace(/^https?:\/\/doi\.org\//, "");
+        const tracked = await trackedFetch("opencitations", `${BASE}/index/v2/citation-count/doi:${encodeURIComponent(doi)}`);
+        if (isTrackedError(tracked)) return tracked;
+        const data = await tracked.res.json();
+
+        const count = Array.isArray(data) && data[0]?.count
+          ? parseInt(data[0].count, 10)
+          : 0;
+
+        return toolResult({ doi, citation_count: count, _source_health: { source: "opencitations", latency_ms: tracked.latency_ms } });
+      },
+    },
+  ];
+}

package/src/tools/orcid.ts

@@ -0,0 +1,139 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+
+const BASE = "https://pub.orcid.org/v3.0";
+
+const HEADERS: Record<string, string> = {
+  Accept: "application/json",
+};
+
+export function createOrcidTools(
+  _ctx: OpenClawPluginToolContext,
+  _api: OpenClawPluginApi,
+) {
+  return [
+    {
+      name: "search_orcid",
+      label: "Search Researchers (ORCID)",
+      description:
+        "Search the ORCID registry for researchers by name, affiliation, or keyword. Returns ORCID iDs that can be used with get_orcid_works.",
+      parameters: Type.Object({
+        query: Type.String({
+          description:
+            "Lucene-style query. Supports fields: family-name, given-names, affiliation-org-name, keyword, orcid, ringgold-org-id. E.g. 'family-name:Smith AND affiliation-org-name:MIT'",
+        }),
+        limit: Type.Optional(
+          Type.Number({ description: "Max results (default 10, max 100)" }),
+        ),
+      }),
+      execute: async (input: { query: string; limit?: number }) => {
+        const params = new URLSearchParams({
+          q: input.query,
+          rows: String(Math.min(input.limit ?? 10, 100)),
+        });
+
+        const result = await trackedFetch(
+          "orcid",
+          `${BASE}/search/?${params}`,
+          { headers: HEADERS },
+          10_000,
+        );
+        if (isTrackedError(result)) return result;
+        const data = await result.res.json();
+
+        const researchers = (data.result ?? []).map(
+          (r: Record<string, unknown>) => {
+            const oi = r["orcid-identifier"] as Record<string, string> | undefined;
+            return {
+              orcid: oi?.path,
+              uri: oi?.uri,
+              source: "orcid",
+            };
+          },
+        );
+
+        return toolResult({
+          total_results: data["num-found"],
+          source: "orcid",
+          researchers,
+          _latency_ms: result.latency_ms,
+        });
+      },
+    },
+    {
+      name: "get_orcid_works",
+      label: "Get Works by ORCID (ORCID)",
+      description:
+        "Get the publication list for a researcher by their ORCID iD. Returns titles, DOIs, publication years, and work types.",
+      parameters: Type.Object({
+        orcid: Type.String({
+          description: "ORCID iD, e.g. '0000-0002-1825-0097'",
+        }),
+      }),
+      execute: async (input: { orcid: string }) => {
+        if (!input?.orcid) {
+          return toolResult({ error: 'orcid parameter is required (e.g., "0000-0002-1825-0097")' });
+        }
+        const orcid = input.orcid.replace(/^https?:\/\/orcid\.org\//, "");
+
+        const result = await trackedFetch(
+          "orcid",
+          `${BASE}/${encodeURIComponent(orcid)}/works`,
+          { headers: HEADERS },
+          10_000,
+        );
+        if (isTrackedError(result)) return result;
+        const data = await result.res.json();
+
+        const groups = data.group as Array<Record<string, unknown>> | undefined;
+
+        const works = (groups ?? []).map((g) => {
+          const summaries = g["work-summary"] as Array<Record<string, unknown>> | undefined;
+          const first = summaries?.[0];
+          if (!first) return null;
+
+          // Extract title
+          const titleObj = first.title as Record<string, unknown> | undefined;
+          const title = (titleObj?.title as Record<string, string> | undefined)?.value;
+
+          // Extract publication date
+          const pubDate = first["publication-date"] as Record<string, unknown> | undefined;
+          const year = (pubDate?.year as Record<string, string> | undefined)?.value;
+          const month = (pubDate?.month as Record<string, string> | undefined)?.value;
+
+          // Extract DOI from external-ids
+          const extIds = first["external-ids"] as Record<string, unknown> | undefined;
+          const extIdList = extIds?.["external-id"] as Array<Record<string, unknown>> | undefined;
+          const doiEntry = extIdList?.find(
+            (e) => e["external-id-type"] === "doi" && e["external-id-relationship"] === "self",
+          );
+          const doi = doiEntry?.["external-id-value"] as string | undefined;
+
+          // Extract journal title
+          const journalTitle = first["journal-title"] as Record<string, string> | undefined;
+
+          return {
+            title,
+            doi,
+            year,
+            month,
+            type: first.type,
+            journal: journalTitle?.value,
+            url: doi ? `https://doi.org/${doi}` : undefined,
+            authors: undefined as string[] | undefined, // ORCID works endpoint does not include author lists
+            source: "orcid",
+          };
+        }).filter(Boolean);
+
+        return toolResult({
+          orcid,
+          total_works: works.length,
+          source: "orcid",
+          works,
+          _latency_ms: result.latency_ms,
+        });
+      },
+    },
+  ];
+}

package/src/tools/osf-preprints.ts

@@ -0,0 +1,104 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+
+const BASE = "https://api.osf.io/v2";
+
+export function createOsfPreprintsTools(
+  _ctx: OpenClawPluginToolContext,
+  _api: OpenClawPluginApi,
+) {
+  return [
+    {
+      name: "search_osf_preprints",
+      label: "Search Preprints (OSF)",
+      description:
+        "Search OSF Preprints, an aggregator covering 180K+ preprints across multiple providers including SocArXiv, PsyArXiv, EarthArXiv, EngrXiv, and NutriXiv. Covers social sciences, psychology, earth sciences, engineering, and more.",
+      parameters: Type.Object({
+        provider: Type.Optional(
+          Type.String({
+            description:
+              "Preprint provider filter: 'osf', 'socarxiv', 'psyarxiv', 'engrxiv', 'eartharxiv', 'nutrixiv'. Omit for all providers.",
+          }),
+        ),
+        size: Type.Optional(
+          Type.Number({ description: "Max results (default 10, max 100)" }),
+        ),
+        page: Type.Optional(
+          Type.Number({ description: "Page number (default 1)" }),
+        ),
+      }),
+      execute: async (input: {
+        provider?: string;
+        size?: number;
+        page?: number;
+      }) => {
+        const params = new URLSearchParams({
+          "page[size]": String(Math.min(input.size ?? 10, 100)),
+        });
+        if (input.provider) params.set("filter[provider]", input.provider);
+        if (input.page) params.set("page", String(input.page));
+
+        const result = await trackedFetch(
+          "osf_preprints",
+          `${BASE}/preprints/?${params}`,
+          {
+            headers: {
+              Accept: "application/vnd.api+json",
+            },
+          },
+          20_000,
+        );
+        if (isTrackedError(result)) return result;
+        const data = await result.res.json();
+
+        const items = data.data as Array<Record<string, unknown>> | undefined;
+        const linksMeta = (data.links as Record<string, unknown>)?.meta as Record<string, unknown> | undefined;
+
+        return toolResult({
+          total_results: linksMeta?.total,
+          page: input.page ?? 1,
+          source: "osf_preprints",
+          preprints: (items ?? []).map((item) => {
+            const attrs = item.attributes as Record<string, unknown> | undefined;
+            const relationships = item.relationships as Record<string, unknown> | undefined;
+            const providerData = (
+              relationships?.provider as Record<string, unknown> | undefined
+            )?.data as Record<string, string> | undefined;
+            const subjects = attrs?.subjects as Array<Array<{ id: string; text: string }>> | undefined;
+
+            // Flatten nested subject arrays
+            const subjectNames = subjects
+              ?.flat()
+              .map((s) => s.text)
+              .filter(Boolean);
+
+            return {
+              id: item.id,
+              title: attrs?.title,
+              description: attrs?.description
+                ? String(attrs.description).slice(0, 500)
+                : undefined,
+              doi: attrs?.doi ?? undefined,
+              date_created: attrs?.date_created,
+              date_published: attrs?.date_published,
+              year: attrs?.date_published
+                ? String(attrs.date_published).slice(0, 4)
+                : attrs?.date_created
+                  ? String(attrs.date_created).slice(0, 4)
+                  : undefined,
+              provider: providerData?.id,
+              tags: attrs?.tags,
+              subjects: subjectNames,
+              is_published: attrs?.is_published,
+              authors: undefined as string[] | undefined, // OSF preprint list does not embed contributor names
+              url: `https://osf.io/preprints/${providerData?.id ?? "osf"}/${String(item.id).replace(/_v\d+$/, "")}`,
+              source: "osf_preprints",
+            };
+          }),
+          _latency_ms: result.latency_ms,
+        });
+      },
+    },
+  ];
+}