cloud-dog-api-kit 0.13.0__py3-none-any.whl

cloud_dog_api_kit/schemas/pagination.py

@@ -0,0 +1,148 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Pagination models and dependency
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: PaginationParams dataclass and FastAPI dependency for extracting
+#   pagination, sort, and filter parameters from list requests.
+# Related requirements: FR4.3
+# Related architecture: CC1.10
+
+"""Pagination models and FastAPI dependency."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+from dataclasses import dataclass
+
+from fastapi import Query
+from pydantic import BaseModel
+
+
+@dataclass
+class PaginationParams:
+    """Pagination, sorting, and filtering parameters.
+
+    Attributes:
+        offset: The starting offset. Defaults to 0.
+        limit: The page size. Defaults to 50.
+        sort: The field to sort by, or None for default ordering.
+        sort_dir: Sort direction — ``asc`` or ``desc``. Defaults to ``asc``.
+
+    Related tests: UT1.13_PaginationModels, UT1.14_PaginationDependency
+    """
+
+    offset: int = 0
+    limit: int = 50
+    sort: str | None = None
+    sort_dir: str = "asc"
+
+
+def get_pagination(
+    offset: int = Query(default=0, ge=0, description="Starting offset"),
+    limit: int = Query(default=50, ge=1, le=1000, description="Page size"),
+    sort: str | None = Query(default=None, description="Sort field (e.g., created_at:desc)"),
+) -> PaginationParams:
+    """FastAPI dependency for extracting pagination + sort parameters.
+
+    Parses the ``sort`` parameter if it contains a colon-separated direction
+    (e.g., ``created_at:desc``).
+
+    Args:
+        offset: Starting offset (query param).
+        limit: Page size (query param).
+        sort: Sort specification (query param).
+
+    Returns:
+        A populated PaginationParams instance.
+
+    Related tests: UT1.14_PaginationDependency
+    """
+    sort_field = sort
+    sort_dir = "asc"
+    if sort and ":" in sort:
+        parts = sort.rsplit(":", 1)
+        sort_field = parts[0]
+        if parts[1].lower() in ("asc", "desc"):
+            sort_dir = parts[1].lower()
+
+    return PaginationParams(
+        offset=offset,
+        limit=limit,
+        sort=sort_field,
+        sort_dir=sort_dir,
+    )
+
+
+class PageInfo(BaseModel):
+    """Pagination metadata for list responses.
+
+    Related tests: UT1.13_PaginationModels
+    """
+
+    limit: int
+    offset: int
+    total: int | None = None
+    has_more: bool
+    cursor: str | None = None
+
+
+T = TypeVar("T")
+
+
+class PaginatedData(BaseModel, Generic[T]):
+    """Paginated list data within the success envelope.
+
+    Related tests: UT1.13_PaginationModels
+    """
+
+    items: list[T]
+    page: PageInfo
+
+
+def paginated_envelope(
+    items: list[Any],
+    limit: int,
+    offset: int,
+    total: int | None = None,
+    has_more: bool = False,
+    cursor: str | None = None,
+    request_id: str = "",
+    correlation_id: str | None = None,
+    version: str = "v1",
+) -> dict[str, Any]:
+    """Build a paginated success response envelope dictionary.
+
+    Related tests: UT1.13_PaginationModels
+    """
+    return {
+        "ok": True,
+        "data": {
+            "items": items,
+            "page": {
+                "limit": limit,
+                "offset": offset,
+                "total": total,
+                "has_more": has_more,
+                "cursor": cursor,
+            },
+        },
+        "meta": {
+            "request_id": request_id,
+            "correlation_id": correlation_id,
+            "version": version,
+        },
+    }

cloud_dog_api_kit/streaming/__init__.py

@@ -0,0 +1,28 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Streaming helpers (SSE, JSONL)
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Helpers for creating SSE and JSONL streaming endpoints.
+# Related requirements: FR8.1, FR8.2, FR8.3
+# Related architecture: CC1.14
+
+"""Streaming helpers for cloud_dog_api_kit."""
+
+from cloud_dog_api_kit.streaming.sse import create_sse_endpoint, SSEEvent
+from cloud_dog_api_kit.streaming.jsonl import create_jsonl_endpoint
+
+__all__ = ["create_sse_endpoint", "create_jsonl_endpoint", "SSEEvent"]

cloud_dog_api_kit/streaming/events.py

@@ -0,0 +1,47 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Streaming event models
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Standard SSE event model and serialisation.
+# Related requirements: FR8.2
+# Related architecture: SA1
+
+"""Streaming event models for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class SSEEvent:
+    """Standard server-sent event payload.
+
+    Related tests: UT1.22_SSEEventModel
+    """
+
+    type: str
+    data: Any = None
+    request_id: str = ""
+    job_id: str | None = None
+
+    def to_sse(self) -> str:
+        """Serialise to SSE wire format."""
+        payload = {"type": self.type, "data": self.data, "request_id": self.request_id, "job_id": self.job_id}
+        return f"event: {self.type}\ndata: {json.dumps(payload, ensure_ascii=False)}\n\n"

