bharosa 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,8 +1,25 @@
-# 0.4.0 — unpublished release candidate
+# Changelog
 
-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.
+## 0.6.0
 
-# Changelog
+Add `markets.schemes.search` and compatible `BharosaMarket.schemes.search` using the canonical account-independent search route. Keep private search and historical methods unchanged. Correct the getting-started example to use an API key without a required account ID.
+
+
+## 0.5.1
+
+Documentation-only correction: use normal npm installation and released status, describe deployed unified-key/latest-NAV access, and remove stale preview wording. Runtime, public types, contracts and dependencies are unchanged from 0.5.0.
+
+## 0.5.0 — 31 October 2026
+
+Add `new Bharosa({ apiKey })` and `client.markets` for baseline market access. Support latest NAV by omitting the date on baseline and account-scoped NAV methods. Preserve existing auth forms, private authorization, production API origin and monthly limits on explicit historical dates.
+
+## 0.4.0 — 30 October 2026
+
+Add account-scoped Growth scheme performance and category return statistics. Preserve the api.bharosa.finance default introduced in 0.3.3 and explicit overrides. No investor monetary-performance, fund-AUM or stated-TER methods.
+
+## 0.3.3 — 30 October 2026
+
+Change the default API origin to https://api.bharosa.finance. No analytics changes.
 
 ## 0.3.2 — 30 October 2026
 
@@ -23,11 +40,11 @@ Adds server-side BharosaMarket for four authenticated registered-app monthly mar
 - Clarify that monthly market reads require authenticated account-read access without a separate market-data approval.
 - Preserve existing methods, exports, authentication, quantity precision, and analytics implementation. Requires a companion API with portfolio lifecycle support; package preparation does not establish production availability.
 
-The entries below retain historical preparation notes from the published 0.1.0 package. They are not additional changes in 0.2.0.
+The entries below are archived preparation notes retained for provenance, not current installation or release instructions. Their historical “unreleased” and “pending” labels describe preparation at that time.
 
-## 0.1.0 — release candidate
+## 0.1.0 — published
 
-Prepared for the first npm release; publication is pending registry authentication and verification. API deployment and external consent activation are separate.
+Initial npm release. API deployment and external consent activation are separate.
 
 - Typed Node.js client with ESM/CommonJS exports, account-scoped direct/delegated authentication, and 17 public resource operations.
 - Portfolio asset, sector, and issuer mix methods for saved and in-memory targets, with MutualFund conveniences delegated to their underlying Portfolio.

package/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-This is an unpublished SDK under local preparation. Keep changes limited to the client, public contracts, documentation, and synthetic tests. Do not copy API implementation, analytics code, provider data, credentials, or internal operational notes into this repository.
+This repository contains the published Bharosa SDK. Keep changes limited to the client, public contracts, documentation, and synthetic tests. Do not copy API implementation, analytics code, provider data, credentials, or internal operational notes into this repository.
 
 ## Development
 

package/MARKET-SEARCH-CONTRACT-SHA256

@@ -0,0 +1 @@
+49577eff1da1c0b5badeb61136ee64f8ed35eab4e68f040d4341016475d4d646

package/README.md

@@ -2,19 +2,19 @@
 
 A TypeScript client for Bharosa accounts, investors, portfolios, and mutual funds. Use one resource interface from TypeScript, ESM, or CommonJS, with no runtime dependencies.
 
-**Local release candidate (unpublished):** `bharosa@0.5.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.
+**Published on npm:** `bharosa`. 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 reviewed local candidate in your backend application:
+Use Node.js 22.12+ in a supported LTS release. Install the SDK in your backend application:
 
 ```sh
-npm install /absolute/path/to/bharosa-0.5.0.tgz --ignore-scripts
+npm install bharosa
 ```
 
 Source contributors can build and pack a local archive using the commands in CONTRIBUTING.md.
 
-Configure your API key through your backend secret manager. In the local unified-key API candidate, every active key has baseline market access; private account calls require the optional account permissions. Then:
+Configure your API key through your backend secret manager. Every active, unexpired API key has baseline market access; private account calls require the optional account permissions. Then:
 
 ```ts
 import { Bharosa } from "bharosa";
