Document source model

1// Viewer-agnostic model for "sources" — the provenance of an extracted value:
2// where in a source document a field came from. Mirrors the Retab
3// `GET /v1/extractions/{id}/sources` response (`GetSourcesResponse`): a value
4// tree plus a parallel `sources` tree whose leaves locate each value with a
5// format-specific anchor.
6//
7// This module has no viewer/React imports so every viewer (PDF today; image,
8// xlsx, csv, docx, text later) shares one source model. Each viewer's adapter
9// turns an `anchor` into something it can render (see e.g. the PDF adapter).
10 
11// ── Anchors — discriminated union on `kind`, one per document format ──────────
12 
13/** A region on one PDF page, normalized to the page box (each value in [0, 1]). */
14export interface PdfBboxAnchor {
15  kind: "pdf_bbox";
16  /** 1-based page number. */
17  page: number;
18  left: number;
19  top: number;
20  width: number;
21  height: number;
22}
23 
24/** A region on an image, normalized to the image box (each value in [0, 1]). */
25export interface ImageBboxAnchor {
26  kind: "image_bbox";
27  /**
28   * 1-based frame index for multi-page rasters — a multi-frame TIFF page, or a
29   * rasterized slide in a deck. Omitted (or 1) for a single-frame image.
30   */
31  page?: number;
32  left: number;
33  top: number;
34  width: number;
35  height: number;
36}
37 
38/** A cell in a CSV. */
39export interface CsvCellAnchor {
40  kind: "csv_cell";
41  /** 1-based row number. */
42  row: number;
43  /** Column letter (A, B, … AA). */
44  column: string;
45  /** Cell coordinate (e.g. A12). */
46  coordinate?: string;
47}
48 
49/** A cell in a spreadsheet (xlsx), on a given sheet. */
50export interface SpreadsheetCellAnchor {
51  kind: "spreadsheet_cell";
52  /** 1-based row number. */
53  row: number;
54  /** Column letter (A, B, … AA). */
55  column: string;
56  coordinate?: string;
57  /** 0-based sheet index. */
58  sheet_index: number;
59  sheet_name?: string;
60}
61 
62/** A character span within a docx paragraph. */
63export interface DocxTextSpanAnchor {
64  kind: "docx_text_span";
65  /** 0-based paragraph index. */
66  paragraph: number;
67  char_start?: number;
68  char_end?: number;
69  /** Raw OOXML of the matched paragraph. */
70  xml?: string;
71}
72 
73/** A character span within a docx table cell. */
74export interface DocxTableCellAnchor {
75  kind: "docx_table_cell";
76  /** 0-based table index. */
77  table: number;
78  /** 0-based row index. */
79  row: number;
80  /** 0-based column index. */
81  column: number;
82  char_start?: number;
83  char_end?: number;
84  xml?: string;
85}
86 
87// … truncated