shopping-cli 3.0.0__py3-none-any.whl

shopping_cli/api/handlers/catalog.py

@@ -0,0 +1,392 @@
+"""Catalog and marketplace HTTP handlers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import hashlib
+import hmac
+import sqlite3
+from typing import Any
+
+from shopping_cli import VERSION
+from shopping_cli.config import deployment_profile_from, production_config_checks, validate_production_config
+from shopping_cli.core import catalog
+from shopping_cli.api import auth as api_auth
+from shopping_cli.api import idempotency
+from shopping_cli.core.errors import AuthError, ConflictError, IdempotencyConflict
+from shopping_cli.core.harness import append_audit_event
+from shopping_cli.core.tokens import token_digest
+from shopping_cli.db.session import db_session
+from shopping_cli.services import tokens as token_service
+
+from .common import (
+    bool_from_query,
+    public_merchant_summary,
+    public_product_summary,
+    require_field,
+    result_limit,
+    result_offset,
+)
+
+
+def health(db_path: str | Path) -> dict[str, Any]:
+    profile = deployment_profile_from()
+    checks: dict[str, Any] = production_config_checks()
+    checks["database"] = "ok"
+    ok = True
+    try:
+        validate_production_config()
+    except ValueError:
+        ok = False
+    try:
+        with db_session(db_path):
+            pass
+    except Exception:
+        checks["database"] = "error"
+        ok = False
+    return {
+        "ok": ok,
+        "service": "shopping-cli-marketplace",
+        "version": VERSION,
+        "storage": "sqlite",
+        "deployment_profile": profile,
+        "checks": checks,
+    }
+
+
+def merchant_list(conn: Any, limit: int = 50, offset: int = 0) -> list[dict[str, Any]]:
+    return catalog.list_merchants(conn, limit=int(limit), offset=int(offset))
+
+
+def _server_idempotency_key(admin_token_hash: str, merchant_id: str) -> str:
+    """Derive a server-side idempotency key so every bootstrap is replayable."""
+    return f"auto:{admin_token_hash}:{merchant_id}"
+
+
+def create_merchant(db_path: str | Path, payload: dict[str, Any], require_admin_token: Any) -> dict[str, Any]:
+    require_admin_token(payload)
+    merchant_id = str(require_field(payload, "id"))
+    name = str(require_field(payload, "name"))
+    admin_token = api_auth.payload_admin_token(payload)
+    admin_token_hash = token_digest(admin_token)
+    # Always use a deterministic idempotency key: honour the client-supplied key
+    # when present, otherwise derive one from admin_token + merchant_id so every
+    # bootstrap is replayable even when the response was lost mid-flight.
+    client_key = idempotency.idempotency_key_from_payload(payload)
+    idempotency_key = client_key or _server_idempotency_key(admin_token_hash, merchant_id)
+    request_hash = idempotency.request_hash(
+        {
+            "id": merchant_id,
+            "name": name,
+            "city": str(payload.get("city") or ""),
+            "service_area": str(payload.get("service_area") or ""),
+            "contact": str(payload.get("contact") or ""),
+            "hours": str(payload.get("hours") or ""),
+            "automation_boundaries": str(payload.get("automation_boundaries") or ""),
+            "tags": payload.get("tags") or [],
+            "delivery_fee": payload.get("delivery_fee", 0),
+            "delivery_eta_minutes": payload.get("delivery_eta_minutes", 0),
+            "delivery_radius_km": payload.get("delivery_radius_km", 0),
+        }
+    )
+
+    def replay(conn: Any) -> dict[str, Any] | None:
+        row = conn.execute(
+            """
+            select request_hash, merchant_id from merchant_bootstrap_idempotency
+            where admin_token_hash = ? and idempotency_key = ?
+            """,
+            (admin_token_hash, idempotency_key),
+        ).fetchone()
+        if row is None:
+            return None
+        if str(row["request_hash"]) != request_hash:
+            raise IdempotencyConflict("idempotency key was reused with a different request")
+        replay_merchant_id = str(row["merchant_id"] or merchant_id)
+        token = deterministic_merchant_token(admin_token, idempotency_key, replay_merchant_id)
+        token_row = conn.execute(
+            "select revoked_at from api_tokens where token_hash = ?",
+            (token_digest(token),),
+        ).fetchone()
+        if token_row is not None and str(token_row["revoked_at"] or ""):
+            raise ConflictError(
+                "merchant bootstrap token was rotated or revoked; "
+                "use POST /merchants/{merchant_id}/token/recover to recover"
+            )
+        token_service.ensure_merchant_token(conn, token, replay_merchant_id)
+        return {
+            "ok": True,
+            "merchant": catalog.merchant_summary(conn, replay_merchant_id),
+            "merchant_token": token,
+            "idempotent": True,
+        }
+
+    with db_session(db_path) as conn:
+        replayed = replay(conn)
+        if replayed is not None:
+            return replayed
+        try:
+            conn.execute(
+                """
+                insert into merchant_bootstrap_idempotency(
+                    admin_token_hash, idempotency_key, request_hash, merchant_id, created_at, updated_at
+                ) values (?, ?, ?, ?, datetime('now'), datetime('now'))
+                """,
+                (admin_token_hash, idempotency_key, request_hash, merchant_id),
+            )
+        except sqlite3.IntegrityError:
+            replayed = replay(conn)
+            if replayed is not None:
+                return replayed
+            raise
+        try:
+            merchant = catalog.create_merchant(
+                conn,
+                merchant_id=merchant_id,
+                name=name,
+                city=str(payload.get("city") or ""),
+                service_area=str(payload.get("service_area") or ""),
+                contact=str(payload.get("contact") or ""),
+                hours=str(payload.get("hours") or ""),
+                automation_boundaries=str(payload.get("automation_boundaries") or ""),
+                tags=payload.get("tags") or [],
+                delivery_fee=payload.get("delivery_fee", 0),
+                delivery_eta_minutes=payload.get("delivery_eta_minutes", 0),
+                delivery_radius_km=payload.get("delivery_radius_km", 0),
+            )
+        except sqlite3.IntegrityError as exc:
+            raise ConflictError(f"Merchant already exists: {merchant_id}") from exc
+        token = deterministic_merchant_token(admin_token, idempotency_key, merchant["id"])
+        token_service.ensure_merchant_token(conn, token, merchant["id"])
+        return {"ok": True, "merchant": merchant, "merchant_token": token}
+
+
+def deterministic_merchant_token(admin_token: str, idempotency_key: str, merchant_id: str) -> str:
+    material = f"merchant-bootstrap\n{idempotency_key}\n{merchant_id}"
+    digest = hmac.new(admin_token.encode("utf-8"), material.encode("utf-8"), hashlib.sha256).hexdigest()
+    return f"shopping_merchant_{digest}"
+
+
+def rotate_merchant_token(
+    db_path: str | Path,
+    merchant_id: str,
+    payload: dict[str, Any],
+    require_admin_token: Any,
+) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        catalog.require_merchant(conn, merchant_id)
+        actor = "admin"
+        try:
+            require_admin_token(payload)
+        except AuthError:
+            token_row = token_service.require_merchant_token(conn, merchant_id, api_auth.payload_token(payload))
+            actor = str(token_row["merchant_id"])
+        token = token_service.rotate_merchant_token(conn, merchant_id, actor=actor)
+        return {"ok": True, "merchant_id": merchant_id, "merchant_token": token, "rotated": True}
+
+
+def recover_merchant_token(
+    db_path: str | Path,
+    merchant_id: str,
+    payload: dict[str, Any],
+    require_admin_token: Any,
+) -> dict[str, Any]:
+    """Admin recovery: issue a fresh merchant token when the bootstrap token was lost.
+
+    This is the explicit recovery path promised by the bootstrap replay error.
+    It revokes all existing merchant tokens and issues a replacement, so the
+    caller does not need the lost token.
+    """
+    require_admin_token(payload)
+    with db_session(db_path) as conn:
+        catalog.require_merchant(conn, merchant_id)
+        token = token_service.rotate_merchant_token(conn, merchant_id, actor="admin")
+        return {
+            "ok": True,
+            "merchant_id": merchant_id,
+            "merchant_token": token,
+            "recovered": True,
+        }
+
+
+def revoke_merchant_tokens(
+    db_path: str | Path,
+    merchant_id: str,
+    payload: dict[str, Any],
+    require_admin_token: Any,
+) -> dict[str, Any]:
+    require_admin_token(payload)
+    with db_session(db_path) as conn:
+        catalog.require_merchant(conn, merchant_id)
+        count = token_service.revoke_merchant_tokens(conn, merchant_id, actor="admin")
+        return {"ok": True, "merchant_id": merchant_id, "revoked_count": count}
+
+
+def update_merchant(
+    db_path: str | Path,
+    merchant_id: str,
+    payload: dict[str, Any],
+    require_merchant_token: Any,
+) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        require_merchant_token(conn, merchant_id, payload)
+        merchant = catalog.update_merchant(
+            conn,
+            merchant_id=merchant_id,
+            name=payload.get("name"),
+            city=payload.get("city"),
+            service_area=payload.get("service_area"),
+            contact=payload.get("contact"),
+            hours=payload.get("hours"),
+            automation_boundaries=payload.get("automation_boundaries"),
+            tags=payload.get("tags") if "tags" in payload else None,
+            delivery_fee=payload.get("delivery_fee"),
+            delivery_eta_minutes=payload.get("delivery_eta_minutes"),
+            delivery_radius_km=payload.get("delivery_radius_km"),
+        )
+        return {"ok": True, "merchant": merchant}
+
+
+def get_merchant(db_path: str | Path, merchant_id: str) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        return {"ok": True, "merchant": public_merchant_summary(catalog.merchant_summary(conn, merchant_id))}
+
+
+def get_merchant_private_config(
+    db_path: str | Path,
+    merchant_id: str,
+    payload: dict[str, Any],
+) -> dict[str, Any]:
+    """Return private automation policy to an authenticated merchant/agent."""
+    with db_session(db_path) as conn:
+        merchant = catalog.require_merchant(conn, merchant_id)
+        token_row = token_service.require_api_token(
+            conn,
+            api_auth.payload_token(payload),
+            "merchant or agent token required",
+        )
+        if token_row["merchant_id"] != merchant_id or token_row["role"] not in {"merchant", "agent"}:
+            raise AuthError("invalid merchant or agent token")
+        actor = str(token_row["agent_id"] or merchant_id)
+        version = str(merchant["updated_at"] or "")
+        append_audit_event(
+            conn,
+            "",
+            actor,
+            "merchant_automation_boundaries_loaded",
+            {"merchant_id": merchant_id, "version": version},
+        )
+        return {
+            "ok": True,
+            "merchant_id": merchant_id,
+            "automation_boundaries": str(merchant["automation_boundaries"] or ""),
+            "version": version,
+        }
+
+def list_merchants(db_path: str | Path, query: dict[str, Any] | None = None) -> dict[str, Any]:
+    query = query or {}
+    with db_session(db_path) as conn:
+        return {
+            "ok": True,
+            "results": [
+                public_merchant_summary(merchant)
+                for merchant in merchant_list(
+                    conn,
+                    limit=result_limit(query.get("limit")),
+                    offset=result_offset(query.get("offset")),
+                )
+            ],
+        }
+
+
+def create_product(
+    db_path: str | Path,
+    payload: dict[str, Any],
+    require_merchant_token: Any,
+) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        merchant_id = str(require_field(payload, "merchant_id"))
+        require_merchant_token(conn, merchant_id, payload)
+        product = catalog.create_product(
+            conn,
+            merchant_id=merchant_id,
+            sku=str(require_field(payload, "sku")),
+            title=str(require_field(payload, "title")),
+            price=require_field(payload, "price"),
+            stock=require_field(payload, "stock"),
+            currency=str(payload.get("currency") or "CNY"),
+            category=str(payload.get("category") or ""),
+            tags=payload.get("tags") or [],
+            description=str(payload.get("description") or ""),
+            delivery_attributes=payload.get("delivery_attributes") or [],
+        )
+        return {"ok": True, "product": product}
+
+
+def update_product(
+    db_path: str | Path,
+    sku: str,
+    payload: dict[str, Any],
+    require_merchant_token: Any,
+) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        existing = catalog.product_summary(conn, sku)
+        merchant_id = str(payload.get("merchant_id") or existing["merchant_id"])
+        require_merchant_token(conn, merchant_id, payload)
+        product = catalog.update_product(
+            conn,
+            sku=sku,
+            merchant_id=merchant_id,
+            title=payload.get("title"),
+            price=payload.get("price"),
+            stock=payload.get("stock"),
+            currency=payload.get("currency"),
+            category=payload.get("category"),
+            tags=payload.get("tags") if "tags" in payload else None,
+            description=payload.get("description"),
+            delivery_attributes=payload.get("delivery_attributes") if "delivery_attributes" in payload else None,
+        )
+        return {"ok": True, "product": product}
+
+
+def get_product(db_path: str | Path, sku: str) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        return {"ok": True, "product": public_product_summary(catalog.product_summary(conn, sku))}
+
+
+def search_products(db_path: str | Path, query: dict[str, Any]) -> dict[str, Any]:
+    max_price = query.get("max_price")
+    with db_session(db_path) as conn:
+        return {
+            "ok": True,
+            "results": [
+                public_product_summary(product)
+                for product in catalog.search_products(
+                    conn,
+                    query=str(query.get("query") or ""),
+                    city=str(query.get("city") or ""),
+                    area=str(query.get("area") or ""),
+                    max_price=max_price if str(max_price or "") else None,
+                    include_out_of_stock=bool_from_query(query.get("include_out_of_stock")),
+                    limit=result_limit(query.get("limit"), default=10),
+                    offset=result_offset(query.get("offset")),
+                )
+            ],
+        }
+
+
+def search_merchants(db_path: str | Path, query: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        return {
+            "ok": True,
+            "results": [
+                public_merchant_summary(merchant)
+                for merchant in catalog.search_merchants(
+                    conn,
+                    query=str(query.get("query") or ""),
+                    city=str(query.get("city") or ""),
+                    limit=result_limit(query.get("limit"), default=10),
+                    offset=result_offset(query.get("offset")),
+                )
+            ],
+        }

shopping_cli/api/handlers/common.py

@@ -0,0 +1,76 @@
+"""Shared API handler normalization helpers."""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+from shopping_cli.core.catalog import (
+    public_merchant_summary as catalog_public_merchant_summary,
+    public_product_summary as catalog_public_product_summary,
+)
+from shopping_cli.core.errors import ValidationError
+
+MAX_SQLITE_INTEGER = 2**63 - 1
+
+
+def require_field(payload: dict[str, Any], field: str) -> Any:
+    try:
+        return payload[field]
+    except KeyError as exc:
+        raise ValidationError(f"missing required field: {field}") from exc
+DEFAULT_RESULT_LIMIT = 50
+MAX_RESULT_LIMIT = 100
+
+
+def bool_from_query(value: Any) -> bool:
+    return str(value or "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def non_negative_whole_int(value: Any, field_name: str, default: int = 0) -> int:
+    if value in (None, ""):
+        return default
+    if isinstance(value, bool):
+        raise ValidationError(f"{field_name} must be a whole number")
+    if isinstance(value, int):
+        number = value
+    elif isinstance(value, float):
+        if not math.isfinite(value) or not value.is_integer():
+            raise ValidationError(f"{field_name} must be a whole number")
+        number = int(value)
+    else:
+        try:
+            number = int(str(value).strip())
+        except ValueError as exc:
+            raise ValidationError(f"{field_name} must be a whole number") from exc
+    if number < 0:
+        raise ValidationError(f"{field_name} must be non-negative")
+    if number > MAX_SQLITE_INTEGER:
+        raise ValidationError(f"{field_name} must be <= {MAX_SQLITE_INTEGER}")
+    return number
+
+
+def positive_whole_int(value: Any, field_name: str) -> int:
+    number = non_negative_whole_int(value, field_name)
+    if number <= 0:
+        raise ValidationError(f"{field_name} must be greater than 0")
+    return number
+
+
+def result_limit(value: Any, default: int = DEFAULT_RESULT_LIMIT) -> int:
+    if value in (None, ""):
+        return default
+    return min(positive_whole_int(value, "limit"), MAX_RESULT_LIMIT)
+
+
+def result_offset(value: Any) -> int:
+    return non_negative_whole_int(value, "offset", default=0)
+
+
+def public_merchant_summary(merchant: dict[str, Any]) -> dict[str, Any]:
+    """公开投影：剥离商家私有字段（contact / automation_boundaries）。"""
+    return catalog_public_merchant_summary(merchant)
+
+
+def public_product_summary(product: dict[str, Any]) -> dict[str, Any]:
+    return catalog_public_product_summary(product)

shopping_cli/api/handlers/conversations.py

@@ -0,0 +1,172 @@
+"""Conversation API handlers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from shopping_cli.api import auth as api_auth
+from shopping_cli.api.handlers.common import DEFAULT_RESULT_LIMIT, require_field, result_limit, result_offset
+from shopping_cli.core.conversations import (
+    conversation_summary,
+    merchant_conversations as merchant_conversation_summaries,
+    normalize_structured_payload,
+)
+from shopping_cli.core.errors import AuthError, ValidationError
+from shopping_cli.db.session import db_session
+from shopping_cli.services import conversations as conversation_service
+from shopping_cli.services import tokens as token_service
+
+
+def _payload_token(payload: dict[str, Any]) -> str:
+    return api_auth.payload_token(payload)
+
+
+def get_conversation(db_path: str | Path, conversation_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        conversation = conversation_summary(conn, conversation_id)
+        token_service.require_conversation_read_token(conn, conversation, _payload_token(payload))
+        return {"ok": True, "conversation": conversation}
+
+
+def append_conversation_message(db_path: str | Path, conversation_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        conversation = conversation_summary(conn, conversation_id)
+        sender = str(require_field(payload, "sender"))
+        structured_payload = normalize_structured_payload(payload.get("structured_payload"))
+        if payload.get("source_id"):
+            structured_payload["source_id"] = payload.get("source_id")
+        status = payload.get("status")
+        if sender in {"buyer", "buyer_cli"}:
+            token_service.require_buyer_conversation_token(conn, conversation, _payload_token(payload))
+            if status not in (None, ""):
+                raise ValidationError("buyer messages cannot set conversation status")
+        elif sender == "merchant":
+            token_service.require_merchant_token(conn, conversation["merchant_id"], _payload_token(payload))
+        elif sender == "merchant_agent":
+            agent_id = str(
+                structured_payload.get("source_id")
+                or token_service.default_merchant_agent_id(conversation["merchant_id"])
+            )
+            token_service.require_agent_or_merchant_token(
+                conn,
+                conversation["merchant_id"],
+                agent_id,
+                _payload_token(payload),
+            )
+        elif sender == "operator":
+            token_service.require_merchant_token(conn, conversation["merchant_id"], _payload_token(payload))
+        else:
+            raise ValidationError(f"Unknown conversation sender: {sender}")
+        result = conversation_service.append_conversation_message(
+            conn,
+            conversation,
+            conversation_id,
+            sender=sender,
+            intent=str(require_field(payload, "intent")),
+            text=str(require_field(payload, "text")),
+            structured_payload=structured_payload,
+            status=status,
+        )
+        return {"ok": True, **result}
+
+
+def close_conversation(db_path: str | Path, conversation_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        conversation = conversation_summary(conn, conversation_id)
+        sender = str(payload.get("sender") or "operator")
+        if sender in {"buyer", "buyer_cli"}:
+            token_service.require_buyer_conversation_token(conn, conversation, _payload_token(payload))
+        elif sender == "merchant":
+            token_service.require_merchant_token(conn, conversation["merchant_id"], _payload_token(payload))
+        elif sender == "merchant_agent":
+            agent_id = str(payload.get("source_id") or token_service.default_merchant_agent_id(conversation["merchant_id"]))
+            token_service.require_agent_or_merchant_token(conn, conversation["merchant_id"], agent_id, _payload_token(payload))
+        elif sender == "operator":
+            token_service.require_merchant_token(conn, conversation["merchant_id"], _payload_token(payload))
+        else:
+            raise ValidationError(f"Unknown conversation sender: {sender}")
+        conversation = conversation_service.close_conversation(
+            conn,
+            conversation,
+            conversation_id,
+            sender=sender,
+            intent=str(payload.get("intent") or "support"),
+            text=str(payload.get("text") or ""),
+            source_id=str(payload.get("source_id") or ""),
+        )
+        return {"ok": True, "conversation": conversation}
+
+
+def append_conversation_closed_audit(
+    conn: Any,
+    conversation_id: str,
+    actor: str,
+    next_actor: str,
+    details: dict[str, Any] | None = None,
+) -> None:
+    conversation_service.append_conversation_closed_audit(conn, conversation_id, actor, next_actor, details)
+
+
+def conversation_list(
+    db_path: str | Path,
+    filters: dict[str, Any],
+    payload: dict[str, Any],
+    owner_kind: str,
+    owner_id: str,
+) -> dict[str, Any]:
+    clauses: list[str] = []
+    values: list[Any] = []
+    for column in ("status", "merchant_id", "buyer_id", "sku"):
+        if filters.get(column):
+            clauses.append(f"{column} = ?")
+            values.append(str(filters[column]))
+    if filters.get("updated_since"):
+        clauses.append("updated_at >= ?")
+        values.append(str(filters["updated_since"]))
+    with db_session(db_path) as conn:
+        if owner_kind == "buyer":
+            token_row = token_service.require_buyer_read_token(conn, owner_id, _payload_token(payload))
+            if token_row["conversation_id"]:
+                clauses.append("id = ?")
+                values.append(str(token_row["conversation_id"]))
+        elif owner_kind == "merchant":
+            token_service.require_merchant_read_token(conn, owner_id, _payload_token(payload))
+        else:
+            raise AuthError("conversation list owner is required")
+        limit = result_limit(filters.get("limit"))
+        offset = result_offset(filters.get("offset"))
+        if str(filters.get("include") or "").lower() == "details":
+            results = conversation_service.list_conversation_details(
+                conn, clauses=clauses, values=values, limit=limit, offset=offset
+            )
+        else:
+            results = conversation_service.list_conversation_summaries(
+                conn, clauses=clauses, values=values, limit=limit, offset=offset
+            )
+        return {"ok": True, "conversations": results}
+
+
+def merchant_conversations(
+    db_path: str | Path,
+    merchant_id: str,
+    payload: dict[str, Any],
+    status: str = "",
+    limit: Any = DEFAULT_RESULT_LIMIT,
+    offset: Any = 0,
+    include: Any = "",
+) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        token_service.require_merchant_read_token(conn, merchant_id, _payload_token(payload))
+        return {
+            "ok": True,
+            "merchant_id": merchant_id,
+            "conversations": merchant_conversation_summaries(
+                conn,
+                merchant_id,
+                status,
+                limit=result_limit(limit),
+                offset=result_offset(offset),
+                summary_only=str(include or "").lower() != "details",
+            ),
+        }