bharosa 0.3.3 → 0.4.0

package/ANALYTICS-CONTRACT-SHA256

@@ -0,0 +1 @@
+ebab801a241565a3b115993b6ae8470d144f8d69f79cdb8acc274ff8c200cf3e

package/CHANGELOG.md

@@ -1,6 +1,6 @@
-# 0.3.3
+# 0.4.0 — unpublished release candidate
 
-Default both clients to https://api.bharosa.finance. Explicit base URL overrides remain supported. Existing clients using the app origin remain compatible. No analytics changes.
+Add account-scoped Growth scheme performance and category return statistics. Change the default origin from published 0.3.2’s app.bharosa.finance to api.bharosa.finance, preserving explicit overrides. The reviewed host-default delta is included directly; no intermediate 0.3.3 publication is required. No investor monetary-performance, fund-AUM or stated-TER methods. API deployment and SDK publication are separate.
 
 # Changelog
 

package/MONTHLY-MARKET-CONTRACT-SHA256

@@ -1 +1 @@
-ad8f930964df34c3a28e3309302d19ba76ab9d48190c024a26b0795422f0b648
+29463b6a150e368a47ac11e2f8f841e3808d94d3ff9b70221fe3804c93b91004

package/README.md

@@ -2,14 +2,14 @@
 
 A TypeScript client for Bharosa accounts, investors, portfolios, and mutual funds. Use one resource interface from TypeScript, ESM, or CommonJS, with no runtime dependencies.
 
-**SDK version:** `bharosa@0.3.3`. Both clients use the production API at `https://api.bharosa.finance` by default. Account access and credentials are still required; installing the SDK does not grant access.
+**Local release candidate (unpublished):** `bharosa@0.4.0`. Both clients use the production API at `https://api.bharosa.finance` by default. Account access and credentials are still required; installing the SDK does not grant access.
 
 ## Start here
 
-Use Node.js 22.12+ in a supported LTS release. Install the published SDK in your backend application:
+Use Node.js 22.12+ in a supported LTS release. Install the reviewed local candidate in your backend application:
 
 ```sh
-npm install bharosa@0.3.3 --ignore-scripts
+npm install /absolute/path/to/bharosa-0.4.0.tgz --ignore-scripts
 ```
 
 Source contributors can build and pack a local archive using the commands in CONTRIBUTING.md.
@@ -124,3 +124,7 @@ Available in SDK 0.3.0 and activated at `https://api.bharosa.finance`. Server ap
 ### Optional API origin override
 
 Set `baseUrl` only for another deployment or tests. Omitted or `undefined` uses `https://api.bharosa.finance`; invalid explicit values fail validation and never fall back. Overrides must be HTTPS origins without credentials, paths, queries or fragments. Local HTTP also requires `allowLocalhostHttp: true`. The SDK does not read `BHAROSA_API_BASE_URL` automatically.
+
+## Growth performance and category returns
+
+Adds `mutualFundSchemes.performance.retrieve` and `fundCategories.statistics.retrieve` for authenticated account access. See [analytics methods, coverage and limitations](docs/analytics.md). These API routes are deployed; this SDK candidate is not yet published. `BharosaMarket` retains its four monthly operations and cannot call account analytics.

package/dist/analytics-contract.cjs

