@miraiva_test/miravia-order-report 0.1.13

package/dist/scripts/config.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Miravia Order Report - Configuration
+
+Important convention (since v0.2):
+    appKey / appSecret / accessToken NO LONGER have any built-in mock defaults.
+    The only way to obtain credentials:
+        1) Start a local callback service: python auth_cli.py login
+        2) Browser redirects to staging authorization page:
+           https://pre-sellercenter.miravia.es/apps/seller/skill/auth
+        3) After seller completes authorization, frontend sends encryptedPayload
+           back to local callback via redirect_uri.
+        4) CLI uses private key from .keypair.json for segmented RSA decryption,
+           writes to credentials.json.
+
+    All callers (including MiraviaClient) must complete the above authorization
+    first, otherwise an error is raised.
+"""
+
+import json
+import os
+
+_SKILL_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+
+# Local credentials file (used only by this Skill; .qoder/skills/ is in .gitignore)
+# Path: <repo>/.qoder/skills/miravia-order-report/credentials.json
+CRED_FILE = os.getenv(
+    "MIRAVIA_CRED_FILE",
+    os.path.join(_SKILL_DIR, "credentials.json"),
+)
+
+# Local RSA keypair file (private key generated by backend generateKeyPair, manually saved)
+# Path: <repo>/.qoder/skills/miravia-order-report/.keypair.json
+KEYPAIR_FILE = os.getenv(
+    "MIRAVIA_KEYPAIR_FILE",
+    os.path.join(_SKILL_DIR, ".keypair.json"),
+)
+
+
+# JSON field name to environment variable mapping (credentials.json uses snake_case short names)
+_JSON_KEY_MAP = {
+    "MIRAVIA_APP_KEY": "app_key",
+    "MIRAVIA_APP_SECRET": "app_secret",
+    "MIRAVIA_ACCESS_TOKEN": "access_token",
+    "MIRAVIA_TOKEN_EXPIRES_AT": "token_expires_at",
+    "MIRAVIA_LAST_LOGIN_AT": "last_login_at",
+}
+
+_SENSITIVE_JSON_KEYS = ("app_key", "app_secret", "access_token")
+
+
+def _maybe_decrypt(json_key: str, value: str) -> str:
+    """Decrypt if this is a sensitive field with ``enc:v1:`` prefix.
+
+    If a sensitive field is plaintext, return empty string (treated as invalid),
+    letting require_business_credentials() prompt re-authorization later.
+    """
+    if json_key not in _SENSITIVE_JSON_KEYS:
+        return value
+    if not value:
+        return ""
+    if not isinstance(value, str) or not value.startswith("enc:"):
+        # Plaintext credentials are no longer accepted, treated as invalid
+        return ""
+    try:
+        from cred_crypto import decrypt_value, CredCryptoError
+    except ImportError:
+        return ""
+    try:
+        return decrypt_value(value)
+    except CredCryptoError:
+        return ""
+
+
+def _read_cred_json(key: str) -> str:
+    """Read a key from credentials.json at import time (auto-decrypts)."""
+    if not os.path.exists(CRED_FILE):
+        return ""
+    json_key = _JSON_KEY_MAP.get(key)
+    if not json_key:
+        return ""
+    try:
+        with open(CRED_FILE, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        raw = data.get(json_key, "")
+        if raw is None:
+            return ""
+        return _maybe_decrypt(json_key, str(raw))
+    except (OSError, json.JSONDecodeError):
+        pass
+    return ""
+
+
+def _resolve(key: str) -> str:
+    """Unified credential lookup order: env var > credentials.json > empty string."""
+    return os.getenv(key) or _read_cred_json(key) or ""
+
+
+# Business credentials (NEVER write default values); if empty at runtime, caller raises error and prompts authorization.
+APP_KEY = _resolve("MIRAVIA_APP_KEY")
+APP_SECRET = _resolve("MIRAVIA_APP_SECRET")
+ACCESS_TOKEN = _resolve("MIRAVIA_ACCESS_TOKEN")
+
+API_BASE = os.getenv("MIRAVIA_API_BASE", "https://pre-api.miravia.es/rest")
+SIGN_METHOD = "sha256"
+
+# Skill Hub authorization page (frontend page, POST /skill/auth is handled internally)
+# Staging: https://pre-sellercenter.miravia.es/apps/seller/skill/auth
+# Production: https://sellercenter.miravia.es/apps/seller/skill/auth
+SKILL_HUB_AUTH_URL = os.getenv(
+    "MIRAVIA_SKILL_HUB_AUTH_URL",
+    "https://pre-sellercenter.miravia.es/apps/seller/skill/auth",
+)
+
+# Current skill version — single source of truth: npm-package/package.json
+# At runtime, reads VERSION file (stamped by build-dist.js during npm publish).
+# Falls back to npm-package/package.json for local development in the source repo.
+def _read_version_from_package_json() -> str:
+    """Read version: VERSION file (installed) > npm-package/package.json (dev) > fallback."""
+    # 1. VERSION file — exists on user machines after npm install/upgrade
+    version_file = os.path.join(_SKILL_DIR, "VERSION")
+    try:
+        with open(version_file, "r", encoding="utf-8") as f:
+            v = f.read().strip()
+            if v:
+                return v
+    except OSError:
+        pass
+    # 2. npm-package/package.json — exists in source repo during development
+    pkg_path = os.path.join(_SKILL_DIR, "npm-package", "package.json")
+    try:
+        with open(pkg_path, "r", encoding="utf-8") as f:
+            return json.load(f).get("version", "0.0.0")
+    except (OSError, json.JSONDecodeError):
+        pass
+    return "0.0.0"
+
+SKILL_VERSION = _read_version_from_package_json()
+
+# Default skill_code: env var > .keypair.json > empty.
+# Falls back to .keypair.json to support out-of-the-box version check without extra config.
+def _read_skill_code_from_keypair() -> str:
+    """Read skill_code from .keypair.json as fallback."""
+    try:
+        kp_path = os.path.join(_SKILL_DIR, ".keypair.json")
+        if os.path.exists(kp_path):
+            with open(kp_path, "r", encoding="utf-8") as f:
+                return json.load(f).get("skill_code", "")
+    except (OSError, json.JSONDecodeError):
+        pass
+    return ""
+
+
+DEFAULT_SKILL_CODE = os.getenv("MIRAVIA_SKILL_CODE", "") or _read_skill_code_from_keypair()
+
+# /orders/get page size limit (API max 100)
+PAGE_SIZE = 100
+
+# Max sub-orders per query (cap 200000; exceeding prompts user to split into multiple queries)
+DEFAULT_MAX_ORDERS = 200000
+
+# Max main orders per time window (exceeding this triggers auto time-window splitting)
+# Although officially offset+limit <= 10000, testing shows API returns empty data at offset>=5000
+# (inflated countTotal issue), so safe cap is set to 5000.
+ORDERS_PER_WINDOW = 5000
+
+# Network timeout and retry
+HTTP_TIMEOUT = 30
+HTTP_RETRY = 3
+
+# Concurrent worker threads (for parallel time-window fetching)
+# Set to 10 balancing platform QPS limits and performance; override via MIRAVIA_CONCURRENT_WORKERS.
+CONCURRENT_WORKERS = int(os.getenv("MIRAVIA_CONCURRENT_WORKERS", "10"))
+
+# Concurrency trigger threshold: enable concurrent fetching when main orders exceed this value
+CONCURRENT_THRESHOLD = int(os.getenv("MIRAVIA_CONCURRENT_THRESHOLD", "1000"))
+
+# Adaptive degradation threshold: when weekly window orders exceed this, auto-fallback to daily splitting.
+# Set to 1.2x ORDERS_PER_WINDOW to prevent silent data loss in the 5001~49999 range
+# (iter_orders truncates at ORDERS_PER_WINDOW due to API offset>=5000 empty-data issue).
+ADAPTIVE_DEGRADE_THRESHOLD = int(os.getenv("MIRAVIA_ADAPTIVE_DEGRADE_THRESHOLD", str(int(ORDERS_PER_WINDOW * 1.2))))
+
+# Default timezone: Spain +02:00 (summer CEST); for winter time set MIRAVIA_TZ_OFFSET=+01:00.
+DEFAULT_TZ_OFFSET = os.getenv("MIRAVIA_TZ_OFFSET", "+02:00")
+
+
+class CredentialMissingError(RuntimeError):
+    """Business credentials missing (not authorized or credentials.json is corrupted)."""
+
+
+def require_business_credentials() -> None:
+    """Pre-call validation: APP_KEY / APP_SECRET / ACCESS_TOKEN must all be present."""
+    missing = []
+    for k, v in (
+        ("MIRAVIA_APP_KEY", APP_KEY),
+        ("MIRAVIA_APP_SECRET", APP_SECRET),
+        ("MIRAVIA_ACCESS_TOKEN", ACCESS_TOKEN),
+    ):
+        if not v:
+            missing.append(k)
+    if missing:
+        raise CredentialMissingError(
+            "missing Miravia credentials: " + ", ".join(missing) + ".\n"
+            "Please run authorization in the skill root directory:\n"
+            "  python scripts/auth_cli.py login\n"
+            f"Credentials file: {CRED_FILE}\n"
+            f"Authorization URL: {SKILL_HUB_AUTH_URL}"
+        )
+
+
+def mask_token(token: str) -> str:
+    if not token:
+        return "<empty>"
+    if len(token) <= 8:
+        return "***"
+    return f"***{token[-6:]}"

package/dist/scripts/cred_crypto.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Local credential encryption (satisfies PRD §4.5.a: App Token stored encrypted, never plaintext).
+
+Design highlights:
+- AES-256-GCM symmetric encryption with independent 12-byte nonce per value.
+- Encryption key derived via HKDF-SHA256 from .keypair.json private key PEM + skill_code
+  + machine fingerprint (hostname + OS username).
+  Benefits: (1) Even if all sellers share the same .keypair.json (skill packaged distribution),
+        different machines derive different keys, so attackers cannot decrypt credentials.json
+        + .keypair.json on another machine; (2) No system keychain dependency, cross-platform;
+        (3) Credentials auto-expire on machine change/hostname change (reasonable security behavior,
+        user must re-run auth_cli.py login).
+- Output format: ``enc:v1:<base64url(nonce || ciphertext || tag)>``.
+- Sensitive fields managed centrally (``SENSITIVE_KEYS``); other fields remain plaintext for status display.
+
+Both read/write sides use this module's encrypt_value / decrypt_value; callers need not
+know KDF details. If .keypair.json is missing, this module degrades to "no encryption";
+the upper layer decides whether to refuse (default: refuse writing new credentials,
+but allow reading historical plaintext for backward compatibility).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+from typing import Optional, Tuple
+
+# Encryption marker prefix; can upgrade to ``enc:v2:`` if algorithm changes in the future.
+ENC_PREFIX = "enc:v1:"
+
+# Fields that require encrypted persistence. Other fields (expiry time, login time, etc.)
+# remain plaintext for ``auth_cli.py status`` display and to avoid treating metadata as secrets.
+SENSITIVE_KEYS = (
+    "MIRAVIA_APP_KEY",
+    "MIRAVIA_APP_SECRET",
+    "MIRAVIA_ACCESS_TOKEN",
+)
+
+
+class CredCryptoError(RuntimeError):
+    """Credential encryption/decryption error (missing .keypair.json, corrupted ciphertext, key mismatch, etc.)."""
+
+
+def _machine_fingerprint() -> bytes:
+    """Generate machine fingerprint: hostname + OS username.
+
+    Purpose: Even if all sellers share the same .keypair.json (skill packaged distribution),
+    different machines derive different AES keys. An attacker with only .keypair.json +
+    credentials.json ciphertext cannot decrypt on their own machine.
+
+    Note: Credentials expire after machine change/hostname change/user change;
+    user must re-run auth_cli.py login.
+    """
+    import getpass
+    import socket
+
+    hostname = socket.gethostname() or "unknown-host"
+    username = getpass.getuser() or "unknown-user"
+    return f"{hostname}|{username}".encode("utf-8")
+
+
+def _load_aesgcm_key(keypair_path: Optional[str] = None) -> bytes:
+    """Derive 32-byte AES-256-GCM key from .keypair.json + machine fingerprint.
+
+    KDF: HKDF-SHA256
+      IKM  = SHA256(private_key_pem || "|" || skill_code || "|" || machine_fingerprint)
+      salt = "miravia-skill-cred-v2"
+      info = "aes-256-gcm"
+
+    v2 change: Added machine_fingerprint to bind key to specific machine,
+    solving the "just copy credentials.json to decrypt" problem in shared private key scenarios.
+    """
+    import config  # Lazy import to avoid circular dependency
+
+    path = keypair_path or config.KEYPAIR_FILE
+    if not os.path.exists(path):
+        raise CredCryptoError(
+            f"Missing .keypair.json (path: {path}), cannot derive encryption key.\n"
+            f"Please persist the Skill Hub-issued private key + skill_code to this file first."
+        )
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            raw = json.load(f)
+    except (OSError, json.JSONDecodeError) as e:
+        raise CredCryptoError(f".keypair.json read failed: {e}") from e
+
+    skill_code = (raw.get("skill_code") or "").strip()
+    private_key = (raw.get("private_key") or "").strip()
+    if not skill_code or not private_key:
+        raise CredCryptoError(".keypair.json missing skill_code or private_key")
+
+    fingerprint = _machine_fingerprint()
+    ikm = hashlib.sha256(
+        private_key.encode("utf-8") + b"|" + skill_code.encode("utf-8") + b"|" + fingerprint
+    ).digest()
+    return _hkdf_sha256(ikm, salt=b"miravia-skill-cred-v2", info=b"aes-256-gcm", length=32)
+
+
+def _hkdf_sha256(ikm: bytes, salt: bytes, info: bytes, length: int) -> bytes:
+    """HKDF-SHA256 (RFC 5869), pure standard library implementation."""
+    import hmac
+
+    if not salt:
+        salt = b"\x00" * hashlib.sha256().digest_size
+    prk = hmac.new(salt, ikm, hashlib.sha256).digest()
+
+    out = b""
+    t = b""
+    counter = 1
+    while len(out) < length:
+        t = hmac.new(prk, t + info + bytes([counter]), hashlib.sha256).digest()
+        out += t
+        counter += 1
+    return out[:length]
+
+
+def _b64url_encode(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _b64url_decode(s: str) -> bytes:
+    pad = "=" * (-len(s) % 4)
+    return base64.urlsafe_b64decode(s + pad)
+
+
+def is_encrypted(value: str) -> bool:
+    return isinstance(value, str) and value.startswith(ENC_PREFIX)
+
+
+def encrypt_value(plaintext: str, key: Optional[bytes] = None) -> str:
+    """Encrypt a single field value, returns ``enc:v1:<...>`` string. Empty/None returns empty string."""
+    if plaintext is None or plaintext == "":
+        return ""
+    try:
+        from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+    except ImportError as e:  # pragma: no cover
+        raise CredCryptoError(
+            "Missing cryptography dependency. Run: pip install -r requirements.txt"
+        ) from e
+
+    if key is None:
+        key = _load_aesgcm_key()
+    nonce = os.urandom(12)
+    ct = AESGCM(key).encrypt(nonce, plaintext.encode("utf-8"), associated_data=None)
+    blob = nonce + ct  # AESGCM appends 16-byte tag to ct
+    return ENC_PREFIX + _b64url_encode(blob)
+
+
+def decrypt_value(value: str, key: Optional[bytes] = None) -> str:
+    """Decrypt a single field. If non-empty and not prefixed with ``enc:v1:``, treat as plaintext residue and raise error requiring re-authorization."""
+    if value is None or value == "":
+        return ""
+    if not is_encrypted(value):
+        raise CredCryptoError(
+            f"Detected plaintext credentials (unencrypted). Please re-run auth_cli.py login to encrypt."
+        )
+    try:
+        from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+    except ImportError as e:  # pragma: no cover
+        raise CredCryptoError(
+            "Missing cryptography dependency. Run: pip install -r requirements.txt"
+        ) from e
+
+    if key is None:
+        key = _load_aesgcm_key()
+    try:
+        blob = _b64url_decode(value[len(ENC_PREFIX):])
+    except (ValueError, base64.binascii.Error) as e:
+        raise CredCryptoError(f"Ciphertext base64 decode failed: {e}") from e
+    if len(blob) < 12 + 16:
+        raise CredCryptoError("Ciphertext length abnormal (< nonce+tag)")
+    nonce, ct = blob[:12], blob[12:]
+    try:
+        return AESGCM(key).decrypt(nonce, ct, associated_data=None).decode("utf-8")
+    except Exception as e:  # InvalidTag etc.
+        raise CredCryptoError(
+            f"AES-GCM decryption failed: {e.__class__.__name__}; "
+            f"Possible causes: (1) Machine/hostname/OS user changed (key is bound to machine fingerprint); "
+            f"(2) .keypair.json was replaced; (3) credentials.json is corrupted. "
+            f"Please re-run auth_cli.py login to re-authorize."
+        ) from e
+
+
+def encrypt_creds(creds: dict, key: Optional[bytes] = None) -> dict:
+    """Batch-encrypt sensitive fields in a credentials dict; other fields pass through unchanged."""
+    if key is None:
+        key = _load_aesgcm_key()
+    out = dict(creds)
+    for k in SENSITIVE_KEYS:
+        v = out.get(k, "")
+        if v and not is_encrypted(v):
+            out[k] = encrypt_value(v, key=key)
+    return out
+
+
+def decrypt_creds(creds: dict, key: Optional[bytes] = None) -> dict:
+    """Batch-decrypt sensitive fields in a credentials dict; non-sensitive fields pass through unchanged.
+
+    If a sensitive field is plaintext (no ``enc:v1:`` prefix), raises CredCryptoError
+    requiring re-authorization. Not backward-compatible with old plaintext credentials.
+    """
+    out = dict(creds)
+    if key is None:
+        key = _load_aesgcm_key()
+    for k in SENSITIVE_KEYS:
+        v = out.get(k, "")
+        if v:
+            out[k] = decrypt_value(v, key=key)
+    return out
+
+
+def has_keypair() -> bool:
+    """Quick check if .keypair.json is available, avoiding exceptions during import."""
+    try:
+        _load_aesgcm_key()
+        return True
+    except CredCryptoError:
+        return False
+
+
+__all__ = [
+    "ENC_PREFIX",
+    "SENSITIVE_KEYS",
+    "CredCryptoError",
+    "is_encrypted",
+    "encrypt_value",
+    "decrypt_value",
+    "encrypt_creds",
+    "decrypt_creds",
+    "has_keypair",
+]

package/dist/scripts/estimate_time.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Lightweight order count probe & time estimator.
+
+Calls /orders/get once (limit=1, offset=0) to get countTotal,
+then estimates generation time based on 2000 orders/minute formula.
+
+Note: countTotal is a server-side estimate and may not match actual fetched count.
+Agent should only show estimated time to user; never display total_orders value.
+
+Usage:
+    python3 scripts/estimate_time.py --agent-type claude --last-days 365
+    python3 scripts/estimate_time.py --agent-type claude --created-after 2025-06-01 --created-before 2026-06-16
+    python3 scripts/estimate_time.py --agent-type claude --last-days 30 --status shipped
+    python3 scripts/estimate_time.py --agent-type claude --last-days 30 --channel AE --ship-to ES
+
+Output (stdout, structured):
+    estimate   : {"total_orders": 8371, "estimated_minutes": 5, "estimated_seconds": 252}
+"""
+
+import argparse
+import json
+import math
+import os
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Optional
+
+import config
+from miravia_client import MiraviaClient
+from skill_logger import set_agent_type
+
+# Estimation formula: 2000 orders/minute (includes LLM analysis & insight injection overhead)
+ORDERS_PER_MINUTE = 2000
+
+# Valid status values (same as export_orders.py)
+VALID_STATUSES = [
+    "all",
+    # -- aggregated --
+    "all_to_ship", "all_shipped",
+    # -- specific --
+    "topack", "packed", "rts", "canceled",
+    "shipped", "delivered",
+]
+
+STATUS_ALIASES = {}
+
+
+def _tz() -> timezone:
+    """Derive tzinfo from config.DEFAULT_TZ_OFFSET, supports env var override (e.g., +02:00 / +01:00)."""
+    off = config.DEFAULT_TZ_OFFSET or "+02:00"
+    sign = 1 if off[0] == "+" else -1
+    hh, mm = off[1:].split(":")
+    return timezone(sign * timedelta(hours=int(hh), minutes=int(mm)))
+
+
+def _resolve_time_range(args) -> tuple:
+    """Parse time range arguments, returns (after_iso, before_iso)."""
+    tz = _tz()
+    now = datetime.now(tz)
+
+    if args.last_days:
+        start = (now - timedelta(days=args.last_days - 1)).replace(
+            hour=0, minute=0, second=0, microsecond=0
+        )
+        end = now.replace(hour=23, minute=59, second=59, microsecond=0)
+    else:
+        if not args.created_after or not args.created_before:
+            print("error: must provide --last-days or both --created-after and --created-before",
+                  file=sys.stderr)
+            sys.exit(1)
+        start = datetime.strptime(args.created_after, "%Y-%m-%d").replace(
+            hour=0, minute=0, second=0, tzinfo=tz
+        )
+        end = datetime.strptime(args.created_before, "%Y-%m-%d").replace(
+            hour=23, minute=59, second=59, tzinfo=tz
+        )
+
+    fmt = "%Y-%m-%dT%H:%M:%S%z"
+    return start.strftime(fmt), end.strftime(fmt)
+
+
+# Cache file for daily version check (avoids upgrade fatigue)
+_UPGRADE_CACHE_FILE = Path(os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))) / ".upgrade_check_cache.json"
+_UPGRADE_CHECK_INTERVAL_SECONDS = 86400  # 24 hours
+
+
+def _read_upgrade_cache() -> Optional[dict]:
+    """Read cached upgrade check result. Returns None if cache is missing or stale (>24h)."""
+    try:
+        if not _UPGRADE_CACHE_FILE.exists():
+            return None
+        cache = json.loads(_UPGRADE_CACHE_FILE.read_text(encoding="utf-8"))
+        checked_at = cache.get("checked_at", 0)
+        if (datetime.now(timezone.utc).timestamp() - checked_at) > _UPGRADE_CHECK_INTERVAL_SECONDS:
+            return None  # Cache expired
+        return cache.get("result")
+    except Exception:
+        return None
+
+
+def _write_upgrade_cache(result: dict) -> None:
+    """Write upgrade check result to cache file."""
+    try:
+        cache = {
+            "checked_at": datetime.now(timezone.utc).timestamp(),
+            "result": result,
+        }
+        _UPGRADE_CACHE_FILE.write_text(json.dumps(cache, ensure_ascii=False), encoding="utf-8")
+    except Exception:
+        pass  # Non-blocking: cache write failure is acceptable
+
+
+def _check_upgrade(client: MiraviaClient) -> None:
+    """Check if skill version is outdated and output upgrade suggestion.
+
+    Rate-limited to once per day via local file cache to avoid upgrade fatigue.
+    Non-blocking: on any failure, silently skip and proceed with normal flow.
+    Output format:
+        upgrade    : {"need_upgrade": true, "current_version": "...", ...}
+    The Agent should present this to the seller and ask for confirmation:
+      - If seller confirms upgrade → run the npx upgrade command first
+      - If seller skips → proceed directly with export/html generation
+    """
+    # Check cache first: if checked within last 24h, suppress upgrade notification
+    # to avoid upgrade fatigue (Agent won't repeatedly ask about upgrades)
+    cached = _read_upgrade_cache()
+    if cached is not None:
+        # Already checked today: always report need_upgrade=false to silence Agent
+        print(f"upgrade    : {json.dumps({'need_upgrade': False, 'current_version': config.SKILL_VERSION, 'cached': True})}", flush=True)
+        return
+
+    try:
+        data = client.check_skill_upgrade()
+        need_upgrade = data.get("need_upgrade", 0)
+        if need_upgrade:
+            latest = data.get("latest_skill", {})
+            upgrade_info = {
+                "need_upgrade": True,
+                "current_version": config.SKILL_VERSION,
+                "latest_version": latest.get("version", "unknown"),
+                "upgrade_command": latest.get("npx_command", "npx @miraiva_test/miravia-order-report@latest upgrade"),
+                "description": latest.get("description", ""),
+                "message": (
+                    f"A newer skill version ({latest.get('version', '?')}) is available. "
+                    f"Current version: {config.SKILL_VERSION}. "
+                    "Please confirm whether to upgrade before proceeding. "
+                    "You can skip the upgrade and continue with the current version."
+                ),
+            }
+            print(f"upgrade    : {json.dumps(upgrade_info)}", flush=True)
+            _write_upgrade_cache(upgrade_info)
+        else:
+            # Version is up-to-date, output for agent awareness
+            result = {"need_upgrade": False, "current_version": config.SKILL_VERSION}
+            print(f"upgrade    : {json.dumps(result)}", flush=True)
+            _write_upgrade_cache(result)
+    except Exception:
+        # Non-blocking: version check failure should never block the estimate flow
+        print(f"upgrade    : {json.dumps({'need_upgrade': False, 'current_version': config.SKILL_VERSION, 'check_skipped': True})}", flush=True)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Quick order count probe & time estimator")
+    parser.add_argument("--last-days", type=int, help="Relative range: last N days")
+    parser.add_argument("--created-after", help="Start date (YYYY-MM-DD)")
+    parser.add_argument("--created-before", help="End date (YYYY-MM-DD)")
+    parser.add_argument("--status", default="all", choices=VALID_STATUSES,
+                        help="Order status filter (default: all)")
+    parser.add_argument("--channel", default=None, choices=["AE", "Miravia"],
+                        help="Channel filter: AE (M2A/AliExpress) or Miravia")
+    parser.add_argument("--ship-to", default=None,
+                        help="Destination country filter (e.g. ES, PT, IT)")
+    parser.add_argument("--order-numbers", default=None,
+                        help="Comma-separated order numbers for direct query")
+    parser.add_argument("--agent-type", required=True,
+                        help="Agent/IDE type identifier (required), dynamically passed by calling Agent")
+    args = parser.parse_args()
+
+    # Set global agent_type (CLI required, sole source)
+    set_agent_type(args.agent_type)
+
+    # Parse time range
+    after, before = _resolve_time_range(args)
+
+    # Single API call to get total count
+    client = MiraviaClient()
+
+    # --- Skill version upgrade check (non-blocking) ---
+    _check_upgrade(client)
+
+    # Map CLI status value to actual API parameter (same logic as export_orders.py)
+    api_status = STATUS_ALIASES.get(args.status, args.status) if args.status != "all" else None
+
+    try:
+        data = client.get_orders_page(
+            created_after=after, created_before=before,
+            status=api_status, limit=1, offset=0,
+            channel=args.channel,
+            ship_to=getattr(args, 'ship_to', None),
+            order_numbers=args.order_numbers,
+        )
+    except Exception as e:
+        print(f"error: API call failed - {e}", file=sys.stderr)
+        sys.exit(1)
+
+    total_orders = int(data.get("countTotal", 0))
+
+    # Zero orders: output no_data signal and exit early
+    if total_orders == 0:
+        result = {
+            "total_orders": 0,
+            "estimated_minutes": 0,
+            "estimated_seconds": 0,
+            "no_data": True,
+            "range_start": after,
+            "range_end": before,
+        }
+        print(f"estimate   : {json.dumps(result)}", flush=True)
+        return
+
+    # Compute estimate (based on 2000 orders/minute throughput)
+    raw_seconds = math.ceil(total_orders / (ORDERS_PER_MINUTE / 60))
+    # Minimum 60 seconds: even with very few orders, LLM data analysis + insight injection takes time
+    estimated_seconds = max(raw_seconds, 60)
+    estimated_minutes = math.ceil(estimated_seconds / 60)
+
+    result = {
+        "total_orders": total_orders,
+        "estimated_minutes": estimated_minutes,
+        "estimated_seconds": estimated_seconds,
+        "no_data": False,
+        "range_start": after,
+        "range_end": before,
+    }
+
+    # Structured output
+    print(f"estimate   : {json.dumps(result)}", flush=True)
+
+
+if __name__ == "__main__":
+    main()