bharosa 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,10 +1,18 @@
-# 0.3.0 — local keys-only release candidate (unpublished)
+# Changelog
 
-Adds server-side BharosaMarket for four registered-app monthly snapshot operations, with no investor token/account argument. Requires separately activated API market_key support. Includes lifecycle0.2.0 changes; no unpublished analytics methods. Version0.3.0 was absent from npm at preparation, not reserved there.
+## 0.3.2 — 30 October 2026
 
-# Changelog
+Default omitted or undefined `baseUrl` to `https://app.bharosa.finance` in Bharosa and BharosaMarket. Preserve explicit overrides, origin validation, redirect rejection and credential boundaries. Remove required origin setup from beginner examples. No analytics additions or API changes.
+
+## 0.3.1 — 30 October 2026
+
+Correct stale publication and activation wording in the README and portfolio guide. Runtime code, API contracts, exports and dependencies are byte-identical to 0.3.0.
+
+## 0.3.0 — published 30 October 2026
+
+Adds server-side BharosaMarket for four authenticated registered-app monthly market operations without an investor token or account argument. Production market-key support is active at app.bharosa.finance in the production environment. Includes the portfolio lifecycle changes below; no analytics additions or general OAuth provisioning.
 
-## 0.2.0 — 30 October 2026
+## Lifecycle changes — included in 0.3.0 (0.2.0 was not published)
 
 - Add `portfolios.update(id, { name, expected_name }, { idempotencyKey })` for account-scoped, name-only updates, with optimistic name comparison and validated response identity. Holdings and snapshots remain unchanged.
 - Accept `positions: []` when creating a saved portfolio. Empty portfolio analysis remains unavailable until holdings exist.

package/README.md

@@ -2,25 +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.
 
-**Release target:** `bharosa@0.1.0`. Registry publication is pending; use the reviewed local archive until publication is confirmed. You also need an API URL and credentials from the operator of your Bharosa service; installing the SDK does not create an account or grant access.
+**SDK version:** `bharosa@0.3.2`. Both clients use the production API at `https://app.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. If you have the source checkout, build and pack it:
+Use Node.js 22.12+ in a supported LTS release. Install the published SDK in your backend application:
 
 ```sh
-npm --prefix tooling ci --ignore-scripts
-npm run build
-npm pack --pack-destination /absolute/path/to/artifacts
+npm install bharosa@0.3.2 --ignore-scripts
 ```
 
-If the operator supplied a reviewed archive, skip the source build. Install that archive in your backend application:
+Source contributors can build and pack a local archive using the commands in CONTRIBUTING.md.
 
-```sh
-npm install /absolute/path/to/artifacts/bharosa-0.1.0.tgz
-```
-
-Configure your application's API origin, account ID, and account key through its secret manager. Then:
+Configure your application's account ID and account key through its secret manager. Then:
 
 ```ts
 import { Bharosa } from "bharosa";
@@ -31,7 +25,6 @@ function required(name: string): string {
   return value;
 }
 const bharosa = new Bharosa({
-  baseUrl: required("BHAROSA_API_BASE_URL"),
   account: required("BHAROSA_ACCOUNT_ID"),
   auth: { type: "account_key", apiKey: required("BHAROSA_SECRET_KEY") },
 });
@@ -116,14 +109,18 @@ The license covers this SDK. The Bharosa API service, analytics implementation,
 
 ### Monthly market history and synthetic samples
 
-`client.marketSnapshots` exposes month-start historical market observations and latest NAV valuation without a separate market-data approval step, using authenticated credentials with the required account-read scope. All external credentials, including direct account keys, use monthly historical market dates; investor transaction and position history retains its full dates. See [monthly snapshots](docs/monthly-market-data.md) for actual observation dates, missing data and availability. This local implementation does not activate live access.
+`client.marketSnapshots` exposes month-start historical market observations and latest NAV valuation without a separate market-data approval step, using authenticated credentials with the required account-read scope. All external credentials, including direct account keys, use monthly historical market dates; investor transaction and position history retains its full dates. See [monthly snapshots](docs/monthly-market-data.md) for actual observation dates, missing data and availability. Installing the SDK does not grant account access.
 
 The optional `bharosa/testing` entrypoint supplies fresh, deterministic synthetic portfolios and fictional fund compositions without credentials or network requests. Its seed helper writes only when explicitly called with an authenticated client, confirmed test account, stable run ID and resolved instrument mapping. See [testing samples](docs/testing.md).
 
