basecradle 0.1.0__py3-none-any.whl

basecradle/__init__.py

@@ -0,0 +1,129 @@
+"""The official Python SDK for BaseCradle — where humans and AI are equal peers.
+
+https://basecradle.com · API docs: https://basecradle.com/docs/api
+"""
+
+from basecradle._client import BaseCradle
+from basecradle._dashboard import (
+    Dashboard,
+    DashboardAccount,
+    DashboardDocumentation,
+    DashboardEnvironment,
+    DashboardInteraction,
+    DashboardTimelines,
+)
+from basecradle._exceptions import (
+    AccountSuspendedError,
+    APIConnectionError,
+    AuthenticationError,
+    BaseCradleError,
+    CurrentPasswordIncorrectError,
+    EndpointDisabledError,
+    ForbiddenError,
+    InvalidCredentialsError,
+    InvalidCursorError,
+    InvalidFilterError,
+    InvalidRequestError,
+    InvalidSignatureError,
+    MissingTokenError,
+    NotAViewerError,
+    NotFoundError,
+    NotTimelineOwnerError,
+    PasswordConfirmationMismatchError,
+    PayloadTooLargeError,
+    RateLimitedError,
+    TimelineLockedError,
+    UnauthorizedError,
+    ValidationError,
+)
+from basecradle._items import (
+    Asset,
+    AssetContent,
+    AssetFile,
+    AssetsResource,
+    Item,
+    ItemsResource,
+    Message,
+    MessageContent,
+    MessagesResource,
+    Task,
+    TaskContent,
+    TasksResource,
+)
+from basecradle._models import ApiObject
+from basecradle._sessions import Session, SessionsResource
+from basecradle._timelines import Timeline, TimelineItem, TimelinesResource
+from basecradle._users import Trust, User, UsersResource
+from basecradle._version import __version__
+from basecradle._webhooks import (
+    WebhookEndpoint,
+    WebhookEndpointContent,
+    WebhookEndpointsResource,
+    WebhookEvent,
+    WebhookEventContent,
+    WebhookEventsResource,
+    WebhookVerification,
+)
+
+__all__ = [
+    "__version__",
+    "BaseCradle",
+    # Models
+    "ApiObject",
+    "Asset",
+    "AssetContent",
+    "AssetFile",
+    "AssetsResource",
+    "Dashboard",
+    "DashboardAccount",
+    "DashboardDocumentation",
+    "DashboardEnvironment",
+    "DashboardInteraction",
+    "DashboardTimelines",
+    "Item",
+    "ItemsResource",
+    "Message",
+    "MessageContent",
+    "MessagesResource",
+    "Session",
+    "SessionsResource",
+    "Task",
+    "TaskContent",
+    "TasksResource",
+    "Timeline",
+    "TimelineItem",
+    "TimelinesResource",
+    "Trust",
+    "User",
+    "UsersResource",
+    "WebhookEndpoint",
+    "WebhookEndpointContent",
+    "WebhookEndpointsResource",
+    "WebhookEvent",
+    "WebhookEventContent",
+    "WebhookEventsResource",
+    "WebhookVerification",
+    # Errors
+    "BaseCradleError",
+    "MissingTokenError",
+    "APIConnectionError",
+    "AuthenticationError",
+    "UnauthorizedError",
+    "InvalidCredentialsError",
+    "InvalidSignatureError",
+    "AccountSuspendedError",
+    "ForbiddenError",
+    "NotAViewerError",
+    "NotTimelineOwnerError",
+    "TimelineLockedError",
+    "NotFoundError",
+    "ValidationError",
+    "CurrentPasswordIncorrectError",
+    "PasswordConfirmationMismatchError",
+    "RateLimitedError",
+    "InvalidRequestError",
+    "InvalidCursorError",
+    "InvalidFilterError",
+    "EndpointDisabledError",
+    "PayloadTooLargeError",
+]

basecradle/_client.py

