mcp-databnf 1.0.0

package/dist/bnf/client.d.ts

@@ -0,0 +1,305 @@
+/**
+ * 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;
+    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 access layer produces. Nothing here knows about MCP. */
+/**
+ * A link to a digitised document held on Gallica.
+ *
+ * This server describes the link and never opens it. `url` is for a person to
+ * follow, and nothing downstream reports what is behind it.
+ */
+interface DigitisedLink {
+    /** The Gallica ARK, as it identifies the document. */
+    ark: string;
+    /** The address to open, exactly as data.bnf.fr publishes it. */
+    url: string;
+    /**
+     * Which statement attached this link to the record.
+     *
+     * `reproduction` is the digitised copy of the edition itself.
+     * `ocr` is the text a machine read off that copy.
+     * `depiction` is an image data.bnf.fr uses to illustrate the record, which
+     * can be a portrait, a title page, or a page of a newspaper that mentions the
+     * subject: it illustrates, and it does not stand for the work.
+     */
+    role: "reproduction" | "ocr" | "depiction";
+    /** Which record carried it, so a caller can say where a link came from. */
+    fromId: string;
+    fromTitle: string | null;
+}
+/** One row of an author search. */
+interface AuthorSummary {
+    /** The identifier get_author takes. */
+    id: string;
+    /** The name as data.bnf.fr writes it on the person. */
+    name: string | null;
+    /** The heading as the authority file writes it, usually with the dates. */
+    label: string | null;
+    birthYear: number | null;
+    deathYear: number | null;
+    /** What the record says the person did, often a single word. */
+    role: string | null;
+    sourceUrl: string;
+}
+/** One person, read in full. */
+interface AuthorDetail {
+    id: string;
+    name: string | null;
+    label: string | null;
+    givenName: string | null;
+    familyName: string | null;
+    /** Other headings the record carries, each with the language it is written in. */
+    otherNames: Array<{
+        label: string;
+        language: string | null;
+    }>;
+    birthDate: string | null;
+    deathDate: string | null;
+    birthYear: number | null;
+    deathYear: number | null;
+    birthPlace: string | null;
+    deathPlace: string | null;
+    /**
+     * What the record states about the person, which is a job title far more
+     * often than a sentence.
+     */
+    biographicalInformation: string | null;
+    /** The occupation the record names. */
+    occupation: string | null;
+    /** Languages, as ISO 639-2 codes the record points at. */
+    languages: string[];
+    /** Countries, as the codes the record points at. */
+    countries: string[];
+    /** Fields of activity in words, as the record writes them. */
+    fields: string[];
+    /** Dewey classes the fields of activity point at, as `800` rather than a URL. */
+    deweyClasses: string[];
+    /** Addresses for the same person in other files, grouped by the file. */
+    sameAs: Record<string, string[]>;
+    /** The classes the record is typed with, which say what kind of thing it is. */
+    types: string[];
+    /** True when the record was longer than one query reads, so parts are missing. */
+    truncated: boolean;
+    /** The record in the BnF general catalogue. */
+    catalogueUrl: string | null;
+    /** When the authority record was created and last changed, as published. */
+    recordCreated: string | null;
+    recordModified: string | null;
+    /** Images data.bnf.fr attaches to the person, as links. */
+    depictions: DigitisedLink[];
+    sourceUrl: string;
+}
+/** One row of a work search. */
+interface WorkSummary {
+    id: string;
+    title: string | null;
+    /** The year the record gives the work, as published. */
+    date: string | null;
+    /** Everyone the record credits with the work. */
+    creators: Array<{
+        id: string;
+        name: string | null;
+    }>;
+    /**
+     * Whether the BnF has established this work as a record of its own, or holds
+     * it provisionally while a cataloguer settles it.
+     */
+    status: "established" | "provisional";
+    sourceUrl: string;
+}
+/** One work, read in full. */
+interface WorkDetail {
+    id: string;
+    title: string | null;
+    /** The label the record carries, which can differ from the title in case. */
+    label: string | null;
+    date: string | null;
+    firstYear: number | null;
+    creators: Array<{
+        id: string;
+        name: string | null;
+    }>;
+    /** Languages of the work, as the codes the record points at. */
+    languages: string[];
+    /** Forms, as the words the BnF vocabulary uses. */
+    forms: string[];
+    /** Subjects in words. */
+    subjects: string[];
+    /** Dewey classes the subjects point at. */
+    deweyClasses: string[];
+    status: "established" | "provisional";
+    /** What the record itself says about how settled it is. */
+    statusStatement: string | null;
+    /**
+     * How many expressions the record links, which is not a count of editions.
+     * Null when the record was longer than one query reads, since the number
+     * would then be the ceiling rather than the count.
+     */
+    expressionCount: number | null;
+    sameAs: Record<string, string[]>;
+    /** The classes the record is typed with, which say what kind of thing it is. */
+    types: string[];
+    /** True when the record was longer than one query reads, so parts are missing. */
+    truncated: boolean;
+    catalogueUrl: string | null;
+    depictions: DigitisedLink[];
+    sourceUrl: string;
+}
+/** One published edition of a work. */
+interface Edition {
+    id: string;
+    title: string | null;
+    /** The date as published, which can be a phrase such as `[s.d.]`. */
+    date: string | null;
+    year: number | null;
+    publisher: string | null;
+    place: string | null;
+    /** The edition statement, when the record carries one. */
+    editionStatement: string | null;
+    /** The extent, in the words of the record: pages, volumes, discs. */
+    extent: string | null;
+    isbn: string | null;
+    /** Notes the cataloguer wrote, as published. */
+    note: string | null;
+    /** The record in the BnF general catalogue. */
+    catalogueUrl: string | null;
+    /** Digitised copies of this edition, as links this server does not open. */
+    digitised: DigitisedLink[];
+    sourceUrl: string;
+}
+/** A page of rows, and whether the endpoint held more. */
+interface Page<T> {
+    rows: T[];
+    /**
+     * True when the endpoint answered with at least one row beyond the page.
+     *
+     * The tools report this rather than a total: counting every match means a
+     * second query over the same span, and a count would read as a ranking on a
+     * search that does not rank.
+     */
+    hasMore: boolean;
+    /** Rows the endpoint sent that could not be read, present only when some were. */
+    skipped?: number;
+}
+
+type EntityKind = "ark" | "temp-work";
+interface EntityId {
+    kind: EntityKind;
+    /** The bare identifier, as a person would quote it. */
+    id: string;
+    /** The address of the thing itself, which the queries bind to. */
+    iri: string;
+    /** The page a person can open. */
+    pageUrl: string;
+}
+
+/**
+ * The one place that talks to data.bnf.fr.
+ *
+ * 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 runs a query, parses it and only then stores: an answer nobody
+ * could parse must not be served back for the rest of the cache's lifetime.
+ *
+ * Every read also carries the moment the metadata came off the endpoint. The
+ * licence asks for the date of retrieval alongside the source, so that date is
+ * a value the layer produces rather than something a caller is trusted to add.
+ */
+
+interface ClientOptions {
+    config?: Partial<Config>;
+    logger?: Logger;
+    fetchImpl?: typeof fetch;
+}
+/** Every read reports where the value came from and when it was retrieved. */
+interface Read<T> {
+    data: T;
+    cached: boolean;
+    /**
+     * When the metadata came off data.bnf.fr, as an ISO 8601 instant.
+     *
+     * A cached answer keeps the moment it was first read. Reporting the moment it
+     * was served would state a date of retrieval that never happened, which is
+     * exactly the claim the licence asks to be accurate.
+     */
+    retrievedAt: string;
+    /** Rows the endpoint sent that could not be read, which paging still counts. */
+    skipped?: number;
+}
+declare class BnfClient {
+    private readonly config;
+    private readonly logger;
+    private readonly limiter;
+    private readonly cache;
+    /** Questions already on the wire, so an identical one waits instead of asking. */
+    private readonly inFlight;
+    private readonly fetchImpl;
+    constructor(options?: ClientOptions);
+    /** The pacing in force, which widens when the endpoint pushes back. */
+    get intervalMs(): number;
+    /** What the BnF sees this client call itself. */
+    get userAgent(): string;
+    /** The deadline one query is given, which callers report rather than guess. */
+    get timeoutMs(): number;
+    /** The one address this client sends anything to. */
+    get endpoint(): string;
+    /**
+     * `cacheKey` is stated rather than taken from the query, because two reads of
+     * one query can produce different values: a list cut to five rows is not the
+     * same value as the same list cut to twenty, and serving one for the other
+     * would answer a size the caller never asked for.
+     */
+    private read;
+    private fetchAndParse;
+    /** Read an identifier a caller wrote, refusing anything this dataset cannot address. */
+    identify(input: string): EntityId;
+    /** The words a search will actually look for, which a tool reports back. */
+    words(input: string): string[];
+    searchAuthors(name: string, limit: number, offset: number): Promise<Read<Page<AuthorSummary>>>;
+    getAuthor(id: EntityId): Promise<Read<AuthorDetail>>;
+    /**
+     * Say what an address is, when it is not the kind of thing that was asked for.
+     *
+     * A record the catalogue does not describe at all and a record describing
+     * something else are two different answers, and only one of them means the
+     * caller should go looking elsewhere.
+     */
+    private refuse;
+    searchWorks(title: string, limit: number, offset: number): Promise<Read<Page<WorkSummary>>>;
+    getWork(id: EntityId): Promise<Read<WorkDetail>>;
+    listEditions(id: EntityId, limit: number, offset: number): Promise<Read<Page<Edition>>>;
+    /** Digitised documents attached to a work and to its editions. */
+    digitisedForWork(id: EntityId, limit: number): Promise<Read<Page<DigitisedLink>>>;
+    /** Digitised documents attached to a person and to the editions of their works. */
+    digitisedForPerson(id: EntityId, limit: number): Promise<Read<Page<DigitisedLink>>>;
+    /** What an address is typed as, which tells a person from a work. */
+    types(id: EntityId): Promise<Read<string[]>>;
+}
+
+export { BnfClient, type ClientOptions, type Read };