imperal-sdk 5.4.2__tar.gz → 5.4.3__tar.gz

{imperal_sdk-5.4.2 → imperal_sdk-5.4.3}/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 5.4.3 — 2026-06-18 — Fix secrets-panel render crash
+
+Bugfix — **nothing to migrate**.
+
+### Fixed
+- Auto-generated `__panel__secrets` panel (created for any extension declaring
+  `@ext.secret`) called `ui.Heading(...)`, which does not exist — the display
+  element is exported as `ui.Header`. Every secrets-panel render raised
+  `AttributeError: module 'imperal_sdk.ui' has no attribute 'Heading'`. Switched
+  to `ui.Header`. No public API change.
+
+## 5.4.2 — 2026-06-16 — BillingClient renew_subscription
+
+Additive — **nothing to migrate**.
+
+### Added
+- `ctx.billing.renew_subscription()` — renews an **expired** subscription for
+  the same plan: charges the saved default card for one fresh period and
+  restores access immediately (POST `/v1/billing/renew`). Surfaces errors
+  (`402` no card / SCA required, `409` not expired). Returns the gateway result
+  dict (`{status, plan, expires_at, payment_intent_id}`).
+
+`BillingProtocol` 18 → 19 methods.
+
 ## 5.4.1 — 2026-06-16 — BillingClient resume + cancel_at_period_end
 
 Additive — **nothing to migrate**.

