stackos-connectors 0.1.0__py3-none-any.whl

stackos_connectors/__init__.py

@@ -0,0 +1,99 @@
+"""Execute a named connector action using plain data and resolved authentication."""
+
+from collections.abc import Mapping
+from functools import lru_cache
+from typing import Any
+
+from .contracts import (
+    ActionDefinition,
+    AuthMethodDefinition,
+    CallOptions,
+    Connector,
+    ConnectorAuth,
+    ConnectorFile,
+    ConnectorRequest,
+    ConnectorResult,
+    NativeSession,
+    RateLimiter,
+    ValidationIssue,
+)
+from .errors import ConnectorError, IntegrationDownError, RateLimitedError, ValidationError
+from .registry import ConnectorClient, ConnectorRegistry
+
+
+@lru_cache(maxsize=1)
+def get_default_client() -> ConnectorClient:
+    """Load reviewed builtin descriptions on first use, without provider imports."""
+    from .catalog import default_registry
+
+    return ConnectorClient(registry=default_registry())
+
+
+async def execute(
+    connector: str,
+    action: str,
+    data: Mapping[str, Any],
+    auth: ConnectorAuth | Mapping[str, Any] | None = None,
+    options: CallOptions | None = None,
+) -> ConnectorResult:
+    return await get_default_client().execute(connector, action, data, auth, options)
+
+
+def validate(
+    connector: str,
+    action: str,
+    data: Mapping[str, Any],
+    auth: ConnectorAuth | Mapping[str, Any] | None = None,
+    options: CallOptions | None = None,
+) -> list[ValidationIssue]:
+    return get_default_client().validate(connector, action, data, auth, options)
+
+
+def validate_data(connector: str, action: str, data: Mapping[str, Any]) -> list[ValidationIssue]:
+    return get_default_client().validate_data(connector, action, data)
+
+
+def estimate_cost(
+    connector: str,
+    action: str,
+    data: Mapping[str, Any],
+    auth: ConnectorAuth | Mapping[str, Any] | None = None,
+    options: CallOptions | None = None,
+) -> int:
+    return get_default_client().estimate_cost(connector, action, data, auth, options)
+
+
+def list_connectors() -> list[str]:
+    return get_default_client().list_connectors()
+
+
+def describe(connector: str, action: str | None = None) -> dict[str, Any]:
+    return get_default_client().describe(connector, action)
+
+
+__all__ = [
+    "ActionDefinition",
+    "AuthMethodDefinition",
+    "CallOptions",
+    "Connector",
+    "ConnectorAuth",
+    "ConnectorClient",
+    "ConnectorError",
+    "ConnectorFile",
+    "ConnectorRegistry",
+    "ConnectorRequest",
+    "ConnectorResult",
+    "IntegrationDownError",
+    "NativeSession",
+    "RateLimitedError",
+    "RateLimiter",
+    "ValidationError",
+    "ValidationIssue",
+    "describe",
+    "estimate_cost",
+    "execute",
+    "get_default_client",
+    "list_connectors",
+    "validate",
+    "validate_data",
+]

stackos_connectors/catalog/index.json

