htmlship 0.1.0__py3-none-any.whl

htmlship-0.1.0.dist-info/METADATA

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: htmlship
+Version: 0.1.0
+Summary: Host and share HTML pages from LLMs and coding agents in one line.
+Project-URL: Homepage, https://htmlship.com
+Project-URL: Repository, https://github.com/htmlship/htmlship
+Author: HTMLShip
+License: MIT
+Keywords: agent,hosting,html,llm,mcp,paste
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.12
+Requires-Dist: click<9,>=8.1
+Requires-Dist: httpx<0.28,>=0.27
+Provides-Extra: cli
+Requires-Dist: pyperclip<2,>=1.9; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.22.1; extra == 'dev'
+Requires-Dist: greenlet>=3.5.0; extra == 'dev'
+Requires-Dist: pytest-asyncio<0.25,>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov<6,>=5; extra == 'dev'
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: ruff<0.8,>=0.7; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.0; extra == 'mcp'
+Provides-Extra: server
+Requires-Dist: alembic<2,>=1.13; extra == 'server'
+Requires-Dist: argon2-cffi<24,>=23; extra == 'server'
+Requires-Dist: asyncpg<0.31,>=0.30; extra == 'server'
+Requires-Dist: boto3<2,>=1.35; extra == 'server'
+Requires-Dist: fastapi<0.116,>=0.115; extra == 'server'
+Requires-Dist: itsdangerous<3,>=2.2; extra == 'server'
+Requires-Dist: nanoid<3,>=2; extra == 'server'
+Requires-Dist: pydantic-settings<3,>=2.5; extra == 'server'
+Requires-Dist: pydantic<3,>=2; extra == 'server'
+Requires-Dist: python-multipart<0.1,>=0.0.12; extra == 'server'
+Requires-Dist: slowapi<0.2,>=0.1.9; extra == 'server'
+Requires-Dist: sqlalchemy<3,>=2.0; extra == 'server'
+Requires-Dist: uvicorn[standard]<0.33,>=0.32; extra == 'server'
+Description-Content-Type: text/markdown
+
+# HTMLShip
+
+Host and share HTML pages from LLMs and coding agents in one line.
+
+HTMLShip has three surfaces:
+
+- a public Python library and CLI (`htmlship`)
+- a FastAPI service for creating, updating, deleting, and viewing HTML pastes
+- a stdio MCP server (`htmlship-mcp`) for agent clients
+
+```bash
+pip install htmlship
+```
+
+```python
+import htmlship
+
+paste = htmlship.publish("<h1>Hello</h1>", title="Demo", expires_in=3600)
+print(paste.url)
+print(paste.owner_key)  # save this to update or delete the paste later
+```
+
+```bash
+curl -X POST https://api.htmlship.com/api/v1/pastes \
+  -H "Content-Type: application/json" \
+  -d '{"html":"<h1>Hello</h1>","title":"Demo"}'
+```
+
+See [`htmlship-implementation-spec.md`](./htmlship-implementation-spec.md) for the product spec and [`DEPLOY.md`](./DEPLOY.md) for the production runbook.
+
+## Python Library
+
+The module-level helpers use `https://api.htmlship.com` by default. Override with `HTMLSHIP_API_URL` or `htmlship.configure(base_url=...)`.
+
+```python
+import htmlship
+
+paste = htmlship.publish(
+    "<h1>Hello</h1>",
+    title="Demo",
+    password="optional-password",
+    expires_in=86400,
+)
+
+fresh = htmlship.get(paste.slug)
+updated = htmlship.update(paste.slug, "<h1>Updated</h1>", owner_key=paste.owner_key)
+htmlship.delete(updated.slug, owner_key=paste.owner_key)
+```
+
+`owner_key` is returned only when a paste is created. It is required for updates and deletes, and the API does not return it again from metadata calls.
+
+## CLI
+
+```bash
+htmlship publish report.html
+cat report.html | htmlship publish -
+htmlship publish --file report.html --title "Q4 Report" --expires-in 3600
+
+htmlship get <slug>
+htmlship update <slug> updated.html
+htmlship delete <slug>
+htmlship list-mine
+```
+
+The CLI stores owner keys in `~/.htmlship/keys.json` so `update`, `delete`, and `list-mine` can work with pastes you created locally. Set `HTMLSHIP_KEYS_DIR` to use another key-store directory, and set `HTMLSHIP_API_URL` to point the CLI at a local or staging API.
+
+## API
+
+Base URL: `https://api.htmlship.com`.
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `GET` | `/health` | Health check with service version. |
+| `GET` | `/version` | Service version. |
+| `POST` | `/api/v1/pastes` | Create a paste. |
+| `GET` | `/api/v1/pastes/{slug}` | Fetch paste metadata. |
+| `PATCH` | `/api/v1/pastes/{slug}` | Replace HTML or title. Requires `X-Owner-Key`. |
+| `DELETE` | `/api/v1/pastes/{slug}` | Soft-delete a paste. Requires `X-Owner-Key`. |
+| `POST` | `/api/v1/pastes/{slug}/version` | Create a new paste linked to an existing parent slug. |
+
+Create payload:
+
+```json
+{
+  "html": "<h1>Hello</h1>",
+  "title": "Optional title",
+  "password": "optional password",
+  "expires_in": 3600,
+  "parent_slug": "optional-parent",
+  "sandbox_mode": "strict"
+}
+```
+
+Notes:
+
+- `html` is stored and served verbatim. Scripts are blocked by the view CSP, not by sanitizing the body.
+- Payloads are limited to 10 MiB by default.
+- `expires_in` is in seconds and must be between 60 seconds and 365 days.
+- `sandbox_mode` accepts `strict` or `relaxed`; the current view headers use the strict CSP.
+- Password-protected views set a signed, HTTP-only session cookie after the correct password is submitted.
+
+## Rendering
+
+Rendered HTML is served from `view.htmlship.com/{slug}` with strict security headers:
+
+- `Content-Security-Policy: default-src 'none'`
+- images from `data:` and `https:`
+- inline styles plus HTTPS stylesheets
+- HTTPS/data fonts and HTTPS media
+- `X-Content-Type-Options: nosniff`
+- `Referrer-Policy: no-referrer`
+- restrictive `Permissions-Policy`
+
+The app routes by `Host` header:
+
+- `htmlship.com` serves the landing page
+- `api.htmlship.com` serves the API and landing assets
+- `view.htmlship.com/{slug}` serves sandboxed HTML
+
+For local development without DNS, append `?_host=view.htmlship.com` (or your configured view host) to spoof the host header, for example:
+
+```bash
+curl "http://localhost:8000/<slug>?_host=view.htmlship.com"
+```
+
+## MCP Server
+
+`htmlship-mcp` is a stdio MCP server exposing three tools:
+
+- `publish_html`
+- `fetch_html`
+- `update_html`
+
+All HTTP traffic goes through the public Python client. Configure the endpoint with `HTMLSHIP_API_URL`.
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows:
+
+```json
+{
+  "mcpServers": {
+    "htmlship": {
+      "command": "htmlship-mcp",
+      "env": {
+        "HTMLSHIP_API_URL": "https://api.htmlship.com"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Then ask: `publish this HTML: <h1>test</h1>`.
+
+### Claude Code
+
+Edit `~/.claude.json` or use `claude mcp add`:
+
+```json
+{
+  "mcpServers": {
+    "htmlship": {
+      "type": "stdio",
+      "command": "htmlship-mcp",
+      "env": {
+        "HTMLSHIP_API_URL": "https://api.htmlship.com"
+      }
+    }
+  }
+}
+```
+
+## Local Development
+
+Requirements:
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/)
+- Docker
+
+```bash
+# 1. Install dependencies (creates .venv)
+uv sync --extra server --extra cli --extra mcp --extra dev
+
+# 2. Start Postgres on localhost:5433
+docker compose up -d postgres
+
+# 3. Copy env and edit if needed
+cp .env.example .env
+
+# 4. Run migrations
+uv run alembic upgrade head
+
+# 5. Start the server
+uv run uvicorn htmlship_server.main:app --reload
+
+# 6. Health check
+curl http://localhost:8000/health
+```
+
+Run tests and linting:
+
+```bash
+uv run pytest
+uv run ruff check .
+```
+
+The test suite uses SQLite and a temporary local blob store. Local development uses Postgres metadata plus `./tmp/blobs/` for HTML blobs unless `SPACES_BUCKET` is configured.
+
+## Configuration
+
+The server reads `.env` via Pydantic settings.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `DATABASE_URL` | `postgresql+asyncpg://htmlship:htmlship@localhost:5433/htmlship` | Async SQLAlchemy database URL. |
+| `PUBLIC_BASE_DOMAIN` | `htmlship.com` | Base domain used to derive host routing. |
+| `API_BASE_URL` | `https://api.htmlship.com` | Public API URL setting. |
+| `VIEW_BASE_URL` | `https://view.htmlship.com` | Public view URL used in paste responses. |
+| `LANDING_BASE_URL` | `https://htmlship.com` | Public landing URL. |
+| `SPACES_BUCKET` | empty | If empty, use local blob storage; otherwise use DigitalOcean Spaces/S3. |
+| `SPACES_REGION` | `nyc3` | Spaces/S3 region. |
+| `SPACES_ENDPOINT_URL` | `https://nyc3.digitaloceanspaces.com` | Spaces/S3 endpoint. |
+| `SPACES_ACCESS_KEY` / `SPACES_SECRET_KEY` | empty | Spaces/S3 credentials. |
+| `SECRET_KEY` | development placeholder | Signs password-view session cookies. Use a strong value in production. |
+| `ENVIRONMENT` | `development` | Enables API docs outside production and secure cookies in production. |
+| `LOG_LEVEL` | `info` | Application log level. |
+| `MAX_PAYLOAD_BYTES` | `10485760` | Server-side HTML size limit. |
+| `DEFAULT_EXPIRES_IN_SECONDS` | empty | Optional default TTL for new pastes. |
+
+## Architecture
+
+One FastAPI process hosts the landing page, JSON API, and view renderer. `HostRoutingMiddleware` classifies requests by host and prevents API routes from being served on the view host.
+
+Postgres stores paste metadata, owner-key/password hashes, expiry, view counts, and parent-version links. HTML bodies are stored as blobs, either in `LocalBlobStore` for development/tests or DigitalOcean Spaces in production.
+
+## Project Layout
+
+```text
+src/htmlship/        Public Python library + CLI
+src/htmlship_server/ FastAPI app, API routers, storage, database models
+src/htmlship_mcp/    MCP server (stdio)
+web/                 Static landing page
+tests/               API, client, CLI, MCP, landing, and view tests
+alembic/             Database migrations
+deploy/              Production configs (nginx, systemd)
+scripts/             Deploy and smoke-test scripts
+```

