mcp-libraryofcongress 1.0.0

package/dist/loc/client.d.ts

@@ -0,0 +1,312 @@
+/**
+ * Settings, read from the environment.
+ *
+ * A value that cannot be read warns and falls back rather than stopping the
+ * server: a typo in one variable should not take away every tool. Warnings go
+ * to stderr, because stdout carries the protocol and anything written there
+ * corrupts the session.
+ */
+declare const LOG_LEVELS: readonly ["silent", "error", "info", "debug"];
+type LogLevel = (typeof LOG_LEVELS)[number];
+interface Config {
+    userAgent: string;
+    minIntervalMs: number;
+    timeoutMs: number;
+    /** Deadline for the full-text newspaper route, which is the slow one. */
+    newspaperTimeoutMs: number;
+    maxRetries: number;
+    cacheTtlMs: number;
+    cacheMaxEntries: number;
+    logLevel: LogLevel;
+}
+interface Logger {
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+
+/** The shapes the API layer produces. Nothing here knows about MCP. */
+/** A catalogue row, trimmed to what picks one record out of a list. */
+interface RecordSummary {
+    /** Opaque, and the string get_item takes. It can carry slashes. */
+    identifier: string | null;
+    title: string | null;
+    /** Whoever the Library credits: author, photographer, publisher, performer. */
+    creator: string | null;
+    /** Read off the date the record carries, when that date names a year. */
+    year: number | null;
+    /** The date exactly as published, which is often a range or a phrase. */
+    date: string | null;
+    /** What the Library calls the physical thing: book, photo, map, newspaper. */
+    format: string | null;
+    /** Places the record is catalogued under. */
+    location: string[];
+    subjects: string[];
+    /** Whether a digitised copy can be read online. */
+    online: boolean;
+    sourceUrl: string;
+}
+/**
+ * How many results a query has, and how the site divides them into pages.
+ *
+ * The two numbers are kept apart on purpose. The site reports the count of
+ * results and the count of pages under names that read alike, and reporting the
+ * page count as a result count multiplies or divides an answer by the page size.
+ */
+interface Paging {
+    /** Results matching the query across every page. */
+    resultCount: number;
+    /** Pages those results are divided into, at the page size in force. */
+    pageCount: number | null;
+    /** The page this answer came from, as the site numbers them. */
+    currentPage: number | null;
+    /** Results a page holds, as the site applied it. */
+    perPage: number | null;
+}
+interface SearchResults {
+    paging: Paging;
+    records: RecordSummary[];
+}
+/**
+ * One newspaper page whose machine-read text matched.
+ *
+ * The text a search returns with a page is the opening of what optical
+ * recognition read off it, not the whole page, so the words searched for are
+ * often further down than the response reaches. `wordsLocated` says which of
+ * the two happened, and the excerpts are cut accordingly.
+ */
+interface NewspaperHit {
+    identifier: string | null;
+    title: string | null;
+    creator: string | null;
+    year: number | null;
+    /** The page within the issue, as the Library numbers it. */
+    pageNumber: number | null;
+    /** Date of the issue, as published: usually YYYY-MM-DD. */
+    publishedOn: string | null;
+    /** The newspaper itself, with the years it ran. */
+    publication: string | null;
+    /** The state the paper was published in, as the Library records it. */
+    state: string | null;
+    /** True when the searched words were found in the text this row carries. */
+    wordsLocated: boolean;
+    /** Passages of machine-read text, cut to the budget the caller set. */
+    excerpts: string[];
+    /** Opens the page itself, already at the right leaf with the query applied. */
+    sourceUrl: string;
+}
+interface NewspaperResults {
+    paging: Paging;
+    hits: NewspaperHit[];
+}
+interface ItemDetail {
+    identifier: string;
+    title: string | null;
+    creator: string | null;
+    year: number | null;
+    date: string | null;
+    format: string | null;
+    /** Every paragraph the Library publishes as the description, joined. */
+    description: string | null;
+    notes: string[];
+    subjects: string[];
+    location: string[];
+    language: string[];
+    /** Collections and divisions the record sits in. */
+    partOf: string[];
+    repository: string | null;
+    callNumber: string | null;
+    /**
+     * What the Library says about reuse. Absent on most records, and silence
+     * here is not permission.
+     */
+    rights: string | null;
+    /** Ready-made citations, in the styles the Library publishes. */
+    citations: Record<string, string>;
+    /** Files that can be downloaded or viewed, one row per served copy. */
+    resources: ItemResource[];
+    sourceUrl: string;
+    /** Every field the Library published for the record, for the caller who wants it. */
+    raw: Record<string, unknown> | null;
+}
+interface ItemResource {
+    caption: string | null;
+    /** Number of files behind this copy, when the Library counts them. */
+    fileCount: number | null;
+    url: string | null;
+    imageUrl: string | null;
+}
+interface CollectionSummary {
+    /** The slug the collection is addressed by, and the string get_item takes. */
+    identifier: string | null;
+    title: string;
+    description: string | null;
+    /** Records gathered in the collection, when the Library counts them. */
+    itemCount: number | null;
+    subjects: string[];
+    formats: string[];
+    sourceUrl: string;
+    /** Lists what the collection holds, one page at a time. */
+    itemsUrl: string | null;
+}
+interface CollectionResults {
+    paging: Paging;
+    collections: CollectionSummary[];
+}
+
+/**
+ * Turning the Library's answers into the shapes this server publishes.
+ *
+ * Two rules run through every function here. A response that cannot be read is
+ * a `parse_failure`, never an empty result, because a caller cannot tell an
+ * empty result from an absence and will report one as the other. And a single
+ * unreadable row among many is skipped rather than failing the page it sat in;
+ * where a parser is given a counter, the rows it dropped are reported.
+ */
+
+interface ExcerptBudget {
+    /** Characters one passage may run to. */
+    maxChars: number;
+    /** Passages kept for one page. */
+    maxCount: number;
+}
+
+/**
+ * One route per kind of thing, which is how the catalogue is divided.
+ *
+ * The vocabulary is the Library's own: a route is a path segment, and the
+ * values a tool accepts are exactly these keys.
+ */
+declare const FORMAT_ROUTE: {
+    readonly books: "/books/";
+    readonly photos: "/photos/";
+    readonly maps: "/maps/";
+    readonly audio: "/audio/";
+    readonly "film-and-videos": "/film-and-videos/";
+    readonly manuscripts: "/manuscripts/";
+    readonly "notated-music": "/notated-music/";
+    readonly newspapers: "/newspapers/";
+};
+type FormatRoute = keyof typeof FORMAT_ROUTE;
+/**
+ * Facet fields a filter may name, and nothing else.
+ *
+ * A facet the site does not know is neither refused nor applied: it answers
+ * with the unfiltered result and no sign that the narrowing was dropped. Only
+ * fields listed here are ever sent, so a filter that reaches the site is one
+ * the site acts on.
+ */
+declare const FACET_FIELD: {
+    readonly subject: "subject";
+    readonly location: "location";
+    readonly language: "language";
+    readonly contributor: "contributor";
+    readonly partof: "partof";
+    /** The state a newspaper was published in, as the newspaper corpus files it. */
+    readonly state: "location_state";
+    /** A newspaper, named with the town and the years it ran. */
+    readonly publication: "partof_title";
+};
+type FacetField = keyof typeof FACET_FIELD;
+/**
+ * Sort orders, mapped from the words the tools use.
+ *
+ * Relevance sends nothing, which is the site's own default.
+ */
+declare const SORT: {
+    readonly relevance: "";
+    readonly newest: "date_desc";
+    readonly oldest: "date";
+    readonly title: "title_s";
+};
+type SortKey = keyof typeof SORT;
+
+/**
+ * Builders for every address the client fetches.
+ *
+ * Query strings are assembled here so no caller can smuggle a parameter past
+ * the checks: which blocks come back, which facet fields may be named and
+ * which sort orders exist are decided by this file, not by whoever calls a
+ * tool. A facet field or a sort order the site does not know is accepted
+ * silently and applied to nothing, so sending only known ones is what keeps a
+ * filter from being quietly dropped.
+ */
+
+type Facets = Partial<Record<FacetField, string>>;
+interface CatalogueQuery {
+    query: string;
+    format: FormatRoute;
+    facets?: Facets;
+    yearFrom?: number;
+    yearTo?: number;
+    sort?: SortKey;
+    /**
+     * When false, the search widens past what the Library has digitised and
+     * takes in catalogue records with no copy to read online.
+     */
+    onlineOnly: boolean;
+    limit: number;
+    page: number;
+}
+/**
+ * The narrowing a full-text newspaper search may carry.
+ *
+ * The corpus files a page under the state it was published in and under the
+ * paper it belongs to, and both are facets the route acts on.
+ */
+interface NewspaperFilters {
+    facets?: Facets;
+    yearFrom?: number;
+    yearTo?: number;
+}
+
+/**
+ * The one place that talks to the Library of Congress.
+ *
+ * It holds a single rate limiter and a single cache, so pacing applies to the
+ * server as a whole rather than to whichever tool happens to be running. It
+ * imports nothing from the MCP layer and is published on its own, so the same
+ * code serves a plain script.
+ *
+ * Every read fetches, parses and only then stores: a response nobody could
+ * parse must not be served back for the rest of the cache's lifetime.
+ */
+
+interface ClientOptions {
+    config?: Partial<Config>;
+    logger?: Logger;
+    fetchImpl?: typeof fetch;
+}
+/** Every read reports whether it went out, so a caller can say what it knows. */
+interface Read<T> {
+    data: T;
+    cached: boolean;
+    /** Rows the site sent that could not be read, which paging still counts. */
+    skipped?: number;
+}
+declare class LocClient {
+    private readonly config;
+    private readonly logger;
+    private readonly limiter;
+    private readonly cache;
+    private readonly fetchImpl;
+    constructor(options?: ClientOptions);
+    /** The pacing in force, which widens when the Library pushes back. */
+    get intervalMs(): number;
+    /** What the Library sees this client call itself. */
+    get userAgent(): string;
+    /**
+     * `cacheKey` is stated rather than taken from the address, because two reads
+     * of one address can produce different values: a passage cut to three hundred
+     * characters is not the same value as the same passage cut to a thousand, and
+     * serving one for the other would answer a budget the caller never set.
+     */
+    private read;
+    searchItems(query: CatalogueQuery): Promise<Read<SearchResults>>;
+    searchNewspapers(query: string, limit: number, page: number, budget: ExcerptBudget, filters?: NewspaperFilters): Promise<Read<NewspaperResults>>;
+    getItem(identifier: string): Promise<Read<ItemDetail>>;
+    listCollections(limit: number, page: number): Promise<Read<CollectionResults>>;
+}
+
+export { type ClientOptions, LocClient, type Read };