/**
 * The user's paper library: text of papers read, kept in the cache folder.
 *
 * Two kinds of entry:
 * - "open": text from an open copy (arXiv, a repository, an open-access
 *   publisher, SportRxiv). Read tools return it in full, by section.
 * - "user": a paper the user supplied, from a file or from Zotero, which may
 *   be paid access. Read tools return its outline and short passages only.
 *
 * Every file here is written with mode 0600 in a 0700 folder. Each entry
 * carries the FORMAT marker, which the public-safety test looks for in the
 * repository so that paper text can never be committed.
 */
import { type Env, FetchError, type PaperContext } from "./core.js";
import type { PaperRecord } from "./records.js";
import { type Section } from "./text.js";
export declare const FORMAT = "football-docs/paper-text/v1";
/**
 * The version of the text extraction. Raise it when extraction changes in a
 * way that makes stored text wrong; open copies saved under an older version
 * are then fetched again. (2: MathML formulas kept once, not twice.) Papers
 * the user supplied are kept, since only they can supply them again.
 */
export declare const TEXT_VERSION = 2;
export type Access = "open" | "user";
export type StoredPaper = {
    format: typeof FORMAT;
    /** The ID the entry is filed under: arxiv:…, doi:…, openalex:… or local:…. */
    key: string;
    access: Access;
    title: string;
    authors: string[];
    year?: number;
    ids: PaperRecord["ids"];
    /** Where the text came from: a URL for open copies, a file name or Zotero item for user papers. */
    origin: string;
    licence?: string;
    zotero?: string;
    sha256?: string;
    savedAt: string;
    /** TEXT_VERSION when saved; absent on entries saved before versions existed. */
    textVersion?: number;
    sections: Section[];
};
/** Passage length for user papers: FOOTBALL_DOCS_PAPERS_PASSAGE_CHARS, 50 to 1000, default 200. */
export declare function passageChars(env: Env): number;
/** Every key an entry can be found by: its own key plus its IDs. */
export declare function aliasesOf(entry: Pick<StoredPaper, "key" | "ids" | "zotero" | "access">): string[];
/** Keys compare in lower case, except Zotero item keys, which are capitals. */
export declare function canonicalKey(key: string): string;
export declare function saveEntry(ctx: PaperContext, entry: StoredPaper): void;
export declare function loadEntry(ctx: PaperContext, key: string): StoredPaper | null;
/** User papers whose metadata names this DOI. */
export declare function userEntriesFor(ctx: PaperContext, doi: string): StoredPaper[];
export declare function listEntries(ctx: PaperContext): StoredPaper[];
/** Remove one entry and its aliases. Returns the removed entry, if any. */
export declare function forgetEntry(ctx: PaperContext, key: string): StoredPaper | null;
/** Delete everything in the cache folder: paper text, the index and the SportRxiv copy. */
export declare function purgeAll(ctx: PaperContext): {
    papers: number;
    bytes: number;
};
export declare function expandPath(path: string): string;
export type LocalPdf = {
    sha256: string;
    name: string;
    sections: Section[];
    title?: string;
    author?: string;
    doi?: string;
};
/** Read a PDF the user names. Only regular files that start as a PDF are read. */
export declare function readLocalPdf(path: string): Promise<LocalPdf>;
export declare const ZOTERO_LOCAL = "http://localhost:23119/api/users/0";
export type ZoteroItem = {
    key: string;
    data: {
        key: string;
        itemType: string;
        title?: string;
        creators?: Array<{
            firstName?: string;
            lastName?: string;
            name?: string;
        }>;
        date?: string;
        DOI?: string;
        url?: string;
        publicationTitle?: string;
        contentType?: string;
        linkMode?: string;
        parentItem?: string;
        filename?: string;
    };
};
export type ZoteroRoute = {
    kind: "local" | "web";
    base: string;
    headers: Record<string, string>;
    label: string;
};
/** Forget the user IDs read from keys. Tests only. */
export declare function resetZoteroRoutes(): void;
/**
 * The route to use: the local API when Zotero answers on this computer, else
 * the web API when a key is set. The error names both ways to set one up.
 */
export declare function zoteroRoute(ctx: PaperContext): Promise<ZoteroRoute>;
export declare function zoteroCreators(item: ZoteroItem): string[];
export declare function searchZotero(ctx: PaperContext, query: string, limit: number): Promise<{
    items: ZoteroItem[];
    label: string;
}>;
export declare function fromZotero(item: ZoteroItem): PaperRecord;
/** A Zotero item with no PDF attachment. Carries the item, so a caller can read its DOI instead. */
export declare class NoZoteroPdfError extends FetchError {
    readonly item: ZoteroItem;
    readonly label: string;
    constructor(item: ZoteroItem, label: string);
}
export type ZoteroPaper = {
    item: ZoteroItem;
    attachment: ZoteroItem;
    sections: Section[];
    sha256: string;
    label: string;
};
/**
 * The text of a Zotero item's PDF: the item itself when it is a PDF
 * attachment, else its first PDF attachment. Reads the stored file; when there
 * is none (a linked file, through the web API), uses Zotero's own full-text index.
 */
export declare function readZoteroPaper(ctx: PaperContext, key: string): Promise<ZoteroPaper>;