htmlship-0.1.0.dist-info/RECORD

@@ -0,0 +1,29 @@
+htmlship/__init__.py,sha256=XnwrjZOXH58DxoOo6CobfD0WfdxOmprDeGdOxqbBIlo,2360
+htmlship/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+htmlship/cli.py,sha256=JwOMhqbxltApQbXP-sPnx3gmS9FlyquAE_bmcESAC7Y,9249
+htmlship/client.py,sha256=eSjvdTiS94gwG_-jZwAYzRsrAwzP14DdwTdZQwwTCfY,6665
+htmlship/exceptions.py,sha256=9P85j5FpjqT4s0z4fErCHfTnguWvbBXuv0UM3MtzjLc,775
+htmlship/models.py,sha256=OdRhEshJZF6rXrprS4QcmfMtiYtnkaIUNlf0FkKwRYU,2238
+htmlship_mcp/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+htmlship_mcp/server.py,sha256=GGYQ08X23HuPRaxyYtcsfHo5l6WEYZDVmS9rz_gtg4E,4059
+htmlship_server/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+htmlship_server/config.py,sha256=1wIeco_m22Kve-3Jt3h310MotfxJCf4a50FjfI2zHnw,1643
+htmlship_server/database.py,sha256=WRBpVqYJmFkXMVniGDiaX9j5HTJDoUxHnZSftqxF7qw,832
+htmlship_server/exceptions.py,sha256=fRR0Dz5PrFvrE8CfM5q53KED-1pr8VIGZ43ECW05-V0,160
+htmlship_server/main.py,sha256=NZ95It_GSQEwuhv9THAjfdvN5PXL506NXo0BoKbUbF0,2218
+htmlship_server/middleware.py,sha256=ZsCkv_AdSsU9hvl8HIHyna04VbZApyre-kJRMj-zfdI,4504
+htmlship_server/security.py,sha256=DwPiC1VORPGnzjOhy8DtB0dWfDEbJQsdDwRMNfIGBmA,1037
+htmlship_server/slugs.py,sha256=Gylvapqka6SSxfYkC1ZJEaQu5NKUtfTsgzHtTMDF__Q,1040
+htmlship_server/storage.py,sha256=Mv7W2xCH9mlPzzshkU4aG8ArlO65YfKUR9hYrOGmLnI,3875
+htmlship_server/db_models/__init__.py,sha256=gLN65iq3xYnEw9Rvhre88i3gw8QBMJMda_33sYncKDo,60
+htmlship_server/db_models/paste.py,sha256=roX2MLMpZDoFNoaluB9AnbrutaiqVzVyFrbHlUSVdVk,2246
+htmlship_server/routers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+htmlship_server/routers/meta.py,sha256=axzAEOLxsD5gpCxrrXBDEUS6HEj2rGSdpT60F_9e_Q8,332
+htmlship_server/routers/pastes.py,sha256=bLHWCc4C3do0NVNpRc96BpZGvQTuCjlmGoMYy4hn5YQ,7207
+htmlship_server/routers/view.py,sha256=ZSDTK_qu59JVLhmjnA_LMCzlxTdeYtAn2gr8K5lEFBg,5582
+htmlship_server/schemas/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+htmlship_server/schemas/pastes.py,sha256=4rqa31YzW7ezSWKme59Sq8GbyAnrqC2dRJo4PSVrkAs,1258
+htmlship-0.1.0.dist-info/METADATA,sha256=PC0ju57I3jE3InMEhWnEIqgfVdJR_Znz8GHnGkloXTU,9664
+htmlship-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+htmlship-0.1.0.dist-info/entry_points.txt,sha256=zsk7_AdOG5WKc_UCBw_BmBBEGC0ynruYWWjk_UlEmd0,87
+htmlship-0.1.0.dist-info/RECORD,,

