Enhance client SDK and update documentation

- Added `pydantic` as a dependency for improved data validation in the client SDK.
- Introduced `AuraClient`, `ClientLogInputs`, and `auralog` for structured logging in the client SDK.
- Updated `README.md` and user documentation to include client SDK usage examples and integration snippets.
- Refactored `test_clientlog.py` to utilize the new client logging methods, improving test clarity and functionality.
- Enhanced `init.py` with a new client integration snippet for easier setup.

Author: Bhanu-Vardhan-Reddy

README.md

@@ -45,7 +45,23 @@ Python keeps snake_case naming, but key public names map directly to Node concep
 | `AuraServer.log(...)` | `AuraServer.log(...)` and `aura_log(...)` |
 | `AuraServer.closeSocket(...)` | `AuraServer.close_socket(...)` and `close_aura_log_socket()` |
 | `fetchProjAuthConfig(...)` | `fetch_proj_auth_config(...)` (`fetch_proj_auth_payload(...)` remains supported) |
-| `AuraClient` / `clientlog(...)` | Not yet exposed as a Python library API |
+| `AuraClient` / `clientlog(...)` | `AuraClient`, `client_log(...)`, and typed `auralog(ClientLogInputs(...))` |
+
+Client SDK quickstart:
+
+```python
+from auralogger.client import AuraClient, ClientLogInputs, auralog
+
+AuraClient.sync_from_secret("project-token")
+auralog(
+    ClientLogInputs(
+        type="info",
+        message="hello from client sdk",
+        location="example/client",
+        data={"source": "python"},
+    )
+)
+```
 
 ## Commands
 

auralogger/__init__.py

@@ -6,6 +6,13 @@
     build_proj_auth_url,
     build_project_logs_url,
 )
+from auralogger.client.client_log import (
+    AuraClient,
+    ClientLogInputs,
+    auralog,
+    client_log,
+    close_client_log_socket,
+)
 from auralogger.commands.client_check import run_client_check
 from auralogger.commands.init import run_init
 from auralogger.commands.server_check import run_server_check
@@ -28,6 +35,11 @@
     "aura_log",
     "close_aura_log_socket",
     "AuraServer",
+    "AuraClient",
+    "ClientLogInputs",
+    "auralog",
+    "client_log",
+    "close_client_log_socket",
     "log",
     "run_get_logs",
     "normalize_and_validate_filters",

auralogger/commands/init.py

@@ -129,15 +129,48 @@ def _build_server_integration_snippet() -> str:
     )
 
 
+def _build_client_integration_snippet() -> str:
+    return "\n".join(
+        [
+            "from typing import Any, Dict, Literal, Optional",
+            "from pydantic import BaseModel, Field",
+            "from auralogger.client import AuraClient",
+            "",
+            "class ClientLogInputs(BaseModel):",
+            "    type: Literal['debug', 'info', 'warn', 'error'] = 'info'",
+            "    message: str = Field(..., min_length=1)",
+            "    location: Optional[str] = None",
+            "    data: Optional[Dict[str, Any]] = None",
+            "",
+            "def configure_client_logger(project_token: str) -> None:",
+            "    AuraClient.sync_from_secret(project_token)",
+            "",
+            "def auralog(loginputs: ClientLogInputs) -> None:",
+            "    AuraClient.log(",
+            "        loginputs.type,",
+            "        loginputs.message,",
+            "        loginputs.location,",
+            "        loginputs.data,",
+            "    )",
+        ]
+    )
+
+
 def _print_integration_help() -> None:
     print()
     print("Server integration snippet (Python)")
     print()
     print(_build_server_integration_snippet())
     print()
     print(
-        "Frontend/browser integration is handled by the Node package "
-        "auralogger-cli/client. Python package support here is server-side."
+        "Client/browser-ingest integration snippet (Python SDK)."
+    )
+    print()
+    print(_build_client_integration_snippet())
+    print()
+    print(
+        "If your frontend runtime is JavaScript/TypeScript, use the Node package "
+        "auralogger-cli/client instead."
     )
     print()
 

auralogger/commands/test_clientlog.py

@@ -2,78 +2,26 @@
 
 from __future__ import annotations
 
-import json
 import time
-from datetime import datetime, timezone
-from typing import Any, Dict, cast
-
-import websocket
-from websocket import create_connection
-
-from auralogger.backend_origin import (
-    build_create_browser_logs_url,
-    resolve_ws_base_url,
-)
+from auralogger.client.client_log import AuraClient, close_client_log_socket
 from auralogger.cli_auth import resolve_project_token_for_init
-from auralogger.proj_auth import fetch_proj_auth_payload
-
-CONNECT_TIMEOUT_S = 5
-
-
-def _iso_timestamp_with_micros(epoch_ms: float) -> str:
-    dt = datetime.fromtimestamp(epoch_ms / 1000.0, tz=timezone.utc)
-    base = dt.strftime("%Y-%m-%dT%H:%M:%S")
-    micros = f"{dt.microsecond:06d}"
-    return f"{base}.{micros}Z"
 
 
 def run_test_clientlog() -> None:
     project_token = resolve_project_token_for_init()
