skillplus 0.1.1__tar.gz → 0.2.0__tar.gz

{skillplus-0.1.1 → skillplus-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillplus
-Version: 0.1.1
+Version: 0.2.0
 Summary: Official Python SDK for SkillPlus
 Project-URL: Homepage, https://skillplus.xyz
 Project-URL: Documentation, https://docs.skillplus.xyz
@@ -30,7 +30,9 @@ pip install skillplus
 
 Requires Python 3.10+.
 
-## Basic usage
+## Quick start
+
+`query` gives a binary answer: is there a report, or not.
 
 ```python
 from skillplus import SkillPlus
@@ -40,43 +42,41 @@ client = SkillPlus(api_key="skp_...")
 result = client.query("https://www.skills.sh/vercel-labs/skills/find-skills")
 # GitHub repositories work the same way: "https://github.com/owner/repo"
 
-if result.status == "found" and result.report:
-    print(result.report.verdict)  # "safe" | "medium" | "high" | "unknown"
+if result.status == "found":
+    print(result.report.verdict)  # "safe" | "medium" | "high" | "unknown" — UI labels: Safe / Caution / High Risk / Unrated
+else:
+    print("no report yet", "(scan in progress)" if result.scanning else "")
 ```
 
 Prefer `verdict` over the legacy `rating` field — it folds historical values
-onto the current three-tier scale (UI labels: safe→Safe, medium→Caution,
-high→High Risk, unknown→Unrated).
+onto the current three-tier scale.
 
-## One call that always ends with a report
+## The three integration patterns
 
-When you just want the final answer — scanning first if the skill has never
-been seen — use the wait helper. It polls internally and returns the
-completed report:
+**1. Show a report (frontend page)** — pure read, instant:
 
 ```python
-report = client.wait_for_report("https://www.skills.sh/vercel-labs/skills/find-skills")
-
-print(report.verdict)
-print(report.summary.total_issues)
-if report.supply_chain:
-    print(report.supply_chain.blacklist_hits)  # poisoned-dependency hits
+result = client.query(url)          # found | not_found, never blocks
 ```
 
-## Advanced options
+**2. Scan in the background (batch pipelines)** — fire-and-forget, or wait:
+
+```python
+ack = client.scan(url)              # returns immediately: ack.accepted / ack.scanning
+report = client.scan(url, wait=True)   # blocks until the report completes, returns it
+```
 
-For repositories containing many skills, or to queue a scan automatically when
-no report exists yet:
+**3. Query-and-scan (skill detail pages)** — if it was never scanned, scan it:
 
 ```python
-result = client.query(
-    "https://github.com/owner/repo",       # multi-skill repos are usually on GitHub
-    skill_path="skills/example",           # pick one skill in the repo
-    scan_if_missing=True,                  # queue a scan if no report exists
-)
+result = client.query(url, scan_if_missing=True)   # triggers a scan, still returns immediately
+result = client.query(url, wait=True)              # scans if needed AND waits for the report
 ```
 
-Client options:
+`wait=True` implies `scan_if_missing`; a failing scan raises `SkillPlusError`
+(errors travel on the exception channel, never as a status value).
+
+## Client options
 
 ```python
 client = SkillPlus(
@@ -87,24 +87,26 @@ client = SkillPlus(
 )
 ```
 
+Waiting calls accept `wait_interval` (default 5 s) and `wait_timeout`
+(default 600 s).
+
 ## Context manager
 
 ```python
 from skillplus import SkillPlus
 
 with SkillPlus(api_key="skp_...") as client:
-    result = client.scan("https://www.skills.sh/vercel-labs/skills/find-skills")
-    print(result.status)
+    ack = client.scan("https://www.skills.sh/vercel-labs/skills/find-skills")
+    print(ack.accepted)
 ```
 
 ## Methods
 
 | Method | Use case |
 |---|---|
-| `query(...)` | Check whether SkillPlus already has a report for a skill. |
-| `scan(...)` | Request a scan when a report is missing or when a fresh check is needed. |
-| `wait_for_report(...)` | Query-and-wait: scans if missing, polls, and returns the completed report. |
-| `get_report(scan_id)` | Retrieve structured report data: verdict, findings, AI audit, supply-chain snapshot. |
+| `query(url, ...)` | Binary check: `found` (report attached) or `not_found`. Options: `scan_if_missing`, `wait`. |
+| `scan(url, ...)` | Trigger a scan: fire-and-forget ack, or `wait=True` for the finished report. `force=True` re-scans fresh reports. |
+| `get_report(scan_id)` | Retrieve a report by id: verdict, findings, AI audit, supply-chain snapshot. |
 | `get_badge(scan_id)` | Fetch the badge SVG for embedding. |
 | `get_badge_url(scan_id)` | Generate a badge URL for READMEs, marketplaces, or internal portals. |
 

{skillplus-0.1.1 → skillplus-0.2.0}/README.md

@@ -12,7 +12,9 @@ pip install skillplus
 
 Requires Python 3.10+.
 
-## Basic usage
+## Quick start
+
+`query` gives a binary answer: is there a report, or not.
 
 ```python
 from skillplus import SkillPlus
@@ -22,43 +24,41 @@ client = SkillPlus(api_key="skp_...")
 result = client.query("https://www.skills.sh/vercel-labs/skills/find-skills")
 # GitHub repositories work the same way: "https://github.com/owner/repo"
 
-if result.status == "found" and result.report:
-    print(result.report.verdict)  # "safe" | "medium" | "high" | "unknown"
+if result.status == "found":
+    print(result.report.verdict)  # "safe" | "medium" | "high" | "unknown" — UI labels: Safe / Caution / High Risk / Unrated
+else:
+    print("no report yet", "(scan in progress)" if result.scanning else "")
 ```
 
 Prefer `verdict` over the legacy `rating` field — it folds historical values
-onto the current three-tier scale (UI labels: safe→Safe, medium→Caution,
-high→High Risk, unknown→Unrated).
+onto the current three-tier scale.
 
-## One call that always ends with a report
+## The three integration patterns
 
-When you just want the final answer — scanning first if the skill has never
-been seen — use the wait helper. It polls internally and returns the
-completed report:
+**1. Show a report (frontend page)** — pure read, instant:
 
 ```python
-report = client.wait_for_report("https://www.skills.sh/vercel-labs/skills/find-skills")
-
-print(report.verdict)
-print(report.summary.total_issues)
-if report.supply_chain:
-    print(report.supply_chain.blacklist_hits)  # poisoned-dependency hits
+result = client.query(url)          # found | not_found, never blocks
 ```
 
-## Advanced options
+**2. Scan in the background (batch pipelines)** — fire-and-forget, or wait:
+
+```python
+ack = client.scan(url)              # returns immediately: ack.accepted / ack.scanning
+report = client.scan(url, wait=True)   # blocks until the report completes, returns it
+```
 
-For repositories containing many skills, or to queue a scan automatically when
-no report exists yet:
+**3. Query-and-scan (skill detail pages)** — if it was never scanned, scan it:
 
 ```python
-result = client.query(
-    "https://github.com/owner/repo",       # multi-skill repos are usually on GitHub
-    skill_path="skills/example",           # pick one skill in the repo
-    scan_if_missing=True,                  # queue a scan if no report exists
-)
+result = client.query(url, scan_if_missing=True)   # triggers a scan, still returns immediately
+result = client.query(url, wait=True)              # scans if needed AND waits for the report
 ```
 
-Client options:
+`wait=True` implies `scan_if_missing`; a failing scan raises `SkillPlusError`
+(errors travel on the exception channel, never as a status value).
+
+## Client options
 
 ```python
 client = SkillPlus(
@@ -69,24 +69,26 @@ client = SkillPlus(
 )
 ```
 
+Waiting calls accept `wait_interval` (default 5 s) and `wait_timeout`
+(default 600 s).
+
 ## Context manager
 
 ```python
 from skillplus import SkillPlus
 
 with SkillPlus(api_key="skp_...") as client:
-    result = client.scan("https://www.skills.sh/vercel-labs/skills/find-skills")
-    print(result.status)
+    ack = client.scan("https://www.skills.sh/vercel-labs/skills/find-skills")
+    print(ack.accepted)
 ```
 
 ## Methods
 
 | Method | Use case |
 |---|---|
-| `query(...)` | Check whether SkillPlus already has a report for a skill. |
-| `scan(...)` | Request a scan when a report is missing or when a fresh check is needed. |
-| `wait_for_report(...)` | Query-and-wait: scans if missing, polls, and returns the completed report. |
-| `get_report(scan_id)` | Retrieve structured report data: verdict, findings, AI audit, supply-chain snapshot. |
+| `query(url, ...)` | Binary check: `found` (report attached) or `not_found`. Options: `scan_if_missing`, `wait`. |
+| `scan(url, ...)` | Trigger a scan: fire-and-forget ack, or `wait=True` for the finished report. `force=True` re-scans fresh reports. |
+| `get_report(scan_id)` | Retrieve a report by id: verdict, findings, AI audit, supply-chain snapshot. |
 | `get_badge(scan_id)` | Fetch the badge SVG for embedding. |
 | `get_badge_url(scan_id)` | Generate a badge URL for READMEs, marketplaces, or internal portals. |
 

{skillplus-0.1.1 → skillplus-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "skillplus"
-version = "0.1.1"
+version = "0.2.0"
 description = "Official Python SDK for SkillPlus"
 readme = "README.md"
 requires-python = ">=3.10"

{skillplus-0.1.1 → skillplus-0.2.0}/src/skillplus/__init__.py

@@ -11,10 +11,9 @@ from .types import (
     QueryResult,
     QueryStatus,
     Rating,
+    ScanAck,
     ScanIssue,
     ScanReport,
-    ScanResult,
-    ScanStatus,
     ScanSummary,
     Severity,
     SeverityNormalized,
@@ -34,10 +33,9 @@ __all__ = [
     "QueryResult",
     "QueryStatus",
     "Rating",
+    "ScanAck",
     "ScanIssue",
     "ScanReport",
-    "ScanResult",
-    "ScanStatus",
     "ScanSummary",
     "Severity",
     "SeverityNormalized",

{skillplus-0.1.1 → skillplus-0.2.0}/src/skillplus/client.py

@@ -13,9 +13,9 @@ from .types import (
     AiReport,
     PlatformListing,
     QueryResult,
+    ScanAck,
     ScanIssue,
     ScanReport,
-    ScanResult,
     ScanSummary,
     SupplyChainHit,
     SupplyChainReport,
@@ -50,7 +50,7 @@ class SkillPlus:
             headers={
                 "Authorization": f"Bearer {api_key}",
                 "Content-Type": "application/json",
-                "User-Agent": "skillplus-python/0.1.1",
+                "User-Agent": "skillplus-python/0.2.0",
             },
         )
 
@@ -71,21 +71,34 @@ class SkillPlus:
         *,
         skill_path: str | None = None,
         scan_if_missing: bool = False,
+        wait: bool = False,
+        wait_interval: float = 5.0,
+        wait_timeout: float = 600.0,
         preferred_provider: str | None = None,
     ) -> QueryResult:
-        """Query an existing report, optionally queueing a scan if no report exists."""
+        """Is there a report? Binary answer: ``found`` (report attached) or
+        ``not_found`` (with ``scanning`` telling you whether one is on the way).
 
-        payload = self._request_json(
-            "POST",
-            "/api/sdk/query",
-            json={
-                "repo_url": repo_url,
-                "skill_path": skill_path,
-                "scan_if_missing": scan_if_missing,
-                "preferred_provider": preferred_provider,
-            },
+        - ``scan_if_missing=True`` — queue a scan when nothing exists, still
+          return immediately.
+        - ``wait=True`` — block until a completed report exists (scanning
+          first if needed) and return ``found``; raises on failure/timeout.
+        """
+
+        if wait:
+            return self._wait_for_completed(
+                repo_url,
+                skill_path=skill_path,
+                preferred_provider=preferred_provider,
+                prior=None,
+                interval=wait_interval,
+                timeout=wait_timeout,
+            )
+        payload = self._raw_query(
+            repo_url, skill_path=skill_path,
+            scan_if_missing=scan_if_missing, preferred_provider=preferred_provider,
         )
-        return _parse_query_result(payload)
+        return _map_server_state(payload)
 
     def scan(
         self,
@@ -94,10 +107,76 @@ class SkillPlus:
         skill_path: str | None = None,
         preferred_provider: str | None = None,
         force: bool = False,
-    ) -> ScanResult:
-        """Request a scan for a skill."""
+        wait: bool = False,
+        wait_interval: float = 5.0,
+        wait_timeout: float = 600.0,
+    ) -> ScanAck | ScanReport:
+        """Trigger a scan.
+
+        - Default: fire-and-forget — returns a :class:`ScanAck` immediately
+          (``accepted=False`` means deduplicated: already scanning, or a
+          fresh report exists and ``force`` was not set).
+        - ``wait=True`` — block until the resulting report completes and
+          return the report itself.
+        """
+
+        if wait:
+            prior: ScanReport | None = None
+            if force:
+                current = self.query(repo_url, skill_path=skill_path)
+                prior = current.report if current.status == "found" else None
+            self._raw_scan(
+                repo_url, skill_path=skill_path,
+                preferred_provider=preferred_provider, force=force,
+            )
+            found = self._wait_for_completed(
+                repo_url,
+                skill_path=skill_path,
+                preferred_provider=preferred_provider,
+                prior=prior,
+                interval=wait_interval,
+                timeout=wait_timeout,
+            )
+            assert found.report is not None
+            return found.report
 
-        payload = self._request_json(
+        payload = self._raw_scan(
+            repo_url, skill_path=skill_path,
+            preferred_provider=preferred_provider, force=force,
+        )
+        status = payload.get("status")
+        message = payload.get("message") or ""
+        if status == "queued":
+            return ScanAck(accepted=True, scanning=True, message=message or "Scan queued")
+        if status == "running":
+            return ScanAck(accepted=False, scanning=True, message=message or "Scan already in progress")
+        if status == "found":
+            return ScanAck(
+                accepted=False, scanning=False,
+                message="A fresh report already exists (pass force=True to re-scan)",
+            )
+        raise SkillPlusError(message or "Scan failed", detail=status)
+
+    def _raw_query(
+        self, repo_url: str, *, skill_path: str | None,
+        scan_if_missing: bool, preferred_provider: str | None,
+    ) -> dict[str, Any]:
+        return self._request_json(
+            "POST",
+            "/api/sdk/query",
+            json={
+                "repo_url": repo_url,
+                "skill_path": skill_path,
+                "scan_if_missing": scan_if_missing,
+                "preferred_provider": preferred_provider,
+            },
+        )
+
+    def _raw_scan(
+        self, repo_url: str, *, skill_path: str | None,
+        preferred_provider: str | None, force: bool,
+    ) -> dict[str, Any]:
+        return self._request_json(
             "POST",
             "/api/sdk/scan",
             json={
@@ -107,37 +186,43 @@ class SkillPlus:
                 "force": force,
             },
         )
-        return _parse_scan_result(payload)
 
-    def wait_for_report(
+    def _wait_for_completed(
         self,
         repo_url: str,
         *,
-        skill_path: str | None = None,
-        preferred_provider: str | None = None,
-        interval: float = 5.0,
-        timeout: float = 600.0,
-    ) -> ScanReport:
-        """Query-and-wait: poll until a completed report exists (scanning if
-        missing). This is the reliable path after a ``queued`` result, which
-        may carry no scan_id to poll."""
+        skill_path: str | None,
+        preferred_provider: str | None,
+        prior: ScanReport | None,
+        interval: float,
+        timeout: float,
+    ) -> QueryResult:
+        """Poll until a completed report exists; a ``prior`` report (from a
+        forced re-scan) must be superseded before we accept an answer."""
 
         deadline = time.monotonic() + timeout
         while True:
-            result = self.query(
-                repo_url,
-                skill_path=skill_path,
-                scan_if_missing=True,
-                preferred_provider=preferred_provider,
+            payload = self._raw_query(
+                repo_url, skill_path=skill_path,
+                scan_if_missing=True, preferred_provider=preferred_provider,
             )
-            if result.status == "found" and result.report and result.report.status == "completed":
-                return result.report
-            if result.status in ("failed", "not_found"):
-                raise SkillPlusError(f"Scan {result.status}: {result.message}", detail=result.status)
+            status = payload.get("status")
+            if status == "failed":
+                raise SkillPlusError(
+                    f"Scan failed: {payload.get('message') or ''}", detail="failed"
+                )
+            report_payload = payload.get("report")
+            if (
+                status == "found"
+                and report_payload
+                and report_payload.get("status") == "completed"
+                and (prior is None or report_payload.get("scanned_at") != prior.scanned_at)
+            ):
+                return _map_server_state(payload)
             if time.monotonic() + interval > deadline:
                 raise SkillPlusError(
-                    f"Timed out waiting for report (last status: {result.status})",
-                    detail=result.status,
+                    f"Timed out waiting for report (last status: {status})",
+                    detail=status,
                 )
             time.sleep(interval)
 
@@ -219,23 +304,21 @@ class SkillPlus:
         return response
 
 
-def _parse_query_result(payload: dict[str, Any]) -> QueryResult:
+def _map_server_state(payload: dict[str, Any]) -> QueryResult:
+    """Fold the server's five-state machine onto the binary query contract."""
+    status = payload.get("status")
+    if status == "found" and payload.get("report"):
+        return QueryResult(
+            status="found",
+            message=payload.get("message") or "Report found",
+            report=_parse_report(payload["report"]),
+            scanning=False,
+        )
     return QueryResult(
-        status=payload["status"],
-        message=payload["message"],
-        scan_id=payload.get("scan_id"),
-        poll_url=payload.get("poll_url"),
-        report=_parse_report(payload["report"]) if payload.get("report") else None,
-    )
-
-
-def _parse_scan_result(payload: dict[str, Any]) -> ScanResult:
-    return ScanResult(
-        status=payload["status"],
-        message=payload["message"],
-        scan_id=payload.get("scan_id"),
-        poll_url=payload.get("poll_url"),
-        report=_parse_report(payload["report"]) if payload.get("report") else None,
+        status="not_found",
+        message=payload.get("message") or "Report not found",
+        report=None,
+        scanning=status in ("queued", "running"),
     )
 
 

{skillplus-0.1.1 → skillplus-0.2.0}/src/skillplus/types.py

@@ -23,8 +23,8 @@ IssueCategory: TypeAlias = Literal[
     "supply_chain",
     "propagation",
 ]
-QueryStatus: TypeAlias = Literal["found", "queued", "running", "not_found", "failed"]
-ScanStatus: TypeAlias = Literal["found", "queued", "running", "failed"]
+# query() is binary: a report exists or it does not.
+QueryStatus: TypeAlias = Literal["found", "not_found"]
 AiReportStatus: TypeAlias = Literal["pending", "processing", "completed", "failed"]
 
 
@@ -160,17 +160,25 @@ class ScanReport:
 
 @dataclass(slots=True)
 class QueryResult:
+    """Binary answer: ``found`` (report attached) or ``not_found``.
+
+    ``scanning`` is a courtesy flag on not_found: True means a scan for this
+    skill is queued or running right now (check back shortly)."""
+
     status: QueryStatus
     message: str
-    scan_id: str | None = None
-    poll_url: str | None = None
     report: ScanReport | None = None
+    scanning: bool = False
 
 
 @dataclass(slots=True)
-class ScanResult:
-    status: ScanStatus
+class ScanAck:
+    """Acknowledgement of a fire-and-forget scan() call.
+
+    ``accepted`` is True only when THIS call queued a new scan; False means
+    it was deduplicated (already scanning, or a fresh report exists and
+    ``force`` was not set)."""
+
+    accepted: bool
+    scanning: bool
     message: str
-    scan_id: str | None = None
-    poll_url: str | None = None
-    report: ScanReport | None = None

skillplus-0.2.0/tests/test_client.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+import json
+
+import pytest
+import respx
+from httpx import Response
+
+from skillplus import SkillPlus, SkillPlusError
+
+
+REPORT_PAYLOAD = {
+    "scan_id": "scan_123",
+    "skill_name": "example",
+    "source": "github:owner/repo",
+    "skill_path": "skills/example",
+    "tree_sha": "abc123",
+    "rule_version": "rules-v1",
+    "valid_skill": True,
+    "rating": "safe",
+    "scanned_at": "2026-06-10T00:00:00Z",
+    "cached": True,
+    "scan_duration_ms": 1200,
+    "summary": {
+        "total_issues": 1,
+        "danger": 0,
+        "warning": 1,
+        "info": 0,
+        "files_scanned": 4,
+        "by_category": {"url": 1},
+    },
+    "issues": [
+        {
+            "rule_id": "external-url",
+            "severity": "warning",
+            "category": "url",
+            "message": "External URL found",
+            "file": "SKILL.md",
+            "line": 12,
+            "snippet": "https://example.com",
+            "domain": "example.com",
+        }
+    ],
+    "report_url": "https://skillplus.xyz/report/scan_123",
+    "badge_url": "https://skillplus.xyz/api/report/scan_123/badge.svg",
+    "blacklisted": False,
+    "whitelisted": False,
+    "status": "completed",
+    "ai_report": {
+        "status": "completed",
+        "risk_level": "low",
+        "refined_rating": "safe",
+        "false_positives": [
+            {"rule_id": "external-url", "file": "SKILL.md", "reason": "Documentation link"}
+        ],
+        "analysis": [
+            {
+                "category": "Command Execution",
+                "status": "pass",
+                "severity": "safe",
+                "title": "No command execution",
+                "description": "No risky command execution was found.",
+                "evidence": ["No shell usage"],
+                "confidence": 0.98,
+            }
+        ],
+        "summary": "No meaningful risk found.",
+        "categories_checked": [],
+        "tokens_used": 500,
+        "duration_ms": 800,
+        "error_message": None,
+    },
+    "external_links": {"website": "https://example.com"},
+    "platform_listings": [
+        {"platform": "skills.sh", "url": "https://skills.sh/owner/repo/example", "installs": 10}
+    ],
+}
+
+
+SERVER_QUEUED = {"status": "queued", "message": "Scan queued", "scan_id": None, "poll_url": None}
+SERVER_RUNNING = {"status": "running", "message": "Scan already in progress", "scan_id": "s1", "poll_url": "/x"}
+SERVER_NOT_FOUND = {"status": "not_found", "message": "Report not found", "scan_id": None, "poll_url": None}
+SERVER_FAILED = {"status": "failed", "message": "boom", "scan_id": None, "poll_url": None}
+
+
+def server_found(report=None):
+    return {
+        "status": "found",
+        "message": "Report found",
+        "scan_id": "scan_123",
+        "poll_url": "/api/scan/status/scan_123",
+        "report": report or REPORT_PAYLOAD,
+    }
+
+
+@respx.mock
+def test_query_sends_auth_and_request_body() -> None:
+    route = respx.post("https://skillplus.xyz/api/sdk/query").mock(
+        return_value=Response(200, json=server_found())
+    )
+    with SkillPlus(api_key="skp_test") as client:
+        result = client.query(
+            "https://github.com/owner/repo",
+            skill_path="skills/example",
+            scan_if_missing=True,
+            preferred_provider="github",
+        )
+    request = route.calls.last.request
+    assert request.headers["Authorization"] == "Bearer skp_test"
+    assert json.loads(request.read()) == {
+        "repo_url": "https://github.com/owner/repo",
+        "skill_path": "skills/example",
+        "scan_if_missing": True,
+        "preferred_provider": "github",
+    }
+    assert result.status == "found"
+    assert result.scanning is False
+    assert result.report is not None
+    assert result.report.scan_id == "scan_123"
+    assert result.report.summary.total_issues == 1
+    assert result.report.issues[0].rule_id == "external-url"
+
+
+@respx.mock
+def test_query_folds_in_progress_onto_not_found_scanning() -> None:
+    for server, scanning in ((SERVER_QUEUED, True), (SERVER_RUNNING, True),
+                             (SERVER_NOT_FOUND, False), (SERVER_FAILED, False)):
+        respx.post("https://skillplus.xyz/api/sdk/query").mock(
+            return_value=Response(200, json=server)
+        )
+        with SkillPlus(api_key="skp_test") as client:
+            result = client.query("https://skills.sh/o/r/s")
+        assert result.status == "not_found"
+        assert result.report is None
+        assert result.scanning is scanning
+
+
+@respx.mock
+def test_query_wait_polls_until_completed() -> None:
+    route = respx.post("https://skillplus.xyz/api/sdk/query")
+    route.side_effect = [
+        Response(200, json=SERVER_QUEUED),
+        Response(200, json=SERVER_RUNNING),
+        Response(200, json=server_found()),
+    ]
+    with SkillPlus(api_key="skp_test") as client:
+        result = client.query("https://skills.sh/o/r/s", wait=True, wait_interval=0.01)
+    assert result.status == "found"
+    assert result.report is not None
+    assert route.call_count == 3
+
+
+@respx.mock
+def test_query_wait_raises_on_scan_failure() -> None:
+    route = respx.post("https://skillplus.xyz/api/sdk/query")
+    route.side_effect = [Response(200, json=SERVER_QUEUED), Response(200, json=SERVER_FAILED)]
+    with SkillPlus(api_key="skp_test") as client:
+        with pytest.raises(SkillPlusError) as excinfo:
+            client.query("https://skills.sh/o/r/s", wait=True, wait_interval=0.01)
+    assert "failed" in str(excinfo.value).lower()
+
+
+@respx.mock
+def test_query_wait_times_out() -> None:
+    respx.post("https://skillplus.xyz/api/sdk/query").mock(
+        return_value=Response(200, json=SERVER_QUEUED)
+    )
+    with SkillPlus(api_key="skp_test") as client:
+        with pytest.raises(SkillPlusError) as excinfo:
+            client.query("https://skills.sh/o/r/s", wait=True, wait_interval=0.01, wait_timeout=0.02)
+    assert "Timed out" in str(excinfo.value)
+
+
+@respx.mock
+def test_scan_ack_semantics() -> None:
+    for server, accepted, scanning in ((SERVER_QUEUED, True, True),
+                                       (SERVER_RUNNING, False, True),
+                                       (server_found(), False, False)):
+        respx.post("https://skillplus.xyz/api/sdk/scan").mock(
+            return_value=Response(200, json=server)
+        )
+        with SkillPlus(api_key="skp_test") as client:
+            ack = client.scan("https://skills.sh/o/r/s")
+        assert (ack.accepted, ack.scanning) == (accepted, scanning)
+
+
+@respx.mock
+def test_scan_wait_triggers_then_returns_report() -> None:
+    scan_route = respx.post("https://skillplus.xyz/api/sdk/scan").mock(
+        return_value=Response(200, json=SERVER_QUEUED)
+    )
+    query_route = respx.post("https://skillplus.xyz/api/sdk/query")
+    query_route.side_effect = [Response(200, json=SERVER_RUNNING), Response(200, json=server_found())]
+    with SkillPlus(api_key="skp_test") as client:
+        report = client.scan("https://skills.sh/o/r/s", wait=True, wait_interval=0.01)
+    assert report.scan_id == "scan_123"
+    assert scan_route.call_count == 1
+    assert query_route.call_count == 2
+
+
+@respx.mock
+def test_scan_wait_force_waits_for_superseding_report() -> None:
+    import copy
+    old = copy.deepcopy(REPORT_PAYLOAD)
+    new = copy.deepcopy(REPORT_PAYLOAD)
+    new["scanned_at"] = "2026-07-18T12:00:00Z"
+    respx.post("https://skillplus.xyz/api/sdk/scan").mock(
+        return_value=Response(200, json=SERVER_QUEUED)
+    )
+    query_route = respx.post("https://skillplus.xyz/api/sdk/query")
+    query_route.side_effect = [
+        Response(200, json=server_found(old)),   # prior capture
+        Response(200, json=server_found(old)),   # still the old report
+        Response(200, json=server_found(new)),   # rescanned
+    ]
+    with SkillPlus(api_key="skp_test") as client:
+        report = client.scan("https://skills.sh/o/r/s", force=True, wait=True, wait_interval=0.01)
+    assert report.scanned_at == "2026-07-18T12:00:00Z"
+    assert query_route.call_count == 3
+
+
+@respx.mock
+def test_http_error_raises_skillplus_error() -> None:
+    respx.post("https://skillplus.xyz/api/sdk/query").mock(
+        return_value=Response(401, json={"detail": "Invalid API key"})
+    )
+    with SkillPlus(api_key="skp_bad") as client:
+        with pytest.raises(SkillPlusError) as excinfo:
+            client.query("https://skills.sh/o/r/s")
+    assert excinfo.value.status_code == 401
+    assert "Invalid API key" in str(excinfo.value)
+
+
+@respx.mock
+def test_get_badge_and_badge_url() -> None:
+    respx.get("https://skillplus.xyz/api/report/scan_123/badge.svg").mock(
+        return_value=Response(200, text="<svg/>")
+    )
+    with SkillPlus(api_key="skp_test") as client:
+        assert client.get_badge("scan_123") == "<svg/>"
+        assert client.get_badge_url("scan_123") == "https://skillplus.xyz/api/report/scan_123/badge.svg"

{skillplus-0.1.1 → skillplus-0.2.0}/tests/test_v3_features.py

@@ -141,7 +141,7 @@ def test_no_retry_when_disabled() -> None:
 
 
 @respx.mock
-def test_wait_for_report_polls_until_completed() -> None:
+def test_query_wait_polls_until_completed_v3() -> None:
     queued = {"status": "queued", "message": "Scan queued", "scan_id": None, "poll_url": None}
     found = {
         "status": "found",
@@ -154,23 +154,21 @@ def test_wait_for_report_polls_until_completed() -> None:
     route.side_effect = [Response(200, json=queued), Response(200, json=found)]
 
     with SkillPlus(api_key="skp_test") as client:
-        report = client.wait_for_report(
-            "https://github.com/owner/repo", interval=0.01, timeout=5.0
-        )
+        result = client.query("https://github.com/owner/repo", wait=True, wait_interval=0.01)
 
-    assert report.scan_id == "scan_123"
+    assert result.report is not None and result.report.scan_id == "scan_123"
     assert route.call_count == 2
 
 
 @respx.mock
-def test_wait_for_report_times_out() -> None:
+def test_query_wait_times_out_v3() -> None:
     queued = {"status": "queued", "message": "Scan queued", "scan_id": None, "poll_url": None}
     respx.post("https://skillplus.xyz/api/sdk/query").mock(
         return_value=Response(200, json=queued)
     )
     with SkillPlus(api_key="skp_test") as client:
         with pytest.raises(SkillPlusError) as excinfo:
-            client.wait_for_report("https://github.com/owner/repo", interval=0.01, timeout=0.02)
+            client.query("https://github.com/owner/repo", wait=True, wait_interval=0.01, wait_timeout=0.02)
     assert "Timed out" in str(excinfo.value)
 
 

skillplus-0.1.1/tests/test_client.py

@@ -1,223 +0,0 @@
-from __future__ import annotations
-
-import json
-
-import pytest
-import respx
-from httpx import Response
-
-from skillplus import SkillPlus, SkillPlusError
-
-
-REPORT_PAYLOAD = {
-    "scan_id": "scan_123",
-    "skill_name": "example",
-    "source": "github:owner/repo",
-    "skill_path": "skills/example",
-    "tree_sha": "abc123",
-    "rule_version": "rules-v1",
-    "valid_skill": True,
-    "rating": "safe",
-    "scanned_at": "2026-06-10T00:00:00Z",
-    "cached": True,
-    "scan_duration_ms": 1200,
-    "summary": {
-        "total_issues": 1,
-        "danger": 0,
-        "warning": 1,
-        "info": 0,
-        "files_scanned": 4,
-        "by_category": {"url": 1},
-    },
-    "issues": [
-        {
-            "rule_id": "external-url",
-            "severity": "warning",
-            "category": "url",
-            "message": "External URL found",
-            "file": "SKILL.md",
-            "line": 12,
-            "snippet": "https://example.com",
-            "domain": "example.com",
-        }
-    ],
-    "report_url": "https://skillplus.xyz/report/scan_123",
-    "badge_url": "https://skillplus.xyz/api/report/scan_123/badge.svg",
-    "blacklisted": False,
-    "whitelisted": False,
-    "status": "completed",
-    "ai_report": {
-        "status": "completed",
-        "risk_level": "low",
-        "refined_rating": "safe",
-        "false_positives": [
-            {"rule_id": "external-url", "file": "SKILL.md", "reason": "Documentation link"}
-        ],
-        "analysis": [
-            {
-                "category": "Command Execution",
-                "status": "pass",
-                "severity": "safe",
-                "title": "No command execution",
-                "description": "No risky command execution was found.",
-                "evidence": ["No shell usage"],
-                "confidence": 0.98,
-            }
-        ],
-        "summary": "No meaningful risk found.",
-        "categories_checked": [],
-        "tokens_used": 500,
-        "duration_ms": 800,
-        "error_message": None,
-    },
-    "external_links": {"website": "https://example.com"},
-    "platform_listings": [
-        {"platform": "skills.sh", "url": "https://skills.sh/owner/repo/example", "installs": 10}
-    ],
-}
-
-
-@respx.mock
-def test_query_sends_auth_and_request_body() -> None:
-    route = respx.post("https://skillplus.xyz/api/sdk/query").mock(
-        return_value=Response(
-            200,
-            json={
-                "status": "found",
-                "message": "Report found",
-                "scan_id": "scan_123",
-                "poll_url": "/api/scan/status/scan_123",
-                "report": REPORT_PAYLOAD,
-            },
-        )
-    )
-
-    with SkillPlus(api_key="skp_test") as client:
-        result = client.query(
-            "https://github.com/owner/repo",
-            skill_path="skills/example",
-            scan_if_missing=True,
-            preferred_provider="github",
-        )
-
-    request = route.calls.last.request
-    assert request.headers["Authorization"] == "Bearer skp_test"
-    assert request.headers["Content-Type"] == "application/json"
-    assert json.loads(request.read()) == {
-        "repo_url": "https://github.com/owner/repo",
-        "skill_path": "skills/example",
-        "scan_if_missing": True,
-        "preferred_provider": "github",
-    }
-    assert result.status == "found"
-    assert result.scan_id == "scan_123"
-    assert result.report is not None
-    assert result.report.rating == "safe"
-    assert result.report.summary.warning == 1
-    assert result.report.issues[0].rule_id == "external-url"
-    assert result.report.ai_report is not None
-    assert result.report.ai_report.false_positives[0].reason == "Documentation link"
-
-
-@respx.mock
-def test_query_without_report_returns_status_envelope() -> None:
-    respx.post("https://skillplus.xyz/api/sdk/query").mock(
-        return_value=Response(
-            200,
-            json={
-                "status": "queued",
-                "message": "Scan queued",
-                "scan_id": "scan_queued",
-                "poll_url": "/api/scan/status/scan_queued",
-                "report": None,
-            },
-        )
-    )
-
-    client = SkillPlus(api_key="skp_test")
-    try:
-        result = client.query("https://github.com/owner/repo", scan_if_missing=True)
-    finally:
-        client.close()
-
-    assert result.status == "queued"
-    assert result.scan_id == "scan_queued"
-    assert result.report is None
-
-
-@respx.mock
-def test_scan_sends_force_flag() -> None:
-    route = respx.post("https://skillplus.xyz/api/sdk/scan").mock(
-        return_value=Response(
-            200,
-            json={
-                "status": "running",
-                "message": "Scan already running",
-                "scan_id": "scan_running",
-                "poll_url": "/api/scan/status/scan_running",
-                "report": None,
-            },
-        )
-    )
-
-    with SkillPlus(api_key="skp_test") as client:
-        result = client.scan("https://github.com/owner/repo", skill_path="skills/example", force=True)
-
-    assert json.loads(route.calls.last.request.read()) == {
-        "repo_url": "https://github.com/owner/repo",
-        "skill_path": "skills/example",
-        "preferred_provider": None,
-        "force": True,
-    }
-    assert result.status == "running"
-    assert result.report is None
-
-
-@respx.mock
-def test_get_report_parses_report() -> None:
-    respx.get("https://skillplus.xyz/api/report/scan_123").mock(
-        return_value=Response(200, json=REPORT_PAYLOAD)
-    )
-
-    with SkillPlus(api_key="skp_test") as client:
-        report = client.get_report("scan_123")
-
-    assert report.scan_id == "scan_123"
-    assert report.platform_listings[0].platform == "skills.sh"
-
-
-@respx.mock
-def test_get_badge_returns_svg_text() -> None:
-    respx.get("https://skillplus.xyz/api/report/scan_123/badge.svg").mock(
-        return_value=Response(200, text="<svg></svg>")
-    )
-
-    with SkillPlus(api_key="skp_test") as client:
-        badge = client.get_badge("scan_123")
-
-    assert badge == "<svg></svg>"
-
-
-def test_get_badge_url_uses_hosted_service() -> None:
-    client = SkillPlus(api_key="skp_test")
-    try:
-        assert (
-            client.get_badge_url("scan_123")
-            == "https://skillplus.xyz/api/report/scan_123/badge.svg"
-        )
-    finally:
-        client.close()
-
-
-@respx.mock
-def test_non_ok_response_raises_skillplus_error() -> None:
-    respx.post("https://skillplus.xyz/api/sdk/query").mock(
-        return_value=Response(401, json={"detail": "Invalid API key"})
-    )
-
-    with SkillPlus(api_key="bad_key") as client:
-        with pytest.raises(SkillPlusError) as exc_info:
-            client.query("https://github.com/owner/repo")
-
-    assert exc_info.value.status_code == 401
-    assert exc_info.value.message == "Invalid API key"