schema.d.ts

/* eslint-disable */
/**
 * This file was automatically generated by json-schema-to-typescript.
 * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
 * and run json-schema-to-typescript to regenerate this file.
 */

/**
 * Structured document representation for Zotero. Defines a semantic content tree of block nodes (paragraphs, headings, lists, tables, images, math, code, captions, notes, blockquotes) with inline text styling, cross-references, source anchors, page geometry, and a document outline. Supports PDF, EPUB, and snapshot sources.
 */
export interface StructuredDocumentText {
  /**
   * Semantic version of this schema (major/minor/patch).
   */
  schemaVersion: string;
  /**
   * Processor that generated this document.
   */
  processor: {
    /**
     * Processor type.
     */
    type: "pdf" | "epub" | "snapshot";
    /**
     * Processor version.
     */
    version: string;
  };
  /**
   * Creation time in ISO 8601.
   */
  dateCreated: string;
  /**
   * MIME type of the source.
   */
  sourceContentType: "application/pdf" | "application/epub+zip" | "text/html" | "application/xhtml+xml";
  /**
   * MD5 hash of the source file (32-char hex string) used to detect changes.
   */
  sourceHash: string;
  /**
   * Size of the original source file in bytes.
   */
  fileSize?: number;
  /**
   * Total character count of extracted text content (sum over all text nodes).
   */
  characterCount?: number;
  /**
   * Source-specific metadata. For PDF: PDFFormatVersion, Title, Author, Subject, Keywords, Creator, Producer, CreationDate, ModDate, Language, and any custom properties. For EPUB: dc:title, dc:creator, dc:language, etc. For snapshot: title, url, charset. Shape is open-ended.
   */
  metadata?: {
    [k: string]: unknown;
  };
  /**
   * Document outline (table of contents).
   */
  outline?: OutlineItem[];
  /**
   * Per-page info. For PDF: physical pages. For EPUB: page mappings (physical page numbers or EPUB locations).
   *
   * @minItems 1
   */
  pages?: [PageInfo, ...PageInfo[]];
  /**
   * For EPUB: whether pages represent physical page numbers from the source or synthetic EPUB locations.
   */
  pageMappingType?: "physical" | "locations";
  /**
   * Top-level block nodes (headings, paragraphs, lists, tables, etc.).
   */
  content: ContentBlockNode[];
};
/**
 * Path to the corresponding heading or block in the content tree.
 *
 * @minItems 1
 */
export type RefPath = [number, ...number[]];
/**
 * Target location in the source or an external URL.
 */
export type Target = {
  /**
   * Position in the source document.
   */
  position?: {
    pageIndex?: number;
    /**
     * Page rect: [x1, y1, x2, y2].
     *
     * @minItems 4
     * @maxItems 4
     */
    rect?: [number, number, number, number];
  };
  /**
   * External URL.
   */
  url?: string;
};
/**
 * Block nodes valid as document content, inside containers, and at top level. Excludes structural-only children (ListItemNode, TableRowNode, TableCellNode) that only appear inside their parent containers.
 */
export type ContentBlockNode =
  | ParagraphNode
  | HeadingNode
  | MathNode
  | ImageNode
  | BlockquoteNode
  | ListNode
  | TableNode
  | CaptionNode
  | NoteNode
  | PreformattedNode;
/**
 * Referenced target nodes. Array because one mention can resolve to multiple targets (e.g. "[2-5]" -> multiple bibliography entries, or ambiguous author-name citations).
 */
export type RefsArray = RefPath[];
/**
 * Nodes that reference this one (inverse of refs).
 */
export type BackRefsArray = RefPath[];
/**
 * Link from this node back to the source document. PDF uses PdfAnchor (pageRects/textMap). EPUB and snapshot use DomAnchor with a selectorMap field that compactly encodes source locations. Use the dom/epub and dom/snapshot decode modules to expand and resolve.
 */
export type Anchor = PdfAnchor | DomAnchor;
/**
 * PDF source anchor with page geometry and/or text layout map. `textMap` validation is intentionally permissive (string-only); consumers should parse and validate decoded run structure at runtime.
 */
export type PdfAnchor = {
  /**
   * Bounding boxes on source pages.
   *
   * @minItems 1
   */
  pageRects?: [PageRect, ...PageRect[]];
  /**
   * Packed text layout encoded as a JSON string. Decoded value is an array of runs; each run is `[header, pageIndex, minX, minY, maxX, maxY, ...widths]`. Header bits: bit 0 = trailing soft hyphen marker, bits 1-2 = axis direction, bit 3 = right-to-left flag. Width entries are either numeric widths or `[delta, width]` pairs.
   */
  textMap?: string;
};
/**
 * Block bounding box: [pageIndex, x1, y1, x2, y2] (page coordinates).
 *
 * @minItems 5
 * @maxItems 5
 */
