@openhands/extensions 0.9.0 → 0.10.0

package/pyproject.toml

@@ -1,8 +1,13 @@
 [project]
 name = "openhands-extensions"
-version = "0.9.0"
+version = "0.10.0"
 description = "OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)"
 requires-python = ">=3.12"
+dependencies = [
+    "deprecation>=2.1,<3",
+    "packaging>=24,<26",
+    "pydantic>=2.10,<3",
+]
 
 [build-system]
 requires = ["hatchling>=1.21"]

package/python/openhands_extensions/__init__.py

@@ -13,12 +13,50 @@ from ._version import __version__
 from .integrations import (
     INTEGRATION_CATALOG_SNAPSHOT,
     get_integration_catalog_entry,
+    get_integration_catalog_entry_model,
     list_integration_catalog,
+    list_integration_catalog_models,
+)
+from .integration_models import (
+    HttpConnectionOption,
+    IntegrationAuthConfig,
+    IntegrationCatalogEntry,
+    IntegrationCatalogSnapshot,
+    IntegrationConnectionOption,
+    IntegrationConnectionModel,
+    IntegrationHttpConfig,
+    IntegrationIdentityMapping,
+    IntegrationOAuthConfig,
+    IntegrationResourceDiscovery,
+    IntegrationTransport,
+    McpConnectionOption,
+    MarketplaceField,
+    SseTransport,
+    StdioTransport,
+    StreamableHttpTransport,
 )
 
 __all__ = [
     "INTEGRATION_CATALOG_SNAPSHOT",
+    "HttpConnectionOption",
+    "IntegrationAuthConfig",
+    "IntegrationCatalogEntry",
+    "IntegrationCatalogSnapshot",
+    "IntegrationConnectionOption",
+    "IntegrationConnectionModel",
+    "IntegrationHttpConfig",
+    "IntegrationIdentityMapping",
+    "IntegrationOAuthConfig",
+    "IntegrationResourceDiscovery",
+    "IntegrationTransport",
+    "MarketplaceField",
+    "McpConnectionOption",
+    "SseTransport",
+    "StdioTransport",
+    "StreamableHttpTransport",
     "__version__",
     "get_integration_catalog_entry",
+    "get_integration_catalog_entry_model",
     "list_integration_catalog",
+    "list_integration_catalog_models",
 ]

package/python/openhands_extensions/_version.py

@@ -16,8 +16,8 @@ from importlib.metadata import PackageNotFoundError, version
 
 #: Fallback used only when the package is not installed (no dist metadata).
 #: Kept in lock-step with pyproject.toml/package.json by the version test.
-# x-release-please-update-version
-_FALLBACK_VERSION = "0.9.0"
+# x-release-please-version
+_FALLBACK_VERSION = "0.10.0"
 
 try:
     __version__: str = version("openhands-extensions")

package/python/openhands_extensions/deprecation.py