cloud_dog_api_kit/streaming/jsonl.py

@@ -0,0 +1,68 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — JSONL streaming helpers
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Line-delimited JSON streaming endpoint helpers.
+# Related requirements: FR8.1, FR8.3
+# Related architecture: CC1.14
+
+"""JSONL streaming helpers for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+import json
+from typing import AsyncGenerator
+
+from starlette.responses import StreamingResponse
+
+from cloud_dog_api_kit.correlation.context import get_request_id
+
+
+async def _jsonl_generator(data_generator: AsyncGenerator) -> AsyncGenerator[str, None]:
+    """Wrap an async generator to produce JSONL output.
+
+    Args:
+        data_generator: Async generator yielding dicts or serialisable objects.
+
+    Yields:
+        JSON Lines strings (one JSON object per line).
+    """
+    request_id = get_request_id()
+    async for item in data_generator:
+        if isinstance(item, dict):
+            item["request_id"] = request_id
+            yield json.dumps(item, default=str) + "\n"
+        else:
+            yield json.dumps({"data": item, "request_id": request_id}, default=str) + "\n"
+
+
+def create_jsonl_endpoint(data_generator: AsyncGenerator) -> StreamingResponse:
+    """Create a StreamingResponse for JSONL output.
+
+    Args:
+        data_generator: Async generator yielding data items.
+
+    Returns:
+        A StreamingResponse with ``application/x-ndjson`` content type.
+
+    Related tests: UT1.21_JSONLStreaming
+    """
+    return StreamingResponse(
+        content=_jsonl_generator(data_generator),
+        media_type="application/x-ndjson",
+        headers={"Cache-Control": "no-cache"},
+    )

cloud_dog_api_kit/streaming/sse.py

@@ -0,0 +1,102 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — SSE streaming helpers
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Server-Sent Events (SSE) streaming endpoint helpers with
+#   standard event types per PS-20.
+# Related requirements: FR8.1, FR8.2, FR8.3
+# Related architecture: CC1.14
+
+"""SSE streaming helpers for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+import json
+from typing import AsyncGenerator
+
+from starlette.responses import StreamingResponse
+
+from cloud_dog_api_kit.correlation.context import get_request_id
+from cloud_dog_api_kit.streaming.events import SSEEvent
+
+STANDARD_EVENT_TYPES = frozenset({"started", "delta", "progress", "tool_call", "completed", "error"})
+
+
+async def _sse_generator(
+    event_generator: AsyncGenerator,
+    event_type_field: str = "type",
+) -> AsyncGenerator[str, None]:
+    """Wrap an async generator to produce SSE-formatted output.
+
+    Args:
+        event_generator: Async generator yielding event dicts or SSEEvent objects.
+        event_type_field: The key in event dicts that specifies the event type.
+
+    Yields:
+        SSE-formatted strings.
+    """
+    request_id = get_request_id()
+    try:
+        async for event in event_generator:
+            if isinstance(event, SSEEvent):
+                if not event.request_id:
+                    event.request_id = request_id
+                yield event.to_sse()
+            elif isinstance(event, dict):
+                sse_event = SSEEvent(
+                    type=event.get(event_type_field, "delta"),
+                    data=event.get("data", event),
+                    request_id=request_id,
+                    job_id=event.get("job_id"),
+                )
+                yield sse_event.to_sse()
+            else:
+                yield f"event: delta\ndata: {json.dumps({'data': str(event), 'request_id': request_id})}\n\n"
+
+        # Send completion event
+        completion = SSEEvent(type="completed", request_id=request_id)
+        yield completion.to_sse()
+
+    except Exception as exc:
+        error_event = SSEEvent(
+            type="error",
+            data={"message": str(exc)},
+            request_id=request_id,
+        )
+        yield error_event.to_sse()
+
+
+def create_sse_endpoint(
+    event_generator: AsyncGenerator,
+    event_type_field: str = "type",
+) -> StreamingResponse:
+    """Create a StreamingResponse for SSE output.
+
+    Args:
+        event_generator: Async generator yielding events.
+        event_type_field: The key in event dicts for event type.
+
+    Returns:
+        A StreamingResponse with ``text/event-stream`` content type.
+
+    Related tests: UT1.20_SSEStreaming, ST1.9_StreamingEndToEnd
+    """
+    return StreamingResponse(
+        content=_sse_generator(event_generator, event_type_field),
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
+    )

