lithora 0.1.0__tar.gz

lithora-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lithora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lithora-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+prune tests
+global-exclude *.py[cod]
+global-exclude __pycache__
+
+# Ship ONLY the README among markdown — keep any internal docs out of the
+# public PyPI distribution.
+global-exclude *.md
+include README.md

lithora-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: lithora
+Version: 0.1.0
+Summary: Official Python SDK for the Lithora REST API (teams, projects, tasks, work graph, AI workspace).
+Author-email: Lithora <support@lithora.io>
+License-Expression: MIT
+Project-URL: Homepage, https://lithora.io
+Project-URL: Documentation, https://github.com/AADI0009/SaaS-App/tree/main/sdk/python
+Project-URL: Repository, https://github.com/AADI0009/SaaS-App
+Project-URL: Issues, https://github.com/AADI0009/SaaS-App/issues
+Project-URL: API, https://api.lithora.io
+Keywords: lithora,sdk,api,project-management,work-graph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Dynamic: license-file
+
+# lithora
+
+Official Python SDK for the [Lithora](https://lithora.io) REST API — teams,
+projects, tasks, the unified work graph, and the confirmation-gated AI
+workspace.
+
+- Base URL: `https://api.lithora.io` (local dev: `http://localhost:8000`)
+- Auth: JWT bearer (HS256). Get a token with `client.login(...)`.
+
+## Install
+
+```bash
+pip install lithora
+# or, from this source tree:
+pip install -e /path/to/sdk/python
+```
+
+Requires Python 3.9+ and `requests>=2.28`.
+
+## Quickstart
+
+```python
+from lithora import Lithora, AuthChallengeError
+
+client = Lithora(base_url="https://api.lithora.io")  # or http://localhost:8000
+
+# 1. Authenticate. Token is stored on the client and reused automatically.
+try:
+    user = client.login("you@example.com", "your-strong-password")
+except AuthChallengeError as e:
+    # Login asked for a second factor instead of returning a token.
+    print("2FA:", e.requires_2fa, " OTP:", e.requires_login_otp)
+    raise
+
+# 2. Create a project (needs a team_id; list teams with client.teams.list()).
+project = client.projects.create("Apollo", team_id="team_123",
+                                 description="Q3 launch", status="active")
+
+# 3. Create a task in that project.
+task = client.tasks.create("Write the spec", project_id=project["id"],
+                           priority="high", status="todo")
+client.tasks.set_status(task["id"], "in_progress")
+
+# 4. Use the AI workspace (confirmation-gated agent over the work graph).
+session = client.ai.create_session(title="Planning")
+reply = client.ai.chat(session["session_id"], "Break the spec into subtasks")
+if reply.get("requires_confirmation"):
+    action = reply["action_plan"]["actions"][0]   # shape per server
+    client.ai.confirm_action(session["session_id"], action["id"], confirmed=True)
+```
+
+Already have a token? Skip `login`: `Lithora(token="eyJ...")`.
+
+## API surface
+
+All methods map 1:1 to verified endpoints. Namespaces on the client:
+
+| Namespace            | Methods |
+|----------------------|---------|
+| `client` (auth)      | `login`, `register`, `set_token` |
+| `client.auth`        | `me` |
+| `client.teams`       | `list`, `get`, `create`, `members` |
+| `client.projects`    | `list`, `get`, `create`, `update`, `patch`, `delete` |
+| `client.tasks`       | `list(project_id)`, `my`, `get`, `create`, `update`, `set_status`, `delete`, `bulk`, `link_github`, `push_to_github` |
+| `client.work_items`  | `list`, `get`, `create`, `update`, `delete`, `create_relation`, `relations`, `children`, `parents`, `delete_relation`, `cycle_time` |
+| `client.ai`          | `create_session`, `chat`, `link_item`, `search`, `confirm_action` |
+
+## Errors
+
+Every non-2xx response raises a typed exception (all subclass `LithoraError`):
+
+| Exception            | When |
+|----------------------|------|
+| `AuthError`          | 401 — missing/invalid/expired token |
+| `ServerError`        | 5xx — failure on Lithora's side |
+| `ApiError`           | any other non-2xx; has `.status` and `.detail` |
+| `AuthChallengeError` | login needs a 2FA/OTP code (no token issued); has `.requires_2fa`, `.requires_login_otp` |
+
+```python
+from lithora import ApiError
+
+try:
+    client.projects.get("does-not-exist")
+except ApiError as e:
+    print(e.status, e.detail)   # e.g. 404 "Project not found"
+```
+
+## Known gaps
+
+- **No API-key / PAT auth.** Lithora only supports JWT bearer tokens today,
+  so this SDK authenticates via `login(email, password)`. There is no
+  long-lived key mechanism to wrap.
+- Some endpoints (`tasks.link_github`, `tasks.push_to_github`,
+  `work_items.create`) accept fields the public contract abbreviates; those
+  methods pass extra keyword arguments straight through to the request body.
+- **`work_items.cycle_time`** targets a newly added analytics endpoint; its
+  response shape is provisional and fields may change. It requires a
+  `team_id` or `project_id` you have access to.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

lithora-0.1.0/README.md

@@ -0,0 +1,102 @@
+# lithora
+
+Official Python SDK for the [Lithora](https://lithora.io) REST API — teams,
+projects, tasks, the unified work graph, and the confirmation-gated AI
+workspace.
+
+- Base URL: `https://api.lithora.io` (local dev: `http://localhost:8000`)
+- Auth: JWT bearer (HS256). Get a token with `client.login(...)`.
+
+## Install
+
+```bash
+pip install lithora
+# or, from this source tree:
+pip install -e /path/to/sdk/python
+```
+
+Requires Python 3.9+ and `requests>=2.28`.
+
+## Quickstart
+
+```python
+from lithora import Lithora, AuthChallengeError
+
+client = Lithora(base_url="https://api.lithora.io")  # or http://localhost:8000
+
+# 1. Authenticate. Token is stored on the client and reused automatically.
+try:
+    user = client.login("you@example.com", "your-strong-password")
+except AuthChallengeError as e:
+    # Login asked for a second factor instead of returning a token.
+    print("2FA:", e.requires_2fa, " OTP:", e.requires_login_otp)
+    raise
+
+# 2. Create a project (needs a team_id; list teams with client.teams.list()).
+project = client.projects.create("Apollo", team_id="team_123",
+                                 description="Q3 launch", status="active")
+
+# 3. Create a task in that project.
+task = client.tasks.create("Write the spec", project_id=project["id"],
+                           priority="high", status="todo")
+client.tasks.set_status(task["id"], "in_progress")
+
+# 4. Use the AI workspace (confirmation-gated agent over the work graph).
+session = client.ai.create_session(title="Planning")
+reply = client.ai.chat(session["session_id"], "Break the spec into subtasks")
+if reply.get("requires_confirmation"):
+    action = reply["action_plan"]["actions"][0]   # shape per server
+    client.ai.confirm_action(session["session_id"], action["id"], confirmed=True)
+```
+
+Already have a token? Skip `login`: `Lithora(token="eyJ...")`.
+
+## API surface
+
+All methods map 1:1 to verified endpoints. Namespaces on the client:
+
+| Namespace            | Methods |
+|----------------------|---------|
+| `client` (auth)      | `login`, `register`, `set_token` |
+| `client.auth`        | `me` |
+| `client.teams`       | `list`, `get`, `create`, `members` |
+| `client.projects`    | `list`, `get`, `create`, `update`, `patch`, `delete` |
+| `client.tasks`       | `list(project_id)`, `my`, `get`, `create`, `update`, `set_status`, `delete`, `bulk`, `link_github`, `push_to_github` |
+| `client.work_items`  | `list`, `get`, `create`, `update`, `delete`, `create_relation`, `relations`, `children`, `parents`, `delete_relation`, `cycle_time` |
+| `client.ai`          | `create_session`, `chat`, `link_item`, `search`, `confirm_action` |
+
+## Errors
+
+Every non-2xx response raises a typed exception (all subclass `LithoraError`):
+
+| Exception            | When |
+|----------------------|------|
+| `AuthError`          | 401 — missing/invalid/expired token |
+| `ServerError`        | 5xx — failure on Lithora's side |
+| `ApiError`           | any other non-2xx; has `.status` and `.detail` |
+| `AuthChallengeError` | login needs a 2FA/OTP code (no token issued); has `.requires_2fa`, `.requires_login_otp` |
+
+```python
+from lithora import ApiError
+
+try:
+    client.projects.get("does-not-exist")
+except ApiError as e:
+    print(e.status, e.detail)   # e.g. 404 "Project not found"
+```
+
+## Known gaps
+
+- **No API-key / PAT auth.** Lithora only supports JWT bearer tokens today,
+  so this SDK authenticates via `login(email, password)`. There is no
+  long-lived key mechanism to wrap.
+- Some endpoints (`tasks.link_github`, `tasks.push_to_github`,
+  `work_items.create`) accept fields the public contract abbreviates; those
+  methods pass extra keyword arguments straight through to the request body.
+- **`work_items.cycle_time`** targets a newly added analytics endpoint; its
+  response shape is provisional and fields may change. It requires a
+  `team_id` or `project_id` you have access to.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

lithora-0.1.0/lithora/__init__.py

@@ -0,0 +1,32 @@
+"""Lithora -- official Python SDK for the Lithora REST API.
+
+Quickstart:
+    >>> from lithora import Lithora
+    >>> client = Lithora(base_url="https://api.lithora.io")
+    >>> client.login("you@example.com", "your-strong-password")
+    >>> project = client.projects.create("Apollo", team_id="team_123")
+    >>> client.tasks.create("Write spec", project_id=project["id"])
+"""
+
+from __future__ import annotations
+
+from .client import Lithora
+from .errors import (
+    ApiError,
+    AuthChallengeError,
+    AuthError,
+    LithoraError,
+    ServerError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Lithora",
+    "LithoraError",
+    "ApiError",
+    "AuthError",
+    "AuthChallengeError",
+    "ServerError",
+    "__version__",
+]

lithora-0.1.0/lithora/client.py

@@ -0,0 +1,237 @@
+"""HTTP client for the Lithora REST API.
+
+The :class:`Lithora` client owns a single :class:`requests.Session`, attaches
+the ``Authorization: Bearer <token>`` header to authenticated calls, maps
+non-2xx responses to typed exceptions, and exposes the API surface through
+resource namespaces (``client.projects``, ``client.tasks``, ...).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import requests
+
+from .errors import ApiError, AuthChallengeError, AuthError, ServerError
+from .resources import (
+    AIResource,
+    AuthResource,
+    AutomationsResource,
+    GitHubResource,
+    ProjectsResource,
+    SearchResource,
+    TasksResource,
+    TeamsResource,
+    TokensResource,
+    WorkItemsResource,
+)
+
+DEFAULT_BASE_URL = "https://api.lithora.io"
+
+
+class Lithora:
+    """Client for the Lithora REST API.
+
+    Args:
+        base_url: API root. Defaults to ``https://api.lithora.io``.
+            For local development use ``http://localhost:8000``.
+            (The SDK appends the ``/api`` prefix itself, so pass the bare host.)
+        token: An existing JWT bearer token. If omitted, call :meth:`login`.
+        timeout: Per-request timeout in seconds.
+
+    Example:
+        >>> client = Lithora(base_url="https://api.lithora.io")
+        >>> client.login("you@example.com", "hunter2-strong-pw")
+        >>> client.projects.list()
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        token: Optional[str] = None,
+        timeout: int = 30,
+    ) -> None:
+        # Normalize: strip a trailing slash and a trailing "/api" so callers can
+        # pass either "https://api.lithora.io" or "https://api.lithora.io/".
+        self.base_url = base_url.rstrip("/")
+        if self.base_url.endswith("/api"):
+            self.base_url = self.base_url[: -len("/api")]
+
+        self.timeout = timeout
+        self.token = token
+
+        self._session = requests.Session()
+        from . import __version__ as _v
+        self._session.headers.update({
+            "Accept": "application/json",
+            "User-Agent": "lithora-python/{}".format(_v),
+        })
+
+        # Resource namespaces -- each one calls back into this client's _request.
+        self.auth = AuthResource(self)
+        self.tokens = TokensResource(self)
+        self.teams = TeamsResource(self)
+        self.projects = ProjectsResource(self)
+        self.tasks = TasksResource(self)
+        self.work_items = WorkItemsResource(self)
+        self.automations = AutomationsResource(self)
+        self.github = GitHubResource(self)
+        self.search = SearchResource(self)
+        self.ai = AIResource(self)
+
+    # ------------------------------------------------------------------ #
+    # Token management
+    # ------------------------------------------------------------------ #
+    def set_token(self, token: Optional[str]) -> None:
+        """Set (or clear) the bearer token used for authenticated requests."""
+        self.token = token
+
+    # ------------------------------------------------------------------ #
+    # Auth helpers (kept on the client so token state lives in one place)
+    # ------------------------------------------------------------------ #
+    def login(self, email: str, password: str) -> Dict[str, Any]:
+        """Authenticate and store the returned JWT on the client.
+
+        Calls ``POST /api/auth/login``. On success the token is saved on the
+        client (used automatically for subsequent calls) and the ``user``
+        object is returned.
+
+        Raises:
+            AuthChallengeError: if the response asks for a login OTP or 2FA
+                code instead of returning a token.
+            AuthError: if the credentials are rejected (401).
+            ApiError: for any other non-2xx response.
+        """
+        data = self._request(
+            "POST",
+            "/auth/login",
+            json={"email": email, "password": password},
+            auth=False,
+        )
+
+        # The login endpoint may withhold the token pending a second factor.
+        if data.get("requires_2fa") or data.get("requires_login_otp"):
+            raise AuthChallengeError(
+                requires_2fa=bool(data.get("requires_2fa")),
+                requires_login_otp=bool(data.get("requires_login_otp")),
+                payload=data,
+            )
+
+        token = data.get("token")
+        if not token:
+            # Defensive: no token and no recognized challenge flag.
+            raise AuthChallengeError(payload=data)
+
+        self.set_token(token)
+        return data.get("user", {})
+
+    def register(
+        self,
+        email: str,
+        password: str,
+        name: str,
+        role: str = "member",
+    ) -> Dict[str, Any]:
+        """Create a new account via ``POST /api/auth/register``.
+
+        Args:
+            email: Account email.
+            password: Min 8 chars; must pass the server's strength check.
+            name: Display name.
+            role: One of ``"admin"``, ``"manager"``, ``"member"``.
+
+        Returns:
+            The decoded JSON response from the register endpoint.
+        """
+        return self._request(
+            "POST",
+            "/auth/register",
+            json={
+                "email": email,
+                "password": password,
+                "name": name,
+                "role": role,
+            },
+            auth=False,
+        )
+
+    # ------------------------------------------------------------------ #
+    # Core request plumbing
+    # ------------------------------------------------------------------ #
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Any] = None,
+        params: Optional[Dict[str, Any]] = None,
+        auth: bool = True,
+    ) -> Any:
+        """Send a request and return parsed JSON, raising typed errors.
+
+        Args:
+            method: HTTP verb, e.g. ``"GET"``, ``"POST"``.
+            path: Path *relative to* the ``/api`` prefix, e.g. ``"/projects"``.
+            json: Optional JSON-serializable request body.
+            params: Optional query-string parameters (``None`` values dropped).
+            auth: When True, attach the ``Authorization: Bearer`` header.
+
+        Raises:
+            AuthError: on a 401 response.
+            ServerError: on a 5xx response.
+            ApiError: on any other non-2xx response.
+        """
+        url = "{}/api{}".format(self.base_url, path)
+
+        headers: Dict[str, str] = {}
+        if auth:
+            if not self.token:
+                # Surface the missing-token case as an auth failure up front,
+                # instead of waiting for the server to 401.
+                raise AuthError(
+                    401,
+                    "No token set. Call client.login(...) or pass token=... to Lithora().",
+                )
+            headers["Authorization"] = "Bearer {}".format(self.token)
+
+        # Drop params whose value is None so callers can pass optional filters.
+        clean_params = (
+            {k: v for k, v in params.items() if v is not None} if params else None
+        )
+
+        response = self._session.request(
+            method,
+            url,
+            json=json,
+            params=clean_params,
+            headers=headers,
+            timeout=self.timeout,
+        )
+
+        return self._handle(response)
+
+    @staticmethod
+    def _handle(response: requests.Response) -> Any:
+        """Map a ``requests.Response`` to parsed JSON or a typed exception."""
+        if response.ok:  # 2xx
+            if response.status_code == 204 or not response.content:
+                return None
+            try:
+                return response.json()
+            except ValueError:
+                return response.text
+
+        # Error path: pull "detail" out of the FastAPI error envelope if we can.
+        detail: Any
+        try:
+            body = response.json()
+            detail = body.get("detail", body) if isinstance(body, dict) else body
+        except ValueError:
+            detail = response.text or response.reason
+
+        status = response.status_code
+        if status == 401:
+            raise AuthError(status, detail, response)
+        if status >= 500:
+            raise ServerError(status, detail, response)
+        raise ApiError(status, detail, response)