-    raw = fetch_proj_auth_payload(project_token)
-    auth = cast(Dict[str, Any], raw)
-
-    project_id = auth.get("project_id")
-    project_name = auth.get("project_name")
-    session_raw = auth.get("session")
-    session = session_raw.strip() if isinstance(session_raw, str) else ""
-    if not session:
-        raise ValueError("proj_auth response did not include a session string.")
-
-    ws_base = resolve_ws_base_url()
-    ws_url = build_create_browser_logs_url(ws_base, project_token)
+    AuraClient.sync_from_secret(project_token)
     print("Sending 5 client test logs via browser ingest route...")
 
-    try:
-        # Browser ingest route is path-auth only; do not send auth headers.
-        ws = create_connection(ws_url, timeout=CONNECT_TIMEOUT_S)
-    except websocket.WebSocketTimeoutException as e:
-        raise ValueError(
-            f"Browser ingest connect timed out after {CONNECT_TIMEOUT_S * 1000}ms."
-        ) from e
-    except Exception as e:
-        raise ValueError(f"auralogger: test-clientlog connect failed: {e}") from e
-
     try:
         for i in range(1, 6):
-            payload = {
-                "type": "info",
-                "message": f"test-clientlog log {i}/5",
-                "location": "cli/test-clientlog",
-                "session": session,
-                "created_at": _iso_timestamp_with_micros(time.time() * 1000.0),
-                "data": json.dumps({"i": i, "kind": "test-clientlog"}),
-            }
-            ws.send(json.dumps(payload))
+            AuraClient.log(
+                "info",
+                f"test-clientlog log {i}/5",
+                "cli/test-clientlog",
+                {"i": i, "kind": "test-clientlog"},
+            )
             time.sleep(0.15)
-    except (TypeError, ValueError) as e:
-        raise ValueError(f"Could not pack test-clientlog payload: {e}") from e
-    except Exception as e:
-        raise ValueError(f"Client burst did not send - {e}") from e
     finally:
-        try:
-            ws.close()
-        except Exception:
-            pass
+        close_client_log_socket()
 
-    label = project_name if isinstance(project_name, str) and project_name.strip() else project_id
-    print(f"Client burst complete for project {label!s}. Try: auralogger get-logs -maxcount 20")
+    print("Client burst complete. Try: auralogger get-logs -maxcount 20")

dev-docs/file-map.md

@@ -58,7 +58,8 @@ Use these pairs when keeping Python terminology close to Node while preserving P
 ## Namespaced compatibility exports
 
 - `auralogger/server/__init__.py` — server runtime re-exports (`AuraServer`, `aura_log`, `close_aura_log_socket`)
-- `auralogger/client/__init__.py` — client-related CLI helper re-exports (`run_client_check`, `run_test_clientlog`)
+- `auralogger/client/__init__.py` — client SDK + CLI re-exports (`AuraClient`, `client_log`, typed `auralog`, plus check/test commands)
+- `auralogger/client/client_log.py` — importable browser-ingest runtime (`AuraClient`) with token override, `proj_auth` hydration cache, socket reuse + idle close, and typed inputs
 - `auralogger/utils/__init__.py` — URL/env/error utility re-exports for stable namespaced imports
 
 ## Configuration (os.environ)

pyproject.toml

@@ -27,6 +27,7 @@ classifiers = [
   "Topic :: System :: Logging",
 ]
 dependencies = [
+  "pydantic>=2.0.0",
   "python-dotenv>=1.0.0",
   "websocket-client>=1.6.0",
 ]