htmlship-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

htmlship-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+htmlship = htmlship.cli:main
+htmlship-mcp = htmlship_mcp.server:main

htmlship_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

htmlship_mcp/server.py

@@ -0,0 +1,123 @@
+"""HTMLShip MCP server.
+
+Exposes three tools — publish_html, fetch_html, update_html — that wrap the
+public Python library. All HTTP traffic goes through the library and the
+real API; this server adds no business logic of its own.
+
+Configure the API endpoint via the HTMLSHIP_API_URL environment variable.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+import htmlship
+from htmlship.exceptions import AuthError, HTMLShipError, NotFoundError
+
+mcp = FastMCP("htmlship")
+
+
+def _client() -> htmlship.HTMLShipClient:
+    base_url = os.getenv("HTMLSHIP_API_URL")
+    return htmlship.HTMLShipClient(base_url=base_url)
+
+
+@mcp.tool()
+def publish_html(
+    html: str,
+    title: str | None = None,
+    expires_in_seconds: int | None = None,
+) -> dict[str, Any]:
+    """Publish an HTML document and get a public URL.
+
+    Args:
+        html: The HTML body to publish. May include inline CSS but scripts will
+            be blocked by Content Security Policy at view time.
+        title: Optional human-readable title.
+        expires_in_seconds: Optional TTL. If omitted, the paste is permanent
+            (subject to the server's default policy).
+
+    Returns:
+        A dict with keys: url, slug, owner_key, expires_at.
+        IMPORTANT: owner_key is the only credential to update or delete the
+        paste later. Save it.
+    """
+    with _client() as c:
+        try:
+            paste = c.publish(html, title=title, expires_in=expires_in_seconds)
+        except HTMLShipError as exc:
+            raise RuntimeError(f"htmlship publish failed: {exc}") from exc
+    return {
+        "url": paste.url,
+        "slug": paste.slug,
+        "owner_key": paste.owner_key,
+        "expires_at": paste.expires_at.isoformat() if paste.expires_at else None,
+    }
+
+
+@mcp.tool()
+def fetch_html(slug: str) -> dict[str, Any]:
+    """Fetch a paste's metadata.
+
+    NOTE: this returns metadata only. To view the rendered HTML, open the
+    `url` in a browser — the content is served from a sandboxed subdomain.
+
+    Args:
+        slug: The paste's short identifier.
+    """
+    with _client() as c:
+        try:
+            paste = c.get(slug)
+        except NotFoundError as exc:
+            raise RuntimeError(f"paste '{slug}' not found") from exc
+        except HTMLShipError as exc:
+            raise RuntimeError(f"htmlship fetch failed: {exc}") from exc
+    return {
+        "slug": paste.slug,
+        "url": paste.url,
+        "title": paste.title,
+        "view_count": paste.view_count,
+        "size_bytes": paste.size_bytes,
+        "has_password": paste.has_password,
+        "parent_slug": paste.parent_slug,
+        "expires_at": paste.expires_at.isoformat() if paste.expires_at else None,
+        "created_at": paste.created_at.isoformat() if paste.created_at else None,
+        "updated_at": paste.updated_at.isoformat() if paste.updated_at else None,
+    }
+
+
+@mcp.tool()
+def update_html(slug: str, html: str, owner_key: str, title: str | None = None) -> dict[str, Any]:
+    """Replace the HTML for an existing paste. Requires the original owner_key.
+
+    Args:
+        slug: The paste's short identifier.
+        html: The new HTML body.
+        owner_key: The owner key returned at publish time.
+        title: Optional new title.
+    """
+    with _client() as c:
+        try:
+            paste = c.update(slug, html, owner_key=owner_key, title=title)
+        except AuthError as exc:
+            raise RuntimeError(f"invalid owner_key for '{slug}'") from exc
+        except NotFoundError as exc:
+            raise RuntimeError(f"paste '{slug}' not found") from exc
+        except HTMLShipError as exc:
+            raise RuntimeError(f"htmlship update failed: {exc}") from exc
+    return {
+        "url": paste.url,
+        "slug": paste.slug,
+        "updated_at": paste.updated_at.isoformat() if paste.updated_at else None,
+    }
+
+
+def main() -> None:
+    """Entry point for the `htmlship-mcp` console script (stdio transport)."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

htmlship_server/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

htmlship_server/config.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        case_sensitive=False,
+    )
+
+    environment: str = "development"
+    log_level: str = "info"
+
+    database_url: str = Field(
+        default="postgresql+asyncpg://htmlship:htmlship@localhost:5433/htmlship"
+    )
+
+    public_base_domain: str = "htmlship.com"
+    api_base_url: str = "https://api.htmlship.com"
+    view_base_url: str = "https://view.htmlship.com"
+    landing_base_url: str = "https://htmlship.com"
+
+    spaces_bucket: str = ""
+    spaces_region: str = "nyc3"
+    spaces_endpoint_url: str = "https://nyc3.digitaloceanspaces.com"
+    spaces_access_key: str = ""
+    spaces_secret_key: str = ""
+
+    secret_key: str = "dev-secret-do-not-use-in-prod"
+
+    max_payload_bytes: int = 10 * 1024 * 1024
+    default_expires_in_seconds: int | None = None
+
+    @field_validator("default_expires_in_seconds", mode="before")
+    @classmethod
+    def _empty_to_none(cls, v):
+        if v == "" or v is None:
+            return None
+        return v
+
+    @property
+    def use_local_blob_store(self) -> bool:
+        return not self.spaces_bucket
+
+    @property
+    def view_host(self) -> str:
+        return f"view.{self.public_base_domain}"
+
+    @property
+    def api_host(self) -> str:
+        return f"api.{self.public_base_domain}"
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