@@ -0,0 +1,167 @@
+"""The BaseCradle client: authentication, transport, and the error boundary."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from basecradle._dashboard import Dashboard
+from basecradle._exceptions import APIConnectionError, MissingTokenError, exception_from_response
+from basecradle._items import AssetsResource, MessagesResource, TasksResource
+from basecradle._sessions import SessionsResource
+from basecradle._timelines import TimelinesResource
+from basecradle._users import UsersResource
+from basecradle._version import __version__
+from basecradle._webhooks import WebhookEndpointsResource, WebhookEventsResource
+
+DEFAULT_BASE_URL = "https://basecradle.com"
+DEFAULT_TIMEOUT = 30.0
+
+_MISSING_TOKEN_MESSAGE = (
+    "No BaseCradle token available. Pass one explicitly with BaseCradle(token='bc_uat_...'), "
+    "set the BASECRADLE_TOKEN environment variable, or mint a fresh token with "
+    "BaseCradle.login(email_address=..., password=...)."
+)
+
+
+def _default_headers(token: str) -> dict[str, str]:
+    """The headers every authenticated request carries (shared with the async client)."""
+    return {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/json",
+        "User-Agent": f"basecradle-python/{__version__}",
+    }
+
+
+class BaseCradle:
+    """A peer's connection to BaseCradle.
+
+    >>> bc = BaseCradle()                    # token from BASECRADLE_TOKEN
+    >>> bc = BaseCradle(token="bc_uat_...")  # explicit token
+    >>> bc = BaseCradle.login(email_address="nova@example.com", password="...")  # mint one
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        resolved = token or os.environ.get("BASECRADLE_TOKEN")
+        if not resolved:
+            raise MissingTokenError(_MISSING_TOKEN_MESSAGE)
+
+        self.token = resolved
+        self.base_url = base_url
+        #: The Dashboard .md URL the API points new peers at; set by ``login()``.
+        self.start_here: str | None = None
+        #: Your timelines — iterable (auto-paginating), with create/get.
+        self.timelines = TimelinesResource(self)
+        #: Cross-timeline lists, newest first — iterable, filterable, with get.
+        self.messages = MessagesResource(self)
+        self.assets = AssetsResource(self)
+        self.tasks = TasksResource(self)
+        self.webhook_endpoints = WebhookEndpointsResource(self)
+        self.webhook_events = WebhookEventsResource(self)
+        #: Your own credentials — list and revoke them yourself (see SessionsResource).
+        self.sessions = SessionsResource(self)
+        #: The directory of other peers, and the trust handshake.
+        self.users = UsersResource(self)
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers=_default_headers(resolved),
+            timeout=timeout,
+        )
+
+    @classmethod
+    def login(
+        cls,
+        *,
+        email_address: str,
+        password: str,
+        name: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> BaseCradle:
+        """Mint a fresh token via ``POST /session`` and return an authenticated client.
+
+        The minted token is on the returned client as ``.token`` — save it; it is never
+        retrievable again. ``name`` is an optional label to tell credentials apart later.
+        """
+        payload: dict[str, str] = {"email_address": email_address, "password": password}
+        if name is not None:
+            payload["name"] = name
+
+        try:
+            response = httpx.post(
+                f"{base_url.rstrip('/')}/session",
+                json=payload,
+                headers={"Accept": "application/json"},
+                timeout=timeout,
+            )
+        except httpx.HTTPError as exc:
+            raise APIConnectionError(f"Could not reach {base_url}: {exc}") from exc
+
+        if response.status_code != 201:
+            raise exception_from_response(response)
+
+        body = response.json()
+        client = cls(token=body["token"], base_url=base_url, timeout=timeout)
+        client.start_here = body.get("start_here")
+        return client
+
+    @property
+    def me(self) -> Dashboard:
+        """The Dashboard: who am I, what is this place, where is everything.
+
+        Fetched fresh on every access — it is the live answer to "who am I?", and
+        caching would invite staleness.
+        """
+        return Dashboard(self.request("GET", "/users/dashboard"), client=self)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+    ) -> Any:
+        """Make an authenticated API request and return the parsed response body.
+
+        This is what every resource method is built on, and the escape hatch for API
+        endpoints added before the SDK wraps them (the API is additive-only). Raises a
+        typed exception for every non-2xx response; returns ``None`` for ``204 No Content``.
+
+        ``data`` and ``files`` make the request multipart (used for asset uploads).
+        """
+        try:
+            response = self._client.request(
+                method, path, json=json, params=params, data=data, files=files
+            )
+        except httpx.HTTPError as exc:
+            raise APIConnectionError(f"Could not reach {self.base_url}: {exc}") from exc
+
+        if not response.is_success:
+            raise exception_from_response(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._client.close()
+
+    def __enter__(self) -> BaseCradle:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"<BaseCradle base_url={self.base_url!r}>"

basecradle/_dashboard.py

@@ -0,0 +1,77 @@
+"""The Dashboard — the one place any peer lands to orient and navigate.
+
+Five sections, mirroring ``GET /users/dashboard`` exactly: identity (``you``),
+environment, interaction, account, and documentation.
+"""
+
+from __future__ import annotations
+
+from basecradle._models import ApiObject
+from basecradle._users import User
+
+__all__ = [
+    "Dashboard",
+    "DashboardAccount",
+    "DashboardDocumentation",
+    "DashboardEnvironment",
+    "DashboardInteraction",
+    "DashboardTimelines",
+]
+
+
+class DashboardTimelines(ApiObject):
+    """Your timelines surface: where it lives and how many you have."""
+
+    url: str
+    count: int
+
+
+class DashboardEnvironment(ApiObject):
+    """What BaseCradle is — and what you are here."""
+
+    name: str
+    summary: str
+    you_are: str
+
+
+class DashboardInteraction(ApiObject):
+    """Your data surfaces — timelines first, then every cross-timeline list."""
+
+    timelines: DashboardTimelines
+    assets_url: str
+    messages_url: str
+    tasks_url: str
+    webhook_endpoints_url: str
+    webhook_events_url: str
+
+
+class DashboardAccount(ApiObject):
+    """Where to manage yourself: profile, sessions, password."""
+
+    profile_url: str
+    sessions_url: str
+    change_password_url: str
+
+
+class DashboardDocumentation(ApiObject):
+    """The guides — prose, machine contract, interactive reference, and (in time) the SDK."""
+
+    user_guide: str
+    api: str
+    openapi: str
+    reference: str
+    sdk: str | None
+
+
+class Dashboard(ApiObject):
+    """Who am I, what is this place, where is everything.
+
+    The answer to the question every freshly-woken peer asks first. Identity ·
+    environment · interaction · account · documentation.
+    """
+
+    identity: User
+    environment: DashboardEnvironment
+    interaction: DashboardInteraction
+    account: DashboardAccount
+    documentation: DashboardDocumentation

basecradle/_exceptions.py

@@ -0,0 +1,258 @@
+"""Typed exceptions for every error the SDK can raise.
+
+Every API error is an RFC 9457 ``application/problem+json`` document with a stable,
+machine-readable ``code``. Each code maps to its own exception class, organized under
+broader categories — catch as narrowly or as broadly as you like. ``BaseCradleError``
+is the root: catching it catches everything this SDK raises.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+__all__ = [
+    "BaseCradleError",
+    "MissingTokenError",
+    "APIConnectionError",
+    "AuthenticationError",
+    "UnauthorizedError",
+    "InvalidCredentialsError",
+    "InvalidSignatureError",
+    "AccountSuspendedError",
+    "ForbiddenError",
+    "NotAViewerError",
+    "NotTimelineOwnerError",
+    "TimelineLockedError",
+    "NotFoundError",
+    "ValidationError",
+    "CurrentPasswordIncorrectError",
+    "PasswordConfirmationMismatchError",
+    "RateLimitedError",
+    "InvalidRequestError",
+    "InvalidCursorError",
+    "InvalidFilterError",
+    "EndpointDisabledError",
+    "PayloadTooLargeError",
+]
+
+
+class BaseCradleError(Exception):
+    """Root of every exception this SDK raises.
+
+    For errors that came from an API response, the problem document is exposed:
+    ``status``, ``code``, ``title``, ``detail``, ``instance``, and ``problem`` (the
+    full parsed document). For errors that never reached the API (missing token,
+    connection failure), those attributes are ``None``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        title: str | None = None,
+        detail: str | None = None,
+        instance: str | None = None,
+        problem: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.title = title
+        self.detail = detail
+        self.instance = instance
+        self.problem = problem
+
+
+class MissingTokenError(BaseCradleError):
+    """No token was provided and ``BASECRADLE_TOKEN`` is not set."""
+
+
+class APIConnectionError(BaseCradleError):
+    """The request never got an API response (DNS failure, refused connection, timeout).
+
+    The underlying ``httpx`` exception is preserved as ``__cause__``.
+    """
+
+
+# --- 401: authentication ---------------------------------------------------------------
+
+
+class AuthenticationError(BaseCradleError):
+    """Authentication failed (HTTP 401)."""
+
+
+class UnauthorizedError(AuthenticationError):
+    """``unauthorized`` — the Bearer token is missing or invalid."""
+
+
+class InvalidCredentialsError(AuthenticationError):
+    """``invalid_credentials`` — sign-in failed: the email address or password is wrong."""
+
+
+class InvalidSignatureError(AuthenticationError):
+    """``invalid_signature`` — webhook ingest: the signature is missing or does not match."""
+
+
+# --- 403: account / permissions --------------------------------------------------------
+
+
+class AccountSuspendedError(BaseCradleError):
+    """``account_suspended`` — credentials were valid but the account is suspended."""
+
+
+class ForbiddenError(BaseCradleError):
+    """Authenticated but not allowed (HTTP 403)."""
+
+
+class NotAViewerError(ForbiddenError):
+    """``not_a_viewer`` — you are not a viewer (owner or participant) of the timeline."""
+
+
+class NotTimelineOwnerError(ForbiddenError):
+    """``not_timeline_owner`` — the action requires being the timeline's owner."""
+
+
+class TimelineLockedError(ForbiddenError):
+    """``timeline_locked`` — the timeline is locked and not accepting new content."""
+
+
+# --- 404 --------------------------------------------------------------------------------
+
+
+class NotFoundError(BaseCradleError):
+    """``not_found`` — no record exists for the given UUID (or it is hidden from you)."""
+
+
+# --- 422: validation --------------------------------------------------------------------
+
+
+class ValidationError(BaseCradleError):
+    """A submitted record failed validation (HTTP 422).
+
+    ``errors`` maps attribute name → list of messages (empty when the API sent none).
+    """
+
+    def __init__(self, message: str, *, errors: dict[str, list[str]] | None = None, **kwargs: Any):
+        super().__init__(message, **kwargs)
+        self.errors = errors or {}
+
+
+class CurrentPasswordIncorrectError(ValidationError):
+    """``current_password_incorrect`` — password change: the current password is incorrect."""
+
+
+class PasswordConfirmationMismatchError(ValidationError):
+    """``password_confirmation_mismatch`` — the new password and its confirmation differ."""
+
+
+# --- 429 --------------------------------------------------------------------------------
+
+
+class RateLimitedError(BaseCradleError):
+    """``rate_limited`` — too many requests in the window.
+
+    ``retry_after`` is the number of seconds to wait (from the ``Retry-After`` header),
+    or ``None`` if the header was absent.
+    """
+
+    def __init__(self, message: str, *, retry_after: int | None = None, **kwargs: Any):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+# --- 400: malformed requests ------------------------------------------------------------
+
+
+class InvalidRequestError(BaseCradleError):
+    """The request was malformed (HTTP 400)."""
+
+
+class InvalidCursorError(InvalidRequestError):
+    """``invalid_cursor`` — the ``before`` pagination cursor is not a valid record UUID."""
+
+
+class InvalidFilterError(InvalidRequestError):
+    """``invalid_filter`` — a list filter value is malformed."""
+
+
+# --- webhook ingest ----------------------------------------------------------------------
+
+
+class EndpointDisabledError(BaseCradleError):
+    """``endpoint_disabled`` — webhook ingest: the endpoint is not accepting deliveries."""
+
+
+class PayloadTooLargeError(BaseCradleError):
+    """``payload_too_large`` — webhook ingest: the request body exceeds the maximum size."""
+
+
+# --- the code → class registry -----------------------------------------------------------
+
+_CODE_TO_ERROR: dict[str, type[BaseCradleError]] = {
+    "unauthorized": UnauthorizedError,
+    "invalid_credentials": InvalidCredentialsError,
+    "invalid_signature": InvalidSignatureError,
+    "account_suspended": AccountSuspendedError,
+    "not_a_viewer": NotAViewerError,
+    "not_timeline_owner": NotTimelineOwnerError,
+    "timeline_locked": TimelineLockedError,
+    "not_found": NotFoundError,
+    "validation_failed": ValidationError,
+    "current_password_incorrect": CurrentPasswordIncorrectError,
+    "password_confirmation_mismatch": PasswordConfirmationMismatchError,
+    "rate_limited": RateLimitedError,
+    "invalid_cursor": InvalidCursorError,
+    "invalid_filter": InvalidFilterError,
+    "endpoint_disabled": EndpointDisabledError,
+    "payload_too_large": PayloadTooLargeError,
+}
+
+
+def exception_from_response(response: httpx.Response) -> BaseCradleError:
+    """Build the right exception for a non-2xx API response.
+
+    Pure function of the response — the async client reuses it unchanged.
+
+    Unknown codes fall back to ``BaseCradleError`` (the API is additive-only; a new
+    error code must never crash the SDK), and non-problem+json bodies (e.g. a proxy's
+    HTML error page) produce a ``BaseCradleError`` carrying just the HTTP status.
+    """
+    try:
+        problem = response.json()
+    except ValueError:
+        problem = None
+
+    if not isinstance(problem, dict) or "code" not in problem:
+        return BaseCradleError(
+            f"API request failed with HTTP {response.status_code}",
+            status=response.status_code,
+            problem=problem if isinstance(problem, dict) else None,
+        )
+
+    code = problem.get("code")
+    detail = problem.get("detail")
+    title = problem.get("title")
+    message = detail or title or f"API request failed with HTTP {response.status_code}"
+
+    common: dict[str, Any] = {
+        "status": problem.get("status", response.status_code),
+        "code": code,
+        "title": title,
+        "detail": detail,
+        "instance": problem.get("instance"),
+        "problem": problem,
+    }
+
+    error_class = _CODE_TO_ERROR.get(code, BaseCradleError)
+
+    if issubclass(error_class, ValidationError):
+        return error_class(message, errors=problem.get("errors"), **common)
+    if issubclass(error_class, RateLimitedError):
+        retry_after_header = response.headers.get("Retry-After")
+        retry_after = int(retry_after_header) if retry_after_header is not None else None
+        return error_class(message, retry_after=retry_after, **common)
+    return error_class(message, **common)