stackos-connectors 0.1.0__tar.gz

stackos_connectors-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-publish
+  cancel-in-progress: false
+
+jobs:
+  build:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the selected commit
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+      - name: Install build tools
+        run: python -m pip install --upgrade build twine
+      - name: Build wheel and source distribution
+        run: python -m build
+      - name: Check distribution metadata
+        run: python -m twine check --strict dist/*
+      - name: Save distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/stackos-connectors/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download the built distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-distributions
+          path: dist/
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/

stackos_connectors-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/

stackos_connectors-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StackOS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stackos_connectors-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: stackos-connectors
+Version: 0.1.0
+Summary: Named provider connectors with plain data and caller-owned authentication.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: boto3<1.44,>=1.43.51
+Requires-Dist: botocore<1.44,>=1.43.51
+Requires-Dist: cryptography>=43
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsonschema>=4.23
+Requires-Dist: pydantic>=2.6
+Requires-Dist: s3transfer<0.20,>=0.19.1
+Description-Content-Type: text/markdown
+
+# StackOS Connectors
+
+A Python library of named provider connectors. A caller supplies a connector,
+action, input data and resolved authentication. The library maps that action to
+the provider protocol and returns provider output, metadata and file descriptors.
+
+The consumer owns credential storage and refresh, authorization, persistent state,
+workflow decisions and audit. Provider implementations use plain contracts and
+can accept caller-owned HTTP clients, rate buckets and native protocol sessions.
+
+Each integration is grouped under `src/stackos_connectors/connectors/`:
+
+```text
+connectors/<provider>/
+  actions.py       # named action mapping
+  integration.py   # provider protocol client, when separate
+  catalog.json     # descriptions, schemas, auth methods and fixed bindings
+  schemas/         # provider-specific schema resources, when needed
+  assets/          # fixed GraphQL documents and other provider resources
+  docs/            # provider reference Markdown
+shared/            # common transport, payload and protocol helpers
+shared/google/     # Google OAuth and batch protocol helpers
+catalog/           # common catalog schema and default resource index
+```
+
+Folder names use Python identifiers, such as `aws_s3`; public connector keys
+remain unchanged, such as `aws-s3`. Provider-only helper modules live beside
+their actions. The root package contains the public contracts and execution API.
+
+The default client loads the bundled connector catalogs. Use `list_connectors`
+and `describe` to discover the installed actions and their input/auth schemas.
+Generic HTTP accepts explicitly registered declarations; OpenRouter currently
+provides a credential probe without a text-generation action.
+
+```python
+from stackos_connectors import ConnectorAuth, get_default_client
+
+client = get_default_client()
+result = await client.execute(
+    connector="serper",
+    action="serper.search",
+    data={"query": "example search"},
+    auth=ConnectorAuth(method="api_key", fields={"api_key": resolved_api_key}),
+)
+```
+
+`describe` supplies provider and action names, descriptions, native input/output
+schemas, setup information and execution auth requirements. Auth method `setup`
+describes credential acquisition; `fields_schema` and `config_schema` define the
+resolved auth accepted for execution. `validate_data` checks input without resolving
+credentials. `validate`, `estimate_cost` and `execute` also check the selected auth
+method. Dynamic actions must be explicitly registered on a scoped client before
+execution; existing names cannot be replaced.
+
+`CallOptions.timeout=None` preserves each provider's default. A numeric timeout
+overrides that default. A supplied HTTP client remains caller-owned.
+
+For file-producing actions, pass `CallOptions(output_dir=Path(...))` and consume
+the plain descriptors in `result.files`. The library does not create application
+artifacts or public download URLs. Telegram actions require an already authorized
+session through `CallOptions(native_session=session)`; the caller owns account
+lifecycle, the TDLib binary, receipt persistence and session shutdown.
+
+For a restricted catalog, construct `ConnectorClient(registry=load_registry(...))`
+using `stackos_connectors.catalog.load_registry` and the provider-local resource
+paths above. Register custom HTTP or Trackbooth declarations on that scoped client
+before execution; request data cannot override a declaration's provider or route.
+
+`ConnectorResult.output_json` contains native response data for in-process use,
+including signed download URLs and pagination tokens. Exact resolved credential
+values are scrubbed from that data. The consumer must project or redact it before
+display, audit or persistent storage. Errors, progress, metadata and file
+descriptors receive full key and text redaction. Results hide response data in
+their default representation.
+
+Provider protocol notes and source links live in each connector's `docs/`
+directory. They cover authentication transport, requests, pagination, response
+meaning and error handling. Use the executable catalog and `describe` for the
+installed action contract.
+
+Existing integration icons are bundled at `connectors/<provider>/assets/icon.*`.
+Each catalog's `icon` object contains a package-relative `path`, `media_type` and
+`kind`. Actions inherit the integration icon unless an action declares its own.
+Kinds preserve the source presentation: `icon`, `wordmark`, `wordmark-dark` or
+`wordmark-inverse`. Missing logos use the neutral `fallback` at
+`shared/icons/integration.svg`. Standard package resources read the bytes without
+a source checkout:
+
+```python
+from importlib.resources import files
+
+description = client.describe("serper", "serper.search")
+icon = description["actions"][0]["icon"]
+icon_bytes = files("stackos_connectors").joinpath(*icon["path"].split("/")).read_bytes()
+```
+
+## Installation
+
+Python 3.12 or newer is required. Source:
+[flowmonkeyio/StackOSConnectors](https://github.com/flowmonkeyio/StackOSConnectors).
+
+Published releases can be installed with:
+
+```bash
+python -m pip install stackos-connectors==0.1.0
+```
+
+Or add `stackos-connectors==0.1.0` to your Python dependency requirements.
+
+Install from a local checkout with `pip install /path/to/StackOSConnectors`, or
+build a wheel with `python -m build --wheel` and install that wheel. Runtime use
+needs only the installed package and its declared dependencies.
+
+## Publishing
+
+The manual [publish workflow](.github/workflows/publish.yml) uses PyPI Trusted
+Publishing through GitHub OIDC. It does not store a PyPI API token. Pushing a
+commit does not publish a release.
+
+Before running it, configure the GitHub `pypi` environment and a PyPI GitHub
+trusted publisher with these exact values:
+
+| Field | Value |
+| --- | --- |
+| PyPI project name | `stackos-connectors` |
+| GitHub owner | `flowmonkeyio` |
+| Repository | `StackOSConnectors` |
+| Workflow filename | `publish.yml` |
+| Environment | `pypi` |
+
+Use a pending publisher for the first release. See the official
+[PyPI trusted publisher setup](https://docs.pypi.org/trusted-publishers/adding-a-publisher/).
+
+After configuration and release review, open **Actions → Publish to PyPI → Run
+workflow** and select `main`. The build job checks out the selected commit,
+builds the wheel and source distribution on Python 3.12, checks their metadata,
+and uploads them as one workflow artifact. The separate publish job downloads
+that artifact and requests the OIDC token inside the `pypi` environment.
+Runs selected on other branches do not build or publish. Only the publish job
+has `id-token: write` permission.
+
+The workflow does not rerun the connector test suite; run the tests and review
+the intended release commit before dispatch. A version already uploaded to
+PyPI cannot be replaced; change the package version for a later release.

stackos_connectors-0.1.0/README.md

@@ -0,0 +1,144 @@
+# StackOS Connectors
+
+A Python library of named provider connectors. A caller supplies a connector,
+action, input data and resolved authentication. The library maps that action to
+the provider protocol and returns provider output, metadata and file descriptors.
+
+The consumer owns credential storage and refresh, authorization, persistent state,
+workflow decisions and audit. Provider implementations use plain contracts and
+can accept caller-owned HTTP clients, rate buckets and native protocol sessions.
+
+Each integration is grouped under `src/stackos_connectors/connectors/`:
+
+```text
+connectors/<provider>/
+  actions.py       # named action mapping
+  integration.py   # provider protocol client, when separate
+  catalog.json     # descriptions, schemas, auth methods and fixed bindings
+  schemas/         # provider-specific schema resources, when needed
+  assets/          # fixed GraphQL documents and other provider resources
+  docs/            # provider reference Markdown
+shared/            # common transport, payload and protocol helpers
+shared/google/     # Google OAuth and batch protocol helpers
+catalog/           # common catalog schema and default resource index
+```
+
+Folder names use Python identifiers, such as `aws_s3`; public connector keys
+remain unchanged, such as `aws-s3`. Provider-only helper modules live beside
+their actions. The root package contains the public contracts and execution API.
+
+The default client loads the bundled connector catalogs. Use `list_connectors`
+and `describe` to discover the installed actions and their input/auth schemas.
+Generic HTTP accepts explicitly registered declarations; OpenRouter currently
+provides a credential probe without a text-generation action.
+
+```python
+from stackos_connectors import ConnectorAuth, get_default_client
+
+client = get_default_client()
+result = await client.execute(
+    connector="serper",
+    action="serper.search",
+    data={"query": "example search"},
+    auth=ConnectorAuth(method="api_key", fields={"api_key": resolved_api_key}),
+)
+```
+
+`describe` supplies provider and action names, descriptions, native input/output
+schemas, setup information and execution auth requirements. Auth method `setup`
+describes credential acquisition; `fields_schema` and `config_schema` define the
+resolved auth accepted for execution. `validate_data` checks input without resolving
+credentials. `validate`, `estimate_cost` and `execute` also check the selected auth
+method. Dynamic actions must be explicitly registered on a scoped client before
+execution; existing names cannot be replaced.
+
+`CallOptions.timeout=None` preserves each provider's default. A numeric timeout
+overrides that default. A supplied HTTP client remains caller-owned.
+
+For file-producing actions, pass `CallOptions(output_dir=Path(...))` and consume
+the plain descriptors in `result.files`. The library does not create application
+artifacts or public download URLs. Telegram actions require an already authorized
+session through `CallOptions(native_session=session)`; the caller owns account
+lifecycle, the TDLib binary, receipt persistence and session shutdown.
+
+For a restricted catalog, construct `ConnectorClient(registry=load_registry(...))`
+using `stackos_connectors.catalog.load_registry` and the provider-local resource
+paths above. Register custom HTTP or Trackbooth declarations on that scoped client
+before execution; request data cannot override a declaration's provider or route.
+
+`ConnectorResult.output_json` contains native response data for in-process use,
+including signed download URLs and pagination tokens. Exact resolved credential
+values are scrubbed from that data. The consumer must project or redact it before
+display, audit or persistent storage. Errors, progress, metadata and file
+descriptors receive full key and text redaction. Results hide response data in
+their default representation.
+
+Provider protocol notes and source links live in each connector's `docs/`
+directory. They cover authentication transport, requests, pagination, response
+meaning and error handling. Use the executable catalog and `describe` for the
+installed action contract.
+
+Existing integration icons are bundled at `connectors/<provider>/assets/icon.*`.
+Each catalog's `icon` object contains a package-relative `path`, `media_type` and
+`kind`. Actions inherit the integration icon unless an action declares its own.
+Kinds preserve the source presentation: `icon`, `wordmark`, `wordmark-dark` or
+`wordmark-inverse`. Missing logos use the neutral `fallback` at
+`shared/icons/integration.svg`. Standard package resources read the bytes without
+a source checkout:
+
+```python
+from importlib.resources import files
+
+description = client.describe("serper", "serper.search")
+icon = description["actions"][0]["icon"]
+icon_bytes = files("stackos_connectors").joinpath(*icon["path"].split("/")).read_bytes()
+```
+
+## Installation
+
+Python 3.12 or newer is required. Source:
+[flowmonkeyio/StackOSConnectors](https://github.com/flowmonkeyio/StackOSConnectors).
+
+Published releases can be installed with:
+
+```bash
+python -m pip install stackos-connectors==0.1.0
+```
+
+Or add `stackos-connectors==0.1.0` to your Python dependency requirements.
+
+Install from a local checkout with `pip install /path/to/StackOSConnectors`, or
+build a wheel with `python -m build --wheel` and install that wheel. Runtime use
+needs only the installed package and its declared dependencies.
+
+## Publishing
+
+The manual [publish workflow](.github/workflows/publish.yml) uses PyPI Trusted
+Publishing through GitHub OIDC. It does not store a PyPI API token. Pushing a
+commit does not publish a release.
+
+Before running it, configure the GitHub `pypi` environment and a PyPI GitHub
+trusted publisher with these exact values:
+
+| Field | Value |
+| --- | --- |
+| PyPI project name | `stackos-connectors` |
+| GitHub owner | `flowmonkeyio` |
+| Repository | `StackOSConnectors` |
+| Workflow filename | `publish.yml` |
+| Environment | `pypi` |
+
+Use a pending publisher for the first release. See the official
+[PyPI trusted publisher setup](https://docs.pypi.org/trusted-publishers/adding-a-publisher/).
+
+After configuration and release review, open **Actions → Publish to PyPI → Run
+workflow** and select `main`. The build job checks out the selected commit,
+builds the wheel and source distribution on Python 3.12, checks their metadata,
+and uploads them as one workflow artifact. The separate publish job downloads
+that artifact and requests the OIDC token inside the `pypi` environment.
+Runs selected on other branches do not build or publish. Only the publish job
+has `id-token: write` permission.
+
+The workflow does not rerun the connector test suite; run the tests and review
+the intended release commit before dispatch. A version already uploaded to
+PyPI cannot be replaced; change the package version for a later release.

stackos_connectors-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "stackos-connectors"
+version = "0.1.0"
+description = "Named provider connectors with plain data and caller-owned authentication."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+dependencies = [
+    "httpx>=0.27",
+    "jsonschema>=4.23",
+    "pydantic>=2.6",
+    "cryptography>=43",
+    "boto3>=1.43.51,<1.44",
+    "botocore>=1.43.51,<1.44",
+    "s3transfer>=0.19.1,<0.20",
+]
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "pytest-httpx>=0.34", "ruff>=0.8", "build>=1.2"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/stackos_connectors"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["B011"]

stackos_connectors-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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"
+}