everscribe 0.1.0__tar.gz

everscribe-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: ci
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install
+        run: pip install -e ".[dev,fastapi,flask,django,grpc]"
+      - name: Lint
+        run: ruff check .
+      - name: Typecheck
+        run: mypy src
+      - name: Test
+        run: pytest -q

everscribe-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Byte-compiled / optimized / cache
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage / type-check caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+
+# subagent scratch reports
+.*-report.md
+.grpc-spike.md

everscribe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Everscribe
+
+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.

everscribe-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.5
+Name: everscribe
+Version: 0.1.0
+Summary: Python SDK for the Everscribe audit-log API
+Project-URL: Homepage, https://everscribe.io
+Project-URL: Repository, https://github.com/everscribe/sdk-python
+Author: Everscribe
+License: MIT
+License-File: LICENSE
+Keywords: audit,audit-log,everscribe,observability,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: django>=4; extra == 'dev'
+Requires-Dist: flask>=2; extra == 'dev'
+Requires-Dist: grpcio>=1.60; extra == 'dev'
+Requires-Dist: httpx>=0.24; extra == 'dev'
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff==0.16.0; extra == 'dev'
+Requires-Dist: starlette>=0.27; extra == 'dev'
+Requires-Dist: types-grpcio; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: starlette>=0.27; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2; extra == 'flask'
+Provides-Extra: grpc
+Requires-Dist: grpcio>=1.60; extra == 'grpc'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<p>
+  <img src="assets/everscribe.svg" alt="Everscribe" height="64" align="middle">
+  &nbsp;&nbsp;<b>+</b>&nbsp;&nbsp;
+  <img src="assets/python.svg" alt="Python" height="56" align="middle">
+</p>
+
+<p>
+  <a href="https://pypi.org/project/everscribe/"><img src="https://img.shields.io/pypi/v/everscribe.svg" alt="PyPI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
+</p>
+
+# sdk-python
+
+Python SDK for the [Everscribe](https://everscribe.io) API. It exposes **middleware** that records an audit event per request, a **recorder** for writing append-only audit events directly, and a **minter** for issuing short-lived browser tokens for [embeddable components](https://github.com/everscribe/components).
+
+</div>
+
+## 📖 Setup Documentation
+
+| Setup link | What it is | Pick it when |
+|---|---|---|
+| [Hosted AI agent](https://everscribe.io/docs/quickstart/hosted-ui) | You install our GitHub App. Our server-side agent walks your repo, proposes a plan, and opens a PR you review. | You want zero hand-wiring and are fine granting Everscribe read access to your repo. Paid feature. |
+| [BYOK Claude Code skill](https://everscribe.io/docs/quickstart/skill) | Install the [`es` CLI](https://github.com/everscribe/cli) and run `es skills download setup`. That drops a skill into your Claude Code skills directory, and your own local Claude agent does the setup. Same behavior as the hosted agent, but against *your* Anthropic key, and your source never leaves your machine. | You do not want to grant Everscribe read access to your repo, and/or you want a free option and already have Claude Code. |
+| [Wire it up yourself](https://everscribe.io/docs/sdks/python-install) | Install the SDK and add the calls by hand. | You want full control, or you are instrumenting a small surface. |
+
+## Supported frameworks
+
+- `FastAPI`
+- `Starlette`
+- `Flask`
+- `Django`
+
+> [!NOTE]
+> Interceptors available for gRPC servers.
+
+Your framework missing? [Open an issue](https://github.com/everscribe/sdk-python/issues).
+
+## Additional resources
+
+- [Runnable examples](https://github.com/everscribe/examples): full-stack runnable
+apps for every Everscribe SDK.
+
+- [AI-assisted setup demo](https://github.com/everscribe/ai-assisted-setup-demo): Sample repo for trying AI setup against something disposable.
+
+- [Everscribe CLI](https://github.com/everscribe/cli): CLI for downloading the Claude skill and managing projects, API keys, events and more.
+
+- [Embeddable components](https://github.com/everscribe/components): drop-in audit
+trail UI for single and multi-tenant apps.

everscribe-0.1.0/README.md

@@ -0,0 +1,50 @@
+<div align="center">
+
+<p>
+  <img src="assets/everscribe.svg" alt="Everscribe" height="64" align="middle">
+  &nbsp;&nbsp;<b>+</b>&nbsp;&nbsp;
+  <img src="assets/python.svg" alt="Python" height="56" align="middle">
+</p>
+
+<p>
+  <a href="https://pypi.org/project/everscribe/"><img src="https://img.shields.io/pypi/v/everscribe.svg" alt="PyPI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
+</p>
+
+# sdk-python
+
+Python SDK for the [Everscribe](https://everscribe.io) API. It exposes **middleware** that records an audit event per request, a **recorder** for writing append-only audit events directly, and a **minter** for issuing short-lived browser tokens for [embeddable components](https://github.com/everscribe/components).
+
+</div>
+
+## 📖 Setup Documentation
+
+| Setup link | What it is | Pick it when |
+|---|---|---|
+| [Hosted AI agent](https://everscribe.io/docs/quickstart/hosted-ui) | You install our GitHub App. Our server-side agent walks your repo, proposes a plan, and opens a PR you review. | You want zero hand-wiring and are fine granting Everscribe read access to your repo. Paid feature. |
+| [BYOK Claude Code skill](https://everscribe.io/docs/quickstart/skill) | Install the [`es` CLI](https://github.com/everscribe/cli) and run `es skills download setup`. That drops a skill into your Claude Code skills directory, and your own local Claude agent does the setup. Same behavior as the hosted agent, but against *your* Anthropic key, and your source never leaves your machine. | You do not want to grant Everscribe read access to your repo, and/or you want a free option and already have Claude Code. |
+| [Wire it up yourself](https://everscribe.io/docs/sdks/python-install) | Install the SDK and add the calls by hand. | You want full control, or you are instrumenting a small surface. |
+
+## Supported frameworks
+
+- `FastAPI`
+- `Starlette`
+- `Flask`
+- `Django`
+
+> [!NOTE]
+> Interceptors available for gRPC servers.
+
+Your framework missing? [Open an issue](https://github.com/everscribe/sdk-python/issues).
+
+## Additional resources
+
+- [Runnable examples](https://github.com/everscribe/examples): full-stack runnable
+apps for every Everscribe SDK.
+
+- [AI-assisted setup demo](https://github.com/everscribe/ai-assisted-setup-demo): Sample repo for trying AI setup against something disposable.
+
+- [Everscribe CLI](https://github.com/everscribe/cli): CLI for downloading the Claude skill and managing projects, API keys, events and more.
+
+- [Embeddable components](https://github.com/everscribe/components): drop-in audit
+trail UI for single and multi-tenant apps.

everscribe-0.1.0/assets/everscribe.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" width="200" height="200">
+  <rect x="0" y="0" width="200" height="200" fill="#1e3a5f"/>
+  <!-- { ES } -->
+  <text x="100" y="124" font-family="'Helvetica Neue', 'Arial', sans-serif"
+        font-weight="500" font-size="72" fill="#f0f4f8"
+        text-anchor="middle">{ ES }</text>
+</svg>

everscribe-0.1.0/assets/python.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><linearGradient id="python-original-a" gradientUnits="userSpaceOnUse" x1="70.252" y1="1237.476" x2="170.659" y2="1151.089" gradientTransform="matrix(.563 0 0 -.568 -29.215 707.817)"><stop offset="0" stop-color="#5A9FD4"/><stop offset="1" stop-color="#306998"/></linearGradient><linearGradient id="python-original-b" gradientUnits="userSpaceOnUse" x1="209.474" y1="1098.811" x2="173.62" y2="1149.537" gradientTransform="matrix(.563 0 0 -.568 -29.215 707.817)"><stop offset="0" stop-color="#FFD43B"/><stop offset="1" stop-color="#FFE873"/></linearGradient><path fill="url(#python-original-a)" d="M63.391 1.988c-4.222.02-8.252.379-11.8 1.007-10.45 1.846-12.346 5.71-12.346 12.837v9.411h24.693v3.137H29.977c-7.176 0-13.46 4.313-15.426 12.521-2.268 9.405-2.368 15.275 0 25.096 1.755 7.311 5.947 12.519 13.124 12.519h8.491V67.234c0-8.151 7.051-15.34 15.426-15.34h24.665c6.866 0 12.346-5.654 12.346-12.548V15.833c0-6.693-5.646-11.72-12.346-12.837-4.244-.706-8.645-1.027-12.866-1.008zM50.037 9.557c2.55 0 4.634 2.117 4.634 4.721 0 2.593-2.083 4.69-4.634 4.69-2.56 0-4.633-2.097-4.633-4.69-.001-2.604 2.073-4.721 4.633-4.721z" transform="translate(0 10.26)"/><path fill="url(#python-original-b)" d="M91.682 28.38v10.966c0 8.5-7.208 15.655-15.426 15.655H51.591c-6.756 0-12.346 5.783-12.346 12.549v23.515c0 6.691 5.818 10.628 12.346 12.547 7.816 2.297 15.312 2.713 24.665 0 6.216-1.801 12.346-5.423 12.346-12.547v-9.412H63.938v-3.138h37.012c7.176 0 9.852-5.005 12.348-12.519 2.578-7.735 2.467-15.174 0-25.096-1.774-7.145-5.161-12.521-12.348-12.521h-9.268zM77.809 87.927c2.561 0 4.634 2.097 4.634 4.692 0 2.602-2.074 4.719-4.634 4.719-2.55 0-4.633-2.117-4.633-4.719 0-2.595 2.083-4.692 4.633-4.692z" transform="translate(0 10.26)"/><radialGradient id="python-original-c" cx="1825.678" cy="444.45" r="26.743" gradientTransform="matrix(0 -.24 -1.055 0 532.979 557.576)" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#B8B8B8" stop-opacity=".498"/><stop offset="1" stop-color="#7F7F7F" stop-opacity="0"/></radialGradient><path opacity=".444" fill="url(#python-original-c)" d="M97.309 119.597c0 3.543-14.816 6.416-33.091 6.416-18.276 0-33.092-2.873-33.092-6.416 0-3.544 14.815-6.417 33.092-6.417 18.275 0 33.091 2.872 33.091 6.417z"/></svg>

everscribe-0.1.0/pyproject.toml

@@ -0,0 +1,98 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# Single version literal: src/everscribe/__init__.py exports __version__ in
+# __all__, so a second copy here would drift and ship a wrong number.
+[tool.hatch.version]
+path = "src/everscribe/__init__.py"
+
+[project]
+name = "everscribe"
+dynamic = ["version"]
+description = "Python SDK for the Everscribe audit-log API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Everscribe" }]
+keywords = ["everscribe", "audit-log", "audit", "sdk", "observability"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+# Core is intentionally zero-dependency: uuid, json, urllib, threading, queue,
+# and contextvars are all part of the Python standard library.
+dependencies = []
+
+[project.optional-dependencies]
+# ASGI adapter (FastAPI, Starlette, and any other ASGI app). FastAPI bundles
+# Starlette, so depending on Starlette alone covers both.
+fastapi = ["starlette>=0.27"]
+flask = ["flask>=2"]
+django = ["django>=4"]
+grpc = ["grpcio>=1.60"]
+dev = [
+    "pytest>=7",
+    "starlette>=0.27",
+    "httpx>=0.24",
+    "flask>=2",
+    "django>=4",
+    "grpcio>=1.60",
+    "types-grpcio",
+    "mypy>=1.5",
+    # Pinned exactly: ruff's default rule set widens between releases, so an
+    # unpinned range silently fails CI on code that never changed. Bump this
+    # deliberately and re-run `ruff check` when adopting a new version.
+    "ruff==0.16.0",
+]
+
+[project.urls]
+Homepage = "https://everscribe.io"
+Repository = "https://github.com/everscribe/sdk-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/everscribe"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+filterwarnings = [
+    # Starlette's TestClient warns about the installed httpx version; external,
+    # test-only, and unrelated to the SDK.
+    "ignore:Using .httpx. with .starlette.testclient. is deprecated",
+]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/everscribe"]
+
+[[tool.mypy.overrides]]
+# Django ships no py.typed marker / inline stubs (unlike Starlette, which
+# this project's ASGI adapter depends on cleanly). Only the adapter's own
+# code is type-checked strictly; Django's surface is treated as untyped.
+module = "django.*"
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# Select explicitly rather than inheriting ruff's default set, which widens
+# between releases and would reintroduce the drift the pinned version guards
+# against. E is scoped to the logical-error subset (E4/E7/E9); line-length and
+# whitespace formatting (E1/E2/E5) are left out, since this repo gates on a
+# linter, not a formatter, matching the Go SDK's no-gofmt-check stance.
+select = ["E4", "E7", "E9", "F", "I", "B", "C4", "DTZ", "UP", "RUF", "BLE"]
+# __all__ blocks are grouped by section with comments on purpose; RUF022's
+# isort-style sort scatters those groups. Keep the human-readable grouping.
+ignore = ["RUF022"]

everscribe-0.1.0/src/everscribe/__init__.py

@@ -0,0 +1,49 @@
+"""Everscribe Python SDK.
+
+Python SDK for the Everscribe audit-log API. Two coordinated surfaces:
+
+- :mod:`everscribe.recorder` - append-only event ingest.
+- :mod:`everscribe.minter` - short-lived embed tokens for frontend audit views.
+
+Bind credentials once with :func:`new` (or :func:`new_from_env`) and create
+per-surface subclients from the returned :class:`Client`::
+
+    import everscribe
+
+    es = everscribe.new(project_id, api_key)
+    rec = es.new_recorder()
+    rec.record(everscribe.Event("user.login"))
+
+The core is zero-dependency (standard library only). The optional ASGI adapter
+lives in :mod:`everscribe.asgi` (install the ``fastapi`` extra).
+"""
+
+from __future__ import annotations
+
+from . import event, minter, recorder
+from .client import (
+    EVERSCRIBE_API_KEY,
+    EVERSCRIBE_PROJECT_ID,
+    Client,
+    new,
+    new_from_env,
+)
+from .event import Event
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Root client
+    "Client",
+    "new",
+    "new_from_env",
+    "EVERSCRIBE_PROJECT_ID",
+    "EVERSCRIBE_API_KEY",
+    # Event model
+    "Event",
+    # Subpackages
+    "event",
+    "recorder",
+    "minter",
+]

everscribe-0.1.0/src/everscribe/asgi.py

@@ -0,0 +1,155 @@
+"""ASGI middleware for FastAPI / Starlette (and any ASGI app).
+
+This adapter supplies only ASGI-specific transport bindings; the record
+lifecycle itself (the request-scoped current event, dedupe, idempotency-key
+stamping, and the final-outcome rule) lives in :mod:`everscribe.event` so
+other framework adapters (Flask, Django, gRPC) can reuse it identically.
+
+It:
+
+1. Builds an Event template (actor from ``resolve_actor``, origin from the
+   request) and installs it, via :func:`everscribe.event.request_scope`, in
+   the request-scoped context so handlers can pull fresh events with
+   :func:`everscribe.event.new_from_context`.
+2. Installs a status capture so :func:`everscribe.event.prepare_event` can
+   auto-populate the event's ``result`` from the final HTTP status when the
+   handler hasn't set one explicitly.
+3. Exposes a single per-request mutable Event via :func:`everscribe.event.current_event`
+   (re-exported here as :func:`current_event`, and available at
+   ``request.state.everscribe_event``) for handlers to enrich (action,
+   target, metadata, optionally result).
+4. If a ``recorder`` was configured, records that event once when the response
+   finishes via :func:`everscribe.event.end_event` - but only when the handler
+   set ``action`` (empty action is a no-op), and only if nothing already
+   claimed the dedupe flag. Auto-record failures are logged, never raised: an
+   audit failure must not break the user-facing response.
+
+Mount it AFTER any session/auth middleware, since ``resolve_actor`` typically
+reads identity off the request.
+
+Requires Starlette (``pip install "everscribe[fastapi]"``).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+
+try:
+    from starlette.requests import Request
+    from starlette.types import ASGIApp, Message, Receive, Scope, Send
+except ImportError as e:  # pragma: no cover - exercised via install extras
+    raise ImportError(
+        "everscribe.asgi requires Starlette. Install it with: "
+        'pip install "everscribe[fastapi]"'
+    ) from e
+
+from .event import (
+    Event,
+    current_event,
+    end_event,
+    origin_from_request,
+    request_scope,
+    result_from_http_status,
+)
+from .event.types import Actor, Logger, Result
+from .recorder import Recorder
+
+ActorResolver = Callable[[Request], Actor]
+"""Derives the :class:`Actor` for a request. Typically reads session/auth
+state off the Starlette ``Request``. Must not consume the request body."""
+
+_ANONYMOUS = Actor(type="anonymous")
+
+
+def event_from_request(request: Request) -> Event:
+    """Return the per-request event from ``request.state``, falling back to
+    :func:`current_event`."""
+    e = getattr(request.state, "everscribe_event", None)
+    return e if isinstance(e, Event) else current_event()
+
+
+class _StatusCapture:
+    """Captures the response status from the ASGI ``http.response.start``
+    message and translates it into a :class:`Result` on demand, satisfying
+    :class:`everscribe.event.OutcomeCapture`.
+
+    Status 0 (nothing written yet) maps to ``outcome`` being ``None`` -
+    :func:`result_from_http_status` is only consulted once a status has
+    actually been captured.
+    """
+
+    def __init__(self) -> None:
+        self._status = 0
+
+    def set_status(self, status: int) -> None:
+        self._status = status
+
+    @property
+    def outcome(self) -> Result | None:
+        if self._status == 0:
+            return None
+        return result_from_http_status(self._status)
+
+
+class EverscribeMiddleware:
+    """ASGI middleware that installs a per-request audit event and (optionally)
+    auto-records it on response finish.
+
+    Add it to a Starlette/FastAPI app::
+
+        app.add_middleware(
+            EverscribeMiddleware,
+            recorder=rec,
+            resolve_actor=lambda req: Actor(type="user", id=req.state.user_id),
+        )
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        recorder: Recorder | None = None,
+        resolve_actor: ActorResolver | None = None,
+        logger: Logger | None = None,
+    ) -> None:
+        self.app = app
+        self.recorder = recorder
+        self.resolve_actor: ActorResolver = resolve_actor or (lambda req: _ANONYMOUS)
+        self.logger: Logger = logger or logging.getLogger("everscribe.asgi")
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        request = Request(scope, receive=receive)
+        template = Event()
+        template.actor = self.resolve_actor(request)
+        remote = request.client.host if request.client else ""
+        template.origin = origin_from_request(dict(request.headers), remote)
+
+        capture = _StatusCapture()
+
+        async def send_wrapper(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                capture.set_status(int(message["status"]))
+            await send(message)
+
+        with request_scope(template, capture) as user_event:
+            scope.setdefault("state", {})["everscribe_event"] = user_event
+            try:
+                await self.app(scope, receive, send_wrapper)
+            finally:
+                # end_event applies the final outcome (including the "no
+                # response written" sentinel) and records user_event once,
+                # skipping it if a handler already recorded it manually.
+                end_event(user_event, self.recorder, self.logger)
+
+
+__all__ = [
+    "ActorResolver",
+    "EverscribeMiddleware",
+    "current_event",
+    "event_from_request",
+]

everscribe-0.1.0/src/everscribe/client.py

@@ -0,0 +1,102 @@
+"""The top-level Everscribe client: binds a project's credentials once and
+hands out per-surface subclients (recorder for ingest, minter for read-side
+embed tokens) that share the same auth.
+
+Typical usage::
+
+    import everscribe
+
+    es = everscribe.new(project_id, api_key)      # or new_from_env()
+    rec = es.new_recorder()
+    try:
+        ...
+    finally:
+        rec.close()
+
+    m = es.new_minter()
+    token = m.mint_token(everscribe.minter.TokenOptions(...))
+
+Customers who only need one surface can call its constructor directly -
+``everscribe.recorder.new(project_id, api_key)`` and
+``everscribe.minter.Client(project_id, api_key)`` both work and skip the
+client step.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from .minter import Client as MinterClient
+from .recorder import BufferedRecorder
+from .recorder import new as _recorder_new
+
+#: Environment-variable names read by :func:`new_from_env`.
+EVERSCRIBE_PROJECT_ID = "EVERSCRIBE_PROJECT_ID"
+EVERSCRIBE_API_KEY = "EVERSCRIBE_API_KEY"
+
+
+class Client:
+    """Credential-bearing handle to an Everscribe project. Holds no network
+    state itself; the subclient constructors build per-surface clients that own
+    their own connections. Reuse a single Client for the lifetime of the
+    process - safe for concurrent use."""
+
+    def __init__(self, project_id: str, api_key: str) -> None:
+        """Validate and trim credentials. Raises :class:`ValueError` if either
+        is empty or whitespace-only, so configuration bugs surface at
+        construction rather than at the first network call."""
+        project_id = project_id.strip()
+        if not project_id:
+            raise ValueError("everscribe: project_id is empty")
+        api_key = api_key.strip()
+        if not api_key:
+            raise ValueError("everscribe: api_key is empty")
+        self.project_id = project_id
+        self._api_key = api_key
+
+    @classmethod
+    def from_env(cls) -> Client:
+        """Construct a Client from ``EVERSCRIBE_PROJECT_ID`` and
+        ``EVERSCRIBE_API_KEY``. Raises :class:`ValueError` naming the missing
+        variable if either is unset or empty after trimming."""
+        project_id = os.environ.get(EVERSCRIBE_PROJECT_ID, "").strip()
+        if not project_id:
+            raise ValueError(f"everscribe: {EVERSCRIBE_PROJECT_ID} is not set or empty")
+        api_key = os.environ.get(EVERSCRIBE_API_KEY, "").strip()
+        if not api_key:
+            raise ValueError(f"everscribe: {EVERSCRIBE_API_KEY} is not set or empty")
+        return cls(project_id, api_key)
+
+    def new_recorder(self, **opts: Any) -> BufferedRecorder:
+        """Return a buffered recorder for the bound project. Keyword options
+        forward to :func:`everscribe.recorder.new` (buffer_size, flush_interval,
+        base_url, ...)."""
+        return _recorder_new(self.project_id, self._api_key, **opts)
+
+    def new_minter(self, **opts: Any) -> MinterClient:
+        """Return a minter client for the bound project. Keyword options
+        forward to :class:`everscribe.minter.Client` (base_url,
+        request_timeout, ...)."""
+        return MinterClient(self.project_id, self._api_key, **opts)
+
+
+def new(project_id: str, api_key: str) -> Client:
+    """Construct a :class:`Client`. Raises :class:`ValueError` on
+    empty/whitespace credentials."""
+    return Client(project_id, api_key)
+
+
+def new_from_env() -> Client:
+    """Construct a :class:`Client` from environment variables. See
+    :meth:`Client.from_env`."""
+    return Client.from_env()
+
+
+__all__ = [
+    "EVERSCRIBE_API_KEY",
+    "EVERSCRIBE_PROJECT_ID",
+    "Client",
+    "new",
+    "new_from_env",
+]