bharosa 0.4.0 → 0.5.0

package/ANALYTICS-CONTRACT-SHA256

@@ -1 +1 @@
-ebab801a241565a3b115993b6ae8470d144f8d69f79cdb8acc274ff8c200cf3e
+1d2d37edf6ea65cdd3bac707119c6815ee73c89770a791d7dfdfadc9630b6f2b

package/MONTHLY-MARKET-CONTRACT-SHA256

@@ -1 +1 @@
-29463b6a150e368a47ac11e2f8f841e3808d94d3ff9b70221fe3804c93b91004
+ef53094920c324ab9d9fd31d8846b6f37da13b757301c6742461ee33b8fe49c4

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.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.
+**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.
 
 ## Start here
 
 Use Node.js 22.12+ in a supported LTS release. Install the reviewed local candidate in your backend application:
 
 ```sh
-npm install /absolute/path/to/bharosa-0.4.0.tgz --ignore-scripts
+npm install /absolute/path/to/bharosa-0.5.0.tgz --ignore-scripts
 ```
 
 Source contributors can build and pack a local archive using the commands in CONTRIBUTING.md.
 
-Configure your application's account ID and account key through its secret manager. Then:
+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:
 
 ```ts
 import { Bharosa } from "bharosa";
@@ -25,10 +25,11 @@ function required(name: string): string {
   return value;
 }
 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();
+const latestNav = await bharosa.markets.schemes.nav("45139");
+// Optional own-account permission is required for this call:
+// const account = await bharosa.accounts.retrieve();
 ```
 
 The startup check names missing environment variables without printing their values. See the [complete setup guide](docs/getting-started.md) for explicit checks and delegated authentication. CommonJS uses `const { Bharosa } = require("bharosa")`.
@@ -127,4 +128,10 @@ 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 are deployed; this 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 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.
+
+## Unified-key candidate
+
+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.
+
+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.

package/dist/client-types.d.cts

@@ -24,7 +24,7 @@ interface BharosaBaseConfig {
     readonly allowLocalhostHttp?: boolean;
     readonly maxResponseBytes?: number;
 }