@@ -0,0 +1,54 @@
+{
+  "schema_version": "stackos.connectors.index.v1",
+  "connectors": [
+    "connectors/ahrefs/catalog.json",
+    "connectors/aignc/catalog.json",
+    "connectors/alibaba_wan/catalog.json",
+    "connectors/apollo/catalog.json",
+    "connectors/aws_s3/catalog.json",
+    "connectors/byteplus_seedance/catalog.json",
+    "connectors/byteplus_seedream/catalog.json",
+    "connectors/clay/catalog.json",
+    "connectors/cloudflare/catalog.json",
+    "connectors/dataforseo/catalog.json",
+    "connectors/firecrawl/catalog.json",
+    "connectors/ftp/catalog.json",
+    "connectors/ghost/catalog.json",
+    "connectors/google_ads/catalog.json",
+    "connectors/google_analytics/catalog.json",
+    "connectors/google_gemini_image/catalog.json",
+    "connectors/google_indexing/catalog.json",
+    "connectors/google_search_console/catalog.json",
+    "connectors/google_tag_manager/catalog.json",
+    "connectors/google_veo/catalog.json",
+    "connectors/google_workspace/catalog.json",
+    "connectors/http/catalog.json",
+    "connectors/hubspot/catalog.json",
+    "connectors/ideogram/catalog.json",
+    "connectors/imap/catalog.json",
+    "connectors/jina/catalog.json",
+    "connectors/kling_video/catalog.json",
+    "connectors/linear/catalog.json",
+    "connectors/meta_ads/catalog.json",
+    "connectors/microsoft_365/catalog.json",
+    "connectors/openai_images/catalog.json",
+    "connectors/openrouter/catalog.json",
+    "connectors/outreach/catalog.json",
+    "connectors/pipedrive/catalog.json",
+    "connectors/reddit/catalog.json",
+    "connectors/reve/catalog.json",
+    "connectors/salesforce/catalog.json",
+    "connectors/salesloft/catalog.json",
+    "connectors/serper/catalog.json",
+    "connectors/shopify/catalog.json",
+    "connectors/sitemap/catalog.json",
+    "connectors/slack_bot/catalog.json",
+    "connectors/smtp/catalog.json",
+    "connectors/stripe/catalog.json",
+    "connectors/taboola/catalog.json",
+    "connectors/telegram/catalog.json",
+    "connectors/trackbooth/catalog.json",
+    "connectors/wordpress/catalog.json",
+    "connectors/xai_imagine/catalog.json"
+  ]
+}

stackos_connectors/catalog/schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$defs": {
+    "icon": {
+      "type": "object",
+      "required": ["path", "media_type", "kind"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {"type": "string", "pattern": "^(?:[A-Za-z0-9_][A-Za-z0-9_-]*/)*[A-Za-z0-9_][A-Za-z0-9_-]*\\.(?:svg|png|jpg|jpeg|webp)$", "not": {"pattern": "[\\r\\n]"}},
+        "media_type": {"enum": ["image/svg+xml", "image/png", "image/jpeg", "image/webp"]},
+        "kind": {"enum": ["icon", "wordmark", "wordmark-dark", "wordmark-inverse", "fallback"]}
+      },
+      "allOf": [
+        {"if": {"properties": {"path": {"pattern": "\\.svg$"}}}, "then": {"properties": {"media_type": {"const": "image/svg+xml"}}}},
+        {"if": {"properties": {"path": {"pattern": "\\.png$"}}}, "then": {"properties": {"media_type": {"const": "image/png"}}}},
+        {"if": {"properties": {"path": {"pattern": "\\.jpe?g$"}}}, "then": {"properties": {"media_type": {"const": "image/jpeg"}}}},
+        {"if": {"properties": {"path": {"pattern": "\\.webp$"}}}, "then": {"properties": {"media_type": {"const": "image/webp"}}}}
+      ]
+    },
+    "presentation_metadata": {
+      "type": "object",
+      "properties": {"icon": {"$ref": "#/$defs/icon"}}
+    },
+    "index": {
+      "type": "object",
+      "required": ["schema_version", "connectors"],
+      "additionalProperties": false,
+      "properties": {
+        "schema_version": {"const": "stackos.connectors.index.v1"},
+        "connectors": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^(?:[a-z0-9][a-z0-9_-]*/)*[a-z0-9][a-z0-9_-]*\\.json$"}}
+      }
+    },
+    "auth_method": {
+      "type": "object",
+      "required": ["key", "fields_schema"],
+      "properties": {
+        "key": {"type": "string", "minLength": 1},
+        "description": {"type": "string"},
+        "payload_format": {"enum": ["raw", "json", "none"]},
+        "payload_field": {"type": "string", "minLength": 1},
+        "fields_schema": {"type": "object"},
+        "config_schema": {"type": "object"}
+      }
+    },
+    "action": {
+      "type": "object",
+      "required": ["key", "operation", "input_schema", "auth_methods", "config"],
+      "properties": {
+        "key": {"type": "string", "minLength": 1},
+        "operation": {"type": "string", "minLength": 1},
+        "description": {"type": "string"},
+        "guidance": {"type": "string"},
+        "icon": {"$ref": "#/$defs/icon"},
+        "input_schema": {"type": "object"},
+        "output_schema": {"type": "object"},
+        "auth_methods": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}},
+        "auth_optional": {"type": "boolean"},
+        "config": {"type": "object"},
+        "examples": {"type": "array", "items": {"type": "object"}},
+        "metadata": {"$ref": "#/$defs/presentation_metadata"}
+      }
+    },
+    "connector": {
+      "type": "object",
+      "required": ["schema_version", "connector", "name", "description", "auth_methods", "actions"],
+      "properties": {
+        "schema_version": {"const": "stackos.connector.v1"},
+        "connector": {"type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$"},
+        "name": {"type": "string", "minLength": 1},
+        "description": {"type": "string"},
+        "icon": {"$ref": "#/$defs/icon"},
+        "implementation": {"type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_.]*:[A-Za-z_][A-Za-z0-9_]*$"},
+        "auth_methods": {"type": "array", "items": {"$ref": "#/$defs/auth_method"}},
+        "actions": {"type": "array", "items": {"$ref": "#/$defs/action"}},
+        "metadata": {"$ref": "#/$defs/presentation_metadata"}
+      }
+    }
+  },
+  "$ref": "#/$defs/connector"
+}

