@miraiva_test/miravia-order-report 0.1.13

package/dist/scripts/inject_insights.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Inject LLM-generated insights into an existing v4 HTML report (SKILL.md Step 5, MANDATORY).
+
+The built-in generate_insights() in report_v4.py only produces rule-engine placeholder summaries
+with no real business analysis value. This script overwrites the HTML with Agent/LLM-generated
+deep analysis, which is the mandatory step for delivering a complete report (see SKILL.md Core Rule #10).
+
+Usage:
+    python3 scripts/inject_insights.py \\
+        --html ./out/miravia_order_report_xxx.html \\
+        --insights ./out/insights.json
+
+The script locates the DATA declaration block in the HTML,
+parses it as JSON, replaces the `agentInsights` field from the insights
+file, and overwrites the HTML in-place.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def inject(html_path: Path, insights_path: Path) -> None:
+    """Inject insights JSON into HTML report's window.DATA object."""
+    html_text = html_path.read_text(encoding="utf-8")
+    insights_data = json.loads(insights_path.read_text(encoding="utf-8"))
+
+    # Locate DATA declaration block (supports const DATA / var DATA / window.DATA)
+    patterns = [
+        re.compile(r"(const\s+DATA\s*=\s*)(.*?)(;\s*\n)", re.DOTALL),
+        re.compile(r"(var\s+DATA\s*=\s*)(.*?)(;\s*\n)", re.DOTALL),
+        re.compile(r"(window\.DATA\s*=\s*)(.*?)(;\s*\n)", re.DOTALL),
+    ]
+    m = None
+    for pattern in patterns:
+        m = pattern.search(html_text)
+        if m:
+            break
+    if not m:
+        print("error: could not locate DATA declaration in HTML",
+              file=sys.stderr)
+        sys.exit(1)
+
+    # Parse existing DATA
+    data_str = m.group(2)
+    try:
+        data = json.loads(data_str)
+    except json.JSONDecodeError as e:
+        print(f"error: failed to parse window.DATA JSON: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Inject agentInsights
+    data["agentInsights"] = insights_data
+
+    # Rebuild the HTML
+    new_data_str = json.dumps(data, ensure_ascii=False, default=str)
+    new_html = (
+        html_text[:m.start()]
+        + m.group(1) + new_data_str + m.group(3)
+        + html_text[m.end():]
+    )
+
+    html_path.write_text(new_html, encoding="utf-8")
+    print(f"injected  : {html_path}")
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(
+        description="Inject Agent insights into v4 HTML report.")
+    p.add_argument("--html", required=True,
+                   help="Path to the generated HTML report file")
+    p.add_argument("--insights", required=True,
+                   help="Path to the Agent-generated insights JSON file")
+    args = p.parse_args()
+
+    html_path = Path(args.html).expanduser().resolve()
+    insights_path = Path(args.insights).expanduser().resolve()
+
+    if not html_path.exists():
+        print(f"error: HTML file not found: {html_path}", file=sys.stderr)
+        return 1
+    if not insights_path.exists():
+        print(f"error: insights file not found: {insights_path}",
+              file=sys.stderr)
+        return 1
+
+    inject(html_path, insights_path)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/dist/scripts/login.bat

@@ -0,0 +1,14 @@
+@echo off
+REM ──────────────────────────────────────────────────────────────────────
+REM login.bat — Windows CMD wrapper for auth_cli.py login
+REM
+REM Purpose: Bypass PowerShell Constrained Language Mode that blocks
+REM .NET method calls (System.Convert, System.Text.Encoding) in
+REM enterprise-managed Windows environments.
+REM
+REM Usage:  scripts\login.bat [any auth_cli.py login arguments]
+REM Example: scripts\login.bat --port 8765 --timeout 300
+REM ──────────────────────────────────────────────────────────────────────
+
+cd /d "%~dp0.."
+python scripts/auth_cli.py login %*

package/dist/scripts/miravia_client.py

@@ -0,0 +1,468 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Miravia Open API Client
+- HMAC-SHA256 signature
+- Auto-pagination
+- Three-endpoint aggregation: /orders/get, /orders/items/get, /reverse/getreverseordersforseller
+
+v0.2 Changes:
+  - Removed Miravia official OAuth (auth.miravia.com) build_authorize_url /
+    exchange_token / refresh_token trio; appKey/appSecret/accessToken
+    are exclusively sourced from the Skill Hub authorization page.
+  - Raises CredentialMissingError on initialization if credentials are empty.
+"""
+
+import hmac
+import hashlib
+import json
+import time
+import random
+import sys
+import logging
+from typing import Any, Dict, Iterable, List, Optional
+from urllib.parse import urlencode
+
+import requests
+
+import config
+from skill_logger import api_tracker, SKILL_NAME, get_agent_type, detect_model_name
+from trace_logger import record_trace
+
+
+logger = logging.getLogger("miravia.client")
+
+
+# ------------- Signature -------------
+
+def generate_sign(api_path: str, params: Dict[str, Any], app_secret: str) -> str:
+    """Generate HMAC-SHA256 uppercase signature per Miravia specification."""
+    filtered = {k: v for k, v in params.items()
+                if v is not None and v != "" and k != "sign"}
+    sorted_keys = sorted(filtered.keys())
+    concat = api_path + "".join(f"{k}{filtered[k]}" for k in sorted_keys)
+    return hmac.new(
+        app_secret.encode("utf-8"),
+        concat.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest().upper()
+
+
+# ------------- HTTP -------------
+
+class MiraviaError(RuntimeError):
+    def __init__(self, code: str, msg: str, payload: Any = None):
+        super().__init__(f"[{code}] {msg}")
+        self.code = code
+        self.msg = msg
+        self.payload = payload
+
+
+# Business error codes that should trigger retry (Core Rule #9: retry 3 times on failure)
+_RETRYABLE_ERROR_CODES = {
+    "RateLimit",           # API rate limiting
+    "ServiceUnavailable",  # Temporary service unavailability
+    "SYSTEM_ERROR",        # Transient server errors
+    "GatewayTimeout",      # Gateway timeout
+    "TOO_MANY_REQUESTS",   # HTTP 429 equivalent
+}
+
+
+class MiraviaClient:
+    def __init__(self,
+                 app_key: Optional[str] = None,
+                 app_secret: Optional[str] = None,
+                 access_token: Optional[str] = None,
+                 api_base: str = config.API_BASE,
+                 action: str = "auto"):
+        # Allow caller to pass explicitly (e.g., unit tests); otherwise read from config.
+        # Business requests are gated by require_business_credentials().
+        self.app_key = app_key if app_key is not None else config.APP_KEY
+        self.app_secret = app_secret if app_secret is not None else config.APP_SECRET
+        self.access_token = access_token if access_token is not None else config.ACCESS_TOKEN
+        self.api_base = api_base.rstrip("/")
+        self.action = action
+        self.session = requests.Session()
+
+    # --- low level ---
+
+    def _common_params(self) -> Dict[str, str]:
+        """Build common parameters for all API requests.
+
+        Includes Miravia gateway-required signing params + 4 Skill Hub passthrough tracking params:
+          - skill_name  : Skill identifier (fixed: miravia_order_reports)
+          - action      : Current invocation scenario/action (export / refund / business / inspect / ping)
+          - agent_type  : Agent/IDE type (qoder / cursor / claude ...)
+          - model_name  : Agent's LLM model name (may be empty)
+        These 4 params are included in every request to /orders/get, /orders/items/get,
+        /reverse/getreverseordersforseller and participate in HMAC-SHA256 signing.
+        """
+        params = {
+            "app_key": self.app_key,
+            "access_token": self.access_token,
+            "sign_method": config.SIGN_METHOD,
+            "timestamp": str(int(time.time() * 1000)),
+            "skill_name": SKILL_NAME,
+            "action": self.action,
+            "agent_type": get_agent_type(),
+        }
+        # model_name may be empty (undetectable); omit empty values to keep signature consistent
+        model = detect_model_name()
+        if model:
+            params["model_name"] = model
+        return params
+
+    def _request(self, method: str, api_path: str,
+                 params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        config.require_business_credentials()
+        params = {k: v for k, v in (params or {}).items() if v is not None and v != ""}
+        params.update(self._common_params())
+        params["sign"] = generate_sign(api_path, params, self.app_secret)
+
+        url = f"{self.api_base}{api_path}"
+        last_exc: Optional[Exception] = None
+        for attempt in range(1, config.HTTP_RETRY + 1):
+            try:
+                if method.upper() == "GET":
+                    resp = self.session.get(
+                        url + "?" + urlencode(params),
+                        timeout=config.HTTP_TIMEOUT,
+                    )
+                else:
+                    resp = self.session.post(
+                        url, data=params, timeout=config.HTTP_TIMEOUT,
+                        headers={"Content-Type": "application/x-www-form-urlencoded"},
+                    )
+                resp.raise_for_status()
+                body = resp.json()
+                # Extract traceId from response body (_trace_id_) or header (EagleEye-TraceId)
+                trace_id = (body.get("_trace_id_")
+                            or resp.headers.get("EagleEye-TraceId")
+                            or "")
+                code = str(body.get("code", "0"))
+                if code != "0":
+                    # Retryable business error codes (rate limit, service unavailable)
+                    if code in _RETRYABLE_ERROR_CODES and attempt < config.HTTP_RETRY:
+                        api_tracker.record(api_path, success=False)
+                        record_trace(api_path, trace_id, success=False, params=params)
+                        sleep_s = min(2 ** attempt, 30) * (0.5 + random.random())
+                        logger.warning(
+                            "API %s %s attempt=%d retryable code=%s, sleeping %.1fs",
+                            method, api_path, attempt, code, sleep_s,
+                        )
+                        time.sleep(sleep_s)
+                        continue
+                    api_tracker.record(api_path, success=False)
+                    record_trace(api_path, trace_id, success=False, params=params)
+                    raise MiraviaError(code, body.get("message", ""), body)
+                api_tracker.record(api_path, success=True)
+                record_trace(api_path, trace_id, success=True, params=params)
+                return body
+            except (requests.RequestException, ValueError) as e:
+                last_exc = e
+                logger.warning("HTTP %s %s attempt=%d err=%s", method, api_path, attempt, e)
+                # Exponential backoff with jitter
+                time.sleep(min(2 ** attempt, 30) * (0.5 + random.random()))
+        api_tracker.record(api_path, success=False)
+        record_trace(api_path, None, success=False, params=params)
+        assert last_exc is not None
+        raise MiraviaError("HTTP_FAIL", str(last_exc))
+
+    # --- skill upgrade check ---
+
+    def check_skill_upgrade(self, current_version: Optional[str] = None,
+                            skill_code: Optional[str] = None) -> Dict[str, Any]:
+        """Check if a newer skill version is available on the server.
+
+        Calls /order/skill/check/upgrade and returns the response data.
+        Returns dict with keys:
+          - need_upgrade: 1 if upgrade available, 0 otherwise
+          - latest_skill: dict with version, package_url, npx_command, etc.
+
+        Non-blocking: caller should catch exceptions and degrade gracefully.
+        """
+        params = {
+            "skill_code": skill_code or config.DEFAULT_SKILL_CODE,
+            "current_version": current_version or config.SKILL_VERSION,
+        }
+        return self._request("GET", "/order/skill/check/upgrade", params).get("data", {})
+
+    # --- ping ---
+
+    def ping(self) -> Dict[str, Any]:
+        """Lightweight health check: calls /seller/get (cheapest endpoint)."""
+        return self._request("GET", "/seller/get")
+
+    # --- orders ---
+
+    # /orders/get gateway limit: offset + limit must not exceed ORDERS_PER_WINDOW.
+    # Testing shows API returns empty data at offset >= ORDERS_PER_WINDOW (inflated countTotal issue).
+    ORDERS_GET_OFFSET_LIMIT_CAP = config.ORDERS_PER_WINDOW
+
+    def get_orders_page(self, created_after: str, created_before: str,
+                         status: Optional[str] = None,
+                         limit: int = config.PAGE_SIZE,
+                         offset: int = 0,
+                         channel: Optional[str] = None,
+                         ship_to: Optional[str] = None,
+                         order_numbers: Optional[str] = None) -> Dict[str, Any]:
+        """Fetch a single page of orders from /orders/get.
+
+        Args:
+            status: API status value (e.g. 'ready_to_ship', 'shipped', 'all_to_ship').
+            channel: Channel filter - maps to API 'marketplace' param. Values: 'AE' (→'ae') or 'Miravia'.
+            ship_to: Receiving country filter - maps to API 'country' param ('ES', 'PT').
+            order_numbers: Comma-separated order numbers (e.g. '12345,67890').
+        """
+        # Note: official docs misspell the param as `limt`; the gateway actually accepts `limit`.
+        params: Dict[str, Any] = {
+            "created_after": created_after,
+            "created_before": created_before,
+            "limit": limit,
+            "offset": offset,
+        }
+        if status and status != "all":
+            params["status"] = status  # e.g. "pending" / "ready_to_ship" / "shipped"
+        if channel:
+            # API actual param name is 'marketplace'; values are lowercase 'ae' or 'Miravia'
+            params["marketplace"] = channel.lower() if channel.upper() == "AE" else channel
+        if ship_to:
+            params["country"] = ship_to
+        if order_numbers:
+            params["orderNumbers"] = order_numbers
+        return self._request("GET", "/orders/get", params)["data"]
+
+    def iter_orders(self, created_after: str, created_before: str,
+                    status: Optional[str] = None,
+                    max_orders: int = config.DEFAULT_MAX_ORDERS,
+                    quiet: bool = False,
+                    channel: Optional[str] = None,
+                    ship_to: Optional[str] = None,
+                    order_numbers: Optional[str] = None) -> Iterable[Dict[str, Any]]:
+        """Fetch order list with auto-pagination.
+
+        Args:
+          - max_orders: Maximum number of orders to return per invocation.
+          - quiet: If True, suppress progress output (used in internal auto-slicing calls).
+          - channel: Channel filter ('AE' for M2A, 'Miravia').
+          - ship_to: Destination country filter ('ES', 'PT', 'IT').
+          - order_numbers: Comma-separated order numbers.
+
+        Pagination formula: offset = (pageNum - 1) * limit
+          - Page 1 offset=0, Page 2 offset=100, Page 3 offset=200 ...
+          - offset must be an integer multiple of limit; otherwise the API returns misaligned data.
+          - Server hard limit: offset + limit <= 10000; split time window if exceeded.
+        """
+        page_size = config.PAGE_SIZE
+        page_num = 1
+        fetched = 0
+        total = None
+        while True:
+            offset = (page_num - 1) * page_size
+            # Server hard limit: offset + limit <= 10000. Exit early to avoid gateway error.
+            if offset + page_size > self.ORDERS_GET_OFFSET_LIMIT_CAP:
+                if not quiet:
+                    print(
+                        f"progress: current window exceeds single-query limit, auto-splitting time range",
+                        flush=True,
+                    )
+                return
+            data = self.get_orders_page(created_after, created_before,
+                                         status=status,
+                                         limit=page_size,
+                                         offset=offset,
+                                         channel=channel,
+                                         ship_to=ship_to,
+                                         order_numbers=order_numbers)
+            orders = data.get("orders", []) or []
+            if total is None:
+                total = int(data.get("countTotal", len(orders)))
+                if not quiet:
+                    print(f"progress: window has data, fetching...", flush=True)
+            if not orders:
+                return
+            for o in orders:
+                yield o
+                fetched += 1
+                if fetched >= max_orders:
+                    return
+            if not quiet:
+                print(f"progress: fetched {fetched} orders", flush=True)
+            # Page not full or reached total — no more data
+            if len(orders) < page_size or fetched >= total:
+                return
+            page_num += 1
+
+    # --- order items ---
+
+    def get_multi_order_items(self, order_ids: List[Any],
+                             concurrent: bool = False) -> List[Dict[str, Any]]:
+        """/orders/items/get supports batch queries; here we call in batches of 50.
+
+        When concurrent=True, uses thread pool to fetch batches concurrently.
+        """
+        if not order_ids:
+            return []
+        BATCH = 50
+        batches = [order_ids[i:i + BATCH] for i in range(0, len(order_ids), BATCH)]
+
+        def _fetch_batch(batch: List[Any]) -> List[Dict[str, Any]]:
+            ids_str = "[" + ",".join(str(x) for x in batch) + "]"
+            data = self._request("GET", "/orders/items/get",
+                                  {"order_ids": ids_str})["data"]
+            if isinstance(data, list):
+                return data
+            elif isinstance(data, dict) and "orders" in data:
+                return data["orders"]
+            return []
+
+        if not concurrent or len(batches) <= 3:
+            # Serial mode
+            out: List[Dict[str, Any]] = []
+            for batch in batches:
+                out.extend(_fetch_batch(batch))
+            return out
+
+        # Concurrent mode
+        from concurrent.futures import ThreadPoolExecutor, as_completed
+        out: List[Dict[str, Any]] = []
+        with ThreadPoolExecutor(max_workers=config.CONCURRENT_WORKERS) as pool:
+            futures = [pool.submit(_fetch_batch, b) for b in batches]
+            for future in as_completed(futures):
+                try:
+                    out.extend(future.result())
+                except Exception as e:
+                    logger.warning("items batch failed: %s", e)
+        return out
+
+    # --- reverse ---
+
+    def get_reverse_orders(self,
+                           created_after_ms: Optional[int] = None,
+                           created_before_ms: Optional[int] = None,
+                           reverse_status_list: Optional[List[str]] = None,
+                           page_size: int = 100,
+                           max_pages: int = 30,
+                           # Below are single-record filter params per official docs. See reference.md "Reverse Order Full API".
+                           trade_order_id: Optional[Any] = None,
+                           reverse_order_id: Optional[Any] = None,
+                           reverse_tracking_number: Optional[str] = None,
+                           ofc_status_list: Optional[List[str]] = None,
+                           dispute_in_progress: Optional[bool] = None,
+                           marketplace: Optional[str] = None,
+                           reverse_line_after_ms: Optional[int] = None,
+                           reverse_line_before_ms: Optional[int] = None,
+                           ) -> List[Dict[str, Any]]:
+        """Fetch reverse orders via /reverse/getreverseordersforseller.
+
+        Official docs full params (1 required pagination + 11 optional filters):
+          - page_size / page_no (required)
+          - trade_order_id / reverse_order_id / reverse_tracking_number (single-record filters)
+          - trade_order_time_range_start/end_time_stamp (main order creation time window, ms)
+          - reverse_order_line_time_range_start/end_time_stamp (reverse line creation time window)
+          - reverse_status_list / ofc_status_list (JSON array strings)
+          - dispute_in_progress / marketplace
+
+        Pitfalls:
+          - Param names `start_create_time` / `end_create_time` / singular `status` do not exist;
+            they are silently discarded by the server and return all data. Do not use.
+          - Server has a deep-page limit at `page_no >= ~31` (offset > 3000); this function
+            uses `max_pages` to cap, avoiding SYSTEM_ERROR; split time window to re-fetch if total exceeds limit.
+          - Single-order scenarios (with trade_order_id / reverse_order_id) typically don't need
+            a time window; this function skips the "no time window" guard error for those.
+        """
+        # Safety check: require at least one filter dimension to avoid pulling all data.
+        single_filter = (trade_order_id is not None
+                         or reverse_order_id is not None
+                         or reverse_tracking_number)
+        time_window = (created_after_ms is not None and created_before_ms is not None) or \
+                      (reverse_line_after_ms is not None and reverse_line_before_ms is not None)
+        if not single_filter and not time_window:
+            raise ValueError(
+                "get_reverse_orders requires at least one filter: "
+                "trade_order_id / reverse_order_id / reverse_tracking_number, "
+                "or a time window (created_after_ms+created_before_ms)."
+            )
+
+        out: List[Dict[str, Any]] = []
+        seen: set = set()
+        page = 1
+        total: Optional[int] = None
+        while page <= max_pages:
+            params: Dict[str, Any] = {
+                "page_size": page_size,
+                "page_no": page,
+            }
+            if created_after_ms is not None:
+                params["trade_order_time_range_start_time_stamp"] = created_after_ms
+            if created_before_ms is not None:
+                params["trade_order_time_range_end_time_stamp"] = created_before_ms
+            if reverse_line_after_ms is not None:
+                params["reverse_order_line_time_range_start_time_stamp"] = reverse_line_after_ms
+            if reverse_line_before_ms is not None:
+                params["reverse_order_line_time_range_end_time_stamp"] = reverse_line_before_ms
+            if trade_order_id is not None:
+                params["trade_order_id"] = trade_order_id
+            if reverse_order_id is not None:
+                params["reverse_order_id"] = reverse_order_id
+            if reverse_tracking_number:
+                params["reverse_tracking_number"] = reverse_tracking_number
+            if reverse_status_list:
+                # Docs show passing as JSON array string
+                params["reverse_status_list"] = json.dumps(reverse_status_list)
+            if ofc_status_list:
+                params["ofc_status_list"] = json.dumps(ofc_status_list)
+            if dispute_in_progress is not None:
+                # API expects string 'true' / 'false'
+                params["dispute_in_progress"] = "true" if dispute_in_progress else "false"
+            if marketplace:
+                params["marketplace"] = marketplace
+            try:
+                data = self._request("GET",
+                                     "/reverse/getreverseordersforseller",
+                                     params)["data"] or {}
+            except MiraviaError as e:
+                # Graceful degradation: log warning and return data fetched so far
+                logger.warning("reverse page=%d failed: %s", page, e)
+                break
+            items = data.get("items") or []
+            if total is None:
+                total = int(data.get("total") or 0)
+                logger.info("reverse total=%d (filters=%s)",
+                            total,
+                            {k: v for k, v in params.items()
+                             if k not in ("page_size", "page_no")})
+            for r in items:
+                rid = (r.get("reverse_order_id") or r.get("dispute_id")
+                       or id(r))
+                if rid in seen:
+                    continue
+                seen.add(rid)
+                out.append(r)
+            if not items or len(items) < page_size or len(out) >= (total or 0):
+                break
+            page += 1
+        if total is not None and total > max_pages * page_size:
+            logger.warning(
+                "reverse total=%d exceeds max_pages*page_size=%d; "
+                "caller should narrow the time window and retry.",
+                total, max_pages * page_size)
+        return out
+
+
+# ------------- CLI for ad-hoc use -------------
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
+    try:
+        config.require_business_credentials()
+    except config.CredentialMissingError as e:
+        print(str(e), file=sys.stderr)
+        sys.exit(1)
+    cli = MiraviaClient()
+    try:
+        cli.ping()
+        print("ping OK")
+    except MiraviaError as e:
+        print(f"ping FAIL: {e}", file=sys.stderr)
+        sys.exit(1)