gamesheet_sdk.common.auth.storage module

Browser storage state file manipulation.

This module provides utilities for reading and writing Playwright browser storage state files, which store cookies, localStorage, and sessionStorage data in JSON format.

The storage state file format is:

{
    "cookies": [...],
    "origins": [
        {
            "origin": "https://example.com",
            "localStorage": [
                {"name": "key", "value": "value"}
            ]
        }
    ]
}

Example usage: .. code-block:: python

from pathlib import Path from gamesheet_sdk.common.config import Config from gamesheet_sdk.common.auth.storage import (

load_local_storage_value, read_state_or_empty, origin_entry_for, apply_local_storage_updates,

)

# Load a localStorage value config = Config() access_token = load_local_storage_value(config, “access_token”) # Create/update localStorage entries state_path = Path.home() / “.gamesheet” / “browser_state.json” state = read_state_or_empty(state_path) origin = origin_entry_for(state, APP_GAMESHEET_COM) apply_local_storage_updates(

origin[“localStorage”], {

“access_token”: “new_token”, “refresh_token”: “new_refresh”,

},

) state_path.write_text(json.dumps(state, indent=2))

gamesheet_sdk.common.auth.storage.read_state_file(path)

Parse the browser storage state JSON, or return None on miss/error.

Reads and parses a Playwright browser storage state file. Returns None if the file does not exist or cannot be parsed.

Note

This function logs a warning (not an error) if the file exists but cannot be read or parsed, allowing graceful fallback to fresh login flows.

Parameters:

path (Path) – Path to the browser storage state JSON file.

Returns:

Parsed storage state dictionary, or None if file is missing or cannot be parsed.

Return type:

dict[str, Any] | None

gamesheet_sdk.common.auth.storage.lookup_local_storage(state, base_url, name)

Return the named localStorage value for base_url, or None.

Searches the storage state dictionary for a localStorage entry matching the given origin (base_url) and key name.

Note

The value returned is untyped (Any) — callers should validate the type before use. See load_local_storage_value() for a string-validated variant.

Parameters:

• state (dict[str, Any]) – Parsed browser storage state dictionary (from read_state_file() or read_state_or_empty()).

• base_url (str) – Origin URL to search for (e.g., APP_GAMESHEET_COM).

• name (str) – localStorage key name to look up.

Returns:

The value associated with the key, or None if the origin or key is not found.

Return type:

Any

gamesheet_sdk.common.auth.storage.load_local_storage_value(config, name)

Read one localStorage entry for config.base_url from the saved state.

High-level helper that reads the browser storage state file from config.browser_state_path, looks up the localStorage value for config.base_url, and validates that it is a non-empty string.

Note

Returns None if the file does not exist, cannot be parsed, the origin is not found, the key is not found, or the value is not a non-empty string.

Example: .. code-block:: python

from gamesheet_sdk.common.config import Config from gamesheet_sdk.common.auth.storage import load_local_storage_value

config = Config() access_token = load_local_storage_value(config, “access_token”) if access_token:

print(f”Found token: {access_token[:10]}…”)

else:

print(“No token found, need to log in”)

Parameters:

• config (Config) – Configuration object containing the browser state path and base URL.

• name (str) – localStorage key name to retrieve (e.g., "access_token").

Returns:

The string value if found and non-empty, otherwise None.

Return type:

str | None

gamesheet_sdk.common.auth.storage.read_state_or_empty(path)

Like read_state_file but returns an empty skeleton on miss/error.

Reads and parses a browser storage state file. Unlike read_state_file(), this function never returns None — if the file does not exist or cannot be parsed, it returns a minimal valid state structure.

Note

This function does not log warnings on parse failures (unlike read_state_file()), making it suitable for write-path helpers where missing state is expected.

Parameters:

path (Path) – Path to the browser storage state JSON file.

Returns:

Parsed storage state dictionary, or {"cookies": [], "origins": []} if the file is missing or cannot be parsed.

Return type:

dict[str, Any]

gamesheet_sdk.common.auth.storage.origin_entry_for(state, base_url)

Return the origin entry for base_url, creating it if absent.

Searches the origins list in the storage state for an entry matching the given URL. If not found, creates a new origin entry with an empty localStorage array and appends it to the list.

Warning

This function mutates the state dictionary by adding a new origin entry if one does not exist. Ensure you write the modified state back to disk after calling this function.

Parameters:

• state (dict[str, Any]) – Browser storage state dictionary (typically from read_state_or_empty()).

• base_url (str) – Origin URL (e.g., APP_GAMESHEET_COM).

Returns:

The origin entry dictionary containing "origin" and "localStorage" keys. The returned dict is a live reference — modifications to it will update the state.

Return type:

dict[str, Any]

gamesheet_sdk.common.auth.storage.apply_local_storage_updates(ls, updates)

Upsert each name → value pair into the localStorage list.

Updates existing localStorage entries in place or appends new entries for keys that do not exist.

Warning

This function mutates the ls list in place. Ensure you write the parent state back to disk after calling this function.

Example: .. code-block:: python

from pathlib import Path import json from gamesheet_sdk.common.auth.storage import (

read_state_or_empty, origin_entry_for, apply_local_storage_updates,

)

state_path = Path.home() / “.gamesheet” / “browser_state.json” state = read_state_or_empty(state_path) origin = origin_entry_for(state, APP_GAMESHEET_COM) # Upsert tokens apply_local_storage_updates(

origin[“localStorage”], {

“access_token”: “eyJ…”, “refresh_token”: “dGh…”,

},

) # Write back to disk state_path.write_text(json.dumps(state, indent=2))

Parameters:

• ls (list[dict[str, str]]) – The localStorage array from an origin entry (typically origin["localStorage"]). This list is mutated in place.

• updates (dict[str, str]) – Dictionary of key-value pairs to upsert.