keble-data-infra-api 0.1.0__py3-none-any.whl

keble_data_infra_api/__init__.py

@@ -0,0 +1,2 @@
+"""Keble raw-data API composition root."""
+

keble_data_infra_api/api/__init__.py

@@ -0,0 +1,2 @@
+"""HTTP routing and error conversion owned by the raw API."""
+

keble_data_infra_api/api/error_handlers.py

@@ -0,0 +1,126 @@
+"""Central HTTP mappings for typed contract and provider errors."""
+
+from typing import cast
+
+import aiohttp
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from keble_data_infra_contract.errors import (
+    OperationNotSupportedError,
+    ProviderAuthenticationError,
+    ProviderNotFoundError,
+    ProviderRateLimitError,
+    ProviderRequestValidationError,
+    ProviderTimeoutError,
+    ProviderUnavailableError,
+)
+from keble_tiktok.commerce_provider import SourceNotConfiguredError
+from keble_tiktok.providers.echotik.errors import (
+    EchoTikAuthError,
+    EchoTikBusinessError,
+    EchoTikInvalidRequest,
+    EchoTikInvalidResponse,
+    EchoTikRateLimited,
+    EchoTikUnavailable,
+)
+from keble_tiktok.providers.fastmoss.errors import (
+    FastMossAuthError,
+    FastMossError,
+    FastMossInvalidResponse,
+    FastMossRateLimited,
+    FastMossUnavailable,
+)
+from keble_keepa import KeepaApiException
+
+from keble_data_infra_api.integrations.video_enrichment.service import (
+    VideoEnrichmentSourceError,
+)
+
+
+async def _unprocessable(_: Request, exc: Exception) -> JSONResponse:
+    """Map unsupported or invalid provider operations to HTTP 422."""
+
+    return JSONResponse(status_code=422, content={"detail": str(exc)})
+
+
+async def _not_found(_: Request, exc: Exception) -> JSONResponse:
+    """Map unknown provider identities to HTTP 404."""
+
+    return JSONResponse(status_code=404, content={"detail": str(exc)})
+
+
+async def _auth(_: Request, __: Exception) -> JSONResponse:
+    """Hide upstream credential material while reporting operator failure."""
+
+    return JSONResponse(
+        status_code=503,
+        content={"detail": "Upstream authentication failure. Check server credentials."},
+    )
+
+
+async def _rate_limited(_: Request, exc: Exception) -> JSONResponse:
+    """Preserve upstream throttling semantics for callers."""
+
+    return JSONResponse(status_code=429, content={"detail": str(exc)})
+
+
+async def _unavailable(_: Request, exc: Exception) -> JSONResponse:
+    """Map provider timeouts and unavailability to HTTP 503."""
+
+    return JSONResponse(status_code=503, content={"detail": str(exc)})
+
+
+async def _bad_gateway(_: Request, exc: Exception) -> JSONResponse:
+    """Map invalid or unsuccessful upstream payloads to HTTP 502."""
+
+    return JSONResponse(status_code=502, content={"detail": str(exc)})
+
+
+async def _video_source(_: Request, exc: Exception) -> JSONResponse:
+    """Preserve retryability when the authoritative enrichment read fails."""
+
+    source_error = cast(VideoEnrichmentSourceError, exc)
+    return JSONResponse(
+        status_code=503 if source_error.retryable else 502,
+        content={"detail": {"code": source_error.code}},
+    )
+
+
+def register_error_handlers(app: FastAPI) -> None:
+    """Register all expected exception mappings once on the sole raw app.
+
+    Side effects if changes:
+    - every generated provider route;
+    - Sentry grouping for expected versus unexpected failures.
+    """
+
+    for error_type in (
+        SourceNotConfiguredError,
+        EchoTikInvalidRequest,
+        OperationNotSupportedError,
+        ProviderRequestValidationError,
+    ):
+        app.add_exception_handler(error_type, _unprocessable)
+    app.add_exception_handler(ProviderNotFoundError, _not_found)
+    for error_type in (EchoTikAuthError, FastMossAuthError, ProviderAuthenticationError):
+        app.add_exception_handler(error_type, _auth)
+    for error_type in (EchoTikRateLimited, FastMossRateLimited, ProviderRateLimitError):
+        app.add_exception_handler(error_type, _rate_limited)
+    for error_type in (
+        EchoTikUnavailable,
+        FastMossUnavailable,
+        ProviderTimeoutError,
+        ProviderUnavailableError,
+        aiohttp.ClientError,
+    ):
+        app.add_exception_handler(error_type, _unavailable)
+    for error_type in (
+        EchoTikBusinessError,
+        EchoTikInvalidResponse,
+        FastMossError,
+        FastMossInvalidResponse,
+        KeepaApiException,
+    ):
+        app.add_exception_handler(error_type, _bad_gateway)
+    app.add_exception_handler(VideoEnrichmentSourceError, _video_source)