@@ -116,11 +116,11 @@ The optional `bharosa/testing` entrypoint supplies fresh, deterministic syntheti
 
 Unit precision: supplied units accept at most four fractional digits; additional digits are rejected, never truncated. Dated amount conversion rounds once to four places using decimal half-even arithmetic; a positive amount rounding to zero returns `units_below_precision`. Currency and NAV precision are unchanged. Exact historical quantities and provenance remain in stored evidence and read responses; the web marks rounded displays with ≈, shows tiny positive values as <0.0001, and makes a rounded edit draft an explicit correction. Existing zero-unit closure remains supported; initial quantities must be positive. No portfolio reset or data rewrite is required. 
 
-After installing the archive, run `node node_modules/bharosa/examples/offline-smoke.mjs` for a credential-free synthetic read. This checks installed imports and the transport path without contacting Bharosa or creating data. It does not prove live access. Source-checkout verification commands require contributor files that are intentionally excluded from the runtime archive.
+After installing the package, run `node node_modules/bharosa/examples/offline-smoke.mjs` for a credential-free synthetic read. This checks installed imports and the transport path without contacting Bharosa or creating data. It does not prove live access. Source-checkout verification commands require contributor files that are intentionally excluded from the runtime archive.
 
-### Registered-app monthly data
+### Baseline market access
 
-Available in SDK 0.3.0 and activated at `https://api.bharosa.finance`. Server applications can use `new BharosaMarket({apiKey})` with an owner-issued `market_key` scoped only to `market:read`. `client.schemes.nav(id,{asOf:'2026-08-01'})`, `schemes.expenseRatio`, `funds.portfolio` and `funds.holdings` use account-independent monthly snapshot routes. These keys cannot read private accounts or portfolios and require no investor OAuth token. Keep secrets server-side; never bundle them into browser code. Existing account-key and delegated-user clients remain unchanged. The production control-plane environment is `production`. General third-party OAuth provisioning is separate and is not enabled by this feature.
+Use `new Bharosa({ apiKey })` and `client.markets` for account-independent latest NAV and monthly snapshots. Existing `new BharosaMarket({ apiKey })` clients remain compatible. Active, unexpired API keys have baseline market access without an investor OAuth token or a separate market-data approval. Legacy market-only keys still cannot access private accounts. Optional own-account permissions apply only to the key's authorized account; accessing another user's account still requires OAuth consent. Keep all secrets server-side.
 
 ### Optional API origin override
 
@@ -128,10 +128,25 @@ Set `baseUrl` only for another deployment or tests. Omitted or `undefined` uses
 
 ## 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 and the SDK 0.4.0 methods are published; this unified-key SDK candidate is not yet published. `BharosaMarket` retains its four monthly operations and cannot call account analytics.
+Adds `mutualFundSchemes.performance.retrieve` and `fundCategories.statistics.retrieve` for authenticated account access. See [analytics methods, coverage and limitations](docs/analytics.md). These API routes and SDK methods are published. `BharosaMarket` retains its four monthly operations and cannot call account analytics.
 
-## Unified-key candidate
+## Unified API keys
 
-This local 0.5.0 candidate adds `new Bharosa({ apiKey })` and `client.markets`, using the existing account-independent market routes. Omit the NAV selection for latest NAV, or pass `{ asOf: "2026-10-01" }` for a monthly snapshot. Missing observations return `status: "missing"` and `data: null`. Explicit dates must be month starts. The account-scoped NAV method also accepts omission, while keeping account authorization.
+SDK 0.5.0 introduced `new Bharosa({ apiKey })` and `client.markets`, using the existing account-independent market routes. Omit the NAV selection for latest NAV, or pass `{ asOf: "2026-10-01" }` for a monthly snapshot. Missing observations return `status: "missing"` and `data: null`. Explicit dates must be month starts. The account-scoped NAV method also accepts omission, while keeping account authorization.
 
