micantis 1.2.5__tar.gz → 1.2.7__tar.gz

{micantis-1.2.5 → micantis-1.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: micantis
-Version: 1.2.5
+Version: 1.2.7
 Summary: Package to simplify Micantis API usage
 Author-email: Mykela DeLuca <mykela.deluca@micantis.io>
 License-Expression: MIT
@@ -121,10 +121,35 @@ api = MicantisAPI()  # Will automatically use environment variables
 # No need to call authenticate() when using a token
 ```
 
+``` python
+# Option 5 - Externally-managed tokens (web apps holding per-user tokens)
+# Provide a zero-argument callable that always returns a currently-valid
+# bearer token. It is consulted before every request (and on 401 retry),
+# so your app owns the refresh logic — e.g. reading the signed-in user's
+# token from Azure App Service / Container Apps built-in authentication.
+service_url = 'your service url'
+
+api = MicantisAPI(service_url=service_url, token_provider=get_current_user_token)
+# No need to call authenticate() when using a token provider
+```
+
 ### Authenticate API
 ``` api.authenticate() ```
 
-**Note:** When using a pre-existing token (Option 3 or 4), you don't need to call `authenticate()` as the token is already configured.
+**Note:** When using a pre-existing token (Option 3 or 4) or a token provider (Option 5), you don't need to call `authenticate()` as the token is already configured.
+
+### Who am I?
+
+``` python
+me = api.get_whoami()
+# {'username': 'jane.doe@example.com', 'displayName': 'Jane Doe', 'email': ...,
+#  'roles': ['Analyst'], 'accessGroups': [{'id': 3, 'name': 'PRC'}],
+#  'defaultAccessGroupId': 3, 'unrestrictedAccess': False}
+```
+
+Returns the identity the API resolves for your credentials, including the access
+groups that scope your data visibility. Handy for "signed in as ..." banners and
+for discovering which labs/groups you can query.
 
 ### Download Data Table Summary
 
@@ -500,6 +525,24 @@ print(f"Retrieved {len(combined_df)} test requests")
 combined_df.head()
 ```
 
+### Get Test Request Member Cells
+Retrieve the actual cells linked to a test request. Note that the `tests` array from `get_test_request()` is the test plan (names and quantities) — it contains no cell IDs.
+
+```python
+# DataFrame with one row per member cell (default)
+cells_df = api.get_test_request_cells(request_id)
+cells_df.head()  # columns: id, name, updated, cycleCount, hasGraphData
+
+# Raw list of dicts
+cells = api.get_test_request_cells(request_id, return_format='list')
+```
+
+```python
+# Use the cell IDs directly — e.g. fetch metadata for every cell in the request
+cell_ids = cells_df['id'].to_list()
+metadata_df = api.get_cell_metadata(cell_ids=cell_ids, metadata=["Cell height"])
+```
+
 ## Write Cell Metadata
 Micantis lets you programmatically assign or update metadata for each cell using either:
 - the built-in field `"name"` (renames the cell) or `"dataSourceKey"`

{micantis-1.2.5 → micantis-1.2.7}/README.md

@@ -101,10 +101,35 @@ api = MicantisAPI()  # Will automatically use environment variables
 # No need to call authenticate() when using a token
 ```
 
+``` python
+# Option 5 - Externally-managed tokens (web apps holding per-user tokens)
+# Provide a zero-argument callable that always returns a currently-valid
+# bearer token. It is consulted before every request (and on 401 retry),
+# so your app owns the refresh logic — e.g. reading the signed-in user's
+# token from Azure App Service / Container Apps built-in authentication.
+service_url = 'your service url'
+
+api = MicantisAPI(service_url=service_url, token_provider=get_current_user_token)
+# No need to call authenticate() when using a token provider
+```
+
 ### Authenticate API
 ``` api.authenticate() ```
 
-**Note:** When using a pre-existing token (Option 3 or 4), you don't need to call `authenticate()` as the token is already configured.
+**Note:** When using a pre-existing token (Option 3 or 4) or a token provider (Option 5), you don't need to call `authenticate()` as the token is already configured.
+
+### Who am I?
+
+``` python
+me = api.get_whoami()
+# {'username': 'jane.doe@example.com', 'displayName': 'Jane Doe', 'email': ...,
+#  'roles': ['Analyst'], 'accessGroups': [{'id': 3, 'name': 'PRC'}],
+#  'defaultAccessGroupId': 3, 'unrestrictedAccess': False}
+```
+
+Returns the identity the API resolves for your credentials, including the access
+groups that scope your data visibility. Handy for "signed in as ..." banners and
+for discovering which labs/groups you can query.
 
 ### Download Data Table Summary
 
@@ -480,6 +505,24 @@ print(f"Retrieved {len(combined_df)} test requests")
 combined_df.head()
 ```
 
+### Get Test Request Member Cells
+Retrieve the actual cells linked to a test request. Note that the `tests` array from `get_test_request()` is the test plan (names and quantities) — it contains no cell IDs.
+
+```python
+# DataFrame with one row per member cell (default)
+cells_df = api.get_test_request_cells(request_id)
+cells_df.head()  # columns: id, name, updated, cycleCount, hasGraphData
+
+# Raw list of dicts
+cells = api.get_test_request_cells(request_id, return_format='list')
+```
+
+```python
+# Use the cell IDs directly — e.g. fetch metadata for every cell in the request
+cell_ids = cells_df['id'].to_list()
+metadata_df = api.get_cell_metadata(cell_ids=cell_ids, metadata=["Cell height"])
+```
+
 ## Write Cell Metadata
 Micantis lets you programmatically assign or update metadata for each cell using either:
 - the built-in field `"name"` (renames the cell) or `"dataSourceKey"`

{micantis-1.2.5 → micantis-1.2.7}/micantis/api_wrapper.py

@@ -9,7 +9,7 @@ import time
 import tempfile
 import uuid
 from datetime import datetime, timedelta, timezone
-from typing import Optional
+from typing import Callable, Optional
 from urllib.parse import quote
 from msal import PublicClientApplication
 from azure.identity import (
@@ -118,6 +118,7 @@ class MicantisAPI:
                  tenant_id: Optional[str] = None,
                  use_managed_identity: bool = False,
                  token: Optional[str] = None,
+                 token_provider: Optional[Callable[[], str]] = None,
                  verify: bool = True):
         """
         Initialize the API client.
@@ -129,6 +130,12 @@ class MicantisAPI:
         token : str, optional
             Pre-existing bearer token. If not provided, checks WORKBOOK_TOKEN environment variable.
             If a token is provided, authentication methods will be skipped.
+        token_provider : callable, optional
+            Zero-argument callable returning a currently-valid bearer token. Consulted
+            before every request (and on 401 retry), so the provider owns refresh logic.
+            Use this when tokens are managed externally (e.g. a web app holding per-user
+            tokens). Takes precedence over other authentication methods; `token` (if also
+            given) only seeds the initial value.
         verify : bool, optional
             Whether to verify SSL certificates. Default: True. Set to False only for local
             development against self-signed certificates — never disable in production.
@@ -145,12 +152,20 @@ class MicantisAPI:
         self.authority = authority
         self.scopes = scopes or ["user.read"]
         self.token = token or os.environ.get("WORKBOOK_TOKEN")
+        self._token_provider = token_provider
         self.headers = None
 
+        # If a provider is given, seed the initial token from it
+        if self._token_provider and not self.token:
+            self.token = self._token_provider()
+
         # If token is provided, set up headers immediately
         if self.token:
             self.headers = {"Authorization": f"Bearer {self.token}"}
-            print("✅ Using pre-existing token from environment or parameter")
+            if self._token_provider:
+                print("✅ Using externally-managed token (token_provider)")
+            else:
+                print("✅ Using pre-existing token from environment or parameter")
 
         # Extra options for service principal / managed identity
         self.service_principal_id = service_principal_id
@@ -248,10 +263,21 @@ class MicantisAPI:
     def _refresh_token_if_needed(self):
         """
         Check if the token is expired or about to expire, and refresh it if needed.
-        Only works for identity-based authentication (Service Principal / Managed Identity).
+        Works for identity-based authentication (Service Principal / Managed Identity)
+        and for externally-managed tokens (token_provider).
 
         Returns True if token was refreshed, False otherwise.
         """
+        # Token-provider mode: the provider owns freshness — consult it every time.
+        # (getattr: tolerate instances built without __init__, e.g. in tests)
+        if getattr(self, "_token_provider", None):
+            new_token = self._token_provider()
+            if new_token and new_token != self.token:
+                self.token = new_token
+                self.headers = {"Authorization": f"Bearer {self.token}"}
+                return True
+            return False
+
         if not self._credential or not self._token_expires:
             return False
 
@@ -284,6 +310,12 @@ class MicantisAPI:
         - Entra interactive if client_id + authority given
         - Username/password login otherwise
         """
+        # Token-provider mode: re-consult the provider (it owns refresh) and return.
+        # This also makes the 401-retry path re-check the provider.
+        if getattr(self, "_token_provider", None):
+            self._refresh_token_if_needed()
+            return
+
         # Skip authentication if token already set
         if self.headers and self.token:
             print("✅ Token already configured, skipping authentication")
@@ -385,6 +417,60 @@ class MicantisAPI:
         # Generic fallback
         return RuntimeError(f"Request failed: {e}")
 
+    # ------------------------
+    # Identity
+    # ------------------------
+    def get_whoami(self, timeout: int = 30):
+        """
+        Fetch the identity the API resolves for the current credentials.
+
+        Useful for showing "signed in as ..." and for discovering which access
+        groups (labs) the caller can see.
+
+        Parameters
+        ----------
+        timeout : int, optional
+            Request timeout in seconds. Default: 30.
+
+        Returns
+        -------
+        dict or None
+            Keys: 'username', 'displayName', 'email', 'roles' (list of str),
+            'accessGroups' (list of {'id', 'name'}), 'defaultAccessGroupId',
+            'unrestrictedAccess' (bool — True for admins who bypass access-group
+            filtering). None if the request fails.
+        """
+        try:
+            return self._retry_on_auth_failure(self._get_whoami, timeout)
+        except Exception as e:
+            print(f"⚠️ get_whoami failed: {e}")
+            return None
+
+    def _get_whoami(self, timeout: int):
+        """
+        Internal helper for get_whoami. Does not handle retries or printing.
+
+        Raises
+        ------
+        RuntimeError
+            If the request fails or authentication is missing.
+        """
+        if not self.headers:
+            raise RuntimeError("Authentication required. Call authenticate() first.")
+
+        self._refresh_token_if_needed()
+
+        try:
+            response = self.session.get(
+                f"{self.service_url}/publicapi/v1/whoami",
+                headers=self.headers,
+                timeout=timeout,
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            raise self._format_request_error(e)
+
     def _get_data_table(
         self,
         offset: int = 0,
@@ -574,6 +660,10 @@ class MicantisAPI:
         Automatically reauthenticates if the session is expired or missing.
         Prints an error message and returns None if the request ultimately fails.
 
+        Supported data kinds: CycleTesterData, StitchedData, CleanedData,
+        DataLoggerData, and PotentiostatData (EIS; requires platform 2.18+).
+        FileData and other kinds fail server-side and return None.
+
         Parameters
         ----------
         guid : str
@@ -1714,6 +1804,72 @@ class MicantisAPI:
                 raise RuntimeError(f"Test request {request_id} not found.")
             raise self._format_request_error(e)
 
+    def get_test_request_cells(self, request_id, return_format='df', timeout: int = 30):
+        """
+        Get the member cells of a test request.
+
+        These are the actual cells linked to the request. The `tests` array returned by
+        get_test_request() is the test plan (names and quantities) and contains no cell IDs.
+
+        Automatically reauthenticates if the session is expired or missing.
+        Prints an error message and returns None if the request ultimately fails.
+
+        Parameters
+        ----------
+        request_id : str
+            GUID of the test request.
+        return_format : str, optional
+            Return format: 'df' for DataFrame (default), anything else for the raw item list.
+        timeout : int, optional
+            Request timeout in seconds. Default: 30.
+
+        Returns
+        -------
+        pd.DataFrame, list, or None
+            One row/dict per member cell with `id`, `name`, `updated`, `cycleCount`,
+            and `hasGraphData`. Returns None if an error occurs.
+        """
+        try:
+            return self._retry_on_auth_failure(
+                self._get_test_request_cells, request_id, return_format, timeout
+            )
+        except Exception as e:
+            print(f"⚠️ get_test_request_cells failed: {e}")
+            return None
+
+    def _get_test_request_cells(self, request_id, return_format: str, timeout: int):
+        """
+        Internal helper for get_test_request_cells. Does not handle retries or printing.
+
+        Raises
+        ------
+        RuntimeError
+            If the request fails or authentication is missing.
+        """
+        if not self.headers:
+            raise RuntimeError("Authentication required. Call authenticate() first.")
+
+        self._refresh_token_if_needed()
+
+        try:
+            response = self.session.get(
+                f"{self.service_url}/publicapi/v1/testmgt/request/get/{request_id}/cells",
+                headers=self.headers,
+                timeout=timeout,
+            )
+            response.raise_for_status()
+
+            items = response.json().get('items', [])
+            if return_format == 'df':
+                return pd.DataFrame(items)
+
+            return items
+
+        except requests.exceptions.RequestException as e:
+            if hasattr(e, 'response') and e.response is not None and e.response.status_code == 404:
+                raise RuntimeError(f"Test request {request_id} not found.")
+            raise self._format_request_error(e)
+
     def download_parquet_file(self,
                               cell_data_id: str,
                               cycle_ranges: list = None,
@@ -2363,6 +2519,31 @@ class MicantisAPI:
             action["name"] = name
         return action
 
+    @staticmethod
+    def change_column_units(source_column_index, new_units, name=None):
+        """Build a change-column-units action for clean_data (MetadataEdit mode).
+
+        Set a cycle-tester aux channel's units. The units drive the channel's
+        display name ("Name (units)"), so use this to fix a wrong unit suffix
+        (e.g. a temperature channel that shows "(V)"). Cycle-tester aux only —
+        logger column units live in the Name, so use rename_column there.
+
+        Parameters
+        ----------
+        source_column_index : int
+            0-based index into the ORIGINAL source column list.
+        new_units : str
+            New units string (e.g. 'degC').
+        name : str, optional
+            Descriptive name for this action.
+        """
+        action = {"$type": "units",
+                  "sourceColumnIndex": int(source_column_index),
+                  "newUnits": new_units}
+        if name is not None:
+            action["name"] = name
+        return action
+
     @staticmethod
     def reorder_columns(source_column_indices, name=None):
         """Build a reorder-columns action for clean_data (MetadataEdit mode).
@@ -2419,6 +2600,37 @@ class MicantisAPI:
         action["columns"] = [{"columnIndex": int(k), "value": float(v)} for k, v in columns.items()]
         return action
 
+    @staticmethod
+    def shift_time(offset_seconds=None, rezero_from_first_row=False, name=None):
+        """Build a shift-time action for clean_data (Parametric mode).
+
+        Shift every surviving timestep's test time by a constant. Works on
+        cycle-tester and logger sources. To make the first remaining row T=0
+        (e.g. after dropping a leading rest step), remove those rows first, then
+        shift_time(rezero_from_first_row=True) — actions apply in order.
+
+        Parameters
+        ----------
+        offset_seconds : float, optional
+            Subtract this many seconds from every timestep. Pass this OR
+            rezero_from_first_row, not both.
+        rezero_from_first_row : bool, optional
+            Re-zero so the first surviving row becomes 0.
+        name : str, optional
+            Descriptive name for this action.
+        """
+        if (offset_seconds is None) == (not rezero_from_first_row):
+            raise ValueError(
+                "shift_time requires exactly one of offset_seconds or rezero_from_first_row.")
+        action = {"$type": "shiftTime"}
+        if name is not None:
+            action["name"] = name
+        if rezero_from_first_row:
+            action["rezeroFromFirstRow"] = True
+        else:
+            action["offsetSeconds"] = float(offset_seconds)
+        return action
+
     def clean_data(self,
                    source_ids: list,
                    mode: str = 'CycleAutoFixup',

{micantis-1.2.5 → micantis-1.2.7}/micantis.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: micantis
-Version: 1.2.5
+Version: 1.2.7
 Summary: Package to simplify Micantis API usage
 Author-email: Mykela DeLuca <mykela.deluca@micantis.io>
 License-Expression: MIT
@@ -121,10 +121,35 @@ api = MicantisAPI()  # Will automatically use environment variables
 # No need to call authenticate() when using a token
 ```
 
+``` python
+# Option 5 - Externally-managed tokens (web apps holding per-user tokens)
+# Provide a zero-argument callable that always returns a currently-valid
+# bearer token. It is consulted before every request (and on 401 retry),
+# so your app owns the refresh logic — e.g. reading the signed-in user's
+# token from Azure App Service / Container Apps built-in authentication.
+service_url = 'your service url'
+
+api = MicantisAPI(service_url=service_url, token_provider=get_current_user_token)
+# No need to call authenticate() when using a token provider
+```
+
 ### Authenticate API
 ``` api.authenticate() ```
 
-**Note:** When using a pre-existing token (Option 3 or 4), you don't need to call `authenticate()` as the token is already configured.
+**Note:** When using a pre-existing token (Option 3 or 4) or a token provider (Option 5), you don't need to call `authenticate()` as the token is already configured.
+
+### Who am I?
+
+``` python
+me = api.get_whoami()
+# {'username': 'jane.doe@example.com', 'displayName': 'Jane Doe', 'email': ...,
+#  'roles': ['Analyst'], 'accessGroups': [{'id': 3, 'name': 'PRC'}],
+#  'defaultAccessGroupId': 3, 'unrestrictedAccess': False}
+```
+
+Returns the identity the API resolves for your credentials, including the access
+groups that scope your data visibility. Handy for "signed in as ..." banners and
+for discovering which labs/groups you can query.
 
 ### Download Data Table Summary
 
@@ -500,6 +525,24 @@ print(f"Retrieved {len(combined_df)} test requests")
 combined_df.head()
 ```
 
+### Get Test Request Member Cells
+Retrieve the actual cells linked to a test request. Note that the `tests` array from `get_test_request()` is the test plan (names and quantities) — it contains no cell IDs.
+
+```python
+# DataFrame with one row per member cell (default)
+cells_df = api.get_test_request_cells(request_id)
+cells_df.head()  # columns: id, name, updated, cycleCount, hasGraphData
+
+# Raw list of dicts
+cells = api.get_test_request_cells(request_id, return_format='list')
+```
+
+```python
+# Use the cell IDs directly — e.g. fetch metadata for every cell in the request
+cell_ids = cells_df['id'].to_list()
+metadata_df = api.get_cell_metadata(cell_ids=cell_ids, metadata=["Cell height"])
+```
+
 ## Write Cell Metadata
 Micantis lets you programmatically assign or update metadata for each cell using either:
 - the built-in field `"name"` (renames the cell) or `"dataSourceKey"`

{micantis-1.2.5 → micantis-1.2.7}/micantis.egg-info/SOURCES.txt

@@ -10,4 +10,6 @@ micantis.egg-info/dependency_links.txt
 micantis.egg-info/requires.txt
 micantis.egg-info/top_level.txt
 tests/test_batch_update_result.py
+tests/test_get_test_request_cells.py
+tests/test_token_provider.py
 tests/test_upload_execution_artifact.py

{micantis-1.2.5 → micantis-1.2.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "micantis"
-version = "1.2.5"
+version = "1.2.7"
 description = "Package to simplify Micantis API usage"
 authors = [
     { name = "Mykela DeLuca", email = "mykela.deluca@micantis.io" }

micantis-1.2.7/tests/test_get_test_request_cells.py

@@ -0,0 +1,88 @@
+"""
+Unit tests for get_test_request_cells.
+
+Mocks the HTTP layer so it can run anywhere without a live server. Exercises:
+- Default 'df' return format → DataFrame with one row per member cell
+- Non-'df' return format → raw item list
+- Empty membership → empty DataFrame
+- 404 → P-03 convention: printed "not found" error, returns None
+
+Run:  pytest
+"""
+import pandas as pd
+import requests
+
+from .test_batch_update_result import _make_api, _mock_response
+
+REQUEST_ID = "11111111-2222-3333-4444-555555555555"
+
+CELLS_BODY = {
+    "count": 2,
+    "items": [
+        {
+            "id": "aaaaaaaa-0000-0000-0000-000000000001",
+            "name": "IQC-EVE-20RM-HLM7-0001",
+            "updated": "2026-05-01T00:00:00Z",
+            "cycleCount": 12,
+            "hasGraphData": True,
+        },
+        {
+            "id": "aaaaaaaa-0000-0000-0000-000000000002",
+            "name": "IQC-EVE-20RM-HLM7-0002",
+            "updated": "2026-05-02T00:00:00Z",
+            "cycleCount": 0,
+            "hasGraphData": False,
+        },
+    ],
+}
+
+
+def test_default_df_returns_one_row_per_cell():
+    api = _make_api()
+    api.session.get.return_value = _mock_response(200, CELLS_BODY)
+
+    result = api.get_test_request_cells(REQUEST_ID)
+
+    assert isinstance(result, pd.DataFrame)
+    assert len(result) == 2
+    assert list(result.columns) == ["id", "name", "updated", "cycleCount", "hasGraphData"]
+    assert result["name"].tolist() == ["IQC-EVE-20RM-HLM7-0001", "IQC-EVE-20RM-HLM7-0002"]
+    url = api.session.get.call_args.args[0]
+    assert url == f"https://fake.test/publicapi/v1/testmgt/request/get/{REQUEST_ID}/cells"
+    print("PASS: default 'df' format → DataFrame with one row per member cell")
+
+
+def test_raw_list_format_returns_items():
+    api = _make_api()
+    api.session.get.return_value = _mock_response(200, CELLS_BODY)
+
+    result = api.get_test_request_cells(REQUEST_ID, return_format="list")
+
+    assert result == CELLS_BODY["items"]
+    print("PASS: non-'df' format → raw item list")
+
+
+def test_empty_membership_returns_empty_dataframe():
+    api = _make_api()
+    api.session.get.return_value = _mock_response(200, {"count": 0, "items": []})
+
+    result = api.get_test_request_cells(REQUEST_ID)
+
+    assert isinstance(result, pd.DataFrame)
+    assert result.empty
+    print("PASS: empty membership → empty DataFrame")
+
+
+def test_404_prints_not_found_and_returns_none(capsys):
+    api = _make_api()
+    resp = _mock_response(404)
+    resp.raise_for_status.side_effect = requests.exceptions.HTTPError(response=resp)
+    api.session.get.return_value = resp
+
+    result = api.get_test_request_cells(REQUEST_ID)
+
+    assert result is None
+    out = capsys.readouterr().out
+    assert "get_test_request_cells failed" in out
+    assert f"Test request {REQUEST_ID} not found" in out
+    print("PASS: 404 → printed not-found error, returns None")

micantis-1.2.7/tests/test_token_provider.py

@@ -0,0 +1,148 @@
+"""
+Unit tests for the token_provider authentication mode and get_whoami.
+
+Mocks the HTTP layer so it can run anywhere without a live server. Exercises:
+- Constructor wiring: provider seeds token + headers; explicit token= takes precedence
+- _refresh_token_if_needed consults the provider (rotates headers on change)
+- 401 retry re-consults the provider and succeeds with the new token
+- get_whoami happy path (URL + payload) and failure path (P-03: print + None)
+- Regression: static token= without a provider keeps its no-refresh behavior
+
+Run:  pytest
+"""
+from unittest.mock import MagicMock
+
+import requests
+
+from micantis.api_wrapper import MicantisAPI
+
+from .test_batch_update_result import _make_api, _mock_response
+
+WHOAMI_BODY = {
+    "username": "jane.doe@milwaukeetool.com",
+    "displayName": "Jane Doe",
+    "email": "jane.doe@milwaukeetool.com",
+    "roles": ["Analyst"],
+    "accessGroups": [{"id": 3, "name": "PRC"}, {"id": 7, "name": "AES"}],
+    "defaultAccessGroupId": 3,
+    "unrestrictedAccess": False,
+}
+
+
+def _make_provider_api(provider):
+    api = MicantisAPI(service_url="https://fake.test", token_provider=provider)
+    api.session = MagicMock()
+    return api
+
+
+def test_constructor_seeds_token_from_provider():
+    provider = MagicMock(return_value="tok-1")
+    api = _make_provider_api(provider)
+
+    assert api.token == "tok-1"
+    assert api.headers == {"Authorization": "Bearer tok-1"}
+    provider.assert_called_once()
+    print("PASS: constructor seeds token + headers from provider")
+
+
+def test_explicit_token_seeds_initial_value_over_provider():
+    provider = MagicMock(return_value="tok-from-provider")
+    api = MicantisAPI(service_url="https://fake.test", token="tok-explicit",
+                      token_provider=provider)
+
+    assert api.token == "tok-explicit"
+    provider.assert_not_called()  # only consulted lazily, before requests
+
+    api._refresh_token_if_needed()
+    assert api.token == "tok-from-provider"
+    print("PASS: explicit token seeds initial value; provider takes over on refresh")
+
+
+def test_refresh_rotates_headers_when_provider_returns_new_token():
+    tokens = iter(["tok-1", "tok-2"])
+    api = _make_provider_api(lambda: next(tokens))
+
+    refreshed = api._refresh_token_if_needed()
+
+    assert refreshed is True
+    assert api.token == "tok-2"
+    assert api.headers == {"Authorization": "Bearer tok-2"}
+    print("PASS: refresh rotates token + headers on provider change")
+
+
+def test_refresh_is_noop_when_provider_returns_same_token():
+    api = _make_provider_api(lambda: "tok-1")
+
+    refreshed = api._refresh_token_if_needed()
+
+    assert refreshed is False
+    assert api.token == "tok-1"
+    print("PASS: refresh no-op when provider returns unchanged token")
+
+
+def test_authenticate_is_provider_refresh_not_interactive():
+    tokens = iter(["tok-1", "tok-2"])
+    api = _make_provider_api(lambda: next(tokens))
+
+    api.authenticate()  # must not attempt msal/azure.identity flows
+
+    assert api.token == "tok-2"
+    print("PASS: authenticate() in provider mode just re-consults the provider")
+
+
+def test_401_retry_reconsults_provider():
+    calls = {"n": 0}
+
+    def provider():
+        calls["n"] += 1
+        return "tok-stale" if calls["n"] <= 3 else "tok-fresh"
+
+    api = _make_provider_api(provider)
+
+    resp_401 = _mock_response(401)
+    resp_401.raise_for_status.side_effect = requests.exceptions.HTTPError(response=resp_401)
+    resp_200 = _mock_response(200, WHOAMI_BODY)
+    api.session.get.side_effect = [resp_401, resp_200]
+
+    result = api.get_whoami()
+
+    assert result == WHOAMI_BODY
+    assert api.session.get.call_count == 2
+    # The retried request must carry the rotated token
+    retry_headers = api.session.get.call_args.kwargs["headers"]
+    assert retry_headers == {"Authorization": "Bearer tok-fresh"}
+    print("PASS: 401 → provider re-consulted → retry succeeds with fresh token")
+
+
+def test_get_whoami_calls_endpoint_and_returns_dict():
+    api = _make_api()
+    api.session.get.return_value = _mock_response(200, WHOAMI_BODY)
+
+    result = api.get_whoami()
+
+    assert result == WHOAMI_BODY
+    url = api.session.get.call_args.args[0]
+    assert url == "https://fake.test/publicapi/v1/whoami"
+    print("PASS: get_whoami hits /publicapi/v1/whoami and returns the payload")
+
+
+def test_get_whoami_failure_prints_and_returns_none(capsys):
+    api = _make_api()
+    resp = _mock_response(500)
+    resp.raise_for_status.side_effect = requests.exceptions.HTTPError(response=resp)
+    api.session.get.return_value = resp
+
+    result = api.get_whoami()
+
+    assert result is None
+    assert "get_whoami failed" in capsys.readouterr().out
+    print("PASS: get_whoami failure → printed error, returns None")
+
+
+def test_static_token_without_provider_never_refreshes():
+    api = MicantisAPI(service_url="https://fake.test", token="tok-static")
+    api.session = MagicMock()
+
+    assert api._refresh_token_if_needed() is False
+    assert api.headers == {"Authorization": "Bearer tok-static"}
+    print("PASS: static token= mode unchanged (no refresh path)")