@@ -0,0 +1,665 @@
+"use strict";
+// Generated from the reviewed analytics OpenAPI snapshot. Transport only.
+module.exports = {
+  "operations": {
+    "analytics_scheme": {
+      "path": "/v1/accounts/{account}/market-data/schemes/{id}/performance",
+      "method": "GET",
+      "status": 200,
+      "marketData": true,
+      "readOnly": true,
+      "parameters": [
+        {
+          "name": "account",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string",
+            "pattern": "^(me|acct_[a-f0-9]{32})$"
+          }
+        },
+        {
+          "name": "id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string",
+            "pattern": "^[1-9][0-9]{0,18}$"
+          }
+        },
+        {
+          "name": "as_of",
+          "in": "query",
+          "required": true,
+          "schema": {
+            "type": "string",
+            "format": "date",
+            "pattern": "^\\d{4}-\\d{2}-01$"
+          }
+        },
+        {
+          "name": "periods",
+          "in": "query",
+          "required": false,
+          "schema": {
+            "type": "string",
+            "pattern": "^(1y|3y|5y|since_inception)(,(1y|3y|5y|since_inception)){0,3}$"
+          }
+        }
+      ],
+      "response": {
+        "type": "object",
+        "properties": {
+          "methodology_version": {
+            "const": "ts-analytics-v1"
+          },
+          "requested_as_of": {
+            "type": "string",
+            "format": "date",
+            "pattern": "^\\d{4}-\\d{2}-01$"
+          },
+          "currency": {
+            "const": "INR"
+          },
+          "source_cutoff": {
+            "type": "string",
+            "format": "date",
+            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+          },
+          "source_version": {
+            "type": "string"
+          },
+          "warnings": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "object": {
+            "const": "scheme_performance"
+          },
+          "scheme_id": {
+            "type": "string"
+          },
+          "fund_id": {
+            "type": "string"
+          },
+          "plan": {
+            "type": "string"
+          },
+          "option": {
+            "type": "string"
+          },
+          "basis": {
+            "type": "string"
+          },
+          "periods": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "period": {
+                  "enum": [
+                    "1y",
+                    "3y",
+                    "5y",
+                    "since_inception"
+                  ]
+                },
+                "requested_start": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "format": "date",
+                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "requested_end": {
+                  "type": "string",
+                  "format": "date",
+                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+                },
+                "status": {
+                  "enum": [
+                    "available",
+                    "unavailable"
+                  ]
+                },
+                "reason": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "total_return_pct": {
+                  "anyOf": [
+                    {
+                      "type": "object",
+                      "properties": {
+                        "status": {
+                          "const": "available"
+                        },
+                        "value": {
+                          "type": "string",
+                          "pattern": "^-?\\d+(\\.\\d{1,8})?$"
+                        },
+                        "reason": {
+                          "type": "null"
+                        }
+                      },
+                      "required": [
+                        "status",
+                        "value",
+                        "reason"
+                      ],
+                      "additionalProperties": true
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "status": {
+                          "const": "unavailable"
+                        },
+                        "value": {
+                          "type": "null"
+                        },
+                        "reason": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "status",
+                        "value",
+                        "reason"
+                      ],
+                      "additionalProperties": true
+                    }
+                  ]
+                },
+                "cagr_pct": {
+                  "anyOf": [
+                    {
+                      "type": "object",
+                      "properties": {
+                        "status": {
+                          "const": "available"
+                        },
+                        "value": {
+                          "type": "string",
+                          "pattern": "^-?\\d+(\\.\\d{1,8})?$"
+                        },
+                        "reason": {
+                          "type": "null"
+                        }
+                      },
+                      "required": [
+                        "status",
+                        "value",
+                        "reason"
+                      ],
+                      "additionalProperties": true
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "status": {
+                          "const": "unavailable"
+                        },
+                        "value": {
+                          "type": "null"
+                        },
+                        "reason": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "status",
+                        "value",
+                        "reason"
+                      ],
+                      "additionalProperties": true
+                    }
+                  ]
+                },
+                "start_observation_date": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "format": "date",
+                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "end_observation_date": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "format": "date",
+                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "start_nav": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "end_nav": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "start_lag_days": {
+                  "anyOf": [
+                    {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "end_lag_days": {
+                  "anyOf": [
+                    {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "elapsed_days": {
+                  "anyOf": [
+                    {
+                      "type": "number"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "annualization_basis": {
+                  "const": "observed_nav_dates_365_25"
+                }
+              },
+              "required": [
+                "period",
+                "requested_start",
+                "requested_end",
+                "status",
+                "reason",
+                "total_return_pct",
+                "cagr_pct",
+                "start_observation_date",
+                "end_observation_date",
+                "start_nav",
+                "end_nav",
+                "start_lag_days",
+                "end_lag_days",
+                "elapsed_days",
+                "annualization_basis"
+              ],
+              "additionalProperties": true
+            },
+            "minItems": 1,
+            "maxItems": 4
+          }
+        },
+        "required": [
+          "methodology_version",
+          "requested_as_of",
+          "currency",
+          "source_cutoff",
+          "source_version",
+          "warnings",
+          "object",
+          "scheme_id",
+          "fund_id",
+          "plan",
+          "option",
+          "basis",
+          "periods"
+        ],
+        "additionalProperties": true
+      }
+    },
+    "analytics_category": {
+      "path": "/v1/accounts/{account}/market-data/categories/{id}/statistics",
+      "method": "GET",
+      "status": 200,
+      "marketData": true,
+      "readOnly": true,
+      "parameters": [
+        {
+          "name": "account",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string",
+            "pattern": "^(me|acct_[a-f0-9]{32})$"
+          }
+        },
+        {
+          "name": "id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100
+          }
+        },
+        {
+          "name": "as_of",
+          "in": "query",
+          "required": true,
+          "schema": {
+            "type": "string",
+            "format": "date",
+            "pattern": "^\\d{4}-\\d{2}-01$"
+          }
+        },
+        {
+          "name": "periods",
+          "in": "query",
+          "required": false,
+          "schema": {
+            "type": "string",
+            "pattern": "^(1y|3y|5y|since_inception)(,(1y|3y|5y|since_inception)){0,3}$"
+          }
+        },
+        {
+          "name": "metrics",
+          "in": "query",
+          "required": false,
+          "schema": {
+            "type": "string",
+            "const": "return",
+            "default": "return"
+          }
+        },
+        {
+          "name": "plan",
+          "in": "query",
+          "required": false,
+          "schema": {
+            "enum": [
+              "direct",
+              "regular"
+            ]
+          }
+        },
+        {
+          "name": "option",
+          "in": "query",
+          "required": false,
+          "schema": {
+            "const": "growth"
+          }
+        }
+      ],
+      "response": {
+        "type": "object",
+        "properties": {
+          "methodology_version": {
+            "const": "ts-analytics-v1"
+          },
+          "requested_as_of": {
+            "type": "string",
+            "format": "date",
+            "pattern": "^\\d{4}-\\d{2}-01$"
+          },
+          "currency": {
+            "const": "INR"
+          },
+          "source_cutoff": {
+            "type": "string",
+            "format": "date",
+            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+          },
+          "source_version": {
+            "type": "string"
+          },
+          "warnings": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "object": {
+            "const": "category_statistics"
+          },
+          "category": {
+            "type": "string"
+          },
+          "cohort": {
+            "type": "object",
+            "properties": {
+              "policy": {
+                "const": "current_classification_as_of_prices"
+              },
+              "plan": {
+                "enum": [
+                  "direct",
+                  "regular"
+                ]
+              },
+              "option": {
+                "const": "growth"
+              },
+              "fund_count": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "selected_scheme_count": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "classification_date": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "format": "date",
+                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            },
+            "required": [
+              "policy",
+              "plan",
+              "option",
+              "fund_count",
+              "selected_scheme_count",
+              "classification_date"
+            ],
+            "additionalProperties": true
+          },
+          "metrics": {
+            "type": "object",
+            "additionalProperties": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "status": {
+                      "const": "available"
+                    },
+                    "value": {
+                      "type": "string",
+                      "pattern": "^-?\\d+(\\.\\d{1,8})?$"
+                    },
+                    "reason": {
+                      "type": "null"
+                    },
+                    "method": {
+                      "const": "equal_weighted_arithmetic_mean"
+                    },
+                    "unit": {
+                      "type": "string"
+                    },
+                    "eligible_count": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "valid_count": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "stale_count": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "invalid_count": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "missing_count": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "coverage_pct": {
+                      "type": "string",
+                      "pattern": "^\\d+(\\.\\d+)?$"
+                    },
+                    "exclusions": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "type": "integer",
+                        "minimum": 0
+                      }
+                    }
+                  },
+                  "required": [
+                    "status",
+                    "value",
+                    "reason",
+                    "method",
+                    "unit",
+                    "eligible_count",
+                    "valid_count",
+                    "stale_count",
+                    "invalid_count",
+                    "missing_count",
+                    "coverage_pct",
+                    "exclusions"
+                  ],
+                  "additionalProperties": true
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "status": {
+                      "const": "unavailable"
+                    },
+                    "value": {
+                      "type": "null"
+                    },
+                    "reason": {
+                      "type": "string"
+                    },
+                    "method": {
+                      "const": "equal_weighted_arithmetic_mean"
+                    },
+                    "unit": {
+                      "type": "string"
+                    },
+                    "eligible_count": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "valid_count": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "stale_count": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "invalid_count": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "missing_count": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "coverage_pct": {
+                      "type": "string",
+                      "pattern": "^\\d+(\\.\\d+)?$"
+                    },
+                    "exclusions": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "type": "integer",
+                        "minimum": 0
+                      }
+                    }
+                  },
+                  "required": [
+                    "status",
+                    "value",
+                    "reason",
+                    "method",
+                    "unit",
+                    "eligible_count",
+                    "valid_count",
+                    "stale_count",
+                    "invalid_count",
+                    "missing_count",
+                    "coverage_pct",
+                    "exclusions"
+                  ],
+                  "additionalProperties": true
+                }
+              ]
+            }
+          }
+        },
+        "required": [
+          "methodology_version",
+          "requested_as_of",
+          "currency",
+          "source_cutoff",
+          "source_version",
+          "warnings",
+          "object",
+          "category",
+          "cohort",
+          "metrics"
+        ],
+        "additionalProperties": true
+      }
+    }
+  }
+};

