stapel-video 0.1.0__tar.gz

stapel_video-0.1.0/LICENSE

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

stapel_video-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: stapel-video
+Version: 0.1.0
+Summary: Video calls (rooms, lobby admission, recording-egress seam) for the Stapel framework
+License: MIT
+Project-URL: Homepage, https://github.com/usestapel/stapel-video
+Project-URL: Repository, https://github.com/usestapel/stapel-video
+Project-URL: Documentation, https://github.com/usestapel/stapel-video#readme
+Project-URL: Changelog, https://github.com/usestapel/stapel-video/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/usestapel/stapel-video/issues
+Keywords: django,stapel,video,livekit,webrtc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<0.11,>=0.10
+Provides-Extra: livekit
+Requires-Dist: livekit-api<1,>=0.7; extra == "livekit"
+Requires-Dist: requests<3,>=2.28; extra == "livekit"
+Provides-Extra: channels
+Requires-Dist: stapel-core[channels]; extra == "channels"
+Provides-Extra: all
+Requires-Dist: livekit-api<1,>=0.7; extra == "all"
+Requires-Dist: requests<3,>=2.28; extra == "all"
+Requires-Dist: stapel-core[channels]; extra == "all"
+Dynamic: license-file
+
+# stapel-video
+
+Video calls for the [Stapel](https://github.com/usestapel) framework — a thin,
+provider-agnostic library over a real-time video backend (LiveKit by default).
+
+- **Rooms** with human-shareable join codes (`abc-defg-hij`).
+- **Admission model** — `public` (anyone with the code joins), `scope_trusted`
+  (members of the room's scope join instantly, others wait), `restricted`
+  (everyone but the host waits in a lobby).
+- **Realtime lobby** over WebSockets (Channels) — `waiting` / `admitted` /
+  `denied`, authenticated by the same Stapel JWT stack HTTP uses.
+- **Host controls** — admit / deny waiting guests.
+- **Provider seam** — one `VideoProvider` ABC (mint join token, create room,
+  start/stop recording egress, verify webhook). Swap vendors without forking.
+- **Recording** is a *seam*, not a pipeline: `start`/`stop_egress` proxy the
+  provider and a `video.egress_ended` comm event carries the storage key to
+  [stapel-recordings](https://github.com/usestapel/stapel-recordings) — by
+  event, never by import.
+
+Alpha (`0.1.0`). See [MODULE.md](MODULE.md) for the agent-facing map of seams.
+
+## Install
+
+```bash
+pip install stapel-video            # core library
+pip install 'stapel-video[livekit]' # + the default LiveKit backend
+pip install 'stapel-video[channels]'# + the realtime lobby (WebSockets)
+```
+
+## Mount
+
+```python
+# urls.py
+path("video/", include("stapel_video.urls"))
+
+# asgi.py (realtime lobby)
+from channels.routing import ProtocolTypeRouter, URLRouter
+from stapel_core.django.jwt.channels import JWTAuthMiddlewareStack
+from stapel_video.routing import websocket_urlpatterns
+
+application = ProtocolTypeRouter({
+    "http": django_asgi_app,
+    "websocket": JWTAuthMiddlewareStack(URLRouter(websocket_urlpatterns)),
+})
+```
+
+## API
+
+| Method | Path | What |
+|---|---|---|
+| POST | `/video/api/rooms` | Create a room (creator auto-admitted host, with a token) |
+| GET | `/video/api/rooms/{join_code}` | Room info |
+| POST | `/video/api/rooms/{join_code}/join` | Join → admitted / waiting / denied |
+| GET | `/video/api/rooms/{join_code}/participants` | Participants (anchor-paginated) |
+| POST | `/video/api/rooms/{join_code}/lobby/admit` | Admit a waiting guest (host-only) |
+| POST | `/video/api/rooms/{join_code}/lobby/deny` | Deny a waiting guest (host-only) |
+| POST | `/video/api/webhook` | Provider webhook ingress (signed, unauthenticated) |
+
+## Configuration (`STAPEL_VIDEO`)
+
+| Key | Default | What |
+|---|---|---|
+| `VIDEO_PROVIDER` | `…livekit.LiveKitProvider` | Video backend (dotted path) |
+| `SCOPE_PROVIDER` | `…scope.DefaultScopeProvider` | scope_key resolution + membership |
+| `DEFAULT_ACCESS_LEVEL` | `restricted` | Access level for a room created without one |
+| `DEFAULT_ADMIT_REQUIRED` | `True` | Whether new rooms start with the lobby on |
+| `LIVEKIT_URL` / `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET` | `""` | Default-provider credentials |
+
+`VIDEO_PROVIDER`, `DEFAULT_ACCESS_LEVEL` and `DEFAULT_ADMIT_REQUIRED` are the
+three CTO-facing config axes surfaced in `docs/capabilities.json`.

stapel_video-0.1.0/README.md

@@ -0,0 +1,70 @@
+# stapel-video
+
+Video calls for the [Stapel](https://github.com/usestapel) framework — a thin,
+provider-agnostic library over a real-time video backend (LiveKit by default).
+
+- **Rooms** with human-shareable join codes (`abc-defg-hij`).
+- **Admission model** — `public` (anyone with the code joins), `scope_trusted`
+  (members of the room's scope join instantly, others wait), `restricted`
+  (everyone but the host waits in a lobby).
+- **Realtime lobby** over WebSockets (Channels) — `waiting` / `admitted` /
+  `denied`, authenticated by the same Stapel JWT stack HTTP uses.
+- **Host controls** — admit / deny waiting guests.
+- **Provider seam** — one `VideoProvider` ABC (mint join token, create room,
+  start/stop recording egress, verify webhook). Swap vendors without forking.
+- **Recording** is a *seam*, not a pipeline: `start`/`stop_egress` proxy the
+  provider and a `video.egress_ended` comm event carries the storage key to
+  [stapel-recordings](https://github.com/usestapel/stapel-recordings) — by
+  event, never by import.
+
+Alpha (`0.1.0`). See [MODULE.md](MODULE.md) for the agent-facing map of seams.
+
+## Install
+
+```bash
+pip install stapel-video            # core library
+pip install 'stapel-video[livekit]' # + the default LiveKit backend
+pip install 'stapel-video[channels]'# + the realtime lobby (WebSockets)
+```
+
+## Mount
+
+```python
+# urls.py
+path("video/", include("stapel_video.urls"))
+
+# asgi.py (realtime lobby)
+from channels.routing import ProtocolTypeRouter, URLRouter
+from stapel_core.django.jwt.channels import JWTAuthMiddlewareStack
+from stapel_video.routing import websocket_urlpatterns
+
+application = ProtocolTypeRouter({
+    "http": django_asgi_app,
+    "websocket": JWTAuthMiddlewareStack(URLRouter(websocket_urlpatterns)),
+})
+```
+
+## API
+
+| Method | Path | What |
+|---|---|---|
+| POST | `/video/api/rooms` | Create a room (creator auto-admitted host, with a token) |
+| GET | `/video/api/rooms/{join_code}` | Room info |
+| POST | `/video/api/rooms/{join_code}/join` | Join → admitted / waiting / denied |
+| GET | `/video/api/rooms/{join_code}/participants` | Participants (anchor-paginated) |
+| POST | `/video/api/rooms/{join_code}/lobby/admit` | Admit a waiting guest (host-only) |
+| POST | `/video/api/rooms/{join_code}/lobby/deny` | Deny a waiting guest (host-only) |
+| POST | `/video/api/webhook` | Provider webhook ingress (signed, unauthenticated) |
+
+## Configuration (`STAPEL_VIDEO`)
+
+| Key | Default | What |
+|---|---|---|
+| `VIDEO_PROVIDER` | `…livekit.LiveKitProvider` | Video backend (dotted path) |
+| `SCOPE_PROVIDER` | `…scope.DefaultScopeProvider` | scope_key resolution + membership |
+| `DEFAULT_ACCESS_LEVEL` | `restricted` | Access level for a room created without one |
+| `DEFAULT_ADMIT_REQUIRED` | `True` | Whether new rooms start with the lobby on |
+| `LIVEKIT_URL` / `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET` | `""` | Default-provider credentials |
+
+`VIDEO_PROVIDER`, `DEFAULT_ACCESS_LEVEL` and `DEFAULT_ADMIT_REQUIRED` are the
+three CTO-facing config axes surfaced in `docs/capabilities.json`.

stapel_video-0.1.0/__init__.py

@@ -0,0 +1,12 @@
+"""stapel-video — video calls for the Stapel framework.
+
+A thin, provider-agnostic library over a real-time video backend (LiveKit by
+default): rooms with join codes, an access-level admission model
+(public / scope-trusted / restricted lobby), a realtime waiting-room over
+Channels, and a recording-egress *seam* (start/stop + a ``video.egress_ended``
+comm emit) that integrates with stapel-recordings by event, never by import.
+"""
+
+default_app_config = "stapel_video.apps.VideoConfig"
+
+__all__ = ["default_app_config"]

stapel_video-0.1.0/_capabilities.py

@@ -0,0 +1,38 @@
+"""stapel-video capabilities.json emitter — thin shim over stapel_tools.capabilities."""
+from pathlib import Path
+
+from stapel_tools.capabilities import axis_group_rules, run_capabilities_cli
+
+#: The three CTO-facing config axes (capability-config.md §16). Every OTHER
+#: DEFAULTS key is an extension seam (SCOPE_PROVIDER dotted path) or a tuning
+#: knob (LiveKit credentials, token TTL, egress store).
+_AXES = {"VIDEO_PROVIDER", "DEFAULT_ACCESS_LEVEL", "DEFAULT_ADMIT_REQUIRED"}
+
+
+def main(argv=None):
+    from stapel_video._codegen import _configure
+
+    _configure()
+    from stapel_video.conf import DEFAULTS
+    from stapel_video.urls import GATE_REGISTRY
+
+    return run_capabilities_cli(
+        argv,
+        repo=Path(__file__).resolve().parent,
+        canonical_prefix="/video",
+        defaults=DEFAULTS,
+        registry=GATE_REGISTRY,
+        is_axis=lambda k: k in _AXES,
+        axis_group=axis_group_rules(
+            exact={
+                "VIDEO_PROVIDER": "video.provider",
+                "DEFAULT_ACCESS_LEVEL": "video.access",
+                "DEFAULT_ADMIT_REQUIRED": "video.admission",
+            }
+        ),
+        prog="stapel-video-capabilities",
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stapel_video-0.1.0/_codegen.py

@@ -0,0 +1,116 @@
+"""stapel-video contract-emission harness (contract-pipeline.md §2-3).
+
+Emits the module's own contract triad into ``docs/`` from a single-module
+``{video + core}`` Django instance mounted at the canonical ``video/api/``
+prefix:
+
+  docs/schema.json   drf-spectacular OpenAPI, this module only, canonical prefix
+  docs/flows.json    generate_flow_docs machine artifact ([] — no @flow_step here)
+  docs/errors.json   generate_error_keys registry
+
+Copied from stapel-calendar's reference implementation; the *mechanism* is
+stapel_tools.codegen (unchanged, shared), this file is the thin per-module
+*config* that wires the module's settings + canonical mount into it.
+
+Usage:
+    python -m stapel_video._codegen --out docs        # `make contract`
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+
+def _configure() -> None:
+    """Configure + boot the single-module Django instance for emission."""
+    repo_root = os.path.dirname(os.path.abspath(__file__))
+    sys.path[:] = [p for p in sys.path if os.path.abspath(p or os.getcwd()) != repo_root]
+
+    from django.conf import settings
+
+    if not settings.configured:
+        from stapel_video._codegen_settings import settings_kwargs
+
+        settings.configure(
+            **settings_kwargs(root_urlconf="stapel_video.codegen_urls", contract=True)
+        )
+
+    import django
+
+    django.setup()
+
+    from drf_spectacular.settings import spectacular_settings
+
+    from stapel_video._codegen_settings import CODEGEN_SCHEMA_PATH_PREFIX
+
+    spectacular_settings.SCHEMA_PATH_PREFIX = CODEGEN_SCHEMA_PATH_PREFIX
+
+    # A real multi-module host registers drf-spectacular's JWT cookie-auth
+    # extension as a side effect of wiring its dev-only Swagger URLs — a global
+    # registration, not tied to any one module's urls.py. video mounts alone,
+    # so without registering it explicitly its protected endpoints would emit
+    # without their `security: [{"JWTCookieAuth": []}]` entry (the webhook is
+    # deliberately unauthenticated and carries none). Applied per the calendar
+    # precedent.
+    from stapel_core.django.openapi.swagger import _register_jwt_auth_extension
+
+    _register_jwt_auth_extension()
+
+
+def _require_python_312() -> None:
+    """Abort emission if not running the pinned 3.12 interpreter.
+
+    drf-spectacular's rendering of component descriptions (``Optional[X]`` vs
+    ``X | None``) depends on the Python minor version — contracts emitted on
+    anything other than 3.12 (the CI/monolith pin) produce false diffs against
+    the committed docs/*.json.
+    """
+    if sys.version_info[:2] != (3, 12):
+        got = f"{sys.version_info.major}.{sys.version_info.minor}"
+        raise SystemExit(
+            f"stapel-video contract emission ABORTED: running Python {got}, but "
+            "contracts must be emitted on Python 3.12 (the CI/monolith pin). "
+            "drf-spectacular renders component descriptions (Optional[X] vs "
+            "X | None) differently across Python minor versions, so emitting on "
+            "any other minor produces false diffs against the committed "
+            "docs/*.json. Re-run under a 3.12 interpreter."
+        )
+
+
+def main(argv: list[str] | None = None) -> int:
+    _require_python_312()
+
+    parser = argparse.ArgumentParser(
+        prog="stapel-video-contract",
+        description="Emit this module's contract triad (schema.json + flows.json "
+        "+ errors.json) into --out, canonical /video/api/ prefix.",
+    )
+    parser.add_argument(
+        "--out",
+        default="docs",
+        help="Output directory for the triad (default: docs).",
+    )
+    args = parser.parse_args(argv)
+
+    _configure()
+
+    from stapel_tools.codegen import emit_errors, emit_flows, emit_schema
+
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    paths = emit_schema(out / "schema.json")
+    flows = emit_flows(out / "flows.json")
+    errors = emit_errors(out / "errors.json")
+
+    print(
+        f"stapel-video contract: {paths} paths, {flows} flows, {errors} error keys "
+        f"→ {out}/",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stapel_video-0.1.0/_codegen_settings.py

@@ -0,0 +1,114 @@
+"""Single-module Django settings for stapel-video's harnesses.
+
+Single source of truth for the ``settings.configure(...)`` block shared by:
+
+  - the pytest suite (``conftest.py``) — mounts video on its *bare* test
+    urlconf (``stapel_video.tests.urls`` -> ``video/`` -> the module's own
+    ``api/rooms`` etc.); and
+  - the contract-emission harness (``_codegen.py`` / ``make contract``) —
+    mounts video on its *canonical* public API prefix
+    (``stapel_video.codegen_urls`` -> ``video/`` -> same ``api/*`` paths the
+    module's own ``urls.py`` declares) and enables drf-spectacular, so the
+    emitted ``schema.json`` / ``flows.json`` paths are byte-identical to what a
+    host mounting this module would serve (contract-pipeline.md §2).
+
+Keeping one copy here means the harness and the tests can never drift in their
+``INSTALLED_APPS`` / mock config. Copied from stapel-calendar's etalon and
+tailored to this module (no gdpr sibling; adds the in-process comm bus + schema
+validation the suite needs).
+"""
+from __future__ import annotations
+
+
+def settings_kwargs(
+    *,
+    root_urlconf: str = "stapel_video.tests.urls",
+    contract: bool = False,
+) -> dict:
+    """Return the ``settings.configure(**kwargs)`` for a single-module video
+    instance. ``contract=True`` swaps in the production ``REST_FRAMEWORK`` (the
+    canonical stapel-core config, inlined) so the emitted schema carries the
+    real permission/renderer/schema classes — kept in lockstep by
+    test_contract.py's identity gate."""
+    if contract:
+        rest_framework = {
+            "DEFAULT_AUTHENTICATION_CLASSES": [
+                "stapel_core.django.jwt.authentication.JWTCookieAuthentication",
+            ],
+            "DEFAULT_PERMISSION_CLASSES": [
+                "stapel_core.django.api.permissions.IsServiceRequest",
+                "stapel_core.django.api.permissions.IsSuperUser",
+            ],
+            "DEFAULT_RENDERER_CLASSES": [
+                "rest_framework.renderers.JSONRenderer",
+                "rest_framework.renderers.BrowsableAPIRenderer",
+            ],
+            "DEFAULT_SCHEMA_CLASS": "stapel_core.django.openapi.schemas.PermissionAwareAutoSchema",
+            "EXCEPTION_HANDLER": "stapel_core.django.api.errors.stapel_exception_handler",
+        }
+    else:
+        rest_framework = None
+
+    kwargs = dict(
+        SECRET_KEY="test-secret-key-not-for-production",
+        INSTALLED_APPS=[
+            "django.contrib.contenttypes",
+            "django.contrib.auth",
+            "django.contrib.sessions",
+            "django.contrib.admin",
+            "django.contrib.messages",
+            # CommonDjangoConfig ships the stapel_core management commands
+            # (generate_error_keys, used by the errors.json drift gate).
+            "stapel_core.django.apps.CommonDjangoConfig",
+            "stapel_core.django.users",
+            "rest_framework",
+            "drf_spectacular",
+            "stapel_video",
+        ],
+        AUTH_USER_MODEL="users.User",
+        DATABASES={
+            "default": {
+                "ENGINE": "django.db.backends.sqlite3",
+                "NAME": ":memory:",
+            }
+        },
+        DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
+        USE_TZ=True,
+        ROOT_URLCONF=root_urlconf,
+        CACHES={
+            "default": {
+                "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+            }
+        },
+        # Synchronous in-process comm with schema validation ON, so the
+        # committed contracts in schemas/ are enforced by the tests.
+        STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
+        STAPEL_COMM={
+            "OUTBOX_ENABLED": False,
+            "ACTION_TRANSPORT": "inprocess",
+            "VALIDATE_SCHEMAS": True,
+        },
+        # In-memory channel layer for the realtime lobby consumer tests.
+        CHANNEL_LAYERS={
+            "default": {"BACKEND": "channels.layers.InMemoryChannelLayer"}
+        },
+        # Test video provider (no network) — overridden per-test where needed.
+        STAPEL_VIDEO={
+            "VIDEO_PROVIDER": "stapel_video.tests.fakeprovider.FakeProvider",
+        },
+        # Skip migrations — create tables directly from models.
+        MIGRATION_MODULES={
+            "users": None,
+            "video": None,
+        },
+    )
+    if rest_framework is not None:
+        kwargs["REST_FRAMEWORK"] = rest_framework
+    return kwargs
+
+
+# The multi-module common path prefix drf-spectacular auto-detects in a
+# multi-module aggregate. Forced on the drf-spectacular settings singleton by
+# the harness so a single-module instance derives the same style of
+# operationIds. Uniform across all pair-backends.
+CODEGEN_SCHEMA_PATH_PREFIX = "/"

stapel_video-0.1.0/actions.py

@@ -0,0 +1,25 @@
+"""Action subscriptions of stapel-video.
+
+Handlers must be idempotent: delivery is at-least-once (outbox retries, broker
+redelivery). Consumes contracts live in ``schemas/consumes/``.
+"""
+import logging
+
+from stapel_core.comm import on_action
+
+logger = logging.getLogger(__name__)
+
+
+@on_action("user.deleted")
+def handle_user_deleted(event):
+    """Erase this module's PII when an account deletion is executed: rooms the
+    user created (and their participants) and the user's participations in
+    other rooms."""
+    from .gdpr import VideoGDPRProvider
+
+    user_id = event.payload.get("user_id")
+    if not user_id:
+        logger.error("user.deleted event without user_id: %s", event.event_id)
+        return
+    VideoGDPRProvider().delete(user_id)
+    logger.info("video data erased for deleted user %s", user_id)

stapel_video-0.1.0/admin.py

@@ -0,0 +1,25 @@
+"""Django admin for stapel-video.
+
+Both models are ``business`` (visible, staff-manageable) by the admin-suite
+default (admin-suite AS-5); neither is ops-machinery nor a secret carrier, so
+both stay undecorated. ``provider_room_ref`` is an opaque provider room name,
+not a credential.
+"""
+from django.contrib import admin
+
+from .models import Room, RoomParticipant
+
+
+@admin.register(Room)
+class RoomAdmin(admin.ModelAdmin):
+    list_display = ("join_code", "access_level", "admit_required", "created_by", "created_at")
+    list_filter = ("access_level", "admit_required")
+    search_fields = ("join_code", "scope_key", "provider_room_ref")
+    raw_id_fields = ("created_by",)
+
+
+@admin.register(RoomParticipant)
+class RoomParticipantAdmin(admin.ModelAdmin):
+    list_display = ("room", "user", "status", "role", "joined_at")
+    list_filter = ("status", "role")
+    raw_id_fields = ("room", "user")

stapel_video-0.1.0/apps.py

@@ -0,0 +1,23 @@
+from django.apps import AppConfig
+
+
+class VideoConfig(AppConfig):
+    name = "stapel_video"
+    label = "video"
+    verbose_name = "Video calls"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        # Import-time side effects: comm actions, system checks, error-key
+        # registration. Keep each in its own module.
+        from . import actions  # noqa: F401
+        from . import checks  # noqa: F401
+        from . import errors  # noqa: F401
+
+        # GDPR: register the per-app data handler (monolith in-process mode).
+        from stapel_core.gdpr import gdpr_registry
+
+        from .gdpr import VideoGDPRProvider
+
+        if not any(p.section == "video" for p in gdpr_registry.providers):
+            gdpr_registry.register(VideoGDPRProvider())

stapel_video-0.1.0/checks.py

@@ -0,0 +1,79 @@
+"""Django system checks for stapel-video configuration.
+
+Policy (docs/library-standard.md §3.7): E-level for configuration the service
+cannot run with; W-level for entries that only degrade lazily.
+
+- VIDEO_PROVIDER unimportable / not a VideoProvider -> E (no room can mint a
+  join token — the module cannot serve calls).
+- SCOPE_PROVIDER unimportable / not a ScopeProvider -> E (create & the
+  scope_trusted join decision cannot resolve scope/membership).
+- DEFAULT_ACCESS_LEVEL not a valid access level -> E (every default-level room
+  create would produce an unjoinable room).
+"""
+from django.core import checks
+
+
+@checks.register(checks.Tags.compatibility)
+def check_video_provider(app_configs, **kwargs):
+    from .conf import video_settings
+    from .providers import VideoProvider
+
+    try:
+        provider = video_settings.VIDEO_PROVIDER
+    except Exception as exc:
+        return [
+            checks.Error(
+                f"STAPEL_VIDEO['VIDEO_PROVIDER'] could not be imported: {exc}",
+                id="stapel_video.E001",
+            )
+        ]
+    target = provider if isinstance(provider, type) else type(provider)
+    if not issubclass(target, VideoProvider):
+        return [
+            checks.Error(
+                "STAPEL_VIDEO['VIDEO_PROVIDER'] must be a VideoProvider subclass",
+                id="stapel_video.E002",
+            )
+        ]
+    return []
+
+
+@checks.register(checks.Tags.compatibility)
+def check_scope_provider(app_configs, **kwargs):
+    from .conf import video_settings
+    from .scope import ScopeProvider
+
+    try:
+        provider = video_settings.SCOPE_PROVIDER
+    except Exception as exc:
+        return [
+            checks.Error(
+                f"STAPEL_VIDEO['SCOPE_PROVIDER'] could not be imported: {exc}",
+                id="stapel_video.E003",
+            )
+        ]
+    target = provider if isinstance(provider, type) else type(provider)
+    if not issubclass(target, ScopeProvider):
+        return [
+            checks.Error(
+                "STAPEL_VIDEO['SCOPE_PROVIDER'] must be a ScopeProvider subclass",
+                id="stapel_video.E004",
+            )
+        ]
+    return []
+
+
+@checks.register(checks.Tags.compatibility)
+def check_default_access_level(app_configs, **kwargs):
+    from .conf import video_settings
+    from .models import AccessLevel
+
+    if video_settings.DEFAULT_ACCESS_LEVEL not in AccessLevel.values:
+        return [
+            checks.Error(
+                "STAPEL_VIDEO['DEFAULT_ACCESS_LEVEL'] must be one of "
+                f"{list(AccessLevel.values)}.",
+                id="stapel_video.E005",
+            )
+        ]
+    return []

stapel_video-0.1.0/codegen_urls.py

@@ -0,0 +1,18 @@
+"""Canonical-prefix URLconf for contract emission (contract-pipeline.md §2).
+
+stapel-video's own ``urls.py`` already bakes ``api/`` into every path
+(``api/rooms``, ``api/webhook``, ...) and documents its expected host mount::
+
+    path("video/", include("stapel_video.urls"))
+
+That is the canonical public API prefix (``video/api/...``) — the same
+``<mod>/api/`` shape every other pair-backend uses. This harness urlconf
+reproduces exactly that documented mount, so drf-spectacular emits
+``/video/api/...`` paths. video is validated standalone (no monolith slice
+exists yet to diff against; contract-pipeline.md §9 fallback path applies).
+"""
+from django.urls import include, path
+
+urlpatterns = [
+    path("video/", include("stapel_video.urls")),
+]