bharosa 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.6.0
+
+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.

package/MARKET-SEARCH-CONTRACT-SHA256

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

package/README.md

@@ -135,3 +135,18 @@ Adds `mutualFundSchemes.performance.retrieve` and `fundCategories.statistics.ret
 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 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/getting-started.md

@@ -16,6 +16,8 @@ Source contributors can build and pack a local archive as described in CONTRIBUT
 
 ## 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/monthly-market-data.md

@@ -11,7 +11,9 @@ 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.
 
-The discovery and account-scoped methods below require their existing account permissions. A baseline-only key does not gain access to scheme search or private analytics.
+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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bharosa",
-  "version": "0.5.1",
+  "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",