@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.
- package/CHANGELOG.md +19 -0
- package/LICENSE +71 -0
- package/NOTICE +41 -0
- package/README.md +198 -2
- package/dist/analytics/contract.d.ts +110 -0
- package/dist/analytics/contract.js +79 -0
- package/dist/analytics/eligibility.d.ts +66 -0
- package/dist/analytics/eligibility.js +93 -0
- package/dist/analytics/gains-schema.d.ts +898 -0
- package/dist/analytics/gains-schema.js +170 -0
- package/dist/analytics/gains.d.ts +319 -0
- package/dist/analytics/gains.js +649 -0
- package/dist/analytics/modules.d.ts +33 -0
- package/dist/analytics/modules.js +74 -0
- package/dist/analytics/returns-schema.d.ts +931 -0
- package/dist/analytics/returns-schema.js +152 -0
- package/dist/analytics/returns.d.ts +126 -0
- package/dist/analytics/returns.js +453 -0
- package/dist/analytics/schedule112a.d.ts +77 -0
- package/dist/analytics/schedule112a.js +134 -0
- package/dist/analytics/xirr.d.ts +75 -0
- package/dist/analytics/xirr.js +314 -0
- package/dist/bin/cas.d.ts +2 -0
- package/dist/bin/cas.js +137 -0
- package/dist/checks.d.ts +49 -0
- package/dist/checks.js +227 -0
- package/dist/compat/casparser.d.ts +121 -0
- package/dist/compat/casparser.js +193 -0
- package/dist/detect.d.ts +10 -0
- package/dist/detect.js +69 -0
- package/dist/errors.d.ts +26 -0
- package/dist/errors.js +95 -0
- package/dist/export/csv.d.ts +21 -0
- package/dist/export/csv.js +49 -0
- package/dist/extract/browser.d.ts +17 -0
- package/dist/extract/browser.js +34 -0
- package/dist/extract/budget.d.ts +46 -0
- package/dist/extract/budget.js +88 -0
- package/dist/extract/node.d.ts +11 -0
- package/dist/extract/node.js +31 -0
- package/dist/extract/pdfjs.d.ts +71 -0
- package/dist/extract/pdfjs.js +244 -0
- package/dist/extract/types.d.ts +106 -0
- package/dist/extract/types.js +11 -0
- package/dist/index.d.ts +27 -0
- package/dist/index.js +26 -0
- package/dist/layout/lines.d.ts +51 -0
- package/dist/layout/lines.js +115 -0
- package/dist/licence/app-licence.d.ts +53 -0
- package/dist/licence/app-licence.js +139 -0
- package/dist/licence/ed25519.d.ts +2 -0
- package/dist/licence/ed25519.js +103 -0
- package/dist/model.d.ts +148 -0
- package/dist/model.js +1 -0
- package/dist/num.d.ts +19 -0
- package/dist/num.js +27 -0
- package/dist/parse.d.ts +4 -0
- package/dist/parse.js +13 -0
- package/dist/parsers/cams/classify.d.ts +25 -0
- package/dist/parsers/cams/classify.js +103 -0
- package/dist/parsers/cams/detailed.d.ts +15 -0
- package/dist/parsers/cams/detailed.js +343 -0
- package/dist/parsers/cams/header.d.ts +47 -0
- package/dist/parsers/cams/header.js +170 -0
- package/dist/parsers/cams/investor.d.ts +28 -0
- package/dist/parsers/cams/investor.js +139 -0
- package/dist/parsers/cams/summary.d.ts +29 -0
- package/dist/parsers/cams/summary.js +413 -0
- package/dist/parsers/cams/table.d.ts +55 -0
- package/dist/parsers/cams/table.js +144 -0
- package/dist/parsers/cams/total.d.ts +17 -0
- package/dist/parsers/cams/total.js +105 -0
- package/dist/parsers/depository/mf.d.ts +22 -0
- package/dist/parsers/depository/mf.js +438 -0
- package/dist/privacy.d.ts +243 -0
- package/dist/privacy.js +256 -0
- package/dist/schema.d.ts +779 -0
- package/dist/schema.js +214 -0
- package/examples/nextjs/app/page.jsx +34 -0
- package/examples/node/server.mjs +45 -0
- package/examples/python/read_cas.py +67 -0
- package/examples/vite/index.html +14 -0
- package/examples/vite/main.js +22 -0
- package/package.json +54 -4
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* xirr@1 output (ReturnsAnalysis, analytics/returns.ts) as a runtime schema,
|
|
3
|
+
* mirroring the types the way schema.ts mirrors CasDocument. Generates the
|
|
4
|
+
* committed schema/xirr.v1.schema.json (npm run schema). Analytics are a
|
|
5
|
+
* separate, versioned object (PLAN.md §5.5), so this is its own schema, not
|
|
6
|
+
* part of CasDocument v1. The guards at the bottom fail the typecheck when
|
|
7
|
+
* the two drift apart.
|
|
8
|
+
*/
|
|
9
|
+
import * as z from "zod";
|
|
10
|
+
import { isoDateSchema, sourceSchema, txnTypeSchema } from "../schema.js";
|
|
11
|
+
z.config({ jitless: true });
|
|
12
|
+
export const XIRR_SCHEMA_ID = "urn:foliolens:schema:xirr:v1";
|
|
13
|
+
const DECIMAL_RE = /^-?\d+(?:\.\d+)?$/;
|
|
14
|
+
export const decimal = (d) => z.string().regex(DECIMAL_RE, 'must be a canonical decimal string, e.g. "-1234.50"').describe(d);
|
|
15
|
+
export const rupees = (d) => z.string().regex(/^-?\d+\.\d{2}$/, "must be a decimal string with 2 places").describe(d);
|
|
16
|
+
export const count = z.int().min(0);
|
|
17
|
+
const eligibilityStateSchema = z
|
|
18
|
+
.enum(["eligible", "partial", "not_available"])
|
|
19
|
+
.meta({ id: "EligibilityState", description: "eligible: computed from complete evidence. partial: some items left out, each listed. not_available: the statement lacks the evidence; reasons say why." });
|
|
20
|
+
export const evidenceRefSchema = z
|
|
21
|
+
.strictObject({
|
|
22
|
+
folio: z.string().describe("Folio number as printed."),
|
|
23
|
+
rtaCode: z.string().describe("The scheme's registrar code."),
|
|
24
|
+
order: z.exactOptional(count.describe("Transaction.order of the row, when the reason is about one row.")),
|
|
25
|
+
source: z.exactOptional(sourceSchema),
|
|
26
|
+
})
|
|
27
|
+
.meta({ id: "EvidenceRef", description: "The scheme, and optionally the row, a reason is about." });
|
|
28
|
+
export const reasonSchema = z
|
|
29
|
+
.strictObject({
|
|
30
|
+
code: z.string().describe("Machine-readable reason code (docs/SPEC-metrics.md lists them). The app maps codes to its own copy."),
|
|
31
|
+
text: z.string().describe("The engine's plain-language wording."),
|
|
32
|
+
ref: z.exactOptional(evidenceRefSchema),
|
|
33
|
+
})
|
|
34
|
+
.meta({ id: "Reason", description: "Why something is not available or was left out." });
|
|
35
|
+
const moduleEligibilitySchema = z
|
|
36
|
+
.strictObject({ state: eligibilityStateSchema, reasons: z.array(reasonSchema).describe("Empty when eligible.") })
|
|
37
|
+
.meta({ id: "ModuleEligibility", description: "Three-state eligibility of an analysis (analysis contract)." });
|
|
38
|
+
const flowShape = {
|
|
39
|
+
order: count.nullable().describe("Transaction.order of the row; null for the terminal value."),
|
|
40
|
+
date: isoDateSchema,
|
|
41
|
+
type: z.union([txnTypeSchema, z.literal("TERMINAL_VALUE")]).describe("The row's type, or TERMINAL_VALUE for the closing market value."),
|
|
42
|
+
included: z.boolean().describe("Whether the row is a cash flow in the rate."),
|
|
43
|
+
amount: rupees('Signed rupees, investor\'s view: negative = paid in, positive = received or held. "0.00" when excluded.'),
|
|
44
|
+
role: z
|
|
45
|
+
.enum(["purchase", "switch_in", "stamp_duty", "redemption", "switch_out", "idcw_payout", "tds_withheld", "reversal", "terminal_value"])
|
|
46
|
+
.nullable()
|
|
47
|
+
.describe("What the flow is; null when excluded."),
|
|
48
|
+
exclusion: z
|
|
49
|
+
.enum(["idcw_reinvested", "stamp_on_reinvestment", "stt_inside_amount", "tds_inside_amount", "informational_row", "lien_only", "not_supported"])
|
|
50
|
+
.nullable()
|
|
51
|
+
.describe("Why the row carries no flow; null when included."),
|
|
52
|
+
parentOrder: count.nullable().describe("For stamp duty, STT and TDS: the row they were attached to."),
|
|
53
|
+
source: sourceSchema.nullable(),
|
|
54
|
+
};
|
|
55
|
+
const flowSchema = z.strictObject(flowShape).meta({ id: "Flow", description: "One row of a scheme under the cash-flow policy, included or excluded." });
|
|
56
|
+
const portfolioFlowSchema = z
|
|
57
|
+
.strictObject({ ...flowShape, folio: z.string(), rtaCode: z.string() })
|
|
58
|
+
.meta({ id: "PortfolioFlow", description: "An external flow in the portfolio rate, with its scheme." });
|
|
59
|
+
const totalsSchema = z
|
|
60
|
+
.strictObject({
|
|
61
|
+
paidIn: rupees("Money paid in (purchases, switch-ins, stamp duty), positive."),
|
|
62
|
+
received: rupees("Money received before the end (redemptions, switch-outs, IDCW, TDS withheld)."),
|
|
63
|
+
terminalValue: rupees("The closing market value; 0.00 when redeemed to zero."),
|
|
64
|
+
net: rupees("received + terminalValue − paidIn."),
|
|
65
|
+
})
|
|
66
|
+
.meta({ id: "FlowTotals", description: "Sums of the included flows, exact." });
|
|
67
|
+
const xirrResultSchema = z
|
|
68
|
+
.discriminatedUnion("status", [
|
|
69
|
+
z.strictObject({
|
|
70
|
+
status: z.literal("computed"),
|
|
71
|
+
rate: decimal('Annual rate as a fraction, 10 decimal places: "0.1000000000" is 10%.'),
|
|
72
|
+
percent: decimal("The rate as a percentage, 2 decimal places (half-up)."),
|
|
73
|
+
from: isoDateSchema,
|
|
74
|
+
to: isoDateSchema,
|
|
75
|
+
days: count.describe("Calendar days from the first flow to the last."),
|
|
76
|
+
underOneYear: z.boolean().describe("Fewer than 365 days: an annualised rate magnifies short-period changes."),
|
|
77
|
+
iterations: count,
|
|
78
|
+
method: z.enum(["newton", "bisection", "newton+bisection", "grid"]),
|
|
79
|
+
residual: decimal("f(rate) in rupees, 6 decimal places."),
|
|
80
|
+
}),
|
|
81
|
+
z.strictObject({
|
|
82
|
+
status: z.literal("unavailable"),
|
|
83
|
+
reason: reasonSchema.describe("Solver outcome: no_flows, single_date, one_sided_flows, no_root, multiple_roots, no_convergence or residual_too_large."),
|
|
84
|
+
}),
|
|
85
|
+
])
|
|
86
|
+
.meta({ id: "XirrResult", description: "A rate, or why none is shown. Never a guess." });
|
|
87
|
+
const schemeReturnsSchema = z
|
|
88
|
+
.strictObject({
|
|
89
|
+
folio: z.string(),
|
|
90
|
+
amc: z.string(),
|
|
91
|
+
rtaCode: z.string(),
|
|
92
|
+
name: z.string(),
|
|
93
|
+
eligibility: moduleEligibilitySchema,
|
|
94
|
+
flows: z.array(flowSchema).describe("Every row of the scheme, included or excluded, plus the terminal value."),
|
|
95
|
+
totals: totalsSchema.nullable(),
|
|
96
|
+
result: xirrResultSchema.nullable().describe("null when the scheme is not eligible."),
|
|
97
|
+
})
|
|
98
|
+
.meta({ id: "SchemeReturns", description: "XIRR for one scheme." });
|
|
99
|
+
const transferLegShape = {
|
|
100
|
+
folio: z.string(),
|
|
101
|
+
rtaCode: z.string(),
|
|
102
|
+
order: count,
|
|
103
|
+
date: isoDateSchema,
|
|
104
|
+
amount: rupees("|amount| as printed."),
|
|
105
|
+
source: sourceSchema,
|
|
106
|
+
};
|
|
107
|
+
const transferLegSchema = z.strictObject(transferLegShape).meta({ id: "TransferLeg", description: "One leg of a switch or STP." });
|
|
108
|
+
const portfolioReturnsSchema = z
|
|
109
|
+
.strictObject({
|
|
110
|
+
eligibility: moduleEligibilitySchema,
|
|
111
|
+
included: z.array(z.strictObject({ folio: z.string(), rtaCode: z.string(), name: z.string() })).describe("Schemes whose flows make up the portfolio rate."),
|
|
112
|
+
excluded: z
|
|
113
|
+
.array(z.strictObject({ folio: z.string(), rtaCode: z.string(), name: z.string(), reasons: z.array(reasonSchema) }))
|
|
114
|
+
.describe("Schemes that block the portfolio rate, each with its reasons."),
|
|
115
|
+
transfers: z
|
|
116
|
+
.array(z.strictObject({
|
|
117
|
+
out: transferLegSchema,
|
|
118
|
+
in: transferLegSchema,
|
|
119
|
+
stampDuty: rupees("Stamp duty on the switch-in eliminated with the pair."),
|
|
120
|
+
stampOrder: count.nullable(),
|
|
121
|
+
gapDays: count.describe("Calendar days from the switch-out to the switch-in."),
|
|
122
|
+
}))
|
|
123
|
+
.describe("Matched internal transfers, eliminated from the portfolio flows."),
|
|
124
|
+
unmatched: z.array(z.strictObject({ ...transferLegShape, type: txnTypeSchema })).describe("Transfer legs with no matching leg; each blocks the portfolio rate."),
|
|
125
|
+
valuationDate: isoDateSchema.nullable().describe("The common terminal date, when every scheme with units shares one."),
|
|
126
|
+
flows: z.array(portfolioFlowSchema).describe("External flows after eliminating internal transfers; empty when not available."),
|
|
127
|
+
totals: totalsSchema.nullable(),
|
|
128
|
+
result: xirrResultSchema.nullable(),
|
|
129
|
+
})
|
|
130
|
+
.meta({ id: "PortfolioReturns", description: "XIRR for the whole statement." });
|
|
131
|
+
export const returnsAnalysisSchema = z
|
|
132
|
+
.strictObject({
|
|
133
|
+
produces: z.literal("xirr@1"),
|
|
134
|
+
dayCount: z.literal("Actual/365").describe("Days between calendar dates over 365, from the earliest flow."),
|
|
135
|
+
schemes: z.array(schemeReturnsSchema),
|
|
136
|
+
portfolio: portfolioReturnsSchema,
|
|
137
|
+
})
|
|
138
|
+
.meta({
|
|
139
|
+
$id: XIRR_SCHEMA_ID,
|
|
140
|
+
title: "xirr@1",
|
|
141
|
+
description: "Historical XIRR per scheme and for the portfolio, computed only from statements with the evidence it needs (docs/SPEC-metrics.md). A computation from past cash flows, not a projection. " +
|
|
142
|
+
"Contains personal data (folios, amounts): handle it like the statement itself.",
|
|
143
|
+
});
|
|
144
|
+
/** The JSON Schema (draft 2020-12) committed as schema/xirr.v1.schema.json. */
|
|
145
|
+
export function returnsJsonSchema() {
|
|
146
|
+
const { $schema, $id, title, description, ...rest } = z.toJSONSchema(returnsAnalysisSchema, { target: "draft-2020-12" });
|
|
147
|
+
return { $schema, $id, title, description, ...rest };
|
|
148
|
+
}
|
|
149
|
+
export function validateReturnsAnalysis(x) {
|
|
150
|
+
const r = returnsAnalysisSchema.safeParse(x);
|
|
151
|
+
return r.success ? { ok: true } : { ok: false, issues: r.error.issues.map((i) => `${i.path.join("/")}: ${i.message}`) };
|
|
152
|
+
}
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
import type { CasDocument, Folio, Scheme, Source, TxnType } from "../model.js";
|
|
2
|
+
import { type AnalysisManifest, type AnalysisModule, type LedgerView, type ModuleEligibility, type PredicateCode, type Reason } from "./contract.js";
|
|
3
|
+
import { type SolverFailure } from "./xirr.js";
|
|
4
|
+
export declare const XIRR_MANIFEST: AnalysisManifest;
|
|
5
|
+
export type ReturnsReasonCode = PredicateCode
|
|
6
|
+
/** A row of a kind xirr@1 doesn't model (merger, gift out, transfer, bonus, unrecognised…). */
|
|
7
|
+
| "event_not_supported" | "amount_missing" | "sign_mismatch" | "stamp_unattributed" | "tds_unattributed" | "cash_row_unclassified" | "flow_after_valuation" | "no_schemes" | "scheme_not_eligible" | "unmatched_transfer" | "valuation_dates_differ";
|
|
8
|
+
/** Why a row carries no flow. */
|
|
9
|
+
export type FlowExclusionCode = "idcw_reinvested" | "stamp_on_reinvestment" | "stt_inside_amount" | "tds_inside_amount" | "informational_row" | "lien_only" | "not_supported";
|
|
10
|
+
export type FlowRole = "purchase" | "switch_in" | "stamp_duty" | "redemption" | "switch_out" | "idcw_payout" | "tds_withheld" | "reversal" | "terminal_value";
|
|
11
|
+
export interface Flow {
|
|
12
|
+
/** Transaction.order of the row; null for the terminal value. */
|
|
13
|
+
order: number | null;
|
|
14
|
+
date: string;
|
|
15
|
+
type: TxnType | "TERMINAL_VALUE";
|
|
16
|
+
included: boolean;
|
|
17
|
+
/** Signed rupees, investor's view: negative = paid in, positive = received or held. "0.00" when excluded. */
|
|
18
|
+
amount: string;
|
|
19
|
+
role: FlowRole | null;
|
|
20
|
+
exclusion: FlowExclusionCode | null;
|
|
21
|
+
/** For stamp duty, STT and TDS: the row they were attached to. */
|
|
22
|
+
parentOrder: number | null;
|
|
23
|
+
source: Source | null;
|
|
24
|
+
}
|
|
25
|
+
export type XirrResult = {
|
|
26
|
+
status: "computed";
|
|
27
|
+
/** Annual rate as a fraction, 10 decimal places: "0.1000000000" is 10 %. */
|
|
28
|
+
rate: string;
|
|
29
|
+
/** The same as a percentage, 2 decimal places (half-up), for display. */
|
|
30
|
+
percent: string;
|
|
31
|
+
from: string;
|
|
32
|
+
to: string;
|
|
33
|
+
days: number;
|
|
34
|
+
/** Fewer than 365 days: an annualised rate magnifies short-period changes. */
|
|
35
|
+
underOneYear: boolean;
|
|
36
|
+
iterations: number;
|
|
37
|
+
method: "newton" | "bisection" | "newton+bisection" | "grid";
|
|
38
|
+
residual: string;
|
|
39
|
+
} | {
|
|
40
|
+
status: "unavailable";
|
|
41
|
+
reason: Reason<SolverFailure>;
|
|
42
|
+
};
|
|
43
|
+
export interface FlowTotals {
|
|
44
|
+
/** Σ money paid in (purchases, switch-ins, stamp duty, reversals of redemptions), positive. */
|
|
45
|
+
paidIn: string;
|
|
46
|
+
/** Σ money received before the end (redemptions, switch-outs, IDCW, TDS withheld). */
|
|
47
|
+
received: string;
|
|
48
|
+
/** The terminal value (0.00 when redeemed to zero). */
|
|
49
|
+
terminalValue: string;
|
|
50
|
+
/** received + terminalValue − paidIn. */
|
|
51
|
+
net: string;
|
|
52
|
+
}
|
|
53
|
+
export interface SchemeReturns {
|
|
54
|
+
folio: string;
|
|
55
|
+
amc: string;
|
|
56
|
+
rtaCode: string;
|
|
57
|
+
name: string;
|
|
58
|
+
eligibility: ModuleEligibility<ReturnsReasonCode>;
|
|
59
|
+
/** Every row of the scheme, included or excluded, plus the terminal value. */
|
|
60
|
+
flows: Flow[];
|
|
61
|
+
totals: FlowTotals | null;
|
|
62
|
+
result: XirrResult | null;
|
|
63
|
+
}
|
|
64
|
+
export interface TransferLeg {
|
|
65
|
+
folio: string;
|
|
66
|
+
rtaCode: string;
|
|
67
|
+
order: number;
|
|
68
|
+
date: string;
|
|
69
|
+
/** |amount| as printed. */
|
|
70
|
+
amount: string;
|
|
71
|
+
source: Source;
|
|
72
|
+
}
|
|
73
|
+
export interface MatchedTransfer {
|
|
74
|
+
out: TransferLeg;
|
|
75
|
+
in: TransferLeg;
|
|
76
|
+
/** Stamp duty on the switch-in eliminated with the pair ("0.00" when none). */
|
|
77
|
+
stampDuty: string;
|
|
78
|
+
stampOrder: number | null;
|
|
79
|
+
/** Calendar days from the switch-out to the switch-in; shown when not 0. */
|
|
80
|
+
gapDays: number;
|
|
81
|
+
}
|
|
82
|
+
export interface UnmatchedTransfer extends TransferLeg {
|
|
83
|
+
type: TxnType;
|
|
84
|
+
}
|
|
85
|
+
export interface PortfolioFlow extends Flow {
|
|
86
|
+
folio: string;
|
|
87
|
+
rtaCode: string;
|
|
88
|
+
}
|
|
89
|
+
export interface PortfolioReturns {
|
|
90
|
+
eligibility: ModuleEligibility<ReturnsReasonCode>;
|
|
91
|
+
/** Schemes whose flows make up the portfolio figure. */
|
|
92
|
+
included: Array<{
|
|
93
|
+
folio: string;
|
|
94
|
+
rtaCode: string;
|
|
95
|
+
name: string;
|
|
96
|
+
}>;
|
|
97
|
+
/** Schemes that block it, each with its reasons. */
|
|
98
|
+
excluded: Array<{
|
|
99
|
+
folio: string;
|
|
100
|
+
rtaCode: string;
|
|
101
|
+
name: string;
|
|
102
|
+
reasons: Reason<ReturnsReasonCode>[];
|
|
103
|
+
}>;
|
|
104
|
+
transfers: MatchedTransfer[];
|
|
105
|
+
unmatched: UnmatchedTransfer[];
|
|
106
|
+
/** The common terminal date, when every scheme with units shares one. */
|
|
107
|
+
valuationDate: string | null;
|
|
108
|
+
/** The external flows used (internal transfers removed). Empty when not available. */
|
|
109
|
+
flows: PortfolioFlow[];
|
|
110
|
+
totals: FlowTotals | null;
|
|
111
|
+
result: XirrResult | null;
|
|
112
|
+
}
|
|
113
|
+
export interface ReturnsAnalysis {
|
|
114
|
+
produces: "xirr@1";
|
|
115
|
+
/** "Actual/365": days between calendar dates over 365, from the earliest flow. */
|
|
116
|
+
dayCount: "Actual/365";
|
|
117
|
+
schemes: SchemeReturns[];
|
|
118
|
+
portfolio: PortfolioReturns;
|
|
119
|
+
}
|
|
120
|
+
/** xirr@1 over a projected view. With `solveRates` false, eligibility and flows only (results null). */
|
|
121
|
+
export declare function returnsFromView(view: LedgerView, solveRates?: boolean): ReturnsAnalysis;
|
|
122
|
+
export declare const xirrModule: AnalysisModule<ReturnsAnalysis>;
|
|
123
|
+
/** xirr@1 for a parsed statement. */
|
|
124
|
+
export declare function returns(cas: CasDocument): ReturnsAnalysis;
|
|
125
|
+
/** One scheme's xirr@1 eligibility, without solving. */
|
|
126
|
+
export declare function schemeReturnsEligibility(folio: Folio, scheme: Scheme, variant: CasDocument["source"]["variant"]): ModuleEligibility<ReturnsReasonCode>;
|