htmlship_server/database.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+
+from sqlalchemy.ext.asyncio import (
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+
+from .config import get_settings
+
+_settings = get_settings()
+
+
+def _build_engine(url: str):
+    kwargs: dict = {"echo": False}
+    if "sqlite" not in url:
+        kwargs.update(pool_size=20, max_overflow=10, pool_pre_ping=True)
+    return create_async_engine(url, **kwargs)
+
+
+engine = _build_engine(_settings.database_url)
+
+SessionLocal = async_sessionmaker(
+    engine,
+    expire_on_commit=False,
+    class_=AsyncSession,
+)
+
+
+async def get_session() -> AsyncIterator[AsyncSession]:
+    async with SessionLocal() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise

htmlship_server/db_models/__init__.py

@@ -0,0 +1,3 @@
+from .paste import Base, Paste
+
+__all__ = ["Base", "Paste"]

htmlship_server/db_models/paste.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import BigInteger, CheckConstraint, DateTime, Index, Integer, String, func
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Paste(Base):
+    __tablename__ = "pastes"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        default=uuid.uuid4,
+        server_default=func.gen_random_uuid(),
+    )
+    slug: Mapped[str] = mapped_column(String(12), unique=True, nullable=False)
+    blob_key: Mapped[str] = mapped_column(String(255), nullable=False)
+    title: Mapped[str | None] = mapped_column(nullable=True)
+    owner_key_hash: Mapped[str] = mapped_column(String(128), nullable=False)
+    password_hash: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    sandbox_mode: Mapped[str] = mapped_column(
+        String(20), nullable=False, default="strict", server_default="strict"
+    )
+    expires_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    view_count: Mapped[int] = mapped_column(
+        BigInteger, nullable=False, default=0, server_default="0"
+    )
+    size_bytes: Mapped[int] = mapped_column(Integer, nullable=False)
+    parent_slug: Mapped[str | None] = mapped_column(String(12), nullable=True)
+    deleted_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+    __table_args__ = (
+        CheckConstraint("sandbox_mode IN ('strict', 'relaxed')", name="ck_sandbox_mode"),
+        CheckConstraint("size_bytes <= 10485760", name="ck_size_bytes"),
+        Index("idx_pastes_slug", "slug"),
+        Index("idx_pastes_expires_at", "expires_at"),
+        Index("idx_pastes_parent_slug", "parent_slug"),
+        Index("idx_pastes_created_at", "created_at"),
+    )

htmlship_server/exceptions.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+class StorageError(Exception):
+    """Raised when the blob store fails."""
+
+
+class PasteNotFoundError(Exception):
+    pass