stackos_connectors/catalog.py

@@ -0,0 +1,160 @@
+"""Load portable connector descriptions and lazy bindings from packaged JSON.
+
+Provider packages use ``load_registry("connectors/provider/catalog.json")``;
+the default registry reads the reviewed resource list in ``catalog/index.json``.
+Execution auth schemas describe resolved credentials, while setup metadata is
+retained separately for discovery and never used as an execution schema.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable, Mapping
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from typing import Any
+
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import SchemaError
+
+from .contracts import ActionDefinition, AuthMethodDefinition, freeze, thaw
+from .registry import ConnectorRegistry
+
+_RESOURCE_PATH = re.compile(r"(?:[a-z0-9][a-z0-9_-]*/)*[a-z0-9][a-z0-9_-]*\.json\Z")
+_ACTION_FIELDS = {
+    "key",
+    "operation",
+    "input_schema",
+    "output_schema",
+    "auth_methods",
+    "config",
+    "description",
+    "guidance",
+    "examples",
+    "metadata",
+    "auth_optional",
+}
+
+
+def _read(resource: Traversable) -> Any:
+    try:
+        return json.loads(resource.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise ValueError(f"could not read connector catalog resource: {resource.name}") from exc
+
+
+def _validate(document: Any, definition: str) -> None:
+    schema = _read(files("stackos_connectors").joinpath("catalog", "schema.json"))
+    validator = Draft202012Validator({"$ref": f"#/$defs/{definition}", "$defs": schema["$defs"]})
+    error = next(validator.iter_errors(document), None)
+    if error is not None:
+        path = ".".join(str(item) for item in error.absolute_path) or "$"
+        raise ValueError(f"invalid connector catalog {definition} at {path}")
+
+
+def registry_from_documents(documents: Iterable[Mapping[str, Any]]) -> ConnectorRegistry:
+    """Build one immutable registry without importing any provider implementation."""
+    actions: list[ActionDefinition] = []
+    implementations: dict[str, str] = {}
+    metadata: dict[str, dict[str, Any]] = {}
+    for original in documents:
+        document = thaw(freeze(original))
+        _validate(document, "connector")
+        key = document["connector"]
+        if key in metadata:
+            raise ValueError(f"duplicate connector registration: {key}")
+        methods: dict[str, AuthMethodDefinition] = {}
+        for method in document["auth_methods"]:
+            if method["key"] in methods:
+                raise ValueError(f"duplicate auth method registration: {key}/{method['key']}")
+            methods[method["key"]] = AuthMethodDefinition(
+                key=method["key"],
+                fields_schema=method["fields_schema"],
+                config_schema=method.get("config_schema", {"type": "object"}),
+                description=method.get("description", ""),
+            )
+            try:
+                Draft202012Validator.check_schema(method["fields_schema"])
+                Draft202012Validator.check_schema(method.get("config_schema", {"type": "object"}))
+            except SchemaError as exc:
+                raise ValueError("invalid connector auth schema") from exc
+        metadata[key] = {
+            **document.get("metadata", {}),
+            **{
+                name: value
+                for name, value in document.items()
+                if name not in {"connector", "implementation", "actions", "metadata"}
+            },
+        }
+        if binding := document.get("implementation"):
+            implementations[key] = binding
+        for action in document["actions"]:
+            unknown = set(action["auth_methods"]) - methods.keys()
+            if unknown:
+                raise ValueError(f"action selects an unknown auth method: {key}/{action['key']}")
+            extra = {
+                **action.get("metadata", {}),
+                **{name: value for name, value in action.items() if name not in _ACTION_FIELDS},
+            }
+            actions.append(
+                ActionDefinition(
+                    connector=key,
+                    key=action["key"],
+                    operation=action["operation"],
+                    input_schema=action["input_schema"],
+                    output_schema=action.get("output_schema", {}),
+                    auth_methods=tuple(methods[name] for name in action["auth_methods"]),
+                    config=action["config"],
+                    description=action.get("description", ""),
+                    guidance=action.get("guidance", ""),
+                    examples=tuple(action.get("examples", [])),
+                    metadata=extra,
+                    auth_optional=action.get("auth_optional", False),
+                )
+            )
+    try:
+        return ConnectorRegistry(
+            actions=actions,
+            implementations=implementations,
+            connector_metadata=metadata,
+        )
+    except SchemaError as exc:
+        raise ValueError("invalid connector action schema") from exc
+
+
+def load_registry(*resource_names: str, root: Traversable | None = None) -> ConnectorRegistry:
+    """Read explicit provider resources, or the index when none are named.
+
+    ``root`` is an explicit local resource root, useful for a consumer's declared
+    catalog and for deterministic tests. Resource names are package-relative JSON
+    paths; absolute paths, empty segments and traversal are rejected.
+    """
+    source = root if root is not None else files("stackos_connectors")
+    if not resource_names:
+        index = _read(source.joinpath("catalog", "index.json"))
+        _validate(index, "index")
+        resource_names = tuple(index["connectors"])
+    for name in resource_names:
+        if not _RESOURCE_PATH.fullmatch(name) or name.rsplit("/", 1)[-1] in {
+            "index.json",
+            "schema.json",
+        }:
+            raise ValueError("invalid connector catalog resource name")
+    if len(set(resource_names)) != len(resource_names):
+        raise ValueError("duplicate connector catalog resource name")
+    registry = registry_from_documents(
+        _read(source.joinpath(*name.split("/"))) for name in resource_names
+    )
+    presentations = [*registry.connector_metadata.values()]
+    presentations.extend(action.metadata for action in registry.actions.values())
+    for metadata in presentations:
+        if (icon := metadata.get("icon")) and not source.joinpath(
+            *icon["path"].split("/")
+        ).is_file():
+            raise ValueError(f"missing connector icon resource: {icon['path']}")
+    return registry
+
+
+def default_registry() -> ConnectorRegistry:
+    return load_registry()

stackos_connectors/connectors/__init__.py

@@ -0,0 +1 @@
+"""connectors components."""

stackos_connectors/connectors/ahrefs/__init__.py

@@ -0,0 +1 @@
+"""connectors ahrefs components."""

stackos_connectors/connectors/ahrefs/actions.py

@@ -0,0 +1,107 @@
+"""Named native Ahrefs API requests; admission decisions belong to the caller."""
+
+from __future__ import annotations
+
+from contextlib import nullcontext
+
+import httpx
+
+from stackos_connectors.connectors.ahrefs.integration import AhrefsIntegration
+from stackos_connectors.contracts import ConnectorRequest, ConnectorResult, ValidationIssue
+from stackos_connectors.errors import ValidationError
+from stackos_connectors.shared.provider_utils import credential_value
+from stackos_connectors.shared.vendor_utils import (
+    issue,
+    optional_str,
+    required_str,
+    unknown_operation,
+)
+
+AHREFS_DEFAULT_ROWS = 100
+AHREFS_MODE_VALUES = ("exact", "prefix", "domain", "subdomains")
+
+
+def _positive_limit(payload, issues):
+    value = payload.get("limit")
+    if value is not None and (not isinstance(value, int) or isinstance(value, bool) or value < 1):
+        issues.append(issue("$.limit", "limit must be a positive integer", "range"))
+
+
+class AhrefsActionConnector:
+    key = "ahrefs"
+
+    def validate(self, request: ConnectorRequest) -> list[ValidationIssue]:
+        payload = request.input_json
+        issues = []
+        match request.operation:
+            case "limits_and_usage":
+                pass
+            case "competitor.keywords" | "keywords_for_site":
+                required_str(payload, "target", issues)
+                optional_str(payload, "country", issues)
+                optional_str(payload, "date", issues)
+                _positive_limit(payload, issues)
+            case "backlink.research" | "top_backlinks":
+                required_str(payload, "target", issues)
+                optional_str(payload, "mode", issues)
+                if (
+                    isinstance(payload.get("mode"), str)
+                    and payload["mode"] not in AHREFS_MODE_VALUES
+                ):
+                    issues.append(
+                        issue(
+                            "$.mode",
+                            "mode must be one of exact, prefix, domain, subdomains",
+                            "enum_mismatch",
+                        )
+                    )
+                _positive_limit(payload, issues)
+            case _:
+                issues.extend(unknown_operation(request))
+        return issues
+
+    def estimate_cost_cents(self, _request: ConnectorRequest) -> int:
+        return 0
+
+    async def execute(self, request: ConnectorRequest) -> ConnectorResult:
+        payload = request.input_json
+        async with (
+            nullcontext(request.options.http)
+            if request.options.http is not None
+            else httpx.AsyncClient(
+                timeout=request.options.timeout if request.options.timeout is not None else 60.0
+            )
+        ) as http:
+            client = AhrefsIntegration(
+                payload=credential_value(request, "api_key").encode(),
+                http=http,
+                rate_limiter=request.options.rate_limiter,
+                timeout=request.options.timeout,
+            )
+            match request.operation:
+                case "limits_and_usage":
+                    result = await client.limits_and_usage()
+                case "competitor.keywords" | "keywords_for_site":
+                    result = await client.keywords_for_site(
+                        target=str(payload["target"]),
+                        country=str(payload.get("country", "us")),
+                        limit=int(payload.get("limit", AHREFS_DEFAULT_ROWS)),
+                        date_=payload.get("date"),
+                    )
+                case "backlink.research" | "top_backlinks":
+                    result = await client.top_backlinks(
+                        target=str(payload["target"]),
+                        mode=str(payload.get("mode", "domain")),
+                        limit=int(payload.get("limit", AHREFS_DEFAULT_ROWS)),
+                    )
+                case _:
+                    raise ValidationError(f"unsupported Ahrefs operation {request.operation!r}")
+        return ConnectorResult(
+            output_json=result.data if isinstance(result.data, dict) else {"data": result.data},
+            metadata_json={
+                "vendor": "ahrefs",
+                "operation": request.operation,
+                **(result.metadata or {}),
+            },
+            cost_cents=0,
+        )