@digital-science-dsl/dimensions-analytics-mcp 0.5.3

package/src/dsl/commands/functions/ClassifyCommand.ts

@@ -0,0 +1,129 @@
+/**
+ * Command for classifying text using Dimensions classification systems.
+ * @module commands/functions/ClassifyCommand
+ */
+
+import { z } from "zod";
+import { Command, ValidationError } from "../../../client/index.js";
+import {
+  CLASSIFICATION_SYSTEMS,
+  type ClassificationSystem,
+  type ClassifyInput,
+  type ClassifyResponse,
+} from "../../types/special-functions.js";
+import { escapeDslString } from "../../utils/escape.js";
+import { validateInput } from "../validate-input.js";
+
+/**
+ * Zod schema for ClassifyCommand input validation.
+ */
+export const ClassifyInputSchema = z
+  .object({
+    /** Document title (at least title or abstract must be provided) */
+    title: z.string().optional().describe("Document title for classification"),
+    /** Document abstract (at least title or abstract must be provided) */
+    abstract: z.string().optional().describe("Document abstract for classification"),
+    /** Classification system to use */
+    system: z.enum(CLASSIFICATION_SYSTEMS).describe("Classification system to use"),
+  })
+  .refine((data) => data.title || data.abstract, {
+    message: "At least one of title or abstract must be provided",
+    path: ["title", "abstract"],
+  });
+
+/**
+ * Input type for ClassifyCommand (raw input).
+ */
+export type ClassifyCommandInput = z.input<typeof ClassifyInputSchema>;
+
+/**
+ * Parsed input type for ClassifyCommand (after validation).
+ */
+export type ClassifyCommandParsedInput = z.output<typeof ClassifyInputSchema>;
+
+/**
+ * Zod schema for validating API response structure.
+ */
+const ClassifyApiResponseSchema = z.record(
+  z.string(),
+  z.array(
+    z.object({
+      id: z.string(),
+      name: z.string(),
+    }),
+  ),
+);
+
+/**
+ * Command for classifying text using Dimensions classification systems.
+ * Supports FOR, SDG, RCDC, and other research classification taxonomies.
+ *
+ * @template S - The classification system type
+ *
+ * @example
+ * ```typescript
+ * const cmd = new ClassifyCommand({
+ *   title: "Burnout and intentions to quit the nursing profession",
+ *   abstract: "BACKGROUND: Burnout is an occupational disease...",
+ *   system: "FOR"
+ * });
+ *
+ * const result = await client.send(cmd);
+ * console.log(result.FOR); // Array of classification entries
+ * ```
+ */
+export class ClassifyCommand<S extends ClassificationSystem = ClassificationSystem> extends Command<
+  ClassifyCommandParsedInput,
+  ClassifyResponse<S>
+> {
+  static readonly inputSchema = ClassifyInputSchema;
+
+  readonly input: ClassifyCommandParsedInput;
+
+  /**
+   * Creates a new ClassifyCommand.
+   * @param input - Command input parameters
+   * @throws {ValidationError} If input validation fails
+   */
+  constructor(input: ClassifyInput & { system: S }) {
+    super();
+    this.input = validateInput(ClassifyInputSchema, input);
+  }
+
+  /**
+   * Resolves the DSL query for this command.
+   * @returns The constructed DSL query string
+   */
+  resolveQuery(): string {
+    const parts: string[] = [];
+
+    if (this.input.title) {
+      parts.push(`title="${escapeDslString(this.input.title)}"`);
+    }
+    if (this.input.abstract) {
+      parts.push(`abstract="${escapeDslString(this.input.abstract)}"`);
+    }
+    parts.push(`system="${this.input.system}"`);
+
+    return `classify(${parts.join(", ")})`;
+  }
+
+  /**
+   * Transforms raw API response to typed output.
+   * @param response - Raw API response
+   * @returns Typed classification results
+   * @throws {ValidationError} If response structure is invalid
+   */
+  transformResponse(response: unknown): ClassifyResponse<S> {
+    const parseResult = ClassifyApiResponseSchema.safeParse(response);
+
+    if (!parseResult.success) {
+      throw new ValidationError("Invalid API response structure", {
+        zodErrors: parseResult.error.issues,
+      });
+    }
+
+    // Return the response with the correct system key
+    return parseResult.data as unknown as ClassifyResponse<S>;
+  }
+}

package/src/dsl/commands/functions/ExtractAffiliationsCommand.ts