export type PageRect = [number, number, number, number, number];
/**
 * True if this is artifact content (header, footer, margin, etc.).
 */
export type ArtifactFlag = boolean;

/**
 * Single outline entry.
 */
export interface OutlineItem {
  /**
   * Outline item title.
   */
  title: string;
  ref?: RefPath;
  target?: Target;
  children?: OutlineItem[];
}
/**
 * Per-page metadata for the source document.
 */
export interface PageInfo {
  /**
   * Page fingerprint for change detection.
   */
  fingerprint?: string;
  /**
   * True if the page was injected by the publisher.
   */
  injected?: boolean;
  /**
   * Page view box: [x1, y1, x2, y2] (CropBox, or MediaBox if no CropBox). Values can be negative when the PDF defines a page box with a non-zero origin (e.g. [-50, -50, 562, 742]).
   *
   * @minItems 4
   * @maxItems 4
   */
  viewRect?: [number, number, number, number];
  /**
   * Source of text on this page.
   */
  textSource?: "born-digital" | "ocr";
  /**
   * Quality flag for text extraction.
   */
  textQuality?: "good" | "suspect" | "bad";
  /**
   * Human-readable page label (e.g. 'i', '15', 'A-3').
   */
  label?: string;
  /**
   * Content ranges that appear on this page.
   */
  contentRanges?: PageContentRange[];
}
/**
 * Logical content range on a page.
 */
export interface PageContentRange {
  start: {
    ref: RefPath;
    /**
     * Character/code-unit offset within the node.
     */
    offset?: number;
  };
  end: {
    ref: RefPath;
    offset?: number;
  };
}
/**
 * Paragraph block (inline text only).
 */
export interface ParagraphNode {
  /**
   * Discriminator for paragraphs.
   */
  type: "paragraph";
  /**
   * Inline content of the paragraph.
   */
  content: TextNode[];
  anchor: Anchor;
  /**
   * True if this block is a reference entry (e.g. bibliography item).
   */
  reference?: boolean;
  refs?: RefsArray;
  backRefs?: BackRefsArray;
  artifact?: ArtifactFlag;
}
/**
 * Inline text node with optional styling and references.
 */
export interface TextNode {
  /**
   * Plain text, including whitespace and newlines as-is.
   */
  text: string;
  style?: TextStyle;
  refs?: RefsArray;
  backRefs?: BackRefsArray;
  target?: Target;
  anchor?: Anchor;
}
/**
 * Inline text style flags.
 */
export interface TextStyle {
  bold?: boolean;
  italic?: boolean;
  sub?: boolean;
  sup?: boolean;
  monospace?: boolean;
}
/**
 * Compact anchor for EPUB and snapshot blocks and text nodes. For blocks, selectorMap is an absolute location: EPUB CFI path (starts with '/') or snapshot CSS selector. For text nodes, selectorMap is relative to the parent block: EPUB stores a CFI suffix, snapshot stores '' (same element), a bare offset, a ' > child' suffix, or an absolute selector fallback. Multi-entry selectorMaps (from merged adjacent text nodes) are newline-separated 'charLen selectorMap' entries starting with a digit. Use expandSelectorMap() to resolve relative values and expandBlockAnchor() to reconstruct WADM selectors.
 */
export interface DomAnchor {
  /**
   * Compact location string. Blocks: absolute (EPUB CFI path starting with '/', or snapshot CSS selector). Text nodes: relative to parent block (EPUB CFI suffix, snapshot offset / child suffix / empty).
   */
  selectorMap: string;
  /**
   * NFC normalization position map. Space-separated 'nfcPos delta' pairs where delta = nfcIdx - origIdx changes. Absent when text is already NFC (all positions 1:1). Decode: origPos = nfcPos - getDelta(deltaMap, nfcPos).
   */
  deltaMap?: string;
}
/**
 * Heading block (inline text only).
 */
export interface HeadingNode {
  /**
   * Discriminator for headings.
   */
  type: "heading";
  /**
   * Inline content of the heading.
   */
  content: TextNode[];
  anchor: Anchor;
  refs?: RefsArray;
  backRefs?: BackRefsArray;
  artifact?: ArtifactFlag;
}
/**
 * Math block represented as inline text nodes.
 */
export interface MathNode {
  /**
   * Discriminator for math blocks.
   */
  type: "math";
  /**
   * Inline content of the math block.
   */
  content: TextNode[];
  anchor: Anchor;
  refs?: RefsArray;
  backRefs?: BackRefsArray;
  artifact?: ArtifactFlag;
}
/**
 * Image block with optional inline text (alt text, labels).
 */
export interface ImageNode {
  /**
   * Discriminator for images.
   */
  type: "image";
  /**
   * Inline text associated with the image.
   */
  content: TextNode[];
  anchor: Anchor;
  refs?: RefsArray;
  backRefs?: BackRefsArray;
  artifact?: ArtifactFlag;
}
/**
 * Blockquote block that contains other blocks.
 */
