@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,144 @@
1
+ const HEADER_WINDOW_Y = 15;
2
+ const HEADER_MIN_HITS = 4;
3
+ const SNAP_TOL = 4;
4
+ const HEADER_LABELS = new Set(["Date", "Transaction", "Amount", "Units", "Price", "Unit", "Balance", "NAV"]);
5
+ const ALIGN = {
6
+ Date: "left",
7
+ Transaction: "left",
8
+ Amount: "right",
9
+ Units: "right",
10
+ Price: "right",
11
+ "Unit Balance": "right",
12
+ NAV: "right",
13
+ };
14
+ /** Matches printed numbers: 1,23,456.78 · (1,234.56) · -12.5 · .25 */
15
+ export const NUMERIC_RE = /^\(?-?(?:\d{1,3}(?:,\d{2,3})*|\d+)?(?:\.\d+)?\)?$/;
16
+ const TRAILING_NUMBER_RE = /^(.*\S)\s+(\(?-?[\d,]*\.?\d+\)?)$/;
17
+ const FULL_DATE_RE = /\d{1,2}[-\s]*[A-Za-z]{3}[-\s]*\d{4}/;
18
+ // A second date this much farther from the row's baseline than the first is a ghost (lines.ts OVERLAY_MIN_DY).
19
+ const GHOST_MIN_DY = 0.05;
20
+ /** A line that carries a number or a date is a data row, never part of the column header. */
21
+ function isDataLine(line) {
22
+ return line.items.some((it) => isNumeric(it.str) || FULL_DATE_RE.test(it.str));
23
+ }
24
+ export function isNumeric(s) {
25
+ const t = s.trim();
26
+ return t.length > 0 && /\d/.test(t) && NUMERIC_RE.test(t);
27
+ }
28
+ /** Finds the next transaction header at or after `start`. */
29
+ export function detectHeader(lines, start) {
30
+ for (let i = start; i < lines.length; i++) {
31
+ const window = [];
32
+ // Unlike casparser, the window stops at the first data row: callers skip
33
+ // every window line, so a row printed close under the header was lost.
34
+ for (let j = i; j < lines.length && lines[j].y - lines[i].y <= HEADER_WINDOW_Y && (j === i || !isDataLine(lines[j])); j++)
35
+ window.push(lines[j]);
36
+ const words = window.flatMap((l) => l.items).filter((it) => HEADER_LABELS.has(it.str.trim()));
37
+ const labels = new Set(words.map((w) => w.str.trim()));
38
+ if (labels.size < HEADER_MIN_HITS)
39
+ continue;
40
+ return { first: i, last: i + window.length - 1, columns: buildColumns(words) };
41
+ }
42
+ return null;
43
+ }
44
+ function buildColumns(words) {
45
+ const cols = [];
46
+ const balance = words.find((w) => w.str.trim() === "Balance");
47
+ for (const w of words) {
48
+ const label = w.str.trim();
49
+ if (label === "Balance")
50
+ continue;
51
+ if (label === "Unit") {
52
+ if (balance && Math.abs((balance.x0 + balance.x1) / 2 - (w.x0 + w.x1) / 2) < 30) {
53
+ cols.push({ label: "Unit Balance", x0: Math.min(w.x0, balance.x0), x1: Math.max(w.x1, balance.x1), align: "right" });
54
+ }
55
+ continue;
56
+ }
57
+ const l = label;
58
+ if (!cols.some((c) => c.label === l))
59
+ cols.push({ label: l, x0: w.x0, x1: w.x1, align: ALIGN[l] });
60
+ }
61
+ return cols.sort((a, b) => a.x0 - b.x0);
62
+ }
63
+ export function assignCells(line, columns) {
64
+ const numericCols = columns.filter((c) => c.align === "right");
65
+ const textCols = columns.filter((c) => c.align === "left");
66
+ const row = { line, cells: {}, via: {}, ambiguities: [], conflicts: [] };
67
+ const placed = new Map();
68
+ const put = (label, text, via, item) => {
69
+ placed.set(label, [...(placed.get(label) ?? []), { item, text }]);
70
+ row.via[label] = via;
71
+ };
72
+ const snapCol = (x1) => numericCols.find((c) => Math.abs(c.x1 - x1) <= SNAP_TOL);
73
+ const zoneAt = (x0) => {
74
+ // A left-aligned column owns x from its own left edge (−3pt) to the next
75
+ // column's left edge.
76
+ let owner;
77
+ for (const c of textCols)
78
+ if (x0 >= c.x0 - 3)
79
+ owner = c;
80
+ const next = columns.find((c) => owner && c.x0 > owner.x0);
81
+ return owner && (!next || x0 < next.x0 - 3) ? owner : undefined;
82
+ };
83
+ // casparser tests each glyph's midpoint; an item's first glyph midpoint is
84
+ // the fallback, so a date indented a little left of its label still lands.
85
+ const zoneCol = (item) => zoneAt(item.x0) ?? zoneAt(item.x0 + (item.x1 - item.x0) / Math.max(item.str.length, 1) / 2);
86
+ for (const item of line.items) {
87
+ const text = item.str.trim();
88
+ if (isNumeric(text)) {
89
+ const col = snapCol(item.x1);
90
+ if (col)
91
+ put(col.label, text, "snap", item);
92
+ else
93
+ row.ambiguities.push({ item, reason: "numeric item does not align with any numeric column" });
94
+ continue;
95
+ }
96
+ const m = TRAILING_NUMBER_RE.exec(text);
97
+ const tailCol = m ? snapCol(item.x1) : undefined;
98
+ if (m && tailCol) {
99
+ const head = zoneCol(item);
100
+ if (head) {
101
+ put(head.label, m[1], "split", item);
102
+ put(tailCol.label, m[2], "split", item);
103
+ continue;
104
+ }
105
+ }
106
+ const col = zoneCol(item);
107
+ if (col)
108
+ put(col.label, text, "zone", item);
109
+ else
110
+ row.ambiguities.push({ item, reason: "text item outside the Date/Transaction columns" });
111
+ }
112
+ for (const [label, parts] of placed) {
113
+ const value = label === "Transaction" ? parts.map((p) => p.text).join(" ") : settle(label, parts, line, row);
114
+ if (value !== null)
115
+ row.cells[label] = value;
116
+ }
117
+ return row;
118
+ }
119
+ /** One value for a Date or numeric cell, or null (a conflict, recorded on the row). */
120
+ function settle(label, parts, line, row) {
121
+ if (new Set(parts.map((p) => p.text)).size === 1)
122
+ return parts[0].text;
123
+ if (label === "Date") {
124
+ const dates = parts.filter((p) => FULL_DATE_RE.test(p.text));
125
+ // Pieces of one date split across items ("21-May-" + "2026").
126
+ if (dates.length < 2)
127
+ return parts.map((p) => p.text).join(" ");
128
+ const ys = line.items.map((i) => i.y).sort((a, b) => a - b);
129
+ const median = ys[Math.floor(ys.length / 2)];
130
+ const byDistance = [...dates].sort((a, b) => Math.abs(a.item.y - median) - Math.abs(b.item.y - median));
131
+ const [best, next] = byDistance;
132
+ if (Math.abs(next.item.y - median) - Math.abs(best.item.y - median) >= GHOST_MIN_DY) {
133
+ for (const p of parts)
134
+ if (p !== best)
135
+ row.ambiguities.push({ item: p.item, reason: "a second date in the Date cell, off the row's baseline, was set aside" });
136
+ return best.text;
137
+ }
138
+ }
139
+ const what = label === "Date" ? "two different dates" : "two different numbers";
140
+ for (const p of parts)
141
+ row.ambiguities.push({ item: p.item, reason: `the ${label} cell holds ${what}` });
142
+ row.conflicts.push(label);
143
+ return null;
144
+ }
@@ -0,0 +1,17 @@
1
+ import { type Line } from "../../layout/lines.js";
2
+ import type { Coverage, PrintedTotal } from "../../model.js";
3
+ /** A grand total, never a sub-total or a scheme footer's "Total Cost Value". */
4
+ export declare const GRAND_TOTAL_RE: RegExp;
5
+ /**
6
+ * The PORTFOLIO SUMMARY's Total row of a detailed statement, or null when no
7
+ * such row is printed before the first folio.
8
+ */
9
+ export declare function findPortfolioSummaryTotal(pages: ReadonlyArray<{
10
+ number: number;
11
+ lines: Line[];
12
+ }>): PrintedTotal | null;
13
+ /**
14
+ * One total from several candidate rows: none → null; rows that agree → the
15
+ * first; rows that disagree → null, recorded in coverage (never a pick).
16
+ */
17
+ export declare function pickTotal(candidates: PrintedTotal[], coverage: Coverage): PrintedTotal | null;
@@ -0,0 +1,105 @@
1
+ import { lineText } from "../../layout/lines.js";
2
+ import { parseNum } from "../../num.js";
3
+ import { isNumeric } from "./table.js";
4
+ const HEADING_RE = /\bportfolio\s+summary\b/i;
5
+ const FOLIO_RE = /Folio\s+No/i;
6
+ /** A grand total, never a sub-total or a scheme footer's "Total Cost Value". */
7
+ export const GRAND_TOTAL_RE = /^\s*((?:grand\s+|portfolio\s+)?total)\b(?!\s+cost\s+value)/i;
8
+ // Header words are grouped into columns when closer than this (as summary.ts's XCLUSTER_GAP).
9
+ const XCLUSTER_GAP = 7;
10
+ // How far left of its column's right edge a right-aligned number may start (a wide total).
11
+ const NUMERIC_WIDTH = 70;
12
+ const RIGHT_SLACK = 6;
13
+ /** Words of an item, x estimated pro rata by character (pdf.js gives item edges only). */
14
+ function itemWords(item) {
15
+ const per = (item.x1 - item.x0) / Math.max(item.str.length, 1);
16
+ return [...item.str.matchAll(/\S+/g)].map((m) => {
17
+ const at = m.index ?? 0;
18
+ return { text: m[0], x0: item.x0 + at * per, x1: item.x0 + (at + m[0].length) * per };
19
+ });
20
+ }
21
+ const lineWords = (line) => line.items.flatMap(itemWords).sort((a, b) => a.x0 - b.x0);
22
+ /** A header line names "Market Value" and carries no numbers. */
23
+ function headerColumns(line) {
24
+ const words = lineWords(line);
25
+ if (words.some((w) => isNumeric(w.text)))
26
+ return null;
27
+ if (!/\bmarket\s+value\b/i.test(lineText(line)))
28
+ return null;
29
+ const clusters = [];
30
+ let maxX1 = -Infinity;
31
+ for (const w of words) {
32
+ const cur = clusters[clusters.length - 1];
33
+ if (cur && w.x0 - maxX1 <= XCLUSTER_GAP) {
34
+ cur.push(w);
35
+ maxX1 = Math.max(maxX1, w.x1);
36
+ }
37
+ else {
38
+ clusters.push([w]);
39
+ maxX1 = w.x1;
40
+ }
41
+ }
42
+ return clusters.map((c) => {
43
+ const text = c.map((w) => w.text).join(" ");
44
+ const kind = /\bmarket\b/i.test(text) ? "market" : /\bcost\b/i.test(text) ? "cost" : "other";
45
+ return { kind, x0: Math.min(...c.map((w) => w.x0)), x1: Math.max(...c.map((w) => w.x1)) };
46
+ });
47
+ }
48
+ /** The Total row's numbers, each placed in its nearest header column. */
49
+ function placeNumbers(numbers, columns) {
50
+ const found = { cost: [], market: [] };
51
+ for (const w of numbers) {
52
+ const col = columns
53
+ .filter((c) => w.x1 >= c.x0 - NUMERIC_WIDTH && w.x1 <= c.x1 + RIGHT_SLACK)
54
+ .sort((a, b) => Math.abs(a.x1 - w.x1) - Math.abs(b.x1 - w.x1))[0];
55
+ const n = parseNum(w.text);
56
+ if (col && col.kind !== "other" && n)
57
+ found[col.kind].push(n);
58
+ }
59
+ const one = (ns) => (ns.length === 1 ? ns[0] : null);
60
+ return { cost: one(found.cost), marketValue: one(found.market) };
61
+ }
62
+ /**
63
+ * The PORTFOLIO SUMMARY's Total row of a detailed statement, or null when no
64
+ * such row is printed before the first folio.
65
+ */
66
+ export function findPortfolioSummaryTotal(pages) {
67
+ for (const page of pages) {
68
+ for (let i = 0; i < page.lines.length; i++) {
69
+ if (!HEADING_RE.test(lineText(page.lines[i])))
70
+ continue;
71
+ let columns = null;
72
+ for (let j = i + 1; j < page.lines.length; j++) {
73
+ const line = page.lines[j];
74
+ const text = lineText(line).trim();
75
+ if (FOLIO_RE.test(text) || HEADING_RE.test(text))
76
+ break;
77
+ columns ??= headerColumns(line);
78
+ const label = GRAND_TOTAL_RE.exec(text)?.[1];
79
+ if (!label)
80
+ continue;
81
+ const numbers = lineWords(line).filter((w) => isNumeric(w.text));
82
+ const placed = columns ? placeNumbers(numbers, columns) : { cost: null, marketValue: null };
83
+ return { label: label.replace(/\s+/g, " "), ...placed, source: { page: page.number, y: line.y } };
84
+ }
85
+ }
86
+ }
87
+ return null;
88
+ }
89
+ /**
90
+ * One total from several candidate rows: none → null; rows that agree → the
91
+ * first; rows that disagree → null, recorded in coverage (never a pick).
92
+ */
93
+ export function pickTotal(candidates, coverage) {
94
+ const first = candidates[0];
95
+ if (!first)
96
+ return null;
97
+ const same = (a, b) => (a?.value ?? null) === (b?.value ?? null);
98
+ const disagree = candidates.slice(1).filter((c) => !same(c.marketValue, first.marketValue) || !same(c.cost, first.cost));
99
+ if (disagree.length === 0)
100
+ return first;
101
+ for (const c of [first, ...disagree]) {
102
+ coverage.ambiguousCells.push({ source: c.source, text: c.marketValue?.raw ?? c.label, reason: "the statement prints more than one portfolio total, and they differ; none was used" });
103
+ }
104
+ return null;
105
+ }
@@ -0,0 +1,22 @@
1
+ import type { Detection } from "../../detect.js";
2
+ import type { ExtractedDocument } from "../../extract/types.js";
3
+ import type { CasDocument } from "../../model.js";
4
+ import { type Num } from "../../num.js";
5
+ /** "31-Oct-2026", "31-10-2026" or "31/10/2026" → ISO date, or null unless a real calendar date. */
6
+ export declare function depositoryDate(s: string): string | null;
7
+ interface Placed {
8
+ units: Num;
9
+ nav: Num;
10
+ value: Num;
11
+ cost: Num | null;
12
+ }
13
+ /**
14
+ * The three numbers that close units × NAV = value within printed precision.
15
+ * Of several, the rightmost value wins (a cost pair, units × average cost =
16
+ * total cost, sits to its left), then the rightmost NAV, then the leftmost
17
+ * units. The cost is the closing pair's total to the left of the NAV, or the
18
+ * one column printed between NAV and value (CDSL's "amount invested").
19
+ */
20
+ export declare function placeByArithmetic(nums: readonly Num[]): Placed | null;
21
+ export declare function parseDepository(doc: ExtractedDocument, detection: Detection): CasDocument;
22
+ export {};