@@ -0,0 +1,163 @@
+/**
+ * Command for extracting/resolving affiliations using the Dimensions API.
+ * @module commands/functions/ExtractAffiliationsCommand
+ */
+
+import { z } from "zod";
+import { Command, ValidationError } from "../../../client/index.js";
+import type {
+  AffiliationInput,
+  ExtractAffiliationsInput,
+  ExtractAffiliationsResponse,
+} from "../../types/special-functions.js";
+import { escapeDslString } from "../../utils/escape.js";
+import { validateInput } from "../validate-input.js";
+
+/**
+ * Schema for a single affiliation input.
+ * Must have either affiliation (freetext) or at least name (structured).
+ */
+const AffiliationInputSchema = z
+  .object({
+    affiliation: z.string().optional().describe("Freetext affiliation string"),
+    name: z.string().optional().describe("Organization name"),
+    city: z.string().optional().describe("City"),
+    state: z.string().optional().describe("State/province"),
+    country: z.string().optional().describe("Country"),
+  })
+  .refine((data) => data.affiliation || data.name, {
+    message: "At least one of affiliation (freetext) or name (structured) must be provided",
+  });
+
+/**
+ * Zod schema for ExtractAffiliationsCommand input validation.
+ */
+export const ExtractAffiliationsInputSchema = z.object({
+  affiliations: z
+    .array(AffiliationInputSchema)
+    .min(1, "At least one affiliation must be provided")
+    .describe("Array of affiliations to resolve"),
+  results: z
+    .enum(["basic", "full", "publisher"])
+    .optional()
+    .describe('Results detail level: "basic" (default), "full", or "publisher"'),
+});
+
+/**
+ * Input type for ExtractAffiliationsCommand (raw input).
+ */
+export type ExtractAffiliationsCommandInput = z.input<typeof ExtractAffiliationsInputSchema>;
+
+/**
+ * Parsed input type for ExtractAffiliationsCommand (after validation).
+ */
+export type ExtractAffiliationsCommandParsedInput = z.output<typeof ExtractAffiliationsInputSchema>;
+
+/**
+ * Schema for a single affiliation result.
+ */
+const AffiliationResultSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  country: z.string().optional(),
+  score: z.number().optional(),
+});
+
+/**
+ * Zod schema for validating API response structure.
+ */
+const ExtractAffiliationsResponseSchema = z.object({
+  extracted_affiliations: z.array(AffiliationResultSchema),
+});
+
+/**
+ * Converts an affiliation input to its JSON representation for DSL.
+ * @param aff - The affiliation input
+ * @returns JSON object string
+ */
+function affiliationToJsonObject(aff: AffiliationInput): string {
+  const parts: string[] = [];
+
+  if (aff.affiliation) {
+    parts.push(`"affiliation": "${escapeDslString(aff.affiliation)}"`);
+  }
+  if (aff.name) {
+    parts.push(`"name": "${escapeDslString(aff.name)}"`);
+  }
+  if (aff.city) {
+    parts.push(`"city": "${escapeDslString(aff.city)}"`);
+  }
+  if (aff.state) {
+    parts.push(`"state": "${escapeDslString(aff.state)}"`);
+  }
+  if (aff.country) {
+    parts.push(`"country": "${escapeDslString(aff.country)}"`);
+  }
+
+  return `{${parts.join(", ")}}`;
+}
+
+/**
+ * Command for extracting/resolving affiliations using the Dimensions API.
+ * Takes freetext or structured affiliation data and returns matched organizations.
+ *
+ * @example
+ * ```typescript
+ * const cmd = new ExtractAffiliationsCommand({
+ *   affiliations: [
+ *     { affiliation: "University of Oxford, UK" },
+ *     { name: "Stanford", city: "Stanford", country: "USA" }
+ *   ]
+ * });
+ *
+ * const result = await client.send(cmd);
+ * console.log(result.extracted_affiliations);
+ * // [{ id: "grid.xxx", name: "University of Oxford", ... }, ...]
+ * ```
+ */
+export class ExtractAffiliationsCommand extends Command<
+  ExtractAffiliationsCommandParsedInput,
+  ExtractAffiliationsResponse
+> {
+  static readonly inputSchema = ExtractAffiliationsInputSchema;
+
+  readonly input: ExtractAffiliationsCommandParsedInput;
+
+  /**
+   * Creates a new ExtractAffiliationsCommand.
+   * @param input - Command input parameters
+   * @throws {ValidationError} If input validation fails
+   */
+  constructor(input: ExtractAffiliationsInput) {
+    super();
+    this.input = validateInput(ExtractAffiliationsInputSchema, input);
+  }
+
+  /**
+   * Resolves the DSL query for this command.
+   * @returns The constructed DSL query string
+   */
+  resolveQuery(): string {
+    const jsonObjects = this.input.affiliations.map(affiliationToJsonObject);
+    const resultsSuffix = this.input.results ? `, results="${this.input.results}"` : "";
+    return `extract_affiliations(json=[${jsonObjects.join(", ")}]${resultsSuffix})`;
+  }
+
+  /**
+   * Transforms raw API response to typed output.
+   * @param response - Raw API response
+   * @returns Typed extraction results
+   * @throws {ValidationError} If response structure is invalid
+   */
+  transformResponse(response: unknown): ExtractAffiliationsResponse {
+    const parseResult = ExtractAffiliationsResponseSchema.safeParse(response);
+
+    if (!parseResult.success) {
+      throw new ValidationError("Invalid API response structure", {
+        zodErrors: parseResult.error.issues,
+      });
+    }
+
+    return parseResult.data;
+  }
+}