keble_data_infra_api/api/router.py

@@ -0,0 +1,177 @@
+"""Universal route construction from provider-owned operation manifests."""
+
+from collections.abc import Awaitable, Callable
+from typing import cast
+
+from fastapi import APIRouter
+import sentry_sdk
+
+from keble_data_infra_contract.manifests import ServiceOperation
+from keble_data_infra_contract.models.base import ContractModel
+from keble_data_infra_contract.models.creator import CommerceCreator
+from keble_data_infra_contract.models.creator_link import CreatorProductLink
+from keble_data_infra_contract.models.identity import Channel, ProviderId
+from keble_data_infra_contract.models.listing import CommerceListing
+from keble_data_infra_contract.models.product import CommerceProduct
+from keble_data_infra_contract.models.store import CommerceStore
+from keble_data_infra_contract.models.video import ShortVideo
+from keble_data_infra_contract.operations import CommerceAction, CommerceResource
+from keble_data_infra_contract.schemas.query import (
+    CreatorProductsQuery,
+    CreatorRankingQuery,
+    ProductCreatorsQuery,
+    ProductLookupQuery,
+    ProductRankingQuery,
+    ProductSearchQuery,
+    ProductVideosQuery,
+    SellerRankingQuery,
+)
+from keble_data_infra_contract.schemas.result import Page, RankingSnapshot
+
+from ..runtime.provider_registry import ProviderRegistry
+
+OperationResponse = (
+    Page[CommerceProduct]
+    | Page[CommerceListing]
+    | Page[CreatorProductLink]
+    | Page[ShortVideo]
+    | RankingSnapshot[CommerceProduct]
+    | RankingSnapshot[CommerceListing]
+    | RankingSnapshot[CommerceCreator]
+    | RankingSnapshot[CommerceStore]
+)
+OperationEndpoint = Callable[..., Awaitable[OperationResponse]]
+
+
+class ProviderOperationDto(ContractModel):
+    """One provider capability returned by discovery."""
+
+    resource: CommerceResource
+    action: CommerceAction
+    path: str
+    operation_id: str
+
+
+class ProviderDiscoveryDto(ContractModel):
+    """One provider and its complete explicit operation set."""
+
+    channel: Channel
+    provider_id: ProviderId
+    operations: tuple[ProviderOperationDto, ...]
+
+
+async def _invoke(
+    operation: ServiceOperation[ContractModel, ContractModel],
+    request: ContractModel,
+) -> OperationResponse:
+    """Invoke one manifest operation and erase only the heterogeneous response union."""
+
+    with sentry_sdk.start_span(
+        op="data_infra.provider_operation",
+        name=operation.key.operation_id(),
+    ) as span:
+        span.set_data("channel", operation.key.channel.value)
+        span.set_data("provider", operation.key.provider_id.root)
+        span.set_data("resource", operation.key.resource.value)
+        span.set_data("action", operation.key.action.value)
+        return cast(OperationResponse, await operation.invoke(request))
+
+
+def _endpoint_for(
+    operation: ServiceOperation[ContractModel, ContractModel],
+) -> OperationEndpoint:
+    """Create a concrete typed FastAPI endpoint for one request model.
+
+    Side effects if changes:
+    - request body schemas for every generated provider route;
+    - manifest handler invocation and response validation;
+    - OpenAPI route parity tests.
+    """
+
+    if operation.request_model is ProductLookupQuery:
+        async def product_lookup(request: ProductLookupQuery) -> OperationResponse:
+            return await _invoke(operation, request)
+        return product_lookup
+    if operation.request_model is ProductSearchQuery:
+        async def product_search(request: ProductSearchQuery) -> OperationResponse:
+            return await _invoke(operation, request)
+        return product_search
+    if operation.request_model is ProductRankingQuery:
+        async def product_ranking(request: ProductRankingQuery) -> OperationResponse:
+            return await _invoke(operation, request)
+        return product_ranking
+    if operation.request_model is CreatorRankingQuery:
+        async def creator_ranking(request: CreatorRankingQuery) -> OperationResponse:
+            return await _invoke(operation, request)
+        return creator_ranking
+    if operation.request_model is SellerRankingQuery:
+        async def seller_ranking(request: SellerRankingQuery) -> OperationResponse:
+            return await _invoke(operation, request)
+        return seller_ranking
+    if operation.request_model is ProductCreatorsQuery:
+        async def product_creators(request: ProductCreatorsQuery) -> OperationResponse:
+            return await _invoke(operation, request)
+        return product_creators
+    if operation.request_model is CreatorProductsQuery:
+        async def creator_products(request: CreatorProductsQuery) -> OperationResponse:
+            return await _invoke(operation, request)
+        return creator_products
+    if operation.request_model is ProductVideosQuery:
+        async def product_videos(request: ProductVideosQuery) -> OperationResponse:
+            return await _invoke(operation, request)
+        return product_videos
+    raise ValueError(f"request model is not registered for HTTP: {operation.request_model}")
+
+
+def create_router(registry: ProviderRegistry) -> APIRouter:
+    """Build every raw route from the central registry and no provider routers."""
+
+    router = APIRouter()
+
+    @router.get("/health", operation_id="health")
+    async def health() -> dict[str, str]:
+        """Report process liveness without contacting providers."""
+
+        return {"status": "ok"}
+
+    @router.get(
+        "/v1/{channel}/providers",
+        response_model=list[ProviderDiscoveryDto],
+        operation_id="list_channel_providers",
+    )
+    async def list_providers(channel: Channel) -> list[ProviderDiscoveryDto]:
+        """List only capabilities explicitly registered for one channel."""
+
+        with sentry_sdk.start_span(
+            op="data_infra.registry.discovery",
+            name=f"providers:{channel.value}",
+        ) as span:
+            manifests = registry.providers_for(channel)
+            span.set_data("provider_count", len(manifests))
+            return [
+                ProviderDiscoveryDto(
+                    channel=manifest.channel,
+                    provider_id=manifest.provider_id,
+                    operations=tuple(
+                        ProviderOperationDto(
+                            resource=operation.key.resource,
+                            action=operation.key.action,
+                            path=operation.key.http_path(),
+                            operation_id=operation.key.operation_id(),
+                        )
+                        for operation in manifest.operations
+                    ),
+                )
+                for manifest in manifests
+            ]
+
+    for operation in registry.operations:
+        router.add_api_route(
+            operation.key.http_path(),
+            _endpoint_for(operation),
+            methods=["POST"],
+            response_model=operation.response_model,
+            operation_id=operation.key.operation_id(),
+        )
+
+    return router

