@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,244 @@
1
+ /**
2
+ * pdf.js extraction backend. Text only: nothing is rendered, no scripting,
3
+ * annotation, action or attachment APIs are called (PLAN.md §5.1, §7).
4
+ *
5
+ * The pdf.js module is injected so the same code serves Node (legacy build)
6
+ * and the browser worker (modern build) without bundler tricks.
7
+ */
8
+ import { CasError } from "../errors.js";
9
+ import { TextBudget } from "./budget.js";
10
+ import { DEFAULT_LIMITS, } from "./types.js";
11
+ export function createPdfjsExtractor(pdfjs, urls = {}) {
12
+ const id = `pdfjs-dist@${pdfjs.version}`;
13
+ return {
14
+ id,
15
+ async extract(bytes, options = {}) {
16
+ const limits = { ...DEFAULT_LIMITS, ...options.limits };
17
+ if (bytes.byteLength > limits.maxBytes) {
18
+ throw new CasError("FILE_TOO_LARGE", `File is ${bytes.byteLength} bytes; limit is ${limits.maxBytes}.`);
19
+ }
20
+ if (options.signal?.aborted)
21
+ throw new CasError("CANCELLED", "Cancelled before start.");
22
+ const sha256 = await sha256Hex(bytes);
23
+ // Hashing a large file takes a while; a cancel issued meanwhile counts.
24
+ if (options.signal?.aborted)
25
+ throw new CasError("CANCELLED", "Extraction cancelled.");
26
+ // pdf.js takes ownership of (transfers) typed arrays; hand it a copy so
27
+ // the caller's buffer stays usable for retries with another password.
28
+ const loadingTask = pdfjs.getDocument({
29
+ data: bytes.slice(),
30
+ password: options.password ?? "",
31
+ cMapPacked: true,
32
+ ...(urls.cMapUrl ? { cMapUrl: urls.cMapUrl } : {}),
33
+ ...(urls.standardFontDataUrl ? { standardFontDataUrl: urls.standardFontDataUrl } : {}),
34
+ ...(urls.wasmUrl ? { wasmUrl: urls.wasmUrl } : {}),
35
+ ...(urls.worker ? { worker: urls.worker() } : {}),
36
+ ...(urls.binaryDataFactory ? { BinaryDataFactory: urls.binaryDataFactory } : {}),
37
+ ...(urls.maxImageSize !== undefined ? { maxImageSize: urls.maxImageSize } : {}),
38
+ // The main thread fetches CMaps, fonts and wasm, so the worker needs no network (its CSP: connect-src 'none').
39
+ useWorkerFetch: false,
40
+ enableXfa: false,
41
+ useSystemFonts: false,
42
+ disableFontFace: true,
43
+ isOffscreenCanvasSupported: false,
44
+ stopAtErrors: false,
45
+ verbosity: 0,
46
+ });
47
+ let stopReason = null;
48
+ // Every pdf.js await is raced against this, so a cancel or timeout ends
49
+ // the extraction with its own code even when pdf.js rejects with an
50
+ // internal error after teardown, or never settles.
51
+ let rejectStop = () => undefined;
52
+ const stopped = new Promise((_, reject) => (rejectStop = reject));
53
+ stopped.catch(() => undefined);
54
+ const guard = (p) => Promise.race([p, stopped]);
55
+ const stop = (err) => {
56
+ if (!stopReason) {
57
+ stopReason = err;
58
+ rejectStop(err);
59
+ }
60
+ void loadingTask.destroy();
61
+ };
62
+ const timer = setTimeout(() => stop(new CasError("TIMEOUT", `Extraction exceeded ${limits.timeoutMs} ms.`)), limits.timeoutMs);
63
+ const onAbort = () => stop(new CasError("CANCELLED", "Extraction cancelled."));
64
+ options.signal?.addEventListener("abort", onAbort, { once: true });
65
+ let doc;
66
+ try {
67
+ try {
68
+ doc = await guard(loadingTask.promise);
69
+ }
70
+ catch (e) {
71
+ throw stopReason ?? mapOpenError(e);
72
+ }
73
+ if (doc.numPages > limits.maxPages) {
74
+ throw new CasError("TOO_MANY_PAGES", `Document has ${doc.numPages} pages; limit is ${limits.maxPages}.`);
75
+ }
76
+ options.onProgress?.({ stage: "opened", pageCount: doc.numPages });
77
+ try {
78
+ return await readPages(doc);
79
+ }
80
+ catch (e) {
81
+ throw stopReason ?? (e instanceof CasError ? e : new CasError("EXTRACTION_FAILED", "The PDF could not be read.", { cause: e }));
82
+ }
83
+ }
84
+ finally {
85
+ clearTimeout(timer);
86
+ options.signal?.removeEventListener("abort", onAbort);
87
+ // pdf.js 6 removed PDFDocumentProxy.destroy(); the loading task owns teardown.
88
+ await loadingTask.destroy().catch(() => undefined);
89
+ }
90
+ async function readPages(doc) {
91
+ const info = (await guard(doc.getMetadata())).info;
92
+ const meta = {
93
+ sha256,
94
+ byteLength: bytes.byteLength,
95
+ pageCount: doc.numPages,
96
+ producer: asString(info["Producer"]),
97
+ creator: asString(info["Creator"]),
98
+ pdfVersion: asString(info["PDFFormatVersion"]),
99
+ encrypted: Boolean(info["EncryptFilterName"]),
100
+ extractor: id,
101
+ };
102
+ const pages = [];
103
+ const budget = new TextBudget(limits, options.heap);
104
+ for (let n = 1; n <= doc.numPages; n++) {
105
+ if (stopReason)
106
+ throw stopReason;
107
+ budget.checkHeap();
108
+ const page = await guard(doc.getPage(n));
109
+ budget.startPage(n);
110
+ const content = await readText(page, budget);
111
+ const read = (rotation) => {
112
+ const viewport = page.getViewport({ scale: 1, rotation });
113
+ const items = [];
114
+ for (const raw of content.items) {
115
+ if (typeof raw["str"] !== "string")
116
+ continue; // marked-content markers
117
+ items.push(toRawItem(pdfjs, raw, viewport.transform, content.styles, n, items.length));
118
+ }
119
+ return { rotation, viewport, items, share: horizontalShare(items) };
120
+ };
121
+ // A page rotated in a viewer and re-saved has /Rotate set on upright
122
+ // content, so its body text runs vertically. Read it at the rotation
123
+ // where most text runs left to right (PLAN.md §5.1: normalise
124
+ // rotation first).
125
+ let best = read(page.rotate);
126
+ if (best.share < 0.5) {
127
+ for (const turn of [90, 180, 270]) {
128
+ const alt = read((page.rotate + turn) % 360);
129
+ if (alt.share > best.share)
130
+ best = alt;
131
+ }
132
+ }
133
+ const { viewport, items } = best;
134
+ pages.push({
135
+ number: n, width: viewport.width, height: viewport.height, rotation: page.rotate, items,
136
+ ...(best.rotation !== page.rotate ? { textRotation: best.rotation } : {}),
137
+ });
138
+ page.cleanup();
139
+ options.onProgress?.({ stage: "page", page: n, pageCount: doc.numPages });
140
+ }
141
+ if (stopReason)
142
+ throw stopReason;
143
+ return { meta, pages };
144
+ }
145
+ /**
146
+ * One page's text, chunk by chunk, so the memory guard can stop a huge
147
+ * page part-way (pdf.js applies back-pressure, so the worker pauses
148
+ * while chunks wait). A breach cancels the stream and ends the
149
+ * extraction with TOO_MUCH_TEXT.
150
+ */
151
+ async function readText(page, budget) {
152
+ const params = { includeMarkedContent: false, disableNormalization: false };
153
+ if (typeof page.streamTextContent !== "function") {
154
+ const content = await guard(page.getTextContent(params));
155
+ budget.add(content.items);
156
+ return content;
157
+ }
158
+ const reader = page.streamTextContent(params).getReader();
159
+ const items = [];
160
+ const styles = Object.create(null);
161
+ try {
162
+ for (;;) {
163
+ const { value, done } = await guard(reader.read());
164
+ if (done)
165
+ break;
166
+ budget.add(value.items);
167
+ Object.assign(styles, value.styles);
168
+ for (const item of value.items)
169
+ items.push(item);
170
+ }
171
+ }
172
+ catch (e) {
173
+ // pdf.js asserts that a cancel carries an Error.
174
+ reader.cancel(e instanceof Error ? e : new Error(String(e))).catch(() => undefined);
175
+ throw e;
176
+ }
177
+ return { items, styles };
178
+ }
179
+ },
180
+ };
181
+ }
182
+ function toRawItem(pdfjs, raw, viewportTransform, styles, page, index) {
183
+ const t = raw["transform"].slice(0, 6);
184
+ const m = pdfjs.Util.transform(viewportTransform, t);
185
+ // Advance vector (a, b) and its unit direction in device space.
186
+ const advLen = Math.hypot(m[0], m[1]) || 1;
187
+ const ux = m[0] / advLen;
188
+ const uy = m[1] / advLen;
189
+ const width = Number(raw["width"]) || 0;
190
+ const x0 = m[4];
191
+ const x1 = x0 + width * ux;
192
+ const fontKey = String(raw["fontName"] ?? "");
193
+ const dir = raw["dir"] === "rtl" || raw["dir"] === "ttb" ? raw["dir"] : "ltr";
194
+ return {
195
+ page,
196
+ index,
197
+ str: raw["str"],
198
+ x0: round(Math.min(x0, x1)),
199
+ x1: round(Math.max(x0, x1)),
200
+ y: round(m[5]),
201
+ fontSize: round(Math.hypot(m[2], m[3])),
202
+ fontKey,
203
+ fontFamily: styles[fontKey]?.fontFamily ?? null,
204
+ dir,
205
+ // Horizontal, left-to-right after page rotation is applied.
206
+ horizontal: ux > 0.99 && Math.abs(uy) < 0.1,
207
+ transform: t,
208
+ hasEOL: raw["hasEOL"] === true,
209
+ };
210
+ }
211
+ /** Share of visible items that run left to right; 1 for a page without text. */
212
+ function horizontalShare(items) {
213
+ const visible = items.filter((i) => i.str.trim() !== "");
214
+ return visible.length ? visible.filter((i) => i.horizontal).length / visible.length : 1;
215
+ }
216
+ function mapOpenError(e) {
217
+ const err = e;
218
+ if (err?.name === "PasswordException") {
219
+ // pdf.js PasswordResponses: 1 = NEED_PASSWORD, 2 = INCORRECT_PASSWORD.
220
+ return err.code === 2
221
+ ? new CasError("INCORRECT_PASSWORD", "The password is incorrect.", { cause: e })
222
+ : new CasError("NEED_PASSWORD", "This PDF needs a password.", { cause: e });
223
+ }
224
+ const msg = err?.message ?? "";
225
+ if (/encrypt/i.test(msg)) {
226
+ return new CasError("UNSUPPORTED_ENCRYPTION", "This PDF uses an encryption method we can't open.", { cause: e });
227
+ }
228
+ if (err?.name === "InvalidPDFException" || err?.name === "FormatError") {
229
+ return new CasError("DAMAGED_FILE", "This file isn't a readable PDF.", { cause: e });
230
+ }
231
+ return new CasError("EXTRACTION_FAILED", "The PDF could not be read.", { cause: e });
232
+ }
233
+ async function sha256Hex(bytes) {
234
+ // WebCrypto rejects views over SharedArrayBuffer; copy only in that case.
235
+ const view = bytes.buffer instanceof ArrayBuffer ? bytes : new Uint8Array(bytes);
236
+ const digest = await globalThis.crypto.subtle.digest("SHA-256", view);
237
+ return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
238
+ }
239
+ function asString(v) {
240
+ return typeof v === "string" && v.length > 0 ? v : null;
241
+ }
242
+ function round(n) {
243
+ return Math.round(n * 1000) / 1000;
244
+ }
@@ -0,0 +1,106 @@
1
+ /**
2
+ * Extraction output. Backend-neutral so a PDFium-WASM extractor can replace
3
+ * pdf.js behind the same interface if the M1 spike demands it (PLAN.md §5.1).
4
+ *
5
+ * Coordinates are normalised device space at scale 1: origin top-left of the
6
+ * page's crop box after /Rotate (or `textRotation`) is applied, x to the right,
7
+ * y downwards.
8
+ * `y` is the text baseline.
9
+ */
10
+ import type { HeapProbe } from "./budget.js";
11
+ export interface RawItem {
12
+ /** 1-based page number. */
13
+ page: number;
14
+ /** Index of the item within its page, in extractor order. */
15
+ index: number;
16
+ str: string;
17
+ x0: number;
18
+ x1: number;
19
+ /** Baseline y (top-down). */
20
+ y: number;
21
+ /** Approximate glyph height (font size in device space). */
22
+ fontSize: number;
23
+ /** Extractor-internal font key. Only valid for equality within one document. */
24
+ fontKey: string;
25
+ /** Font family hint from the extractor, if any. Not the PDF BaseFont. */
26
+ fontFamily: string | null;
27
+ /** Writing direction as reported by the extractor. */
28
+ dir: "ltr" | "rtl" | "ttb";
29
+ /** Advance direction after normalisation: true when text runs left-to-right horizontally. */
30
+ horizontal: boolean;
31
+ /** Raw 6-element text matrix in PDF user space, kept for later re-analysis. */
32
+ transform: [number, number, number, number, number, number];
33
+ hasEOL: boolean;
34
+ }
35
+ export interface RawPage {
36
+ number: number;
37
+ width: number;
38
+ height: number;
39
+ /** Page /Rotate value in degrees. */
40
+ rotation: number;
41
+ /**
42
+ * Set when the text was read at a rotation other than /Rotate: a page
43
+ * rotated in a viewer and re-saved, whose text would otherwise run
44
+ * vertically. Coordinates are for this rotation.
45
+ */
46
+ textRotation?: number;
47
+ items: RawItem[];
48
+ }
49
+ export interface DocumentMeta {
50
+ sha256: string;
51
+ byteLength: number;
52
+ pageCount: number;
53
+ producer: string | null;
54
+ creator: string | null;
55
+ pdfVersion: string | null;
56
+ encrypted: boolean;
57
+ /** Extractor backend id + version, e.g. "pdfjs-dist@6.3.289". */
58
+ extractor: string;
59
+ }
60
+ export interface ExtractedDocument {
61
+ meta: DocumentMeta;
62
+ pages: RawPage[];
63
+ }
64
+ export interface ExtractLimits {
65
+ maxBytes: number;
66
+ maxPages: number;
67
+ /** Total text items across the document. */
68
+ maxItems: number;
69
+ /** Text items on one page (memory guard, extract/budget.ts). */
70
+ maxPageItems: number;
71
+ /** Estimated bytes of one page's extracted text (memory guard). */
72
+ maxPageTextBytes: number;
73
+ /** Estimated bytes of the whole document's extracted text (memory guard). */
74
+ maxTextBytes: number;
75
+ /** Stop when ExtractOptions.heap reports more than this share of the JS heap limit (0–1). */
76
+ maxHeapShare: number;
77
+ /** Wall-clock budget for the whole extraction. */
78
+ timeoutMs: number;
79
+ }
80
+ export declare const DEFAULT_LIMITS: ExtractLimits;
81
+ /** A real extraction event, for a progress display that never runs ahead of the work. */
82
+ export type ExtractProgress = {
83
+ stage: "opened";
84
+ pageCount: number;
85
+ } | {
86
+ stage: "page";
87
+ page: number;
88
+ pageCount: number;
89
+ };
90
+ export interface ExtractOptions {
91
+ password?: string;
92
+ limits?: Partial<ExtractLimits>;
93
+ signal?: AbortSignal;
94
+ /**
95
+ * Reads the host's JS heap (browser: `performance.memory` where it exists).
96
+ * Checked as text arrives; past `limits.maxHeapShare` extraction stops with
97
+ * TOO_MUCH_TEXT.
98
+ */
99
+ heap?: HeapProbe;
100
+ /** Called after the file opens (decrypted) and after each page is read. */
101
+ onProgress?: (p: ExtractProgress) => void;
102
+ }
103
+ export interface Extractor {
104
+ readonly id: string;
105
+ extract(bytes: Uint8Array, options?: ExtractOptions): Promise<ExtractedDocument>;
106
+ }
@@ -0,0 +1,11 @@
1
+ export const DEFAULT_LIMITS = {
2
+ maxBytes: 25 * 1024 * 1024,
3
+ maxPages: 300,
4
+ maxItems: 400_000,
5
+ // A real CAS page holds a few hundred items; these stop text bombs early.
6
+ maxPageItems: 50_000,
7
+ maxPageTextBytes: 16 * 1024 * 1024,
8
+ maxTextBytes: 96 * 1024 * 1024,
9
+ maxHeapShare: 0.8,
10
+ timeoutMs: 30_000,
11
+ };
@@ -0,0 +1,27 @@
1
+ export { CasError, CAS_ERRORS, isCasError, type CasErrorCode } from "./errors.js";
2
+ export { detect, type Detection, type Issuer, type Variant } from "./detect.js";
3
+ export { createPdfjsExtractor, type PdfjsModule, type PdfjsResourceUrls } from "./extract/pdfjs.js";
4
+ export { estimateItemBytes, TextBudget, type HeapProbe, type HeapReading, type TextBudgetLimits } from "./extract/budget.js";
5
+ export { DEFAULT_LIMITS, type DocumentMeta, type ExtractedDocument, type ExtractLimits, type ExtractOptions, type ExtractProgress, type Extractor, type RawItem, type RawPage, } from "./extract/types.js";
6
+ export { parseCas } from "./parse.js";
7
+ export { depositoryDate, placeByArithmetic } from "./parsers/depository/mf.js";
8
+ export { APP_CODE_PREFIX, SACHFOLIO_PUBLIC_KEYS, checkAppLicence, checkAppPayload, mintAppLicence, todayInIndia as licenceToday, type AppLicencePayload, type AppLicenceStatus, type AppPlan, } from "./licence/app-licence.js";
9
+ export { ed25519Verify } from "./licence/ed25519.js";
10
+ export { CASPARSER_TXN_TYPE, toCasparser, toCasparserDemat, type CasparserDematAccount, type CasparserDematData, type CasparserDematMutualFund, type CasparserCasData, type CasparserDecimal, type CasparserFolio, type CasparserOptions, type CasparserScheme, type CasparserTransaction, type CasparserTxnType, } from "./compat/casparser.js";
11
+ export { toHoldingsCsv, toTransactionsCsv, HOLDINGS_CSV_HEADER, TRANSACTIONS_CSV_HEADER } from "./export/csv.js";
12
+ export { ENGINE_VERSION } from "./parsers/cams/detailed.js";
13
+ export type * from "./model.js";
14
+ export { parseNum, type Num } from "./num.js";
15
+ export { PURCHASE_TYPES } from "./checks.js";
16
+ export { CAS_DOCUMENT_SCHEMA_ID, casDocumentJsonSchema, casDocumentSchema, validateCasDocument, type CasDocumentValidation, type SchemaIssue, } from "./schema.js";
17
+ export { analyze, ANALYTICS_VERSION, holdingsEligibility, schemeXirrEligibility, outflowBreakdowns, type Analytics, type Eligibility, type OutflowBreakdown, type SchemeAnalytics } from "./analytics/eligibility.js";
18
+ export { isValidIsin } from "./checks.js";
19
+ export { annotatePrivacy, privacyInventory, PRIVACY, redactCas, type FieldPrivacy, type PrivacyClass, type PrivacyMapName, type RedactedCasDocument, type RedactedCheck, type RedactedFolio, type RedactedNum, type RedactedScheme, type RedactedTransaction, } from "./privacy.js";
20
+ export { checkWhy, evaluatePredicate, evaluateRequires, project, type AnalysisManifest, type AnalysisModule, type Consumes, type EligibilityState, type EvidenceRef, type LedgerView, type ModuleEligibility, type ModuleReport, type PredicateCode, type PredicateId, type Reason, type RegClass, type SchemeView, } from "./analytics/contract.js";
21
+ export { MODULES, moduleReports, holdingsModule, coverageModule, observationsModule, type HoldingsOutput } from "./analytics/modules.js";
22
+ export { returns, returnsFromView, schemeReturnsEligibility, xirrModule, XIRR_MANIFEST, type Flow, type FlowExclusionCode, type FlowRole, type FlowTotals, type MatchedTransfer, type PortfolioFlow, type PortfolioReturns, type ReturnsAnalysis, type ReturnsReasonCode, type SchemeReturns, type TransferLeg, type UnmatchedTransfer, type XirrResult, } from "./analytics/returns.js";
23
+ export { solveXirr, daysBetween, type DatedFlow, type SolveResult, type SolverFailure } from "./analytics/xirr.js";
24
+ export { returnsAnalysisSchema, returnsJsonSchema, validateReturnsAnalysis, XIRR_SCHEMA_ID } from "./analytics/returns-schema.js";
25
+ export { gainsOutputSchema, gainsJsonSchema, validateGainsOutput, GAINS_SCHEMA_ID } from "./analytics/gains-schema.js";
26
+ export { gains, gainsModule, GAINS_MANIFEST, fmv2018FromPack, termOf, addMonths, financialYear, windowAmount, type Bucket, type FundType, type FundTypeBasis, type GainsOptions, type GainsOutput, type GainsReasonCode, type Grandfathering, type LotFlag, type MergerStep, type Nav2018Pack, type OpenLot, type RealisedLot, type RuleCode, type SaleNote, type SchemeGains, type QuarterTotals, type Term, type YearTotals, } from "./analytics/gains.js";
27
+ export { schedule112A, schedule112ACells, years112A, quarterlyGains, quarterOf, rupees, QUARTERS, HEADER_112A, CONSOLIDATED_ISIN, CONSOLIDATED_NAME, type LotRef, type Quarter, type QuarterlyRow, type Row112A, type Schedule112A, } from "./analytics/schedule112a.js";
package/dist/index.js ADDED
@@ -0,0 +1,26 @@
1
+ export { CasError, CAS_ERRORS, isCasError } from "./errors.js";
2
+ export { detect } from "./detect.js";
3
+ export { createPdfjsExtractor } from "./extract/pdfjs.js";
4
+ export { estimateItemBytes, TextBudget } from "./extract/budget.js";
5
+ export { DEFAULT_LIMITS, } from "./extract/types.js";
6
+ export { parseCas } from "./parse.js";
7
+ export { depositoryDate, placeByArithmetic } from "./parsers/depository/mf.js";
8
+ export { APP_CODE_PREFIX, SACHFOLIO_PUBLIC_KEYS, checkAppLicence, checkAppPayload, mintAppLicence, todayInIndia as licenceToday, } from "./licence/app-licence.js";
9
+ export { ed25519Verify } from "./licence/ed25519.js";
10
+ export { CASPARSER_TXN_TYPE, toCasparser, toCasparserDemat, } from "./compat/casparser.js";
11
+ export { toHoldingsCsv, toTransactionsCsv, HOLDINGS_CSV_HEADER, TRANSACTIONS_CSV_HEADER } from "./export/csv.js";
12
+ export { ENGINE_VERSION } from "./parsers/cams/detailed.js";
13
+ export { parseNum } from "./num.js";
14
+ export { PURCHASE_TYPES } from "./checks.js";
15
+ export { CAS_DOCUMENT_SCHEMA_ID, casDocumentJsonSchema, casDocumentSchema, validateCasDocument, } from "./schema.js";
16
+ export { analyze, ANALYTICS_VERSION, holdingsEligibility, schemeXirrEligibility, outflowBreakdowns } from "./analytics/eligibility.js";
17
+ export { isValidIsin } from "./checks.js";
18
+ export { annotatePrivacy, privacyInventory, PRIVACY, redactCas, } from "./privacy.js";
19
+ export { checkWhy, evaluatePredicate, evaluateRequires, project, } from "./analytics/contract.js";
20
+ export { MODULES, moduleReports, holdingsModule, coverageModule, observationsModule } from "./analytics/modules.js";
21
+ export { returns, returnsFromView, schemeReturnsEligibility, xirrModule, XIRR_MANIFEST, } from "./analytics/returns.js";
22
+ export { solveXirr, daysBetween } from "./analytics/xirr.js";
23
+ export { returnsAnalysisSchema, returnsJsonSchema, validateReturnsAnalysis, XIRR_SCHEMA_ID } from "./analytics/returns-schema.js";
24
+ export { gainsOutputSchema, gainsJsonSchema, validateGainsOutput, GAINS_SCHEMA_ID } from "./analytics/gains-schema.js";
25
+ export { gains, gainsModule, GAINS_MANIFEST, fmv2018FromPack, termOf, addMonths, financialYear, windowAmount, } from "./analytics/gains.js";
26
+ export { schedule112A, schedule112ACells, years112A, quarterlyGains, quarterOf, rupees, QUARTERS, HEADER_112A, CONSOLIDATED_ISIN, CONSOLIDATED_NAME, } from "./analytics/schedule112a.js";
@@ -0,0 +1,51 @@
1
+ /**
2
+ * Page cleanup + line clustering over extractor items (PLAN.md §5.1).
3
+ *
4
+ * Every removed item is recorded with a reason, so coverage accounting and
5
+ * debugging can see exactly what was set aside.
6
+ */
7
+ import type { RawItem, RawPage } from "../extract/types.js";
8
+ export type SuppressionReason = "whitespace" | "watermark" | "non_horizontal" | "devanagari" | "overlay_twin";
9
+ /** The CAMS / KFintech watermark (detect.ts reads it before cleanup). */
10
+ export declare const WATERMARK_RE: RegExp;
11
+ export interface CleanOptions {
12
+ /**
13
+ * How to treat two overlapping same-font items a fraction of a point apart.
14
+ * - "same-text" (default): only exact duplicates are removed.
15
+ * In both modes the same text drawn twice at one spot (an overprint or fake
16
+ * bold) is removed, whatever the font: casparser `pageobj.py` drops such
17
+ * repeats too.
18
+ * - "any-text": the KFintech date twin. KFin draws a ghost of the previous
19
+ * row's date ~0.7pt above each row's real date. The item farther from the
20
+ * row's median baseline is removed (casparser `extract.py` rule). Only
21
+ * enabled for issuers whose fixtures show the pattern (docs/M1-SPIKE.md).
22
+ */
23
+ overlayTwins?: "same-text" | "any-text";
24
+ }
25
+ export interface Suppression {
26
+ item: RawItem;
27
+ reason: SuppressionReason;
28
+ }
29
+ export interface Line {
30
+ page: number;
31
+ /** Mean baseline y (top-down) of the items on the line. */
32
+ y: number;
33
+ /** Items sorted left to right. */
34
+ items: RawItem[];
35
+ }
36
+ export interface CleanPage {
37
+ number: number;
38
+ lines: Line[];
39
+ suppressed: Suppression[];
40
+ }
41
+ /** Baseline tolerance for one visual line, in points (casparser uses 1.5). */
42
+ export declare const LINE_Y_TOL = 1.5;
43
+ export declare function cleanPage(page: RawPage, options?: CleanOptions): CleanPage;
44
+ export declare function clusterLines(items: RawItem[], page: number): Line[];
45
+ /**
46
+ * Visible characters of rotated text other than the watermark: body text the
47
+ * page lost to cleanup. A page rotated and re-saved is normalised by the
48
+ * extractor; this measures what is left (e.g. a rotated table).
49
+ */
50
+ export declare function rotatedTextChars(page: CleanPage): number;
51
+ export declare function lineText(line: Line): string;
@@ -0,0 +1,115 @@
1
+ /** The CAMS / KFintech watermark (detect.ts reads it before cleanup). */
2
+ export const WATERMARK_RE = /CAMSCASWS|KFINCASWS/;
3
+ // Overlay geometry, from casparser `extract.py` (MIT).
4
+ const OVERLAY_ROW_TOL = 3.0;
5
+ const OVERLAY_MIN_DY = 0.05;
6
+ const OVERLAY_MIN_X_FRAC = 0.5;
7
+ /** Baseline tolerance for one visual line, in points (casparser uses 1.5). */
8
+ export const LINE_Y_TOL = 1.5;
9
+ const DEVANAGARI_RE = /[ऀ-ॿ]/g;
10
+ export function cleanPage(page, options = {}) {
11
+ const kept = [];
12
+ const suppressed = [];
13
+ for (const item of page.items) {
14
+ if (item.str.trim() === "")
15
+ suppressed.push({ item, reason: "whitespace" });
16
+ // Rotated text. The CAMS/KFin watermark is expected and detection has
17
+ // already read it. Other rotated text can't be laid out in lines; callers
18
+ // warn about it (rotatedTextChars).
19
+ else if (!item.horizontal)
20
+ suppressed.push({ item, reason: WATERMARK_RE.test(item.str) ? "watermark" : "non_horizontal" });
21
+ // Hindi overlay text on depository statements. Only items that are mostly
22
+ // Devanagari; v0.1 parses CAMS/KFin, where this never fires.
23
+ else if ((item.str.match(DEVANAGARI_RE)?.length ?? 0) > item.str.length / 2)
24
+ suppressed.push({ item, reason: "devanagari" });
25
+ else
26
+ kept.push(item);
27
+ }
28
+ const twins = findOverlayTwins(kept, options.overlayTwins ?? "same-text");
29
+ for (const item of twins)
30
+ suppressed.push({ item, reason: "overlay_twin" });
31
+ const survivors = twins.size ? kept.filter((i) => !twins.has(i)) : kept;
32
+ return { number: page.number, lines: clusterLines(survivors, page.number), suppressed };
33
+ }
34
+ /**
35
+ * Pairs of same-font items whose x-ranges overlap by ≥50% of the narrower one
36
+ * and whose baselines differ by (0.05, 3] pt. Returns the member of each pair
37
+ * farther from its row band's median baseline. Pairs under 0.05pt apart are
38
+ * repeats of one spot: only identical text is removed (the later item).
39
+ */
40
+ function findOverlayTwins(items, mode) {
41
+ const drop = new Set();
42
+ const sorted = [...items].sort((a, b) => a.y - b.y);
43
+ const bands = [];
44
+ for (const it of sorted) {
45
+ const band = bands[bands.length - 1];
46
+ if (band && it.y - band[0].y <= OVERLAY_ROW_TOL)
47
+ band.push(it);
48
+ else
49
+ bands.push([it]);
50
+ }
51
+ for (const band of bands) {
52
+ if (band.length < 2)
53
+ continue;
54
+ const ys = band.map((i) => i.y).sort((a, b) => a - b);
55
+ const median = ys[Math.floor(ys.length / 2)];
56
+ for (let i = 0; i < band.length; i++) {
57
+ const a = band[i];
58
+ if (drop.has(a))
59
+ continue;
60
+ for (let j = i + 1; j < band.length; j++) {
61
+ const b = band[j];
62
+ if (drop.has(b))
63
+ continue;
64
+ const overlap = Math.min(a.x1, b.x1) - Math.max(a.x0, b.x0);
65
+ const narrower = Math.min(a.x1 - a.x0, b.x1 - b.x0);
66
+ if (overlap <= 0 || narrower <= 0 || overlap / narrower < OVERLAY_MIN_X_FRAC)
67
+ continue;
68
+ const sameText = a.str.trim() === b.str.trim();
69
+ const dy = Math.abs(a.y - b.y);
70
+ if (dy < OVERLAY_MIN_DY) {
71
+ // Kept, both copies would land in one cell and "999.95 999.95" reads as no number.
72
+ if (sameText)
73
+ drop.add(b);
74
+ continue;
75
+ }
76
+ if (dy > OVERLAY_ROW_TOL || a.fontKey !== b.fontKey)
77
+ continue;
78
+ if (mode === "same-text" && !sameText)
79
+ continue;
80
+ drop.add(Math.abs(a.y - median) > Math.abs(b.y - median) ? a : b);
81
+ if (drop.has(a))
82
+ break;
83
+ }
84
+ }
85
+ }
86
+ return drop;
87
+ }
88
+ export function clusterLines(items, page) {
89
+ const sorted = [...items].sort((a, b) => a.y - b.y || a.x0 - b.x0);
90
+ const lines = [];
91
+ for (const item of sorted) {
92
+ const last = lines[lines.length - 1];
93
+ if (last && Math.abs(item.y - last.y) <= LINE_Y_TOL) {
94
+ last.items.push(item);
95
+ last.y = last.items.reduce((s, i) => s + i.y, 0) / last.items.length;
96
+ }
97
+ else {
98
+ lines.push({ page, y: item.y, items: [item] });
99
+ }
100
+ }
101
+ for (const line of lines)
102
+ line.items.sort((a, b) => a.x0 - b.x0);
103
+ return lines;
104
+ }
105
+ /**
106
+ * Visible characters of rotated text other than the watermark: body text the
107
+ * page lost to cleanup. A page rotated and re-saved is normalised by the
108
+ * extractor; this measures what is left (e.g. a rotated table).
109
+ */
110
+ export function rotatedTextChars(page) {
111
+ return page.suppressed.filter((s) => s.reason === "non_horizontal").reduce((n, s) => n + s.item.str.replace(/\s/g, "").length, 0);
112
+ }
113
+ export function lineText(line) {
114
+ return line.items.map((i) => i.str).join(" ");
115
+ }
@@ -0,0 +1,53 @@
1
+ export declare const APP_CODE_PREFIX = "SF1";
2
+ /** Public keys that sign Sachfolio licence codes: base64url of the raw 32-byte Ed25519 key. */
3
+ export declare const SACHFOLIO_PUBLIC_KEYS: Readonly<Record<string, string>>;
4
+ export type AppPlan = "app-year" | "evaluation";
5
+ export interface AppLicencePayload {
6
+ v: 1;
7
+ /** Signing key id. */
8
+ k: string;
9
+ /** Licence id, "L" + 10 hex characters. */
10
+ id: string;
11
+ p: "cas-reader";
12
+ plan: AppPlan;
13
+ /** The licensee as named on the order. */
14
+ org: string;
15
+ /** The app the licence covers: a domain ("example.com") or an app id ("com.example.app"). */
16
+ app: string;
17
+ /** First and last day it covers, ISO dates, inclusive (India time). */
18
+ from: string;
19
+ to: string;
20
+ }
21
+ export type AppLicenceStatus = {
22
+ status: "valid";
23
+ licence: AppLicencePayload;
24
+ } | {
25
+ status: "expired" | "not-started";
26
+ licence: AppLicencePayload;
27
+ }
28
+ /** Not a code, changed after signing, or signed with a key this version doesn't know. */
29
+ | {
30
+ status: "invalid" | "unknown-key" | "unsupported";
31
+ }
32
+ /** This runtime has no Web Crypto (an insecure browser page). */
33
+ | {
34
+ status: "unchecked";
35
+ };
36
+ /** Today's date in India, as an ISO date. */
37
+ export declare function todayInIndia(now?: Date): string;
38
+ export declare function checkAppPayload(x: unknown): AppLicencePayload | null;
39
+ /**
40
+ * Checks an app licence code offline. Never throws for a bad code, and never
41
+ * affects reading: show the result in your admin screen or logs if you like.
42
+ */
43
+ export declare function checkAppLicence(code: string, options?: {
44
+ today?: string;
45
+ keys?: Readonly<Record<string, string>>;
46
+ }): Promise<AppLicenceStatus>;
47
+ /** Makes a code. Only the minting tool calls this, with the private key. */
48
+ export declare function mintAppLicence(input: Omit<AppLicencePayload, "v" | "p" | "id"> & {
49
+ id?: string;
50
+ }, privateKey: CryptoKey): Promise<{
51
+ code: string;
52
+ payload: AppLicencePayload;
53
+ }>;