opsai-cli 0.1.0__py3-none-any.whl

opsai_cli/contracts.py

@@ -0,0 +1,203 @@
+"""Standalone API v1 snapshot (2026-10-31).
+
+Mirrors api/routes/open_api/schemas.py and shared/button_guide.py.
+Contract tests compare against those pure model definitions without importing
+the backend. Never import backend modules in the distributed client.
+"""
+from typing import Annotated, Literal
+from urllib.parse import urlsplit
+import ipaddress
+
+from pydantic import BaseModel, ConfigDict, Field, AfterValidator, model_validator
+
+
+
+class ButtonRegion(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    number: int = Field(ge=1, le=100)
+    x: float = Field(ge=0, le=1, allow_inf_nan=False)
+    y: float = Field(ge=0, le=1, allow_inf_nan=False)
+    text: str = Field(min_length=1, max_length=1000)
+
+    @model_validator(mode="after")
+    def nonblank(self):
+        if not self.text.strip():
+            raise ValueError("请填写每个标记的功能")
+        return self
+
+class ButtonGuide(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    original: str = Field(min_length=1, max_length=2048)
+    base: str | None = Field(default=None, max_length=2048)
+    annotated: str | None = Field(default=None, max_length=2048)
+    marker_size: float = Field(default=0.036, ge=0.000001, le=8, allow_inf_nan=False)
+    regions: list[ButtonRegion] = Field(default_factory=list, max_length=100)
+
+    @model_validator(mode="after")
+    def unique_numbers(self):
+        if len({r.number for r in self.regions}) != len(self.regions):
+            raise ValueError("功能标记序号不能重复")
+        if self.regions and not self.annotated:
+            raise ValueError("功能标记缺少已保存的标记图片")
+        return self
+
+
+
+def public_url(value: str) -> str:
+    parsed = urlsplit(value)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname or parsed.username or parsed.password:
+        raise ValueError("素材必须是公开的 HTTP/HTTPS URL")
+    host = parsed.hostname.lower().rstrip(".")
+    if host == "localhost" or host.endswith((".localhost", ".local", ".internal")):
+        raise ValueError("素材 URL 不可指向内网")
+    try:
+        address = ipaddress.ip_address(host)
+    except ValueError:
+        pass
+    else:
+        if not address.is_global:
+            raise ValueError("素材 URL 不可指向内网")
+    return value
+
+
+def nonblank(value: str) -> str:
+    if not value.strip():
+        raise ValueError("不能为空")
+    return value
+
+
+Text = Annotated[str, Field(min_length=1, max_length=128), AfterValidator(nonblank)]
+Id = Annotated[int, Field(strict=True, gt=0)]
+Money = Annotated[float, Field(gt=0, allow_inf_nan=False)]
+URL = Annotated[str, Field(max_length=2000), AfterValidator(public_url)]
+
+
+class Contract(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, allow_inf_nan=False)
+
+
+class Images(Contract):
+    main_img: URL
+    bg_img: list[URL] = Field(default_factory=list)
+    size_img: URL | None = None
+    sale_img: list[URL] = Field(default_factory=list)
+    scene_img: list[URL] = Field(default_factory=list)
+    compete_img: list[URL] = Field(default_factory=list)
+    family_img: URL | None = None
+
+
+class Dimensions(Contract):
+    product_length: float | None = Field(None, ge=0)
+    product_width: float | None = Field(None, ge=0)
+    product_height: float | None = Field(None, ge=0)
+    product_weight: float | None = Field(None, ge=0)
+    package_length: float | None = Field(None, ge=0)
+    package_width: float | None = Field(None, ge=0)
+    package_height: float | None = Field(None, ge=0)
+    package_weight: float | None = Field(None, ge=0)
+    length_unit: Literal["毫米", "厘米", "米", "英寸"] = "毫米"
+    weight_unit: Literal["克", "千克", "磅"] = "克"
+
+
+class Product(Contract):
+    sku: Annotated[str, Field(min_length=1, max_length=64)]
+    spu: Annotated[str, Field(min_length=1, max_length=64)] | None = None
+    title: Annotated[str, Field(min_length=1, max_length=255)]
+    description: str | None = None
+    keywords: list[str] = Field(default_factory=list)
+    sale_points: list[str] = Field(default_factory=list)
+    video_url: URL | None = None
+    price: float | None = Field(None, ge=0)
+    currency: Literal["RMB"] = "RMB"
+    inventory: int = Field(50, ge=0)
+    package_list: str | None = Field(None, max_length=255)
+    size: str | None = None
+    dimensions: Dimensions = Field(default_factory=Dimensions)
+    images: Images
+    button_guide: ButtonGuide | None = None
+
+    @model_validator(mode="after")
+    def validate_materials(self):
+        if not self.sku.strip() or not self.title.strip() or (self.spu is not None and not self.spu.strip()):
+            raise ValueError("SKU、SPU、标题不能为空白")
+        if len(self.images.main_img) > 512:
+            raise ValueError("主图 URL 长度不能超过 512")
+        if self.button_guide:
+            for value in (self.button_guide.original, self.button_guide.base, self.button_guide.annotated):
+                if value:
+                    public_url(value)
+        return self
+
+
+class SitePrice(Contract):
+    site: Annotated[str, Field(pattern=r"^[A-Z]{2}$")]
+    price: Money
+    pre_promotion_price: Money | None = None
+    promotional_price: Money | None = None
+    currency: Annotated[str, Field(pattern=r"^[A-Z]{3}$")] | None = None
+
+
+class StorePrices(Contract):
+    store_id: Id
+    site_prices: list[SitePrice] = Field(min_length=1, max_length=100)
+
+    @model_validator(mode="after")
+    def unique_sites(self):
+        if len({row.site for row in self.site_prices}) != len(self.site_prices):
+            raise ValueError("同一店铺站点价格不可重复")
+        return self
+
+
+class ListingSubmit(Contract):
+    request_id: Text
+    store_ids: list[Id] = Field(min_length=1, max_length=100)
+    prices: list[StorePrices] = Field(min_length=1, max_length=100)
+    products: list[Product] = Field(min_length=1, max_length=100)
+
+    @model_validator(mode="after")
+    def complete_prices(self):
+        if len(set(self.store_ids)) != len(self.store_ids):
+            raise ValueError("店铺不可重复")
+        if len({p.store_id for p in self.prices}) != len(self.prices) or {p.store_id for p in self.prices} != set(self.store_ids):
+            raise ValueError("prices 必须与 store_ids 一一对应")
+        if len({p.sku for p in self.products}) != len(self.products):
+            raise ValueError("商品 SKU 不可重复")
+        return self
+
+
+class AvailableActions(Contract):
+    store_id: Id
+    listing_sku: Text
+    platform: Literal[9] = 9
+
+
+class ListingPrices(Contract):
+    store_id: Id
+    listing_skus: list[Text] = Field(min_length=1, max_length=100)
+    action_id: Id
+    platform: Literal[9]
+
+
+class ActivityItem(Contract):
+    listing_sku: Text
+    action_price: Money
+
+
+class ActivitySubmit(Contract):
+    request_id: Text
+    store_id: Id
+    action_id: Id
+    items: list[ActivityItem] = Field(min_length=1, max_length=100)
+
+    @model_validator(mode="after")
+    def unique_skus(self):
+        if len({item.listing_sku for item in self.items}) != len(self.items):
+            raise ValueError("listing_sku 不可重复")
+        return self
+
+
+class OptimizationSubmit(Contract):
+    request_id: Text
+    store_id: Id
+    mode: Literal["update", "create"]
+    listing_sku: Text

opsai_cli/credentials.py

@@ -0,0 +1,71 @@
+"""Origin-bound OS credentials; no plaintext or plugin fallback."""
+
+import hashlib
+import json
+import os
+import sys
+
+from opsai_cli.config import normalize_base_url, profile_name
+from opsai_cli.errors import CliError
+
+
+UNAVAILABLE = "System credential storage is unavailable or locked; use OPSAI_API_KEY in this process instead."
+
+
+def validate_key(value: str) -> str:
+    if (not isinstance(value, str) or not value or len(value) > 72
+            or any(ord(c) < 33 or ord(c) > 126 for c in value)):
+        raise CliError("API Key must contain 1-72 printable ASCII characters without whitespace.")
+    return value
+
+
+def system_backend():
+    # Select built-in OS implementations explicitly. Do not honor third-party
+    # plaintext, null, or chained fallback backends configured via keyring.
+    try:
+        if sys.platform == "win32":
+            from keyring.backends.Windows import WinVaultKeyring
+            backend = WinVaultKeyring()
+        elif sys.platform == "darwin":
+            from keyring.backends.macOS import Keyring
+            backend = Keyring()
+        elif sys.platform.startswith("linux"):
+            from keyring.backends.SecretService import Keyring
+            backend = Keyring()
+        else:
+            raise CliError(UNAVAILABLE)
+        if backend.priority <= 0:
+            raise CliError(UNAVAILABLE)
+        return backend
+    except Exception:
+        raise CliError(UNAVAILABLE) from None
+
+
+def credential_account(profile: str, base_url: str) -> str:
+    identity = [profile_name(profile), normalize_base_url(base_url)]
+    return hashlib.sha256(json.dumps(identity, separators=(",", ":")).encode()).hexdigest()
+
+
+class CredentialStore:
+    def __init__(self, backend_factory=None):
+        self.backend_factory = backend_factory or system_backend
+
+    def save(self, profile: str, base_url: str, key: str) -> None:
+        key = validate_key(key)
+        account = credential_account(profile, base_url)
+        try:
+            self.backend_factory().set_password("opsai-cli", account, key)
+        except Exception:
+            raise CliError(UNAVAILABLE) from None
+
+    def resolve(self, profile: str, base_url: str) -> str:
+        account = credential_account(profile, base_url)
+        if "OPSAI_API_KEY" in os.environ:
+            return validate_key(os.environ["OPSAI_API_KEY"])
+        try:
+            key = self.backend_factory().get_password("opsai-cli", account)
+        except Exception:
+            raise CliError(UNAVAILABLE) from None
+        if key is None:
+            raise CliError("No API Key for this profile and service address; run opsai auth configure or set OPSAI_API_KEY.")
+        return validate_key(key)

opsai_cli/errors.py

@@ -0,0 +1,11 @@
+"""Safe user-facing errors; never render raw transport or backend exceptions."""
+
+
+class CliError(Exception):
+    def __init__(self, message: str, exit_code: int = 2, *, status: int | None = None,
+                 retryable: bool = False, retry_after: float | None = None):
+        super().__init__(message)
+        self.exit_code = exit_code
+        self.status = status
+        self.retryable = retryable
+        self.retry_after = retry_after

opsai_cli/output.py

@@ -0,0 +1,62 @@
+"""Stable stdout results and stderr diagnostics, with credential redaction."""
+
+import json
+import re
+import sys
+
+from opsai_cli.errors import CliError
+
+
+class Output:
+    def __init__(self, mode=None, secrets=()):
+        self.mode = mode or ("table" if sys.stdout.isatty() else "json")
+        self.secrets = tuple(s for s in secrets if s)
+
+    def clean(self, value):
+        if isinstance(value, str):
+            for secret in self.secrets:
+                value = value.replace(secret, "[REDACTED]")
+            return re.sub(r"(?i)bearer\s+[^\s\"']+", "Bearer [REDACTED]", value)
+        if isinstance(value, list):
+            return [self.clean(v) for v in value]
+        if isinstance(value, dict):
+            return {self.clean(str(k)): self.clean(v) for k, v in value.items()}
+        return value
+
+    def note(self, text):
+        print(self.clean(text), file=sys.stderr, flush=True)
+
+    def emit(self, value, event="result"):
+        value = self.clean(value)
+        try:
+            json.dumps(value, allow_nan=False)
+        except (ValueError, TypeError, RecursionError):
+            raise CliError("API returned non-serializable or non-finite result data.", 5) from None
+        if self.mode == "ndjson":
+            print(json.dumps({"event": event, "data": value}, ensure_ascii=True, allow_nan=False), flush=True)
+        elif self.mode == "json":
+            print(json.dumps(value, ensure_ascii=True, indent=2, allow_nan=False), flush=True)
+        else:
+            data = value.get("data", value) if isinstance(value, dict) else value
+            rows = data if isinstance(data, list) else [data]
+            if rows and all(isinstance(row, dict) for row in rows):
+                columns = list(dict.fromkeys(k for row in rows for k in row))
+                print("\t".join(columns))
+                for row in rows:
+                    print("\t".join(json.dumps(row.get(k), ensure_ascii=True) for k in columns))
+            else:
+                print(json.dumps(data, ensure_ascii=True))
+            print("Business task times: Asia/Shanghai; platform timestamps retain their source timezone.")
+
+    def event(self, name, data):
+        if self.mode == "ndjson":
+            self.emit(data, name)
+        elif name == "log":
+            self.note(str(data.get("message", "")))
+
+    def error(self, exc):
+        error = {"source": "cli", "exit_code": exc.exit_code, "message": str(exc)}
+        if self.mode in {"json", "ndjson"}:
+            print(json.dumps(self.clean({"error": error}), ensure_ascii=True), file=sys.stderr, flush=True)
+        else:
+            self.note(f"opsai: {exc}")

opsai_cli/sse.py

@@ -0,0 +1,65 @@
+"""Bounded SSE framing over HTTPX's incremental UTF-8 line decoder."""
+
+import json
+import codecs
+
+from opsai_cli.errors import CliError
+
+
+def utf8_lines(chunks, check=lambda: None):
+    decoder = codecs.getincrementaldecoder("utf-8")("strict")
+    line, skip_lf = [], False
+    try:
+        for chunk in chunks:
+            check()
+            text = decoder.decode(chunk)
+            for char in text:
+                if skip_lf:
+                    skip_lf = False
+                    if char == "\n":
+                        continue
+                if char in "\r\n":
+                    yield "".join(line)
+                    line = []
+                    skip_lf = char == "\r"
+                else:
+                    line.append(char)
+                    if len(line) > 2 * 1024 * 1024:
+                        raise CliError("SSE line exceeded the supported size.", 5)
+        tail = decoder.decode(b"", final=True)
+        if tail or line:
+            yield "".join(line) + tail
+    except UnicodeError:
+        raise CliError("SSE returned invalid UTF-8.", 5) from None
+
+
+def parse_events(lines, check=lambda: None):
+    name, data, size = "message", [], 0
+    first = True
+    for line in lines:
+        check()
+        if first:
+            line = line.removeprefix("\ufeff")
+            first = False
+        size += len(line)
+        if size > 2 * 1024 * 1024:
+            raise CliError("SSE event exceeded the supported size.", 5)
+        if line == "":
+            if data:
+                try:
+                    payload = json.loads("\n".join(data))
+                    if not isinstance(payload, dict):
+                        raise ValueError
+                except ValueError:
+                    raise CliError("SSE returned invalid event JSON.", 5) from None
+                yield name, payload
+            name, data, size = "message", [], 0
+        elif not line.startswith(":"):
+            field, separator, value = line.partition(":")
+            if value.startswith(" "):
+                value = value[1:]
+            if field == "event":
+                name = value
+            elif field == "data":
+                data.append(value if separator else "")
+    # Unterminated events are not dispatched; no fabricated terminal result.

opsai_cli/tasks.py

@@ -0,0 +1,177 @@
+"""Bounded task orchestration. Never cancel a remote task on local exit."""
+
+import math
+import time
+
+from opsai_cli.errors import CliError
+
+
+ACTIVE = {"pending", "running", "paused"}
+TERMINAL = {
+    "listing": {"completed", "failed", "cancelled"},
+    "activity": {"completed", "partial_failed", "failed", "cancelled"},
+    "optimization": {"succeeded", "failed", "cancelled"},
+}
+
+
+def finite_positive(value, name):
+    if not isinstance(value, (int, float)) or isinstance(value, bool) or not math.isfinite(value) or value <= 0:
+        raise CliError(f"{name} must be a finite positive number.")
+
+
+def validate_options(request_timeout, wait_timeout, poll_interval, max_retries):
+    finite_positive(request_timeout, "--request-timeout")
+    finite_positive(wait_timeout, "--wait-timeout")
+    finite_positive(poll_interval, "--poll-interval")
+    if poll_interval < 1:
+        raise CliError("--poll-interval must be at least 1 second.")
+    if type(max_retries) is not int or not 0 <= max_retries <= 10:
+        raise CliError("--max-retries must be between 0 and 10.")
+
+
+def task_data(envelope, expected_id=None):
+    data = envelope.get("data")
+    if (not isinstance(data, dict) or type(data.get("task_id")) is not int or data["task_id"] <= 0
+            or not isinstance(data.get("status"), str)
+            or (expected_id is not None and data["task_id"] != expected_id)):
+        raise CliError("API returned invalid task details.", 5)
+    return data
+
+
+def outcome(family, data):
+    if data["status"] in {"failed", "partial_failed", "cancelled"}:
+        return 1
+    if data.get("error") or data.get("error_message"):
+        return 1
+    if family == "listing":
+        items = data.get("items")
+        return 0 if isinstance(items, list) and items and all(isinstance(r, dict) and r.get("status") in {"PUBLISHED", "SUBMITTED"} for r in items) else 1
+    if family == "activity":
+        items = data.get("items")
+        return 0 if isinstance(items, list) and items and len(items) == data.get("total") and data.get("failed_count") == 0 and all(isinstance(r, dict) and r.get("status") == "success" for r in items) else 1
+    results = data.get("results")
+    return 0 if isinstance(results, list) and results and data.get("success_count") == data.get("total") == 1 and all(isinstance(r, dict) and r.get("success") is True for r in results) else 1
+
+
+class TaskSession:
+    def __init__(self, client, output, *, family, prefix, request_timeout=30,
+                 wait_timeout=1800, poll_interval=5, max_retries=2,
+                 waiting=False, clock=None, sleep=None):
+        validate_options(request_timeout, wait_timeout, poll_interval, max_retries)
+        self.client, self.output = client, output
+        self.family, self.prefix = family, prefix
+        self.clock, self.sleep = clock or time.monotonic, sleep or time.sleep
+        self.deadline = self.clock() + (wait_timeout if waiting else 120)
+        self.timeout_code = 6 if waiting else 5
+        self.request_timeout, self.interval, self.retries = request_timeout, poll_interval, max_retries
+        self.task_id = None
+        self.request_id = None
+
+    def remaining(self):
+        remaining = self.deadline - self.clock()
+        if remaining <= 0:
+            raise CliError("Local deadline expired; the server task may still be running.", self.timeout_code)
+        return remaining
+
+    def pause(self, seconds):
+        remaining = self.remaining()
+        if seconds >= remaining:
+            raise CliError("Local deadline would expire before the next permitted request; server work may continue.", self.timeout_code)
+        self.sleep(seconds)
+        self.remaining()
+
+    def retry_pause(self, error, attempt):
+        if not error.retryable or attempt >= self.retries:
+            raise error
+        delay = error.retry_after if error.retry_after is not None else min(2 ** attempt, 30)
+        if error.status == 429 and error.retry_after is None:
+            delay = 60
+        self.output.note(f"Transient API error; retry {attempt + 1}/{self.retries} after {delay:g}s.")
+        self.pause(delay)
+
+    def request(self, method, path, *, body=None, params=None, retry=True):
+        for attempt in range(self.retries + 1):
+            remaining = self.remaining()
+            try:
+                result = self.client.request_json(method, path, json=body, params=params,
+                                                 timeout=min(self.request_timeout, remaining))
+                self.remaining()
+                return result
+            except CliError as exc:
+                if not retry:
+                    raise
+                self.retry_pause(exc, attempt)
+
+    def accepted(self, data):
+        self.task_id = data["task_id"]
+        self.output.note(f"Task accepted: task_id={self.task_id}. Resume: opsai {self.family} task watch {self.task_id} (use the same --profile).")
+        self.output.event("accepted", data)
+
+    def watch(self):
+        while True:
+            envelope = self.request("GET", f"{self.prefix}/tasks/{self.task_id}")
+            data = task_data(envelope, self.task_id)
+            if data["status"] in TERMINAL[self.family]:
+                return envelope
+            if data["status"] not in ACTIVE:
+                self.output.note("Unknown task status; waiting until the configured deadline.")
+            self.output.event("status", data)
+            self.pause(self.interval)
+
+    def submit_stream(self, body):
+        # Reconnect/re-submit only while no accepted event has been received.
+        # The exact same normalized request body and request_id are reused.
+        for attempt in range(self.retries + 1):
+            try:
+                events = self.client.stream_events(self.prefix + "/tasks/stream", body,
+                    timeout=min(max(30, self.request_timeout), self.remaining()), check=self.remaining)
+                try:
+                    for name, data in events:
+                        self.remaining()
+                        if name == "accepted":
+                            details = task_data({"data": data}, self.task_id)
+                            self.accepted(details)
+                        elif name == "result":
+                            if self.task_id is None:
+                                raise CliError("SSE result arrived before task acceptance.", 5)
+                            details = task_data({"data": data}, self.task_id)
+                            if details["status"] not in TERMINAL[self.family]:
+                                raise CliError("SSE result was not a terminal task state.", 5)
+                            return {"code": 0, "message": "Task finished", "data": details}
+                        elif name == "error":
+                            raise CliError("SSE status reading failed.", 5)
+                        elif name == "log":
+                            self.output.event(name, data)
+                finally:
+                    events.close()
+                raise CliError("SSE ended without a final result.", 5, retryable=True)
+            except CliError as exc:
+                if exc.exit_code == 6:
+                    raise
+                if self.task_id is not None:
+                    self.output.note("SSE unavailable; switching to task polling. Logs may be incomplete.")
+                    return self.watch()
+                self.retry_pause(exc, attempt)
+
+    def stop(self):
+        for attempt in range(self.retries + 1):
+            try:
+                envelope = self.request("POST", f"{self.prefix}/tasks/{self.task_id}/stop", retry=False)
+            except CliError as exc:
+                if exc.status in {408, 425, 429}:
+                    self.retry_pause(exc, attempt)
+                    continue
+                if not exc.retryable or (exc.status is not None and exc.status < 500):
+                    raise
+                self.output.note("Stop response was not confirmed; querying task state without repeating the stop request.")
+                return self.watch()
+            data = task_data(envelope, self.task_id)
+            if data["status"] in TERMINAL[self.family]:
+                return envelope
+            return self.watch()
+
+    def recovery_note(self):
+        if self.task_id is not None:
+            self.output.note(f"Server work is not rolled back. Query: opsai {self.family} task get {self.task_id} (use the same --profile).")
+        elif self.request_id is not None:
+            self.output.note(f"Submission outcome may be unknown. Retry the original body with request_id={self.request_id}; do not generate a new request_id.")