@@ -0,0 +1,159 @@
+"""Versioned deprecation helpers for OpenHands extensions.
+
+This module intentionally mirrors ``openhands.sdk.utils.deprecation`` so public
+extension APIs use the same decorator, runtime warning, and model-input
+compatibility behavior as the SDK.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable
+from datetime import date
+from functools import cache
+from importlib.metadata import PackageNotFoundError, version as get_version
+from typing import Any, TypeVar, cast
+
+from deprecation import (
+    DeprecatedWarning,
+    UnsupportedWarning,
+    deprecated as _deprecated,
+)
+from packaging import version as pkg_version
+
+
+_FuncT = TypeVar("_FuncT", bound=Callable[..., Any])
+
+
+@cache
+def _current_version() -> str:
+    try:
+        return get_version("openhands-extensions")
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
+def deprecated(
+    *,
+    deprecated_in: str,
+    removed_in: str | date | None,
+    current_version: str | None = None,
+    details: str = "",
+) -> Callable[[_FuncT], _FuncT]:
+    """Return a decorator that deprecates a callable with explicit metadata."""
+    base_decorator = _deprecated(
+        deprecated_in=deprecated_in,
+        removed_in=removed_in,
+        current_version=current_version or _current_version(),
+        details=details,
+    )
+
+    def decorator(func: _FuncT) -> _FuncT:
+        return cast(_FuncT, base_decorator(func))
+
+    return decorator
+
+
+def _should_warn(
+    *,
+    deprecated_in: str | None,
+    removed_in: str | date | None,
+    current_version: str | None,
+) -> tuple[bool, bool]:
+    is_deprecated = False
+    is_unsupported = False
+
+    if isinstance(removed_in, date):
+        if date.today() >= removed_in:
+            is_unsupported = True
+        else:
+            is_deprecated = True
+    elif current_version:
+        current = pkg_version.parse(current_version)
+        if removed_in and current >= pkg_version.parse(str(removed_in)):
+            is_unsupported = True
+        elif deprecated_in and current >= pkg_version.parse(deprecated_in):
+            is_deprecated = True
+    else:
+        is_deprecated = True
+
+    return is_deprecated, is_unsupported
+
+
+def warn_deprecated(
+    feature: str,
+    *,
+    deprecated_in: str,
+    removed_in: str | date | None,
+    current_version: str | None = None,
+    details: str = "",
+    stacklevel: int = 2,
+) -> None:
+    """Emit a deprecation warning for dynamic access to a legacy feature."""
+    current_version = current_version or _current_version()
+    is_deprecated, is_unsupported = _should_warn(
+        deprecated_in=deprecated_in,
+        removed_in=removed_in,
+        current_version=current_version,
+    )
+
+    if not (is_deprecated or is_unsupported):
+        return
+
+    warning_cls = UnsupportedWarning if is_unsupported else DeprecatedWarning
+    warning = warning_cls(feature, deprecated_in, removed_in, details)
+    warnings.warn(warning, stacklevel=stacklevel)
+
+
+def warn_cleanup(
+    workaround: str,
+    *,
+    cleanup_by: str | date,
+    current_version: str | None = None,
+    details: str = "",
+    stacklevel: int = 2,
+) -> None:
+    """Emit a warning when a temporary workaround has reached its deadline."""
+    current_version = current_version or _current_version()
+
+    should_cleanup = False
+    if isinstance(cleanup_by, date):
+        should_cleanup = date.today() >= cleanup_by
+    else:
+        try:
+            current = pkg_version.parse(current_version)
+            target = pkg_version.parse(str(cleanup_by))
+            should_cleanup = current >= target
+        except pkg_version.InvalidVersion:
+            pass
+
+    if should_cleanup:
+        message = (
+            f"Cleanup required: {workaround}. "
+            f"This workaround was scheduled for removal by {cleanup_by}."
+        )
+        if details:
+            message += f" {details}"
+        warnings.warn(message, UserWarning, stacklevel=stacklevel)
+
+
+def handle_deprecated_model_fields(
+    data: Any,
+    deprecated_fields: tuple[str, ...],
+) -> Any:
+    """Remove permanently supported legacy fields from Pydantic model input."""
+    if not isinstance(data, dict):
+        return data
+
+    for field in deprecated_fields:
+        data.pop(field, None)
+
+    return data
+
+
+__all__ = [
+    "deprecated",
+    "warn_deprecated",
+    "warn_cleanup",
+    "handle_deprecated_model_fields",
+]

package/python/openhands_extensions/integration_models.py

@@ -0,0 +1,233 @@
+"""Typed models for the OpenHands integration catalog.
+
+The hand-authored JSON files under ``integrations/catalog`` remain the source
+of truth. These models provide a Python representation of the public catalog
+contract defined by ``integrations/catalog.schema.json`` and
+``integrations/index.d.ts``.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+
+NonEmptyString = Annotated[str, Field(min_length=1)]
+HttpsUrl = Annotated[str, Field(pattern=r"^https://", min_length=8)]
+IdentityPath = Annotated[
+    str,
+    Field(pattern=r"^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$", min_length=1),
+]
+IntegrationAuthStrategy = Literal["none", "api_key", "bearer", "basic", "oauth2"]
+IntegrationProvider = Literal["mcp", "http"]
+
+
+class CatalogModel(BaseModel):
+    """Base model for strict, portable catalog data."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    @model_validator(mode="before")
+    @classmethod
+    def reject_explicit_nulls(cls, values: Any) -> Any:
+        """Match the JSON Schema: optional fields may be omitted, never null."""
+        if not isinstance(values, dict):
+            return values
+
+        null_fields = [field for field, value in values.items() if value is None]
+        if null_fields:
+            raise ValueError(
+                "Catalog fields must be omitted instead of set to null: "
+                f"{', '.join(null_fields)}"
+            )
+        return values
+
+
+class MarketplaceField(CatalogModel):
+    key: NonEmptyString
+    label: NonEmptyString
+    type: Literal["text", "password"]
+    placeholder: str | None = None
+    helperText: str | None = None
+    helperLink: HttpsUrl | None = None
+    required: bool
+
+    @model_validator(mode="after")
+    def password_fields_have_help(self) -> MarketplaceField:
+        if self.type == "password" and not self.helperText:
+            raise ValueError("Password marketplace fields require helperText.")
+        return self
+
+
+class StreamableHttpTransport(CatalogModel):
+    kind: Literal["shttp"]
+    url: HttpsUrl
+    apiKeyOptional: bool | None = None
+    headerFields: list[MarketplaceField] | None = None
+    urlEditable: bool | None = None
+
+
+class SseTransport(CatalogModel):
+    kind: Literal["sse"]
+    url: HttpsUrl
+    apiKeyOptional: bool | None = None
+    headerFields: list[MarketplaceField] | None = None
+    urlEditable: bool | None = None
+
+
+class StdioTransport(CatalogModel):
+    kind: Literal["stdio"]
+    serverName: NonEmptyString
+    command: NonEmptyString
+    args: list[str]
+    envFields: list[MarketplaceField] | None = None
+    argFields: list[MarketplaceField] | None = None
+
+
+IntegrationTransport = Annotated[
+    StreamableHttpTransport | SseTransport | StdioTransport,
+    Field(discriminator="kind"),
+]
+
+
+class IntegrationOAuthConfig(CatalogModel):
+    authorizationUrl: HttpsUrl | None = None
+    tokenUrl: HttpsUrl | None = None
+    scopes: list[NonEmptyString] | None = None
+    optionalScopes: list[NonEmptyString] | None = None
+    toolScopes: list[NonEmptyString] | None = None
+    scopeSeparator: Literal["space", "comma"] | None = None
+    pkce: bool | None = None
+    clientAuthentication: Literal["basic", "body", "none"] | None = None
+    registrationUrl: HttpsUrl | None = None
+    additionalAuthorizationParams: dict[str, str] | None = None
+    additionalTokenParams: dict[str, str] | None = None
+
+
+class IntegrationAuthConfig(CatalogModel):
+    strategy: IntegrationAuthStrategy
+    authModes: list[IntegrationAuthStrategy] | None = Field(default=None, min_length=1)
+    credentialLabel: NonEmptyString | None = None
+    credentialPlaceholder: NonEmptyString | None = None
+    credentialHelp: NonEmptyString | None = None
+    credentialSecretName: NonEmptyString | None = None
+    saveCredentialAsSecretByDefault: bool | None = None
+    apiKeyHeaderName: NonEmptyString | None = None
+    apiKeyOptional: bool | None = None
+    oauth: IntegrationOAuthConfig | None = None
+
+
+class IntegrationHttpConfig(CatalogModel):
+    apiBaseUrl: HttpsUrl
+    openApiUrl: HttpsUrl
+
+
+class IntegrationIdentityMapping(CatalogModel):
+    source: Literal["oauth_token_response", "access_token_claims", "identity_api"]
+    endpoint: HttpsUrl | None = None
+    externalPrincipalIdPath: IdentityPath
+    externalTenantIdPath: IdentityPath | None = None
+    externalResourceIdPath: IdentityPath | None = None
+    resourceNamePath: IdentityPath | None = None
+    resourceUrlPath: IdentityPath | None = None
+
+    @model_validator(mode="after")
+    def identity_api_requires_endpoint(self) -> IntegrationIdentityMapping:
+        if self.source == "identity_api" and not self.endpoint:
+            raise ValueError("identity_api mappings require an endpoint.")
+        if self.source != "identity_api" and self.endpoint:
+            raise ValueError("Only identity_api mappings may define an endpoint.")
+        return self
+
+
+class IntegrationResourceDiscovery(CatalogModel):
+    endpoint: HttpsUrl
+    itemsPath: IdentityPath | None = None
+    externalResourceIdPath: IdentityPath
+    resourceNamePath: IdentityPath | None = None
+    resourceUrlPath: IdentityPath | None = None
+
+
+class IntegrationConnectionModel(CatalogModel):
+    principalType: Literal["user", "bot", "service_account", "application"]
+    credentialScope: Literal["account", "tenant", "organization", "resource"]
+    resourceType: NonEmptyString
+    resourceCardinality: Literal["one", "many"]
+    selectionMode: Literal["automatic", "post_auth", "runtime"]
+    identityMapping: IntegrationIdentityMapping | None = None
+    resourceDiscovery: IntegrationResourceDiscovery | None = None
+
+    @model_validator(mode="after")
+    def post_auth_requires_resource_discovery(self) -> IntegrationConnectionModel:
+        if self.selectionMode == "post_auth" and not self.resourceDiscovery:
+            raise ValueError("post_auth connections require resourceDiscovery.")
+        return self
+
+
+class McpConnectionOption(CatalogModel):
+    id: NonEmptyString
+    provider: Literal["mcp"]
+    transport: IntegrationTransport
+    auth: IntegrationAuthConfig
+    connectionModel: IntegrationConnectionModel | None = None
+
+
+class HttpConnectionOption(CatalogModel):
+    id: NonEmptyString
+    provider: Literal["http"]
+    http: IntegrationHttpConfig
+    auth: IntegrationAuthConfig
+    connectionModel: IntegrationConnectionModel | None = None
+
+
+IntegrationConnectionOption = Annotated[
+    McpConnectionOption | HttpConnectionOption,
+    Field(discriminator="provider"),
+]
+
+
+class IntegrationCatalogEntry(CatalogModel):
+    id: NonEmptyString
+    name: NonEmptyString
+    description: NonEmptyString
+    categories: list[NonEmptyString] | None = Field(default=None, min_length=1)
+    appUrl: HttpsUrl | None = None
+    docsUrl: HttpsUrl
+    notes: NonEmptyString | None = None
+    iconBg: NonEmptyString | None = None
+    iconColor: NonEmptyString | None = None
+    logoUrl: HttpsUrl | None = None
+    keywords: list[NonEmptyString] | None = None
+    popularityRank: int | None = Field(default=None, ge=0)
+    installHint: NonEmptyString | None = None
+    connectionOptions: list[IntegrationConnectionOption] = Field(min_length=1)
+
+    @field_validator("categories", "keywords")
+    @classmethod
+    def list_values_are_unique(
+        cls, values: list[NonEmptyString] | None
+    ) -> list[NonEmptyString] | None:
+        if values is not None and len(values) != len(set(values)):
+            raise ValueError("Catalog list values must be unique.")
+        return values
+
+    @model_validator(mode="after")
+    def validate_auth_requirements(self) -> IntegrationCatalogEntry:
+        for option in self.connectionOptions:
+            if option.provider == "http" and option.auth.strategy == "api_key":
+                if not option.auth.apiKeyHeaderName:
+                    raise ValueError(
+                        "HTTP API-key connections require apiKeyHeaderName."
+                    )
+            if option.provider == "http" and option.auth.strategy == "oauth2":
+                oauth = option.auth.oauth
+                if not oauth or not oauth.authorizationUrl or not oauth.tokenUrl:
+                    raise ValueError(
+                        "HTTP OAuth connections require authorizationUrl and tokenUrl."
+                    )
+        return self
+
+
+class IntegrationCatalogSnapshot(CatalogModel):
+    integrations: list[IntegrationCatalogEntry]

package/python/openhands_extensions/integrations.py

@@ -14,10 +14,16 @@ from importlib import resources
 from pathlib import Path
 from typing import Any, Iterable
 
+from .deprecation import deprecated
+from .integration_models import IntegrationCatalogEntry
+
+
 __all__ = [
     "INTEGRATION_CATALOG_SNAPSHOT",
     "get_integration_catalog_entry",
+    "get_integration_catalog_entry_model",
     "list_integration_catalog",
+    "list_integration_catalog_models",
 ]
 
 
@@ -45,7 +51,14 @@ def _read_json(path: Any) -> dict[str, Any]:
 def _integrations() -> tuple[dict[str, Any], ...]:
     entries = [_read_json(path) for path in _catalog_files()]
     entries.sort(
-        key=lambda entry: (-(entry.get("popularityRank") if entry.get("popularityRank") is not None else -1), entry["id"]),
+        key=lambda entry: (
+            -(
+                entry.get("popularityRank")
+                if entry.get("popularityRank") is not None
+                else -1
+            ),
+            entry["id"],
+        ),
     )
     return tuple(entries)
 
@@ -56,7 +69,9 @@ def _integration_by_id() -> dict[str, dict[str, Any]]:
 
 
 def _entry_supports_mcp(entry: dict[str, Any]) -> bool:
-    return any(option.get("provider") == "mcp" for option in entry.get("connectionOptions", []))
+    return any(
+        option.get("provider") == "mcp" for option in entry.get("connectionOptions", [])
+    )
 
 
 def _entry_supports_oauth(entry: dict[str, Any]) -> bool:
@@ -66,11 +81,20 @@ def _entry_supports_oauth(entry: dict[str, Any]) -> bool:
     )
 
 
+@deprecated(
+    deprecated_in="0.10.0",
+    removed_in="0.12.0",
+    details="Use list_integration_catalog_models() for validated Pydantic models.",
+)
 def list_integration_catalog(
     mcp: bool | None = None,
     oauth: bool | None = None,
 ) -> list[dict[str, Any]]:
-    """Return the integration catalog, optionally filtered by connector type."""
+    """Return raw catalog dictionaries, optionally filtered by connector type.
+
+    Deprecated since v0.10.0 and scheduled for removal in v0.12.0.
+    Use :func:`list_integration_catalog_models` instead.
+    """
     result = []
     for entry in _integrations():
         if mcp is not None and _entry_supports_mcp(entry) != mcp:
@@ -81,12 +105,43 @@ def list_integration_catalog(
     return result
 
 
+def list_integration_catalog_models(
+    mcp: bool | None = None,
+    oauth: bool | None = None,
+) -> list[IntegrationCatalogEntry]:
+    """Return typed, validated integration catalog entries.
+
+    ``list_integration_catalog`` remains available for callers that need the
+    original JSON-compatible dictionaries. New Python consumers should prefer
+    this function for a stable, validated contract.
+    """
+    return [
+        IntegrationCatalogEntry.model_validate(entry)
+        for entry in list_integration_catalog(mcp=mcp, oauth=oauth)
+    ]
+
+
+@deprecated(
+    deprecated_in="0.10.0",
+    removed_in="0.12.0",
+    details="Use get_integration_catalog_entry_model() for a validated Pydantic model.",
+)
 def get_integration_catalog_entry(id: str) -> dict[str, Any] | None:
-    """Return one integration catalog entry by id, or ``None``."""
+    """Return one raw catalog dictionary by id, or ``None``.
+
+    Deprecated since v0.10.0 and scheduled for removal in v0.12.0.
+    Use :func:`get_integration_catalog_entry_model` instead.
+    """
     entry = _integration_by_id().get(id)
     return copy.deepcopy(entry) if entry is not None else None
 
 
+def get_integration_catalog_entry_model(id: str) -> IntegrationCatalogEntry | None:
+    """Return one typed catalog entry, or ``None`` when it does not exist."""
+    entry = get_integration_catalog_entry(id)
+    return IntegrationCatalogEntry.model_validate(entry) if entry is not None else None
+
+
 INTEGRATION_CATALOG_SNAPSHOT: dict[str, Any] = {
     "integrations": copy.deepcopy(list(_integrations()))
 }