package/dist/analytics-contract.d.cts

@@ -0,0 +1,2 @@
+import type { Operation } from "./schema.cjs";
+export const operations: Readonly<Record<string, Operation>>;

package/dist/analytics-contract.d.ts

@@ -0,0 +1,2 @@
+import type { Operation } from "./schema.js";
+export const operations: Readonly<Record<string, Operation>>;

package/dist/analytics-types.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/analytics-types.d.cts

@@ -0,0 +1,103 @@
+import type { RequestOptions } from "./client-types.cjs";
+export type AnalyticsPeriod = "1y" | "3y" | "5y" | "since_inception";
+export type AnalyticsMetric = {
+    status: "available";
+    value: string;
+    reason: null;
+} | {
+    status: "unavailable";
+    value: null;
+    reason: string;
+};
+export interface PerformanceSelection {
+    asOf: string;
+    periods?: AnalyticsPeriod[];
+}
+export interface AnalyticsEnvelope {
+    methodology_version: "ts-analytics-v1";
+    requested_as_of: string;
+    currency: "INR";
+    source_cutoff: string;
+    source_version: string;
+    warnings: string[];
+}
+export interface PerformancePeriod {
+    period: AnalyticsPeriod;
+    requested_start: string | null;
+    requested_end: string;
+    status: "available" | "unavailable";
+    reason: string | null;
+    total_return_pct: AnalyticsMetric;
+    cagr_pct: AnalyticsMetric;
+}
+export interface AnalyticsFreshnessPolicy {
+    nav_days: number;
+    aum_days: number;
+    ter_days: number;
+    category_min_funds: number;
+    category_min_coverage_pct: number;
+}
+export interface SchemePerformance extends AnalyticsEnvelope {
+    calculation_precision: "decimal_inputs_float64_returns";
+    freshness_policy: AnalyticsFreshnessPolicy;
+    available_history_start: string | null;
+    inception_basis: "verified_first_scheme_nav" | null;
+    scheme_nav_inception_date: string | null;
+    object: "scheme_performance";
+    scheme_id: string;
+    fund_id: string;
+    plan: string;
+    option: string;
+    basis: string;
+    periods: (PerformancePeriod & {
+        start_observation_date: string | null;
+        end_observation_date: string | null;
+        start_nav: string | null;
+        end_nav: string | null;
+        start_lag_days: number | null;
+        end_lag_days: number | null;
+        elapsed_days: number | null;
+        annualization_basis: "observed_nav_dates_365_25";
+    })[];
+}
+export interface CategorySelection {
+    asOf: string;
+    periods?: Exclude<AnalyticsPeriod, "since_inception">[];
+    metrics?: "return"[];
+    plan?: "direct" | "regular";
+    option?: "growth";
+}
+export interface CategoryStatistics extends AnalyticsEnvelope {
+    freshness_policy: AnalyticsFreshnessPolicy;
+    object: "category_statistics";
+    category: string;
+    cohort: {
+        policy: "current_classification_as_of_prices";
+        plan: "direct" | "regular";
+        option: "growth";
+        fund_count: number;
+        selected_scheme_count: number;
+        classification_date: string | null;
+    };
+    metrics: Record<string, AnalyticsMetric & {
+        method: "equal_weighted_arithmetic_mean";
+        return_type: "total_return" | "cagr" | null;
+        observation_date_min: string | null;
+        observation_date_max: string | null;
+        observed_elapsed_days_min: number | null;
+        observed_elapsed_days_max: number | null;
+        start_lag_days_max: number | null;
+        end_lag_days_max: number | null;
+        unit: string;
+        eligible_count: number;
+        valid_count: number;
+        missing_count: number;
+        stale_count: number;
+        invalid_count: number;
+        coverage_pct: string;
+        exclusions: Record<string, number>;
+    }>;
+}
+export interface AnalyticsResource<P, R> {
+    retrieve(id: string, params: P, options?: RequestOptions): Promise<R>;
+}

