stackos-connectors 0.1.0__py3-none-any.whl

stackos_connectors/connectors/ahrefs/catalog.json

@@ -0,0 +1,186 @@
+{
+  "schema_version": "stackos.connector.v1",
+  "connector": "ahrefs",
+  "name": "Ahrefs",
+  "description": "Organic keyword and backlink research provider; requires eligible API access and API units.",
+  "auth_methods": [
+    {
+      "key": "api_key",
+      "description": "Supply the Ahrefs API key for bearer authentication.",
+      "fields_schema": {
+        "type": "object",
+        "properties": {
+          "api_key": {
+            "description": "API Key",
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "api_key"
+        ]
+      },
+      "config_schema": {
+        "type": "object",
+        "properties": {},
+        "required": []
+      },
+      "payload_format": "raw",
+      "payload_field": "api_key",
+      "setup": {
+        "label": "API key",
+        "description": "Ahrefs API v3 calls consume API units and require eligible Direct API access. Obtain an API key in the Ahrefs app. The limits_and_usage action reads subscription information, including plan and key limits and remaining units.",
+        "fields": [
+          {
+            "description": null,
+            "key": "api_key",
+            "label": "API Key",
+            "options": null,
+            "placeholder": null,
+            "required": true,
+            "secret": true,
+            "type": "secret"
+          }
+        ]
+      }
+    }
+  ],
+  "actions": [
+    {
+      "key": "competitor.keywords",
+      "operation": "competitor.keywords",
+      "input_schema": {
+        "additionalProperties": false,
+        "properties": {
+          "country": {
+            "type": "string"
+          },
+          "date": {
+            "type": "string"
+          },
+          "limit": {
+            "description": "Positive number of rows requested from Ahrefs. Defaults to 100; provider plan restrictions are returned by Ahrefs.",
+            "minimum": 1,
+            "type": "integer"
+          },
+          "target": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "target"
+        ],
+        "type": "object"
+      },
+      "output_schema": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "auth_methods": [
+        "api_key"
+      ],
+      "auth_optional": false,
+      "config": {},
+      "description": "Fetch organic keywords for a target. Returns provider data and API-unit response headers. Does not make an implicit limits request.",
+      "metadata": {
+        "capability": "seo-research",
+        "name": "Competitor Keywords",
+        "risk_level": "cost"
+      }
+    },
+    {
+      "key": "backlink.research",
+      "operation": "backlink.research",
+      "input_schema": {
+        "additionalProperties": false,
+        "properties": {
+          "limit": {
+            "description": "Positive number of rows requested from Ahrefs. Defaults to 100; provider plan restrictions are returned by Ahrefs.",
+            "minimum": 1,
+            "type": "integer"
+          },
+          "mode": {
+            "enum": [
+              "exact",
+              "prefix",
+              "domain",
+              "subdomains"
+            ],
+            "type": "string"
+          },
+          "target": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "target"
+        ],
+        "type": "object"
+      },
+      "output_schema": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "auth_methods": [
+        "api_key"
+      ],
+      "auth_optional": false,
+      "config": {},
+      "description": "Fetch backlinks for a target. Returns provider data and API-unit response headers. Does not make an implicit limits request.",
+      "metadata": {
+        "capability": "seo-research",
+        "name": "Backlink Research",
+        "risk_level": "cost"
+      }
+    },
+    {
+      "key": "limits_and_usage",
+      "operation": "limits_and_usage",
+      "input_schema": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      },
+      "output_schema": {
+        "type": "object",
+        "additionalProperties": true
+      },
+      "auth_methods": [
+        "api_key"
+      ],
+      "config": {},
+      "description": "Fetch subscription limits and usage with GET /v3/subscription-info/limits-and-usage. Returns provider facts without enforcing caller admission policy.",
+      "metadata": {
+        "name": "Limits and usage",
+        "risk_level": "read"
+      }
+    }
+  ],
+  "setup": {
+    "billing_url": "https://app.ahrefs.com/account/subscription",
+    "console_url": "https://app.ahrefs.com/",
+    "credential_label": "Ahrefs API key",
+    "credential_url": "https://app.ahrefs.com/api",
+    "docs_url": "https://docs.ahrefs.com/",
+    "fallback_reason": "API access is plan/account gated; official API docs and Ahrefs app are the nearest setup path.",
+    "fallback_url": "https://docs.ahrefs.com/",
+    "homepage_url": "https://ahrefs.com/",
+    "setup_note": "Ahrefs API v3 calls consume API units and require eligible Direct API access. Obtain an API key in the Ahrefs app. The limits_and_usage action reads subscription information, including plan and key limits and remaining units.",
+    "signup_url": "https://app.ahrefs.com/user/sign-up",
+    "docs": [
+      "https://docs.ahrefs.com/en/api/docs/introduction",
+      "https://docs.ahrefs.com/en/api/docs/api-keys-creation-and-management",
+      "https://docs.ahrefs.com/en/api/docs/limits-consumption",
+      "https://docs.ahrefs.com/en/api/reference/subscription-info/get-limits-and-usage",
+      "https://docs.ahrefs.com/en/api/reference/site-explorer",
+      "https://docs.ahrefs.com/en/api/reference/site-explorer/get-organic-keywords",
+      "https://docs.ahrefs.com/en/api/reference/site-explorer/get-all-backlinks"
+    ]
+  },
+  "implementation": "stackos_connectors.connectors.ahrefs.actions:AhrefsActionConnector",
+  "icon": {
+    "media_type": "image/png",
+    "kind": "icon",
+    "path": "connectors/ahrefs/assets/icon.png"
+  }
+}