export interface BlockquoteNode {
  /**
   * Discriminator for blockquotes.
   */
  type: "blockquote";
  /**
   * Block content inside the blockquote.
   */
  content: ContentBlockNode[];
  anchor: Anchor;
  refs?: RefsArray;
  backRefs?: BackRefsArray;
  artifact?: ArtifactFlag;
}
/**
 * List block containing list items.
 */
export interface ListNode {
  /**
   * Discriminator for lists.
   */
  type: "list";
  /**
   * True for ordered lists, false for unordered. Defaults to false if omitted.
   */
  ordered?: boolean;
  /**
   * Start index for ordered lists (defaults to 1).
   */
  startIndex?: number;
  /**
   * Items in this list.
   *
   * @minItems 1
   */
  content: [ListItemNode, ...ListItemNode[]];
  anchor: Anchor;
  refs?: RefsArray;
  backRefs?: BackRefsArray;
  artifact?: ArtifactFlag;
}
/**
 * Single list item: contains either inline text (simple items) or block children (items with nested structure).
 */
export interface ListItemNode {
  /**
   * Block type discriminator for list items.
   */
  type: "listitem";
  /**
   * Either inline text (TextNode[]) for simple items, or block children (ContentBlockNode[]) for items with nested structure.
   */
  content: [TextNode, ...TextNode[]] | [ContentBlockNode, ...ContentBlockNode[]];
  anchor: Anchor;
  /**
   * True if this block is a reference entry (e.g. bibliography item).
   */
  reference?: boolean;
  refs?: RefsArray;
  backRefs?: BackRefsArray;
  artifact?: ArtifactFlag;
}
/**
 * Top-level table block.
 */
export interface TableNode {
  /**
   * Block type discriminator for tables.
   */
  type: "table";
  /**
   * Either inline text (TextNode[]) for simple/flat tables, or structured rows (TableRowNode[]) for fully parsed tables.
   */
  content: [TextNode, ...TextNode[]] | [TableRowNode, ...TableRowNode[]];
  anchor: Anchor;
  refs?: RefsArray;
  backRefs?: BackRefsArray;
  artifact?: ArtifactFlag;
}
/**
 * Single table row.
 */
export interface TableRowNode {
  /**
   * Block type discriminator for table rows.
   */
  type: "tablerow";
  /**
   * Cells in this row. No raw text directly under a row.
   *
   * @minItems 1
   */
  content: [TableCellNode, ...TableCellNode[]];
  anchor: Anchor;
  refs?: RefsArray;
  backRefs?: BackRefsArray;
  artifact?: ArtifactFlag;
}
/**
 * Table cell container (header or data cell).
 */
export interface TableCellNode {
  /**
   * Block type discriminator for table cells.
   */
  type: "tablecell";
  /**
   * If true, this is a header cell (<th>); otherwise a data cell (<td>).
   */
  header?: boolean;
  /**
   * Axis for header cells: 'row' or 'column'.
   */
  axis?: "row" | "column";
  /**
   * Horizontal span of this cell. Default is 1 if omitted.
   */
  colspan?: number;
  /**
   * Vertical span of this cell. Default is 1 if omitted.
   */
  rowspan?: number;
  /**
   * Block content of the cell (paragraphs, lists, nested tables, etc.). Inline text must live inside those blocks.
   */
  content: ContentBlockNode[];
  anchor: Anchor;
  refs?: RefsArray;
  backRefs?: BackRefsArray;
  artifact?: ArtifactFlag;
}
/**
 * Shared caption block (for tables, figures, images, groups, etc.).
 */
export interface CaptionNode {
  /**
   * Block type discriminator for captions.
   */
  type: "caption";
  /**
   * Inline content of the caption.
   */
  content: TextNode[];
  anchor: Anchor;
  refs?: RefsArray;
  backRefs?: BackRefsArray;
  artifact?: ArtifactFlag;
}
/**
 * Note block used across the document (including table-local notes).
 */
export interface NoteNode {
  /**
   * Block type discriminator for notes.
   */
  type: "note";
  /**
   * Inline content of the note body.
   */
  content: TextNode[];
  anchor: Anchor;
  refs?: RefsArray;
  backRefs?: BackRefsArray;
  /**
   * True if this block is a reference entry (e.g. bibliography item).
   */
  reference?: boolean;
  artifact?: ArtifactFlag;
}
/**
 * Preformatted block with whitespace-significant text.
 */
export interface PreformattedNode {
  /**
   * Discriminator for preformatted blocks.
   */
  type: "preformatted";
  /**
   * Inline content of the preformatted block.
   */
  content: TextNode[];
  anchor: Anchor;
  refs?: RefsArray;
  backRefs?: BackRefsArray;
  artifact?: ArtifactFlag;
}