-Unit precision follow-up (local, unreleased): 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. Canonical marketing reconciliation is coordinated through the parent, with deployment pending.
+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.
 
-### Local candidate: registered-app monthly data
+### Registered-app monthly data
+
+Available in SDK 0.3.0 and activated at `https://app.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.
+
+### Optional API origin override
 
-Not published or activated. Server applications can use `new BharosaMarket({baseUrl, 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. A separately versioned release and explicit API activation are required.
+Set `baseUrl` only for another deployment or tests. Omitted or `undefined` uses `https://app.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.

package/dist/client-types.d.cts

@@ -17,7 +17,8 @@ export interface BharosaTransport {
     send(url: string, request: RequestInit): Promise<Response>;
 }
 interface BharosaBaseConfig {
-    readonly baseUrl: string;
+    /** Defaults to https://app.bharosa.finance. Explicit overrides must be valid origins. */
+    readonly baseUrl?: string;
     readonly account: string;
     readonly allowLocalhostHttp?: boolean;
     readonly maxResponseBytes?: number;

package/dist/client-types.d.ts

@@ -17,7 +17,8 @@ export interface BharosaTransport {
     send(url: string, request: RequestInit): Promise<Response>;
 }
 interface BharosaBaseConfig {
-    readonly baseUrl: string;
+    /** Defaults to https://app.bharosa.finance. Explicit overrides must be valid origins. */
+    readonly baseUrl?: string;
     readonly account: string;
     readonly allowLocalhostHttp?: boolean;
     readonly maxResponseBytes?: number;

package/dist/index.d.cts

@@ -16,7 +16,8 @@ export declare class Bharosa implements T.ClientSurface {
     constructor(config: T.BharosaConfig);
 }
 export interface BharosaMarketConfig {
-    baseUrl: string;
+    /** Defaults to https://app.bharosa.finance. */
+    baseUrl?: string;
     apiKey: string;
     allowLocalhostHttp?: boolean;
     maxResponseBytes?: number;

package/dist/index.d.ts

@@ -16,7 +16,8 @@ export declare class Bharosa implements T.ClientSurface {
     constructor(config: T.BharosaConfig);
 }
 export interface BharosaMarketConfig {
-    baseUrl: string;
+    /** Defaults to https://app.bharosa.finance. */
+    baseUrl?: string;
     apiKey: string;
     allowLocalhostHttp?: boolean;
     maxResponseBytes?: number;

package/dist/transport.cjs

@@ -156,7 +156,7 @@ function createTransport(config, marketOnly = false) {
     ]);
     check(config.allowLocalhostHttp === undefined ||
         typeof config.allowLocalhostHttp === "boolean");
-    const base = origin(config.baseUrl, config.allowLocalhostHttp);
+    const base = origin(config.baseUrl === undefined ? "https://app.bharosa.finance" : config.baseUrl, config.allowLocalhostHttp);
     check((0, validate_cjs_1.valid)(operations.retrieve_account.parameters[0].schema, config.account));
     const account = config.account;
     let headers, secrets;

package/docs/getting-started.md

@@ -4,25 +4,15 @@
 
 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 an authorized API origin, account ID, and account key from your Bharosa service operator. There is no default public origin. The SDK neither provisions accounts nor runs an OAuth consent flow.
+Obtain your authorized account ID and account key. Bharosa and BharosaMarket default to the production origin `https://app.bharosa.finance`; no API URL environment variable is required. The SDK neither provisions accounts nor runs an OAuth consent flow.
 
-## Install a local build
-
-From the SDK directory:
-
-```sh
-npm --prefix tooling ci --ignore-scripts
-npm run build
-npm pack --pack-destination /absolute/path/to/artifacts
-```
-
-Then, from your application directory:
+## Install
 
 ```sh
-npm install /absolute/path/to/artifacts/bharosa-0.0.0-development.tgz
+npm install bharosa@0.3.2 --ignore-scripts
 ```
 
-Use the filename produced by `npm pack` if the development version changes. This installs your local artifact; `npm install bharosa` is not currently supported. Use the archive until an npm release is available.
+Source contributors can build and pack a local archive as described in CONTRIBUTING.md.
 
 ## Read your account
 
@@ -38,7 +28,6 @@ function required(name) {
 }
 
 const bharosa = new Bharosa({
-  baseUrl: required("BHAROSA_API_BASE_URL"),
   account: required("BHAROSA_ACCOUNT_ID"),
   auth: { type: "account_key", apiKey: required("BHAROSA_SECRET_KEY") },
 });
@@ -46,7 +35,7 @@ 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. The origin must use HTTPS and contain no path, query, user information, or fragment.
+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.
 
 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/`.
 
@@ -65,7 +54,7 @@ To try the interface without an API or credentials, use the [synthetic examples]
 ## Caller-owned transport and first-party market data
 
 `BharosaTransport.send(url: string, request: RequestInit): Promise<Response>`
-can replace credential configuration. Construct with `baseUrl`, `account` and
+can replace credential configuration. Construct with `account`, an optional `baseUrl`, and
 `transport`; do not also pass `auth` or `fetch`. The host application owns its
 private session adapter, URL/origin restrictions, per-write CSRF, cookie policy
 and cancellation on account changes. SDK requests default to omitted credentials,

package/docs/portfolios.md

@@ -87,9 +87,9 @@ The earlier singular `client` option remains supported, but cannot be combined w
 
 `await client.accounts.retrieve()` uses the account configured on the SDK; no repeated account ID is needed. Its nullable `personal_client_id` identifies the authenticated human's linked household, not a new family resource or an access grant. Machine account keys receive null because they do not identify a signed-in person. A null link must not be replaced by guessing from a client name or account owner. The prelaunch public account response no longer exposes the internal `owner` user ID; ownership remains enforced on the server.
 
-Units-first portfolio creation (local, unreleased): `portfolios.create` accepts an initial position with either `current_value` or positive `quantity`, never both, using the supplied `as_of` date. Existing amount requests and amount-only responses remain unchanged. Supplied units are stored atomically without requiring a NAV. Snapshot `quantity` can now be a decimal string and `valuation` can be null; `total_current_value` is null when any snapshot position lacks a reported amount, and `valuation_basis` is `supplied_quantity`. Consumers of general snapshot reads must handle these new nullable values; this is an intentional prelaunch type widening. Older SDKs cannot read units-only snapshots. Snapshot replacement and in-memory analytics remain amount-only. No public package release or availability change is implied.
+Units-first portfolio creation: `portfolios.create` accepts an initial position with either `current_value` or positive `quantity`, never both, using the supplied `as_of` date. Existing amount requests and amount-only responses remain unchanged. Supplied units are stored atomically without requiring a NAV. Snapshot `quantity` can now be a decimal string and `valuation` can be null; `total_current_value` is null when any snapshot position lacks a reported amount, and `valuation_basis` is `supplied_quantity`. Consumers of general snapshot reads must handle these new nullable values; this is an intentional prelaunch type widening. Older SDKs cannot read units-only snapshots. Snapshot replacement and in-memory analytics remain amount-only. These shapes are included in the published SDK.
 
-## Empty creation and name updates (SDK 0.2.0)
+## Empty creation and name updates (SDK 0.3.0)
 
 The companion API accepts `positions: []` in `portfolios.create`. It persists a portfolio, investment account and zero-position snapshot immediately. Add the first holding afterward through the returned portfolio's `holdings.setCurrent` method. Cancellation before creation sends no request.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bharosa",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "private": false,
   "description": "Typed Bharosa resource SDK with server credentials or caller-owned transport.",
   "license": "MIT",