stackos_connectors/connectors/ahrefs/integration.py

@@ -0,0 +1,184 @@
+"""Ahrefs integration wrapper (PLAN.md L1047).
+
+Authentication: Bearer ``Authorization: Bearer <api_key>``. Ahrefs only
+serves this wrapper when the operator has a paid plan/API units that
+allow direct API v3 calls; for solo/SMB operators DataForSEO covers most
+of the same surface area.
+
+Operations:
+
+- ``keywords_for_site(target, country)`` — keyword inventory.
+- ``top_backlinks(target, mode, limit)`` — top inbound links.
+
+Graceful degrade: if no credential payload is present,
+``test_credentials`` raises ``IntegrationDownError`` with a documented
+fallback hint. Wrapper construction itself does NOT raise — the skill code
+checks ``test_credentials`` before issuing the first real op.
+"""
+
+from __future__ import annotations
+
+from datetime import date, timedelta
+from typing import Any
+
+from stackos_connectors.errors import IntegrationDownError
+from stackos_connectors.shared.base import BaseIntegration, IntegrationCallResult
+
+_AHREFS_UNIT_HEADERS = {
+    "x-api-rows": "rows",
+    "x-api-units-cost-row": "cost_row",
+    "x-api-units-cost-total": "cost_total",
+    "x-api-units-cost-total-actual": "cost_total_actual",
+}
+
+
+class AhrefsIntegration(BaseIntegration):
+    """Wrapper for ``https://api.ahrefs.com/v3``."""
+
+    kind = "ahrefs"
+    vendor = "ahrefs"
+    # Official refs: https://docs.ahrefs.com/en/api/docs/introduction and
+    # https://docs.ahrefs.com/en/api/docs/limits-consumption. Ahrefs bills in
+    # API units; unit headers are metadata until StackOS models unit budgets.
+    default_qps = 1.0
+
+    BASE_URL = "https://api.ahrefs.com/v3"
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._api_key = self.payload.decode("utf-8").strip() if self.payload else ""
+
+    def _require_key(self) -> str:
+        if not self._api_key:
+            raise IntegrationDownError(
+                "Ahrefs API key is not configured.",
+                data={
+                    "vendor": "ahrefs",
+                    "hint": "Pass a non-empty API key using the api_key authentication method.",
+                },
+            )
+        return self._api_key
+
+    def _auth_headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._require_key()}",
+            "Accept": "application/json",
+        }
+
+    @staticmethod
+    def _default_report_date() -> str:
+        """Use yesterday: Ahrefs reports are date-bound and may lag today."""
+        return (date.today() - timedelta(days=1)).isoformat()
+
+    @staticmethod
+    def _parse_int(value: str | None) -> int | None:
+        if value is None:
+            return None
+        try:
+            return int(value)
+        except ValueError:
+            return None
+
+    def _extract_response_metadata(
+        self,
+        op: str,
+        *,
+        request: Any,
+        response: Any,
+        http_response: Any,
+    ) -> dict[str, Any] | None:
+        """Capture Ahrefs unit-accounting headers documented for API v3."""
+        del op, request, response
+        api_units: dict[str, Any] = {}
+        for header, key in _AHREFS_UNIT_HEADERS.items():
+            parsed = self._parse_int(http_response.headers.get(header))
+            if parsed is not None:
+                api_units[key] = parsed
+        cache_header = http_response.headers.get("x-api-cache")
+        if cache_header:
+            api_units["cache"] = cache_header
+        if not api_units:
+            return None
+        metadata: dict[str, Any] = {"api_units": api_units}
+        if isinstance(cache_header, str) and cache_header.lower() == "hit":
+            metadata["cached"] = True
+        return metadata
+
+    async def limits_and_usage(self) -> IntegrationCallResult:
+        """Read the free subscription/usage endpoint before paid row calls."""
+        return await self.call(
+            op="limits_and_usage",
+            method="GET",
+            url=f"{self.BASE_URL}/subscription-info/limits-and-usage",
+            headers=self._auth_headers(),
+        )
+
+    async def keywords_for_site(
+        self,
+        *,
+        target: str,
+        country: str = "us",
+        limit: int = 100,
+        date_: str | None = None,
+    ) -> IntegrationCallResult:
+        """Keyword inventory for the target domain."""
+        # Endpoint ref:
+        # https://docs.ahrefs.com/en/api/reference/site-explorer/get-organic-keywords
+        params = {
+            "target": target,
+            "country": country,
+            "limit": str(limit),
+            "date": date_ or self._default_report_date(),
+            "select": "keyword,volume,cpc,best_position,keyword_difficulty",
+        }
+        return await self.call(
+            op="keywords_for_site",
+            method="GET",
+            url=f"{self.BASE_URL}/site-explorer/organic-keywords",
+            params=params,
+            headers=self._auth_headers(),
+        )
+
+    async def top_backlinks(
+        self,
+        *,
+        target: str,
+        mode: str = "domain",
+        limit: int = 100,
+    ) -> IntegrationCallResult:
+        """Top inbound backlinks; ``mode`` is ``domain`` or ``exact``."""
+        # Endpoint ref:
+        # https://docs.ahrefs.com/en/api/reference/site-explorer/get-all-backlinks
+        params = {
+            "target": target,
+            "mode": mode,
+            "limit": str(limit),
+            "select": "url_from,url_to,domain_rating_source,first_seen",
+        }
+        return await self.call(
+            op="top_backlinks",
+            method="GET",
+            url=f"{self.BASE_URL}/site-explorer/all-backlinks",
+            params=params,
+            headers=self._auth_headers(),
+        )
+
+    async def test_credentials(self) -> dict[str, Any]:
+        """Cheap auth probe — call a free ``domain-rating`` query.
+
+        Raises ``IntegrationDownError`` with the Ahrefs setup hint when no
+        key is configured (graceful degrade — the keyword-discovery skill
+        picks this up and falls back to DataForSEO).
+        """
+        self._require_key()
+        result = await self.call(
+            op="test",
+            method="GET",
+            url=f"{self.BASE_URL}/site-explorer/domain-rating",
+            params={"target": "wordcount.com", "date": self._default_report_date()},
+            headers=self._auth_headers(),
+        )
+        return {"ok": True, "vendor": "ahrefs", "data": result.data}
+
+
+__all__ = ["AhrefsIntegration"]