cloud_dog_api_kit/testing/__init__.py

@@ -0,0 +1,46 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Test scaffolding (fixtures, conformance, flow templates)
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Reusable test fixtures, conformance validators, and baseline
+#   flow templates for verifying API compliance.
+# Related requirements: FR16.1, FR16.2, FR16.3
+# Related architecture: CC1.19
+
+"""Test scaffolding for cloud_dog_api_kit."""
+
+from cloud_dog_api_kit.testing.fixtures import create_test_client, create_auth_headers
+from cloud_dog_api_kit.testing.conformance import (
+    validate_error_envelope,
+    validate_success_envelope,
+    validate_pagination_response,
+    validate_correlation_id,
+)
+from cloud_dog_api_kit.testing.flows import AuthFlow, CRUDFlow, JobFlow, StreamingFlow
+
+__all__ = [
+    "create_test_client",
+    "create_auth_headers",
+    "validate_error_envelope",
+    "validate_success_envelope",
+    "validate_pagination_response",
+    "validate_correlation_id",
+    "AuthFlow",
+    "CRUDFlow",
+    "JobFlow",
+    "StreamingFlow",
+]

cloud_dog_api_kit/testing/conformance.py

@@ -0,0 +1,156 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Conformance test helpers
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Conformance validators for verifying API responses match
+#   the standard envelope schemas, pagination format, and correlation ID rules.
+# Related requirements: FR16.2
+# Related architecture: CC1.19
+
+"""Conformance test helpers for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def validate_success_envelope(response_json: dict[str, Any]) -> list[str]:
+    """Validate a response against the success envelope schema.
+
+    Args:
+        response_json: The parsed JSON response body.
+
+    Returns:
+        A list of validation error messages. Empty if valid.
+
+    Related tests: UT1.35_ConformanceValidators
+    """
+    errors: list[str] = []
+    if not isinstance(response_json, dict):
+        return ["Response is not a dict"]
+
+    if response_json.get("ok") is not True:
+        errors.append("Missing or false 'ok' field")
+
+    if "data" not in response_json:
+        errors.append("Missing 'data' field")
+
+    if "meta" not in response_json:
+        errors.append("Missing 'meta' field")
+    else:
+        meta = response_json["meta"]
+        if not isinstance(meta, dict):
+            errors.append("'meta' is not a dict")
+        else:
+            if "request_id" not in meta:
+                errors.append("Missing 'meta.request_id'")
+
+    return errors
+
+
+def validate_error_envelope(response_json: dict[str, Any]) -> list[str]:
+    """Validate a response against the error envelope schema.
+
+    Args:
+        response_json: The parsed JSON response body.
+
+    Returns:
+        A list of validation error messages. Empty if valid.
+
+    Related tests: UT1.35_ConformanceValidators
+    """
+    errors: list[str] = []
+    if not isinstance(response_json, dict):
+        return ["Response is not a dict"]
+
+    if response_json.get("ok") is not False:
+        errors.append("'ok' field should be false")
+
+    if "error" not in response_json:
+        errors.append("Missing 'error' field")
+    else:
+        error = response_json["error"]
+        if not isinstance(error, dict):
+            errors.append("'error' is not a dict")
+        else:
+            if "code" not in error:
+                errors.append("Missing 'error.code'")
+            if "message" not in error:
+                errors.append("Missing 'error.message'")
+            if "retryable" not in error:
+                errors.append("Missing 'error.retryable'")
+
+    if "meta" not in response_json:
+        errors.append("Missing 'meta' field")
+
+    return errors
+
+
+def validate_pagination_response(response_json: dict[str, Any]) -> list[str]:
+    """Validate a paginated list response.
+
+    Args:
+        response_json: The parsed JSON response body.
+
+    Returns:
+        A list of validation error messages. Empty if valid.
+
+    Related tests: UT1.35_ConformanceValidators
+    """
+    errors = validate_success_envelope(response_json)
+    if errors:
+        return errors
+
+    data = response_json.get("data", {})
+    if "items" not in data:
+        errors.append("Missing 'data.items'")
+    elif not isinstance(data["items"], list):
+        errors.append("'data.items' is not a list")
+
+    if "page" not in data:
+        errors.append("Missing 'data.page'")
+    else:
+        page = data["page"]
+        if not isinstance(page, dict):
+            errors.append("'data.page' is not a dict")
+        else:
+            for field in ("limit", "offset", "has_more"):
+                if field not in page:
+                    errors.append(f"Missing 'data.page.{field}'")
+
+    return errors
+
+
+def validate_correlation_id(response_headers: dict[str, str]) -> list[str]:
+    """Validate that correlation ID is present in response headers.
+
+    Args:
+        response_headers: The HTTP response headers.
+
+    Returns:
+        A list of validation error messages. Empty if valid.
+
+    Related tests: UT1.35_ConformanceValidators
+    """
+    errors: list[str] = []
+    # Check for X-Request-Id (case-insensitive)
+    header_keys_lower = {k.lower(): v for k, v in response_headers.items()}
+    if "x-request-id" not in header_keys_lower:
+        errors.append("Missing X-Request-Id response header")
+    elif not header_keys_lower["x-request-id"]:
+        errors.append("Empty X-Request-Id response header")
+    return errors

cloud_dog_api_kit/testing/fixtures.py

@@ -0,0 +1,90 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Reusable test fixtures
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Reusable test fixtures for API testing — configured TestClient
+#   with auth headers and database session protocol.
+# Related requirements: FR16.1
+# Related architecture: CC1.19
+
+"""Reusable test fixtures for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+
+from fastapi import FastAPI
+from httpx import ASGITransport, AsyncClient
+
+
+def create_test_client(
+    app: FastAPI,
+    base_url: str = "http://test",
+    api_key: str | None = None,
+    bearer_token: str | None = None,
+) -> AsyncClient:
+    """Create a configured async test client for a FastAPI application.
+
+    Args:
+        app: The FastAPI application.
+        base_url: Base URL for the test client.
+        api_key: Optional API key to include in all requests.
+        bearer_token: Optional Bearer token to include in all requests.
+
+    Returns:
+        A configured httpx.AsyncClient.
+
+    Related tests: UT1.34_TestFixtures
+    """
+    headers: dict[str, str] = {}
+    if api_key:
+        headers["X-API-Key"] = api_key
+    if bearer_token:
+        headers["Authorization"] = f"Bearer {bearer_token}"
+
+    transport = ASGITransport(app=app)
+    return AsyncClient(
+        transport=transport,
+        base_url=base_url,
+        headers=headers,
+    )
+
+
+def create_auth_headers(
+    api_key: str | None = None,
+    bearer_token: str | None = None,
+    app_id: str | None = None,
+) -> dict[str, str]:
+    """Create standard authentication headers.
+
+    Args:
+        api_key: API key value.
+        bearer_token: Bearer token value.
+        app_id: Application ID for service-to-service calls.
+
+    Returns:
+        A dictionary of HTTP headers.
+
+    Related tests: UT1.34_TestFixtures
+    """
+    headers: dict[str, str] = {}
+    if api_key:
+        headers["X-API-Key"] = api_key
+    if bearer_token:
+        headers["Authorization"] = f"Bearer {bearer_token}"
+    if app_id:
+        headers["X-App-Id"] = app_id
+    return headers