{imperal_sdk-5.4.2 → imperal_sdk-5.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imperal-sdk
-Version: 5.4.2
+Version: 5.4.3
 Summary: SDK for building Imperal Cloud extensions
 Author: Valentin Scerbacov, Imperal, Inc.
 License-Expression: AGPL-3.0-or-later

{imperal_sdk-5.4.2 → imperal_sdk-5.4.3}/sdk_claims.json

@@ -1,5 +1,5 @@
 {
-  "_sdk_version": "5.4.2",
+  "_sdk_version": "5.4.3",
   "constants": {
     "max_call_depth": {
       "counts_root": true,

{imperal_sdk-5.4.2 → imperal_sdk-5.4.3}/src/imperal_sdk/__init__.py

@@ -1,7 +1,7 @@
 """Imperal Cloud SDK — build extensions for the Imperal platform."""
 from typing import TYPE_CHECKING
 
-__version__ = "5.4.2"
+__version__ = "5.4.3"
 
 # 5.2.2 (2026-06-11): the package root resolves its public surface lazily
 # (PEP 562). The eager imports pulled the HTTP transport (Context / client

{imperal_sdk-5.4.2 → imperal_sdk-5.4.3}/src/imperal_sdk/chat/extension.py

@@ -61,6 +61,7 @@ class FunctionDef:
     _pydantic_model: type | None = None  # auto-detected Pydantic BaseModel class
     _pydantic_param: str = ""  # parameter name that receives the model instance
     _return_model: type | None = None  # data_model kwarg OR autodetected return Pydantic model
+    _ui_builder: bool = False  # @chat.function(ui_builder=True): Declarative-UI builder; exempt from the V23 data_model rule
 
 
 class ChatExtension:
@@ -117,7 +118,8 @@ class ChatExtension:
                  id_projection: str | None = None,
                  background: bool = False,
                  long_running: bool = False,
-                 data_model: type | None = None):
+                 data_model: type | None = None,
+                 ui_builder: bool = False):
         """Register a chat function.
 
         Args:
@@ -266,6 +268,7 @@ class ChatExtension:
                 long_running=long_running,
                 _pydantic_model=_detected_model, _pydantic_param=_detected_param,
                 _return_model=_detected_return_model,
+                _ui_builder=ui_builder,
             )
             return func
         return decorator

{imperal_sdk-5.4.2 → imperal_sdk-5.4.3}/src/imperal_sdk/cli/main.py

@@ -9,6 +9,11 @@ import configparser
 import click
 import httpx
 
+try:
+    from imperal_sdk import __version__ as SDK_VERSION
+except Exception:  # pragma: no cover - defensive
+    SDK_VERSION = "5.x"
+
 
 def _load_credentials() -> dict:
     """Load credentials from .imperal/credentials or environment variables."""
@@ -57,7 +62,7 @@ def _validate_manifest(manifest: dict) -> list[str]:
 
 
 @click.group()
-@click.version_option(version="1.0.0")
+@click.version_option(version=SDK_VERSION)
 def cli():
     """Imperal Cloud SDK — build extensions for the Imperal platform."""
     pass
@@ -67,7 +72,7 @@ def cli():
 @click.argument("name")
 @click.option("--template", type=click.Choice(["chat", "tool"]), default="chat", help="Extension template")
 def init(name: str, template: str):
-    """Scaffold a new extension project (federal v4 contract)."""
+    """Scaffold a new extension project (federal v5 contract)."""
     os.makedirs(name, exist_ok=True)
     os.makedirs(f"{name}/tests", exist_ok=True)
 
@@ -88,7 +93,7 @@ from pydantic import BaseModel, Field
 from imperal_sdk import Extension, ChatExtension, ActionResult
 
 
-# Federal v4 Extension surface — V14 (description ≥40 chars), V15
+# Federal v5 Extension surface — V14 (description ≥40 chars), V15
 # (display_name ≥3 chars, ≠ app_id), V19 (actions_explicit=True), and
 # V21 (icon.svg required, XML <svg> root + viewBox) are all satisfied
 # by these defaults. Edit display_name + description before publish.
@@ -165,7 +170,7 @@ async def fn_default(ctx, **kwargs):
         )
 
     with open(f"{name}/requirements.txt", "w") as f:
-        f.write("imperal-sdk>=4.0.0\n")
+        f.write("imperal-sdk>=5.0.0\n")
 
     with open(f"{name}/tests/__init__.py", "w") as f:
         pass
@@ -212,9 +217,9 @@ async def fn_default(ctx, **kwargs):
     click.echo(f"")
     click.echo(f"Next steps:")
     click.echo(f"  cd {name}")
-    click.echo(f"  pip install 'imperal-sdk>=4.0.0'")
+    click.echo(f"  pip install 'imperal-sdk>=5.0.0'")
     click.echo(f"  imperal build       # generates imperal.json")
-    click.echo(f"  imperal validate    # runs V14-V22+V24 federal validators")
+    click.echo(f"  imperal validate    # runs V1-V24+V31 federal validators")
     click.echo(f"  imperal test        # smoke-test handlers via MockContext")
     click.echo(f"  imperal deploy      # upload to panel.imperal.io/developer")
 
@@ -297,7 +302,7 @@ def build(path: str):
 @cli.command()
 @click.argument("path", default=".")
 def validate(path: str):
-    """Validate extension against SDK v1.0.0 rules."""
+    """Validate extension against the current SDK federal rules (V1-V24+V31)."""
     original_dir = os.getcwd()
     try:
         os.chdir(path)
@@ -346,7 +351,7 @@ def validate(path: str):
                     fix="Fix the JSON syntax error at the reported line",
                 ))
 
-        click.echo(f"\n── Imperal Extension Validator v1.0 {'─' * 40}")
+        click.echo(f"\n── Imperal Extension Validator (SDK {SDK_VERSION}) {'─' * 36}")
         click.echo(f"\nExtension: {report.app_id} v{report.version}")
         click.echo(f"Tools: {report.tool_count}, Functions: {report.function_count}, Events: {report.event_count}")
 

{imperal_sdk-5.4.2 → imperal_sdk-5.4.3}/src/imperal_sdk/secrets/panel_handler.py

@@ -114,7 +114,7 @@ async def builtin_secrets_panel_handler(ctx: Any, **_params: Any) -> dict:
         ))
 
     root = ui.Stack(children=[
-        ui.Heading(f"Secrets · {ext_id}", level=2),
+        ui.Header(f"Secrets · {ext_id}", level=2),
         ui.Text(
             "Credentials this extension needs — API keys, OAuth tokens. "
             "Stored encrypted in Vault; never visible to admins or in logs."

{imperal_sdk-5.4.2 → imperal_sdk-5.4.3}/src/imperal_sdk/testing/mock_context.py

@@ -207,18 +207,22 @@ class MockHTTP:
     """Mock HTTP client. Register responses per URL pattern."""
 
     def __init__(self):
-        self._mocks: list[tuple[str, str, dict, int]] = []
+        self._mocks: list[tuple[str, str, dict, int, dict]] = []
 
-    def mock_get(self, url_pattern: str, response: dict, status: int = 200) -> None:
-        self._mocks.append(("GET", url_pattern, response, status))
+    def mock_get(self, url_pattern: str, response: dict, status: int = 200,
+                 headers: dict | None = None) -> None:
+        self._mocks.append(("GET", url_pattern, response, status, headers or {}))
 
-    def mock_post(self, url_pattern: str, response: dict, status: int = 200) -> None:
-        self._mocks.append(("POST", url_pattern, response, status))
+    def mock_post(self, url_pattern: str, response: dict, status: int = 200,
+                  headers: dict | None = None) -> None:
+        self._mocks.append(("POST", url_pattern, response, status, headers or {}))
 
     async def _find(self, method: str, url: str) -> HTTPResponse:
-        for m, pattern, resp, status in self._mocks:
+        for entry in self._mocks:
+            m, pattern, resp, status = entry[0], entry[1], entry[2], entry[3]
+            hdrs = entry[4] if len(entry) > 4 else {}  # tolerate legacy 4-tuples
             if m == method and pattern in url:
-                return HTTPResponse(status_code=status, body=resp)
+                return HTTPResponse(status_code=status, body=resp, headers=dict(hdrs))
         return HTTPResponse(status_code=404, body={"error": "No mock registered"})
 
     async def get(self, url: str, **kwargs) -> HTTPResponse:

{imperal_sdk-5.4.2 → imperal_sdk-5.4.3}/src/imperal_sdk/types/models.py

@@ -91,13 +91,15 @@ class HTTPResponse:
     body: dict | str | bytes = ""
     headers: dict = field(default_factory=dict)
 
-    def json(self) -> dict:
-        if isinstance(self.body, dict):
+    def json(self) -> dict | list:
+        # Already-parsed JSON (the prod http client parses on content-type: json,
+        # so an array endpoint like WP /wp/v2/posts yields a list body).
+        if isinstance(self.body, (dict, list)):
             return self.body
-        if isinstance(self.body, str):
+        if isinstance(self.body, (str, bytes, bytearray)):
             import json
             return json.loads(self.body)
-        raise ValueError("Body is bytes, cannot parse as JSON")
+        raise ValueError(f"Cannot parse {type(self.body).__name__} body as JSON")
 
     def text(self) -> str:
         if isinstance(self.body, str):

{imperal_sdk-5.4.2 → imperal_sdk-5.4.3}/src/imperal_sdk/validator.py

@@ -728,7 +728,7 @@ def validate_extension(ext) -> ValidationReport:
     #      can be promoted post-soak.
     #
     # Soak severity is env-toggled via IMPERAL_VALIDATOR_V23_SEVERITY
-    # (default "warn"; flip to "error" after third-party adoption).
+    # (default "error" since 2026-06-17 P5-final; set "warn" to opt out).
     try:
         _chat_exts = getattr(ext, "_chat_extensions", {}) or {}
         for _tool_name, _chat_ext in _chat_exts.items():
@@ -744,14 +744,20 @@ def validate_extension(ext) -> ValidationReport:
 def _v23_v24_check_data_model_presence(report, extensions, functions):
     """Apply V23 (read) + V24 (write/destructive) ``data_model`` rules to each
     @chat.function in the given functions dict (name -> FunctionDef)."""
-    _v23_severity = os.environ.get("IMPERAL_VALIDATOR_V23_SEVERITY", "warn").lower()
-    _v23_level = "ERROR" if _v23_severity == "error" else "WARN"
+    _v23_severity = os.environ.get("IMPERAL_VALIDATOR_V23_SEVERITY", "error").lower()
+    # P5-final (2026-06-17): V23 defaults to ERROR. Only an explicit env "warn"
+    # downgrades it; anything else (including unset) resolves to ERROR.
+    _v23_level = "WARN" if _v23_severity == "warn" else "ERROR"
     for fn_name, fn_def in (functions or {}).items():
         _action_type = getattr(fn_def, "action_type", "read")
         _return_model = getattr(fn_def, "_return_model", None)
         if _return_model is not None:
             continue
         if _action_type == "read":
+            # Declarative-UI builders (@chat.function(ui_builder=True)) return ui.*
+            # output, not an SDL entity — exempt from the data_model requirement.
+            if getattr(fn_def, "_ui_builder", False):
+                continue
             report.issues.append(ValidationIssue(
                 rule="V23", level=_v23_level,
                 message=(

{imperal_sdk-5.4.2 → imperal_sdk-5.4.3}/tests/test_cli.py

@@ -3,6 +3,7 @@
 import os
 import pytest
 from click.testing import CliRunner
+from imperal_sdk import __version__
 from imperal_sdk.cli.main import cli
 
 
@@ -10,7 +11,7 @@ def test_cli_version():
     runner = CliRunner()
     result = runner.invoke(cli, ["--version"])
     assert result.exit_code == 0
-    assert "1.0.0" in result.output
+    assert __version__ in result.output  # CLI reports the real SDK version
 
 
 def test_cli_init_chat_template():
@@ -40,7 +41,7 @@ def test_cli_init_chat_template():
             assert "actions_explicit=True" in content
 
         with open("my-test-ext/requirements.txt") as f:
-            assert "imperal-sdk>=4.0.0" in f.read()  # v4.1.9 — was >=1.0.0
+            assert "imperal-sdk>=5.0.0" in f.read()  # scaffold pins current major
 
         with open("my-test-ext/icon.svg") as f:
             svg = f.read()

{imperal_sdk-5.4.2 → imperal_sdk-5.4.3}/tests/test_data_model_kwarg.py

@@ -139,8 +139,8 @@ def test_data_model_none_means_no_return_model():
 
 
 def test_v23_warn_when_read_missing_data_model(monkeypatch):
-    """``IMPERAL_VALIDATOR_V23_SEVERITY=warn`` (default) MUST emit WARN."""
-    monkeypatch.delenv("IMPERAL_VALIDATOR_V23_SEVERITY", raising=False)
+    """``IMPERAL_VALIDATOR_V23_SEVERITY=warn`` (explicit opt-out) MUST emit WARN."""
+    monkeypatch.setenv("IMPERAL_VALIDATOR_V23_SEVERITY", "warn")
     ext = _make_ext()
     chat = _make_chat(ext)
 
@@ -159,6 +159,26 @@ def test_v23_warn_when_read_missing_data_model(monkeypatch):
     assert "data_model" in v23[0].message
 
 
+def test_v23_error_by_default(monkeypatch):
+    """P5-final (2026-06-17): with the env unset, V23 defaults to ERROR."""
+    monkeypatch.delenv("IMPERAL_VALIDATOR_V23_SEVERITY", raising=False)
+    ext = _make_ext()
+    chat = _make_chat(ext)
+
+    @chat.function(
+        name="list_notes",
+        description="List notes — read tool deliberately missing data_model",
+        action_type="read",
+    )
+    async def list_notes(ctx, params: ListNotesParams) -> ActionResult:
+        return ActionResult.success(data={}, summary="ok")
+
+    report = validate_extension(ext)
+    v23 = [i for i in report.errors if i.rule == "V23"]
+    assert len(v23) == 1
+    assert "data_model" in v23[0].message
+
+
 def test_v23_error_when_severity_env_set(monkeypatch):
     """``IMPERAL_VALIDATOR_V23_SEVERITY=error`` MUST promote to ERROR."""
     monkeypatch.setenv("IMPERAL_VALIDATOR_V23_SEVERITY", "error")
@@ -179,6 +199,25 @@ def test_v23_error_when_severity_env_set(monkeypatch):
     assert "data_model" in v23[0].message
 
 
+def test_v23_skips_ui_builder(monkeypatch):
+    """``ui_builder=True`` read tools are exempt from V23 even at severity=error."""
+    monkeypatch.setenv("IMPERAL_VALIDATOR_V23_SEVERITY", "error")
+    ext = _make_ext()
+    chat = _make_chat(ext)
+
+    @chat.function(
+        name="get_panel_data",
+        description="Declarative-UI builder — exempt from V23 via ui_builder flag",
+        action_type="read",
+        ui_builder=True,
+    )
+    async def get_panel_data(ctx, params: ListNotesParams) -> ActionResult:
+        return ActionResult.success(data={}, summary="ok")
+
+    report = validate_extension(ext)
+    assert not [i for i in report.issues if i.rule == "V23"]
+
+
 def test_v23_passes_when_data_model_declared():
     """Reads with ``data_model=`` MUST NOT trigger V23."""
     ext = _make_ext()

imperal_sdk-5.4.3/tests/test_http_json_and_mock.py

@@ -0,0 +1,37 @@
+"""Regression tests: HTTPResponse.json() on JSON-array bodies + MockHTTP headers."""
+import asyncio
+
+from imperal_sdk.types.models import HTTPResponse
+from imperal_sdk.testing.mock_context import MockHTTP
+
+
+def test_json_returns_list_for_array_body():
+    """An array endpoint (e.g. WP /wp/v2/posts) yields a list body — must not raise."""
+    r = HTTPResponse(status_code=200, body=[{"id": 1}, {"id": 2}])
+    assert r.json() == [{"id": 1}, {"id": 2}]
+
+
+def test_json_dict_body():
+    assert HTTPResponse(status_code=200, body={"a": 1}).json() == {"a": 1}
+
+
+def test_json_parses_str_and_bytes():
+    assert HTTPResponse(status_code=200, body="[1, 2]").json() == [1, 2]
+    assert HTTPResponse(status_code=200, body=b'{"a": 1}').json() == {"a": 1}
+
+
+def test_mockhttp_get_sets_response_headers():
+    mh = MockHTTP()
+    mh.mock_get("/wp/v2/posts", [{"id": 1}], status=200, headers={"X-WP-Total": "57"})
+    resp = asyncio.run(mh.get("https://example.com/wp/v2/posts"))
+    assert resp.status_code == 200
+    assert resp.headers.get("X-WP-Total") == "57"
+    assert resp.json() == [{"id": 1}]
+
+
+def test_mockhttp_post_headers_default_empty():
+    mh = MockHTTP()
+    mh.mock_post("/x", {"ok": True})
+    resp = asyncio.run(mh.post("https://example.com/x"))
+    assert resp.headers == {}
+    assert resp.json() == {"ok": True}