@sachfolio/cas-reader 0.0.0-stage → 0.2.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/LICENSE +71 -0
  3. package/NOTICE +41 -0
  4. package/README.md +198 -2
  5. package/dist/analytics/contract.d.ts +110 -0
  6. package/dist/analytics/contract.js +79 -0
  7. package/dist/analytics/eligibility.d.ts +66 -0
  8. package/dist/analytics/eligibility.js +93 -0
  9. package/dist/analytics/gains-schema.d.ts +898 -0
  10. package/dist/analytics/gains-schema.js +170 -0
  11. package/dist/analytics/gains.d.ts +319 -0
  12. package/dist/analytics/gains.js +649 -0
  13. package/dist/analytics/modules.d.ts +33 -0
  14. package/dist/analytics/modules.js +74 -0
  15. package/dist/analytics/returns-schema.d.ts +931 -0
  16. package/dist/analytics/returns-schema.js +152 -0
  17. package/dist/analytics/returns.d.ts +126 -0
  18. package/dist/analytics/returns.js +453 -0
  19. package/dist/analytics/schedule112a.d.ts +77 -0
  20. package/dist/analytics/schedule112a.js +134 -0
  21. package/dist/analytics/xirr.d.ts +75 -0
  22. package/dist/analytics/xirr.js +314 -0
  23. package/dist/bin/cas.d.ts +2 -0
  24. package/dist/bin/cas.js +137 -0
  25. package/dist/checks.d.ts +49 -0
  26. package/dist/checks.js +227 -0
  27. package/dist/compat/casparser.d.ts +121 -0
  28. package/dist/compat/casparser.js +193 -0
  29. package/dist/detect.d.ts +10 -0
  30. package/dist/detect.js +69 -0
  31. package/dist/errors.d.ts +26 -0
  32. package/dist/errors.js +95 -0
  33. package/dist/export/csv.d.ts +21 -0
  34. package/dist/export/csv.js +49 -0
  35. package/dist/extract/browser.d.ts +17 -0
  36. package/dist/extract/browser.js +34 -0
  37. package/dist/extract/budget.d.ts +46 -0
  38. package/dist/extract/budget.js +88 -0
  39. package/dist/extract/node.d.ts +11 -0
  40. package/dist/extract/node.js +31 -0
  41. package/dist/extract/pdfjs.d.ts +71 -0
  42. package/dist/extract/pdfjs.js +244 -0
  43. package/dist/extract/types.d.ts +106 -0
  44. package/dist/extract/types.js +11 -0
  45. package/dist/index.d.ts +27 -0
  46. package/dist/index.js +26 -0
  47. package/dist/layout/lines.d.ts +51 -0
  48. package/dist/layout/lines.js +115 -0
  49. package/dist/licence/app-licence.d.ts +53 -0
  50. package/dist/licence/app-licence.js +139 -0
  51. package/dist/licence/ed25519.d.ts +2 -0
  52. package/dist/licence/ed25519.js +103 -0
  53. package/dist/model.d.ts +148 -0
  54. package/dist/model.js +1 -0
  55. package/dist/num.d.ts +19 -0
  56. package/dist/num.js +27 -0
  57. package/dist/parse.d.ts +4 -0
  58. package/dist/parse.js +13 -0
  59. package/dist/parsers/cams/classify.d.ts +25 -0
  60. package/dist/parsers/cams/classify.js +103 -0
  61. package/dist/parsers/cams/detailed.d.ts +15 -0
  62. package/dist/parsers/cams/detailed.js +343 -0
  63. package/dist/parsers/cams/header.d.ts +47 -0
  64. package/dist/parsers/cams/header.js +170 -0
  65. package/dist/parsers/cams/investor.d.ts +28 -0
  66. package/dist/parsers/cams/investor.js +139 -0
  67. package/dist/parsers/cams/summary.d.ts +29 -0
  68. package/dist/parsers/cams/summary.js +413 -0
  69. package/dist/parsers/cams/table.d.ts +55 -0
  70. package/dist/parsers/cams/table.js +144 -0
  71. package/dist/parsers/cams/total.d.ts +17 -0
  72. package/dist/parsers/cams/total.js +105 -0
  73. package/dist/parsers/depository/mf.d.ts +22 -0
  74. package/dist/parsers/depository/mf.js +438 -0
  75. package/dist/privacy.d.ts +243 -0
  76. package/dist/privacy.js +256 -0
  77. package/dist/schema.d.ts +779 -0
  78. package/dist/schema.js +214 -0
  79. package/examples/nextjs/app/page.jsx +34 -0
  80. package/examples/node/server.mjs +45 -0
  81. package/examples/python/read_cas.py +67 -0
  82. package/examples/vite/index.html +14 -0
  83. package/examples/vite/main.js +22 -0
  84. package/package.json +54 -4