package/src/dsl/commands/functions/ExtractConceptsCommand.ts

@@ -0,0 +1,141 @@
+/**
+ * Command for extracting concepts from text using the Dimensions API.
+ * @module commands/functions/ExtractConceptsCommand
+ */
+
+import { z } from "zod";
+import { Command, ValidationError } from "../../../client/index.js";
+import type {
+  ExtractConceptsInput,
+  ExtractConceptsResponse,
+} from "../../types/special-functions.js";
+import { escapeDslString } from "../../utils/escape.js";
+import { validateInput } from "../validate-input.js";
+
+/**
+ * Zod schema for ExtractConceptsCommand input validation.
+ */
+export const ExtractConceptsInputSchema = z.object({
+  /** Text to extract concepts from */
+  text: z.string().min(1, "Text must not be empty").describe("Text to extract concepts from"),
+  /** Whether to include relevance scores in the response */
+  returnScores: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("Include relevance scores for concepts"),
+});
+
+/**
+ * Input type for ExtractConceptsCommand (raw input).
+ */
+export type ExtractConceptsCommandInput = z.input<typeof ExtractConceptsInputSchema>;
+
+/**
+ * Parsed input type for ExtractConceptsCommand (after validation with defaults).
+ */
+export type ExtractConceptsCommandParsedInput = z.output<typeof ExtractConceptsInputSchema>;
+
+/**
+ * Zod schema for validating API response with concept strings.
+ */
+const ConceptsSimpleResponseSchema = z.object({
+  extracted_concepts: z.array(z.string()),
+});
+
+/**
+ * Zod schema for validating API response with concept objects.
+ */
+const ConceptsWithScoresResponseSchema = z.object({
+  extracted_concepts: z.array(
+    z.object({
+      concept: z.string(),
+      relevance: z.number(),
+    }),
+  ),
+});
+
+/**
+ * Command for extracting concepts from text using the Dimensions API.
+ *
+ * @template WithScores - Whether relevance scores are included
+ *
+ * @example
+ * ```typescript
+ * // Simple extraction
+ * const cmd = new ExtractConceptsCommand({
+ *   text: "Machine learning algorithms for drug discovery"
+ * });
+ * const result = await client.send(cmd);
+ * console.log(result.extracted_concepts); // string[]
+ *
+ * // With scores
+ * const cmdScores = new ExtractConceptsCommand({
+ *   text: "Machine learning algorithms for drug discovery",
+ *   returnScores: true
+ * });
+ * const resultScores = await client.send(cmdScores);
+ * console.log(resultScores.extracted_concepts); // { concept, relevance }[]
+ * ```
+ */
+export class ExtractConceptsCommand<WithScores extends boolean = false> extends Command<
+  ExtractConceptsCommandParsedInput,
+  ExtractConceptsResponse<WithScores>
+> {
+  static readonly inputSchema = ExtractConceptsInputSchema;
+
+  readonly input: ExtractConceptsCommandParsedInput;
+
+  /**
+   * Creates a new ExtractConceptsCommand.
+   * @param input - Command input parameters
+   * @throws {ValidationError} If input validation fails
+   */
+  constructor(input: ExtractConceptsInput & { returnScores?: WithScores }) {
+    super();
+    this.input = validateInput(ExtractConceptsInputSchema, input);
+  }
+
+  /**
+   * Resolves the DSL query for this command.
+   * @returns The constructed DSL query string
+   */
+  resolveQuery(): string {
+    const escapedText = escapeDslString(this.input.text);
+
+    if (this.input.returnScores) {
+      return `extract_concepts("${escapedText}", return_scores=true)`;
+    }
+    return `extract_concepts("${escapedText}")`;
+  }
+
+  /**
+   * Transforms raw API response to typed output.
+   * @param response - Raw API response
+   * @returns Typed extraction results
+   * @throws {ValidationError} If response structure is invalid
+   */
+  transformResponse(response: unknown): ExtractConceptsResponse<WithScores> {
+    if (this.input.returnScores) {
+      const parseResult = ConceptsWithScoresResponseSchema.safeParse(response);
+
+      if (!parseResult.success) {
+        throw new ValidationError("Invalid API response structure", {
+          zodErrors: parseResult.error.issues,
+        });
+      }
+
+      return parseResult.data as unknown as ExtractConceptsResponse<WithScores>;
+    } else {
+      const parseResult = ConceptsSimpleResponseSchema.safeParse(response);
+
+      if (!parseResult.success) {
+        throw new ValidationError("Invalid API response structure", {
+          zodErrors: parseResult.error.issues,
+        });
+      }
+
+      return parseResult.data as unknown as ExtractConceptsResponse<WithScores>;
+    }
+  }
+}