lithora-0.1.0/lithora/errors.py

@@ -0,0 +1,79 @@
+"""Typed exceptions raised by the Lithora SDK.
+
+The hierarchy is intentionally shallow so callers can catch broadly
+(``except LithoraError``) or narrowly (``except AuthError``).
+
+    LithoraError                 base for everything this SDK raises
+    +-- ApiError                 any non-2xx HTTP response (carries status + detail)
+        +-- AuthError            401 -- bad/missing/expired token
+        +-- ServerError          5xx -- something broke on Lithora's side
+    +-- AuthChallengeError       login succeeded but needs OTP / 2FA before a token is issued
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class LithoraError(Exception):
+    """Base class for all errors raised by the Lithora SDK."""
+
+
+class ApiError(LithoraError):
+    """Raised for any non-2xx HTTP response from the API.
+
+    FastAPI returns errors as ``{"detail": "..."}``; ``detail`` is parsed
+    out of the body when present, otherwise it falls back to the raw text.
+
+    Attributes:
+        status: The HTTP status code (e.g. 400, 404, 422).
+        detail: The ``detail`` field from the JSON body, or the raw response text.
+        response: The underlying ``requests.Response`` (may be ``None``).
+    """
+
+    def __init__(self, status: int, detail: Any, response: Optional[Any] = None) -> None:
+        self.status = status
+        self.detail = detail
+        self.response = response
+        super().__init__("HTTP {}: {}".format(status, detail))
+
+
+class AuthError(ApiError):
+    """Raised on a 401 -- the token is missing, invalid, or expired."""
+
+
+class ServerError(ApiError):
+    """Raised on a 5xx -- the failure originated on Lithora's side."""
+
+
+class AuthChallengeError(LithoraError):
+    """Login did not return a token because a second factor is required.
+
+    The Lithora ``POST /api/auth/login`` endpoint may respond with
+    ``{"requires_login_otp": true}`` or ``{"requires_2fa": true}`` and *no*
+    token. Rather than silently pretend authentication succeeded, the SDK
+    raises this so the caller can prompt the user for the challenge.
+
+    Attributes:
+        requires_2fa: True when an authenticator/2FA code is required.
+        requires_login_otp: True when an emailed/SMS login OTP is required.
+        payload: The full JSON body returned by the login call.
+    """
+
+    def __init__(
+        self,
+        *,
+        requires_2fa: bool = False,
+        requires_login_otp: bool = False,
+        payload: Optional[dict] = None,
+    ) -> None:
+        self.requires_2fa = requires_2fa
+        self.requires_login_otp = requires_login_otp
+        self.payload = payload or {}
+        if requires_2fa:
+            reason = "two-factor authentication (2FA) code required"
+        elif requires_login_otp:
+            reason = "login one-time passcode (OTP) required"
+        else:
+            reason = "an additional authentication challenge is required"
+        super().__init__("Login incomplete: {}".format(reason))