-export type BharosaConfig = BharosaBaseConfig & ({
+type LegacyBharosaConfig = BharosaBaseConfig & ({
     readonly auth: Auth;
     readonly fetch?: typeof globalThis.fetch;
     readonly transport?: never;
@@ -33,6 +33,17 @@ export type BharosaConfig = BharosaBaseConfig & ({
     readonly auth?: never;
     readonly fetch?: never;
 });
+/** Simple server-side API-key configuration. Account access remains server-authorized. */
+export type BharosaConfig = LegacyBharosaConfig | {
+    readonly apiKey: string;
+    readonly account?: string;
+    readonly baseUrl?: string;
+    readonly allowLocalhostHttp?: boolean;
+    readonly maxResponseBytes?: number;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly auth?: never;
+    readonly transport?: never;
+};
 export interface RequestOptions {
     idempotencyKey?: string;
     signal?: AbortSignal;

package/dist/client-types.d.ts

@@ -24,7 +24,7 @@ interface BharosaBaseConfig {
     readonly allowLocalhostHttp?: boolean;
     readonly maxResponseBytes?: number;
 }
-export type BharosaConfig = BharosaBaseConfig & ({
+type LegacyBharosaConfig = BharosaBaseConfig & ({
     readonly auth: Auth;
     readonly fetch?: typeof globalThis.fetch;
     readonly transport?: never;
@@ -33,6 +33,17 @@ export type BharosaConfig = BharosaBaseConfig & ({
     readonly auth?: never;
     readonly fetch?: never;
 });
+/** Simple server-side API-key configuration. Account access remains server-authorized. */
+export type BharosaConfig = LegacyBharosaConfig | {
+    readonly apiKey: string;
+    readonly account?: string;
+    readonly baseUrl?: string;
+    readonly allowLocalhostHttp?: boolean;
+    readonly maxResponseBytes?: number;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly auth?: never;
+    readonly transport?: never;
+};
 export interface RequestOptions {
     idempotencyKey?: string;
     signal?: AbortSignal;

package/dist/index.cjs

@@ -45,9 +45,11 @@ class Bharosa {
     fundCategories;
     mutualFunds;
     mutualFundSchemes;
+    markets;
     marketSnapshots;
     marketData;
     constructor(config) {
+        this.markets = baselineMarkets((0, transport_cjs_1.createTransport)(config, true));
         const call = (0, transport_cjs_1.createTransport)(config);
         const analyticsQuery = (q, extra = []) => {
             (0, transport_cjs_1.keys)(q, ["asOf", "periods", ...extra]);
@@ -314,7 +316,10 @@ class Bharosa {
         };
         this.marketSnapshots = {
             schemes: {
-                nav: (id, q, o) => call("monthly_nav", { id, ...monthlyQuery(q) }, 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);
+                },
                 expenseRatio: (id, q, o) => call("monthly_expense", { id, ...monthlyQuery(q) }, undefined, o),
                 valuation: (id, input = {}, o) => {
                     (0, transport_cjs_1.keys)(input, ["units", "asOf", "positionDate", "observedValue"]);
@@ -408,24 +413,33 @@ class BharosaMarket {
         ]);
         const { apiKey, ...rest } = config;
         const call = (0, transport_cjs_1.createTransport)({ ...rest, account: "me", auth: { type: "account_key", apiKey } }, true);
-        const query = (q, paging = false) => {
-            (0, transport_cjs_1.keys)(q, paging ? ["asOf", "limit", "startingAfter"] : ["asOf"]);
-            return {
-                as_of: q.asOf,
-                ...(q.limit === undefined ? {} : { limit: q.limit }),
-                ...(q.startingAfter === undefined
-                    ? {}
-                    : { starting_after: q.startingAfter }),
-            };
-        };
-        this.schemes = {
-            nav: (id, q, o) => call("monthly_nav", { id, ...query(q) }, undefined, o),
-            expenseRatio: (id, q, o) => call("monthly_expense", { id, ...query(q) }, undefined, o),
-        };
-        this.funds = {
-            portfolio: (id, q, o) => call("monthly_portfolio", { id, ...query(q) }, undefined, o),
-            holdings: (id, q, o) => call("monthly_holdings", { id, ...query(q, true) }, undefined, o),
-        };
+        const resources = baselineMarkets(call);
+        this.schemes = resources.schemes;
+        this.funds = resources.funds;
     }
 }
 exports.BharosaMarket = BharosaMarket;
+function baselineMarkets(call) {
+    const query = (q, paging = false) => {
+        (0, transport_cjs_1.keys)(q, paging ? ["asOf", "limit", "startingAfter"] : ["asOf"]);
+        return {
+            as_of: q.asOf,
+            ...(q.limit === undefined ? {} : { limit: q.limit }),
+            ...(q.startingAfter === undefined
+                ? {}
+                : { starting_after: q.startingAfter }),
+        };
+    };
+    const schemes = {
+        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);
+        },
+        expenseRatio: (id, q, o) => call("monthly_expense", { id, ...query(q) }, undefined, o),
+    };
+    const funds = {
+        portfolio: (id, q, o) => call("monthly_portfolio", { id, ...query(q) }, undefined, o),
+        holdings: (id, q, o) => call("monthly_holdings", { id, ...query(q, true) }, undefined, o),
+    };
+    return Object.freeze({ schemes: Object.freeze(schemes), funds: Object.freeze(funds) });
+}

package/dist/index.d.cts

@@ -13,6 +13,7 @@ export declare class Bharosa implements T.ClientSurface {
     readonly fundCategories: T.ClientSurface["fundCategories"];
     readonly mutualFunds: T.ClientSurface["mutualFunds"];
     readonly mutualFundSchemes: T.ClientSurface["mutualFundSchemes"];
+    readonly markets: BaselineMarketClient;
     readonly marketSnapshots: MonthlyMarketClient;
     readonly marketData: D.MarketDataClient;
     constructor(config: T.BharosaConfig);
@@ -27,7 +28,16 @@ export interface BharosaMarketConfig {
 }
 /** Server-only registered-app monthly market access. No account or user token. */
 export declare class BharosaMarket {
-    readonly schemes: Pick<MonthlyMarketClient["schemes"], "nav" | "expenseRatio">;
+    readonly schemes: BaselineMarketClient["schemes"];
     readonly funds: MonthlyMarketClient["funds"];
     constructor(config: BharosaMarketConfig);
 }
+export interface BaselineMarketClient {
+    readonly schemes: {
+        nav(id: string, selection?: {
+            asOf?: string;
+        }, options?: T.RequestOptions): ReturnType<MonthlyMarketClient["schemes"]["nav"]>;
+        expenseRatio: MonthlyMarketClient["schemes"]["expenseRatio"];
+    };
+    readonly funds: MonthlyMarketClient["funds"];
+}

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export declare class Bharosa implements T.ClientSurface {
     readonly fundCategories: T.ClientSurface["fundCategories"];
     readonly mutualFunds: T.ClientSurface["mutualFunds"];
     readonly mutualFundSchemes: T.ClientSurface["mutualFundSchemes"];
+    readonly markets: BaselineMarketClient;
     readonly marketSnapshots: MonthlyMarketClient;
     readonly marketData: D.MarketDataClient;
     constructor(config: T.BharosaConfig);
@@ -27,7 +28,16 @@ export interface BharosaMarketConfig {
 }
 /** Server-only registered-app monthly market access. No account or user token. */
 export declare class BharosaMarket {
-    readonly schemes: Pick<MonthlyMarketClient["schemes"], "nav" | "expenseRatio">;
+    readonly schemes: BaselineMarketClient["schemes"];
     readonly funds: MonthlyMarketClient["funds"];
     constructor(config: BharosaMarketConfig);
 }
+export interface BaselineMarketClient {
+    readonly schemes: {
+        nav(id: string, selection?: {
+            asOf?: string;
+        }, options?: T.RequestOptions): ReturnType<MonthlyMarketClient["schemes"]["nav"]>;
+        expenseRatio: MonthlyMarketClient["schemes"]["expenseRatio"];
+    };
+    readonly funds: MonthlyMarketClient["funds"];
+}

package/dist/monthly-market-data.cjs

@@ -29,12 +29,13 @@ module.exports = {
         {
           "name": "as_of",
           "in": "query",
-          "required": true,
+          "required": false,
           "schema": {
             "type": "string",
             "format": "date",
             "pattern": "^[0-9]{4}-[0-9]{2}-01$"
-          }
+          },
+          "description": "Omit for latest NAV on or before today in Asia/Kolkata. When supplied, must be the first of a month and not in the future. Actual observation date is returned separately."
         }
       ],
       "response": {

package/dist/monthly-types.d.cts

@@ -21,7 +21,7 @@ export interface MonthSelection {
 }
 export interface MonthlyMarketClient {
     schemes: {
-        nav(id: string, query: MonthSelection, options?: RequestOptions): Promise<MarketSnapshot<D.NavObservation>>;
+        nav(id: string, query?: Partial<MonthSelection>, options?: RequestOptions): Promise<MarketSnapshot<D.NavObservation>>;
         expenseRatio(id: string, query: MonthSelection, options?: RequestOptions): Promise<MarketSnapshot<D.ExpenseObservation>>;
         valuation(id: string, input?: D.ValuationInput, options?: RequestOptions): Promise<D.LatestNavValuation>;
     };

package/dist/monthly-types.d.ts

@@ -21,7 +21,7 @@ export interface MonthSelection {
 }
 export interface MonthlyMarketClient {
     schemes: {
-        nav(id: string, query: MonthSelection, options?: RequestOptions): Promise<MarketSnapshot<D.NavObservation>>;
+        nav(id: string, query?: Partial<MonthSelection>, options?: RequestOptions): Promise<MarketSnapshot<D.NavObservation>>;
         expenseRatio(id: string, query: MonthSelection, options?: RequestOptions): Promise<MarketSnapshot<D.ExpenseObservation>>;
         valuation(id: string, input?: D.ValuationInput, options?: RequestOptions): Promise<D.LatestNavValuation>;
     };

package/dist/response-checks.cjs

@@ -190,7 +190,7 @@ function responseMatches(id, op, data, params, body, account) {
     }
     if (id.startsWith("monthly_") && id !== "monthly_valuation") {
         const observation = d("observation_date"), requested = d("requested_date"), data = d("data");
-        if (requested !== params.as_of)
+        if (!(id === "monthly_nav" && params.as_of === undefined) && requested !== params.as_of)
             return false;
         if (d("status") === "available") {
             if (typeof observation !== "string" ||

package/dist/transport.cjs

@@ -143,7 +143,17 @@ async function read(response, max, signal) {
         reader.releaseLock();
     }
 }
-function createTransport(config, marketOnly = false) {
+function createTransport(input, marketOnly = false) {
+    let config;
+    if (input != null && typeof input === "object" && Object.hasOwn(input, "apiKey")) {
+        keys(input, ["apiKey", "account", "baseUrl", "allowLocalhostHttp", "maxResponseBytes", "fetch"]);
+        const simple = input;
+        const { apiKey, account, ...rest } = simple;
+        config = { ...rest, account: account === undefined ? "me" : account, auth: { type: "account_key", apiKey } };
+    }
+    else {
+        config = input;
+    }
     const customTransport = config?.transport !== undefined;
     if (!customTransport)
         assertServer();
@@ -177,7 +187,7 @@ function createTransport(config, marketOnly = false) {
             (a.type === "delegated_application" && token(a.userAccessToken)));
         headers = Object.freeze({
             Authorization: "Bearer " + a.apiKey,
-            ...(a.type === "delegated_application"
+            ...(a.type === "delegated_application" && !marketOnly
                 ? { "Bharosa-User-Authorization": "Bearer " + a.userAccessToken }
                 : {}),
             Accept: "application/json",

package/dist/transport.d.cts

@@ -2,4 +2,4 @@ import type { OperationResults } from "./operation-types.cjs";
 import type { BharosaConfig, RequestOptions } from "./client-types.cjs";
 export declare function check(v: unknown): asserts v;
 export declare function keys(v: unknown, allowed: readonly string[]): void;
-export declare function createTransport(config: BharosaConfig, marketOnly?: boolean): <K extends keyof OperationResults>(id: K, params?: Record<string, unknown>, body?: unknown, opts?: RequestOptions) => Promise<OperationResults[K]>;
+export declare function createTransport(input: BharosaConfig, marketOnly?: boolean): <K extends keyof OperationResults>(id: K, params?: Record<string, unknown>, body?: unknown, opts?: RequestOptions) => Promise<OperationResults[K]>;

package/dist/transport.d.ts

@@ -2,4 +2,4 @@ import type { OperationResults } from "./operation-types.js";
 import type { BharosaConfig, RequestOptions } from "./client-types.js";
 export declare function check(v: unknown): asserts v;
 export declare function keys(v: unknown, allowed: readonly string[]): void;
-export declare function createTransport(config: BharosaConfig, marketOnly?: boolean): <K extends keyof OperationResults>(id: K, params?: Record<string, unknown>, body?: unknown, opts?: RequestOptions) => Promise<OperationResults[K]>;
+export declare function createTransport(input: BharosaConfig, marketOnly?: boolean): <K extends keyof OperationResults>(id: K, params?: Record<string, unknown>, body?: unknown, opts?: RequestOptions) => Promise<OperationResults[K]>;

package/docs/analytics.md

@@ -1,6 +1,6 @@
 # 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.
+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.
 
 ```ts
 import { Bharosa } from "bharosa";

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 the unpublished 0.4.0 candidate
+## Install the unpublished 0.5.0 candidate
 
 ```sh
-npm install /absolute/path/to/bharosa-0.4.0.tgz --ignore-scripts
+npm install /absolute/path/to/bharosa-0.5.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.4.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Typed Bharosa resource SDK with server credentials or caller-owned transport.",
   "license": "MIT",