Prepare SharesightAPI 1.5.0

Author: Poshy163

.github/workflows/publish.yml

@@ -37,6 +37,7 @@ jobs:
         run: |
           python -m ruff check .
           python -m ruff format --check .
+          python -m mypy SharesightAPI tests/typecheck_models.py
       - name: Build distributions
         run: python -m build
       - name: Check distribution metadata and contents

.github/workflows/test.yml

@@ -39,6 +39,7 @@ jobs:
       - run: python -m pip install -r requirements_test.txt
       - run: python -m ruff check .
       - run: python -m ruff format --check .
+      - run: python -m mypy SharesightAPI tests/typecheck_models.py
       - run: python -m build
       - run: python -m twine check dist/*
       - run: python scripts/check_dist.py dist

.gitignore

@@ -7,6 +7,10 @@ output.json
 
 /.pytest_cache/
 /.ruff_cache/
+/.mypy_cache/
+/.coverage
+/coverage.xml
+/htmlcov/
 /.venv/
 
 /build

CHANGELOG.md

@@ -3,6 +3,50 @@
 All notable changes to this project are documented here. Versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [1.5.0] - 2026-08-31
+
+### Added
+
+- Added partial `TypedDict` response models for portfolios, holdings,
+  performance, trades, payouts, cash accounts, groups, currencies, countries,
+  custom investments, prices, adjustments, coupon rates and value series.
+  Missing and nullable API fields remain valid.
+- Added typed read-only helpers for the public v2/v3 portfolio, performance,
+  valuation, diversity, tax, holding, trade, payout, cash, instrument, user,
+  group, currency, country and custom-investment endpoints, plus clearly
+  labelled entitlement-dependent benchmark and value-series reads.
+- Added bounded opaque-cursor pagination for Sharesight's documented paginated
+  routes, with repeated-cursor protection and no unsafe page-count guessing.
+- Added opt-in `Decimal` JSON decoding, per-request timeouts, bounded retry
+  jitter and a typed malformed-response exception.
+
+### Changed
+
+- Added explicit preferred-V3 helpers while preserving the legacy V2 response
+  contracts of `list_portfolios()`, `get_portfolio()` and
+  `get_portfolio_performance()`; corrected official `.json` route spellings
+  where required.
+- Portfolio/holding trade lists and holding payouts now deliberately use the
+  public V2 routes; Sharesight marks their V3 counterparts as internal-only.
+- Added explicit public V2 portfolio list, detail and performance fallbacks;
+  modelled the V2 portfolio/cash-account and V3 custom-investment detail routes
+  as the bare objects they actually return.
+- Custom-investment child reads accept and preserve Sharesight's opaque page
+  cursors rather than assuming numeric pages.
+- Corrected the bundled example's client construction and V2 route spelling;
+  it no longer prints OAuth token data or writes portfolio payloads unless the
+  user explicitly opts in.
+- Corrected `create_trade()` to post to `v2/trades.json`, wrap the trade body,
+  and inject the portfolio id. It remains explicitly isolated as a
+  write-capable method and is covered only with mocks.
+- Token-file existence, replacement, permissions and deletion are now
+  asynchronous; unique atomic temporary files and legacy/new owner-only
+  permissions prevent predictable-symlink and brief-readable-file windows.
+- OAuth log redaction now recursively removes nested credentials and writes
+  only allowlisted metadata; token exceptions never retain raw error bodies.
+
+[1.5.0]: https://github.com/Poshy163/Sharesight-API/compare/v1.4.0...v1.5.0
+
 ## [1.4.0] - 2026-08-27
 
 ### Added

MANIFEST.in

@@ -1,4 +1,5 @@
 include CHANGELOG.md
+include example.py
 include LICENSE
 include README.md
 include RELEASING.md

README.md

@@ -101,39 +101,115 @@ result = await sharesight.get_api_request(["v3", "portfolios", None], access_tok
 the client to refresh a caller-stored token. A refresh response that omits a
 replacement refresh token retains the token that just succeeded.
 
-## Convenience methods
+## Typed convenience methods
+
+The client prefers public v3 endpoints, as Sharesight recommends, and uses v2
+where v3 has no equivalent public aggregate. Response annotations come from
+the partial `TypedDict` models exported by `SharesightAPI`; fields remain
+optional because Sharesight omits data for empty, sold, delisted and
+plan-limited positions.
 
 ```python
-portfolios = await sharesight.list_portfolios()
-portfolio = await sharesight.get_portfolio(portfolio_id)
-performance = await sharesight.get_portfolio_performance(
+portfolios = await sharesight.list_portfolios_v3()
+portfolio = await sharesight.get_portfolio_v3(portfolio_id)
+# Stable V2 helpers (the unsuffixed list/detail/performance methods preserve
+# their pre-1.5 routes and response shapes):
+portfolios_v2 = await sharesight.list_portfolios_v2()
+portfolio_v2 = await sharesight.get_portfolio_v2(portfolio_id)
+performance = await sharesight.get_portfolio_performance_v3(
     portfolio_id,
     start_date="2026-01-01",
     end_date="2026-08-27",
 )
+performance_v2 = await sharesight.get_portfolio_performance_v2(portfolio_id)
 holdings = await sharesight.list_holdings(portfolio_id)
+all_holdings = await sharesight.list_all_holdings()
 holding = await sharesight.get_holding(holding_id)
 trades = await sharesight.list_trades(portfolio_id)
-trade = await sharesight.create_trade(portfolio_id, trade_data)
+payouts = await sharesight.list_portfolio_payouts(portfolio_id)
 cash_accounts = await sharesight.list_cash_accounts()
 cash_account = await sharesight.get_cash_account(cash_account_id)
+cash_transactions = await sharesight.list_cash_account_transactions(cash_account_id)
+benchmark = await sharesight.get_portfolio_benchmark(portfolio_id)
+value_history = await sharesight.get_portfolio_value_data(portfolio_id)
+capital_gains = await sharesight.get_capital_gains(portfolio_id)
+unrealised_cgt = await sharesight.get_unrealised_cgt(portfolio_id)
 groups = await sharesight.list_groups()
+currencies = await sharesight.list_currencies()
+countries = await sharesight.list_countries(supported=True)
+custom_investments = await sharesight.list_custom_investments(portfolio_id=portfolio_id)
+custom_investment = await sharesight.get_custom_investment(custom_investment_id)
+custom_prices = await sharesight.list_custom_investment_prices(custom_investment_id)
+custom_adjustments = await sharesight.list_custom_investment_adjustments(custom_investment_id)
+coupon_rates = await sharesight.list_custom_investment_coupon_rates(custom_investment_id)
 ```
 
+| Data | Preferred endpoint |
+|---|---|
+| Portfolio list/detail | V3 `portfolios`, `portfolios/{id}` |
+| Performance/holdings | Public V3 portfolio routes |
+| Trades and holding payouts | Public V2 routes (the V3 equivalents are internal-scoped) |
+| Valuation/diversity/tax/payout aggregates | V2 portfolio routes |
+| Cash accounts/transactions | V2 cash-account routes |
+| Benchmark | V3 internal-tagged route; entitlement-dependent |
+| Value series | V3 mobile-tagged route; entitlement-dependent |
+| Performance index | Public V3 portfolio route |
+| User instruments/account/groups/currencies | Public V2 routes |
+| Countries/custom-investment reads | Public V3 routes |
+
+`create_trade()` is intentionally separated from the read-only group because
+it mutates financial records. Test it with mocks or a Sharesight developer
+sandbox before any authorised live use.
+
+## Pagination and monetary precision
+
+The aggregate endpoints above return complete arrays. For the documented V3
+custom-investment routes that paginate, the generic collector follows the
+opaque cursor returned in `pagination.page`:
+
+```python
+all_prices = await sharesight.get_all_pages(
+    ["v3", f"custom_investment/{custom_investment_id}/prices.json", None],
+    item_key="prices",
+    per_page=100,
+)
+```
+
+Pagination is bounded by `max_pages` and rejects malformed or repeated cursors
+with `SharesightResponseError`. You can also pass the returned
+`pagination.page` string through each dedicated helper's `page=` argument.
+The collector never guesses another page from array length, so using it with a
+non-paginated aggregate endpoint cannot duplicate a large response.
+
+To preserve fractional JSON numbers as decimal values rather than binary
+floats:
+
+```python
+sharesight = SharesightAPI(..., preserve_decimal=True)
+```
+
+Date-only and datetime values remain the exact strings supplied by Sharesight
+so applications can apply their own timezone policy without the client
+inventing one. Most are ISO-8601; a few legacy V2 portfolio fields use display
+formats such as `01 Jan 2009`.
+
 ## Raw requests
 
 An endpoint is `[version, path, query_parameters]`:
 
 ```python
 portfolios = await sharesight.get_api_request(["v3", "portfolios", None], access_token)
 
-trade = await sharesight.post_api_request(
-    ["v2", f"portfolios/{portfolio_id}/trades", {"dry_run": "true"}],
-    {"trade": trade_data},
+value_history = await sharesight.get_api_request(
+    ["v3", f"portfolios/{portfolio_id}/portfolio_value_data.json", None],
     access_token,
 )
 ```
 
+The raw `POST`, `PUT`, `PATCH`, and `DELETE` helpers can mutate Sharesight
+records. Keep those calls outside polling code and validate them with mocks or
+an authorised developer sandbox.
+
 The official endpoint references are available for
 [v2](https://portfolio.sharesight.com/api/2/doc/index.html) and
 [v3](https://portfolio.sharesight.com/api/3/doc/index.html).
@@ -164,15 +240,20 @@ from SharesightAPI import (
     SharesightAuthError,
     SharesightError,
     SharesightRateLimitError,
+    SharesightResponseError,
 )
 ```
 
 - `SharesightError` is the base exception.
-- `SharesightAuthError` retains authentication status, body, and headers.
+- `SharesightAuthError` retains authentication status and headers. Normal API
+  errors retain their structured body; token-endpoint bodies are reduced to a
+  safe OAuth error code because providers may echo credentials in free text.
 - `SharesightAPIError` exposes `status_code`, `message`, `response_data`, and
   `response_headers`.
 - `SharesightRateLimitError` represents HTTP 429 and Sharesight's rate-limit
   HTTP 403, and may expose `retry_after`.
+- `SharesightResponseError` represents a successful response with a malformed
+  or non-advancing shape.
 
 By default, failures return a body for backward compatibility. JSON error
 bodies gain `status_code` when the server omitted it. Opt into exceptions with
@@ -205,11 +286,15 @@ sharesight = SharesightAPI(
     api_url_base,
     max_retries=3,
     retry_backoff=1.0,
+    retry_jitter=0.25,
+    max_retry_delay=300,
+    request_timeout=30,
 )
 ```
 
-Backoff doubles after each failure. Numeric `Retry-After` values are respected
-and capped at five minutes. Set `max_retries=0` when a host application owns
+Backoff doubles after each failure, adds bounded positive jitter, and never
+exceeds `max_retry_delay`. Numeric `Retry-After` values are respected and
+capped by the same limit. Set `max_retries=0` when a host application owns
 scheduling and rate-limit backoff; this surfaces the rejection immediately
 instead of sleeping inside the request.
 
@@ -227,6 +312,8 @@ python -m pip install -r requirements_test.txt
 python -m pip install -e .
 python -m pytest
 python -m ruff check .
+python -m ruff format --check .
+python -m mypy SharesightAPI tests/typecheck_models.py
 python -m build
 python -m twine check dist/*
 python scripts/check_dist.py dist

RELEASING.md

@@ -33,6 +33,7 @@ for the project-side setup.
    python -m pip install -e .
    python -m pytest
    python -m ruff check .
+   python -m mypy SharesightAPI tests/typecheck_models.py
    python -m build
    python -m twine check dist/*
    python scripts/check_dist.py dist
@@ -41,16 +42,17 @@ for the project-side setup.
 4. Commit and push the reviewed release changes. Confirm the `Test` workflow
    succeeds on that exact commit.
 5. Create a GitHub release whose tag is exactly `v<package version>`, for
-   example `v1.4.0`, targeting the validated commit.
+   example `v1.5.0`, targeting the validated commit.
 6. Publish the GitHub release. The `Publish Python package` workflow checks
    that the tag and package versions match, rebuilds the distributions, and
    publishes them through the `pypi` environment.
 7. Verify the files and metadata on PyPI, then install into a clean environment:
 
    ```bash
+   RELEASE_VERSION="$(python -c 'from SharesightAPI import __version__; print(__version__)')"
    python -m venv release-smoke
-   release-smoke/bin/python -m pip install SharesightAPI==1.4.0
-   release-smoke/bin/python -c "import SharesightAPI; print(SharesightAPI.__version__)"
+   release-smoke/bin/python -m pip install "SharesightAPI==$RELEASE_VERSION"
+   release-smoke/bin/python -I -c "import SharesightAPI; print(SharesightAPI.__version__)"
    ```
 
    On Windows, use `release-smoke\Scripts\python.exe`.