tests/test_client_sdk.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+from auralogger.client.client_log import (
+    AuraClient,
+    ClientLogInputs,
+    auralog,
+    client_log,
+    close_client_log_socket,
+)
+
+
+class _FakeSocket:
+    def __init__(self) -> None:
+        self.sent: list[str] = []
+        self.closed = False
+
+    def send(self, body: str) -> None:
+        self.sent.append(body)
+
+    def close(self) -> None:
+        self.closed = True
+
+
+class AuraClientSdkTests(unittest.TestCase):
+    def test_configure_rejects_empty_token(self) -> None:
+        with self.assertRaises(ValueError):
+            AuraClient.configure("   ")
+
+    def test_sync_from_secret_validates_required_fields(self) -> None:
+        with patch(
+            "auralogger.client.client_log.fetch_proj_auth_payload",
+            return_value={"project_id": "p1", "session": ""},
+        ):
+            with self.assertRaises(ValueError):
+                AuraClient.sync_from_secret("cipher-token")
+
+    def test_log_delegates_to_client_log_function(self) -> None:
+        with patch("auralogger.client.client_log.client_log") as mocked:
+            AuraClient.log("info", "hello", "tests/client", {"k": 1})
+        mocked.assert_called_once_with("info", "hello", "tests/client", {"k": 1})
+
+    def test_auralog_uses_typed_inputs(self) -> None:
+        with patch("auralogger.client.client_log.AuraClient.log") as mocked:
+            auralog(
+                ClientLogInputs(
+                    type="warn",
+                    message="typed input",
+                    location="tests/client",
+                    data={"ok": True},
+                )
+            )
+        mocked.assert_called_once_with("warn", "typed input", "tests/client", {"ok": True})
+
+    def test_client_log_sends_when_runtime_is_hydrated(self) -> None:
+        ws = _FakeSocket()
+        with patch(
+            "auralogger.client.client_log._resolve_project_token_runtime",
+            return_value="ptok",
+        ), patch(
+            "auralogger.client.client_log._merged_runtime_for_send",
+            return_value={"project_id": "pid", "session": "sess", "styles": []},
+        ), patch(
+            "auralogger.client.client_log._ensure_ws",
+            return_value=ws,
+        ), patch("auralogger.client.client_log.print_log"), patch(
+            "auralogger.client.client_log._schedule_socket_idle_close"
+        ):
+            client_log("info", "hello", "tests/client", {"x": 1})
+
+        self.assertEqual(len(ws.sent), 1)
+
+    def test_close_socket_delegates(self) -> None:
+        with patch("auralogger.client.client_log.close_client_log_socket") as mocked:
+            AuraClient.close_socket()
+        mocked.assert_called_once_with()
+
+    def test_close_client_log_socket_closes_ws(self) -> None:
+        ws = _FakeSocket()
+        with patch("auralogger.client.client_log._ws", ws), patch(
+            "auralogger.client.client_log._bound_url", "wss://x"
+        ):
+            close_client_log_socket()
+        self.assertTrue(ws.closed)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_public_api_names.py

@@ -3,7 +3,14 @@
 import unittest
 from unittest.mock import patch
 
-from auralogger import AuraServer, fetch_proj_auth_config, fetch_proj_auth_payload
+from auralogger import (
+    AuraClient,
+    AuraServer,
+    ClientLogInputs,
+    auralog,
+    fetch_proj_auth_config,
+    fetch_proj_auth_payload,
+)
 
 
 class PublicApiNamingTests(unittest.TestCase):
@@ -37,6 +44,23 @@ def test_sync_from_secret_validates_required_fields(self) -> None:
             with self.assertRaises(ValueError):
                 AuraServer.sync_from_secret("cipher-token")
 
+    def test_aura_client_log_delegates_to_client_log(self) -> None:
+        with patch("auralogger.client.client_log.client_log") as mocked:
+            AuraClient.log("info", "hello", "tests/public-api", {"k": 1})
+        mocked.assert_called_once_with("info", "hello", "tests/public-api", {"k": 1})
+
+    def test_client_auralog_uses_model_fields(self) -> None:
+        with patch("auralogger.client.client_log.AuraClient.log") as mocked:
+            auralog(
+                ClientLogInputs(
+                    type="info",
+                    message="hello",
+                    location="tests/public-api",
+                    data={"k": 1},
+                )
+            )
+        mocked.assert_called_once_with("info", "hello", "tests/public-api", {"k": 1})
+
 
 if __name__ == "__main__":
     unittest.main()

user-docs/commands.md

@@ -30,6 +30,9 @@ Default API/WebSocket hosts need no URL config unless you override them. See **[
 - `auralogger test-clientlog` — send 5 browser-ingest test logs.
 - `auralogger get-logs [filters...]` — fetch and print logs.
 
+For application/runtime usage (not CLI), Python now exposes an importable client SDK:
+`from auralogger.client import AuraClient, ClientLogInputs, auralog`.
+
 If you run an unknown command, the CLI exits with code `1`, prints `Unknown command: <name>`, and shows usage plus valid commands so you can retry quickly.
 
 ---

user-docs/environment.md

@@ -39,6 +39,7 @@ Older names such as `AURALOGGER_SECRET_KEY` are **not** read.
 | **`auralogger test-clientlog`** | Prompts for missing token, then sends a 5-log burst through `create_browser_logs` using path-only auth. |
 | **`auralogger get-logs`** | `AURALOGGER_PROJECT_TOKEN` and `AURALOGGER_USER_SECRET`; styles from env or fetched once via `proj_auth` for that run. |
 | **`aura_log()`** | `AURALOGGER_PROJECT_TOKEN` and `AURALOGGER_USER_SECRET`; id/session/styles from env or from a cached `proj_auth` fetch. Otherwise console-only with a one-time stderr hint. |
+| **`AuraClient` / `client_log()`** | `AURALOGGER_PROJECT_TOKEN` (or `AuraClient.configure(...)`) and reachable `proj_auth` for full send path; falls back to console-only if project/session hydration fails. |
 
 ## Optional