@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,343 @@
1
+ import { cleanPage, lineText, rotatedTextChars } from "../../layout/lines.js";
2
+ import { parseNum } from "../../num.js";
3
+ import { checkScheme, fixSigns, portfolioTotalCheck } from "../../checks.js";
4
+ import { findPortfolioSummaryTotal } from "./total.js";
5
+ import { classify, giftFolio } from "./classify.js";
6
+ import { buildSchemeHeader, hyphenatedName, isHeaderLine, NOMINEE_RE, regionCandidate } from "./header.js";
7
+ import { extractAddressee } from "./investor.js";
8
+ import { assignCells, detectHeader } from "./table.js";
9
+ import Big from "big.js";
10
+ export const ENGINE_VERSION = "0.1.0-m2";
11
+ const FOLIO_LINE_RE = /Folio\s+No\s*:\s*(\d+(?:\s*\/\s*\d+)?)(?:.*?PAN\s*:\s*([A-Z]{5}\d{4}[A-Z]))?(?:.*?KYC\s*:\s*(OK|NOT OK))?(?:.*?PAN\s*:\s*(OK|NOT OK))?/i;
12
+ const OPEN_BAL_RE = /Opening\s+Unit\s+Balance\s*:?\s*([\d,.]+)/i;
13
+ const CLOSE_BAL_RE = /Closing\s+Unit\s+Balance\s*:?\s*([\d,.]+)/i;
14
+ const NAV_RE = /NAV\s+on\s+(\d{2}-[A-Za-z]{3}-\d{4})\s*:\s*INR\s*([\d,.]+)/i;
15
+ const VALUATION_RE = /(?:Valuation|Market\s+Value)\s+on\s+(\d{2}-[A-Za-z]{3}-\d{4})\s*:\s*INR\s*([\d,.]+)/i;
16
+ const COST_VALUE_RE = /Total\s+Cost\s+Value\s*:?\s*([\d,.]+)/i;
17
+ const STMT_PERIOD_RE = /(\d{2}-[A-Za-z]{3}-\d{4})\s+To\s+(\d{2}-[A-Za-z]{3}-\d{4})/i;
18
+ const AMC_RE = /^(.+?\s+(?:MF|Mutual\s*Fund|Fund\s*House))$/i;
19
+ const DATE_CELL_RE = /^\s*(\d{1,2})[-\s]*([A-Za-z]{3})[-\s]*(\d{4})/;
20
+ const PAGE_FOOTER_RE = /^Page\s*\d+\s*(?:of|\/)\s*\d+$/i;
21
+ const CONTINUATION_MAX_GAP = 10;
22
+ const HOLDER_NAME_RE = /^[A-Z][A-Za-z .'&-]*$/;
23
+ // casparser TXN_HEADER_LABELS (MIT): a column header that follows the folio
24
+ // line across a page break is not a name. casparser needs 4 labels; KFin
25
+ // splits its header over lines, so 2 is enough here.
26
+ const TXN_HEADER_WORDS = new Set(["date", "transaction", "amount", "units", "price", "unit", "balance", "nav"]);
27
+ const TXN_HEADER_MIN_HITS = 2;
28
+ // Page furniture a holder window can also run into (not in casparser).
29
+ const BANNER_RE = /\b(?:consolidated|statement|summary|portfolio)\b/i;
30
+ const FOOTER_RES = [OPEN_BAL_RE, CLOSE_BAL_RE, NAV_RE, VALUATION_RE, COST_VALUE_RE];
31
+ const NUMERIC_CELLS = ["Amount", "Units", "Price", "NAV", "Unit Balance"];
32
+ const MONTHS = { jan: "01", feb: "02", mar: "03", apr: "04", may: "05", jun: "06", jul: "07", aug: "08", sep: "09", oct: "10", nov: "11", dec: "12" };
33
+ /** "dd-Mmm-yyyy" → ISO date, or null unless it is a real calendar date (PLAN.md §5.4 group 3). */
34
+ export function isoDate(s) {
35
+ const m = DATE_CELL_RE.exec(s);
36
+ const mm = m && MONTHS[m[2].toLowerCase()];
37
+ if (!m || !mm)
38
+ return null;
39
+ const day = Number(m[1]);
40
+ // Day 0 of the next month is the last day of this one.
41
+ if (day < 1 || day > new Date(Date.UTC(Number(m[3]), Number(mm), 0)).getUTCDate())
42
+ return null;
43
+ return `${m[3]}-${mm}-${m[1].padStart(2, "0")}`;
44
+ }
45
+ function looksLikeHolderName(text) {
46
+ const t = text.split(/\s+/).join(" ").trim();
47
+ const words = t.split(" ");
48
+ if (words.length < 2 || words.length > 8 || t.length > 80)
49
+ return false;
50
+ if (!HOLDER_NAME_RE.test(t))
51
+ return false;
52
+ if (!words.every((w) => w === "&" || /^[A-Z]/.test(w)))
53
+ return false;
54
+ if (words.filter((w) => TXN_HEADER_WORDS.has(w.toLowerCase())).length >= TXN_HEADER_MIN_HITS || BANNER_RE.test(t))
55
+ return false;
56
+ // A hyphenated name ("Test Al-Investor") also looks like "<code>-"; header.ts tells them apart.
57
+ return !isHeaderLine(t) || hyphenatedName(t);
58
+ }
59
+ export function parseDetailed(doc, detection) {
60
+ const overlayTwins = detection.issuer === "KFINTECH" ? "any-text" : "same-text";
61
+ const coverage = { pages: doc.pages.length, datedRowsSeen: 0, transactionsParsed: 0, datedRowsSkipped: [], ambiguousCells: [], schemeRegionsUnbuilt: [] };
62
+ const warnings = [];
63
+ const folios = new Map();
64
+ let period = null;
65
+ let amc = null;
66
+ let folio = null;
67
+ let scheme = null;
68
+ let columns = [];
69
+ let headerBuf = [];
70
+ let headerActive = false;
71
+ let headerStart = { page: 1, y: 0 };
72
+ let holderLinesLeft = 0;
73
+ let folioPage = 0;
74
+ let order = 0;
75
+ // Rows with a cell that held two values: checks that need that cell report "unavailable".
76
+ const unreadable = new Set();
77
+ let undatedNumeric = 0;
78
+ // Lines of every page, for the PORTFOLIO SUMMARY total (read after the walk).
79
+ const pageLines = [];
80
+ const abandon = (where) => {
81
+ if (headerActive && regionCandidate(headerBuf)) {
82
+ coverage.schemeRegionsUnbuilt.push({ source: headerStart, reason: `scheme header abandoned at ${where} without an Opening Unit Balance` });
83
+ }
84
+ };
85
+ for (const page of doc.pages) {
86
+ const clean = cleanPage(page, { overlayTwins });
87
+ const { lines } = clean;
88
+ pageLines.push({ number: page.number, lines });
89
+ // Rotated text other than the watermark can't be laid out in rows.
90
+ const rotated = rotatedTextChars(clean);
91
+ if (rotated)
92
+ warnings.push(`Page ${page.number}: ${rotated} characters of rotated text were set aside; anything printed there is missing.`);
93
+ const header = detectHeader(lines, 0);
94
+ let headerFirst = -1;
95
+ let headerLast = -1;
96
+ if (header) {
97
+ columns = header.columns;
98
+ headerFirst = header.first;
99
+ headerLast = header.last;
100
+ }
101
+ let contIdx = -2;
102
+ let contY = 0;
103
+ for (let i = 0; i < lines.length; i++) {
104
+ const line = lines[i];
105
+ const text = lineText(line).trim();
106
+ const src = { page: page.number, y: line.y };
107
+ if (!period) {
108
+ const m = STMT_PERIOD_RE.exec(text);
109
+ const from = m && isoDate(m[1]);
110
+ const to = m && isoDate(m[2]);
111
+ if (from && to)
112
+ period = { from, to };
113
+ }
114
+ // A wrapped description joins the row above it before any anchor is
115
+ // tried: its text can read like one ("Folio No: 7654321" after a gift
116
+ // row). casparser tests anchors first. Footer lines stay anchors.
117
+ if (scheme && !headerActive && columns.length && i > headerLast && i === contIdx + 1 && line.y - contY <= CONTINUATION_MAX_GAP &&
118
+ !FOOTER_RES.some((re) => re.test(text))) {
119
+ const row = assignCells(line, columns);
120
+ const filled = Object.keys(row.cells);
121
+ const last = scheme.transactions[scheme.transactions.length - 1];
122
+ if (last && filled.length === 1 && filled[0] === "Transaction" && row.ambiguities.length === 0) {
123
+ last.description = `${last.description} ${(row.cells.Transaction ?? "").trim()}`;
124
+ Object.assign(last, reclassify(last));
125
+ contIdx = i;
126
+ contY = line.y;
127
+ continue;
128
+ }
129
+ }
130
+ // AMC header
131
+ const amcM = AMC_RE.exec(text);
132
+ if (amcM && !text.includes(":")) {
133
+ abandon("AMC boundary");
134
+ amc = amcM[1].trim();
135
+ headerBuf = [];
136
+ headerActive = false;
137
+ holderLinesLeft = 0;
138
+ continue;
139
+ }
140
+ // Folio header. A dated row that mentions a folio is a gift transfer.
141
+ // Inside a transaction table (a scheme still open), so is text that
142
+ // starts in the Transaction column: a wrapped gift or transmission
143
+ // description further down than a continuation; a real folio line
144
+ // starts at the margin.
145
+ const txnCol = columns.find((c) => c.label === "Transaction");
146
+ const inTxnColumn = scheme !== null && !headerActive && txnCol !== undefined && line.items[0].x0 >= txnCol.x0 - 3;
147
+ if (/Folio No/i.test(text) && !DATE_CELL_RE.test(text) && !inTxnColumn) {
148
+ const m = FOLIO_LINE_RE.exec(text);
149
+ if (m) {
150
+ const no = m[1].replace(/\s+/g, " ").trim();
151
+ const key = `${amc ?? "UNKNOWN"}|${no}`;
152
+ let f = folios.get(key);
153
+ if (!f) {
154
+ f = { folio: no, amc: amc ?? "UNKNOWN", pan: m[2] ?? null, kyc: m[3] ?? null, panKyc: m[4] ?? null, holderName: null, schemes: [] };
155
+ folios.set(key, f);
156
+ }
157
+ folio = f;
158
+ scheme = null;
159
+ holderLinesLeft = f.holderName ? 0 : 2;
160
+ folioPage = page.number;
161
+ abandon("folio boundary");
162
+ headerBuf = [];
163
+ headerActive = true;
164
+ headerStart = src;
165
+ continue;
166
+ }
167
+ }
168
+ // Holder name: observed, never consumed (it also flows into the region buffer, where it is inert).
169
+ // The page's column header doesn't count against the window, nor does
170
+ // the banner above it when the folio line ended the previous page
171
+ // (casparser cams_detailed.py, MIT, follows the window across pages).
172
+ const furniture = header !== null && i <= headerLast && (i >= headerFirst || page.number !== folioPage);
173
+ if (holderLinesLeft && folio && !furniture) {
174
+ holderLinesLeft--;
175
+ if (looksLikeHolderName(text)) {
176
+ folio.holderName = text.split(/\s+/).join(" ");
177
+ holderLinesLeft = 0;
178
+ }
179
+ else if (isHeaderLine(text) || OPEN_BAL_RE.test(text))
180
+ holderLinesLeft = 0;
181
+ }
182
+ // Opening Unit Balance closes the header region and builds the scheme.
183
+ const openM = OPEN_BAL_RE.exec(text);
184
+ if (openM) {
185
+ if (headerActive) {
186
+ const h = buildSchemeHeader(headerBuf);
187
+ if (h && folio) {
188
+ scheme = {
189
+ ...h, open: null, close: null, closeCalculated: null, nav: null, valuation: null, cost: null, footerSource: null,
190
+ transactions: [], checks: [], source: headerStart,
191
+ };
192
+ folio.schemes.push(scheme);
193
+ }
194
+ else {
195
+ scheme = null;
196
+ coverage.schemeRegionsUnbuilt.push({ source: src, reason: "unparseable scheme header before Opening Unit Balance; its transactions were skipped" });
197
+ }
198
+ headerActive = false;
199
+ headerBuf = [];
200
+ }
201
+ if (scheme)
202
+ scheme.open = parseNum(openM[1]);
203
+ continue;
204
+ }
205
+ // Footer anchors attach to the current scheme. Closing balance re-opens the region.
206
+ let consumed = false;
207
+ if (scheme) {
208
+ const c = CLOSE_BAL_RE.exec(text);
209
+ if (c) {
210
+ scheme.close = parseNum(c[1]);
211
+ scheme.footerSource ??= src;
212
+ headerBuf = [];
213
+ headerActive = true;
214
+ headerStart = src;
215
+ consumed = true;
216
+ }
217
+ const nav = NAV_RE.exec(text);
218
+ if (nav) {
219
+ const v = parseNum(nav[2]);
220
+ const d = isoDate(nav[1]);
221
+ if (v && d)
222
+ scheme.nav = { date: d, value: v };
223
+ consumed = true;
224
+ }
225
+ const val = VALUATION_RE.exec(text);
226
+ if (val) {
227
+ const v = parseNum(val[2]);
228
+ const d = isoDate(val[1]);
229
+ if (v && d) {
230
+ scheme.valuation = { date: d, value: v };
231
+ scheme.footerSource = src;
232
+ }
233
+ consumed = true;
234
+ }
235
+ const cost = COST_VALUE_RE.exec(text);
236
+ if (cost) {
237
+ scheme.cost = parseNum(cost[1]);
238
+ consumed = true;
239
+ }
240
+ if (!headerActive) {
241
+ const nm = NOMINEE_RE.exec(text);
242
+ if (nm?.groups)
243
+ scheme.nominees = [nm.groups["n1"], nm.groups["n2"], nm.groups["n3"]].map((n) => (n ?? "").trim()).filter(Boolean);
244
+ }
245
+ }
246
+ if (headerActive) {
247
+ if (!consumed && !(i >= headerFirst && i <= headerLast))
248
+ headerBuf.push(text);
249
+ continue;
250
+ }
251
+ if (!scheme || !columns.length || i <= headerLast)
252
+ continue;
253
+ // Page footer ("Page 3 of 50"): its page number lands in a numeric
254
+ // column. Measured on a real KFintech statement (one per page).
255
+ if (PAGE_FOOTER_RE.test(text))
256
+ continue;
257
+ // Transaction rows
258
+ const row = assignCells(line, columns);
259
+ const dateCell = row.cells.Date ?? "";
260
+ const desc = (row.cells.Transaction ?? "").trim();
261
+ const date = isoDate(dateCell);
262
+ // Two dates in the Date cell, or a date that isn't on the calendar: a
263
+ // dated row that can't be placed. Recorded, never guessed.
264
+ const badDate = row.conflicts.includes("Date")
265
+ ? "the Date cell holds two different dates"
266
+ : !date && DATE_CELL_RE.test(dateCell) ? "the date is not a real calendar date" : null;
267
+ if (!date && !badDate) {
268
+ // Not a continuation (joined above). Numbers or unplaced items on a
269
+ // line without a readable date are a row we failed to read.
270
+ const numbers = NUMERIC_CELLS.filter((l) => row.cells[l] !== undefined);
271
+ for (const l of numbers)
272
+ coverage.ambiguousCells.push({ source: src, text: row.cells[l], reason: `${l} on a line without a readable date; the line was skipped` });
273
+ for (const a of row.ambiguities)
274
+ coverage.ambiguousCells.push({ source: src, text: a.item.str, reason: `${a.reason} (line without a readable date, skipped)` });
275
+ if (numbers.length || row.ambiguities.length)
276
+ undatedNumeric++;
277
+ continue;
278
+ }
279
+ coverage.datedRowsSeen++;
280
+ for (const a of row.ambiguities)
281
+ coverage.ambiguousCells.push({ source: src, text: a.item.str, reason: a.reason });
282
+ if (badDate || !date) {
283
+ coverage.datedRowsSkipped.push({ source: src, reason: `dated line skipped: ${badDate}` });
284
+ continue;
285
+ }
286
+ if (!desc) {
287
+ coverage.datedRowsSkipped.push({ source: src, reason: "dated line without a description" });
288
+ continue;
289
+ }
290
+ const amount = parseNum(row.cells.Amount);
291
+ const units = parseNum(row.cells.Units);
292
+ let price = parseNum(row.cells.Price ?? row.cells.NAV);
293
+ const balance = parseNum(row.cells["Unit Balance"]);
294
+ if (!amount && !units && !balance && !desc.startsWith("***")) {
295
+ coverage.datedRowsSkipped.push({ source: src, reason: "dated line with no amount, units or balance (not a *** marker row)" });
296
+ continue;
297
+ }
298
+ // A Price cell that held two values isn't missing: don't derive one.
299
+ if (!price && !row.conflicts.includes("Price") && !row.conflicts.includes("NAV") && amount && units && !new Big(units.value).eq(0)) {
300
+ // Older templates omit Price; derive it and mark it as derived.
301
+ price = { raw: "derived", value: new Big(amount.value).div(new Big(units.value)).abs().toFixed(4), scale: 4 };
302
+ }
303
+ const t = {
304
+ order: order++, date, description: desc, amount, units, price, balance,
305
+ type: "UNKNOWN", dividendRate: null, giftFolio: null, signCorrected: false, source: src,
306
+ };
307
+ Object.assign(t, reclassify(t));
308
+ if (row.conflicts.length)
309
+ unreadable.add(t);
310
+ scheme.transactions.push(t);
311
+ coverage.transactionsParsed++;
312
+ contIdx = i;
313
+ contY = line.y;
314
+ }
315
+ }
316
+ abandon("end of document");
317
+ const allSchemes = [...folios.values()].flatMap((f) => f.schemes);
318
+ for (const s of allSchemes) {
319
+ fixSigns(s, (t) => Object.assign(t, reclassify(t)));
320
+ s.checks = checkScheme(s, period, { unreadable });
321
+ }
322
+ if (undatedNumeric)
323
+ warnings.push(`${undatedNumeric} line(s) in transaction tables carry numbers or unplaced text but no readable date; they were skipped.`);
324
+ if (coverage.schemeRegionsUnbuilt.length)
325
+ warnings.push(`${coverage.schemeRegionsUnbuilt.length} scheme header(s) could not be read; their transactions are missing.`);
326
+ const printedTotal = findPortfolioSummaryTotal(pageLines);
327
+ return {
328
+ schemaVersion: "1",
329
+ source: { issuer: detection.issuer, variant: detection.variant, engineVersion: ENGINE_VERSION },
330
+ 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 },
331
+ statementPeriod: period,
332
+ addressee: extractAddressee(doc),
333
+ folios: [...folios.values()],
334
+ printedTotal,
335
+ checks: [portfolioTotalCheck(printedTotal, allSchemes)],
336
+ coverage,
337
+ warnings,
338
+ };
339
+ }
340
+ function reclassify(t) {
341
+ const { type, dividendRate } = classify(t.description, t.units);
342
+ return { type, dividendRate, giftFolio: type === "GIFT_IN" || type === "GIFT_OUT" ? giftFolio(t.description) : null };
343
+ }
@@ -0,0 +1,47 @@
1
+ import type { Plan, PlanOption } from "../../model.js";
2
+ export declare const RTA_TOKEN_RE: RegExp;
3
+ export declare const NOMINEE_RE: RegExp;
4
+ export interface SchemeHeader {
5
+ name: string;
6
+ rtaCode: string;
7
+ rta: string;
8
+ isin: string | null;
9
+ advisor: string | null;
10
+ plan: Plan;
11
+ option: PlanOption;
12
+ nominees: string[];
13
+ }
14
+ export declare function isHeaderLine(text: string): boolean;
15
+ /**
16
+ * A hyphenated person's name ("Test Al-Investor", "MARY-ANN TESTPERSON") also
17
+ * matches the `<code>-` pattern; casparser assumes a name has no dash. Scheme
18
+ * codes are upper case ("128TSGPG", "HGFG") and the scheme name after them
19
+ * isn't ("HGFG-HDFC Flexi Cap…"), whereas a name reads as Title Case or all
20
+ * upper case. An all-upper-case scheme line wrapped before its markers still
21
+ * passes, so callers only act on this when another scheme line follows.
22
+ */
23
+ export declare function hyphenatedName(text: string): boolean;
24
+ /** A region is a scheme header only if it has a `<code>-` line AND Registrar evidence. */
25
+ export declare function regionCandidate(buf: string[]): {
26
+ lines: string[];
27
+ schemeIdx: number;
28
+ members: number[];
29
+ text: string;
30
+ } | null;
31
+ export declare function buildSchemeHeader(buf: string[]): SchemeHeader | null;
32
+ /**
33
+ * Plan from the scheme name only. "(Advisor: DIRECT)" is the folio's broker
34
+ * code, not the plan: units bought without a distributor before Direct plans
35
+ * existed (2013), or whose broker was later changed to "Direct", are still in
36
+ * the Regular plan. Direct plans carry "Direct" in their names. The suffix
37
+ * decides; without a plan word there, the whole name may say "Direct" or
38
+ * "Regular Plan" ("… Fund Direct Plan - Growth"), but not a fund name's
39
+ * "Regular" ("… Regular Savings Fund").
40
+ */
41
+ export declare function planOf(name: string): Plan;
42
+ /**
43
+ * Option from the scheme name's suffix, or the whole name when the suffix
44
+ * names none. "Dividend Yield" is a fund category, not an option. A suffix
45
+ * naming both Growth and IDCW is UNKNOWN rather than a guess.
46
+ */
47
+ export declare function optionOf(name: string): PlanOption;
@@ -0,0 +1,170 @@
1
+ /**
2
+ * Scheme-header region → scheme identity. Ported from casparser
3
+ * `cams_detailed.py` (MIT): every line between a folio line (or the previous
4
+ * scheme's closing balance) and the next "Opening Unit Balance" is buffered,
5
+ * and the whole region is judged at once, because the header wraps
6
+ * unpredictably (scheme name, ISIN, advisor and registrar can each spill
7
+ * onto the next line, in different orders per template).
8
+ */
9
+ import { cleanSchemeName } from "./classify.js";
10
+ export const RTA_TOKEN_RE = /\b(CAMS|KFINTECH|KFIN|KARVY)\b/i;
11
+ const HEADER_MARKER_RE = /Registrar\s*:|Advisor\s*:|ISIN\s*:|Nominee\s+\d|\bARN-?\d+\b|\bINA\d+\b/i;
12
+ // "<code>-<name>": alphanumeric code tokens, at least one letter, dash glued
13
+ // to the last token ("Entry Load - NIL" and "01-Jan-1990" don't match).
14
+ const SCHEME_CODE_RE = /^\s*(?=[A-Z0-9 ]{0,40}[A-Z])[A-Z0-9]+(?: [A-Z0-9]+)*-/i;
15
+ const TRAILING_MARKER_RE = /(Registrar\s*:|Advisor\s*:|ISIN\s*:|\(\s*Advisor\s*:)\s*$/i;
16
+ const INLINE_ISIN_RE = /[-\s]*ISIN\s*:\s*([A-Z0-9]+)/i;
17
+ const INLINE_ADVISOR_RE = /[-\s]*\(\s*Advisor\s*:\s*([^)]+?)\)/i;
18
+ const INLINE_ADVISOR_RE_G = /[-\s]*\(\s*Advisor\s*:\s*([^)]+?)\)/gi;
19
+ const NAME_EXCISE_ISIN_RE = /[-\s]*ISIN\s*:\s*INF[A-Z0-9]*/gi;
20
+ const NAME_TERMINATOR_RE = /\(\s*Advisor\s*:|Registrar\s*:?|Nominee\s+\d|\bARN-?\d+\b|\bINA\d+\b|\b(?:CAMS|KFINTECH|KFIN|KARVY)\b/i;
21
+ const ADVISOR_CODE_RE = /\b(ARN-?\d+|INA\d+)\b/i;
22
+ const FULL_ISIN_RE = /^INF[0-9A-Z]{8}\d$/;
23
+ const ISIN_ANYWHERE_RE = /\bINF[0-9A-Z]{8}\d\b/;
24
+ const SCHEME_HEAD_RTA_RE = /Registrar\s*:\s*(\S+)/i;
25
+ export const NOMINEE_RE = /Nominee\s+1\s*:\s*(?<n1>[^:]*?)\s*(?:Nominee\s+2\s*:\s*(?<n2>[^:]*?)\s*(?:Nominee\s+3\s*:\s*(?<n3>.*?))?)?$/i;
26
+ export function isHeaderLine(text) {
27
+ return HEADER_MARKER_RE.test(text) || RTA_TOKEN_RE.test(text) || SCHEME_CODE_RE.test(text);
28
+ }
29
+ // casparser's holder-name shape (cams_detailed.py, MIT): letters and name punctuation.
30
+ const NAME_SHAPE_RE = /^[A-Z][A-Za-z .'&-]*$/;
31
+ /**
32
+ * A hyphenated person's name ("Test Al-Investor", "MARY-ANN TESTPERSON") also
33
+ * matches the `<code>-` pattern; casparser assumes a name has no dash. Scheme
34
+ * codes are upper case ("128TSGPG", "HGFG") and the scheme name after them
35
+ * isn't ("HGFG-HDFC Flexi Cap…"), whereas a name reads as Title Case or all
36
+ * upper case. An all-upper-case scheme line wrapped before its markers still
37
+ * passes, so callers only act on this when another scheme line follows.
38
+ */
39
+ export function hyphenatedName(text) {
40
+ const t = text.split(/\s+/).join(" ").trim();
41
+ const words = t.split(" ");
42
+ if (!SCHEME_CODE_RE.test(t) || words.length < 2 || words.length > 8 || t.length > 80 || !NAME_SHAPE_RE.test(t))
43
+ return false;
44
+ if (!words.every((w) => w === "&" || /^[A-Z]/.test(w)) || HEADER_MARKER_RE.test(t) || RTA_TOKEN_RE.test(t))
45
+ return false;
46
+ return /[a-z]/.test(codeOf(t)) || t === t.toUpperCase();
47
+ }
48
+ const codeOf = (line) => line.slice(0, line.indexOf("-")).trim();
49
+ function expectsContinuation(text) {
50
+ if (TRAILING_MARKER_RE.test(text.trim()))
51
+ return true;
52
+ const adv = /\(\s*Advisor\s*:/i.exec(text);
53
+ return adv !== null && !text.slice(adv.index + adv[0].length).includes(")");
54
+ }
55
+ function findSchemeLine(lines) {
56
+ // "ARN-…" is a wrapped advisor code, never a scheme.
57
+ const found = lines.flatMap((ln, k) => (SCHEME_CODE_RE.test(ln) && codeOf(ln).toUpperCase() !== "ARN" ? [k] : []));
58
+ const [first, next] = found;
59
+ if (first === undefined)
60
+ return null;
61
+ // Not in casparser: a hyphenated holder name printed above the scheme line
62
+ // would otherwise give the scheme its code and put the name in scheme.name.
63
+ if (next !== undefined && hyphenatedName(lines[first]) && !hyphenatedName(lines[next]) && !/[a-z]/.test(codeOf(lines[next])))
64
+ return next;
65
+ return first;
66
+ }
67
+ function memberIndices(lines) {
68
+ const out = [];
69
+ let forced = false;
70
+ lines.forEach((ln, idx) => {
71
+ if (forced || isHeaderLine(ln)) {
72
+ out.push(idx);
73
+ forced = expectsContinuation(ln);
74
+ }
75
+ else
76
+ forced = false;
77
+ });
78
+ return out;
79
+ }
80
+ /** A region is a scheme header only if it has a `<code>-` line AND Registrar evidence. */
81
+ export function regionCandidate(buf) {
82
+ const lines = buf.map((s) => s.trim()).filter(Boolean);
83
+ if (!lines.length)
84
+ return null;
85
+ const schemeIdx = findSchemeLine(lines);
86
+ if (schemeIdx === null)
87
+ return null;
88
+ const members = memberIndices(lines);
89
+ const text = members.map((k) => lines[k]).join(" ");
90
+ if (!text.includes("Registrar"))
91
+ return null;
92
+ return { lines, schemeIdx, members, text };
93
+ }
94
+ export function buildSchemeHeader(buf) {
95
+ const cand = regionCandidate(buf);
96
+ if (!cand)
97
+ return null;
98
+ const { lines, schemeIdx, members, text } = cand;
99
+ const schemeLine = lines[schemeIdx];
100
+ const dash = schemeLine.indexOf("-");
101
+ const rtaCode = schemeLine.slice(0, dash).trim();
102
+ let nameText = [schemeLine.slice(dash + 1), ...members.filter((k) => k > schemeIdx).map((k) => lines[k])].join(" ");
103
+ nameText = nameText.replace(INLINE_ADVISOR_RE_G, "").replace(NAME_EXCISE_ISIN_RE, "");
104
+ const cut = NAME_TERMINATOR_RE.exec(nameText);
105
+ const rawName = cut ? nameText.slice(0, cut.index) : nameText;
106
+ const name = cleanSchemeName(rawName);
107
+ let isin = INLINE_ISIN_RE.exec(text)?.[1]?.trim() ?? null;
108
+ if (!isin || !FULL_ISIN_RE.test(isin))
109
+ isin = ISIN_ANYWHERE_RE.exec(text)?.[0] ?? null;
110
+ let advisor = INLINE_ADVISOR_RE.exec(text)?.[1]?.trim() ?? null;
111
+ const code = advisor ? ADVISOR_CODE_RE.exec(advisor) : null;
112
+ if (code)
113
+ advisor = code[1];
114
+ const rtaTok = RTA_TOKEN_RE.exec(text);
115
+ const rta = rtaTok ? rtaTok[1].toUpperCase() : SCHEME_HEAD_RTA_RE.exec(text)?.[1]?.trim() || "UNKNOWN";
116
+ let nominees = [];
117
+ for (const ln of lines) {
118
+ const m = NOMINEE_RE.exec(ln);
119
+ if (m?.groups) {
120
+ nominees = [m.groups["n1"], m.groups["n2"], m.groups["n3"]].map((n) => (n ?? "").trim()).filter(Boolean);
121
+ break;
122
+ }
123
+ }
124
+ return { name, rtaCode, rta, isin, advisor, plan: planOf(name), option: optionOf(name), nominees };
125
+ }
126
+ /**
127
+ * The plan/option part of a scheme name: what follows the first " - " (or the
128
+ * first "-" when no dash is spaced). Fund names carry words such as "Growth",
129
+ * "Regular" or "Dividend Yield" that are not the plan or the option.
130
+ */
131
+ function suffixOf(name) {
132
+ const spaced = /\s+-\s+/.exec(name);
133
+ if (spaced)
134
+ return name.slice(spaced.index + spaced[0].length);
135
+ const dash = name.indexOf("-");
136
+ return dash >= 0 ? name.slice(dash + 1) : name;
137
+ }
138
+ const PLAN_WORD_RE = /\b(direct|regular)\b/i;
139
+ /**
140
+ * Plan from the scheme name only. "(Advisor: DIRECT)" is the folio's broker
141
+ * code, not the plan: units bought without a distributor before Direct plans
142
+ * existed (2013), or whose broker was later changed to "Direct", are still in
143
+ * the Regular plan. Direct plans carry "Direct" in their names. The suffix
144
+ * decides; without a plan word there, the whole name may say "Direct" or
145
+ * "Regular Plan" ("… Fund Direct Plan - Growth"), but not a fund name's
146
+ * "Regular" ("… Regular Savings Fund").
147
+ */
148
+ export function planOf(name) {
149
+ const word = PLAN_WORD_RE.exec(suffixOf(name))?.[1] ?? (/\bdirect\b/i.test(name) ? "direct" : /\bregular\s+plan\b/i.test(name) ? "regular" : null);
150
+ return word === null ? "UNKNOWN" : word.toLowerCase() === "direct" ? "DIRECT" : "REGULAR";
151
+ }
152
+ const IDCW_RE = /idcw|dividend|income\s+distribution\s+cum\s+capital\s+withdrawal|\bdiv\b/;
153
+ const GROWTH_RE = /\bgrowth\b/;
154
+ /**
155
+ * Option from the scheme name's suffix, or the whole name when the suffix
156
+ * names none. "Dividend Yield" is a fund category, not an option. A suffix
157
+ * naming both Growth and IDCW is UNKNOWN rather than a guess.
158
+ */
159
+ export function optionOf(name) {
160
+ const whole = name.toLowerCase().replace(/dividend\s+yield/g, " ");
161
+ const suffix = suffixOf(whole);
162
+ const n = IDCW_RE.test(suffix) || GROWTH_RE.test(suffix) ? suffix : whole;
163
+ const idcw = IDCW_RE.test(n);
164
+ const growth = GROWTH_RE.test(n);
165
+ if (idcw && growth)
166
+ return "UNKNOWN";
167
+ if (idcw)
168
+ return /reinv/.test(n) ? "IDCW_REINVEST" : /pay\s*out|\bpaid\b/.test(n) ? "IDCW_PAYOUT" : "UNKNOWN";
169
+ return growth ? "GROWTH" : "UNKNOWN";
170
+ }
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Addressee block on page 1 of a CAMS / KFintech CAS: the person the statement
3
+ * was sent to. Ported from casparser `parsers/_investor.py` (MIT),
4
+ * `extract_cams_kfin_investor`, which reads the top-left column of page 1:
5
+ *
6
+ * Email Id: <email>
7
+ * <Investor Name>
8
+ * <Address line 1> … <Address line N>
9
+ * [Phone Off: …] some KFin templates
10
+ * Mobile: <mobile>
11
+ *
12
+ * Differences, each toward null rather than a guess:
13
+ * - casparser walks pdfium page objects. pdf.js items can split one run (label
14
+ * and value, or an email in pieces), so left-column items are clustered into
15
+ * lines and joined by geometry: touching items are glued, separated ones get
16
+ * a space.
17
+ * - Without `Mobile:` casparser reads to the end of the column, pulling the
18
+ * portfolio summary into the address. Here the block also ends at a gap wider
19
+ * than a blank line or at a line that belongs to the statement body.
20
+ * - Email and mobile must validate once the label is stripped. A value with an
21
+ * internal space, a mask or a truncation is null, never repaired.
22
+ * - Nothing throws. A page 1 without the block gives all nulls.
23
+ * - Nothing is derived from the PDF password (PLAN.md §5.5).
24
+ */
25
+ import type { ExtractedDocument } from "../../extract/types.js";
26
+ import type { CasDocument } from "../../model.js";
27
+ export type Addressee = CasDocument["addressee"];
28
+ export declare function extractAddressee(doc: ExtractedDocument): Addressee;