-Existing `auth` configurations and `BharosaMarket` remain supported. Baseline calls use only the API key; delegated private calls still require user consent and a valid user token. The production origin remains `https://api.bharosa.finance`. Unified-key server changes are locally tested and pending coordinated activation; this archive alone does not activate permissions.
+Existing `auth` configurations and `BharosaMarket` remain supported. Baseline calls use only the API key; delegated private calls still require user consent and a valid user token. The production origin remains `https://api.bharosa.finance`. Unified-key support is deployed. Private permissions remain optional and are enforced by the server; installing the SDK grants no additional access.
+
+## Find a scheme with baseline market access
+
+```ts
+const choices = await bharosa.markets.schemes.search({ query: "equity", limit: 5 });
+const selected = choices.data[0];
+if (selected) {
+  const nav = await bharosa.markets.schemes.nav(selected.scheme_id);
+  console.log(selected.plan_label, selected.option_label, nav.status);
+}
+```
+
+Choose the intended scheme and plan from the results. `query` must have 2–100 characters, with at least two after trimming; `limit` is 1–20 and defaults to 10. If `has_more` is true, refine the query; search has no cursor or historical date parameter. An empty `data` array is a valid result. Search returns scheme identities and latest NAV references, including freshness and data-mode information. It does not grant private account access. Existing `mutualFunds.search` remains account-scoped. `BharosaMarket` users can call `schemes.search` directly.
+
+Available in SDK 0.6.0 and later, using the account-independent `/v1/market-data/schemes/search` route.

package/dist/index.cjs

@@ -399,7 +399,7 @@ class Bharosa {
     }
 }
 exports.Bharosa = Bharosa;
