bharosa 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,10 +1,14 @@
-# 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.1 — 30 October 2026
 
-# Changelog
+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,23 +2,17 @@
 
 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.
+**Published SDK:** `bharosa@0.3.0` includes portfolio lifecycle and registered-app monthly market support. This documentation patch preserves that runtime. 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.
 
 ## 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.0 --ignore-scripts
 ```
 
-If the operator supplied a reviewed archive, skip the source build. Install that archive in your backend application:
-
-```sh
-npm install /absolute/path/to/artifacts/bharosa-0.1.0.tgz
-```
+Source contributors can build and pack a local archive using the commands in CONTRIBUTING.md.
 
 Configure your application's API origin, account ID, and account key through its secret manager. Then:
 
@@ -116,14 +110,14 @@ 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
 
-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.
+Available in SDK 0.3.0 and activated at `https://app.bharosa.finance`. 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. The production control-plane environment is `production`. General third-party OAuth provisioning is separate and is not enabled by this feature.

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.1",
   "private": false,
   "description": "Typed Bharosa resource SDK with server credentials or caller-owned transport.",
   "license": "MIT",