aioghost 0.1.0__tar.gz

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

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

aioghost-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,39 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: |
+          ruff check src/ tests/
+
+      - name: Type check with mypy
+        run: |
+          mypy src/
+
+      - name: Run tests
+        run: |
+          pytest tests/ -v --tb=short

aioghost-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+venv/
+.venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# mypy
+.mypy_cache/
+
+# ruff
+.ruff_cache/

aioghost-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vitrixbot
+
+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.

aioghost-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: aioghost
+Version: 0.1.0
+Summary: Async Python client for the Ghost Admin API
+Project-URL: Homepage, https://github.com/vitrixbot/aioghost
+Project-URL: Documentation, https://github.com/vitrixbot/aioghost#readme
+Project-URL: Repository, https://github.com/vitrixbot/aioghost
+Project-URL: Issues, https://github.com/vitrixbot/aioghost/issues
+Author-email: vitrixbot <vitrixclawd@icloud.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aiohttp,api,async,asyncio,cms,ghost
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: pyjwt>=2.0.0
+Provides-Extra: dev
+Requires-Dist: aioresponses>=0.7.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-aiohttp>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aioghost
+
+Async Python client for the [Ghost Admin API](https://ghost.org/docs/admin-api/).
+
+## Installation
+
+```bash
+pip install aioghost
+```
+
+## Quick Start
+
+```python
+import asyncio
+from aioghost import GhostAdminAPI
+
+async def main():
+    async with GhostAdminAPI(
+        site_url="https://your-site.ghost.io",
+        admin_api_key="your-admin-api-key"
+    ) as api:
+        # Get site info
+        site = await api.get_site()
+        print(f"Site: {site['title']}")
+
+        # Get member counts
+        members = await api.get_members_count()
+        print(f"Total members: {members['total']}")
+        print(f"Paid members: {members['paid']}")
+
+        # Get MRR
+        mrr = await api.get_mrr()
+        print(f"MRR: ${mrr.get('usd', 0) / 100:.2f}")
+
+asyncio.run(main())
+```
+
+## Features
+
+- **Fully async** — Built on `aiohttp` for non-blocking I/O
+- **Type hints** — Full type annotations for IDE support
+- **Context manager** — Automatic session cleanup with `async with`
+- **Parallel requests** — Uses `asyncio.gather()` for efficient batching
+- **Proper exceptions** — Typed exceptions for different error cases
+
+## API Coverage
+
+| Endpoint | Method |
+|----------|--------|
+| Site info | `get_site()` |
+| Posts count | `get_posts_count()` |
+| Latest post | `get_latest_post()` |
+| Members count | `get_members_count()` |
+| MRR | `get_mrr()` |
+| Newsletters | `get_newsletters()` |
+| Latest email | `get_latest_email()` |
+| Comments count | `get_comments_count()` |
+| Tiers | `get_tiers()` |
+| ActivityPub stats | `get_activitypub_stats()` |
+| Webhooks | `create_webhook()`, `delete_webhook()` |
+| Validate credentials | `validate_credentials()` |
+
+## Getting Your Admin API Key
+
+1. Log in to your Ghost Admin panel
+2. Go to **Settings → Integrations**
+3. Click **Add custom integration**
+4. Copy the **Admin API Key** (format: `id:secret`)
+
+## Exceptions
+
+```python
+from aioghost import (
+    GhostError,           # Base exception
+    GhostAuthError,       # Invalid API key
+    GhostConnectionError, # Network error
+    GhostNotFoundError,   # 404 response
+    GhostValidationError, # Invalid request
+)
+```
+
+## Passing Your Own Session
+
+If you want to reuse an existing `aiohttp.ClientSession`:
+
+```python
+import aiohttp
+from aioghost import GhostAdminAPI
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        api = GhostAdminAPI(
+            site_url="https://your-site.ghost.io",
+            admin_api_key="your-key",
+            session=session,
+        )
+        site = await api.get_site()
+        # Session is NOT closed when api goes out of scope
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

aioghost-0.1.0/README.md

@@ -0,0 +1,103 @@
+# aioghost
+
+Async Python client for the [Ghost Admin API](https://ghost.org/docs/admin-api/).
+
+## Installation
+
+```bash
+pip install aioghost
+```
+
+## Quick Start
+
+```python
+import asyncio
+from aioghost import GhostAdminAPI
+
+async def main():
+    async with GhostAdminAPI(
+        site_url="https://your-site.ghost.io",
+        admin_api_key="your-admin-api-key"
+    ) as api:
+        # Get site info
+        site = await api.get_site()
+        print(f"Site: {site['title']}")
+
+        # Get member counts
+        members = await api.get_members_count()
+        print(f"Total members: {members['total']}")
+        print(f"Paid members: {members['paid']}")
+
+        # Get MRR
+        mrr = await api.get_mrr()
+        print(f"MRR: ${mrr.get('usd', 0) / 100:.2f}")
+
+asyncio.run(main())
+```
+
+## Features
+
+- **Fully async** — Built on `aiohttp` for non-blocking I/O
+- **Type hints** — Full type annotations for IDE support
+- **Context manager** — Automatic session cleanup with `async with`
+- **Parallel requests** — Uses `asyncio.gather()` for efficient batching
+- **Proper exceptions** — Typed exceptions for different error cases
+
+## API Coverage
+
+| Endpoint | Method |
+|----------|--------|
+| Site info | `get_site()` |
+| Posts count | `get_posts_count()` |
+| Latest post | `get_latest_post()` |
+| Members count | `get_members_count()` |
+| MRR | `get_mrr()` |
+| Newsletters | `get_newsletters()` |
+| Latest email | `get_latest_email()` |
+| Comments count | `get_comments_count()` |
+| Tiers | `get_tiers()` |
+| ActivityPub stats | `get_activitypub_stats()` |
+| Webhooks | `create_webhook()`, `delete_webhook()` |
+| Validate credentials | `validate_credentials()` |
+
+## Getting Your Admin API Key
+
+1. Log in to your Ghost Admin panel
+2. Go to **Settings → Integrations**
+3. Click **Add custom integration**
+4. Copy the **Admin API Key** (format: `id:secret`)
+
+## Exceptions
+
+```python
+from aioghost import (
+    GhostError,           # Base exception
+    GhostAuthError,       # Invalid API key
+    GhostConnectionError, # Network error
+    GhostNotFoundError,   # 404 response
+    GhostValidationError, # Invalid request
+)
+```
+
+## Passing Your Own Session
+
+If you want to reuse an existing `aiohttp.ClientSession`:
+
+```python
+import aiohttp
+from aioghost import GhostAdminAPI
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        api = GhostAdminAPI(
+            site_url="https://your-site.ghost.io",
+            admin_api_key="your-key",
+            session=session,
+        )
+        site = await api.get_site()
+        # Session is NOT closed when api goes out of scope
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

aioghost-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aioghost"
+version = "0.1.0"
+description = "Async Python client for the Ghost Admin API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "vitrixbot", email = "vitrixclawd@icloud.com" }
+]
+keywords = ["ghost", "cms", "api", "async", "asyncio", "aiohttp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Framework :: AsyncIO",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "aiohttp>=3.8.0",
+    "PyJWT>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-aiohttp>=1.0.0",
+    "aioresponses>=0.7.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/vitrixbot/aioghost"
+Documentation = "https://github.com/vitrixbot/aioghost#readme"
+Repository = "https://github.com/vitrixbot/aioghost"
+Issues = "https://github.com/vitrixbot/aioghost/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aioghost"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "C4", "W"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

aioghost-0.1.0/src/aioghost/__init__.py

@@ -0,0 +1,20 @@
+"""Async Python client for the Ghost Admin API."""
+
+from .client import GhostAdminAPI
+from .exceptions import (
+    GhostAuthError,
+    GhostConnectionError,
+    GhostError,
+    GhostNotFoundError,
+    GhostValidationError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "GhostAdminAPI",
+    "GhostError",
+    "GhostAuthError",
+    "GhostConnectionError",
+    "GhostNotFoundError",
+    "GhostValidationError",
+]

aioghost-0.1.0/src/aioghost/client.py

@@ -0,0 +1,434 @@
+"""Ghost Admin API client."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from datetime import UTC, datetime, timedelta
+from typing import Any, cast
+
+import aiohttp
+import jwt
+
+from .exceptions import (
+    GhostAuthError,
+    GhostConnectionError,
+    GhostError,
+    GhostNotFoundError,
+    GhostValidationError,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+JWT_EXPIRY_MINUTES = 5
+
+
+class GhostAdminAPI:
+    """Async client for the Ghost Admin API."""
+
+    def __init__(
+        self,
+        site_url: str,
+        admin_api_key: str,
+        session: aiohttp.ClientSession | None = None,
+    ) -> None:
+        """Initialize the API client.
+
+        Args:
+            site_url: The Ghost site URL (e.g., https://example.ghost.io)
+            admin_api_key: The Admin API key (format: id:secret)
+            session: Optional aiohttp session. If not provided, one will be created.
+        """
+        self.site_url = site_url.rstrip("/")
+        self.admin_api_key = admin_api_key
+        self._session = session
+        self._owns_session = session is None
+
+    def _generate_token(self) -> str:
+        """Generate a JWT token for Ghost Admin API authentication."""
+        try:
+            key_id, secret = self.admin_api_key.split(":")
+        except ValueError as err:
+            raise GhostAuthError("Invalid API key format. Expected 'id:secret'") from err
+
+        try:
+            secret_bytes = bytes.fromhex(secret)
+        except ValueError as err:
+            raise GhostAuthError("Invalid API key secret. Expected hex string.") from err
+
+        now = datetime.now(UTC)
+        payload = {
+            "iat": int(now.timestamp()),
+            "exp": int((now + timedelta(minutes=JWT_EXPIRY_MINUTES)).timestamp()),
+            "aud": "/admin/",
+        }
+
+        headers = {
+            "alg": "HS256",
+            "kid": key_id,
+            "typ": "JWT",
+        }
+
+        return jwt.encode(payload, secret_bytes, algorithm="HS256", headers=headers)
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        """Get or create aiohttp session."""
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+            self._owns_session = True
+        return self._session
+
+    async def close(self) -> None:
+        """Close the session if we own it."""
+        if self._owns_session and self._session and not self._session.closed:
+            await self._session.close()
+
+    async def __aenter__(self) -> GhostAdminAPI:
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        """Async context manager exit."""
+        await self.close()
+
+    def _get_auth_headers(self) -> dict[str, str]:
+        """Get authorization headers for Ghost Admin API."""
+        return {
+            "Authorization": f"Ghost {self._generate_token()}",
+            "Accept-Version": "v5.0",
+        }
+
+    async def _request(
+        self,
+        method: str,
+        endpoint: str,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Make an authenticated request to the Ghost Admin API.
+
+        Args:
+            method: HTTP method (GET, POST, DELETE, etc.)
+            endpoint: API endpoint (e.g., /ghost/api/admin/posts/)
+            params: Query parameters
+            json: JSON body for POST/PUT requests
+
+        Returns:
+            JSON response as a dictionary
+
+        Raises:
+            GhostAuthError: If authentication fails
+            GhostNotFoundError: If the resource is not found
+            GhostValidationError: If the request is invalid
+            GhostConnectionError: If the connection fails
+            GhostError: For other API errors
+        """
+        session = await self._get_session()
+        url = f"{self.site_url}{endpoint}"
+        headers = self._get_auth_headers()
+
+        if json:
+            headers["Content-Type"] = "application/json"
+
+        try:
+            async with session.request(
+                method, url, headers=headers, params=params, json=json
+            ) as response:
+                if response.status == 401:
+                    raise GhostAuthError("Authentication failed. Check your API key.")
+                if response.status == 404:
+                    raise GhostNotFoundError(f"Resource not found: {endpoint}")
+                if response.status == 422:
+                    data = await response.json()
+                    errors = data.get("errors", [{}])
+                    message = errors[0].get("message", "Validation failed")
+                    raise GhostValidationError(message)
+                if response.status >= 400:
+                    text = await response.text()
+                    raise GhostError(f"API error {response.status}: {text}")
+
+                result: dict[str, Any] = await response.json()
+                return result
+
+        except aiohttp.ClientError as err:
+            raise GhostConnectionError(f"Connection failed: {err}") from err
+
+    async def _get(
+        self, endpoint: str, params: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Make a GET request."""
+        return await self._request("GET", endpoint, params=params)
+
+    async def _post(
+        self, endpoint: str, json: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Make a POST request."""
+        return await self._request("POST", endpoint, json=json)
+
+    async def _delete(self, endpoint: str) -> dict[str, Any]:
+        """Make a DELETE request."""
+        return await self._request("DELETE", endpoint)
+
+    # -------------------------------------------------------------------------
+    # Site
+    # -------------------------------------------------------------------------
+
+    async def get_site(self) -> dict[str, Any]:
+        """Get site information.
+
+        Returns:
+            Site info dict with title, description, url, etc.
+        """
+        data = await self._get("/ghost/api/admin/site/")
+        return cast(dict[str, Any], data.get("site", {}))
+
+    # -------------------------------------------------------------------------
+    # Posts
+    # -------------------------------------------------------------------------
+
+    async def get_posts_count(self) -> dict[str, int]:
+        """Get post counts by status.
+
+        Returns:
+            Dict with 'published', 'drafts', 'scheduled' counts.
+        """
+        published, drafts, scheduled = await asyncio.gather(
+            self._get("/ghost/api/admin/posts/", {"limit": 1, "filter": "status:published"}),
+            self._get("/ghost/api/admin/posts/", {"limit": 1, "filter": "status:draft"}),
+            self._get("/ghost/api/admin/posts/", {"limit": 1, "filter": "status:scheduled"}),
+        )
+
+        return {
+            "published": int(published.get("meta", {}).get("pagination", {}).get("total", 0)),
+            "drafts": int(drafts.get("meta", {}).get("pagination", {}).get("total", 0)),
+            "scheduled": int(scheduled.get("meta", {}).get("pagination", {}).get("total", 0)),
+        }
+
+    async def get_latest_post(self) -> dict[str, Any] | None:
+        """Get the most recently published post.
+
+        Returns:
+            Post dict or None if no posts exist.
+        """
+        data = await self._get(
+            "/ghost/api/admin/posts/",
+            {"limit": 1, "order": "published_at desc", "filter": "status:published"},
+        )
+        posts = data.get("posts", [])
+        return posts[0] if posts else None
+
+    # -------------------------------------------------------------------------
+    # Members
+    # -------------------------------------------------------------------------
+
+    async def get_members_count(self) -> dict[str, int]:
+        """Get member counts from stats endpoint.
+
+        Returns:
+            Dict with 'total', 'paid', 'free', 'comped' counts.
+        """
+        data = await self._get("/ghost/api/admin/members/stats/count/")
+
+        total = data.get("total", 0)
+        history = data.get("data", [])
+
+        if history:
+            latest = history[-1]
+            return {
+                "total": total,
+                "paid": latest.get("paid", 0),
+                "free": latest.get("free", 0),
+                "comped": latest.get("comped", 0),
+            }
+
+        return {"total": total, "paid": 0, "free": 0, "comped": 0}
+
+    async def get_mrr(self) -> dict[str, int]:
+        """Get MRR (Monthly Recurring Revenue) data.
+
+        Returns:
+            Dict with currency keys and MRR values in cents.
+            E.g., {"usd": 12284, "eur": 5000}
+        """
+        data = await self._get("/ghost/api/admin/members/stats/mrr/")
+
+        result: dict[str, int] = {}
+        for currency_data in data.get("data", []):
+            currency = currency_data.get("currency", "usd")
+            values = currency_data.get("data", [])
+            if values:
+                latest = values[-1]
+                result[currency] = latest.get("value", 0)
+
+        return result
+
+    # -------------------------------------------------------------------------
+    # Newsletters
+    # -------------------------------------------------------------------------
+
+    async def get_newsletters(self) -> list[dict[str, Any]]:
+        """Get newsletters with subscriber counts.
+
+        Returns:
+            List of newsletter dicts.
+        """
+        data = await self._get(
+            "/ghost/api/admin/newsletters/",
+            {"include": "count.members"},
+        )
+        return cast(list[dict[str, Any]], data.get("newsletters", []))
+
+    # -------------------------------------------------------------------------
+    # Email / Latest Email
+    # -------------------------------------------------------------------------
+
+    def _build_email_stats(self, post: dict[str, Any]) -> dict[str, Any]:
+        """Build email stats dict from post with email data."""
+        email = post["email"]
+        email_count = email.get("email_count", 0)
+        opened_count = email.get("opened_count", 0)
+        count_data = post.get("count", {})
+        clicked_count = count_data.get("clicks", 0) or 0
+
+        return {
+            "title": post.get("title"),
+            "slug": post.get("slug"),
+            "published_at": post.get("published_at"),
+            "email_count": email_count,
+            "delivered_count": email.get("delivered_count", 0),
+            "opened_count": opened_count,
+            "clicked_count": clicked_count,
+            "failed_count": email.get("failed_count", 0),
+            "open_rate": round(opened_count / email_count * 100) if email_count > 0 else 0,
+            "click_rate": round(clicked_count / email_count * 100) if email_count > 0 else 0,
+            "subject": email.get("subject"),
+            "submitted_at": email.get("submitted_at"),
+        }
+
+    async def get_latest_email(self) -> dict[str, Any] | None:
+        """Get the most recently sent email newsletter.
+
+        Returns:
+            Email stats dict or None if no emails have been sent.
+        """
+        data = await self._get(
+            "/ghost/api/admin/posts/",
+            {
+                "limit": 10,
+                "order": "published_at desc",
+                "filter": "status:published",
+                "include": "email,count.clicks",
+            },
+        )
+
+        for post in data.get("posts", []):
+            if post.get("email"):
+                return self._build_email_stats(post)
+
+        return None
+
+    # -------------------------------------------------------------------------
+    # Comments
+    # -------------------------------------------------------------------------
+
+    async def get_comments_count(self) -> int:
+        """Get total comments count.
+
+        Returns:
+            Total number of comments.
+        """
+        data = await self._get("/ghost/api/admin/comments/", {"limit": 1})
+        return int(data.get("meta", {}).get("pagination", {}).get("total", 0))
+
+    # -------------------------------------------------------------------------
+    # Tiers
+    # -------------------------------------------------------------------------
+
+    async def get_tiers(self) -> list[dict[str, Any]]:
+        """Get subscription tiers.
+
+        Returns:
+            List of tier dicts.
+        """
+        data = await self._get("/ghost/api/admin/tiers/")
+        return cast(list[dict[str, Any]], data.get("tiers", []))
+
+    # -------------------------------------------------------------------------
+    # ActivityPub / Social Web
+    # -------------------------------------------------------------------------
+
+    async def get_activitypub_stats(self) -> dict[str, int]:
+        """Get ActivityPub follower/following counts (public endpoints).
+
+        Returns:
+            Dict with 'followers' and 'following' counts.
+        """
+        session = await self._get_session()
+        headers = {"Accept": "application/activity+json"}
+
+        stats = {"followers": 0, "following": 0}
+
+        async def fetch_count(endpoint: str, key: str) -> None:
+            try:
+                url = f"{self.site_url}/.ghost/activitypub/{endpoint}/index"
+                async with session.get(url, headers=headers) as response:
+                    if response.ok:
+                        data = await response.json()
+                        stats[key] = data.get("totalItems", 0)
+            except Exception as err:
+                _LOGGER.debug("ActivityPub %s not available: %s", endpoint, err)
+
+        await asyncio.gather(
+            fetch_count("followers", "followers"),
+            fetch_count("following", "following"),
+        )
+
+        return stats
+
+    # -------------------------------------------------------------------------
+    # Webhooks
+    # -------------------------------------------------------------------------
+
+    async def create_webhook(self, event: str, target_url: str) -> dict[str, Any]:
+        """Create a webhook in Ghost.
+
+        Ghost automatically associates the webhook with the integration
+        that owns the API key being used.
+
+        Args:
+            event: Event type (e.g., 'member.added', 'post.published')
+            target_url: URL to POST webhook payloads to
+
+        Returns:
+            Created webhook dict.
+        """
+        data = await self._post(
+            "/ghost/api/admin/webhooks/",
+            {"webhooks": [{"event": event, "target_url": target_url}]},
+        )
+        webhooks = cast(list[dict[str, Any]], data.get("webhooks", [{}]))
+        return webhooks[0]
+
+    async def delete_webhook(self, webhook_id: str) -> None:
+        """Delete a webhook from Ghost.
+
+        Args:
+            webhook_id: The webhook ID to delete.
+        """
+        await self._delete(f"/ghost/api/admin/webhooks/{webhook_id}/")
+
+    # -------------------------------------------------------------------------
+    # Validation
+    # -------------------------------------------------------------------------
+
+    async def validate_credentials(self) -> bool:
+        """Validate the API credentials.
+
+        Returns:
+            True if credentials are valid, False otherwise.
+        """
+        try:
+            await self.get_site()
+            return True
+        except GhostError:
+            return False

aioghost-0.1.0/src/aioghost/exceptions.py

@@ -0,0 +1,21 @@
+"""Exceptions for the Ghost Admin API client."""
+
+
+class GhostError(Exception):
+    """Base exception for Ghost API errors."""
+
+
+class GhostAuthError(GhostError):
+    """Authentication failed (invalid API key or expired token)."""
+
+
+class GhostConnectionError(GhostError):
+    """Failed to connect to the Ghost API."""
+
+
+class GhostNotFoundError(GhostError):
+    """Requested resource was not found."""
+
+
+class GhostValidationError(GhostError):
+    """Request validation failed."""

aioghost-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for aioghost."""

aioghost-0.1.0/tests/test_client.py

@@ -0,0 +1,106 @@
+"""Tests for the Ghost Admin API client."""
+
+import pytest
+from aioresponses import aioresponses
+
+from aioghost import GhostAdminAPI, GhostAuthError
+
+
+@pytest.fixture
+def api():
+    """Create a test API client."""
+    return GhostAdminAPI(
+        site_url="https://test.ghost.io",
+        admin_api_key="650b7a9f8e8c1234567890ab:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
+    )
+
+
+@pytest.mark.asyncio
+async def test_get_site(api: GhostAdminAPI):
+    """Test getting site info."""
+    with aioresponses() as m:
+        m.get(
+            "https://test.ghost.io/ghost/api/admin/site/",
+            payload={"site": {"title": "Test Site", "url": "https://test.ghost.io"}},
+        )
+
+        async with api:
+            site = await api.get_site()
+
+        assert site["title"] == "Test Site"
+        assert site["url"] == "https://test.ghost.io"
+
+
+@pytest.mark.asyncio
+async def test_get_members_count(api: GhostAdminAPI):
+    """Test getting member counts."""
+    with aioresponses() as m:
+        m.get(
+            "https://test.ghost.io/ghost/api/admin/members/stats/count/",
+            payload={
+                "total": 100,
+                "data": [{"paid": 10, "free": 85, "comped": 5}],
+            },
+        )
+
+        async with api:
+            members = await api.get_members_count()
+
+        assert members["total"] == 100
+        assert members["paid"] == 10
+        assert members["free"] == 85
+        assert members["comped"] == 5
+
+
+@pytest.mark.asyncio
+async def test_invalid_api_key_format():
+    """Test that invalid API key format raises error."""
+    api = GhostAdminAPI(
+        site_url="https://test.ghost.io",
+        admin_api_key="invalid-key-no-colon",
+    )
+
+    with pytest.raises(GhostAuthError, match="Invalid API key format"):
+        api._generate_token()
+
+
+@pytest.mark.asyncio
+async def test_invalid_api_key_secret():
+    """Test that invalid API key secret raises error."""
+    api = GhostAdminAPI(
+        site_url="https://test.ghost.io",
+        admin_api_key="validid:not-hex-string",
+    )
+
+    with pytest.raises(GhostAuthError, match="Invalid API key secret"):
+        api._generate_token()
+
+
+@pytest.mark.asyncio
+async def test_validate_credentials_success(api: GhostAdminAPI):
+    """Test credential validation success."""
+    with aioresponses() as m:
+        m.get(
+            "https://test.ghost.io/ghost/api/admin/site/",
+            payload={"site": {"title": "Test"}},
+        )
+
+        async with api:
+            valid = await api.validate_credentials()
+
+        assert valid is True
+
+
+@pytest.mark.asyncio
+async def test_validate_credentials_failure(api: GhostAdminAPI):
+    """Test credential validation failure."""
+    with aioresponses() as m:
+        m.get(
+            "https://test.ghost.io/ghost/api/admin/site/",
+            status=401,
+        )
+
+        async with api:
+            valid = await api.validate_credentials()
+
+        assert valid is False