-/** Server-only registered-app monthly market access. No account or user token. */
+/** Server-only baseline market access. No account or user token. */
 class BharosaMarket {
     schemes;
     funds;
@@ -431,6 +431,11 @@ function baselineMarkets(call) {
         };
     };
     const schemes = {
+        search: async (p, o) => {
+            (0, transport_cjs_1.keys)(p, ["query", "limit"]);
+            (0, transport_cjs_1.check)(typeof p.query === "string" && p.query.trim().length >= 2 && p.query.length <= 100);
+            return call("searchMarketSchemes", p, undefined, o);
+        },
         nav: (id, q = {}, o) => {
             (0, transport_cjs_1.keys)(q, ["asOf"]);
             return call("monthly_nav", { id, ...(q.asOf === undefined ? {} : { as_of: q.asOf }) }, undefined, o);

package/dist/index.d.cts

@@ -2,6 +2,7 @@ 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";
+import type * as M from "./models.cjs";
 import type * as D from "./market-types.cjs";
 export type * from "./client-types.cjs";
 export * from "./errors.cjs";
@@ -26,7 +27,7 @@ export interface BharosaMarketConfig {
     maxResponseBytes?: number;
     fetch?: typeof globalThis.fetch;
 }
-/** Server-only registered-app monthly market access. No account or user token. */
+/** Server-only baseline market access. No account or user token. */
 export declare class BharosaMarket {
     readonly schemes: BaselineMarketClient["schemes"];
     readonly funds: MonthlyMarketClient["funds"];
@@ -34,6 +35,10 @@ export declare class BharosaMarket {
 }
 export interface BaselineMarketClient {
     readonly schemes: {
+        search(query: {
+            query: string;
+            limit?: number;
+        }, options?: T.RequestOptions): Promise<M.FundsList>;
         nav(id: string, selection?: {
             asOf?: string;
         }, options?: T.RequestOptions): ReturnType<MonthlyMarketClient["schemes"]["nav"]>;

package/dist/index.d.ts

@@ -2,6 +2,7 @@ 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";
+import type * as M from "./models.js";
 import type * as D from "./market-types.js";
 export type * from "./client-types.js";
 export * from "./errors.js";
@@ -26,7 +27,7 @@ export interface BharosaMarketConfig {
     maxResponseBytes?: number;
     fetch?: typeof globalThis.fetch;
 }
-/** Server-only registered-app monthly market access. No account or user token. */
+/** Server-only baseline market access. No account or user token. */
 export declare class BharosaMarket {
     readonly schemes: BaselineMarketClient["schemes"];
     readonly funds: MonthlyMarketClient["funds"];
@@ -34,6 +35,10 @@ export declare class BharosaMarket {
 }
 export interface BaselineMarketClient {
     readonly schemes: {
+        search(query: {
+            query: string;
+            limit?: number;
+        }, options?: T.RequestOptions): Promise<M.FundsList>;
         nav(id: string, selection?: {
             asOf?: string;
         }, options?: T.RequestOptions): ReturnType<MonthlyMarketClient["schemes"]["nav"]>;

package/dist/market-search.cjs

@@ -0,0 +1,357 @@
+"use strict";
+// Generated from the canonical market search contract; all references resolved locally.
+module.exports = {
+  "operations": {
+    "searchMarketSchemes": {
+      "path": "/v1/market-data/schemes/search",
+      "method": "GET",
+      "status": 200,
+      "marketData": true,
+      "readOnly": true,
+      "parameters": [
+        {
+          "name": "query",
+          "in": "query",
+          "required": true,
+          "description": "2–100 characters. Case-insensitive label and identifier search; percent and underscore are literal.",
+          "schema": {
+            "type": "string",
+            "minLength": 2,
+            "maxLength": 100
+          }
+        },
+        {
+          "name": "limit",
+          "in": "query",
+          "required": false,
+          "description": "1–20; default 10. Search is a bounded result set, not cursor pagination.",
+          "schema": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 20,
+            "default": 10
+          }
+        }
+      ],
+      "response": {
+        "type": "object",
+        "properties": {
+          "object": {
+            "const": "list"
+          },
+          "data": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "instrument": {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string",
+                      "pattern": "^ins_[A-Za-z0-9_-]{1,150}$"
+                    },
+                    "object": {
+                      "const": "instrument"
+                    },
+                    "created": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 9007199254740991
+                    },
+                    "name": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 200,
+                      "pattern": "\\S"
+                    },
+                    "identifiers": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "namespace": {
+                            "type": "string"
+                          },
+                          "value": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "namespace",
+                          "value"
+                        ],
+                        "additionalProperties": true
+                      }
+                    },
+                    "domicile_country": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "type": {
+                      "const": "mutual_fund"
+                    },
+                    "mutual_fund": {
+                      "type": "object",
+                      "properties": {
+                        "fund_name": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 200,
+                          "pattern": "\\S"
+                        },
+                        "share_class": {
+                          "anyOf": [
+                            {
+                              "type": "string"
+                            },
+                            {
+                              "type": "null"
+                            }
+                          ]
+                        },
+                        "class_currency": {
+                          "anyOf": [
+                            {
+                              "type": "string"
+                            },
+                            {
+                              "type": "null"
+                            }
+                          ]
+                        },
+                        "distribution_policy": {
+                          "type": "string",
+                          "x-known-values": [
+                            "accumulating",
+                            "distributing",
+                            "unknown"
+                          ],
+                          "minLength": 1
+                        }
+                      },
+                      "required": [
+                        "fund_name",
+                        "share_class",
+                        "class_currency",
+                        "distribution_policy"
+                      ],
+                      "additionalProperties": true
+                    }
+                  },
+                  "required": [
+                    "id",
+                    "object",
+                    "created",
+                    "name",
+                    "identifiers",
+                    "domicile_country",
+                    "type",
+                    "mutual_fund"
+                  ],
+                  "additionalProperties": true
+                },
+                "market": {
+                  "const": "IN"
+                },
+                "currency": {
+                  "const": "INR"
+                },
+                "scheme_id": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Opaque catalogue identifier; production bridge accepts validated positive decimal scheme IDs, fixture IDs are not DB IDs."
+                },
+                "plan_label": {
+                  "type": "string"
+                },
+                "option_label": {
+                  "type": "string"
+                },
+                "amfi_code": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "isin": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "identity_status": {
+                  "type": "string",
+                  "x-known-values": [
+                    "resolved",
+                    "conflict"
+                  ],
+                  "minLength": 1
+                },
+                "latest_nav": {
+                  "anyOf": [
+                    {
+                      "type": "object",
+                      "properties": {
+                        "amount": {
+                          "type": "string",
+                          "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{1,18})?$"
+                        },
+                        "currency": {
+                          "const": "INR"
+                        },
+                        "date": {
+                          "type": "string",
+                          "format": "date",
+                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+                          "description": "Real calendar date, 1900-01-01 through today Asia/Kolkata; replacement cannot move backwards."
+                        }
+                      },
+                      "required": [
+                        "amount",
+                        "currency",
+                        "date"
+                      ],
+                      "additionalProperties": true
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "data_mode": {
+                  "type": "string",
+                  "x-known-values": [
+                    "live",
+                    "fixture"
+                  ],
+                  "minLength": 1
+                },
+                "source": {
+                  "type": "string"
+                },
+                "freshness": {
+                  "type": "object",
+                  "properties": {
+                    "status": {
+                      "type": "string",
+                      "x-known-values": [
+                        "recent",
+                        "stale",
+                        "missing",
+                        "invalid",
+                        "fixture"
+                      ],
+                      "minLength": 1
+                    },
+                    "checked_at": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "as_of": {
+                      "type": "string",
+                      "format": "date",
+                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+                      "description": "Real calendar date, 1900-01-01 through today Asia/Kolkata; replacement cannot move backwards."
+                    },
+                    "time_zone": {
+                      "const": "Asia/Kolkata"
+                    },
+                    "age_days": {
+                      "anyOf": [
+                        {
+                          "type": "integer"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "recent_within_days": {
+                      "const": 3
+                    }
+                  },
+                  "required": [
+                    "status",
+                    "checked_at",
+                    "as_of",
+                    "time_zone",
+                    "age_days",
+                    "recent_within_days"
+                  ],
+                  "additionalProperties": true
+                }
+              },
+              "required": [
+                "instrument",
+                "market",
+                "currency",
+                "scheme_id",
+                "plan_label",
+                "option_label",
+                "amfi_code",
+                "isin",
+                "identity_status",
+                "latest_nav",
+                "data_mode",
+                "source",
+                "freshness"
+              ],
+              "additionalProperties": true
+            }
+          },
+          "has_more": {
+            "type": "boolean"
+          },
+          "url": {
+            "type": "string"
+          },
+          "market_data": {
+            "type": "object",
+            "properties": {
+              "mode": {
+                "type": "string",
+                "x-known-values": [
+                  "live",
+                  "fixture",
+                  "unavailable"
+                ],
+                "minLength": 1
+              },
+              "notice": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "mode",
+              "notice"
+            ],
+            "additionalProperties": true
+          }
+        },
+        "required": [
+          "object",
+          "data",
+          "has_more",
+          "url",
+          "market_data"
+        ],
+        "additionalProperties": true
+      }
+    }
+  }
+};

package/dist/market-search.d.cts

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

package/dist/market-search.d.ts

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

package/dist/operation-types.d.cts

@@ -5,6 +5,7 @@ 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 {
+    searchMarketSchemes: M.FundsList;
     analytics_scheme: A.SchemePerformance;
     analytics_category: A.CategoryStatistics;
     monthly_nav: S.MarketSnapshot<D.NavObservation>;

package/dist/operation-types.d.ts

@@ -5,6 +5,7 @@ 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 {
+    searchMarketSchemes: M.FundsList;
     analytics_scheme: A.SchemePerformance;
     analytics_category: A.CategoryStatistics;
     monthly_nav: S.MarketSnapshot<D.NavObservation>;

package/dist/response-checks.cjs

@@ -55,6 +55,11 @@ function responseMatches(id, op, data, params, body, account) {
             (typeof params.limit === "number" && page.length > params.limit))
             return false;
     }
+    if (id === "searchMarketSchemes") {
+        const page = rows(d("data"));
+        if (d("url") !== op.path || page.length > (typeof params.limit === "number" ? params.limit : 10) || (d("has_more") === true && page.length === 0))
+            return false;
+    }
     if (op.marketData) {
         if (id.endsWith("_get") && d("id") !== params.id)
             return false;

package/dist/transport.cjs

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.check = check;
 exports.keys = keys;
 exports.createTransport = createTransport;
+const market_search_cjs_1 = require("./market-search.cjs");
 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");
@@ -15,6 +16,7 @@ const operations = {
     ...market_data_cjs_1.operations,
     ...monthly_market_data_cjs_1.operations,
     ...analytics_contract_cjs_1.operations,
+    ...market_search_cjs_1.operations,
 };
 function assertServer() {
     if (typeof window !== "undefined" ||
@@ -209,7 +211,7 @@ function createTransport(input, marketOnly = false) {
     const call = async (id, params = {}, body, opts = {}) => {
         const op = operations[id];
         if (marketOnly &&
-            !["monthly_nav", "monthly_expense", "monthly_portfolio", "monthly_holdings"].includes(id)) {
+            !["monthly_nav", "monthly_expense", "monthly_portfolio", "monthly_holdings", "searchMarketSchemes"].includes(id)) {
             throw Object.assign(new errors_cjs_1.ValidationError(), { code: "market_only_operation" });
         }
         let o, serialized, url;

package/docs/analytics.md

@@ -1,6 +1,6 @@
 # Growth scheme performance and category returns
 
-The two analytics methods are deployed and published in SDK 0.4.0. This local unified-key successor preserves them. Default origin is https://api.bharosa.finance; explicit baseUrl overrides remain supported. Account authorization with accounts:read is required. BharosaMarket does not expose these methods.
+The two analytics methods are deployed and published in SDK 0.4.0. SDK 0.5.0 and later preserve them. Default origin is https://api.bharosa.finance; explicit baseUrl overrides remain supported. Account authorization with accounts:read is required. BharosaMarket does not expose these methods.
 
 ```ts
 import { Bharosa } from "bharosa";

package/docs/getting-started.md

@@ -4,18 +4,20 @@
 
 Use Node.js 22.12 or later in a supported LTS release. The SDK supports ESM and CommonJS. Key-based authentication is server-only; keep credentials in your backend or server that handles browser sessions. Browser applications can supply a generic transport whose private host implementation manages sessions, origin restrictions and CSRF. Bun and Deno are unsupported.
 
-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.
+Obtain an API key. For private account calls, enable the needed optional own-account permissions; the simple API-key configuration defaults to account selector `me`. 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 the unpublished 0.5.0 candidate
+## Install from npm
 
 ```sh
-npm install /absolute/path/to/bharosa-0.5.0.tgz --ignore-scripts
+npm install bharosa
 ```
 
 Source contributors can build and pack a local archive as described in CONTRIBUTING.md.
 
 ## Read your account
 
+This call requires the optional own-account read permission. An account ID is not a prerequisite: the API-key shorthand selects `me`. Use an explicit `account` only when needed; delegated access uses the server-authorized account.
+
 In an ESM application, save this as `account.mjs`:
 
 ```js
@@ -28,14 +30,13 @@ function required(name) {
 }
 
 const bharosa = new Bharosa({
-  account: required("BHAROSA_ACCOUNT_ID"),
-  auth: { type: "account_key", apiKey: required("BHAROSA_SECRET_KEY") },
+  apiKey: required("BHAROSA_SECRET_KEY"),
 });
 const account = await bharosa.accounts.retrieve();
 console.log(account.id);
 ```
 
-Supply those variables through your application's secret management, then run `node account.mjs`. Do not commit their values. For another deployment or tests, explicitly supply `baseUrl`. It must use HTTPS and contain no path, query, user information, or fragment; local HTTP additionally requires `allowLocalhostHttp: true`. Invalid explicit origins fail before sending a request.
+Supply `BHAROSA_SECRET_KEY` through your application's secret management, then run `node account.mjs`. Do not commit their values. For another deployment or tests, explicitly supply `baseUrl`. It must use HTTPS and contain no path, query, user information, or fragment; local HTTP additionally requires `allowLocalhostHttp: true`. Invalid explicit origins fail before sending a request.
 
 CommonJS applications use `const { Bharosa } = require("bharosa")` inside an async function. TypeScript applications import types from the same root package; do not import files from `dist/`.
 

package/docs/index.md

@@ -1,8 +1,8 @@
 # Bharosa SDK guides
 
-Build a Node.js integration with the Bharosa resource API. This SDK is not yet published on npm; install it from a local archive. Ask your service operator for API access separately.
+Build a Node.js integration with the Bharosa resource API. Install the published SDK with `npm install bharosa`. Use an API key for baseline market data and optional authorized own-account access; other users' accounts require OAuth consent.
 
-1. [Install locally and make your first request](getting-started.md).
+1. [Install and make your first request](getting-started.md).
 2. [Work with portfolios and mixes](portfolios.md).
 3. [Handle errors, cancellation, and retries](reliability.md).
 4. [Use monthly market snapshots](monthly-market-data.md).

package/docs/monthly-market-data.md

@@ -1,6 +1,19 @@
-# Monthly market snapshots
+# Latest NAV and monthly market snapshots
 
-`client.mutualFundSchemes` and `client.mutualFunds.portfolios` provide month-start market history and current NAV valuation. Monthly market data requires no separate application approval. Use authenticated credentials with the required account-read scope; installing the SDK does not authenticate you or grant private account access. Availability still depends on the deployed service and source data.
+Use `new Bharosa({ apiKey })` and `client.markets` for baseline market access with any active, unexpired API key. No account permission, investor token or separate market-data approval is required on these account-independent routes. Existing account-scoped methods retain account authorization; installing the SDK grants no private account access. Availability depends on source observations.
+
+```ts
+import { Bharosa } from "bharosa";
+const client = new Bharosa({ apiKey: process.env.BHAROSA_SECRET_KEY! });
+const latest = await client.markets.schemes.nav("45139");
+const monthly = await client.markets.schemes.nav("45139", { asOf: "2026-10-01" });
+```
+
+Baseline methods are `markets.schemes.nav`, `markets.schemes.expenseRatio`, `markets.funds.portfolio` and `markets.funds.holdings`. Omit the NAV selection for latest NAV; all explicit historical dates must be month starts. The remaining three methods require a monthly selection. `BharosaMarket` exposes the same baseline methods without the `markets` prefix.
+
+SDK 0.6.0 adds baseline discovery through `client.markets.schemes.search({ query: "equity", limit: 5 })`, returning `data`, `has_more`, `url` and `market_data`. Use a returned `scheme_id` for NAV and expense methods. Choose among the plan/option labels; do not assume the first result is the intended investment. Refine the query when `has_more` is true; no cursor or historical selection is accepted. Search uses the account-independent `/v1/market-data/schemes/search` route.
+
+The existing account-scoped discovery and analytics methods below retain their account permissions. Baseline access never grants private analytics.
 
 Resolve an investible scheme through `client.mutualFunds.search()` and its returned `scheme_id`. Fund-owner IDs and scheme IDs are distinct: NAV and expense ratios belong to schemes; portfolio snapshots and holdings belong to fund owners. Do not use an AMC ID as a fund-owner ID.
 
@@ -24,7 +37,7 @@ Replace the search term with a fund you intend to inspect and choose among the r
 
 Supported methods:
 
-- `mutualFundSchemes.navs.retrieve(schemeId, { asOf })`
+- `mutualFundSchemes.navs.retrieve(schemeId)` for latest NAV, or pass `{ asOf }` for a monthly snapshot
 - `mutualFundSchemes.expenseRatios.retrieve(schemeId, { asOf })`
 - `mutualFundSchemes.valuation(schemeId, { units })` for current value using the latest eligible NAV. Supply a month-start `asOf` for historical valuation. Actual NAV date and freshness are returned; old NAVs are not labelled today's prices.
 - `mutualFunds.portfolios.retrieve(fundOwnerId, { asOf })`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bharosa",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "private": false,
   "description": "Typed Bharosa resource SDK with server credentials or caller-owned transport.",
   "license": "MIT",
@@ -45,7 +45,8 @@
     "CHANGELOG.md",
     "FIRST-PARTY-CONTRACT-SHA256",
     "MONTHLY-MARKET-CONTRACT-SHA256",
-    "ANALYTICS-CONTRACT-SHA256"
+    "ANALYTICS-CONTRACT-SHA256",
+    "MARKET-SEARCH-CONTRACT-SHA256"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
@@ -61,7 +62,9 @@
     "generate:monthly": "node scripts/generate-monthly.mjs",
     "check:monthly": "node scripts/generate-monthly.mjs --check",
     "generate:analytics": "node scripts/generate-analytics.mjs",
-    "check:analytics": "node scripts/generate-analytics.mjs --check"
+    "check:analytics": "node scripts/generate-analytics.mjs --check",
+    "generate:market-search": "node scripts/generate-market-search.mjs",
+    "check:market-search": "node scripts/generate-market-search.mjs --check"
   },
   "publishConfig": {
     "access": "public",