package/src/dsl/commands/functions/ExtractGrantsCommand.ts

@@ -0,0 +1,112 @@
+/**
+ * Command for extracting/resolving grants using the Dimensions API.
+ * @module commands/functions/ExtractGrantsCommand
+ */
+
+import { z } from "zod";
+import { Command, ValidationError } from "../../../client/index.js";
+import type { ExtractGrantsInput, ExtractGrantsResponse } from "../../types/special-functions.js";
+import { escapeDslString } from "../../utils/escape.js";
+import { validateInput } from "../validate-input.js";
+
+/**
+ * Zod schema for ExtractGrantsCommand input validation.
+ */
+export const ExtractGrantsInputSchema = z.object({
+  grantNumber: z
+    .string()
+    .min(1, "Grant number must not be empty")
+    .describe("Grant number to look up"),
+  fundref: z.string().optional().describe("FundRef ID of the funder"),
+  funderName: z.string().optional().describe("Funder name (alternative to fundref)"),
+});
+
+/**
+ * Input type for ExtractGrantsCommand (raw input).
+ */
+export type ExtractGrantsCommandInput = z.input<typeof ExtractGrantsInputSchema>;
+
+/**
+ * Parsed input type for ExtractGrantsCommand (after validation).
+ */
+export type ExtractGrantsCommandParsedInput = z.output<typeof ExtractGrantsInputSchema>;
+
+/**
+ * Zod schema for validating API response structure.
+ * The Dimensions API returns a single resolved grant ID, or null if not found.
+ */
+const ExtractGrantsResponseSchema = z.object({
+  grant_id: z.string().nullable(),
+});
+
+/**
+ * Command for extracting/resolving grants using the Dimensions API.
+ * Takes a grant number and optional funder information to find matching grants.
+ *
+ * @example
+ * ```typescript
+ * const cmd = new ExtractGrantsCommand({
+ *   grantNumber: "R01HL117329",
+ *   fundref: "100000050"
+ * });
+ *
+ * const result = await client.send(cmd);
+ * console.log(result.extracted_grants);
+ * // [{ id: "grant.xxx", title: "...", funder: "NIH", ... }]
+ * ```
+ */
+export class ExtractGrantsCommand extends Command<
+  ExtractGrantsCommandParsedInput,
+  ExtractGrantsResponse
+> {
+  static readonly inputSchema = ExtractGrantsInputSchema;
+
+  readonly input: ExtractGrantsCommandParsedInput;
+
+  /**
+   * Creates a new ExtractGrantsCommand.
+   * @param input - Command input parameters
+   * @throws {ValidationError} If input validation fails
+   */
+  constructor(input: ExtractGrantsInput) {
+    super();
+    this.input = validateInput(ExtractGrantsInputSchema, input);
+  }
+
+  /**
+   * Resolves the DSL query for this command.
+   * @returns The constructed DSL query string
+   */
+  resolveQuery(): string {
+    const parts: string[] = [];
+
+    parts.push(`grant_number="${escapeDslString(this.input.grantNumber)}"`);
+
+    // Prefer fundref over funderName if both are provided
+    if (this.input.fundref) {
+      parts.push(`fundref="${escapeDslString(this.input.fundref)}"`);
+    } else if (this.input.funderName) {
+      parts.push(`funder_name="${escapeDslString(this.input.funderName)}"`);
+    }
+
+    return `extract_grants(${parts.join(", ")})`;
+  }
+
+  /**
+   * Transforms raw API response to typed output.
+   * @param response - Raw API response
+   * @returns Typed extraction results
+   * @throws {ValidationError} If response structure is invalid
+   */
+  transformResponse(response: unknown): ExtractGrantsResponse {
+    const parseResult = ExtractGrantsResponseSchema.safeParse(response);
+
+    if (!parseResult.success) {
+      throw new ValidationError("Invalid API response structure", {
+        zodErrors: parseResult.error.issues,
+      });
+    }
+
+    return parseResult.data;
+  }
+}