stackos_connectors/connectors/aignc/__init__.py

@@ -0,0 +1 @@
+"""AIGNC native protocol connector."""

stackos_connectors/connectors/aignc/actions.py

@@ -0,0 +1,82 @@
+"""Named AIGNC requests with caller-owned files and resolved bearer credentials."""
+
+from contextlib import nullcontext
+from pathlib import Path
+
+import httpx
+
+from stackos_connectors.connectors.aignc.integration import AigncIntegration
+from stackos_connectors.contracts import ConnectorRequest, ConnectorResult, ValidationIssue
+from stackos_connectors.shared.provider_utils import credential_value, issue
+
+
+class AigncActionConnector:
+    key = "aignc"
+
+    def validate(self, request: ConnectorRequest) -> list[ValidationIssue]:
+        issues = []
+        if request.operation == "image.generate" and request.options.output_dir is None:
+            issues.append(
+                issue("$.options.output_dir", "output_dir is required for generated media")
+            )
+        for name in ("max_response_bytes", "max_image_bytes", "max_audio_bytes"):
+            value = request.options.provider_context.get(name)
+            if value is not None and (type(value) is not int or value <= 0):
+                issues.append(
+                    issue(
+                        f"$.options.provider_context.{name}", f"{name} must be a positive integer"
+                    )
+                )
+        return issues
+
+    def estimate_cost_cents(self, _request: ConnectorRequest) -> int:
+        return 0
+
+    async def execute(self, request: ConnectorRequest) -> ConnectorResult:
+        data = request.input_json
+        async with (
+            nullcontext(request.options.http)
+            if request.options.http is not None
+            else httpx.AsyncClient()
+        ) as http:
+            client = AigncIntegration(
+                payload=credential_value(request, "api_key").encode(),
+                http=http,
+                timeout=request.options.timeout,
+                rate_limiter=request.options.rate_limiter,
+                output_dir=request.options.output_dir,
+                **{
+                    name: request.options.provider_context.get(name)
+                    for name in ("max_response_bytes", "max_image_bytes", "max_audio_bytes")
+                },
+            )
+            if request.operation == "models.list":
+                result = await client.models()
+            elif request.operation == "chat.complete":
+                result = await client.chat_complete(
+                    model=data["model"],
+                    messages=data["messages"],
+                    max_tokens=data["max_tokens"],
+                    google_search=data.get("google_search", False),
+                )
+            elif request.operation == "image.generate":
+                result = await client.generate_image(
+                    prompt=data["prompt"], max_tokens=data["max_tokens"]
+                )
+            elif request.operation == "audio.analyze":
+                result = await client.analyze_audio(
+                    model=data["model"],
+                    instruction=data["instruction"],
+                    audio_path=Path(data["audio_path"]),
+                    format=data["format"],
+                    max_tokens=data["max_tokens"],
+                )
+            else:
+                from stackos_connectors.errors import ValidationError
+
+                raise ValidationError("unsupported AIGNC operation")
+        return ConnectorResult(
+            output_json=result.data,
+            metadata_json={"vendor": "aignc", **(result.metadata or {})},
+            files=client.files,
+        )