@@ -0,0 +1,139 @@
1
+ import { cleanPage, clusterLines, LINE_Y_TOL } from "../../layout/lines.js";
2
+ // casparser's top-left column cutoff: everything right of it is the
3
+ // disclaimer paragraph, which shares baselines with the addressee block.
4
+ const LEFT_COLUMN_X = 200;
5
+ // Items closer than this are one word split by the extractor. A real space is
6
+ // ~0.25 em in the fonts these statements use.
7
+ const GLUE_GAP_EM = 0.1;
8
+ // A left-column run may continue past the cutoff only across a word space;
9
+ // the disclaimer column sits much farther away.
10
+ const CHAIN_GAP_EM = 0.4;
11
+ // Without a `Mobile:` close, the block ends at a baseline step wider than one blank line.
12
+ const BLOCK_GAP_EM = 2.5;
13
+ // Name + address + phone lines. More than this and we are not in the block.
14
+ const MAX_BLOCK_LINES = 12;
15
+ const MAX_NAME_LENGTH = 100;
16
+ const EMAIL_LABEL_RE = /^E-?mail\s*Id\s*:\s*/i;
17
+ const MOBILE_LABEL_RE = /(?:^|\s)Mobile\s*:\s*/i;
18
+ // casparser drops `Phone Off:`; `Phone Res:` / `Tel:` are the same kind of line.
19
+ const PHONE_RE = /^(?:Phone|Tel(?:ephone)?)\b[^:]{0,12}:/i;
20
+ const EMAIL_RE = /^[A-Za-z0-9._%+'-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}$/;
21
+ // Ends like a whole address even if EMAIL_RE rejects it (e.g. masked). Anything
22
+ // else may have wrapped onto the next line.
23
+ const EMAIL_COMPLETE_RE = /@[^@\s]+\.[A-Za-z]{2,}$/;
24
+ const MOBILE_RE = /^\+?\d{8,15}$/;
25
+ const NAME_RE = /^\p{L}[\p{L} .'&-]*$/u;
26
+ // Statement-body lines that never belong to a postal address.
27
+ const NOT_ADDRESS_RE = /Consolidated\s+Account|Portfolio\s+Summary|Folio\s+No|Mutual\s+Fund|Unit\s+Balance|\bISIN\b|Registrar\s*:|\bPAN\s*:|\bKYC\s*:|\d{1,2}-[A-Za-z]{3}-\d{4}|^Date\s+Transaction|E-?mail\s*Id\s*:/i;
28
+ export function extractAddressee(doc) {
29
+ const page = doc.pages[0];
30
+ const lines = page ? leftColumnLines(page) : [];
31
+ const start = lines.findIndex((l) => EMAIL_LABEL_RE.test(l.text));
32
+ if (start < 0)
33
+ return { name: null, email: null, mobile: null, address: null };
34
+ const emailText = lines[start].text.replace(EMAIL_LABEL_RE, "");
35
+ const email = EMAIL_RE.test(emailText) ? emailText : null;
36
+ // A value cut short of "@domain.tld" may continue on the next line, so that
37
+ // line can't be taken as the name.
38
+ const wrapped = emailText !== "" && !EMAIL_COMPLETE_RE.test(emailText);
39
+ const { body, mobileText, ended } = readBlock(lines, start);
40
+ const kept = body.filter((t) => !PHONE_RE.test(t));
41
+ const first = kept[0];
42
+ const name = !wrapped && first !== undefined && first.length <= MAX_NAME_LENGTH && NAME_RE.test(first) ? first : null;
43
+ // The address is only as trustworthy as the name line above it and the end below it.
44
+ const rest = kept.slice(1);
45
+ const address = name !== null && ended && rest.length > 0 ? rest.join("\n") : null;
46
+ const mobileValue = mobileText?.replace(/[\s-]/g, "") ?? "";
47
+ const mobile = MOBILE_RE.test(mobileValue) ? mobileValue : null;
48
+ return { name, email, mobile, address };
49
+ }
50
+ /**
51
+ * The lines after `Email Id:` up to `Mobile:` (casparser's rule). Without that
52
+ * close, the lines up to the first wide gap or statement-body line. `ended` is
53
+ * false when neither came within MAX_BLOCK_LINES, i.e. the end is unknown.
54
+ */
55
+ function readBlock(lines, start) {
56
+ const body = [];
57
+ let hitLimit = false;
58
+ for (let i = start + 1; i < lines.length; i++) {
59
+ const line = lines[i];
60
+ const m = MOBILE_LABEL_RE.exec(line.text);
61
+ if (m) {
62
+ // A mid-line label keeps the text before it as the last address line.
63
+ const before = line.text.slice(0, m.index).trim();
64
+ const texts = body.map((l) => l.text);
65
+ if (before)
66
+ texts.push(before);
67
+ return { body: texts, mobileText: line.text.slice(m.index + m[0].length), ended: true };
68
+ }
69
+ if (NOT_ADDRESS_RE.test(line.text))
70
+ break;
71
+ if (body.length === MAX_BLOCK_LINES) {
72
+ hitLimit = true;
73
+ break;
74
+ }
75
+ body.push(line);
76
+ }
77
+ let prev = lines[start];
78
+ let n = 0;
79
+ for (; n < body.length; n++) {
80
+ const line = body[n];
81
+ if (line.y - prev.y > BLOCK_GAP_EM * Math.max(line.em, prev.em))
82
+ break;
83
+ prev = line;
84
+ }
85
+ return { body: body.slice(0, n).map((l) => l.text), mobileText: null, ended: n < body.length || !hitLimit };
86
+ }
87
+ /**
88
+ * Page lines built from the top-left column only. Filtering items before
89
+ * clustering keeps the right-column disclaimer out of both the text and the
90
+ * line baselines.
91
+ */
92
+ function leftColumnLines(page) {
93
+ // The statement walk's cleanup (whitespace, watermark, overlay twins), then
94
+ // repeats: casparser `pageobj.py` drops text drawn twice at one spot. Matching
95
+ // by overlap also catches fake bold (a copy a fraction of a point to the
96
+ // side), which would otherwise double the name.
97
+ const kept = new Map();
98
+ const items = cleanPage(page)
99
+ .lines.flatMap((l) => l.items)
100
+ .filter((i) => {
101
+ const same = kept.get(i.str.trim()) ?? [];
102
+ if (same.some((k) => isRepeat(k, i)))
103
+ return false;
104
+ kept.set(i.str.trim(), [...same, i]);
105
+ return true;
106
+ });
107
+ const beyond = items.filter((i) => i.x0 >= LEFT_COLUMN_X).sort((a, b) => a.x0 - b.x0);
108
+ return clusterLines(items.filter((i) => i.x0 < LEFT_COLUMN_X), page.number).map((line) => {
109
+ const run = [...line.items];
110
+ let edge = Math.max(...run.map((i) => i.x1));
111
+ for (const it of beyond) {
112
+ const gap = it.x0 - edge;
113
+ const size = Math.max(it.fontSize, run[run.length - 1].fontSize, 1);
114
+ if (Math.abs(it.y - line.y) > LINE_Y_TOL || gap < -GLUE_GAP_EM * size || gap > CHAIN_GAP_EM * size)
115
+ continue;
116
+ run.push(it);
117
+ edge = Math.max(edge, it.x1);
118
+ }
119
+ return { y: line.y, em: Math.max(...run.map((i) => i.fontSize)), text: joinRun(run) };
120
+ });
121
+ }
122
+ /** Same text on the same baseline, overlapping by at least half the narrower item. */
123
+ function isRepeat(a, b) {
124
+ if (Math.abs(a.y - b.y) > LINE_Y_TOL)
125
+ return false;
126
+ const overlap = Math.min(a.x1, b.x1) - Math.max(a.x0, b.x0);
127
+ return overlap > 0 && overlap >= 0.5 * Math.min(a.x1 - a.x0, b.x1 - b.x0);
128
+ }
129
+ /** Touching items are one word split by the extractor; separated ones get a space. */
130
+ function joinRun(items) {
131
+ let text = "";
132
+ let edge = -Infinity;
133
+ for (const it of items) {
134
+ const size = Math.max(it.fontSize, 1);
135
+ text += (text === "" || it.x0 - edge <= GLUE_GAP_EM * size ? "" : " ") + it.str;
136
+ edge = Math.max(edge, it.x1);
137
+ }
138
+ return text.replace(/\s+/g, " ").trim();
139
+ }
@@ -0,0 +1,29 @@
1
+ import type { Detection } from "../../detect.js";
2
+ import type { ExtractedDocument, RawItem } from "../../extract/types.js";
3
+ import { type Line } from "../../layout/lines.js";
4
+ import type { CasDocument } from "../../model.js";
5
+ export type SummaryLabel = "Folio" | "ISIN" | "Scheme" | "Cost" | "Balance" | "NAVDate" | "NAV" | "MarketValue" | "Registrar";
6
+ export interface SummaryColumn {
7
+ label: SummaryLabel;
8
+ x0: number;
9
+ x1: number;
10
+ align: "left" | "right";
11
+ }
12
+ export interface SummaryRow {
13
+ cells: Partial<Record<SummaryLabel, string>>;
14
+ /** Items that fell in no column. */
15
+ unassigned: RawItem[];
16
+ }
17
+ /**
18
+ * casparser `detect_summary_columns`: a ≤15pt window of lines with ≥5
19
+ * distinct header words, including "Folio" and "Scheme". Only header-like
20
+ * lines join the window, so a row printed close under the header isn't
21
+ * swallowed and a note above it isn't mistaken for it.
22
+ */
23
+ export declare function detectSummaryHeader(lines: Line[]): {
24
+ first: number;
25
+ last: number;
26
+ columns: SummaryColumn[];
27
+ } | null;
28
+ export declare function assignSummaryCells(line: Line, columns: SummaryColumn[]): SummaryRow;
29
+ export declare function parseSummary(doc: ExtractedDocument, detection: Detection): CasDocument;
@@ -0,0 +1,413 @@
1
+ /**
2
+ * CAMS / KFintech SUMMARY parser: holdings only, no transactions (PLAN.md
3
+ * §5.3). Ported from casparser `cams_summary.py` (MIT). The statement is one
4
+ * table with a row per scheme:
5
+ *
6
+ * Folio No. | ISIN | Scheme Name | Cost Value | Unit Balance | NAV Date | NAV | Market Value | Registrar
7
+ *
8
+ * KFin prints the same fields as "Closing Unit Balance" and "Price", with the
9
+ * header spread over 2-3 baselines. Long scheme names wrap onto lines below
10
+ * the row that carry text in the Scheme column only. AMC name lines separate
11
+ * groups of folios, and a "Total" row ends the table.
12
+ *
13
+ * Differences from casparser:
14
+ * - cells are assigned per pdf.js item as in table.ts (numbers by right edge,
15
+ * text by left edge); casparser assigns single glyphs by their midpoint;
16
+ * - the header window takes only header-like lines, and only label words
17
+ * are clustered into columns, so a nearby title or note can't glue two
18
+ * columns together or stand in for the header;
19
+ * - unprinted values stay null (casparser writes 0), and no ISIN/AMFI lookup
20
+ * is done;
21
+ * - a wrapped-name fragment must sit on the line directly below its row;
22
+ * - rows that look like holdings but can't be read are recorded in coverage.
23
+ */
24
+ import { isinCheck, portfolioTotalCheck, productBound } from "../../checks.js";
25
+ import { CasError } from "../../errors.js";
26
+ import { cleanPage, lineText, rotatedTextChars } from "../../layout/lines.js";
27
+ import { big, parseNum } from "../../num.js";
28
+ import { cleanSchemeName } from "./classify.js";
29
+ import { ENGINE_VERSION, isoDate } from "./detailed.js";
30
+ import { optionOf, planOf, RTA_TOKEN_RE } from "./header.js";
31
+ import { extractAddressee } from "./investor.js";
32
+ import { isNumeric } from "./table.js";
33
+ import { GRAND_TOTAL_RE, pickTotal } from "./total.js";
34
+ // Header geometry, from casparser `cams_summary.py` (MIT).
35
+ const SUMMARY_HEADER_LABELS = new Set(["Folio", "No", "No.", "ISIN", "Scheme", "Name", "Cost", "Value", "Unit", "Balance", "Closing", "NAV", "Date", "Price", "Market", "Registrar"]);
36
+ const SUMMARY_MIN_HITS = 5;
37
+ const HEADER_WINDOW_Y = 15;
38
+ // KFin header columns sit as close as ~9pt apart (Market → Registrar).
39
+ const XCLUSTER_GAP = 7;
40
+ // Widest expected numeric value; also how far left of its label's right edge a value may end.
41
+ const NUMERIC_WIDTH = 42;
42
+ // casparser lets glyph midpoints reach x_hi + 3; an item's right edge sits about half a glyph further.
43
+ const RIGHT_SLACK = 4;
44
+ // Not in casparser, which accepts a Scheme-only line anywhere below the row.
45
+ // A wrapped line sits one line height (~9-10pt at the template's font) below.
46
+ const CONTINUATION_MAX_GAP = 12;
47
+ // casparser COLUMN_RULES: the first rule whose required words are all in one
48
+ // x-cluster wins. Word order inside a cluster doesn't matter, because KFin
49
+ // stacks "Closing Unit" above "Balance".
50
+ const COLUMN_RULES = [
51
+ { required: ["Folio"], label: "Folio", align: "left" },
52
+ { required: ["ISIN"], label: "ISIN", align: "left" },
53
+ { required: ["Scheme"], label: "Scheme", align: "left" },
54
+ { required: ["Cost"], label: "Cost", align: "right" },
55
+ { required: ["Closing", "Balance"], label: "Balance", align: "right" },
56
+ { required: ["Unit", "Balance"], label: "Balance", align: "right" },
57
+ { required: ["NAV", "Date"], label: "NAVDate", align: "left" },
58
+ { required: ["NAV"], label: "NAV", align: "right" },
59
+ { required: ["Price"], label: "NAV", align: "right" },
60
+ { required: ["Market"], label: "MarketValue", align: "right" },
61
+ { required: ["Registrar"], label: "Registrar", align: "left" },
62
+ ];
63
+ const CELL_NAMES = {
64
+ Folio: "Folio", ISIN: "ISIN", Scheme: "Scheme", Cost: "Cost Value", Balance: "Unit Balance",
65
+ NAVDate: "NAV Date", NAV: "NAV", MarketValue: "Market Value", Registrar: "Registrar",
66
+ };
67
+ // Row patterns, from casparser `cams_summary.py` (MIT). A folio has ≥6 digits
68
+ // so stray small numbers in disclaimers don't qualify.
69
+ const FOLIO_CELL_RE = /^\s*(\d{6,}(?:\s*\/\s*\d+)?)/;
70
+ const ISIN_CELL_RE = /(INF[A-Z0-9]{8}\d)/;
71
+ const SUMMARY_DATE_RE = /as\s+on\s+(\d{2}-[A-Za-z]{3}-\d{4})/i;
72
+ const SCHEME_CELL_RE = /^\s*([\w\s]{2,15}?)\s*-\s*(.+)$/;
73
+ const SCHEME_LOOKS_LIKE_DATA = /^\s*[A-Z0-9][\w\s]{1,15}\s*-\s*\S/;
74
+ const SUMMARY_TOTAL_RE = /^\s*(?:grand\s+|sub\s+|portfolio\s+)?total\b/i;
75
+ // casparser `cams_detailed.py` AMC_RE (MIT); the ":" guard is detailed.ts's.
76
+ const AMC_RE = /^(.+?\s+(?:MF|Mutual\s*Fund|Fund\s*House))$/i;
77
+ // "-", "--", "NA": printed in place of a value that doesn't exist.
78
+ const PLACEHOLDER_RE = /^(?:-+|N\.?A\.?)$/i;
79
+ // Only if a template prints them inside the scheme cell, as the detailed CAS does.
80
+ const INLINE_ADVISOR_RE = /[-\s]*\(\s*Advisor\s*:\s*([^)]+?)\)/i;
81
+ const INLINE_ADVISOR_RE_G = new RegExp(INLINE_ADVISOR_RE.source, "gi");
82
+ const ADVISOR_CODE_RE = /\b(ARN-?\d+|INA\d+)\b/i;
83
+ const INLINE_ISIN_RE = /[-\s]*ISIN\s*:\s*(INF[A-Z0-9]{8}\d)/i;
84
+ const INLINE_ISIN_RE_G = new RegExp(INLINE_ISIN_RE.source, "gi");
85
+ const HISTORY_UNAVAILABLE = "Summary statements list holdings only, with no transactions, so purchase history can't be checked. Returns and gains need a detailed statement from the first purchase.";
86
+ /**
87
+ * Words of an item, x estimated pro rata by character: pdf.js gives item edges
88
+ * only, and CAMS draws "Folio No." as one item with a real space.
89
+ */
90
+ function itemWords(item) {
91
+ const per = (item.x1 - item.x0) / Math.max(item.str.length, 1);
92
+ return [...item.str.matchAll(/\S+/g)].map((m) => {
93
+ const at = m.index ?? 0;
94
+ return { text: m[0], x0: item.x0 + at * per, x1: item.x0 + (at + m[0].length) * per };
95
+ });
96
+ }
97
+ const isAmcLine = (text) => AMC_RE.test(text) && !text.includes(":");
98
+ const hasLabel = (line) => line.items.some((i) => itemWords(i).some((w) => SUMMARY_HEADER_LABELS.has(w.text)));
99
+ // Unit annotations such as "(INR)" sit under their column label.
100
+ const isAnnotation = (w) => /^\(.*\)$/.test(w);
101
+ /**
102
+ * Header text is mostly label words and carries no numbers or dates. A data
103
+ * row, an AMC line or prose (a note naming the columns) ends the window; in
104
+ * casparser any line within 15pt joins it.
105
+ */
106
+ function headerish(line) {
107
+ if (line.items.some((i) => isNumeric(i.str) || isoDate(i.str) !== null) || isAmcLine(lineText(line).trim()))
108
+ return false;
109
+ const words = line.items.flatMap(itemWords);
110
+ return words.filter((w) => SUMMARY_HEADER_LABELS.has(w.text) || isAnnotation(w.text)).length * 2 >= words.length;
111
+ }
112
+ /**
113
+ * casparser `detect_summary_columns`: a ≤15pt window of lines with ≥5
114
+ * distinct header words, including "Folio" and "Scheme". Only header-like
115
+ * lines join the window, so a row printed close under the header isn't
116
+ * swallowed and a note above it isn't mistaken for it.
117
+ */
118
+ export function detectSummaryHeader(lines) {
119
+ for (let i = 0; i < lines.length; i++) {
120
+ const top = lines[i];
121
+ if (!hasLabel(top) || !headerish(top))
122
+ continue;
123
+ let last = i;
124
+ for (let j = i + 1; j < lines.length && lines[j].y - top.y <= HEADER_WINDOW_Y && headerish(lines[j]); j++)
125
+ last = j;
126
+ while (last > i && !hasLabel(lines[last]))
127
+ last--;
128
+ const words = lines.slice(i, last + 1).flatMap((l) => l.items.flatMap(itemWords));
129
+ const labels = new Set(words.map((w) => w.text).filter((t) => SUMMARY_HEADER_LABELS.has(t)));
130
+ if (labels.size >= SUMMARY_MIN_HITS && labels.has("Folio") && labels.has("Scheme")) {
131
+ // Other words (a title, a stray note) would bridge clusters.
132
+ const columns = buildColumns(words.filter((w) => SUMMARY_HEADER_LABELS.has(w.text) || isAnnotation(w.text)));
133
+ // Not in casparser: a header that yields no holding columns isn't the holdings table's.
134
+ const has = (l) => columns.some((c) => c.label === l);
135
+ if (has("Folio") && has("Scheme") && (has("Balance") || has("MarketValue")))
136
+ return { first: i, last, columns };
137
+ }
138
+ }
139
+ return null;
140
+ }
141
+ /** casparser `_build_summary_columns`: cluster words by x across all header baselines, then name each cluster. */
142
+ function buildColumns(words) {
143
+ const clusters = [];
144
+ let maxX1 = -Infinity;
145
+ for (const w of [...words].sort((a, b) => a.x0 - b.x0)) {
146
+ const cur = clusters[clusters.length - 1];
147
+ if (cur && w.x0 - maxX1 <= XCLUSTER_GAP) {
148
+ cur.push(w);
149
+ maxX1 = Math.max(maxX1, w.x1);
150
+ }
151
+ else {
152
+ clusters.push([w]);
153
+ maxX1 = w.x1;
154
+ }
155
+ }
156
+ const cols = [];
157
+ for (const cluster of clusters) {
158
+ const tokens = new Set(cluster.map((w) => w.text));
159
+ const rule = COLUMN_RULES.find((r) => r.required.every((t) => tokens.has(t)) && !cols.some((c) => c.label === r.label));
160
+ if (rule) {
161
+ cols.push({ label: rule.label, x0: Math.min(...cluster.map((w) => w.x0)), x1: Math.max(...cluster.map((w) => w.x1)), align: rule.align });
162
+ }
163
+ }
164
+ return cols.sort((a, b) => a.x0 - b.x0);
165
+ }
166
+ /**
167
+ * casparser `_summary_column_ranges`: a right-aligned numeric column owns
168
+ * [x_hi − 42, x_hi + slack]; a left-aligned column owns from its left edge
169
+ * (−3pt) to where the next column's zone starts.
170
+ */
171
+ function zones(columns) {
172
+ const sorted = [...columns].sort((a, b) => a.x0 + a.x1 - (b.x0 + b.x1));
173
+ return sorted.map((col, k) => {
174
+ if (col.align === "right")
175
+ return { col, lo: col.x1 - NUMERIC_WIDTH, hi: col.x1 + RIGHT_SLACK };
176
+ const next = sorted[k + 1];
177
+ const hi = !next ? Infinity : next.align === "right" ? next.x1 - NUMERIC_WIDTH : next.x0 - 3;
178
+ return { col, lo: col.x0 - 3, hi };
179
+ });
180
+ }
181
+ export function assignSummaryCells(line, columns) {
182
+ const all = zones(columns);
183
+ const right = all.filter((z) => z.col.align === "right");
184
+ const left = all.filter((z) => z.col.align === "left");
185
+ const leftAt = (x) => left.find((z) => x >= z.lo && x < z.hi)?.col;
186
+ const row = { cells: {}, unassigned: [] };
187
+ const put = (label, text) => {
188
+ const prev = row.cells[label];
189
+ row.cells[label] = prev ? `${prev} ${text}` : text;
190
+ };
191
+ for (const item of line.items) {
192
+ const text = item.str.trim();
193
+ if (isNumeric(text) || PLACEHOLDER_RE.test(text)) {
194
+ // Adjacent numeric zones can overlap; the nearest right edge wins.
195
+ const col = right
196
+ .filter((z) => item.x1 >= z.lo && item.x1 <= z.hi)
197
+ .sort((a, b) => Math.abs(a.col.x1 - item.x1) - Math.abs(b.col.x1 - item.x1))[0]?.col;
198
+ if (col) {
199
+ put(col.label, text);
200
+ continue;
201
+ }
202
+ }
203
+ // Text, and numbers outside the numeric columns (an all-digit folio). A
204
+ // date centred under "NAV Date" can start left of the label, hence the
205
+ // midpoint fallback.
206
+ const col = leftAt(item.x0) ?? leftAt((item.x0 + item.x1) / 2);
207
+ if (col)
208
+ put(col.label, text);
209
+ else
210
+ row.unassigned.push(item);
211
+ }
212
+ return row;
213
+ }
214
+ function rtaOf(cell) {
215
+ const tok = RTA_TOKEN_RE.exec(cell);
216
+ return tok ? tok[1].toUpperCase() : cell.trim() || "UNKNOWN";
217
+ }
218
+ /** Name, advisor and plan once every wrapped fragment is in. */
219
+ function finishName(s, parts) {
220
+ let text = parts.join(" ");
221
+ const adv = INLINE_ADVISOR_RE.exec(text)?.[1]?.trim();
222
+ if (adv)
223
+ s.advisor = ADVISOR_CODE_RE.exec(adv)?.[1] ?? adv;
224
+ text = text.replace(INLINE_ADVISOR_RE_G, " ");
225
+ const isin = INLINE_ISIN_RE.exec(text)?.[1];
226
+ if (isin && !s.isin)
227
+ s.isin = isin;
228
+ text = text.replace(INLINE_ISIN_RE_G, " ");
229
+ s.name = cleanSchemeName(text);
230
+ s.plan = planOf(s.name);
231
+ s.option = optionOf(s.name);
232
+ }
233
+ /** Same identity and precision bound as checks.ts. NAV and value share the row's one NAV date. */
234
+ function valuationCheck(s) {
235
+ if (!s.close || !s.nav || !s.valuation)
236
+ return { id: "valuation.units_x_nav", status: "unavailable", detail: "Closing units, NAV or value not found" };
237
+ const product = big(s.close).times(big(s.nav.value));
238
+ const bound = productBound(s.close, s.nav.value, s.valuation.value);
239
+ const ok = product.minus(big(s.valuation.value)).abs().lte(bound);
240
+ return {
241
+ id: "valuation.units_x_nav", status: ok ? "pass" : "fail",
242
+ expected: s.valuation.value.value, observed: product.toFixed(2), tolerance: bound.toFixed(4), source: s.footerSource ?? s.source,
243
+ };
244
+ }
245
+ export function parseSummary(doc, detection) {
246
+ // casparser drops overlay twins on every CAMS/KFin page; FolioLens scopes the any-text rule to KFin, as in detailed.ts.
247
+ const overlayTwins = detection.issuer === "KFINTECH" ? "any-text" : "same-text";
248
+ const cleaned = doc.pages.map((p) => cleanPage(p, { overlayTwins }));
249
+ const pages = cleaned.map((c) => ({ number: c.number, lines: c.lines }));
250
+ // A summary has no transaction rows, so the dated-row counters stay 0.
251
+ const coverage = { pages: doc.pages.length, datedRowsSeen: 0, transactionsParsed: 0, datedRowsSkipped: [], ambiguousCells: [], schemeRegionsUnbuilt: [] };
252
+ const warnings = [];
253
+ // As in detailed.ts: rotated text other than the watermark is lost to the layout.
254
+ for (const c of cleaned) {
255
+ const rotated = rotatedTextChars(c);
256
+ if (rotated)
257
+ warnings.push(`Page ${c.number}: ${rotated} characters of rotated text were set aside; anything printed there is missing.`);
258
+ }
259
+ // The summary's one date. Read first so a row printed above it can still fall back to it.
260
+ let asOn = null;
261
+ for (const p of pages)
262
+ for (const l of p.lines)
263
+ asOn ??= isoDate(SUMMARY_DATE_RE.exec(lineText(l))?.[1] ?? "");
264
+ const folios = new Map();
265
+ const nameParts = new Map();
266
+ let amc = null;
267
+ let current = null;
268
+ let columns = [];
269
+ let sawHeader = false;
270
+ let undated = 0;
271
+ const totals = [];
272
+ for (const page of pages) {
273
+ const header = detectSummaryHeader(page.lines);
274
+ if (header) {
275
+ columns = header.columns;
276
+ sawHeader = true;
277
+ }
278
+ // Pages without a header reuse the last one's columns, from their first line.
279
+ const headerLast = header ? header.last : -1;
280
+ let contIdx = -2;
281
+ let contY = 0;
282
+ for (let i = 0; i < page.lines.length; i++) {
283
+ const line = page.lines[i];
284
+ const text = lineText(line).trim();
285
+ const src = { page: page.number, y: line.y };
286
+ if (isAmcLine(text)) {
287
+ amc = AMC_RE.exec(text)[1].trim();
288
+ current = null;
289
+ continue;
290
+ }
291
+ if (!columns.length || i <= headerLast)
292
+ continue;
293
+ const row = assignSummaryCells(line, columns);
294
+ const cell = (l) => (row.cells[l] ?? "").trim();
295
+ const folioRaw = cell("Folio");
296
+ // Only a leading folio number counts; other text in the Folio zone is a disclaimer or a spill.
297
+ const folioNo = FOLIO_CELL_RE.exec(folioRaw)?.[1].replace(/\s+/g, " ").trim() ?? "";
298
+ // A long folio ("/0" suffix) can push the ISIN into the Folio cell.
299
+ const isin = (ISIN_CELL_RE.exec(cell("ISIN")) ?? ISIN_CELL_RE.exec(folioRaw))?.[1] ?? null;
300
+ const schemeCell = cell("Scheme");
301
+ const valueCells = ["Cost", "Balance", "NAVDate", "NAV", "MarketValue"].filter((l) => cell(l) !== "");
302
+ // The total row ends the table, so notes below it can't extend the last scheme's name.
303
+ if (!folioNo && (SUMMARY_TOTAL_RE.test(schemeCell) || SUMMARY_TOTAL_RE.test(text))) {
304
+ // The grand total is the statement's own portfolio total; a sub-total isn't.
305
+ const label = (GRAND_TOTAL_RE.exec(schemeCell) ?? GRAND_TOTAL_RE.exec(folioRaw) ?? GRAND_TOTAL_RE.exec(text))?.[1];
306
+ if (label) {
307
+ const printed = (l) => {
308
+ const c = cell(l);
309
+ return c && !PLACEHOLDER_RE.test(c) ? parseNum(c) : null;
310
+ };
311
+ totals.push({ label: label.replace(/\s+/g, " "), cost: printed("Cost"), marketValue: printed("MarketValue"), source: src });
312
+ }
313
+ current = null;
314
+ continue;
315
+ }
316
+ if (folioNo && SCHEME_LOOKS_LIKE_DATA.test(schemeCell)) {
317
+ const key = `${amc ?? "UNKNOWN"}|${folioNo}`;
318
+ let folio = folios.get(key);
319
+ if (!folio) {
320
+ folio = { folio: folioNo, amc: amc ?? "UNKNOWN", pan: null, kyc: null, panKyc: null, holderName: null, schemes: [] };
321
+ folios.set(key, folio);
322
+ }
323
+ const num = (l) => {
324
+ const c = cell(l);
325
+ if (!c || PLACEHOLDER_RE.test(c))
326
+ return null;
327
+ const n = parseNum(c);
328
+ if (!n)
329
+ coverage.ambiguousCells.push({ source: src, text: c, reason: `${CELL_NAMES[l]} cell is not a number` });
330
+ return n;
331
+ };
332
+ // casparser falls back to the statement date when the row prints no NAV date.
333
+ const navDateCell = cell("NAVDate");
334
+ let date = asOn;
335
+ if (navDateCell && !PLACEHOLDER_RE.test(navDateCell)) {
336
+ date = isoDate(navDateCell);
337
+ if (!date)
338
+ coverage.ambiguousCells.push({ source: src, text: navDateCell, reason: "NAV Date cell is not a date" });
339
+ }
340
+ for (const it of row.unassigned)
341
+ coverage.ambiguousCells.push({ source: src, text: it.str, reason: "item outside every summary column" });
342
+ const navValue = num("NAV");
343
+ const value = num("MarketValue");
344
+ if (!date && (navValue || value))
345
+ undated++;
346
+ const code = SCHEME_CELL_RE.exec(schemeCell);
347
+ const scheme = {
348
+ name: "", rtaCode: code ? code[1].trim() : "", rta: rtaOf(cell("Registrar")), isin, advisor: null,
349
+ plan: "UNKNOWN", option: "UNKNOWN", nominees: [],
350
+ open: null, close: num("Balance"), closeCalculated: null,
351
+ nav: navValue && date ? { date, value: navValue } : null,
352
+ valuation: value && date ? { date, value } : null,
353
+ cost: num("Cost"), transactions: [], checks: [], source: src, footerSource: src,
354
+ };
355
+ folio.schemes.push(scheme);
356
+ nameParts.set(scheme, [code ? code[2] : schemeCell]);
357
+ current = scheme;
358
+ contIdx = i;
359
+ contY = line.y;
360
+ continue;
361
+ }
362
+ // A wrapped name: Scheme text only (casparser ignores Folio-zone text that isn't a folio), right below the row.
363
+ if (current && !folioNo && schemeCell && valueCells.length === 0 && i === contIdx + 1 && line.y - contY <= CONTINUATION_MAX_GAP) {
364
+ nameParts.get(current).push(schemeCell);
365
+ current.isin ??= isin;
366
+ if (current.rta === "UNKNOWN" && cell("Registrar"))
367
+ current.rta = rtaOf(cell("Registrar"));
368
+ contIdx = i;
369
+ contY = line.y;
370
+ continue;
371
+ }
372
+ // Anything else carrying a folio number, a scheme code with values, or a
373
+ // units-and-value pair is a holding we failed to read. Reasons never
374
+ // quote the row: they reach the coverage report.
375
+ const holdingValues = parseNum(cell("Balance")) !== null && parseNum(cell("MarketValue")) !== null;
376
+ if (folioNo || (SCHEME_LOOKS_LIKE_DATA.test(schemeCell) && valueCells.length > 0) || holdingValues) {
377
+ coverage.schemeRegionsUnbuilt.push({
378
+ source: src,
379
+ reason: folioNo
380
+ ? "summary row has a folio number but no '<code>-<scheme name>' cell; the holding was skipped"
381
+ : "summary row has holding values but no folio number; the holding was skipped",
382
+ });
383
+ current = null;
384
+ }
385
+ }
386
+ }
387
+ if (!sawHeader) {
388
+ throw new CasError("UNKNOWN_TEMPLATE", `Found ${detection.issuer} summary markers but couldn't find the holdings table.`);
389
+ }
390
+ for (const [scheme, parts] of nameParts) {
391
+ finishName(scheme, parts);
392
+ scheme.checks = [valuationCheck(scheme), isinCheck(scheme), { id: "history.complete", status: "unavailable", detail: HISTORY_UNAVAILABLE }];
393
+ }
394
+ if (coverage.schemeRegionsUnbuilt.length)
395
+ warnings.push(`${coverage.schemeRegionsUnbuilt.length} summary row(s) could not be read; those holdings are missing.`);
396
+ if (undated)
397
+ warnings.push(`${undated} holding(s) have no readable NAV date and the statement date wasn't found; their NAV and value were not used.`);
398
+ const printedTotal = pickTotal(totals, coverage);
399
+ const allSchemes = [...folios.values()].flatMap((f) => f.schemes);
400
+ return {
401
+ schemaVersion: "1",
402
+ source: { issuer: detection.issuer, variant: detection.variant, engineVersion: ENGINE_VERSION },
403
+ provenance: { sha256: doc.meta.sha256, pageCount: doc.meta.pageCount, producer: doc.meta.producer, creator: doc.meta.creator, pdfVersion: doc.meta.pdfVersion, encrypted: doc.meta.encrypted, extractor: doc.meta.extractor },
404
+ // A summary is a snapshot; like casparser, the as-on date is both ends of the period.
405
+ statementPeriod: asOn ? { from: asOn, to: asOn } : null,
406
+ addressee: extractAddressee(doc),
407
+ folios: [...folios.values()],
408
+ printedTotal,
409
+ checks: [portfolioTotalCheck(printedTotal, allSchemes)],
410
+ coverage,
411
+ warnings,
412
+ };
413
+ }
@@ -0,0 +1,55 @@
1
+ /**
2
+ * CAMS/KFin transaction-table columns and cell assignment.
3
+ *
4
+ * Header detection follows casparser `cams_detailed.py` (MIT): a header is a
5
+ * ≤15pt window of lines carrying ≥4 column labels; "Unit" + "Balance" stacked
6
+ * vertically form one column. Numeric columns are right-aligned.
7
+ *
8
+ * Assignment differs from casparser because pdf.js gives items, not glyphs:
9
+ * 1. A numeric item is assigned to the right-aligned column whose right edge
10
+ * its own right edge snaps to (±SNAP_TOL).
11
+ * 2. A text item is assigned to the left-aligned column whose zone contains
12
+ * its left edge.
13
+ * 3. A text item that ends in a numeric token whose right edge snaps to a
14
+ * numeric column is split: the token goes to that column (the pdf.js
15
+ * merge case the reviews predicted).
16
+ * 4. Anything else is recorded as an ambiguity, never guessed.
17
+ * 5. Only Transaction text is joined when several items land in one cell.
18
+ * A Date or numeric cell that receives two different values is a
19
+ * conflict: both items are recorded and the cell is left empty. The one
20
+ * exception is a second date drawn off the row's baseline (the KFin ghost
21
+ * when the overlay rule couldn't pair it): the date on the baseline is
22
+ * kept and the other is recorded.
23
+ */
24
+ import type { RawItem } from "../../extract/types.js";
25
+ import type { Line } from "../../layout/lines.js";
26
+ export type ColumnLabel = "Date" | "Transaction" | "Amount" | "Units" | "Price" | "Unit Balance" | "NAV";
27
+ export interface Column {
28
+ label: ColumnLabel;
29
+ x0: number;
30
+ x1: number;
31
+ align: "left" | "right";
32
+ }
33
+ export interface Ambiguity {
34
+ item: RawItem;
35
+ reason: string;
36
+ }
37
+ export interface RowCells {
38
+ line: Line;
39
+ cells: Partial<Record<ColumnLabel, string>>;
40
+ /** How each cell was assigned, for the evidence trail. */
41
+ via: Partial<Record<ColumnLabel, "snap" | "zone" | "split">>;
42
+ ambiguities: Ambiguity[];
43
+ /** Date or numeric cells that received two different values; each is left empty and its items are in `ambiguities`. */
44
+ conflicts: ColumnLabel[];
45
+ }
46
+ /** Matches printed numbers: 1,23,456.78 · (1,234.56) · -12.5 · .25 */
47
+ export declare const NUMERIC_RE: RegExp;
48
+ export declare function isNumeric(s: string): boolean;
49
+ /** Finds the next transaction header at or after `start`. */
50
+ export declare function detectHeader(lines: Line[], start: number): {
51
+ first: number;
52
+ last: number;
53
+ columns: Column[];
54
+ } | null;
55
+ export declare function assignCells(line: Line, columns: Column[]): RowCells;