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

package/dist/dsl/client.d.ts

@@ -0,0 +1,330 @@
+/**
+ * Main DimensionsClient class for interacting with the Dimensions API.
+ * Orchestrates authentication, rate limiting, and HTTP communication.
+ * @module client
+ */
+import type { Command, DimensionsClientConfig, DslResponse, QueryExecutorOptions } from "../client/index.js";
+import { FluentQueryBuilder } from "./fluent-query-builder.js";
+import { QueryBuilder } from "./query-builder.js";
+import type { SchemaStore } from "./schema/index.js";
+import type { ClinicalTrial, Dataset, Grant, Organization, Patent, PolicyDocument, Publication, Researcher } from "./types/entities.js";
+import type { AffiliationInput, ClassificationSystem, ClassifyInput, ClassifyResponse, ExtractAffiliationsResponse, ExtractConceptsResponse, ExtractGrantsInput, ExtractGrantsResponse } from "./types/special-functions.js";
+/**
+ * Rate limit status information.
+ */
+export interface RateLimitInfo {
+    /** Number of requests remaining in the current window */
+    remaining: number;
+    /** Time in milliseconds until the rate limit window resets */
+    resetInMs: number;
+}
+/**
+ * Client for interacting with the Dimensions Analytics API.
+ * Handles authentication, rate limiting, and command execution.
+ *
+ * @example
+ * ```typescript
+ * const client = new DimensionsClient({ apiKey: "your-api-key" });
+ *
+ * const result = await client.send(
+ *   client.rawQuery('search publications for "machine learning" return publications limit 10')
+ * );
+ * ```
+ */
+export declare class DimensionsClient {
+    private readonly config;
+    private readonly authProvider?;
+    private readonly httpClient?;
+    private readonly internalClient?;
+    private readonly rateLimiter;
+    private schemaStore?;
+    /**
+     * Creates a new DimensionsClient instance.
+     * @param config - Client configuration
+     * @throws {ValidationError} If configuration is invalid
+     */
+    constructor(config: DimensionsClientConfig);
+    private executeDslQuery;
+    /**
+     * Sends a command to the Dimensions API.
+     * @param command - The command to execute
+     * @returns The transformed response
+     * @throws {ValidationError} If command input is invalid
+     * @throws {AuthenticationError} If authentication fails
+     * @throws {RateLimitError} If rate limit is exceeded
+     * @throws {QuerySyntaxError} If query syntax is invalid
+     * @throws {ServerError} If server error occurs
+     * @throws {NetworkError} If network error occurs
+     * @throws {TimeoutError} If request times out
+     */
+    send<TInput, TOutput>(command: Command<TInput, TOutput>): Promise<TOutput>;
+    /**
+     * Gets current rate limit status.
+     * @returns Rate limit information
+     */
+    getRateLimitInfo(): RateLimitInfo;
+    /**
+     * Invalidates the cached authentication token.
+     * Forces a new token to be fetched on the next request.
+     */
+    invalidateToken(): void;
+    /**
+     * Resets the rate limiter, clearing all recorded request timestamps.
+     * Useful for testing or when starting a fresh session.
+     */
+    resetRateLimiter(): void;
+    /**
+     * Executes a raw DSL query against the Dimensions API.
+     * Use this for generic/dynamic queries not covered by specific commands.
+     *
+     * @param dsl - The DSL query string to execute
+     * @param options - Optional signal and timeout overrides
+     * @returns The raw API response
+     * @throws {AuthenticationError} If authentication fails
+     * @throws {RateLimitError} If rate limit is exceeded
+     * @throws {QuerySyntaxError} If query syntax is invalid
+     * @throws {ServerError} If server error occurs
+     * @throws {NetworkError} If network error occurs
+     * @throws {TimeoutError} If request times out
+     *
+     * @example
+     * ```typescript
+     * const response = await client.rawQuery(
+     *   'search publications for "CRISPR" return publications[id+title] limit 10'
+     * );
+     * console.log(response.publications);
+     * ```
+     */
+    rawQuery(dsl: string, options?: QueryExecutorOptions): Promise<DslResponse>;
+    /**
+     * Validates a DSL string and throws {@link ValidationError} if it is invalid.
+     * @param dsl - The DSL query string to validate
+     * @throws {ValidationError} If the DSL fails parsing or semantic validation
+     */
+    private assertValidDsl;
+    /**
+     * Attaches a loaded describe schema for QueryBuilder entity/index validation.
+     * @param store - Schema from {@link loadSchema} or {@link getOrLoadSchema}
+     */
+    attachSchemaStore(store: SchemaStore): void;
+    /**
+     * Creates a {@link QueryBuilder} validated against the attached schema when present.
+     * @returns New query builder instance
+     */
+    createQueryBuilder(): QueryBuilder;
+    /**
+     * Creates a type-safe fluent query builder for the specified entity.
+     * @param entity - The entity type key
+     * @returns A FluentQueryBuilder typed to the entity
+     */
+    private createFluentBuilder;
+    /**
+     * Creates a fluent query builder for publications.
+     * @returns A FluentQueryBuilder configured for publications
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .publications()
+     *   .for("machine learning")
+     *   .where("year", ">=", 2020)
+     *   .fields(["id", "title", "doi"])
+     *   .execute();
+     * ```
+     */
+    publications(): FluentQueryBuilder<Publication, "publications">;
+    /**
+     * Creates a fluent query builder for grants.
+     * @returns A FluentQueryBuilder configured for grants
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .grants()
+     *   .for("cancer research")
+     *   .where("funding_usd", ">", 1000000)
+     *   .execute();
+     * ```
+     */
+    grants(): FluentQueryBuilder<Grant, "grants">;
+    /**
+     * Creates a fluent query builder for researchers.
+     * @returns A FluentQueryBuilder configured for researchers
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .researchers()
+     *   .for("smith")
+     *   .whereNotEmpty("orcid_id")
+     *   .execute();
+     * ```
+     */
+    researchers(): FluentQueryBuilder<Researcher, "researchers">;
+    /**
+     * Creates a fluent query builder for patents.
+     * @returns A FluentQueryBuilder configured for patents
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .patents()
+     *   .for("battery technology")
+     *   .where("year", ">=", 2020)
+     *   .execute();
+     * ```
+     */
+    patents(): FluentQueryBuilder<Patent, "patents">;
+    /**
+     * Creates a fluent query builder for clinical trials.
+     * @returns A FluentQueryBuilder configured for clinical_trials
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .clinicalTrials()
+     *   .for("diabetes")
+     *   .where("phase", "=", "Phase 3")
+     *   .execute();
+     * ```
+     */
+    clinicalTrials(): FluentQueryBuilder<ClinicalTrial, "clinical_trials">;
+    /**
+     * Creates a fluent query builder for datasets.
+     * @returns A FluentQueryBuilder configured for datasets
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .datasets()
+     *   .for("genomics")
+     *   .where("year", ">=", 2020)
+     *   .execute();
+     * ```
+     */
+    datasets(): FluentQueryBuilder<Dataset, "datasets">;
+    /**
+     * Creates a fluent query builder for policy documents.
+     * @returns A FluentQueryBuilder configured for policy_documents
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .policyDocuments()
+     *   .for("climate change")
+     *   .execute();
+     * ```
+     */
+    policyDocuments(): FluentQueryBuilder<PolicyDocument, "policy_documents">;
+    /**
+     * Creates a fluent query builder for organizations.
+     * @returns A FluentQueryBuilder configured for organizations
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .organizations()
+     *   .for("stanford")
+     *   .execute();
+     * ```
+     */
+    organizations(): FluentQueryBuilder<Organization, "organizations">;
+    /**
+     * Classifies text using a specified Dimensions classification system.
+     * Supports FOR, SDG, RCDC, and other research classification taxonomies.
+     *
+     * @template S - The classification system type
+     * @param options - Classification options including title, abstract, and system
+     * @returns Classification codes with their names
+     * @throws {ValidationError} If input validation fails
+     * @throws {AuthenticationError} If authentication fails
+     * @throws {QuerySyntaxError} If query syntax is invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await client.classify({
+     *   title: "Burnout and intentions to quit the nursing profession",
+     *   abstract: "BACKGROUND: Burnout is an occupational disease...",
+     *   system: "FOR"
+     * });
+     * console.log(result.FOR); // [{ id: "1117", name: "Public Health..." }]
+     * ```
+     */
+    classify<S extends ClassificationSystem>(options: ClassifyInput & {
+        system: S;
+    }): Promise<ClassifyResponse<S>>;
+    /**
+     * Extracts concepts from text using Dimensions natural language processing.
+     *
+     * @template WithScores - Whether to include relevance scores
+     * @param text - Text to extract concepts from
+     * @param options - Optional settings including returnScores
+     * @returns Array of concepts, optionally with relevance scores
+     * @throws {ValidationError} If input validation fails
+     * @throws {AuthenticationError} If authentication fails
+     * @throws {QuerySyntaxError} If query syntax is invalid
+     *
+     * @example
+     * ```typescript
+     * // Simple extraction
+     * const concepts = await client.extractConcepts(
+     *   "Machine learning algorithms for drug discovery"
+     * );
+     * console.log(concepts.extracted_concepts); // ["machine learning", "drug discovery", ...]
+     *
+     * // With relevance scores
+     * const conceptsWithScores = await client.extractConcepts(
+     *   "Machine learning algorithms for drug discovery",
+     *   { returnScores: true }
+     * );
+     * console.log(conceptsWithScores.extracted_concepts);
+     * // [{ concept: "machine learning", relevance: 0.95 }, ...]
+     * ```
+     */
+    extractConcepts<WithScores extends boolean = false>(text: string, options?: {
+        returnScores?: WithScores;
+    }): Promise<ExtractConceptsResponse<WithScores>>;
+    /**
+     * Extracts and resolves organization affiliations using Dimensions entity resolution.
+     * Takes freetext or structured affiliation data and returns matched organizations.
+     *
+     * @param affiliations - Array of affiliation inputs to resolve
+     * @returns Array of resolved organization matches with confidence scores
+     * @throws {ValidationError} If input validation fails
+     * @throws {AuthenticationError} If authentication fails
+     * @throws {QuerySyntaxError} If query syntax is invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await client.extractAffiliations([
+     *   { affiliation: "University of Oxford, UK" },
+     *   { name: "Stanford", city: "Stanford", country: "USA" }
+     * ]);
+     * console.log(result.extracted_affiliations);
+     * // [{ id: "grid.4991.5", name: "University of Oxford", score: 0.95 }, ...]
+     * ```
+     */
+    extractAffiliations(affiliations: readonly AffiliationInput[]): Promise<ExtractAffiliationsResponse>;
+    /**
+     * Resolves a grant number to a Dimensions grant ID.
+     * Takes a grant number and optional funder information to find the matching grant.
+     *
+     * @param options - Grant lookup parameters
+     * @returns Resolved grant ID, or null if no match found
+     * @throws {ValidationError} If input validation fails
+     * @throws {AuthenticationError} If authentication fails
+     * @throws {QuerySyntaxError} If query syntax is invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await client.extractGrants({
+     *   grantNumber: "R01HL117329",
+     *   fundref: "100000050"
+     * });
+     * console.log(result.grant_id);
+     * // "grant.2544064"
+     * ```
+     */
+    extractGrants(options: ExtractGrantsInput): Promise<ExtractGrantsResponse>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/dsl/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/dsl/client.ts"],"names":[],"mappings":"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"}