package/dist/analytics-types.d.ts

@@ -0,0 +1,103 @@
+import type { RequestOptions } from "./client-types.js";
+export type AnalyticsPeriod = "1y" | "3y" | "5y" | "since_inception";
+export type AnalyticsMetric = {
+    status: "available";
+    value: string;
+    reason: null;
+} | {
+    status: "unavailable";
+    value: null;
+    reason: string;
+};
+export interface PerformanceSelection {
+    asOf: string;
+    periods?: AnalyticsPeriod[];
+}
+export interface AnalyticsEnvelope {
+    methodology_version: "ts-analytics-v1";
+    requested_as_of: string;
+    currency: "INR";
+    source_cutoff: string;
+    source_version: string;
+    warnings: string[];
+}
+export interface PerformancePeriod {
+    period: AnalyticsPeriod;
+    requested_start: string | null;
+    requested_end: string;
+    status: "available" | "unavailable";
+    reason: string | null;
+    total_return_pct: AnalyticsMetric;
+    cagr_pct: AnalyticsMetric;
+}
+export interface AnalyticsFreshnessPolicy {
+    nav_days: number;
+    aum_days: number;
+    ter_days: number;
+    category_min_funds: number;
+    category_min_coverage_pct: number;
+}
+export interface SchemePerformance extends AnalyticsEnvelope {
+    calculation_precision: "decimal_inputs_float64_returns";
+    freshness_policy: AnalyticsFreshnessPolicy;
+    available_history_start: string | null;
+    inception_basis: "verified_first_scheme_nav" | null;
+    scheme_nav_inception_date: string | null;
+    object: "scheme_performance";
+    scheme_id: string;
+    fund_id: string;
+    plan: string;
+    option: string;
+    basis: string;
+    periods: (PerformancePeriod & {
+        start_observation_date: string | null;
+        end_observation_date: string | null;
+        start_nav: string | null;
+        end_nav: string | null;
+        start_lag_days: number | null;
+        end_lag_days: number | null;
+        elapsed_days: number | null;
+        annualization_basis: "observed_nav_dates_365_25";
+    })[];
+}
+export interface CategorySelection {
+    asOf: string;
+    periods?: Exclude<AnalyticsPeriod, "since_inception">[];
+    metrics?: "return"[];
+    plan?: "direct" | "regular";
+    option?: "growth";
+}
+export interface CategoryStatistics extends AnalyticsEnvelope {
+    freshness_policy: AnalyticsFreshnessPolicy;
+    object: "category_statistics";
+    category: string;
+    cohort: {
+        policy: "current_classification_as_of_prices";
+        plan: "direct" | "regular";
+        option: "growth";
+        fund_count: number;
+        selected_scheme_count: number;
+        classification_date: string | null;
+    };
+    metrics: Record<string, AnalyticsMetric & {
+        method: "equal_weighted_arithmetic_mean";
+        return_type: "total_return" | "cagr" | null;
+        observation_date_min: string | null;
+        observation_date_max: string | null;
+        observed_elapsed_days_min: number | null;
+        observed_elapsed_days_max: number | null;
+        start_lag_days_max: number | null;
+        end_lag_days_max: number | null;
+        unit: string;
+        eligible_count: number;
+        valid_count: number;
+        missing_count: number;
+        stale_count: number;
+        invalid_count: number;
+        coverage_pct: string;
+        exclusions: Record<string, number>;
+    }>;
+}
+export interface AnalyticsResource<P, R> {
+    retrieve(id: string, params: P, options?: RequestOptions): Promise<R>;
+}