keble_data_infra_api/api/video_enrichment_router.py

@@ -0,0 +1,169 @@
+"""Internal-only query and recovery routes for local enrichment projections."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from fastapi import APIRouter, HTTPException, Query, status
+
+from keble_data_infra_api.integrations.video_enrichment.service import IngestionOutcome
+from keble_data_infra_contract.models.video_enrichment import (
+    VideoEnrichmentJob,
+    VideoEnrichmentIngestionRecord,
+    VideoEnrichmentProjection,
+    VideoEnrichmentSubmitRequest,
+)
+
+
+class VideoEnrichmentRouterServiceProtocol(Protocol):
+    """Typed application surface consumed by internal enrichment routes."""
+
+    async def get_projection(
+        self,
+        result_id: str,
+    ) -> VideoEnrichmentProjection | None:
+        """Read one normalized projection by result identity."""
+        ...
+
+    async def submit(
+        self,
+        request: VideoEnrichmentSubmitRequest,
+    ) -> VideoEnrichmentJob:
+        """Submit one idempotent independent enrichment job."""
+        ...
+
+    async def get_job(self, job_id: str) -> VideoEnrichmentJob | None:
+        """Read one submitted job by stable identity."""
+        ...
+
+    async def get_projection_by_job_id(
+        self,
+        job_id: str,
+    ) -> VideoEnrichmentProjection | None:
+        """Read the newest normalized projection by submitted job identity."""
+        ...
+
+    async def list_failed_ingestions(
+        self,
+        limit: int,
+    ) -> list[VideoEnrichmentIngestionRecord]:
+        """List bounded durable ingestion failures."""
+        ...
+
+    async def retry_failed_ingestion(
+        self,
+        event_id: str,
+    ) -> IngestionOutcome | None:
+        """Retry one durable failed completion event."""
+        ...
+
+    async def replay_result(self, result_id: str) -> IngestionOutcome:
+        """Re-ingest one authoritative result through the canonical state machine."""
+        ...
+
+
+def build_video_enrichment_router(
+    service: VideoEnrichmentRouterServiceProtocol,
+) -> APIRouter:
+    """Build internal operations without adding fields to public commerce APIs."""
+
+    router = APIRouter(prefix="/internal", tags=["video-enrichment-internal"])
+
+    @router.post(
+        "/video-enrichments:submit",
+        response_model=VideoEnrichmentJob,
+        status_code=status.HTTP_202_ACCEPTED,
+    )
+    async def submit_video_enrichment(
+        request: VideoEnrichmentSubmitRequest,
+    ) -> VideoEnrichmentJob:
+        """Submit video analysis without exposing the independent service to consumers.
+
+        Side effects if changes:
+        - Stand Out ENRICH workers call only this centralized data-infra API;
+        - deterministic upstream idempotency makes retrying the same command safe.
+        """
+
+        return await service.submit(request)
+
+    @router.get(
+        "/video-enrichment-jobs/{job_id}",
+        response_model=VideoEnrichmentJob,
+        responses={404: {"description": "Enrichment job not found"}},
+    )
+    async def get_video_enrichment_job(job_id: str) -> VideoEnrichmentJob:
+        """Read one submitted job without leaking upstream persistence fields."""
+
+        job = await service.get_job(job_id)
+        if job is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail={"code": "VIDEO_ENRICHMENT_JOB_NOT_FOUND"},
+            )
+        return job
+
+    @router.get(
+        "/video-enrichments/{result_id}",
+        response_model=VideoEnrichmentProjection,
+        responses={404: {"description": "Projection not found"}},
+    )
+    async def get_video_enrichment(result_id: str) -> VideoEnrichmentProjection:
+        projection = await service.get_projection(result_id)
+        if projection is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail={"code": "VIDEO_ENRICHMENT_NOT_FOUND"},
+            )
+        return projection
+
+    @router.get(
+        "/video-enrichment-jobs/{job_id}/projection",
+        response_model=VideoEnrichmentProjection,
+        responses={404: {"description": "Completed projection not found"}},
+    )
+    async def get_video_enrichment_by_job(
+        job_id: str,
+    ) -> VideoEnrichmentProjection:
+        """Resolve one submitted job to its newest normalized local projection.
+
+        Side effects if changes:
+        - Stand Out ENRICH workers depend on this API-owned correlation route;
+        - a 404 means completion ingestion is not yet durably available and is retryable.
+        """
+
+        projection = await service.get_projection_by_job_id(job_id)
+        if projection is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail={"code": "VIDEO_ENRICHMENT_JOB_PROJECTION_NOT_FOUND"},
+            )
+        return projection
+
+    @router.get(
+        "/video-enrichment-ingestions/failed",
+        response_model=list[VideoEnrichmentIngestionRecord],
+    )
+    async def list_failed_video_enrichment_ingestions(
+        limit: int = Query(default=100, ge=1, le=500),
+    ) -> list[VideoEnrichmentIngestionRecord]:
+        return await service.list_failed_ingestions(limit=limit)
+
+    @router.post(
+        "/video-enrichment-ingestions/{event_id}/retry",
+        responses={404: {"description": "Failed ingestion not found"}},
+    )
+    async def retry_video_enrichment_ingestion(event_id: str) -> dict[str, str | None]:
+        outcome = await service.retry_failed_ingestion(event_id)
+        if outcome is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail={"code": "FAILED_INGESTION_NOT_FOUND"},
+            )
+        return {"disposition": outcome.disposition.value, "reason": outcome.reason}
+
+    @router.post("/video-enrichments/{result_id}/replay")
+    async def replay_video_enrichment_result(result_id: str) -> dict[str, str | None]:
+        outcome = await service.replay_result(result_id)
+        return {"disposition": outcome.disposition.value, "reason": outcome.reason}
+
+    return router

keble_data_infra_api/integrations/__init__.py

@@ -0,0 +1,2 @@
+"""External integration adapters owned by the raw API runtime."""
+

keble_data_infra_api/integrations/video_enrichment/__init__.py

@@ -0,0 +1,2 @@
+"""Video-enrichment ingestion and persistence adapters."""
+