package/src/dsl/commands/functions/index.ts

@@ -0,0 +1,31 @@
+/**
+ * DSL special function commands for the Dimensions API.
+ * Provides classify, extract_concepts, extract_affiliations, and extract_grants operations.
+ * @module commands/functions
+ */
+
+export {
+  ClassifyCommand,
+  type ClassifyCommandInput,
+  type ClassifyCommandParsedInput,
+  ClassifyInputSchema,
+} from "./ClassifyCommand.js";
+export {
+  ExtractAffiliationsCommand,
+  type ExtractAffiliationsCommandInput,
+  type ExtractAffiliationsCommandParsedInput,
+  ExtractAffiliationsInputSchema,
+} from "./ExtractAffiliationsCommand.js";
+export {
+  ExtractConceptsCommand,
+  type ExtractConceptsCommandInput,
+  type ExtractConceptsCommandParsedInput,
+  ExtractConceptsInputSchema,
+} from "./ExtractConceptsCommand.js";
+
+export {
+  ExtractGrantsCommand,
+  type ExtractGrantsCommandInput,
+  type ExtractGrantsCommandParsedInput,
+  ExtractGrantsInputSchema,
+} from "./ExtractGrantsCommand.js";

package/src/dsl/commands/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Commands for the Dimensions API client.
+ * @module commands
+ */
+
+export type { ExtendedWhereFilterInput, WhereFilterInput } from "./facet/index.js";
+export {
+  EntitySchema,
+  ExtendedWhereFilterSchema,
+  WhereFilterSchema,
+} from "./facet/index.js";
+export {
+  ClassifyCommand,
+  type ClassifyCommandInput,
+  type ClassifyCommandParsedInput,
+  ClassifyInputSchema,
+  ExtractAffiliationsCommand,
+  type ExtractAffiliationsCommandInput,
+  type ExtractAffiliationsCommandParsedInput,
+  ExtractAffiliationsInputSchema,
+  ExtractConceptsCommand,
+  type ExtractConceptsCommandInput,
+  type ExtractConceptsCommandParsedInput,
+  ExtractConceptsInputSchema,
+  ExtractGrantsCommand,
+  type ExtractGrantsCommandInput,
+  type ExtractGrantsCommandParsedInput,
+  ExtractGrantsInputSchema,
+} from "./functions/index.js";

package/src/dsl/commands/validate-input.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared input validation helper for command constructors.
+ * Reduces boilerplate across all Command subclasses.
+ * @module commands/validate-input
+ */
+
+import type { z } from "zod";
+import { ValidationError } from "../../client/index.js";
+
+/**
+ * Validates input against a Zod schema, returning the parsed result.
+ * Throws a {@link ValidationError} with the first Zod issue message on failure.
+ *
+ * @template T - The Zod schema type
+ * @param schema - Zod schema to validate against
+ * @param input - Raw input to validate
+ * @returns The parsed and validated input
+ * @throws {ValidationError} If validation fails
+ */
+export function validateInput<T extends z.ZodTypeAny>(schema: T, input: unknown): z.output<T> {
+  const result = schema.safeParse(input);
+  if (!result.success) {
+    const firstError = result.error.issues[0];
+    throw new ValidationError(firstError?.message ?? "Validation failed", {
+      zodErrors: result.error.issues,
+    });
+  }
+  return result.data;
+}