package/dist/client-types.d.cts

@@ -1,3 +1,4 @@
+import type * as A from "./analytics-types.cjs";
 import type { MonthlyMarketClient } from "./monthly-types.cjs";
 import type { MarketDataClient, CurrentHoldingsInput, CurrentHoldingsResult } from "./market-types.cjs";
 export type * from "./market-types.cjs";
@@ -175,7 +176,11 @@ export type FundObjectReferences = Omit<Fields<FundReferences>, "data"> & {
 };
 export interface ClientSurface {
     readonly marketSnapshots: MonthlyMarketClient;
+    readonly fundCategories: {
+        readonly statistics: A.AnalyticsResource<A.CategorySelection, A.CategoryStatistics>;
+    };
     readonly mutualFundSchemes: {
+        readonly performance: A.AnalyticsResource<A.PerformanceSelection, A.SchemePerformance>;
         readonly navs: {
             readonly retrieve: MonthlyMarketClient["schemes"]["nav"];
         };

package/dist/client-types.d.ts

@@ -1,3 +1,4 @@
+import type * as A from "./analytics-types.js";
 import type { MonthlyMarketClient } from "./monthly-types.js";
 import type { MarketDataClient, CurrentHoldingsInput, CurrentHoldingsResult } from "./market-types.js";
 export type * from "./market-types.js";
@@ -175,7 +176,11 @@ export type FundObjectReferences = Omit<Fields<FundReferences>, "data"> & {
 };
 export interface ClientSurface {
     readonly marketSnapshots: MonthlyMarketClient;
+    readonly fundCategories: {
+        readonly statistics: A.AnalyticsResource<A.CategorySelection, A.CategoryStatistics>;
+    };
     readonly mutualFundSchemes: {
+        readonly performance: A.AnalyticsResource<A.PerformanceSelection, A.SchemePerformance>;
         readonly navs: {
             readonly retrieve: MonthlyMarketClient["schemes"]["nav"];
         };

package/dist/index.cjs

@@ -42,12 +42,50 @@ class Bharosa {
     clients;
     investors;
     portfolios;
+    fundCategories;
     mutualFunds;
     mutualFundSchemes;
     marketSnapshots;
     marketData;
     constructor(config) {
         const call = (0, transport_cjs_1.createTransport)(config);
+        const analyticsQuery = (q, extra = []) => {
+            (0, transport_cjs_1.keys)(q, ["asOf", "periods", ...extra]);
+            checkedDate(q.asOf);
+            (0, transport_cjs_1.check)(q.asOf.endsWith("-01"));
+            if (q.periods !== undefined)
+                (0, transport_cjs_1.check)(Array.isArray(q.periods) &&
+                    q.periods.length > 0 &&
+                    q.periods.length <= 4 &&
+                    new Set(q.periods).size === q.periods.length &&
+                    q.periods.every((p) => ["1y", "3y", "5y", "since_inception"].includes(p)));
+            return {
+                as_of: q.asOf,
+                ...(q.periods === undefined ? {} : { periods: q.periods.join(",") }),
+            };
+        };
+        this.fundCategories = Object.freeze({
+            statistics: Object.freeze({
+                retrieve: (id, q, o) => {
+                    const query = analyticsQuery(q, ["metrics", "plan", "option"]);
+                    if (q.metrics !== undefined)
+                        (0, transport_cjs_1.check)(Array.isArray(q.metrics) &&
+                            q.metrics.length > 0 &&
+                            q.metrics.length <= 3 &&
+                            new Set(q.metrics).size === q.metrics.length &&
+                            q.metrics.every((m) => m === "return"));
+                    (0, transport_cjs_1.check)(!q.periods?.includes("since_inception"));
+                    (0, transport_cjs_1.check)(!(q.metrics && !q.metrics.includes("return") && q.periods));
+                    return call("analytics_category", {
+                        id,
+                        ...query,
+                        ...(q.metrics ? { metrics: q.metrics.join(",") } : {}),
+                        ...(q.plan ? { plan: q.plan } : {}),
+                        ...(q.option ? { option: q.option } : {}),
+                    }, undefined, o);
+                },
+            }),
+        });
         const list = (p) => {
             (0, transport_cjs_1.keys)(p, ["limit", "startingAfter", "client"]);
             return Object.fromEntries(Object.entries(p)
@@ -299,6 +337,9 @@ class Bharosa {
             },
         };
         this.mutualFundSchemes = Object.freeze({
+            performance: Object.freeze({
+                retrieve: (id, q, o) => call("analytics_scheme", { id, ...analyticsQuery(q) }, undefined, o),
+            }),
             navs: Object.freeze({ retrieve: this.marketSnapshots.schemes.nav }),
             expenseRatios: Object.freeze({
                 retrieve: this.marketSnapshots.schemes.expenseRatio,

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+export type * from "./analytics-types.cjs";
 import type { MonthlyMarketClient } from "./monthly-types.cjs";
 export type * from "./monthly-types.cjs";
 import type * as T from "./client-types.cjs";
@@ -9,6 +10,7 @@ export declare class Bharosa implements T.ClientSurface {
     readonly clients: T.ClientSurface["clients"];
     readonly investors: T.ClientSurface["investors"];
     readonly portfolios: T.ClientSurface["portfolios"];
+    readonly fundCategories: T.ClientSurface["fundCategories"];
     readonly mutualFunds: T.ClientSurface["mutualFunds"];
     readonly mutualFundSchemes: T.ClientSurface["mutualFundSchemes"];
     readonly marketSnapshots: MonthlyMarketClient;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export type * from "./analytics-types.js";
 import type { MonthlyMarketClient } from "./monthly-types.js";
 export type * from "./monthly-types.js";
 import type * as T from "./client-types.js";
@@ -9,6 +10,7 @@ export declare class Bharosa implements T.ClientSurface {
     readonly clients: T.ClientSurface["clients"];
     readonly investors: T.ClientSurface["investors"];
     readonly portfolios: T.ClientSurface["portfolios"];
+    readonly fundCategories: T.ClientSurface["fundCategories"];
     readonly mutualFunds: T.ClientSurface["mutualFunds"];
     readonly mutualFundSchemes: T.ClientSurface["mutualFundSchemes"];
     readonly marketSnapshots: MonthlyMarketClient;

package/dist/operation-types.d.cts

@@ -1,9 +1,12 @@
+import type * as A from "./analytics-types.cjs";
 import type * as S from "./monthly-types.cjs";
 import type * as M from "./models.cjs";
 import type * as D from "./market-types.cjs";
 import type { CurrentMixEvidence } from "./client-types.cjs";
 /** Each entry is the decoded response of the corresponding generated operation. */
 export interface OperationResults {
+    analytics_scheme: A.SchemePerformance;
+    analytics_category: A.CategoryStatistics;
     monthly_nav: S.MarketSnapshot<D.NavObservation>;
     monthly_expense: S.MarketSnapshot<D.ExpenseObservation>;
     monthly_portfolio: S.MarketSnapshot<D.FundPortfolio>;

package/dist/operation-types.d.ts

@@ -1,9 +1,12 @@
+import type * as A from "./analytics-types.js";
 import type * as S from "./monthly-types.js";
 import type * as M from "./models.js";
 import type * as D from "./market-types.js";
 import type { CurrentMixEvidence } from "./client-types.js";
 /** Each entry is the decoded response of the corresponding generated operation. */
 export interface OperationResults {
+    analytics_scheme: A.SchemePerformance;
+    analytics_category: A.CategoryStatistics;
     monthly_nav: S.MarketSnapshot<D.NavObservation>;
     monthly_expense: S.MarketSnapshot<D.ExpenseObservation>;
     monthly_portfolio: S.MarketSnapshot<D.FundPortfolio>;

package/dist/response-checks.cjs

@@ -121,6 +121,73 @@ function responseMatches(id, op, data, params, body, account) {
             b("valuation_date") !== undefined &&
             d("valuation_date") !== b("valuation_date")))
         return false;
+    if (id.startsWith("analytics_")) {
+        if (id === "analytics_aum") {
+            if (d("requested_date") !== params.as_of ||
+                (d("observation_date") !== null &&
+                    String(d("observation_date")) > String(params.as_of)))
+                return false;
+            if (d("status") === "available" &&
+                field(d("data"), "basis") === "reported_fund_total" &&
+                field(field(d("data"), "source"), "date") !== d("observation_date"))
+                return false;
+            if (d("status") === "available" &&
+                (field(d("data"), "fund_id") !== params.id ||
+                    field(d("data"), "date") !== d("observation_date") ||
+                    String(d("observation_date")) > String(params.as_of)))
+                return false;
+        }
+        else {
+            if (d("requested_as_of") !== params.as_of)
+                return false;
+            const identity = id === "analytics_scheme"
+                ? "scheme_id"
+                : id === "analytics_portfolio"
+                    ? "portfolio_id"
+                    : "category";
+            if (d(identity) !== params.id)
+                return false;
+            if (id === "analytics_category") {
+                if (d("cohort", "plan") !== (params.plan ?? "direct") ||
+                    d("cohort", "option") !== (params.option ?? "growth"))
+                    return false;
+                const requested = String(params.metrics ?? "return").split(",");
+                const expected = requested.flatMap((m) => m === "return"
+                    ? String(params.periods ?? "1y,3y,5y")
+                        .split(",")
+                        .map((p) => "return_" + p)
+                    : [m]);
+                for (const key of expected) {
+                    const metric = d("metrics", key);
+                    if (!(0, schema_cjs_1.record)(metric))
+                        return false;
+                    const eligible = Number(field(metric, "eligible_count")), valid = Number(field(metric, "valid_count"));
+                    const excluded = [
+                        "missing_count",
+                        "stale_count",
+                        "invalid_count",
+                    ].reduce((n, k) => n + Number(field(metric, k)), 0);
+                    if (eligible !== d("cohort", "fund_count") ||
+                        valid + excluded !== eligible)
+                        return false;
+                    if (field(metric, "status") === "available" &&
+                        (valid < 3 || valid * 100 < eligible * 80))
+                        return false;
+                }
+            }
+            if (id !== "analytics_category") {
+                const expected = String(params.periods ?? "1y,3y,5y").split(",");
+                const got = rows(d("periods"));
+                if (got.length !== expected.length ||
+                    got.some((p, i) => field(p, "period") !== expected[i] ||
+                        field(p, "requested_end") !== params.as_of ||
+                        (id === "analytics_scheme" &&
+                            (later(field(p, "start_observation_date"), field(p, "requested_start")) ||
+                                later(field(p, "end_observation_date"), params.as_of)))))
+                    return false;
+            }
+        }
+    }
     if (id.startsWith("monthly_") && id !== "monthly_valuation") {
         const observation = d("observation_date"), requested = d("requested_date"), data = d("data");
         if (requested !== params.as_of)

package/dist/transport.cjs

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.check = check;
 exports.keys = keys;
 exports.createTransport = createTransport;
+const analytics_contract_cjs_1 = require("./analytics-contract.cjs");
 const monthly_market_data_cjs_1 = require("./monthly-market-data.cjs");
 const contract_cjs_1 = require("./contract.cjs");
 const market_data_cjs_1 = require("./market-data.cjs");
@@ -13,6 +14,7 @@ const operations = {
     ...contract_cjs_1.operations,
     ...market_data_cjs_1.operations,
     ...monthly_market_data_cjs_1.operations,
+    ...analytics_contract_cjs_1.operations,
 };
 function assertServer() {
     if (typeof window !== "undefined" ||
@@ -196,13 +198,10 @@ function createTransport(config, marketOnly = false) {
     check(Number.isInteger(max) && max >= 1 && max <= 16777216);
     const call = async (id, params = {}, body, opts = {}) => {
         const op = operations[id];
-        if (marketOnly)
-            check([
-                "monthly_nav",
-                "monthly_expense",
-                "monthly_portfolio",
-                "monthly_holdings",
-            ].includes(id));
+        if (marketOnly &&
+            !["monthly_nav", "monthly_expense", "monthly_portfolio", "monthly_holdings"].includes(id)) {
+            throw Object.assign(new errors_cjs_1.ValidationError(), { code: "market_only_operation" });
+        }
         let o, serialized, url;
         try {
             o = options(opts);

package/dist/validate.cjs

@@ -62,7 +62,9 @@ function valid(s, v, depth = 0) {
                 (s.required ?? []).every((k) => Object.hasOwn(v, k)) &&
                 keys.every((k) => Object.hasOwn(s.properties ?? {}, k)
                     ? valid(s.properties?.[k], v[k], depth + 1)
-                    : s.additionalProperties !== false));
+                    : typeof s.additionalProperties === "object"
+                        ? valid(s.additionalProperties, v[k], depth + 1)
+                        : s.additionalProperties !== false));
         }
         default:
             return true;

package/docs/analytics.md

@@ -0,0 +1,26 @@
+# Growth scheme performance and category returns
+
+SDK0.4.0 candidate, unpublished. The two API methods are deployed. Default origin is https://api.bharosa.finance, incorporating the reviewed host-default delta directly on published0.3.2; explicit baseUrl overrides remain supported. Account authorization with accounts:read is required. BharosaMarket does not expose these methods.
+
+```ts
+import { Bharosa } from "bharosa";
+const client = new Bharosa({
+  account: "me",
+  auth: { type: "account_key", apiKey: process.env.BHAROSA_SECRET_KEY! },
+});
+const scheme = await client.mutualFundSchemes.performance.retrieve("45139", {
+  asOf: "2026-10-01", periods: ["1y", "3y"],
+});
+const category = await client.fundCategories.statistics.retrieve("index_fund", {
+  asOf: "2026-10-01", periods: ["1y"], metrics: ["return"],
+  plan: "direct", option: "growth",
+});
+```
+
+Use an exact first-of-month asOf. Discover category identifiers through marketData.categories.list; index_fund is a real category, equity was only a local fixture label. Category metrics accepts only return and defaults to return. Category returns are equal-weight means with fund deduplication, minimum3valid funds and80%coverage; inspect status/reason and eligible/valid/missing/invalid/stale counts. An HTTP200 can correctly contain an unavailable metric. Current classification is applied to historical prices, with survivorship/reclassification bias; this is not an investable index return.
+
+Scheme responses report exact NAV observations and boundary lags, total return, and annualization over observed dates using365.25days. CAGR is unavailable for periods not longer than one year. IDCW and unverified inception remain explicitly unavailable. NAV freshness limits and missing data must be checked before using a value.
+
+There are no investor-performance or fund-AUM methods or public types in this release. Stated-TER comparisons remain deferred; existing expense-ratio methods retain their prior behavior. Future AUM belongs to mutualFunds, not schemes. Shared response freshness metadata includes aum_days/ter_days because the deployed envelope contains those fields; their presence does not expose AUM/TER methods.
+
+Hosted scheme/category verification used the app-origin compatibility path with synthetic account access and real market data. Authenticated verification on the new api hostname remains a final-trial requirement; do not claim that journey has passed. No SDK example should create credentials or mutate a portfolio.

package/docs/getting-started.md

@@ -6,10 +6,10 @@ Use Node.js 22.12 or later in a supported LTS release. The SDK supports ESM and
 
 Obtain your authorized account ID and account key. Bharosa and BharosaMarket default to the production origin `https://api.bharosa.finance`; no API URL environment variable is required. The SDK neither provisions accounts nor runs an OAuth consent flow.
 
-## Install
+## Install the unpublished 0.4.0 candidate
 
 ```sh
-npm install bharosa@0.3.3 --ignore-scripts
+npm install /absolute/path/to/bharosa-0.4.0.tgz --ignore-scripts
 ```
 
 Source contributors can build and pack a local archive as described in CONTRIBUTING.md.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bharosa",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "private": false,
   "description": "Typed Bharosa resource SDK with server credentials or caller-owned transport.",
   "license": "MIT",
@@ -44,7 +44,8 @@
     "SECURITY.md",
     "CHANGELOG.md",
     "FIRST-PARTY-CONTRACT-SHA256",
-    "MONTHLY-MARKET-CONTRACT-SHA256"
+    "MONTHLY-MARKET-CONTRACT-SHA256",
+    "ANALYTICS-CONTRACT-SHA256"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
@@ -58,7 +59,9 @@
     "check:first-party": "node scripts/generate-first-party.mjs --check",
     "typecheck": "node tooling/node_modules/typescript/bin/tsc --noEmit && node tooling/node_modules/typescript/bin/tsc -p tsconfig.test.json --noEmit && node tooling/node_modules/typescript/bin/tsc --noEmit --strict --target ES2022 --module NodeNext --moduleResolution NodeNext --typeRoots tooling/node_modules/@types test/api-compatibility.ts",
     "generate:monthly": "node scripts/generate-monthly.mjs",
-    "check:monthly": "node scripts/generate-monthly.mjs --check"
+    "check:monthly": "node scripts/generate-monthly.mjs --check",
+    "generate:analytics": "node scripts/generate-analytics.mjs",
+    "check:analytics": "node scripts/generate-analytics.mjs --check"
   },
   "publishConfig": {
     "access": "public",